feat: add validation utilities for common patterns

Author: Mearman

src/utils/validation.test.ts

@@ -0,0 +1,83 @@
+/**
+ * @fileoverview Unit tests for validation utilities and schemas
+ * @module utils/validation.test
+ */
+
+import { describe, expect, it } from 'vitest';
+import { dateSchema, timestampSchema, urlSchema, validateInput } from './validation.js';
+
+/**
+ * Test suite for validation schemas
+ */
+describe('validation schemas', () => {
+	/**
+	 * Tests for URL validation schema
+	 */
+	describe('urlSchema', () => {
+		it('should accept valid URLs', () => {
+			expect(urlSchema.parse('https://example.com')).toBe('https://example.com');
+			expect(urlSchema.parse('http://example.com/path')).toBe('http://example.com/path');
+		});
+
+		it('should reject invalid URLs', () => {
+			expect(() => urlSchema.parse('not a url')).toThrow();
+			expect(() => urlSchema.parse('example.com')).toThrow();
+		});
+	});
+
+	/**
+	 * Tests for date validation schema (YYYY-MM-DD format)
+	 */
+	describe('dateSchema', () => {
+		it('should accept valid dates', () => {
+			expect(dateSchema.parse('2024-01-01')).toBe('2024-01-01');
+			expect(dateSchema.parse('2024-12-31')).toBe('2024-12-31');
+		});
+
+		it('should reject invalid dates', () => {
+			expect(() => dateSchema.parse('2024-1-1')).toThrow();
+			expect(() => dateSchema.parse('01-01-2024')).toThrow();
+			expect(() => dateSchema.parse('2024/01/01')).toThrow();
+		});
+	});
+
+	/**
+	 * Tests for timestamp validation schema (YYYYMMDDHHmmss format)
+	 */
+	describe('timestampSchema', () => {
+		it('should accept valid timestamps', () => {
+			expect(timestampSchema.parse('20240101120000')).toBe('20240101120000');
+		});
+
+		it('should reject invalid timestamps', () => {
+			expect(() => timestampSchema.parse('2024-01-01')).toThrow();
+			expect(() => timestampSchema.parse('202401011200')).toThrow();
+		});
+	});
+});
+
+/**
+ * Test suite for the validateInput utility function
+ */
+describe('validateInput', () => {
+	it('should return parsed value for valid input', () => {
+		const result = validateInput(urlSchema, 'https://example.com');
+		expect(result).toBe('https://example.com');
+	});
+
+	it('should throw formatted error for invalid input', () => {
+		expect(() => validateInput(urlSchema, 'invalid')).toThrow('Validation failed');
+	});
+
+	it('should re-throw non-ZodError errors', () => {
+		// Create a schema that throws a non-ZodError
+		const faultySchema = {
+			parse: () => {
+				throw new Error('Not a ZodError');
+			},
+			// biome-ignore lint/suspicious/noExplicitAny: Testing error handling
+		} as any;
+
+		expect(() => validateInput(faultySchema, 'input')).toThrow('Not a ZodError');
+	});
+});

src/utils/validation.ts

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Common validation schemas and utilities for input validation
+ * @module utils/validation
+ */
+
+import { z } from 'zod';
+
+/**
+ * Common validation schemas for reuse across tools
+ */
+
+/**
+ * Schema for validating URL strings
+ * @description Ensures the input is a valid URL format
+ * @example
+ * ```typescript
+ * const validUrl = urlSchema.parse("https://example.com");
+ * // Returns: "https://example.com"
+ * ```
+ */
+export const urlSchema = z.string().url('Invalid URL format');
+
+/**
+ * Schema for validating date strings in YYYY-MM-DD format
+ * @description Validates that the input matches the YYYY-MM-DD date format
+ * @example
+ * ```typescript
+ * const validDate = dateSchema.parse("2024-01-15");
+ * // Returns: "2024-01-15"
+ * ```
+ */
+export const dateSchema = z
+	.string()
+	.regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format');
+
+/**
+ * Schema for validating timestamp strings in YYYYMMDDHHmmss format
+ * @description Validates 14-digit timestamp strings commonly used by web archives
+ * @example
+ * ```typescript
+ * const validTimestamp = timestampSchema.parse("20240115143022");
+ * // Returns: "20240115143022" (2024-01-15 14:30:22)
+ * ```
+ */
+export const timestampSchema = z
+	.string()
+	.regex(/^\d{14}$/, 'Timestamp must be in YYYYMMDDHHmmss format');
+
+/**
+ * Validate and parse input with helpful error messages
+ * @param schema - Zod schema to validate against
+ * @param input - Unknown input to validate
+ * @returns Validated and typed input
+ * @throws {Error} If validation fails, with formatted error messages
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ name: z.string() });
+ * const validated = validateInput(schema, { name: "test" });
+ * // Returns: { name: "test" } with TypeScript type inference
+ * ```
+ */
+export function validateInput<T>(schema: z.ZodSchema<T>, input: unknown): T {
+	try {
+		return schema.parse(input);
+	} catch (error) {
+		if (error instanceof z.ZodError) {
+			const issues = error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
+			throw new Error(`Validation failed:\n${issues.join('\n')}`);
+		}
+		throw error;
+	}
+}