@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/provider/validation/adapters/class-validator.adapter.js

@@ -0,0 +1,258 @@
+/**
+ * Class-Validator Adapter
+ * @module @expressots/core/validation
+ *
+ * Adapter for class-validator library - wraps existing ValidateDTO logic
+ */
+import { packageResolver } from "../../dto-validator/package-resolver.js";
+import { nodeRequire } from "../../../utils/node-require.js";
+/**
+ * Validation adapter for class-validator library
+ *
+ * Uses the existing packageResolver pattern to optionally load
+ * class-validator and class-transformer packages.
+ *
+ * @example
+ * ```typescript
+ * // Register the adapter
+ * validationRegistry.register(new ClassValidatorAdapter());
+ *
+ * // Use with a decorated DTO class
+ * class CreateUserDTO {
+ *     @IsEmail()
+ *     email: string;
+ *
+ *     @MinLength(2)
+ *     name: string;
+ * }
+ *
+ * const result = await adapter.validate(data, CreateUserDTO);
+ * ```
+ */
+export class ClassValidatorAdapter {
+    name = "class-validator";
+    priority = 100; // Highest priority - check first
+    // Cache for loaded packages
+    classValidator = null;
+    classTransformer = null;
+    packagesLoaded = false;
+    /**
+     * Check if this adapter can handle the given schema
+     * Class-validator works with class constructors that have validation decorators
+     */
+    canHandle(schema) {
+        // Must be a function (class constructor)
+        if (typeof schema !== "function") {
+            return false;
+        }
+        // Check for class-validator metadata
+        // class-validator stores metadata using reflect-metadata
+        try {
+            const metadataStorage = this.getMetadataStorage();
+            if (metadataStorage) {
+                const targetMetadata = metadataStorage.getTargetValidationMetadatas(schema, "", false, false);
+                return targetMetadata && targetMetadata.length > 0;
+            }
+        }
+        catch {
+            // If we can't check metadata, assume it might be a DTO class
+            // and let validation proceed (will succeed if no validators)
+        }
+        // Fallback: check if it looks like a class (has prototype)
+        return schema.prototype !== undefined;
+    }
+    /**
+     * Validate data against a class-validator decorated class
+     */
+    async validate(data, schema, options) {
+        // Load packages if not already loaded
+        await this.ensurePackagesLoaded();
+        // If packages aren't available, skip validation (backward compatible)
+        if (!this.classValidator || !this.classTransformer) {
+            return { success: true, data };
+        }
+        const cv = this.classValidator;
+        const ct = this.classTransformer;
+        try {
+            // Transform plain object to class instance
+            const instance = ct.plainToInstance(schema, data, {
+                enableImplicitConversion: true,
+                groups: options?.group ? [options.group] : undefined,
+                excludeExtraneousValues: options?.stripUnknown,
+            });
+            // Validate the instance
+            const errors = await cv.validate(instance, {
+                groups: options?.group ? [options.group] : undefined,
+                skipMissingProperties: options?.partial,
+                whitelist: options?.stripUnknown,
+                forbidNonWhitelisted: false,
+                stopAtFirstError: options?.abortEarly,
+            });
+            if (errors.length === 0) {
+                return { success: true, data: instance };
+            }
+            return {
+                success: false,
+                errors: this.mapErrors(errors),
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: "",
+                        message: error instanceof Error
+                            ? error.message
+                            : "Validation failed unexpectedly",
+                        code: "validation_error",
+                    },
+                ],
+            };
+        }
+    }
+    /**
+     * Transform data without validation
+     */
+    async transform(data, schema) {
+        await this.ensurePackagesLoaded();
+        if (!this.classTransformer) {
+            return data;
+        }
+        const ct = this.classTransformer;
+        return ct.plainToInstance(schema, data, {
+            enableImplicitConversion: true,
+        });
+    }
+    /**
+     * Map class-validator errors to our ValidationFieldError format
+     */
+    mapErrors(errors, parentPath = "") {
+        return errors.flatMap((error) => {
+            const path = parentPath
+                ? `${parentPath}.${error.property}`
+                : error.property;
+            // Handle nested errors
+            if (error.children && error.children.length > 0) {
+                return this.mapErrors(error.children, path);
+            }
+            // Get constraint messages
+            const constraints = error.constraints || {};
+            const messages = Object.values(constraints);
+            const codes = Object.keys(constraints);
+            // Create helpful error with example and hint
+            const validationError = {
+                path,
+                message: messages.join(", ") || "Validation failed",
+                code: codes[0] || "validation_error",
+                received: error.value,
+                constraints,
+                ...this.getHelpfulInfo(path, codes[0], error.value),
+            };
+            return [validationError];
+        });
+    }
+    /**
+     * Get helpful information (example and hint) based on the error type
+     */
+    getHelpfulInfo(path, code, value) {
+        const fieldName = path.split(".").pop() || path;
+        // Provide helpful info based on common validation codes
+        switch (code) {
+            case "isEmail":
+                return {
+                    expected: "valid email address",
+                    example: "user@example.com",
+                    hint: "Check for missing @ symbol or domain",
+                };
+            case "isNotEmpty":
+                return {
+                    expected: "non-empty value",
+                    example: fieldName.toLowerCase().includes("email")
+                        ? "user@example.com"
+                        : "example value",
+                    hint: "This field is required",
+                };
+            case "minLength":
+                return {
+                    expected: "string with minimum length",
+                    hint: `Value "${value}" is too short`,
+                };
+            case "maxLength":
+                return {
+                    expected: "string within maximum length",
+                    hint: `Value "${value}" is too long`,
+                };
+            case "isInt":
+            case "isNumber":
+                return {
+                    expected: "number",
+                    example: 42,
+                    hint: "Remove quotes and non-numeric characters",
+                };
+            case "isBoolean":
+                return {
+                    expected: "boolean",
+                    example: true,
+                    hint: "Use true, false, 1, or 0",
+                };
+            case "isUUID":
+                return {
+                    expected: "valid UUID",
+                    example: "550e8400-e29b-41d4-a716-446655440000",
+                    hint: "UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+                };
+            case "isUrl":
+            case "isURL":
+                return {
+                    expected: "valid URL",
+                    example: "https://example.com",
+                    hint: "Include protocol (http:// or https://)",
+                };
+            case "isPhoneNumber":
+                return {
+                    expected: "valid phone number",
+                    example: "+1234567890",
+                    hint: "Include country code",
+                };
+            case "isDate":
+            case "isDateString":
+                return {
+                    expected: "valid date",
+                    example: "2024-01-15",
+                    hint: "Use ISO 8601 format (YYYY-MM-DD)",
+                };
+            case "isArray":
+                return {
+                    expected: "array",
+                    example: [],
+                    hint: "Provide an array value",
+                };
+            default:
+                return {};
+        }
+    }
+    /**
+     * Ensure class-validator and class-transformer packages are loaded
+     */
+    async ensurePackagesLoaded() {
+        if (this.packagesLoaded) {
+            return;
+        }
+        this.classValidator = await packageResolver("class-validator");
+        this.classTransformer = await packageResolver("class-transformer");
+        this.packagesLoaded = true;
+    }
+    /**
+     * Try to get the class-validator metadata storage
+     */
+    getMetadataStorage() {
+        try {
+            const cv = nodeRequire("class-validator");
+            return cv.getMetadataStorage?.() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/lib/esm/provider/validation/adapters/index.js

@@ -0,0 +1,10 @@
+/**
+ * Validation Adapters
+ * @module @expressots/core/validation/adapters
+ *
+ * Built-in adapters for validation libraries.
+ * Additional adapters (Zod, Yup, Joi) available as separate packages:
+ * - @expressots/validator-zod
+ * - @expressots/validator-yup
+ */
+export { ClassValidatorAdapter } from "./class-validator.adapter.js";

package/lib/esm/provider/validation/helpful-error-formatter.js

@@ -0,0 +1,225 @@
+/**
+ * Helpful Error Formatter
+ * @module @expressots/core/validation
+ *
+ * Formats validation errors with helpful information including
+ * examples, hints, and received values - making debugging easier.
+ */
+/**
+ * Helpful Error Formatter
+ *
+ * Transforms validation errors into user-friendly formats with
+ * examples, hints, and contextual information.
+ *
+ * @example
+ * ```typescript
+ * const formatter = new HelpfulErrorFormatter();
+ *
+ * // Format errors with helpful information
+ * const response = formatter.format(errors, "helpful");
+ * // Returns:
+ * // {
+ * //   type: "validation-error",
+ * //   title: "Validation Failed",
+ * //   status: 400,
+ * //   errors: [{
+ * //     field: "email",
+ * //     message: "Must be a valid email address",
+ * //     received: "not-an-email",
+ * //     example: "user@example.com",
+ * //     hint: "Check for missing @ symbol"
+ * //   }]
+ * // }
+ * ```
+ */
+export class HelpfulErrorFormatter {
+    documentationBaseUrl;
+    /**
+     * Set the base URL for documentation links in error responses
+     * @param url - Base URL for API documentation
+     */
+    setDocumentationUrl(url) {
+        this.documentationBaseUrl = url;
+    }
+    /**
+     * Format validation errors into a response object
+     * @param errors - Array of validation errors
+     * @param format - Output format (helpful, simple, rfc7807, flat)
+     * @returns Formatted error response
+     */
+    format(errors, format = "helpful") {
+        switch (format) {
+            case "simple":
+                return this.formatSimple(errors);
+            case "rfc7807":
+                return this.formatRfc7807(errors);
+            case "flat":
+                return this.formatFlat(errors);
+            case "helpful":
+            default:
+                return this.formatHelpful(errors);
+        }
+    }
+    /**
+     * Format errors in the "helpful" format with examples and hints
+     */
+    formatHelpful(errors) {
+        return {
+            type: "validation-error",
+            title: "Validation Failed",
+            status: 400,
+            detail: this.getSummary(errors),
+            errors: errors.map((error) => ({
+                field: error.path,
+                message: error.message,
+                code: error.code,
+                received: this.sanitizeValue(error.received),
+                expected: error.expected,
+                example: error.example,
+                hint: error.hint,
+            })),
+            documentation: this.documentationBaseUrl
+                ? `${this.documentationBaseUrl}/errors/validation`
+                : undefined,
+        };
+    }
+    /**
+     * Format errors in a simple format (just field and message)
+     */
+    formatSimple(errors) {
+        return {
+            status: 400,
+            message: "Validation failed",
+            errors: errors.map((error) => ({
+                field: error.path,
+                message: error.message,
+            })),
+        };
+    }
+    /**
+     * Format errors according to RFC 7807 (Problem Details for HTTP APIs)
+     */
+    formatRfc7807(errors) {
+        return {
+            type: "https://expressots.com/errors/validation",
+            title: "Validation Failed",
+            status: 400,
+            detail: this.getSummary(errors),
+            errors: errors.map((error) => ({
+                pointer: `/${error.path.replace(/\./g, "/")}`,
+                title: error.message,
+                code: error.code || "validation_error",
+            })),
+        };
+    }
+    /**
+     * Format errors as a flat object (field -> message)
+     */
+    formatFlat(errors) {
+        const errorMap = {};
+        errors.forEach((error) => {
+            if (!errorMap[error.path]) {
+                errorMap[error.path] = error.message;
+            }
+            else {
+                errorMap[error.path] += `, ${error.message}`;
+            }
+        });
+        return {
+            status: 400,
+            message: "Validation failed",
+            errors: Object.entries(errorMap).map(([field, message]) => ({
+                field,
+                message,
+            })),
+        };
+    }
+    /**
+     * Generate a human-readable summary of the errors
+     */
+    getSummary(errors) {
+        const count = errors.length;
+        if (count === 1) {
+            return `1 validation error in field "${errors[0].path}"`;
+        }
+        const fields = [...new Set(errors.map((e) => e.path))];
+        if (fields.length === 1) {
+            return `${count} validation errors in field "${fields[0]}"`;
+        }
+        if (fields.length <= 3) {
+            return `${count} validation errors in fields: ${fields.join(", ")}`;
+        }
+        return `${count} validation errors in ${fields.length} fields`;
+    }
+    /**
+     * Sanitize a value for display in error messages
+     * (hide sensitive data, truncate long strings)
+     */
+    sanitizeValue(value) {
+        if (value === undefined || value === null) {
+            return value;
+        }
+        if (typeof value === "string") {
+            // Check for sensitive field patterns
+            if (value.length > 0) {
+                // Truncate long strings
+                if (value.length > 100) {
+                    return `${value.substring(0, 100)}... (truncated)`;
+                }
+            }
+            return value;
+        }
+        if (Array.isArray(value)) {
+            if (value.length > 10) {
+                return `[Array with ${value.length} items]`;
+            }
+            return value.slice(0, 10).map((v) => this.sanitizeValue(v));
+        }
+        if (typeof value === "object") {
+            return "[Object]";
+        }
+        return value;
+    }
+    /**
+     * Create a custom error response with the given format
+     * @param errors - Validation errors
+     * @param customizer - Function to customize each error
+     * @returns Customized error response
+     */
+    formatCustom(errors, customizer) {
+        return {
+            status: 400,
+            message: "Validation failed",
+            errors: errors.map(customizer),
+        };
+    }
+    /**
+     * Group errors by field path
+     * @param errors - Validation errors
+     * @returns Errors grouped by field
+     */
+    groupByField(errors) {
+        return errors.reduce((acc, error) => {
+            if (!acc[error.path]) {
+                acc[error.path] = [];
+            }
+            acc[error.path].push(error);
+            return acc;
+        }, {});
+    }
+    /**
+     * Get the first error for each field
+     * @param errors - Validation errors
+     * @returns First error per field
+     */
+    getFirstErrorPerField(errors) {
+        const seen = new Set();
+        return errors.filter((error) => {
+            if (seen.has(error.path)) {
+                return false;
+            }
+            seen.add(error.path);
+            return true;
+        });
+    }
+}

package/lib/esm/provider/validation/index.js

@@ -0,0 +1,21 @@
+/**
+ * Validation System
+ * @module @expressots/core/validation
+ *
+ * ExpressoTS Smart Validation System
+ *
+ * Features:
+ * - Pluggable adapter architecture (class-validator, Zod, Yup, custom)
+ * - TypeScript-first auto-validation
+ * - Smart field detection (email, phone, url, password, etc.)
+ * - Helpful error messages with examples and hints
+ * - Universal parameter validation (@body, @query, @param, @headers)
+ */
+// Core components
+export { ValidationRegistry } from "./validation-registry.js";
+export { SmartFieldDetector } from "./smart-field-detector.js";
+export { HelpfulErrorFormatter, } from "./helpful-error-formatter.js";
+// Type inference utilities
+export { getParameterType, getAllParameterTypes, getClassProperties, hasClassValidatorDecorators, isZodSchema, isClassConstructor, detectSchemaType, } from "./type-inference.js";
+// Built-in adapters
+export { ClassValidatorAdapter } from "./adapters/index.js";