@expressots/core 3.0.0 → 4.0.0-preview.3

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

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * Class-Validator Adapter
+ * @module @expressots/core/validation
+ *
+ * Adapter for class-validator library - wraps existing ValidateDTO logic
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClassValidatorAdapter = void 0;
+const package_resolver_js_1 = require("../../dto-validator/package-resolver.js");
+const node_require_js_1 = require("../../../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);
+ * ```
+ */
+class ClassValidatorAdapter {
+    constructor() {
+        this.name = "class-validator";
+        this.priority = 100; // Highest priority - check first
+        // Cache for loaded packages
+        this.classValidator = null;
+        this.classTransformer = null;
+        this.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 (0, package_resolver_js_1.packageResolver)("class-validator");
+        this.classTransformer = await (0, package_resolver_js_1.packageResolver)("class-transformer");
+        this.packagesLoaded = true;
+    }
+    /**
+     * Try to get the class-validator metadata storage
+     */
+    getMetadataStorage() {
+        try {
+            const cv = (0, node_require_js_1.nodeRequire)("class-validator");
+            return cv.getMetadataStorage?.() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.ClassValidatorAdapter = ClassValidatorAdapter;

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

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Validation Adapters
+ * @module @expressots/core/validation/adapters
+ *
+ * Built-in adapters for validation libraries. The validation libraries
+ * themselves (`class-validator`, `zod`, `yup`) are *optional peer
+ * dependencies* — install only the one(s) you actually use.
+ *
+ * Additional Joi adapter is on the roadmap.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createYupValidator = exports.YupValidatorAdapter = exports.createZodValidator = exports.ZodValidatorAdapter = exports.ClassValidatorAdapter = void 0;
+var class_validator_adapter_js_1 = require("./class-validator.adapter.js");
+Object.defineProperty(exports, "ClassValidatorAdapter", { enumerable: true, get: function () { return class_validator_adapter_js_1.ClassValidatorAdapter; } });
+var zod_adapter_js_1 = require("./zod.adapter.js");
+Object.defineProperty(exports, "ZodValidatorAdapter", { enumerable: true, get: function () { return zod_adapter_js_1.ZodValidatorAdapter; } });
+Object.defineProperty(exports, "createZodValidator", { enumerable: true, get: function () { return zod_adapter_js_1.createZodValidator; } });
+var yup_adapter_js_1 = require("./yup.adapter.js");
+Object.defineProperty(exports, "YupValidatorAdapter", { enumerable: true, get: function () { return yup_adapter_js_1.YupValidatorAdapter; } });
+Object.defineProperty(exports, "createYupValidator", { enumerable: true, get: function () { return yup_adapter_js_1.createYupValidator; } });

package/lib/cjs/provider/validation/adapters/yup.adapter.js

@@ -0,0 +1,118 @@
+"use strict";
+/**
+ * Yup Validation Adapter
+ * @module @expressots/core/validation
+ *
+ * Built-in adapter for the [yup](https://github.com/jquense/yup) validation
+ * library. `yup` is declared as an *optional* peer dependency: install it
+ * explicitly (`npm i yup`) to enable this adapter.
+ *
+ * @example
+ * ```ts
+ * import * as yup from "yup";
+ * import { validationRegistry, createYupValidator } from "@expressots/core";
+ *
+ * validationRegistry.register(createYupValidator());
+ *
+ * const CreateUserSchema = yup.object({
+ *   email: yup.string().email().required(),
+ *   age:   yup.number().integer().min(18).required(),
+ * });
+ *
+ * @controller("/users")
+ * class UsersController {
+ *   @Post("/")
+ *   create(@body(CreateUserSchema) input: yup.InferType<typeof CreateUserSchema>) {
+ *     // input is fully typed and validated
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YupValidatorAdapter = void 0;
+exports.createYupValidator = createYupValidator;
+/**
+ * Adapter for [yup](https://github.com/jquense/yup). Detects yup schemas at
+ * runtime by checking for the `__isYupSchema__` brand or the presence of a
+ * `validate` + `cast` method pair.
+ *
+ * @public API
+ */
+class YupValidatorAdapter {
+    constructor() {
+        this.name = "yup";
+        this.priority = 80;
+    }
+    canHandle(schema) {
+        if (schema === null || typeof schema !== "object")
+            return false;
+        const candidate = schema;
+        if (candidate.__isYupSchema__ === true)
+            return true;
+        return (typeof candidate.validate === "function" &&
+            typeof candidate.cast === "function");
+    }
+    async validate(data, schema, options) {
+        if (typeof schema.validate !== "function") {
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: "",
+                        message: "YupValidatorAdapter received a schema with no validate() method.",
+                        code: "invalid_schema",
+                    },
+                ],
+            };
+        }
+        try {
+            const yupOptions = {
+                abortEarly: options?.abortEarly ?? false,
+                stripUnknown: options?.stripUnknown ?? false,
+            };
+            const validated = await schema.validate(data, yupOptions);
+            return { success: true, data: validated };
+        }
+        catch (error) {
+            const yupError = error;
+            // yup batches per-field issues into `inner` when abortEarly is false,
+            // and emits a single message otherwise.
+            const issues = yupError?.inner && yupError.inner.length > 0
+                ? yupError.inner
+                : [yupError];
+            return {
+                success: false,
+                errors: this.mapIssues(issues),
+            };
+        }
+    }
+    async transform(data, schema) {
+        if (typeof schema.cast === "function") {
+            try {
+                return schema.cast(data);
+            }
+            catch {
+                return data;
+            }
+        }
+        return data;
+    }
+    mapIssues(issues) {
+        return issues.map((issue) => ({
+            path: issue.path ?? "",
+            message: issue.message ?? "Validation failed",
+            code: issue.type ?? "validation_error",
+            received: issue.value,
+        }));
+    }
+}
+exports.YupValidatorAdapter = YupValidatorAdapter;
+/**
+ * Convenience factory matching the `createXxxValidator` naming used by the
+ * other adapters. Equivalent to `new YupValidatorAdapter()`.
+ *
+ * @public API
+ */
+function createYupValidator() {
+    return new YupValidatorAdapter();
+}

package/lib/cjs/provider/validation/adapters/zod.adapter.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Zod Validation Adapter
+ * @module @expressots/core/validation
+ *
+ * Built-in adapter for the [zod](https://zod.dev) validation library.
+ * `zod` is declared as an *optional* peer dependency: install it explicitly
+ * (`npm i zod`) to enable this adapter; otherwise validation falls back to
+ * the next registered adapter.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { validationRegistry, ZodValidatorAdapter, createZodValidator } from "@expressots/core";
+ *
+ * validationRegistry.register(createZodValidator());
+ *
+ * const CreateUserSchema = z.object({
+ *   email: z.string().email(),
+ *   age:   z.number().int().min(18),
+ * });
+ *
+ * @controller("/users")
+ * class UsersController {
+ *   @Post("/")
+ *   create(@body(CreateUserSchema) input: z.infer<typeof CreateUserSchema>) {
+ *     // input is fully typed and validated
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZodValidatorAdapter = void 0;
+exports.createZodValidator = createZodValidator;
+/**
+ * Adapter for [zod](https://zod.dev). Picks up any zod schema (`z.object`,
+ * `z.string`, ...) at runtime by structural detection — no compile-time
+ * dependency on `zod` is required.
+ *
+ * @public API
+ */
+class ZodValidatorAdapter {
+    constructor() {
+        this.name = "zod";
+        this.priority = 90;
+    }
+    canHandle(schema) {
+        if (schema === null || typeof schema !== "object")
+            return false;
+        const candidate = schema;
+        return (typeof candidate.safeParseAsync === "function" ||
+            typeof candidate.safeParse === "function" ||
+            typeof candidate.parseAsync === "function" ||
+            typeof candidate.parse === "function");
+    }
+    async validate(data, schema, 
+    // ValidationOptions accepted for interface compliance; Zod surfaces its own
+    // configuration through the schema itself, so options are not consumed here.
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options) {
+        try {
+            // Prefer the safe variants because they encode the failure mode in the
+            // result rather than throwing.
+            if (typeof schema.safeParseAsync === "function") {
+                const r = await schema.safeParseAsync(data);
+                return r.success
+                    ? { success: true, data: r.data }
+                    : { success: false, errors: this.mapIssues(r.error?.issues ?? []) };
+            }
+            if (typeof schema.safeParse === "function") {
+                const r = schema.safeParse(data);
+                return r.success
+                    ? { success: true, data: r.data }
+                    : { success: false, errors: this.mapIssues(r.error?.issues ?? []) };
+            }
+            if (typeof schema.parseAsync === "function") {
+                const parsed = await schema.parseAsync(data);
+                return { success: true, data: parsed };
+            }
+            if (typeof schema.parse === "function") {
+                const parsed = schema.parse(data);
+                return { success: true, data: parsed };
+            }
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: "",
+                        message: "ZodValidatorAdapter received a schema with no parse/safeParse method.",
+                        code: "invalid_schema",
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            // zod throws ZodError for `parse`/`parseAsync`. Pull issues if present.
+            const maybeIssues = error?.issues;
+            if (Array.isArray(maybeIssues)) {
+                return { success: false, errors: this.mapIssues(maybeIssues) };
+            }
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: "",
+                        message: error instanceof Error
+                            ? error.message
+                            : "Validation failed unexpectedly",
+                        code: "validation_error",
+                    },
+                ],
+            };
+        }
+    }
+    async transform(data, schema) {
+        const result = await this.validate(data, schema);
+        return result.success ? result.data : data;
+    }
+    mapIssues(issues) {
+        return issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message,
+            code: issue.code ?? "validation_error",
+            received: issue.received,
+        }));
+    }
+}
+exports.ZodValidatorAdapter = ZodValidatorAdapter;
+/**
+ * Convenience factory matching the `createXxxValidator` naming used by the
+ * other adapters. Equivalent to `new ZodValidatorAdapter()`.
+ *
+ * @public API
+ */
+function createZodValidator() {
+    return new ZodValidatorAdapter();
+}