adorn-api 1.0.11 → 1.0.13

package/dist/express.cjs

@@ -43,10 +43,9 @@ module.exports = __toCommonJS(express_exports);
 // src/runtime/polyfill.ts
 Symbol.metadata ??= /* @__PURE__ */ Symbol("Symbol.metadata");
 
-// src/adapter/express/index.ts
-var import_express2 = require("express");
-var import_node_fs2 = require("fs");
-var import_node_path3 = require("path");
+// src/adapter/express/router.ts
+var import_express = require("express");
+var import_node_path2 = require("path");
 
 // src/runtime/metadata/key.ts
 var ADORN_META = /* @__PURE__ */ Symbol.for("adorn-api/meta");
@@ -157,8 +156,7 @@ function computeBoundRoutes(controllers, manifest) {
         responses: manifestOp.responses,
         use: routeOp.use,
         auth: routeOp.auth,
-        controllerUse: bucket.controllerUse,
-        paginationConfig: routeOp.pagination
+        controllerUse: bucket.controllerUse
       });
     }
   }
@@ -218,7 +216,7 @@ async function getMtime(filePath) {
 async function loadArtifacts(options) {
   const { outDir } = options;
   const cacheKey = import_node_path.default.resolve(outDir);
-  let entry = artifactCache.get(cacheKey);
+  const entry = artifactCache.get(cacheKey);
   const openapiPath = import_node_path.default.join(outDir, "openapi.json");
   const manifestPath = import_node_path.default.join(outDir, "manifest.json");
   const validatorsPath = import_node_path.default.join(outDir, "validators.mjs");
@@ -267,351 +265,7 @@ async function loadArtifacts(options) {
   };
 }
 
-// src/adapter/express/index.ts
-var import_swagger_ui_express = __toESM(require("swagger-ui-express"), 1);
-
-// src/adapter/express/bootstrap.ts
-var import_express = __toESM(require("express"), 1);
-var import_node_path2 = __toESM(require("path"), 1);
-function bootstrap(options) {
-  return new Promise(async (resolve2, reject) => {
-    try {
-      const {
-        controllers,
-        port: userPort,
-        host: userHost,
-        artifactsDir: userArtifactsDir = ".adorn",
-        enableSwagger = true,
-        swaggerPath = "/docs",
-        swaggerJsonPath = "/docs/openapi.json",
-        middleware,
-        auth,
-        coerce
-      } = options;
-      if (controllers.length === 0) {
-        reject(new Error("At least one controller must be provided to bootstrap()."));
-        return;
-      }
-      const envPort = process.env.PORT;
-      const port = userPort ?? (envPort !== void 0 ? Number(envPort) : 3e3);
-      const host = userHost ?? process.env.HOST ?? "0.0.0.0";
-      if (isNaN(port) || port < 0 || port > 65535) {
-        reject(new Error(`Invalid port: ${port}. Port must be between 0 and 65535.`));
-        return;
-      }
-      const absoluteArtifactsDir = import_node_path2.default.isAbsolute(userArtifactsDir) ? userArtifactsDir : import_node_path2.default.resolve(process.cwd(), userArtifactsDir);
-      const app = (0, import_express.default)();
-      app.use(import_express.default.json());
-      const router = await createExpressRouter({
-        controllers,
-        artifactsDir: absoluteArtifactsDir,
-        middleware,
-        auth,
-        coerce
-      });
-      app.use(router);
-      if (enableSwagger) {
-        const displayHost = host === "0.0.0.0" ? "localhost" : host;
-        const serverUrl = `http://${displayHost}:${port}`;
-        app.use(
-          setupSwagger({
-            artifactsDir: absoluteArtifactsDir,
-            jsonPath: swaggerJsonPath,
-            uiPath: swaggerPath,
-            swaggerOptions: {
-              servers: [{ url: serverUrl }]
-            }
-          })
-        );
-      }
-      const server = app.listen(port, host, () => {
-        const displayHost = host === "0.0.0.0" ? "localhost" : host;
-        const serverUrl = `http://${displayHost}:${port}`;
-        console.log(`\u{1F680} Server running on ${serverUrl}`);
-        if (enableSwagger) {
-          console.log(`\u{1F4DA} Swagger UI: ${serverUrl}${swaggerPath}`);
-        }
-        const result = {
-          server,
-          app,
-          url: serverUrl,
-          port,
-          host,
-          close: () => new Promise((closeResolve) => {
-            server.close(() => {
-              console.log("Server closed gracefully");
-              closeResolve();
-            });
-          })
-        };
-        resolve2(result);
-      });
-      server.on("error", (error) => {
-        if (error.code === "EADDRINUSE") {
-          reject(new Error(`Port ${port} already in use. Please choose a different port.`));
-        } else if (error.code === "EACCES") {
-          reject(new Error(`Permission denied for port ${port}. Ports below 1024 require root privileges.`));
-        } else {
-          reject(new Error(`Failed to start server: ${error.message}`));
-        }
-      });
-    } catch (error) {
-      reject(error);
-    }
-  });
-}
-
-// src/adapter/express/index.ts
-function normalizeCoerceOptions(coerce) {
-  return {
-    body: coerce?.body ?? false,
-    query: coerce?.query ?? false,
-    path: coerce?.path ?? false,
-    header: coerce?.header ?? false,
-    cookie: coerce?.cookie ?? false,
-    dateTime: coerce?.dateTime ?? false,
-    date: coerce?.date ?? false
-  };
-}
-async function createExpressRouter(options) {
-  const { controllers, artifactsDir = ".adorn", middleware = {} } = options;
-  let manifest;
-  let openapi;
-  let precompiledValidators = null;
-  if (options.manifest && options.openapi) {
-    manifest = options.manifest;
-    openapi = options.openapi;
-    if (manifest.validation.mode === "precompiled" && manifest.validation.precompiledModule) {
-      try {
-        const validatorPath = (0, import_node_path3.join)(artifactsDir, manifest.validation.precompiledModule);
-        precompiledValidators = require(validatorPath).validators;
-      } catch (err) {
-        console.warn(`Failed to load precompiled validators: ${err}`);
-      }
-    }
-  } else {
-    const artifacts = await loadArtifacts({ outDir: artifactsDir });
-    manifest = artifacts.manifest;
-    openapi = artifacts.openapi;
-    precompiledValidators = artifacts.validators?.validators ?? null;
-  }
-  const routes = bindRoutes({ controllers, manifest });
-  const validator = precompiledValidators ? null : createValidator();
-  const router = (0, import_express2.Router)();
-  const instanceCache = /* @__PURE__ */ new Map();
-  const coerce = normalizeCoerceOptions(options.coerce);
-  function getInstance(Ctor) {
-    if (!instanceCache.has(Ctor)) {
-      instanceCache.set(Ctor, new Ctor());
-    }
-    return instanceCache.get(Ctor);
-  }
-  function resolveMiddleware(items, named = {}) {
-    return items.map((item) => {
-      if (typeof item === "string") {
-        const fn = named[item];
-        if (!fn) {
-          throw new Error(`Named middleware "${item}" not found in middleware registry`);
-        }
-        return fn;
-      }
-      return item;
-    });
-  }
-  function createAuthMiddleware(authConfig, routeAuth, globalSecurity) {
-    return async (req, res, next) => {
-      const isPublic = routeAuth === "public";
-      const hasAuthDecorator = routeAuth && routeAuth !== "public";
-      const hasGlobalSecurity = globalSecurity && globalSecurity.length > 0;
-      if (!hasAuthDecorator && !hasGlobalSecurity) {
-        return next();
-      }
-      if (isPublic) {
-        return next();
-      }
-      const authMeta = routeAuth;
-      const scheme = authMeta.scheme;
-      const requiredScopes = authMeta.scopes || [];
-      const isOptional = authMeta.optional ?? false;
-      const authRuntime = authConfig.schemes[scheme];
-      if (!authRuntime) {
-        throw new Error(`Auth scheme "${scheme}" not found in auth configuration`);
-      }
-      const result = await authRuntime.authenticate(req);
-      if (!result) {
-        if (isOptional) {
-          req.auth = null;
-          return next();
-        }
-        return authRuntime.challenge(res);
-      }
-      req.auth = result.principal;
-      if (authRuntime.authorize && requiredScopes.length > 0) {
-        if (!authRuntime.authorize(result, requiredScopes)) {
-          res.status(403).json({ error: "Forbidden", message: "Insufficient scopes" });
-          return;
-        }
-      }
-      next();
-    };
-  }
-  function getSchemaByRef(ref) {
-    if (!ref.startsWith("#/components/schemas/")) return null;
-    const schemaName = ref.replace("#/components/schemas/", "");
-    return openapi.components.schemas[schemaName] || null;
-  }
-  for (const route of routes) {
-    const method = route.httpMethod.toLowerCase();
-    const openapiOperation = getOpenApiOperation(openapi, route);
-    const paramSchemaIndex = buildParamSchemaIndex(openapiOperation);
-    const bodySchema = getRequestBodySchema(openapiOperation, route.args.body?.contentType) ?? (route.args.body ? getSchemaByRef(route.args.body.schemaRef) : null);
-    const coerceBodyDates = getDateCoercionOptions(coerce, "body");
-    const coerceQueryDates = getDateCoercionOptions(coerce, "query");
-    const coercePathDates = getDateCoercionOptions(coerce, "path");
-    const coerceHeaderDates = getDateCoercionOptions(coerce, "header");
-    const coerceCookieDates = getDateCoercionOptions(coerce, "cookie");
-    const middlewareChain = [];
-    if (middleware.global) {
-      middlewareChain.push(...resolveMiddleware(middleware.global, middleware.named || {}));
-    }
-    if (route.controllerUse) {
-      middlewareChain.push(...resolveMiddleware(route.controllerUse, middleware.named || {}));
-    }
-    if (route.use) {
-      middlewareChain.push(...resolveMiddleware(route.use, middleware.named || {}));
-    }
-    if (options.auth) {
-      const authMw = createAuthMiddleware(options.auth, route.auth, openapi.security || []);
-      middlewareChain.push(authMw);
-    }
-    router[method](route.fullPath, ...middlewareChain, async (req, res, next) => {
-      try {
-        const validationErrors = precompiledValidators ? validateRequestWithPrecompiled(route, req, precompiledValidators) : validateRequest(route, req, openapi, validator);
-        if (validationErrors) {
-          return res.status(400).json(formatValidationErrors(validationErrors));
-        }
-        const instance = getInstance(route.controllerCtor);
-        const handler = instance[route.methodName];
-        if (typeof handler !== "function") {
-          throw new Error(`Method ${route.methodName} not found on controller`);
-        }
-        const args = [];
-        if (route.args.body) {
-          const coercedBody = (coerceBodyDates.date || coerceBodyDates.dateTime) && bodySchema ? coerceDatesWithSchema(req.body, bodySchema, coerceBodyDates, openapi.components.schemas) : req.body;
-          args[route.args.body.index] = coercedBody;
-        }
-        for (const pathArg of route.args.path) {
-          const rawValue = req.params[pathArg.name];
-          const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "path", pathArg.name) ?? (pathArg.schemaRef ? getSchemaByRef(pathArg.schemaRef) : null) ?? schemaFromType(pathArg.schemaType);
-          const coerced = coerceParamValue(rawValue, paramSchema, coercePathDates, openapi.components.schemas);
-          args[pathArg.index] = coerced;
-        }
-        if (route.args.query.length > 0) {
-          const deepObjectArgs = route.args.query.filter((q) => q.serialization?.style === "deepObject");
-          const standardArgs = route.args.query.filter((q) => q.serialization?.style !== "deepObject");
-          if (deepObjectArgs.length > 0) {
-            const rawQuery = getRawQueryString(req);
-            const names = new Set(deepObjectArgs.map((q) => q.name));
-            const parsedDeep = parseDeepObjectParams(rawQuery, names);
-            for (const q of deepObjectArgs) {
-              const rawValue = parsedDeep[q.name];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(q.schemaRef) : null) ?? schemaFromType(q.schemaType);
-              const baseValue = rawValue === void 0 ? {} : rawValue;
-              const coerced = coerceParamValue(baseValue, paramSchema, coerceQueryDates, openapi.components.schemas);
-              args[q.index] = coerced;
-            }
-          }
-          if (standardArgs.length > 0) {
-            const firstQueryIndex = standardArgs[0].index;
-            const allSameIndex = standardArgs.every((q) => q.index === firstQueryIndex);
-            if (allSameIndex) {
-              args[firstQueryIndex] = {};
-              for (const q of standardArgs) {
-                const parsed = parseQueryValue(req.query[q.name], q);
-                const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(q.schemaRef) : null) ?? schemaFromType(q.schemaType);
-                const coerced = coerceParamValue(parsed, paramSchema, coerceQueryDates, openapi.components.schemas);
-                args[firstQueryIndex][q.name] = coerced;
-              }
-            } else {
-              for (const q of standardArgs) {
-                const parsed = parseQueryValue(req.query[q.name], q);
-                const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(q.schemaRef) : null) ?? schemaFromType(q.schemaType);
-                const coerced = coerceParamValue(parsed, paramSchema, coerceQueryDates, openapi.components.schemas);
-                args[q.index] = coerced;
-              }
-            }
-          }
-        }
-        if (route.args.paginationParamIndex !== null) {
-          const pageStr = req.query.page;
-          const pageSizeStr = req.query.pageSize;
-          const defaultPageSize = route.paginationConfig?.defaultPageSize ?? 10;
-          const page = pageStr ? parseInt(pageStr, 10) : 1;
-          const pageSize = pageSizeStr ? parseInt(pageSizeStr, 10) : defaultPageSize;
-          args[route.args.paginationParamIndex] = { page, pageSize };
-        }
-        if (route.args.headers.length > 0) {
-          const firstHeaderIndex = route.args.headers[0].index;
-          const allSameIndex = route.args.headers.every((h) => h.index === firstHeaderIndex);
-          if (allSameIndex) {
-            args[firstHeaderIndex] = {};
-            for (const h of route.args.headers) {
-              const headerValue = req.headers[h.name.toLowerCase()];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "header", h.name) ?? (h.schemaRef ? getSchemaByRef(h.schemaRef) : null) ?? schemaFromType(h.schemaType);
-              const coerced = coerceParamValue(headerValue, paramSchema, coerceHeaderDates, openapi.components.schemas);
-              args[firstHeaderIndex][h.name] = coerced ?? void 0;
-            }
-          } else {
-            for (const h of route.args.headers) {
-              const headerValue = req.headers[h.name.toLowerCase()];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "header", h.name) ?? (h.schemaRef ? getSchemaByRef(h.schemaRef) : null) ?? schemaFromType(h.schemaType);
-              const coerced = coerceParamValue(headerValue, paramSchema, coerceHeaderDates, openapi.components.schemas);
-              args[h.index] = coerced ?? void 0;
-            }
-          }
-        }
-        if (route.args.cookies.length > 0) {
-          const firstCookieIndex = route.args.cookies[0].index;
-          const allSameIndex = route.args.cookies.every((c) => c.index === firstCookieIndex);
-          const cookies = parseCookies(req.headers.cookie);
-          if (allSameIndex) {
-            args[firstCookieIndex] = {};
-            for (const c of route.args.cookies) {
-              const cookieValue = cookies[c.name];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "cookie", c.name) ?? (c.schemaRef ? getSchemaByRef(c.schemaRef) : null) ?? schemaFromType(c.schemaType);
-              const coerced = coerceParamValue(cookieValue, paramSchema, coerceCookieDates, openapi.components.schemas);
-              args[firstCookieIndex][c.name] = coerced;
-            }
-          } else {
-            for (const c of route.args.cookies) {
-              const cookieValue = cookies[c.name];
-              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "cookie", c.name) ?? (c.schemaRef ? getSchemaByRef(c.schemaRef) : null) ?? schemaFromType(c.schemaType);
-              const coerced = coerceParamValue(cookieValue, paramSchema, coerceCookieDates, openapi.components.schemas);
-              args[c.index] = coerced;
-            }
-          }
-        }
-        if (args.length === 0) {
-          args.push(req);
-        }
-        const result = await handler.apply(instance, args);
-        const primaryResponse = route.responses[0];
-        const status = primaryResponse?.status ?? 200;
-        res.status(status).json(result);
-      } catch (error) {
-        next(error);
-      }
-    });
-  }
-  return router;
-}
-function getDateCoercionOptions(coerce, location) {
-  const enabled = coerce[location];
-  return {
-    dateTime: enabled && coerce.dateTime,
-    date: enabled && coerce.date
-  };
-}
+// src/adapter/express/openapi.ts
 function toOpenApiPath(path3) {
   return path3.replace(/:([^/]+)/g, "{$1}");
 }
@@ -621,7 +275,7 @@ function getOpenApiOperation(openapi, route) {
   if (!pathItem) return null;
   return pathItem[route.httpMethod.toLowerCase()] ?? null;
 }
-function buildParamSchemaIndex(operation) {
+function getParamSchemaIndex(operation) {
   const index = /* @__PURE__ */ new Map();
   const params = operation?.parameters ?? [];
   for (const param of params) {
@@ -648,155 +302,6 @@ function schemaFromType(schemaType) {
   if (!schemaType) return null;
   return { type: schemaType };
 }
-function validateRequestWithPrecompiled(route, req, validators) {
-  const errors = [];
-  const deepNames = new Set(route.args.query.filter((q) => q.serialization?.style === "deepObject").map((q) => q.name));
-  const deepValues = deepNames.size > 0 ? parseDeepObjectParams(getRawQueryString(req), deepNames) : {};
-  if (route.args.body) {
-    const validator = validators[route.operationId]?.body;
-    if (validator) {
-      const valid = validator(req.body);
-      if (!valid) {
-        const v = validators[route.operationId].body;
-        for (const err of v.errors || []) {
-          errors.push({
-            path: `#/body${err.instancePath}`,
-            message: err.message || "Invalid value",
-            keyword: err.keyword,
-            params: err.params
-          });
-        }
-      }
-    }
-  }
-  for (const q of route.args.query) {
-    const value = q.serialization?.style === "deepObject" ? deepValues[q.name] : req.query[q.name];
-    if (value === void 0) continue;
-    const schema = schemaFromType(q.schemaType) ?? {};
-    const coerced = coerceParamValue(value, schema, { dateTime: false, date: false }, {});
-    if (Object.keys(schema).length > 0 && coerced !== void 0) {
-      errors.push({
-        path: `#/query/${q.name}`,
-        message: `Schema validation not supported for query params in precompiled mode`,
-        keyword: "notSupported",
-        params: {}
-      });
-    }
-  }
-  for (const p of route.args.path) {
-    const value = req.params[p.name];
-    if (value === void 0) continue;
-    const schema = schemaFromType(p.schemaType) ?? {};
-    const coerced = coerceParamValue(value, schema, { dateTime: false, date: false }, {});
-    if (Object.keys(schema).length > 0 && coerced !== void 0) {
-      errors.push({
-        path: `#/path/${p.name}`,
-        message: `Schema validation not supported for path params in precompiled mode`,
-        keyword: "notSupported",
-        params: {}
-      });
-    }
-  }
-  return errors.length > 0 ? errors : null;
-}
-function validateRequest(route, req, openapi, validator) {
-  function getSchemaByRef(ref) {
-    if (!ref.startsWith("#/components/schemas/")) return null;
-    const schemaName = ref.replace("#/components/schemas/", "");
-    return openapi.components.schemas[schemaName] || null;
-  }
-  const openapiOperation = getOpenApiOperation(openapi, route);
-  const paramSchemaIndex = buildParamSchemaIndex(openapiOperation);
-  const deepNames = new Set(route.args.query.filter((q) => q.serialization?.style === "deepObject").map((q) => q.name));
-  const deepValues = deepNames.size > 0 ? parseDeepObjectParams(getRawQueryString(req), deepNames) : {};
-  const errors = [];
-  if (route.args.body) {
-    const bodySchema = getSchemaByRef(route.args.body.schemaRef);
-    if (bodySchema) {
-      const validate = validator.compile(bodySchema);
-      const valid = validate(req.body);
-      if (!valid) {
-        for (const err of validate.errors || []) {
-          errors.push({
-            path: `#/body${err.instancePath}`,
-            message: err.message || "Invalid value",
-            keyword: err.keyword,
-            params: err.params
-          });
-        }
-      }
-    }
-  }
-  for (const q of route.args.query) {
-    const value = q.serialization?.style === "deepObject" ? deepValues[q.name] : req.query[q.name];
-    const openapiSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name);
-    let schema = {};
-    if (openapiSchema) {
-      schema = resolveSchema(openapiSchema, openapi.components.schemas);
-    } else {
-      if (q.schemaType) {
-        const type = Array.isArray(q.schemaType) ? q.schemaType[0] : q.schemaType;
-        schema.type = type;
-      }
-      if (q.schemaRef && q.schemaRef.includes("Inline")) {
-        const inlineSchema = getSchemaByRef(q.schemaRef);
-        if (inlineSchema) {
-          Object.assign(schema, inlineSchema);
-        }
-      }
-    }
-    const coerced = coerceParamValue(value, schema, { dateTime: false, date: false }, openapi.components.schemas);
-    if (Object.keys(schema).length > 0 && coerced !== void 0) {
-      const validate = validator.compile(schema);
-      const valid = validate(coerced);
-      if (!valid) {
-        for (const err of validate.errors || []) {
-          errors.push({
-            path: `#/query/${q.name}`,
-            message: err.message || "Invalid value",
-            keyword: err.keyword,
-            params: err.params
-          });
-        }
-      }
-    }
-  }
-  for (const p of route.args.path) {
-    const value = req.params[p.name];
-    const openapiSchema = getParamSchemaFromIndex(paramSchemaIndex, "path", p.name);
-    let schema = {};
-    if (openapiSchema) {
-      schema = resolveSchema(openapiSchema, openapi.components.schemas);
-    } else {
-      if (p.schemaType) {
-        const type = Array.isArray(p.schemaType) ? p.schemaType[0] : p.schemaType;
-        schema.type = type;
-      }
-      if (p.schemaRef && p.schemaRef.includes("Inline")) {
-        const inlineSchema = getSchemaByRef(p.schemaRef);
-        if (inlineSchema) {
-          Object.assign(schema, inlineSchema);
-        }
-      }
-    }
-    const coerced = coerceParamValue(value, schema, { dateTime: false, date: false }, openapi.components.schemas);
-    if (Object.keys(schema).length > 0 && coerced !== void 0) {
-      const validate = validator.compile(schema);
-      const valid = validate(coerced);
-      if (!valid) {
-        for (const err of validate.errors || []) {
-          errors.push({
-            path: `#/path/${p.name}`,
-            message: err.message || "Invalid value",
-            keyword: err.keyword,
-            params: err.params
-          });
-        }
-      }
-    }
-  }
-  return errors.length > 0 ? errors : null;
-}
 function resolveSchema(schema, components, seen = /* @__PURE__ */ new Set()) {
   const ref = schema.$ref;
   if (typeof ref !== "string" || !ref.startsWith("#/components/schemas/")) {
@@ -809,6 +314,31 @@ function resolveSchema(schema, components, seen = /* @__PURE__ */ new Set()) {
   seen.add(name);
   return resolveSchema(next, components, seen);
 }
+function getSchemaByRef(openapi, ref) {
+  if (!ref.startsWith("#/components/schemas/")) return null;
+  const schemaName = ref.replace("#/components/schemas/", "");
+  return openapi.components.schemas[schemaName] || null;
+}
+
+// src/adapter/express/coercion.ts
+function normalizeCoerceOptions(coerce) {
+  return {
+    body: coerce?.body ?? false,
+    query: coerce?.query ?? false,
+    path: coerce?.path ?? false,
+    header: coerce?.header ?? false,
+    cookie: coerce?.cookie ?? false,
+    dateTime: coerce?.dateTime ?? false,
+    date: coerce?.date ?? false
+  };
+}
+function getDateCoercionOptions(coerce, location) {
+  const enabled = coerce[location];
+  return {
+    dateTime: enabled && coerce.dateTime,
+    date: enabled && coerce.date
+  };
+}
 function coerceDatesWithSchema(value, schema, dateCoercion, components) {
   if (!schema || !dateCoercion.date && !dateCoercion.dateTime) return value;
   return coerceWithSchema(value, schema, dateCoercion, components, { coercePrimitives: false });
@@ -1016,6 +546,408 @@ function parseCookies(cookieHeader) {
   }
   return cookies;
 }
+function normalizeSort(sort) {
+  if (Array.isArray(sort)) {
+    return sort.map((s) => String(s));
+  }
+  if (typeof sort === "string") {
+    return sort.split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+// src/adapter/express/auth.ts
+function createAuthMiddleware(authConfig, routeAuth, globalSecurity) {
+  return async (req, res, next) => {
+    const isPublic = routeAuth === "public";
+    const hasAuthDecorator = routeAuth && routeAuth !== "public";
+    const hasGlobalSecurity = globalSecurity && globalSecurity.length > 0;
+    if (!hasAuthDecorator && !hasGlobalSecurity) {
+      return next();
+    }
+    if (isPublic) {
+      return next();
+    }
+    const authMeta = routeAuth;
+    const scheme = authMeta.scheme;
+    const requiredScopes = authMeta.scopes || [];
+    const isOptional = authMeta.optional ?? false;
+    const authRuntime = authConfig.schemes[scheme];
+    if (!authRuntime) {
+      throw new Error(`Auth scheme "${scheme}" not found in auth configuration`);
+    }
+    const result = await authRuntime.authenticate(req);
+    if (!result) {
+      if (isOptional) {
+        req.auth = null;
+        return next();
+      }
+      return authRuntime.challenge(res);
+    }
+    req.auth = result.principal;
+    if (authRuntime.authorize && requiredScopes.length > 0) {
+      if (!authRuntime.authorize(result, requiredScopes)) {
+        res.status(403).json({ error: "Forbidden", message: "Insufficient scopes" });
+        return;
+      }
+    }
+    next();
+  };
+}
+
+// src/adapter/express/validation.ts
+function validateRequestWithPrecompiled(route, req, validators) {
+  const errors = [];
+  const deepNames = new Set(route.args.query.filter((q) => q.serialization?.style === "deepObject").map((q) => q.name));
+  const deepValues = deepNames.size > 0 ? parseDeepObjectParams(getRawQueryString(req), deepNames) : {};
+  if (route.args.body) {
+    const validator = validators[route.operationId]?.body;
+    if (validator) {
+      const valid = validator(req.body);
+      if (!valid) {
+        const v = validators[route.operationId].body;
+        for (const err of v.errors || []) {
+          errors.push({
+            path: `#/body${err.instancePath}`,
+            message: err.message || "Invalid value",
+            keyword: err.keyword,
+            params: err.params
+          });
+        }
+      }
+    }
+  }
+  for (const q of route.args.query) {
+    let value = q.serialization?.style === "deepObject" ? deepValues[q.name] : req.query[q.name];
+    if (q.content === "application/json" && typeof value === "string") {
+      try {
+        value = JSON.parse(value);
+      } catch {
+        errors.push({
+          path: `#/query/${q.name}`,
+          message: "Invalid JSON string",
+          keyword: "json",
+          params: {}
+        });
+        continue;
+      }
+    }
+  }
+  return errors.length > 0 ? errors : null;
+}
+function validateRequest(route, req, openapi, validator) {
+  const openapiOperation = getOpenApiOperation(openapi, route);
+  const paramSchemaIndex = getParamSchemaIndex(openapiOperation);
+  const deepNames = new Set(route.args.query.filter((q) => q.serialization?.style === "deepObject").map((q) => q.name));
+  const deepValues = deepNames.size > 0 ? parseDeepObjectParams(getRawQueryString(req), deepNames) : {};
+  const errors = [];
+  if (route.args.body) {
+    const bodySchema = getSchemaByRef(openapi, route.args.body.schemaRef);
+    if (bodySchema) {
+      const validate = validator.compile(bodySchema);
+      const valid = validate(req.body);
+      if (!valid) {
+        for (const err of validate.errors || []) {
+          errors.push({
+            path: `#/body${err.instancePath}`,
+            message: err.message || "Invalid value",
+            keyword: err.keyword,
+            params: err.params
+          });
+        }
+      }
+    }
+  }
+  for (const q of route.args.query) {
+    let value = q.serialization?.style === "deepObject" ? deepValues[q.name] : req.query[q.name];
+    if (q.content === "application/json" && typeof value === "string") {
+      try {
+        value = JSON.parse(value);
+      } catch {
+        errors.push({
+          path: `#/query/${q.name}`,
+          message: "Invalid JSON string",
+          keyword: "json",
+          params: {}
+        });
+        continue;
+      }
+    }
+    const openapiSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name);
+    let schema = {};
+    if (openapiSchema) {
+      schema = resolveSchema(openapiSchema, openapi.components.schemas);
+    } else {
+      if (q.schemaType) {
+        const type = Array.isArray(q.schemaType) ? q.schemaType[0] : q.schemaType;
+        schema.type = type;
+      }
+      if (q.schemaRef && q.schemaRef.includes("Inline")) {
+        const inlineSchema = getSchemaByRef(openapi, q.schemaRef);
+        if (inlineSchema) {
+          Object.assign(schema, inlineSchema);
+        }
+      }
+    }
+    const coerced = coerceParamValue(value, schema, { dateTime: false, date: false }, openapi.components.schemas);
+    if (Object.keys(schema).length > 0 && coerced !== void 0) {
+      const validate = validator.compile(schema);
+      const valid = validate(coerced);
+      if (!valid) {
+        for (const err of validate.errors || []) {
+          errors.push({
+            path: `#/query/${q.name}`,
+            message: err.message || "Invalid value",
+            keyword: err.keyword,
+            params: err.params
+          });
+        }
+      }
+    }
+  }
+  for (const p of route.args.path) {
+    const value = req.params[p.name];
+    const openapiSchema = getParamSchemaFromIndex(paramSchemaIndex, "path", p.name);
+    let schema = {};
+    if (openapiSchema) {
+      schema = resolveSchema(openapiSchema, openapi.components.schemas);
+    } else {
+      if (p.schemaType) {
+        const type = Array.isArray(p.schemaType) ? p.schemaType[0] : p.schemaType;
+        schema.type = type;
+      }
+      if (p.schemaRef && p.schemaRef.includes("Inline")) {
+        const inlineSchema = getSchemaByRef(openapi, p.schemaRef);
+        if (inlineSchema) {
+          Object.assign(schema, inlineSchema);
+        }
+      }
+    }
+    const coerced = coerceParamValue(value, schema, { dateTime: false, date: false }, openapi.components.schemas);
+    if (Object.keys(schema).length > 0 && coerced !== void 0) {
+      const validate = validator.compile(schema);
+      const valid = validate(coerced);
+      if (!valid) {
+        for (const err of validate.errors || []) {
+          errors.push({
+            path: `#/path/${p.name}`,
+            message: err.message || "Invalid value",
+            keyword: err.keyword,
+            params: err.params
+          });
+        }
+      }
+    }
+  }
+  return errors.length > 0 ? errors : null;
+}
+
+// src/adapter/express/router.ts
+async function createExpressRouter(options) {
+  const { controllers, artifactsDir = ".adorn", middleware = {}, defaultPageSize = 10 } = options;
+  let manifest;
+  let openapi;
+  let precompiledValidators = null;
+  if (options.manifest && options.openapi) {
+    manifest = options.manifest;
+    openapi = options.openapi;
+    if (manifest.validation.mode === "precompiled" && manifest.validation.precompiledModule) {
+      try {
+        const validatorPath = (0, import_node_path2.join)(artifactsDir, manifest.validation.precompiledModule);
+        precompiledValidators = require(validatorPath).validators;
+      } catch (err) {
+        console.warn(`Failed to load precompiled validators: ${err}`);
+      }
+    }
+  } else {
+    const artifacts = await loadArtifacts({ outDir: artifactsDir });
+    manifest = artifacts.manifest;
+    openapi = artifacts.openapi;
+    precompiledValidators = artifacts.validators?.validators ?? null;
+  }
+  const routes = bindRoutes({ controllers, manifest });
+  const validator = precompiledValidators ? null : createValidator();
+  const router = (0, import_express.Router)();
+  const instanceCache = /* @__PURE__ */ new Map();
+  const coerce = normalizeCoerceOptions(options.coerce);
+  function getInstance(Ctor) {
+    if (!instanceCache.has(Ctor)) {
+      instanceCache.set(Ctor, new Ctor());
+    }
+    return instanceCache.get(Ctor);
+  }
+  function resolveMiddleware(items, named = {}) {
+    return items.map((item) => {
+      if (typeof item === "string") {
+        const fn = named[item];
+        if (!fn) {
+          throw new Error(`Named middleware "${item}" not found in middleware registry`);
+        }
+        return fn;
+      }
+      return item;
+    });
+  }
+  for (const route of routes) {
+    const method = route.httpMethod.toLowerCase();
+    const openapiOperation = getOpenApiOperation(openapi, route);
+    const paramSchemaIndex = getParamSchemaIndex(openapiOperation);
+    const bodySchema = getRequestBodySchema(openapiOperation, route.args.body?.contentType) ?? (route.args.body ? getSchemaByRef(openapi, route.args.body.schemaRef) : null);
+    const coerceBodyDates = getDateCoercionOptions(coerce, "body");
+    const coerceQueryDates = getDateCoercionOptions(coerce, "query");
+    const coercePathDates = getDateCoercionOptions(coerce, "path");
+    const coerceHeaderDates = getDateCoercionOptions(coerce, "header");
+    const coerceCookieDates = getDateCoercionOptions(coerce, "cookie");
+    const middlewareChain = [];
+    if (middleware.global) {
+      middlewareChain.push(...resolveMiddleware(middleware.global, middleware.named || {}));
+    }
+    if (route.controllerUse) {
+      middlewareChain.push(...resolveMiddleware(route.controllerUse, middleware.named || {}));
+    }
+    if (route.use) {
+      middlewareChain.push(...resolveMiddleware(route.use, middleware.named || {}));
+    }
+    if (options.auth) {
+      const authMw = createAuthMiddleware(options.auth, route.auth, openapi.security || []);
+      middlewareChain.push(authMw);
+    }
+    router[method](route.fullPath, ...middlewareChain, async (req, res, next) => {
+      try {
+        const validationErrors = precompiledValidators ? validateRequestWithPrecompiled(route, req, precompiledValidators) : validateRequest(route, req, openapi, validator);
+        if (validationErrors) {
+          return res.status(400).json(formatValidationErrors(validationErrors));
+        }
+        const instance = getInstance(route.controllerCtor);
+        const handler = instance[route.methodName];
+        if (typeof handler !== "function") {
+          throw new Error(`Method ${route.methodName} not found on controller`);
+        }
+        const args = [];
+        if (route.args.body) {
+          const coercedBody = (coerceBodyDates.date || coerceBodyDates.dateTime) && bodySchema ? coerceDatesWithSchema(req.body, bodySchema, coerceBodyDates, openapi.components.schemas) : req.body;
+          args[route.args.body.index] = coercedBody;
+        }
+        for (const pathArg of route.args.path) {
+          const rawValue = req.params[pathArg.name];
+          const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "path", pathArg.name) ?? (pathArg.schemaRef ? getSchemaByRef(openapi, pathArg.schemaRef) : null) ?? schemaFromType(pathArg.schemaType);
+          const coerced = coerceParamValue(rawValue, paramSchema, coercePathDates, openapi.components.schemas);
+          args[pathArg.index] = coerced;
+        }
+        if (route.args.query.length > 0) {
+          const jsonArgs = route.args.query.filter((q) => q.content === "application/json");
+          const standardArgs = route.args.query.filter((q) => q.content !== "application/json");
+          const queryArgIndex = standardArgs[0]?.index;
+          if (queryArgIndex !== void 0) {
+            args[queryArgIndex] = {};
+          }
+          if (jsonArgs.length > 0) {
+            for (const q of jsonArgs) {
+              const rawValue = req.query[q.name];
+              if (rawValue === void 0 || rawValue === null) continue;
+              let parsed = rawValue;
+              if (typeof rawValue === "string" && rawValue.length > 0) {
+                try {
+                  parsed = JSON.parse(rawValue);
+                } catch {
+                  parsed = rawValue;
+                }
+              }
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(openapi, q.schemaRef) : null) ?? schemaFromType(q.schemaType);
+              const coerced = coerceParamValue(parsed, paramSchema, coerceQueryDates, openapi.components.schemas);
+              if (!args[q.index] || typeof args[q.index] !== "object") {
+                args[q.index] = {};
+              }
+              Object.assign(args[q.index], coerced);
+            }
+          }
+          if (standardArgs.length > 0) {
+            for (const q of standardArgs) {
+              const rawValue = req.query[q.name];
+              if (rawValue === void 0) continue;
+              const parsed = parseQueryValue(rawValue, q);
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "query", q.name) ?? (q.schemaRef ? getSchemaByRef(openapi, q.schemaRef) : null) ?? schemaFromType(q.schemaType);
+              const coerced = coerceParamValue(parsed, paramSchema, coerceQueryDates, openapi.components.schemas);
+              if (!args[q.index] || typeof args[q.index] !== "object") {
+                args[q.index] = {};
+              }
+              args[q.index][q.name] = coerced;
+            }
+          }
+          if (queryArgIndex !== void 0 && args[queryArgIndex]) {
+            const queryObj = args[queryArgIndex];
+            if (queryObj.page === void 0) {
+              queryObj.page = 1;
+            }
+            if (queryObj.pageSize === void 0) {
+              queryObj.pageSize = defaultPageSize;
+            }
+            if (queryObj.sort) {
+              queryObj.sort = normalizeSort(queryObj.sort);
+            }
+          }
+        }
+        if (route.args.headers.length > 0) {
+          const firstHeaderIndex = route.args.headers[0].index;
+          const allSameIndex = route.args.headers.every((h) => h.index === firstHeaderIndex);
+          if (allSameIndex) {
+            args[firstHeaderIndex] = {};
+            for (const h of route.args.headers) {
+              const headerValue = req.headers[h.name.toLowerCase()];
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "header", h.name) ?? (h.schemaRef ? getSchemaByRef(openapi, h.schemaRef) : null) ?? schemaFromType(h.schemaType);
+              const coerced = coerceParamValue(headerValue, paramSchema, coerceHeaderDates, openapi.components.schemas);
+              args[firstHeaderIndex][h.name] = coerced ?? void 0;
+            }
+          } else {
+            for (const h of route.args.headers) {
+              const headerValue = req.headers[h.name.toLowerCase()];
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "header", h.name) ?? (h.schemaRef ? getSchemaByRef(openapi, h.schemaRef) : null) ?? schemaFromType(h.schemaType);
+              const coerced = coerceParamValue(headerValue, paramSchema, coerceHeaderDates, openapi.components.schemas);
+              args[h.index] = coerced ?? void 0;
+            }
+          }
+        }
+        if (route.args.cookies.length > 0) {
+          const firstCookieIndex = route.args.cookies[0].index;
+          const allSameIndex = route.args.cookies.every((c) => c.index === firstCookieIndex);
+          const cookies = parseCookies(req.headers.cookie);
+          if (allSameIndex) {
+            args[firstCookieIndex] = {};
+            for (const c of route.args.cookies) {
+              const cookieValue = cookies[c.name];
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "cookie", c.name) ?? (c.schemaRef ? getSchemaByRef(openapi, c.name) : null) ?? schemaFromType(c.schemaType);
+              const coerced = coerceParamValue(cookieValue, paramSchema, coerceCookieDates, openapi.components.schemas);
+              args[firstCookieIndex][c.name] = coerced;
+            }
+          } else {
+            for (const c of route.args.cookies) {
+              const cookieValue = cookies[c.name];
+              const paramSchema = getParamSchemaFromIndex(paramSchemaIndex, "cookie", c.name) ?? (c.schemaRef ? getSchemaByRef(openapi, c.name) : null) ?? schemaFromType(c.schemaType);
+              const coerced = coerceParamValue(cookieValue, paramSchema, coerceCookieDates, openapi.components.schemas);
+              args[c.index] = coerced;
+            }
+          }
+        }
+        if (args.length === 0) {
+          args.push(req);
+        }
+        const result = await handler.apply(instance, args);
+        const primaryResponse = route.responses[0];
+        const status = primaryResponse?.status ?? 200;
+        res.status(status).json(result);
+      } catch (error) {
+        next(error);
+      }
+    });
+  }
+  return router;
+}
+
+// src/adapter/express/swagger.ts
+var import_express2 = require("express");
+var import_node_fs2 = require("fs");
+var import_node_path3 = require("path");
+var import_swagger_ui_express = __toESM(require("swagger-ui-express"), 1);
 function setupSwagger(options = {}) {
   const {
     artifactsDir = ".adorn",
@@ -1038,6 +970,94 @@ function setupSwagger(options = {}) {
   }));
   return router;
 }
+
+// src/adapter/express/bootstrap.ts
+var import_express3 = __toESM(require("express"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
+function bootstrap(options) {
+  return new Promise((resolve2, reject) => {
+    const {
+      controllers,
+      port: userPort,
+      host: userHost,
+      artifactsDir: userArtifactsDir = ".adorn",
+      enableSwagger = true,
+      swaggerPath = "/docs",
+      swaggerJsonPath = "/docs/openapi.json",
+      middleware,
+      auth,
+      coerce
+    } = options;
+    if (controllers.length === 0) {
+      reject(new Error("At least one controller must be provided to bootstrap()."));
+      return;
+    }
+    const envPort = process.env.PORT;
+    const port = userPort ?? (envPort !== void 0 ? Number(envPort) : 3e3);
+    const host = userHost ?? process.env.HOST ?? "0.0.0.0";
+    if (isNaN(port) || port < 0 || port > 65535) {
+      reject(new Error(`Invalid port: ${port}. Port must be between 0 and 65535.`));
+      return;
+    }
+    const absoluteArtifactsDir = import_node_path4.default.isAbsolute(userArtifactsDir) ? userArtifactsDir : import_node_path4.default.resolve(process.cwd(), userArtifactsDir);
+    const app = (0, import_express3.default)();
+    app.use(import_express3.default.json());
+    createExpressRouter({
+      controllers,
+      artifactsDir: absoluteArtifactsDir,
+      middleware,
+      auth,
+      coerce
+    }).then((router) => {
+      app.use(router);
+      if (enableSwagger) {
+        const displayHost = host === "0.0.0.0" ? "localhost" : host;
+        const serverUrl = `http://${displayHost}:${port}`;
+        app.use(
+          setupSwagger({
+            artifactsDir: absoluteArtifactsDir,
+            jsonPath: swaggerJsonPath,
+            uiPath: swaggerPath,
+            swaggerOptions: {
+              servers: [{ url: serverUrl }]
+            }
+          })
+        );
+      }
+      const server = app.listen(port, host, () => {
+        const displayHost = host === "0.0.0.0" ? "localhost" : host;
+        const serverUrl = `http://${displayHost}:${port}`;
+        console.log(`\u{1F680} Server running on ${serverUrl}`);
+        if (enableSwagger) {
+          console.log(`\u{1F4DA} Swagger UI: ${serverUrl}${swaggerPath}`);
+        }
+        const result = {
+          server,
+          app,
+          url: serverUrl,
+          port,
+          host,
+          close: () => new Promise((closeResolve) => {
+            server.close(() => {
+              console.log("Server closed gracefully");
+              closeResolve();
+            });
+          })
+        };
+        resolve2(result);
+      });
+      server.on("error", (error) => {
+        if (error.code === "EADDRINUSE") {
+          reject(new Error(`Port ${port} already in use. Please choose a different port.`));
+        } else if (error.code === "EACCES") {
+          reject(new Error(`Permission denied for port ${port}. Ports below 1024 require root privileges.`));
+        } else {
+          reject(new Error(`Failed to start server: ${error.message}`));
+        }
+      });
+    }).catch(reject);
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ValidationErrorResponse,