adorn-api 1.0.6 → 1.0.8

package/dist/express.js

@@ -249,7 +249,8 @@ function bootstrap(options) {
         swaggerPath = "/docs",
         swaggerJsonPath = "/docs/openapi.json",
         middleware,
-        auth
+        auth,
+        coerce
       } = options;
       if (controllers.length === 0) {
         reject(new Error("At least one controller must be provided to bootstrap()."));
@@ -269,7 +270,8 @@ function bootstrap(options) {
         controllers,
         artifactsDir: absoluteArtifactsDir,
         middleware,
-        auth
+        auth,
+        coerce
       });
       app.use(router);
       if (enableSwagger) {
@@ -324,6 +326,17 @@ function bootstrap(options) {
 }
 
 // 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;
@@ -350,6 +363,7 @@ async function createExpressRouter(options) {
   const validator = precompiledValidators ? null : createValidator();
   const router = Router();
   const instanceCache = /* @__PURE__ */ new Map();
+  const coerce = normalizeCoerceOptions(options.coerce);
   function getInstance(Ctor) {
     if (!instanceCache.has(Ctor)) {
       instanceCache.set(Ctor, new Ctor());
@@ -412,6 +426,14 @@ async function createExpressRouter(options) {
   }
   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 || {}));
@@ -439,29 +461,50 @@ async function createExpressRouter(options) {
         }
         const args = [];
         if (route.args.body) {
-          args[route.args.body.index] = req.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 coerced = coerceValue(req.params[pathArg.name], pathArg.schemaType);
+          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 firstQueryIndex = route.args.query[0].index;
-          const allSameIndex = route.args.query.every((q) => q.index === firstQueryIndex);
-          if (allSameIndex) {
-            args[firstQueryIndex] = {};
-            for (const q of route.args.query) {
-              const parsed = parseQueryValue(req.query[q.name], q);
-              const coerced = coerceValue(parsed, q.schemaType);
-              args[firstQueryIndex][q.name] = coerced;
-            }
-          } else {
-            for (const q of route.args.query) {
-              const parsed = parseQueryValue(req.query[q.name], q);
-              const coerced = coerceValue(parsed, q.schemaType);
+          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.headers.length > 0) {
           const firstHeaderIndex = route.args.headers[0].index;
@@ -470,12 +513,16 @@ async function createExpressRouter(options) {
             args[firstHeaderIndex] = {};
             for (const h of route.args.headers) {
               const headerValue = req.headers[h.name.toLowerCase()];
-              args[firstHeaderIndex][h.name] = headerValue ?? void 0;
+              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()];
-              args[h.index] = headerValue ?? void 0;
+              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;
             }
           }
         }
@@ -487,13 +534,15 @@ async function createExpressRouter(options) {
             args[firstCookieIndex] = {};
             for (const c of route.args.cookies) {
               const cookieValue = cookies[c.name];
-              const coerced = coerceValue(cookieValue, c.schemaType);
+              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 coerced = coerceValue(cookieValue, c.schemaType);
+              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;
             }
           }
@@ -512,8 +561,53 @@ async function createExpressRouter(options) {
   }
   return router;
 }
+function getDateCoercionOptions(coerce, location) {
+  const enabled = coerce[location];
+  return {
+    dateTime: enabled && coerce.dateTime,
+    date: enabled && coerce.date
+  };
+}
+function toOpenApiPath(path3) {
+  return path3.replace(/:([^/]+)/g, "{$1}");
+}
+function getOpenApiOperation(openapi, route) {
+  const pathKey = toOpenApiPath(route.fullPath);
+  const pathItem = openapi.paths?.[pathKey];
+  if (!pathItem) return null;
+  return pathItem[route.httpMethod.toLowerCase()] ?? null;
+}
+function buildParamSchemaIndex(operation) {
+  const index = /* @__PURE__ */ new Map();
+  const params = operation?.parameters ?? [];
+  for (const param of params) {
+    if (!param?.name || !param?.in) continue;
+    if (param.schema) {
+      index.set(`${param.in}:${param.name}`, param.schema);
+    }
+  }
+  return index;
+}
+function getParamSchemaFromIndex(index, location, name) {
+  return index.get(`${location}:${name}`) ?? null;
+}
+function getRequestBodySchema(operation, contentType) {
+  const content = operation?.requestBody?.content;
+  if (!content) return null;
+  if (contentType && content[contentType]?.schema) {
+    return content[contentType].schema;
+  }
+  const first = Object.values(content)[0];
+  return first?.schema ?? null;
+}
+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) {
@@ -532,14 +626,10 @@ function validateRequestWithPrecompiled(route, req, validators) {
     }
   }
   for (const q of route.args.query) {
-    const value = req.query[q.name];
+    const value = q.serialization?.style === "deepObject" ? deepValues[q.name] : req.query[q.name];
     if (value === void 0) continue;
-    const schema = {};
-    if (q.schemaType) {
-      const type = Array.isArray(q.schemaType) ? q.schemaType[0] : q.schemaType;
-      schema.type = type;
-    }
-    const coerced = coerceValue(value, q.schemaType);
+    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}`,
@@ -552,12 +642,8 @@ function validateRequestWithPrecompiled(route, req, validators) {
   for (const p of route.args.path) {
     const value = req.params[p.name];
     if (value === void 0) continue;
-    const schema = {};
-    if (p.schemaType) {
-      const type = Array.isArray(p.schemaType) ? p.schemaType[0] : p.schemaType;
-      schema.type = type;
-    }
-    const coerced = coerceValue(value, p.schemaType);
+    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}`,
@@ -575,6 +661,10 @@ function validateRequest(route, req, openapi, validator) {
     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);
@@ -594,19 +684,24 @@ function validateRequest(route, req, openapi, validator) {
     }
   }
   for (const q of route.args.query) {
-    const value = req.query[q.name];
-    const schema = {};
-    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 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 = coerceValue(value, q.schemaType);
+    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);
@@ -624,18 +719,23 @@ function validateRequest(route, req, openapi, validator) {
   }
   for (const p of route.args.path) {
     const value = req.params[p.name];
-    const schema = {};
-    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 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 = coerceValue(value, p.schemaType);
+    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);
@@ -653,23 +753,127 @@ function validateRequest(route, req, openapi, validator) {
   }
   return errors.length > 0 ? errors : null;
 }
-function coerceValue(value, schemaType) {
+function resolveSchema(schema, components, seen = /* @__PURE__ */ new Set()) {
+  const ref = schema.$ref;
+  if (typeof ref !== "string" || !ref.startsWith("#/components/schemas/")) {
+    return schema;
+  }
+  const name = ref.replace("#/components/schemas/", "");
+  if (seen.has(name)) return schema;
+  const next = components[name];
+  if (!next) return schema;
+  seen.add(name);
+  return resolveSchema(next, components, seen);
+}
+function coerceDatesWithSchema(value, schema, dateCoercion, components) {
+  if (!schema || !dateCoercion.date && !dateCoercion.dateTime) return value;
+  return coerceWithSchema(value, schema, dateCoercion, components, { coercePrimitives: false });
+}
+function coerceParamValue(value, schema, dateCoercion, components) {
+  if (!schema) return value;
+  return coerceWithSchema(value, schema, dateCoercion, components, { coercePrimitives: true });
+}
+function coerceWithSchema(value, schema, dateCoercion, components, options) {
   if (value === void 0 || value === null) return value;
-  const type = Array.isArray(schemaType) ? schemaType[0] : schemaType;
-  if (type === "number" || type === "integer") {
+  if (value instanceof Date) return value;
+  const resolved = resolveSchema(schema, components);
+  const override = resolved["x-adorn-coerce"];
+  const allowDateTime = override === true ? true : override === false ? false : dateCoercion.dateTime;
+  const allowDate = override === true ? true : override === false ? false : dateCoercion.date;
+  const byFormat = coerceDateString(value, resolved, allowDateTime, allowDate);
+  if (byFormat !== value) return byFormat;
+  const allOf = resolved.allOf;
+  if (Array.isArray(allOf)) {
+    let out = value;
+    for (const entry of allOf) {
+      out = coerceWithSchema(out, entry, { dateTime: allowDateTime, date: allowDate }, components, options);
+    }
+    return out;
+  }
+  const variants = resolved.oneOf ?? resolved.anyOf;
+  if (Array.isArray(variants)) {
+    for (const entry of variants) {
+      const out = coerceWithSchema(value, entry, { dateTime: allowDateTime, date: allowDate }, components, options);
+      if (out !== value) return out;
+    }
+  }
+  const schemaType = resolved.type;
+  const types = Array.isArray(schemaType) ? schemaType : schemaType ? [schemaType] : [];
+  if ((types.includes("array") || resolved.items) && Array.isArray(value)) {
+    const itemSchema = resolved.items ?? {};
+    return value.map((item) => coerceWithSchema(item, itemSchema, { dateTime: allowDateTime, date: allowDate }, components, options));
+  }
+  if ((types.includes("object") || resolved.properties || resolved.additionalProperties) && isPlainObject(value)) {
+    const props = resolved.properties;
+    const out = { ...value };
+    if (props) {
+      for (const [key, propSchema] of Object.entries(props)) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+          out[key] = coerceWithSchema(value[key], propSchema, { dateTime: allowDateTime, date: allowDate }, components, options);
+        }
+      }
+    }
+    const additional = resolved.additionalProperties;
+    if (additional && typeof additional === "object") {
+      for (const [key, entry] of Object.entries(value)) {
+        if (props && Object.prototype.hasOwnProperty.call(props, key)) continue;
+        out[key] = coerceWithSchema(entry, additional, { dateTime: allowDateTime, date: allowDate }, components, options);
+      }
+    }
+    return out;
+  }
+  if (options.coercePrimitives) {
+    return coercePrimitiveValue(value, types);
+  }
+  return value;
+}
+function coerceDateString(value, schema, allowDateTime, allowDate) {
+  if (typeof value !== "string") return value;
+  const format = schema.format;
+  const schemaType = schema.type;
+  const types = Array.isArray(schemaType) ? schemaType : schemaType ? [schemaType] : [];
+  const allowsString = types.length === 0 || types.includes("string");
+  if (format === "date-time" && allowDateTime && allowsString) {
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime())) {
+      throw new Error(`Invalid date-time: ${value}`);
+    }
+    return parsed;
+  }
+  if (format === "date" && allowDate && allowsString) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+      throw new Error(`Invalid date: ${value}`);
+    }
+    const parsed = /* @__PURE__ */ new Date(`${value}T00:00:00.000Z`);
+    if (Number.isNaN(parsed.getTime())) {
+      throw new Error(`Invalid date: ${value}`);
+    }
+    return parsed;
+  }
+  return value;
+}
+function coercePrimitiveValue(value, types) {
+  if (value === void 0 || value === null) return value;
+  if (types.includes("number") || types.includes("integer")) {
     const num = Number(value);
-    if (isNaN(num)) {
+    if (Number.isNaN(num)) {
       throw new Error(`Invalid number: ${value}`);
     }
     return num;
   }
-  if (type === "boolean") {
+  if (types.includes("boolean")) {
     if (value === "true") return true;
     if (value === "false") return false;
+    if (typeof value === "boolean") return value;
     throw new Error(`Invalid boolean: ${value}`);
   }
   return value;
 }
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
 function parseQueryValue(value, param) {
   if (value === void 0 || value === null) return value;
   const isArray = Array.isArray(param.schemaType) ? param.schemaType.includes("array") : param.schemaType === "array";
@@ -693,6 +897,69 @@ function parseQueryValue(value, param) {
   }
   return value;
 }
+function getRawQueryString(req) {
+  const url = req.originalUrl ?? req.url ?? "";
+  const index = url.indexOf("?");
+  if (index === -1) return "";
+  return url.slice(index + 1);
+}
+function parseDeepObjectParams(rawQuery, names) {
+  const out = {};
+  if (!rawQuery || names.size === 0) return out;
+  const params = new URLSearchParams(rawQuery);
+  for (const [key, value] of params.entries()) {
+    const path3 = parseBracketPath(key);
+    if (path3.length === 0) continue;
+    const root = path3[0];
+    if (!names.has(root)) continue;
+    assignDeepValue(out, path3, value);
+  }
+  return out;
+}
+function parseBracketPath(key) {
+  const parts = [];
+  let current = "";
+  for (let i = 0; i < key.length; i++) {
+    const ch = key[i];
+    if (ch === "[") {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    if (ch === "]") {
+      if (current) parts.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (current) parts.push(current);
+  return parts;
+}
+function assignDeepValue(target, path3, value) {
+  let cursor = target;
+  for (let i = 0; i < path3.length; i++) {
+    const key = path3[i];
+    if (!key) continue;
+    const isLast = i === path3.length - 1;
+    if (isLast) {
+      const existing = cursor[key];
+      if (existing === void 0) {
+        cursor[key] = value;
+      } else if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        cursor[key] = [existing, value];
+      }
+      return;
+    }
+    const next = cursor[key];
+    if (!isPlainObject(next)) {
+      cursor[key] = {};
+    }
+    cursor = cursor[key];
+  }
+}
 function parseCookies(cookieHeader) {
   if (!cookieHeader) return {};
   const cookies = {};