@scallywag/validation 1.0.0 → 1.0.1

package/dist/validators.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Validation Utilities
+ *
+ * Helper functions for validation and sanitization
+ */
+import { z } from 'zod';
+import { FractalValidationContext, ValidationError, ValidationOptions, ValidationResult } from './types';
+export { sanitizeString, sanitizeObjectStrings, containsXssPatterns, XSS_PATTERNS, SQL_PATTERNS, HTML_ENTITIES, } from './sanitization';
+/**
+ * Validate data against a Zod schema
+ */
+export declare function validateData<T>(schema: z.ZodSchema<T>, data: unknown, options?: ValidationOptions): Promise<ValidationResult<T>>;
+/**
+ * Validate and sanitize request data
+ */
+export declare function validateRequest<T>(schema: z.ZodSchema<T>, data: unknown, context?: FractalValidationContext): Promise<ValidationResult<T>>;
+/**
+ * Create a validation decorator for class methods
+ */
+export declare function createValidationDecorator<T>(schema: z.ZodSchema<T>, options?: ValidationOptions): (_target: unknown, _propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
+/**
+ * Validate environment variables
+ */
+export declare function validateEnv<T>(schema: z.ZodSchema<T>): T;
+/**
+ * Create a validator function from a schema
+ */
+export declare function createValidator<T>(schema: z.ZodSchema<T>): (data: unknown) => data is T;
+/**
+ * Create an async validator function from a schema
+ */
+export declare function createAsyncValidator<T>(schema: z.ZodSchema<T>): (data: unknown) => Promise<boolean>;
+/**
+ * Validate file upload
+ */
+export declare function validateFileUpload(file: File, allowedTypes: string[], maxSize: number): ValidationResult<File>;
+/**
+ * Batch validate multiple values
+ */
+export declare function batchValidate<T>(schema: z.ZodSchema<T>, dataArray: unknown[], options?: ValidationOptions): Promise<Array<ValidationResult<T>>>;
+/**
+ * Custom error formatter for API responses
+ */
+export declare function formatValidationErrors(errors: ValidationError[]): Record<string, string[]>;
+/**
+ * Check if validation result has specific error codes
+ */
+export declare function hasErrorCode(result: ValidationResult<unknown>, code: string): boolean;
+/**
+ * Get validation errors for a specific field
+ */
+export declare function getFieldErrors(result: ValidationResult<unknown>, field: string): ValidationError[];
+/**
+ * Validate input against a Zod schema synchronously.
+ * Throws a structured error on validation failure.
+ *
+ * Use this at module boundaries where invalid input should be rejected
+ * immediately. For non-throwing validation, use `safeValidateInput`.
+ */
+export declare function validateInput<T>(schema: z.ZodSchema<T>, input: unknown): T;
+/**
+ * Validate input against a Zod schema synchronously.
+ * Returns a discriminated result object instead of throwing.
+ *
+ * Use this when the caller needs to handle validation failure
+ * gracefully without try/catch.
+ */
+export declare function safeValidateInput<T>(schema: z.ZodSchema<T>, input: unknown): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: string[];
+};
+/**
+ * Parse JSON string and validate with Zod schema
+ * Combines JSON.parse() with Zod validation for type-safe parsing
+ *
+ * @param schema - Zod schema to validate against
+ * @param jsonString - JSON string to parse and validate
+ * @returns Validated and parsed data
+ * @throws ZodError if validation fails
+ * @throws SyntaxError if JSON parsing fails
+ *
+ * @example
+ * ```typescript
+ * const UserSchema = z.object({ name: z.string(), age: z.number() });
+ * const user = parseAndValidateJSON(UserSchema, '{"name":"John","age":30}');
+ * ```
+ */
+export declare function parseAndValidateJSON<T>(schema: z.ZodSchema<T>, jsonString: string): T;
+/**
+ * Safely parse JSON string and validate with Zod schema
+ * Returns a result object instead of throwing
+ *
+ * @param schema - Zod schema to validate against
+ * @param jsonString - JSON string to parse and validate
+ * @returns Validation result with success flag
+ *
+ * @example
+ * ```typescript
+ * const result = safeParseAndValidateJSON(UserSchema, jsonString);
+ * if (result.success) {
+ *   processData(result.data);
+ * } else {
+ *   handleErrors(result.errors);
+ * }
+ * ```
+ */
+export declare function safeParseAndValidateJSON<T>(schema: z.ZodSchema<T>, jsonString: string): ValidationResult<T>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","sourceRoot":"","sources":["../validators.ts"],"names":[],"mappings":"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"}

package/dist/validators.js

@@ -0,0 +1,324 @@
+/**
+ * Validation Utilities
+ *
+ * Helper functions for validation and sanitization
+ */
+import { z } from 'zod';
+import { sanitizeObjectStrings } from './sanitization';
+/**
+ * Convert a ZodError into an array of ValidationError objects.
+ * Shared between parseAndValidateJSON and safeParseAndValidateJSON.
+ */
+function zodErrorToValidationErrors(error) {
+    return error.issues.map((err) => ({
+        field: err.path.join('.'),
+        message: err.message,
+        code: err.code,
+        value: 'received' in err ? err.received : undefined,
+    }));
+}
+// Re-export sanitization utilities for consumers
+export { sanitizeString, sanitizeObjectStrings, containsXssPatterns, XSS_PATTERNS, SQL_PATTERNS, HTML_ENTITIES, } from './sanitization';
+/**
+ * Validate data against a Zod schema
+ */
+export async function validateData(schema, data, options = {}) {
+    try {
+        const result = options.async
+            ? await schema.parseAsync(data)
+            : schema.parse(data);
+        return {
+            success: true,
+            data: result,
+        };
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            return {
+                success: false,
+                errors: zodErrorToValidationErrors(error),
+            };
+        }
+        return {
+            success: false,
+            errors: [
+                {
+                    field: 'unknown',
+                    message: 'Validation failed with unknown error',
+                    code: 'unknown_error',
+                    value: data,
+                },
+            ],
+        };
+    }
+}
+/**
+ * Validate and sanitize request data
+ */
+export async function validateRequest(schema, data, context) {
+    // Pre-sanitization for string fields
+    if (typeof data === 'object' && data !== null) {
+        const sanitizedData = sanitizeObjectStrings(data);
+        return validateData(schema, sanitizedData, {
+            strict: (context === null || context === void 0 ? void 0 : context.securityLevel) === 'critical',
+        });
+    }
+    return validateData(schema, data, {
+        strict: (context === null || context === void 0 ? void 0 : context.securityLevel) === 'critical',
+    });
+}
+/**
+ * Create a validation decorator for class methods
+ */
+export function createValidationDecorator(schema, options = {}) {
+    return function (_target, _propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        descriptor.value = async function (...args) {
+            // Validate the first argument (typically request data)
+            const dataToValidate = args[0];
+            const validationResult = await validateData(schema, dataToValidate, options);
+            if (!validationResult.success) {
+                throw new Error(`Validation failed: ${JSON.stringify(validationResult.errors)}`);
+            }
+            // Replace the first argument with validated data
+            args[0] = validationResult.data;
+            return originalMethod.apply(this, args);
+        };
+        return descriptor;
+    };
+}
+/**
+ * Validate environment variables
+ */
+export function validateEnv(schema) {
+    try {
+        return schema.parse(process.env);
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const errorMessage = error.issues
+                .map((err) => `${err.path.join('.')}: ${err.message}`)
+                .join('\n');
+            throw new Error(`Environment validation failed:\n${errorMessage}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Create a validator function from a schema
+ */
+export function createValidator(schema) {
+    return (data) => {
+        try {
+            schema.parse(data);
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    };
+}
+/**
+ * Create an async validator function from a schema
+ */
+export function createAsyncValidator(schema) {
+    return async (data) => {
+        try {
+            await schema.parseAsync(data);
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    };
+}
+/**
+ * Validate file upload
+ */
+export function validateFileUpload(file, allowedTypes, maxSize) {
+    const errors = [];
+    if (!file) {
+        errors.push({
+            field: 'file',
+            message: 'File is required',
+            code: 'required',
+        });
+    }
+    if (file && !allowedTypes.includes(file.type)) {
+        errors.push({
+            field: 'type',
+            message: `File type not allowed. Allowed types: ${allowedTypes.join(', ')}`,
+            code: 'invalid_type',
+            value: file.type,
+        });
+    }
+    if (file && file.size > maxSize) {
+        errors.push({
+            field: 'size',
+            message: `File too large. Maximum size: ${maxSize} bytes`,
+            code: 'too_large',
+            value: file.size,
+        });
+    }
+    if (errors.length === 0) {
+        return {
+            success: true,
+            data: file,
+        };
+    }
+    else {
+        return {
+            success: false,
+            errors,
+        };
+    }
+}
+/**
+ * Batch validate multiple values
+ */
+export async function batchValidate(schema, dataArray, options = {}) {
+    return Promise.all(dataArray.map((data) => validateData(schema, data, options)));
+}
+/**
+ * Custom error formatter for API responses
+ */
+export function formatValidationErrors(errors) {
+    var _a;
+    // @preflight-ignore:in-memory Temporary local object for building API response, not persistent storage.
+    const formatted = {};
+    for (const error of errors) {
+        const fieldErrors = (_a = formatted[error.field]) !== null && _a !== void 0 ? _a : [];
+        fieldErrors.push(error.message);
+        formatted[error.field] = fieldErrors;
+    }
+    return formatted;
+}
+/**
+ * Check if validation result has specific error codes
+ */
+export function hasErrorCode(result, code) {
+    if (!result.success && result.errors) {
+        return result.errors.some((error) => error.code === code);
+    }
+    return false;
+}
+/**
+ * Get validation errors for a specific field
+ */
+export function getFieldErrors(result, field) {
+    if (!result.success && result.errors) {
+        return result.errors.filter((error) => error.field === field);
+    }
+    return [];
+}
+/**
+ * Validate input against a Zod schema synchronously.
+ * Throws a structured error on validation failure.
+ *
+ * Use this at module boundaries where invalid input should be rejected
+ * immediately. For non-throwing validation, use `safeValidateInput`.
+ */
+export function validateInput(schema, input) {
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        const errors = result.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`);
+        throw new Error(`Validation failed: ${errors.join('; ')}`);
+    }
+    return result.data;
+}
+/**
+ * Validate input against a Zod schema synchronously.
+ * Returns a discriminated result object instead of throwing.
+ *
+ * Use this when the caller needs to handle validation failure
+ * gracefully without try/catch.
+ */
+export function safeValidateInput(schema, input) {
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        return {
+            success: false,
+            errors: result.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`),
+        };
+    }
+    return { success: true, data: result.data };
+}
+/**
+ * Parse JSON string and validate with Zod schema
+ * Combines JSON.parse() with Zod validation for type-safe parsing
+ *
+ * @param schema - Zod schema to validate against
+ * @param jsonString - JSON string to parse and validate
+ * @returns Validated and parsed data
+ * @throws ZodError if validation fails
+ * @throws SyntaxError if JSON parsing fails
+ *
+ * @example
+ * ```typescript
+ * const UserSchema = z.object({ name: z.string(), age: z.number() });
+ * const user = parseAndValidateJSON(UserSchema, '{"name":"John","age":30}');
+ * ```
+ */
+export function parseAndValidateJSON(schema, jsonString) {
+    const parsed = JSON.parse(jsonString);
+    return schema.parse(parsed);
+}
+/**
+ * Safely parse JSON string and validate with Zod schema
+ * Returns a result object instead of throwing
+ *
+ * @param schema - Zod schema to validate against
+ * @param jsonString - JSON string to parse and validate
+ * @returns Validation result with success flag
+ *
+ * @example
+ * ```typescript
+ * const result = safeParseAndValidateJSON(UserSchema, jsonString);
+ * if (result.success) {
+ *   processData(result.data);
+ * } else {
+ *   handleErrors(result.errors);
+ * }
+ * ```
+ */
+export function safeParseAndValidateJSON(schema, jsonString) {
+    try {
+        const parsed = JSON.parse(jsonString);
+        const validated = schema.parse(parsed);
+        return {
+            success: true,
+            data: validated,
+        };
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            return {
+                success: false,
+                errors: [
+                    {
+                        field: 'json',
+                        message: `Invalid JSON: ${error.message}`,
+                        code: 'invalid_json',
+                    },
+                ],
+            };
+        }
+        if (error instanceof z.ZodError) {
+            return {
+                success: false,
+                errors: zodErrorToValidationErrors(error),
+            };
+        }
+        return {
+            success: false,
+            errors: [
+                {
+                    field: 'unknown',
+                    message: 'Unknown error during parsing/validation',
+                    code: 'unknown_error',
+                },
+            ],
+        };
+    }
+}
+//# sourceMappingURL=validators.js.map

package/dist/validators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.js","sourceRoot":"","sources":["../validators.ts"],"names":[],"mappings":"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"}

package/dist/wrappers.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Validation Wrappers
+ *
+ * High-level wrapper functions for common validation patterns.
+ * These provide ergonomic APIs for JSON parsing with schema validation
+ * and type-safe assertion helpers.
+ */
+import { z } from 'zod';
+import type { ValidationError } from './types';
+/**
+ * Error thrown when JSON parsing fails
+ */
+export declare class JsonParseError extends Error {
+    readonly code: "JSON_PARSE_ERROR";
+    readonly rawInput: string;
+    constructor(message: string, rawInput: string, cause?: Error);
+}
+/**
+ * Error thrown when schema validation fails
+ */
+export declare class SchemaValidationError extends Error {
+    readonly code: "SCHEMA_VALIDATION_ERROR";
+    readonly errors: ValidationError[];
+    readonly value: unknown;
+    constructor(message: string, errors: ValidationError[], value: unknown);
+    /**
+     * Get a formatted summary of validation errors
+     */
+    getErrorSummary(): string;
+}
+/**
+ * Parse a JSON string and validate it against a Zod schema.
+ *
+ * Combines JSON.parse() with Zod validation in a single operation,
+ * providing type-safe parsing with clear error types.
+ *
+ * @param json - The JSON string to parse
+ * @param schema - The Zod schema to validate against
+ * @returns The parsed and validated data with full type inference
+ * @throws JsonParseError if the JSON string is malformed
+ * @throws SchemaValidationError if the parsed data fails schema validation
+ *
+ * @example
+ * const UserSchema = z.object(\{
+ *   id: z.string().uuid(),
+ *   name: z.string().min(1),
+ *   email: z.string().email(),
+ * \});
+ *
+ * // Fully typed: user is \{ id: string; name: string; email: string \}
+ * const user = parseJsonWithSchema(jsonString, UserSchema);
+ *
+ * // Error handling - catch JsonParseError for invalid JSON
+ * // and SchemaValidationError for validation failures
+ */
+export declare function parseJsonWithSchema<T>(json: string, schema: z.ZodSchema<T>): T;
+/**
+ * Assert that a value conforms to a Zod schema, narrowing the type.
+ *
+ * This is a type assertion function that throws if validation fails,
+ * allowing TypeScript to narrow the type after the assertion.
+ *
+ * @param value - The value to validate
+ * @param schema - The Zod schema to validate against
+ * @throws SchemaValidationError if validation fails
+ *
+ * @example
+ * const ConfigSchema = z.object(\{ port: z.number(), host: z.string() \});
+ *
+ * function loadConfig(rawConfig: unknown): void \{
+ *   // After this line, TypeScript knows rawConfig is \{ port: number; host: string \}
+ *   assertSchema(rawConfig, ConfigSchema);
+ *   // Type-safe access to rawConfig.host and rawConfig.port
+ * \}
+ */
+export declare function assertSchema<T>(value: unknown, schema: z.ZodSchema<T>): asserts value is T;
+/**
+ * Type guard version of assertSchema that returns a boolean instead of throwing.
+ *
+ * Useful when you want to check if a value matches a schema without throwing,
+ * while still getting type narrowing in the true branch.
+ *
+ * @param value - The value to check
+ * @param schema - The Zod schema to validate against
+ * @returns True if the value matches the schema, false otherwise
+ *
+ * @example
+ * function handleMessage(msg: unknown): void \{
+ *   if (isSchema(msg, TextMessageSchema)) \{
+ *     // msg is typed as TextMessage here
+ *   \} else if (isSchema(msg, ImageMessageSchema)) \{
+ *     // msg is typed as ImageMessage here
+ *   \}
+ * \}
+ */
+export declare function isSchema<T>(value: unknown, schema: z.ZodSchema<T>): value is T;
+/**
+ * Parse JSON string safely, returning the parsed value or a default.
+ *
+ * Use this when you need to parse JSON before applying a Zod schema,
+ * or when the schema is determined dynamically.
+ *
+ * @param json - The JSON string to parse
+ * @param defaultValue - Value to return if parsing fails
+ * @returns The parsed value as unknown, or the default value
+ *
+ * @example
+ * ```typescript
+ * // Parse request body, defaulting to empty object on failure
+ * const body = safeParseJson(text, {});
+ *
+ * // Then validate with a schema
+ * const validated = MySchema.parse(body);
+ * ```
+ */
+export declare function safeParseJson(json: string, defaultValue?: unknown): unknown;
+//# sourceMappingURL=wrappers.d.ts.map

package/dist/wrappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrappers.d.ts","sourceRoot":"","sources":["../wrappers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;GAEG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,IAAI,EAAG,kBAAkB,CAAU;IACnD,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAgB7D;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,SAAgB,IAAI,EAAG,yBAAyB,CAAU;IAC1D,SAAgB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1C,SAAgB,KAAK,EAAE,OAAO,CAAC;gBAEnB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,KAAK,EAAE,OAAO;IAUtE;;OAEG;IACI,eAAe,IAAI,MAAM;CAGjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GACrB,CAAC,CAuCH;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,KAAK,IAAI,CAAC,CAsBpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GACrB,KAAK,IAAI,CAAC,CAEZ;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,YAAY,GAAE,OAAc,GAC3B,OAAO,CAMT"}