@scallywag/validation 1.0.0 → 1.0.4

package/dist/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Validation Framework Types
+ *
+ * Common types and interfaces for validation
+ */
+import { z } from 'zod';
+/**
+ * Validation result interface
+ */
+export type ValidationResult<T = unknown> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: ValidationError[];
+};
+/**
+ * Validation error structure
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+    code: string;
+    value?: unknown;
+}
+/**
+ * Validation options
+ */
+export interface ValidationOptions {
+    strict?: boolean;
+    stripUnknown?: boolean;
+    errorMap?: z.ZodErrorMap;
+    async?: boolean;
+}
+/**
+ * Field validation metadata
+ */
+export interface FieldMetadata {
+    required: boolean;
+    type: string;
+    description?: string;
+    examples?: unknown[];
+    constraints?: Record<string, unknown>;
+}
+/**
+ * Schema metadata for documentation
+ */
+export interface SchemaMetadata {
+    name: string;
+    description: string;
+    version: string;
+    fields: Record<string, FieldMetadata>;
+}
+/**
+ * API endpoint validation configuration
+ */
+export interface EndpointValidation {
+    /**
+     * Unified input schema - single Zod schema for all method input.
+     * When present, merges body, query, and params into one validated object.
+     * Takes precedence over separate body/query/params schemas.
+     *
+     * @example
+     * ```typescript
+     * const CreateEventSchema = z.object({
+     *   title: z.string().min(1),
+     *   category: z.enum(['NETWORKING', 'WORKSHOP']),
+     * });
+     *
+     * { input: CreateEventSchema }
+     * ```
+     */
+    input?: z.ZodSchema;
+    /**
+     * Output schema for response validation.
+     * Can be used to validate responses before sending.
+     */
+    output?: z.ZodSchema;
+    body?: z.ZodSchema;
+    query?: z.ZodSchema;
+    params?: z.ZodSchema;
+    headers?: z.ZodSchema;
+    response?: z.ZodSchema;
+}
+/**
+ * Validation rule types for decorators
+ */
+export type ValidationRuleType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'email' | 'url' | 'uuid' | 'date' | 'custom';
+/**
+ * Validation rule definition
+ */
+export interface ValidationRule {
+    field: string;
+    type: ValidationRuleType;
+    required: boolean;
+    constraints?: {
+        min?: number;
+        max?: number;
+        pattern?: string;
+        enum?: unknown[];
+        custom?: (value: unknown) => boolean | string;
+    };
+    message?: string;
+}
+/**
+ * Security validation levels
+ */
+export declare enum SecurityLevel {
+    LOW = "low",
+    MEDIUM = "medium",
+    HIGH = "high",
+    CRITICAL = "critical"
+}
+/**
+ * Input sanitization options
+ */
+export interface SanitizationOptions {
+    html?: boolean;
+    sql?: boolean;
+    xss?: boolean;
+    trim?: boolean;
+    lowercase?: boolean;
+    uppercase?: boolean;
+}
+/**
+ * Validation context for fractal architecture
+ */
+export interface FractalValidationContext {
+    interface: string;
+    method?: string;
+    path?: string;
+    securityLevel: SecurityLevel;
+    userRole?: string;
+    permissions?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * Validation Framework Types
+ *
+ * Common types and interfaces for validation
+ */
+/**
+ * Security validation levels
+ */
+export var SecurityLevel;
+(function (SecurityLevel) {
+    SecurityLevel["LOW"] = "low";
+    SecurityLevel["MEDIUM"] = "medium";
+    SecurityLevel["HIGH"] = "high";
+    SecurityLevel["CRITICAL"] = "critical";
+})(SecurityLevel || (SecurityLevel = {}));
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAuHH;;GAEG;AACH,MAAM,CAAN,IAAY,aAKX;AALD,WAAY,aAAa;IACvB,4BAAW,CAAA;IACX,kCAAiB,CAAA;IACjB,8BAAa,CAAA;IACb,sCAAqB,CAAA;AACvB,CAAC,EALW,aAAa,KAAb,aAAa,QAKxB"}

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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"}