@expressots/core 4.0.0-preview.1 → 4.0.0-preview.3

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();
+}

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

@@ -13,7 +13,7 @@
  * - Universal parameter validation (@body, @query, @param, @headers)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClassValidatorAdapter = exports.detectSchemaType = exports.isClassConstructor = exports.isZodSchema = exports.hasClassValidatorDecorators = exports.getClassProperties = exports.getAllParameterTypes = exports.getParameterType = exports.HelpfulErrorFormatter = exports.SmartFieldDetector = exports.ValidationRegistry = void 0;
+exports.createYupValidator = exports.YupValidatorAdapter = exports.createZodValidator = exports.ZodValidatorAdapter = exports.ClassValidatorAdapter = exports.detectSchemaType = exports.isClassConstructor = exports.isZodSchema = exports.hasClassValidatorDecorators = exports.getClassProperties = exports.getAllParameterTypes = exports.getParameterType = exports.HelpfulErrorFormatter = exports.SmartFieldDetector = exports.ValidationRegistry = void 0;
 // Core components
 var validation_registry_js_1 = require("./validation-registry.js");
 Object.defineProperty(exports, "ValidationRegistry", { enumerable: true, get: function () { return validation_registry_js_1.ValidationRegistry; } });
@@ -33,3 +33,7 @@ Object.defineProperty(exports, "detectSchemaType", { enumerable: true, get: func
 // Built-in adapters
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "ClassValidatorAdapter", { enumerable: true, get: function () { return index_js_1.ClassValidatorAdapter; } });
+Object.defineProperty(exports, "ZodValidatorAdapter", { enumerable: true, get: function () { return index_js_1.ZodValidatorAdapter; } });
+Object.defineProperty(exports, "createZodValidator", { enumerable: true, get: function () { return index_js_1.createZodValidator; } });
+Object.defineProperty(exports, "YupValidatorAdapter", { enumerable: true, get: function () { return index_js_1.YupValidatorAdapter; } });
+Object.defineProperty(exports, "createYupValidator", { enumerable: true, get: function () { return index_js_1.createYupValidator; } });

package/lib/cjs/render/adapters/react-adapter.js

@@ -300,20 +300,20 @@ class ReactAdapter extends base_adapter_js_1.BaseEngineAdapter {
             .replace(/</g, "\\u003c")
             .replace(/>/g, "\\u003e")
             .replace(/&/g, "\\u0026");
-        return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <script>
-    window.__INITIAL_DATA__ = ${safeData};
-    window.__COMPONENT__ = "${view}";
-  </script>
-</head>
-<body>
-  <div id="root">${html}</div>
-  <script src="/assets/client.js" defer></script>
-</body>
+        return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <script>
+    window.__INITIAL_DATA__ = ${safeData};
+    window.__COMPONENT__ = "${view}";
+  </script>
+</head>
+<body>
+  <div id="root">${html}</div>
+  <script src="/assets/client.js" defer></script>
+</body>
 </html>`;
     }
     /**

package/lib/cjs/render/features/type-generator.js

@@ -114,36 +114,36 @@ class TypeGenerator {
             const propsType = v.propsType || "Record<string, unknown>";
             return `  "${v.name}": ${propsType};`;
         });
-        return `/**
- * Auto-generated view types
- * Generated by ExpressoTS Render Engine
- * Do not edit this file manually
- */
-
-/**
- * View name to props type mapping
- */
-export interface Views {
-${viewTypes.join("\n")}
-}
-
-/**
- * All view names
- */
-export type ViewName = keyof Views;
-
-/**
- * Get props type for a specific view
- */
-export type ViewProps<T extends ViewName> = Views[T];
-
-/**
- * Type-safe render function signature
- */
-export type RenderFunction = <T extends ViewName>(
-  view: T,
-  data: Views[T],
-) => Promise<string>;
+        return `/**
+ * Auto-generated view types
+ * Generated by ExpressoTS Render Engine
+ * Do not edit this file manually
+ */
+
+/**
+ * View name to props type mapping
+ */
+export interface Views {
+${viewTypes.join("\n")}
+}
+
+/**
+ * All view names
+ */
+export type ViewName = keyof Views;
+
+/**
+ * Get props type for a specific view
+ */
+export type ViewProps<T extends ViewName> = Views[T];
+
+/**
+ * Type-safe render function signature
+ */
+export type RenderFunction = <T extends ViewName>(
+  view: T,
+  data: Views[T],
+) => Promise<string>;
 `;
     }
     /**

package/lib/cjs/render/features/view-debugger.js

@@ -29,12 +29,18 @@ class ViewDebugger {
         app.get("/__views", (req, res) => {
             this.handleViewsEndpoint(req, res);
         });
-        // Preview a view
-        app.get("/__views/preview/:view(*)", (req, res) => {
+        // Preview a view. The view name can contain slashes (e.g.
+        // `users/profile`), so we use a named splat (`*view`) — the
+        // path-to-regexp v6 form `:view(*)` shipped by Express 4 is not
+        // valid in path-to-regexp v8 (Express 5) and now throws
+        // `Missing parameter name`. Path-to-regexp v8 captures the splat
+        // segments as `req.params.view: string[]`; the helpers below
+        // normalise that to a slash-joined string for backward compat.
+        app.get("/__views/preview/*view", (req, res) => {
             this.handlePreviewEndpoint(req, res);
         });
-        // Get view info
-        app.get("/__views/info/:view(*)", (req, res) => {
+        // Get view info — same shape as preview.
+        app.get("/__views/info/*view", (req, res) => {
             this.handleInfoEndpoint(req, res);
         });
         // Get metrics
@@ -73,7 +79,7 @@ class ViewDebugger {
      */
     async handlePreviewEndpoint(req, res) {
         try {
-            const view = req.params.view;
+            const view = this.resolveViewParam(req.params.view);
             const data = req.query.data ? JSON.parse(req.query.data) : {};
             const html = await this.renderService.render(view, data);
             res.setHeader("Content-Type", "text/html");
@@ -82,16 +88,30 @@ class ViewDebugger {
         catch (error) {
             res.status(500).json({
                 error: error.message,
-                view: req.params.view,
+                view: this.resolveViewParam(req.params.view),
             });
         }
     }
+    /**
+     * Normalise the `view` route param across Express 4 and 5.
+     *
+     * Express 4 / path-to-regexp v6 captured `/__views/preview/:view(*)`
+     * as a single string. Express 5 / path-to-regexp v8 changed the
+     * named-splat capture to `string[]` (one entry per slash-separated
+     * segment). The view engine needs the slash-joined form, so we always
+     * collapse the array shape back to that.
+     */
+    resolveViewParam(value) {
+        if (Array.isArray(value))
+            return value.join("/");
+        return typeof value === "string" ? value : "";
+    }
     /**
      * Handle the view info endpoint.
      */
     handleInfoEndpoint(req, res) {
         try {
-            const view = req.params.view;
+            const view = this.resolveViewParam(req.params.view);
             const viewFiles = this.renderService.getViewFiles();
             // Find matching view
             const matchingFiles = viewFiles.filter((file) => file.includes(view));
@@ -120,54 +140,54 @@ class ViewDebugger {
      * Wrap preview HTML with debug info.
      */
     wrapPreview(view, html) {
-        return `<!DOCTYPE html>
-<html>
-<head>
-  <title>View Preview: ${view}</title>
-  <style>
-    .debug-bar {
-      position: fixed;
-      top: 0;
-      left: 0;
-      right: 0;
-      background: #1a1a2e;
-      color: #eee;
-      padding: 8px 16px;
-      font-family: system-ui, -apple-system, sans-serif;
-      font-size: 13px;
-      z-index: 99999;
-      display: flex;
-      align-items: center;
-      gap: 16px;
-      box-shadow: 0 2px 8px rgba(0,0,0,0.2);
-    }
-    .debug-bar strong {
-      color: #00d9ff;
-    }
-    .debug-bar a {
-      color: #ff6b6b;
-      text-decoration: none;
-    }
-    .debug-bar a:hover {
-      text-decoration: underline;
-    }
-    .content-wrapper {
-      padding-top: 50px;
-    }
-  </style>
-</head>
-<body>
-  <div class="debug-bar">
-    <span>📁 <strong>${view}</strong></span>
-    <span>|</span>
-    <span>Engine: <strong>${this.renderService.getActiveEngine().name}</strong></span>
-    <span>|</span>
-    <a href="/__views">← Back to Views</a>
-  </div>
-  <div class="content-wrapper">
-    ${html}
-  </div>
-</body>
+        return `<!DOCTYPE html>
+<html>
+<head>
+  <title>View Preview: ${view}</title>
+  <style>
+    .debug-bar {
+      position: fixed;
+      top: 0;
+      left: 0;
+      right: 0;
+      background: #1a1a2e;
+      color: #eee;
+      padding: 8px 16px;
+      font-family: system-ui, -apple-system, sans-serif;
+      font-size: 13px;
+      z-index: 99999;
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+    }
+    .debug-bar strong {
+      color: #00d9ff;
+    }
+    .debug-bar a {
+      color: #ff6b6b;
+      text-decoration: none;
+    }
+    .debug-bar a:hover {
+      text-decoration: underline;
+    }
+    .content-wrapper {
+      padding-top: 50px;
+    }
+  </style>
+</head>
+<body>
+  <div class="debug-bar">
+    <span>📁 <strong>${view}</strong></span>
+    <span>|</span>
+    <span>Engine: <strong>${this.renderService.getActiveEngine().name}</strong></span>
+    <span>|</span>
+    <a href="/__views">← Back to Views</a>
+  </div>
+  <div class="content-wrapper">
+    ${html}
+  </div>
+</body>
 </html>`;
     }
 }

package/lib/cjs/testing/fluent-request.js

@@ -233,7 +233,13 @@ class FluentRequestImpl {
     }
     /**
      * Execute the request and return the response.
+     *
+     * The generic defaults to `any` (see {@link FluentResponse} for the
+     * rationale) so test code can read `response.body.foo` directly. Pass
+     * an explicit type — `.execute<UserDto>()` — to opt into strict
+     * typing.
      */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async execute() {
         const startTime = Date.now();
         // Build URL with query parameters
@@ -317,6 +323,7 @@ class FluentRequestImpl {
     /**
      * Alias for execute().
      */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     end() {
         return this.execute();
     }

package/lib/cjs/testing/snapshot-request.js

@@ -120,9 +120,11 @@ class SnapshotRequestImpl {
         this.fluentRequest.expect(assertion);
         return this;
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     execute() {
         return this.fluentRequest.execute();
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     end() {
         return this.fluentRequest.end();
     }

package/lib/cjs/types/application/application-factory.d.ts

@@ -112,6 +112,12 @@ export declare class AppFactory {
      *
      * @throws {Error} If webServerType is not a valid constructor
      *
+     * @deprecated Use `bootstrap()` from `@expressots/core` instead. `bootstrap()`
+     * additionally handles environment file loading, port configuration,
+     * graceful shutdown, the startup banner, and configuration validation.
+     * `AppFactory.create()` will keep working for advanced use cases but is
+     * scheduled for removal in a future major release.
+     *
      * @public API
      */
     static create<T extends IWebServer>(webServerType: IWebServerConstructor<T>): Promise<IWebServerBuilder>;