@web-ts-toolkit/access-router 0.4.0 → 0.5.0

package/index.mjs

@@ -1,16 +1,16 @@
 // src/index.ts
-import { isPlainObject as isPlainObject11, isString as isString12, isUndefined as isUndefined4 } from "@web-ts-toolkit/utils";
+import { isPlainObject as isPlainObject14, isString as isString12, isUndefined as isUndefined4 } from "@web-ts-toolkit/utils";
 
 // src/middleware.ts
 import JsonRouter2 from "@web-ts-toolkit/express-json-router";
-import { isArray as isArray9, isFunction as isFunction6, isPlainObject as isPlainObject8, isString as isString7 } from "@web-ts-toolkit/utils";
+import { isArray as isArray10, isFunction as isFunction6, isPlainObject as isPlainObject11, isString as isString7 } from "@web-ts-toolkit/utils";
 
 // src/core.ts
 import {
   castArray as castArray5,
   compact as compact3,
-  forEach as forEach6,
-  isArray as isArray8,
+  forEach as forEach7,
+  isArray as isArray9,
   isBoolean as isBoolean5,
   isFunction as isFunction5,
   isString as isString6,
@@ -25,11 +25,11 @@ import {
   addLeadingSlash,
   forEach as forEach2,
   get as get3,
-  isArray as isArray3,
+  isArray as isArray4,
   isBoolean,
   isFunction,
   isNil as isNil2,
-  isPlainObject as isPlainObject5,
+  isPlainObject as isPlainObject7,
   isString as isString4,
   keys
 } from "@web-ts-toolkit/utils";
@@ -51,20 +51,11 @@ var findElementById = (collection, id) => {
 };
 
 // src/helpers/document.ts
-import { get, isArray, isPlainObject as isPlainObject3, isPromise, isString as isString2, pick, set } from "@web-ts-toolkit/utils";
-
-// src/lib.ts
-import { Document, Schema } from "mongoose";
-import { isPlainObject } from "@web-ts-toolkit/utils";
-var isSchema = (val) => val instanceof Schema;
-var isObjectIdType = (val) => val === "ObjectId" || val === Schema.Types.ObjectId;
-var isReference = (val) => isPlainObject(val) && !!val.ref && isObjectIdType(val.type);
-var isDocument = function isDocument2(doc) {
-  return doc instanceof Document;
-};
+import { Document } from "mongoose";
+import { get, isPlainObject as isPlainObject2, pick, set } from "@web-ts-toolkit/utils";
 
 // src/helpers/query.ts
-import { flattenDeep, isNaN, isNil, isPlainObject as isPlainObject2, isString, reduce } from "@web-ts-toolkit/utils";
+import { flattenDeep, isNaN, isNil, isPlainObject, isString, reduce } from "@web-ts-toolkit/utils";
 function genPagination({
   skip,
   limit,
@@ -92,7 +83,7 @@ function parseSortString(sortString) {
 }
 function normalizeSelect(select) {
   if (Array.isArray(select)) return flattenDeep(select.map(normalizeSelect));
-  if (isPlainObject2(select)) {
+  if (isPlainObject(select)) {
     return reduce(
       select,
       (ret, val, key) => {
@@ -108,17 +99,21 @@ function normalizeSelect(select) {
 }
 
 // src/helpers/document.ts
-function getDocValue(doc, path, defalutValue) {
+import { isArray, isPromise, isString as isString2 } from "@web-ts-toolkit/utils";
+function isDocument(doc) {
+  return doc instanceof Document;
+}
+function getDocValue(doc, path, defaultValue) {
   if (isDocument(doc)) {
-    return get(doc._doc, path, defalutValue);
-  } else if (isPlainObject3(doc)) {
-    return get(doc, path, defalutValue);
+    return get(doc._doc, path, defaultValue);
+  } else if (isPlainObject2(doc)) {
+    return get(doc, path, defaultValue);
   }
 }
 function setDocValue(doc, path, value) {
   if (isDocument(doc)) {
     set(doc._doc, path, value);
-  } else if (isPlainObject3(doc)) {
+  } else if (isPlainObject2(doc)) {
     set(doc, path, value);
   }
 }
@@ -207,16 +202,19 @@ function handleResultError(result) {
 }
 
 // src/helpers/index.ts
-import {
-  forEach,
-  isArray as isArray2,
-  isEmpty,
-  isObject,
-  isPlainObject as isPlainObject4,
-  isString as isString3,
-  mapValuesAsync,
-  noop
-} from "@web-ts-toolkit/utils";
+import { forEach, isArray as isArray2, isEmpty, isObject, isPlainObject as isPlainObject4, isString as isString3, mapValuesAsync } from "@web-ts-toolkit/utils";
+
+// src/lib.ts
+import { Document as Document2, Schema } from "mongoose";
+import { isPlainObject as isPlainObject3 } from "@web-ts-toolkit/utils";
+var isSchema = (val) => val instanceof Schema;
+var isObjectIdType = (val) => val === "ObjectId" || val === Schema.Types.ObjectId;
+var isReference = (val) => isPlainObject3(val) && !!val.ref && isObjectIdType(val.type);
+var isDocument2 = function isDocument3(doc) {
+  return doc instanceof Document2;
+};
+
+// src/helpers/index.ts
 function recurseObject(obj) {
   if (isSchema(obj)) {
     return buildRefs(obj.tree);
@@ -266,7 +264,7 @@ function buildSubPaths(schema) {
 }
 async function iterateQuery(query, handler) {
   if (!isPlainObject4(query)) return query;
-  if (!handler) return noop;
+  if (!handler) return query;
   const queryObject = query;
   return mapValuesAsync(queryObject, async (val, key) => {
     if (isPlainObject4(val)) {
@@ -295,6 +293,252 @@ var createValidator = (fn) => {
   return { stringHandler, arrayHandler };
 };
 
+// src/openapi/build-spec.ts
+import { isArray as isArray3, isPlainObject as isPlainObject6 } from "@web-ts-toolkit/utils";
+
+// src/openapi/responses.ts
+var json = (schema) => ({
+  content: {
+    "application/json": {
+      schema
+    }
+  }
+});
+var problemJson = {
+  content: {
+    "application/problem+json": {
+      schema: {
+        type: "object",
+        properties: {
+          type: { type: "string" },
+          title: { type: "string" },
+          status: { type: "number" },
+          detail: { type: "string" },
+          errors: { type: "array", items: {} }
+        },
+        additionalProperties: true
+      }
+    }
+  }
+};
+var genericDataSchema = { type: "object", additionalProperties: true };
+var genericListSchema = { type: "array", items: genericDataSchema };
+var openApiResponses = {
+  single(description = "Success") {
+    return {
+      200: { description, ...json(genericDataSchema) },
+      400: { description: "Bad Request", ...problemJson },
+      401: { description: "Unauthorized", ...problemJson },
+      404: { description: "Not Found", ...problemJson }
+    };
+  },
+  list(description = "Success") {
+    return {
+      200: { description, ...json(genericListSchema) },
+      400: { description: "Bad Request", ...problemJson },
+      401: { description: "Unauthorized", ...problemJson }
+    };
+  },
+  create(description = "Created") {
+    return {
+      201: { description, ...json(genericDataSchema) },
+      400: { description: "Bad Request", ...problemJson },
+      401: { description: "Unauthorized", ...problemJson }
+    };
+  },
+  delete(description = "Deleted") {
+    return {
+      200: { description, ...json(genericDataSchema) },
+      400: { description: "Bad Request", ...problemJson },
+      401: { description: "Unauthorized", ...problemJson },
+      404: { description: "Not Found", ...problemJson }
+    };
+  },
+  batch(description = "Success") {
+    return {
+      200: { description, ...json(genericListSchema) },
+      400: { description: "Bad Request", ...problemJson },
+      401: { description: "Unauthorized", ...problemJson }
+    };
+  }
+};
+
+// src/openapi/schemas.ts
+import { z } from "zod";
+import { isPlainObject as isPlainObject5 } from "@web-ts-toolkit/utils";
+var fallbackObjectSchema = { type: "object", additionalProperties: true };
+function patchOpenApiObjectSchema(source, properties) {
+  return {
+    kind: "objectProperties",
+    source,
+    properties
+  };
+}
+function defineOpenApiSchemaResolver(resolve) {
+  return {
+    kind: "schemaResolver",
+    resolve
+  };
+}
+function getNestedOpenApiSchemaDataSource(source) {
+  return isPlainObject5(source) && "data" in source ? source.data : void 0;
+}
+function unwrapNestedOpenApiSchemaSource(source, fallback) {
+  if (isPlainObject5(source) && ("default" in source || "data" in source)) {
+    return source.default ?? fallback;
+  }
+  return source ?? fallback;
+}
+function isOpenApiSchemaPatch(source) {
+  return isPlainObject5(source) && source.kind === "objectProperties";
+}
+function isOpenApiSchemaResolver(source) {
+  return isPlainObject5(source) && source.kind === "schemaResolver" && typeof source.resolve === "function";
+}
+function isJsonSchemaLike(source) {
+  return isPlainObject5(source) && ("type" in source || "properties" in source || "$ref" in source || "anyOf" in source);
+}
+function hasOpenApiSchema(source) {
+  return isPlainObject5(source) && isJsonSchemaLike(source.openapi);
+}
+function toOpenApiSchema(source) {
+  if (!source) return void 0;
+  const resolvedSource = isOpenApiSchemaResolver(source) ? source.resolve() : source;
+  if (!resolvedSource) return void 0;
+  if (isOpenApiSchemaPatch(resolvedSource)) {
+    const schema = toOpenApiSchema(resolvedSource.source) ?? { ...fallbackObjectSchema };
+    const properties = isPlainObject5(schema.properties) ? { ...schema.properties } : {};
+    for (const [key, value] of Object.entries(resolvedSource.properties)) {
+      properties[key] = toOpenApiSchema(value) ?? fallbackObjectSchema;
+    }
+    return {
+      ...schema,
+      type: schema.type ?? "object",
+      properties
+    };
+  }
+  if (hasOpenApiSchema(resolvedSource)) {
+    return resolvedSource.openapi;
+  }
+  if (isJsonSchemaLike(resolvedSource)) {
+    return resolvedSource;
+  }
+  try {
+    return z.toJSONSchema(resolvedSource);
+  } catch {
+    return fallbackObjectSchema;
+  }
+}
+
+// src/openapi/build-spec.ts
+var openApiMediaType = "application/json";
+var normalizePath = (path) => {
+  if (!path) return "/";
+  return path.startsWith("/") ? path : `/${path}`;
+};
+var toOpenApiPath = (path) => normalizePath(path).replace(/:([A-Za-z0-9_]+)/g, "{$1}");
+var schemaToQueryParameters = (schema) => {
+  const jsonSchema = toOpenApiSchema(schema);
+  if (!jsonSchema || jsonSchema.type !== "object") return [];
+  const properties = isPlainObject6(jsonSchema.properties) ? jsonSchema.properties : {};
+  const required = new Set(
+    isArray3(jsonSchema.required) ? jsonSchema.required.filter((item) => typeof item === "string") : []
+  );
+  return Object.entries(properties).map(([name, value]) => ({
+    name,
+    in: "query",
+    required: required.has(name),
+    schema: value
+  }));
+};
+var schemaToPathParameters = (path, pathParams) => {
+  const names = [...toOpenApiPath(path).matchAll(/\{([^}]+)\}/g)].map((item) => item[1]);
+  return names.map((name) => ({
+    name,
+    in: "path",
+    required: true,
+    schema: (pathParams && name in pathParams ? toOpenApiSchema(pathParams[name]) : void 0) ?? { type: "string" }
+  }));
+};
+var getDefaultResponses = (route) => {
+  if (route.operationId === "root.query") return openApiResponses.batch();
+  if (route.method === "delete") return openApiResponses.delete();
+  if (route.operationId?.toLowerCase().includes("create")) return openApiResponses.create();
+  if (route.operationId?.toLowerCase().includes("list")) return openApiResponses.list();
+  if (route.operationId?.toLowerCase().includes("distinct")) return openApiResponses.list();
+  return openApiResponses.single();
+};
+var buildOperation = (route) => {
+  const queryParameters = schemaToQueryParameters(route.query);
+  const pathParameters = schemaToPathParameters(route.path, route.pathParams);
+  const bodySchema = toOpenApiSchema(route.body);
+  const responses = route.responses ?? getDefaultResponses(route);
+  const operation = {
+    operationId: route.operationId,
+    summary: route.summary,
+    description: route.description,
+    tags: route.tags,
+    deprecated: route.deprecated,
+    responses
+  };
+  const parameters = [...pathParameters, ...queryParameters];
+  if (parameters.length) {
+    operation.parameters = parameters;
+  }
+  if (bodySchema) {
+    operation.requestBody = {
+      required: true,
+      content: {
+        [openApiMediaType]: {
+          schema: bodySchema
+        }
+      }
+    };
+  }
+  if (route.acl) {
+    operation["x-access-router-acl"] = route.acl;
+  }
+  return operation;
+};
+function buildOpenApiSpec(routes, options) {
+  const paths = {};
+  const { servers, ...info } = options;
+  for (const route of routes) {
+    const path = toOpenApiPath(route.path);
+    if (!paths[path]) {
+      paths[path] = {};
+    }
+    paths[path][route.method] = buildOperation(route);
+  }
+  return {
+    openapi: "3.1.0",
+    info,
+    servers,
+    paths
+  };
+}
+
+// src/openapi/registry.ts
+var OpenApiRegistry = class {
+  constructor() {
+    this.routes = [];
+  }
+  register(route) {
+    const existingIndex = this.routes.findIndex((item) => item.method === route.method && item.path === route.path);
+    if (existingIndex === -1) {
+      this.routes.push(route);
+      return;
+    }
+    this.routes[existingIndex] = route;
+  }
+  getRoutes() {
+    return [...this.routes];
+  }
+  getSpec(info) {
+    return buildOpenApiSpec(this.routes, info);
+  }
+};
+
 // src/logger-default.ts
 import util from "util";
 import { createLogger, format, transports } from "winston";
@@ -401,9 +645,9 @@ var hasModelPermission = (value, modelPermissionPrefix) => {
   if (isString4(value)) {
     return value.trim().split(" ").some((item) => item.startsWith(modelPermissionPrefix));
   }
-  if (isArray3(value)) {
+  if (isArray4(value)) {
     return value.some((item) => {
-      if (isString4(item) || isArray3(item)) {
+      if (isString4(item) || isArray4(item)) {
         return hasModelPermission(item, modelPermissionPrefix);
       }
       return true;
@@ -417,13 +661,13 @@ var classifyPermissionSchema = (permissionSchema, modelPermissionPrefix) => {
   const modelPermissionKeys = {};
   forEach2(schemaKeys, (schemaKey) => {
     const schemaRule = permissionSchema[schemaKey];
-    const ruleEntries = isPlainObject5(schemaRule) ? Object.entries(schemaRule) : FIELD_ACCESS_KEYS.map((accessKey) => [accessKey, schemaRule]);
+    const ruleEntries = isPlainObject7(schemaRule) ? Object.entries(schemaRule) : FIELD_ACCESS_KEYS.map((accessKey) => [accessKey, schemaRule]);
     for (let x = 0; x < ruleEntries.length; x++) {
       const [accessKey, value] = ruleEntries[x];
-      if (!isArray3(globalPermissionKeys[accessKey])) {
+      if (!isArray4(globalPermissionKeys[accessKey])) {
         globalPermissionKeys[accessKey] = [];
       }
-      if (!isArray3(modelPermissionKeys[accessKey])) {
+      if (!isArray4(modelPermissionKeys[accessKey])) {
         modelPermissionKeys[accessKey] = [];
       }
       if (isBoolean(value)) {
@@ -467,6 +711,16 @@ var AccessRuntime = class {
     this.modelRefs = {};
     this.modelSubs = {};
     this.modelAtts = {};
+    this.openApiRegistry = new OpenApiRegistry();
+  }
+  registerOpenApiRoute(route) {
+    this.openApiRegistry.register(route);
+  }
+  getOpenApiRoutes() {
+    return this.openApiRegistry.getRoutes();
+  }
+  getOpenApiSpec(info) {
+    return this.openApiRegistry.getSpec(info);
   }
   setGlobalOptions(options) {
     this.globalOptions.assign(options);
@@ -738,19 +992,19 @@ import {
   forEach as forEach3,
   get as get4,
   intersectionBy,
-  isArray as isArray4,
-  isPlainObject as isPlainObject6,
+  isArray as isArray5,
+  isPlainObject as isPlainObject8,
   uniq
 } from "@web-ts-toolkit/utils";
 function validateClientFilter(filter2) {
   const errors = [];
   const blockedOperators = /* @__PURE__ */ new Set(["$where", "$expr", "$function", "$accumulator"]);
   const visit = (value, path) => {
-    if (isArray4(value)) {
+    if (isArray5(value)) {
       value.forEach((item, index) => visit(item, `${path}[${index}]`));
       return;
     }
-    if (!isPlainObject6(value)) return;
+    if (!isPlainObject8(value)) return;
     Object.entries(value).forEach(([key, child]) => {
       const nextPath = path ? `${path}.${key}` : key;
       if (blockedOperators.has(key)) {
@@ -866,7 +1120,7 @@ var Base = class {
     if (!include) return docs;
     const includes = compact(castArray(include));
     if (includes.length === 0) return docs;
-    const isSingle = !isArray4(docs);
+    const isSingle = !isArray5(docs);
     if (isSingle) docs = [docs];
     for (let x = 0; x < includes.length; x++) {
       const include2 = includes[x];
@@ -951,14 +1205,16 @@ var Base = class {
     if (!result.success) return null;
     let ret = result.data;
     if (sqOptions.path) {
-      ret = isArray4(ret) ? flatten(ret.map((v) => get4(v, sqOptions.path))) : get4(ret, sqOptions.path);
+      ret = isArray5(ret) ? flatten(ret.map((v) => get4(v, sqOptions.path))) : get4(ret, sqOptions.path);
     }
     if (sqOptions.compact) {
       ret = compact(castArray(ret));
     }
     return ret;
   }
-  async handleDate(val, key) {
+  handleDate(val, key) {
+    if (val instanceof Date) return val;
+    if (typeof val === "string" || typeof val === "number") return new Date(val);
     return /* @__PURE__ */ new Date();
   }
 };
@@ -966,7 +1222,7 @@ var Base = class {
 // src/services/service.ts
 import {
   castArray as castArray2,
-  isArray as isArray5,
+  isArray as isArray6,
   isBoolean as isBoolean3,
   isFunction as isFunction3,
   omit,
@@ -977,6 +1233,21 @@ import diff from "deep-diff";
 
 // src/model.ts
 import mongoose3 from "mongoose";
+
+// src/logger.ts
+var passthrough = (level) => (...args) => {
+  const globalLogger = getGlobalOption("logger");
+  const target = globalLogger?.[level] ?? defaultLogger[level];
+  return target.apply(globalLogger ?? defaultLogger, args);
+};
+var logger = {
+  debug: passthrough("debug"),
+  info: passthrough("info"),
+  warn: passthrough("warn"),
+  error: passthrough("error")
+};
+
+// src/model.ts
 var Model = class {
   constructor(modelName) {
     this.modelName = modelName;
@@ -1006,12 +1277,15 @@ var Model = class {
     if (lean) builder.lean();
     return builder;
   }
-  // See https://github.com/Automattic/mongoose/blob/65b2d12a8f85f86136cfaf32947f338ba0c5f451/lib/query.js#L3011
-  validateSort(sort, logError = console.error) {
+  validateSort(sort, logError = logger.error) {
     const validSortOrders = [1, -1, "asc", "ascending", "desc", "descending"];
+    const fieldPathPattern = /^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/;
+    const isValidFieldPath = (field) => fieldPathPattern.test(field);
     if (sort === null || sort === void 0) return true;
     if (typeof sort === "string") {
-      if (!/^[a-zA-Z0-9\s-]+/.test(sort)) {
+      const fields = sort.trim().split(/\s+/).filter(Boolean);
+      const isValid = fields.every((field) => isValidFieldPath(field.startsWith("-") ? field.slice(1) : field));
+      if (!isValid) {
         logError("Invalid sort string:", sort);
         return false;
       }
@@ -1024,8 +1298,8 @@ var Model = class {
           return false;
         }
         const [key, order] = pair;
-        if (typeof key !== "string") {
-          logError("Invalid sort array key: must be string", key);
+        if (typeof key !== "string" || !isValidFieldPath(key)) {
+          logError("Invalid sort array key: must be a field path string", key);
           return false;
         }
         if (!validSortOrders.includes(order)) {
@@ -1037,7 +1311,11 @@ var Model = class {
       return isValid;
     }
     if (typeof sort === "object" && !(sort instanceof Map)) {
-      const isValid = Object.values(sort).every((order) => {
+      const isValid = Object.entries(sort).every(([key, order]) => {
+        if (!isValidFieldPath(key)) {
+          logError("Invalid sort object key: must be a field path string", key);
+          return false;
+        }
         if (!validSortOrders.includes(order)) {
           logError('Invalid sort object value: must be 1, -1, "asc", or "desc"', order);
           return false;
@@ -1047,7 +1325,11 @@ var Model = class {
       return isValid;
     }
     if (sort instanceof Map) {
-      const isValid = Array.from(sort.values()).every((order) => {
+      const isValid = Array.from(sort.entries()).every(([key, order]) => {
+        if (!isValidFieldPath(key)) {
+          logError("Invalid sort Map key: must be a field path string", key);
+          return false;
+        }
         if (!validSortOrders.includes(order)) {
           logError('Invalid sort Map value: must be 1, -1, "asc", or "desc"', order);
           return false;
@@ -1070,9 +1352,6 @@ var Model = class {
     if (lean) builder.lean();
     return builder;
   }
-  findOneAndDelete(filter2) {
-    return this.model.findOneAndDelete(filter2);
-  }
   exists(filter2) {
     if (!filter2) return null;
     return this.findOne(filter2).select("_id").lean();
@@ -1081,10 +1360,6 @@ var Model = class {
   countDocuments(filter2 = {}) {
     return this.model.countDocuments(filter2);
   }
-  // see https://mongoosejs.com/docs/api.html#model_Model.estimatedDocumentCount
-  estimatedDocumentCount() {
-    return this.model.estimatedDocumentCount();
-  }
   // see https://mongoosejs.com/docs/api.html#model_Model.distinct
   distinct(field, conditions = {}) {
     return this.model.distinct(field, conditions);
@@ -1092,19 +1367,6 @@ var Model = class {
 };
 var model_default = Model;
 
-// src/logger.ts
-var passthrough = (level) => (...args) => {
-  const globalLogger = getGlobalOption("logger");
-  const target = globalLogger?.[level] ?? defaultLogger[level];
-  return target.apply(globalLogger ?? defaultLogger, args);
-};
-var logger = {
-  debug: passthrough("debug"),
-  info: passthrough("info"),
-  warn: passthrough("warn"),
-  error: passthrough("error")
-};
-
 // src/services/model-subdocument-service.ts
 import { forEach as forEach4, get as get5, pick as pick3 } from "@web-ts-toolkit/utils";
 async function listSub(service, id, sub, options) {
@@ -1328,7 +1590,7 @@ function resolveExistsOptions(service, options = {}) {
 
 // src/services/service.ts
 var assertModelDocument = (value, modelName, hookName) => {
-  if (isDocument(value)) {
+  if (isDocument2(value)) {
     return value;
   }
   throw new Error(`${hookName} hook for model=${modelName} must return a Mongoose document instance`);
@@ -1422,7 +1684,7 @@ var Service = class extends Base {
       genPagination({ skip, limit, page, pageSize }, this.options.listHardLimit)
     ]);
     const finalSelect = normalizeSelect(_select);
-    const filteredPopulate = isArray5(finalSelect) && isArray5(_populate) ? _populate.filter((p) => finalSelect.includes(p.path.split(".")[0])) : _populate;
+    const filteredPopulate = isArray6(finalSelect) && isArray6(_populate) ? _populate.filter((p) => finalSelect.includes(p.path.split(".")[0])) : _populate;
     const { includes, includeLocalFields, includePaths } = this.processInclude(include);
     const query = {
       filter: _filter,
@@ -1505,7 +1767,7 @@ var Service = class extends Base {
             validationError = { success: false, code: "bad_request" /* BadRequest */ };
             return;
           }
-        } else if (isArray5(validated)) {
+        } else if (isArray6(validated)) {
           if (validated.length > 0) {
             validationError = { success: false, code: "bad_request" /* BadRequest */, errors: validated };
             return;
@@ -1595,7 +1857,7 @@ var Service = class extends Base {
     const validated = await this.validate(allowedData, "update", context);
     if (isBoolean3(validated)) {
       if (!validated) return { success: false, code: "bad_request" /* BadRequest */ };
-    } else if (isArray5(validated)) {
+    } else if (isArray6(validated)) {
       if (validated.length > 0) return { success: false, code: "bad_request" /* BadRequest */, errors: validated };
     }
     const prepared = await this.prepare(allowedData, "update", context);
@@ -2199,29 +2461,29 @@ var DataService = class {
 };
 
 // src/processors.ts
-import { castArray as castArray3, cloneDeep, forEach as forEach5, get as get6, isArray as isArray6, map as map3, set as set5 } from "@web-ts-toolkit/utils";
+import { castArray as castArray3, cloneDeep, forEach as forEach6, get as get7, isArray as isArray7, map as map2, set as set5 } from "@web-ts-toolkit/utils";
 var copyAndDepopulate = (docObject, operations, options = { mutable: true, idField: "_id" }) => {
-  const obj = get6(options, "mutable", true) ? docObject : cloneDeep(docObject);
-  const idField = get6(options, "idField", "_id");
-  forEach5(castArray3(operations), (op) => {
+  const obj = get7(options, "mutable", true) ? docObject : cloneDeep(docObject);
+  const idField = get7(options, "idField", "_id");
+  forEach6(castArray3(operations), (op) => {
     if (!op.src || !op.dest) return;
     let targets = [obj];
     const segs = op.src.split(".");
-    forEach5(segs, (seg, ind) => {
+    forEach6(segs, (seg, ind) => {
       if (segs.length === ind + 1) {
-        forEach5(targets, (target) => {
+        forEach6(targets, (target) => {
           const targetObject = target;
-          set5(targetObject, op.dest, get6(targetObject, seg));
+          set5(targetObject, op.dest, get7(targetObject, seg));
           set5(
             targetObject,
             seg,
-            isArray6(targetObject[seg]) ? map3(targetObject[seg], idField) : get6(targetObject, `${seg}.${idField}`)
+            isArray7(targetObject[seg]) ? map2(targetObject[seg], idField) : get7(targetObject, `${seg}.${idField}`)
           );
         });
       } else {
         targets = targets.reduce((ret, target) => {
           const targetObject = target;
-          if (isArray6(targetObject[seg])) ret.push(...targetObject[seg]);
+          if (isArray7(targetObject[seg])) ret.push(...targetObject[seg]);
           else ret.push(targetObject[seg]);
           return ret;
         }, []);
@@ -2272,12 +2534,12 @@ var Cache = class {
 import {
   castArray as castArray4,
   arrayToRecord,
-  isArray as isArray7,
+  isArray as isArray8,
   isBoolean as isBoolean4,
   isEmpty as isEmpty2,
   isEqual,
   isFunction as isFunction4,
-  isPlainObject as isPlainObject7,
+  isPlainObject as isPlainObject10,
   isString as isString5
 } from "@web-ts-toolkit/utils";
 
@@ -2317,10 +2579,10 @@ var permission_default = Permission;
 
 // src/core-shared.ts
 function isAndFilter(filter2) {
-  return !!filter2 && isPlainObject7(filter2) && Object.keys(filter2).length === 1 && isArray7(filter2.$and);
+  return !!filter2 && isPlainObject10(filter2) && Object.keys(filter2).length === 1 && isArray8(filter2.$and);
 }
 function isMergeableClause(filter2) {
-  return !!filter2 && isPlainObject7(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
+  return !!filter2 && isPlainObject10(filter2) && Object.keys(filter2).every((key) => !key.startsWith("$"));
 }
 function optimizeAndFilter(clausesInput) {
   const clauses = [];
@@ -2365,7 +2627,7 @@ function optimizeAndFilter(clausesInput) {
 }
 function normalizeFilter(filter2) {
   if (filter2 === false) return false;
-  if (!filter2 || !isPlainObject7(filter2) || isEmpty2(filter2)) return null;
+  if (!filter2 || !isPlainObject10(filter2) || isEmpty2(filter2)) return null;
   if (!isAndFilter(filter2)) {
     return filter2;
   }
@@ -2417,8 +2679,8 @@ async function setRequestPermissions(req) {
   const globalPermissions = getGlobalOption("globalPermissions");
   if (!isFunction4(globalPermissions)) return;
   const permissions = await globalPermissions.call(req, req);
-  if (isPlainObject7(permissions)) req[requestPermissionField] = permissions;
-  else if (isArray7(permissions)) req[requestPermissionField] = arrayToRecord(permissions);
+  if (isPlainObject10(permissions)) req[requestPermissionField] = permissions;
+  else if (isArray8(permissions)) req[requestPermissionField] = arrayToRecord(permissions);
   else if (isString5(permissions)) req[requestPermissionField] = { [permissions]: true };
 }
 async function evaluateRouteGuard(req, permissions, routeGuard) {
@@ -2430,7 +2692,7 @@ async function evaluateRouteGuard(req, permissions, routeGuard) {
   if (isString5(routeGuard)) {
     return stringHandler(routeGuard);
   }
-  if (isArray7(routeGuard)) {
+  if (isArray8(routeGuard)) {
     return arrayHandler(routeGuard);
   }
   if (isFunction4(routeGuard)) {
@@ -2468,7 +2730,7 @@ async function collectSchemaFields({
       if (value) fields.push(key);
     } else if (isString5(value)) {
       if (stringHandler(value)) fields.push(key);
-    } else if (isArray7(value)) {
+    } else if (isArray8(value)) {
       if (arrayHandler(value)) fields.push(key);
     } else if (isFunction4(value)) {
       if (await value.call(req, ...functionArgs)) fields.push(key);
@@ -2757,7 +3019,7 @@ var Core = class {
     if (isFunction5(validate)) {
       const permissions = this.getGlobalPermissions();
       return validate.call(this.req, allowedData, permissions, context);
-    } else if (isBoolean5(validate) || isArray8(validate)) {
+    } else if (isBoolean5(validate) || isArray9(validate)) {
       return validate;
     } else {
       return true;
@@ -2888,7 +3150,7 @@ var Core = class {
   runTasks(modelName, docObject, task) {
     const tasks = compact3(castArray5(task));
     if (tasks.length === 0) return docObject;
-    forEach6(tasks, (task2) => {
+    forEach7(tasks, (task2) => {
       const { type, args, options } = task2;
       switch (type) {
         case "COPY_AND_DEPOPULATE":
@@ -2971,19 +3233,19 @@ function guard(condition) {
     const permissions = req[PERMISSIONS];
     let cond = condition;
     let phas = (key) => permissions.has(key);
-    if (isPlainObject8(condition)) {
+    if (isPlainObject11(condition)) {
       const { modelName, id, condition: _cond } = condition;
       const svc = req.macl.getPublicService(modelName);
       const select = getModelOption(modelName, `alwaysSelectFields.read`, void 0);
       let _id = isString7(id) ? id : null;
-      if (isPlainObject8(id)) {
+      if (isPlainObject11(id)) {
         const { type = "param", key } = id;
         if (type === "param") {
           const paramValue = req.params[key];
-          _id = isArray9(paramValue) ? paramValue[0] ?? null : paramValue ?? null;
+          _id = isArray10(paramValue) ? paramValue[0] ?? null : paramValue ?? null;
         } else if (type === "query") {
           const _qval = req.query[key];
-          if (isArray9(_qval)) _id = _qval.length > 0 ? _qval[0] : null;
+          if (isArray10(_qval)) _id = _qval.length > 0 ? _qval[0] : null;
           else _id = _qval;
         } else {
           _id = null;
@@ -3003,7 +3265,7 @@ function guard(condition) {
     const { stringHandler, arrayHandler } = createValidator(phas);
     if (isString7(cond)) {
       if (stringHandler(cond)) return next();
-    } else if (isArray9(cond)) {
+    } else if (isArray10(cond)) {
       if (arrayHandler(cond)) return next();
     } else if (isFunction6(cond)) {
       const result = await cond.call(req, permissions);
@@ -3014,11 +3276,11 @@ function guard(condition) {
 }
 
 // src/routers/index.ts
-import express from "express";
+import express2 from "express";
 
 // src/routers/model-router.ts
 import JsonRouter5 from "@web-ts-toolkit/express-json-router";
-import { forEach as forEach7, isPlainObject as isPlainObject9, isString as isString9, isUndefined as isUndefined2, normalizeUrlPath, padEnd } from "@web-ts-toolkit/utils";
+import { forEach as forEach8, isPlainObject as isPlainObject12, isString as isString9, isUndefined as isUndefined2, normalizeUrlPath as normalizeUrlPath2, padEnd } from "@web-ts-toolkit/utils";
 
 // src/routers/router-mutation.ts
 var MODEL_BUILD_TIME_OPTION_KEYS = /* @__PURE__ */ new Set([
@@ -3110,88 +3372,88 @@ function formatModelUpsertResponse(result) {
 import JsonRouter4 from "@web-ts-toolkit/express-json-router";
 
 // src/validation/common.ts
-import { z } from "zod";
-var stringOrStringArray = z.union([z.string(), z.array(z.string())]);
-var queryBooleanString = z.enum(["true", "false"]);
-var positiveIntegerString = z.string().regex(/^\d+$/, "Expected a non-negative integer");
-var nonNegativeIntegerSchema = z.number().int().min(0);
-var unknownRecord = z.record(z.string(), z.unknown());
-var projectionObjectSchema = z.record(z.string(), z.union([z.literal(1), z.literal(-1)]));
-var projectionSchema = z.union([z.string(), z.array(z.string()), projectionObjectSchema]);
-var sortOrderSchema = z.union([
-  z.literal(-1),
-  z.literal(1),
-  z.literal("asc"),
-  z.literal("ascending"),
-  z.literal("desc"),
-  z.literal("descending")
+import { z as z2 } from "zod";
+var stringOrStringArray = z2.union([z2.string(), z2.array(z2.string())]);
+var queryBooleanString = z2.enum(["true", "false"]);
+var positiveIntegerString = z2.string().regex(/^\d+$/, "Expected a non-negative integer");
+var nonNegativeIntegerSchema = z2.number().int().min(0);
+var unknownRecord = z2.record(z2.string(), z2.unknown());
+var projectionObjectSchema = z2.record(z2.string(), z2.union([z2.literal(1), z2.literal(-1)]));
+var projectionSchema = z2.union([z2.string(), z2.array(z2.string()), projectionObjectSchema]);
+var sortOrderSchema = z2.union([
+  z2.literal(-1),
+  z2.literal(1),
+  z2.literal("asc"),
+  z2.literal("ascending"),
+  z2.literal("desc"),
+  z2.literal("descending")
 ]);
-var sortSchema = z.union([
-  z.string(),
-  z.record(z.string(), sortOrderSchema),
-  z.array(z.tuple([z.string(), sortOrderSchema])),
-  z.null()
+var sortSchema = z2.union([
+  z2.string(),
+  z2.record(z2.string(), sortOrderSchema),
+  z2.array(z2.tuple([z2.string(), sortOrderSchema])),
+  z2.null()
 ]);
-var populateSchema = z.union([
-  z.string(),
-  z.array(
-    z.union([
-      z.string(),
-      z.object({
-        path: z.string().min(1),
+var populateSchema = z2.union([
+  z2.string(),
+  z2.array(
+    z2.union([
+      z2.string(),
+      z2.object({
+        path: z2.string().min(1),
         select: projectionSchema.optional(),
-        match: z.unknown().optional(),
-        access: z.enum(["list", "read"]).optional()
+        match: z2.unknown().optional(),
+        access: z2.enum(["list", "read"]).optional()
       }).passthrough()
     ])
   ),
-  z.object({
-    path: z.string().min(1),
+  z2.object({
+    path: z2.string().min(1),
     select: projectionSchema.optional(),
-    match: z.unknown().optional(),
-    access: z.enum(["list", "read"]).optional()
+    match: z2.unknown().optional(),
+    access: z2.enum(["list", "read"]).optional()
   }).passthrough()
 ]);
-var subPopulateSchema = z.union([
-  z.string(),
-  z.array(
-    z.union([
-      z.string(),
-      z.object({
-        path: z.string().min(1),
+var subPopulateSchema = z2.union([
+  z2.string(),
+  z2.array(
+    z2.union([
+      z2.string(),
+      z2.object({
+        path: z2.string().min(1),
         select: projectionSchema.optional()
       }).passthrough()
     ])
   ),
-  z.object({
-    path: z.string().min(1),
+  z2.object({
+    path: z2.string().min(1),
     select: projectionSchema.optional()
   }).passthrough()
 ]);
-var includeItemSchema = z.object({
-  model: z.string().min(1),
-  op: z.enum(["list", "read", "count"]),
-  path: z.string().min(1),
-  filter: z.record(z.string(), z.unknown()).optional(),
-  localField: z.string().min(1),
-  foreignField: z.string().min(1),
-  args: z.unknown().optional(),
-  options: z.unknown().optional()
+var includeItemSchema = z2.object({
+  model: z2.string().min(1),
+  op: z2.enum(["list", "read", "count"]),
+  path: z2.string().min(1),
+  filter: z2.record(z2.string(), z2.unknown()).optional(),
+  localField: z2.string().min(1),
+  foreignField: z2.string().min(1),
+  args: z2.unknown().optional(),
+  options: z2.unknown().optional()
 }).passthrough();
-var includeSchema = z.union([includeItemSchema, z.array(includeItemSchema)]);
-var fieldsSchema = z.array(z.string().min(1));
-var taskSchema = z.object({
-  type: z.string().min(1),
-  args: z.unknown(),
+var includeSchema = z2.union([includeItemSchema, z2.array(includeItemSchema)]);
+var fieldsSchema = z2.array(z2.string().min(1));
+var taskSchema = z2.object({
+  type: z2.string().min(1),
+  args: z2.unknown(),
   options: unknownRecord.optional()
 });
-var tasksSchema = z.union([taskSchema, z.array(taskSchema)]);
-var objectOrArraySchema = z.union([z.record(z.string(), z.unknown()), z.array(z.unknown())]);
+var tasksSchema = z2.union([taskSchema, z2.array(taskSchema)]);
+var objectOrArraySchema = z2.union([z2.record(z2.string(), z2.unknown()), z2.array(z2.unknown())]);
 function rejectKeys(body, ctx, keys2) {
   for (const key of keys2) {
     if (key in body) {
       ctx.addIssue({
-        code: z.ZodIssueCode.custom,
+        code: z2.ZodIssueCode.custom,
         message: `Unsupported field: ${key}`,
         path: [key]
       });
@@ -3280,8 +3542,11 @@ function toRequestSchemaValidator(schema) {
   if (isRequestSchemaValidator(schema)) return schema;
   return schema.validate;
 }
-function defineRequestSchema(validator) {
-  return validator;
+function defineRequestSchema(validator, options = {}) {
+  return {
+    validate: validator,
+    openapi: options.openapi
+  };
 }
 function fromZod(schema) {
   return (value) => {
@@ -3561,8 +3826,8 @@ function buildPointer(path) {
 }
 
 // src/validation/model-router.ts
-import { z as z2 } from "zod";
-var listQuerySchema = z2.object({
+import { z as z3 } from "zod";
+var listQuerySchema = z3.object({
   skip: positiveIntegerString.optional(),
   limit: positiveIntegerString.optional(),
   page: positiveIntegerString.optional(),
@@ -3572,122 +3837,122 @@ var listQuerySchema = z2.object({
   include_count: queryBooleanString.optional(),
   include_extra_headers: queryBooleanString.optional()
 }).passthrough();
-var createQuerySchema = z2.object({
+var createQuerySchema = z3.object({
   include_permissions: queryBooleanString.optional()
 }).passthrough();
-var readQuerySchema = z2.object({
+var readQuerySchema = z3.object({
   include_permissions: queryBooleanString.optional(),
   try_list: queryBooleanString.optional()
 }).passthrough();
-var updateQuerySchema = z2.object({
+var updateQuerySchema = z3.object({
   returning_all: queryBooleanString.optional(),
   include_permissions: queryBooleanString.optional()
 }).passthrough();
-var upsertQuerySchema = z2.object({
+var upsertQuerySchema = z3.object({
   returning_all: queryBooleanString.optional(),
   include_permissions: queryBooleanString.optional()
 }).passthrough();
-var listBodySchema = z2.object({
+var listBodySchema = z3.object({
   filter: objectOrArraySchema.optional(),
   select: projectionSchema.optional(),
   sort: sortSchema.optional(),
   populate: populateSchema.optional(),
   include: includeSchema.optional(),
   tasks: tasksSchema.optional(),
-  skip: z2.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  limit: z2.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  page: z2.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  pageSize: z2.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  options: z2.object({
-    skim: z2.boolean().optional(),
-    includePermissions: z2.boolean().optional(),
-    includeCount: z2.boolean().optional(),
-    includeExtraHeaders: z2.boolean().optional(),
-    populateAccess: z2.unknown().optional()
+  skip: z3.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  limit: z3.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  page: z3.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  pageSize: z3.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  options: z3.object({
+    skim: z3.boolean().optional(),
+    includePermissions: z3.boolean().optional(),
+    includeCount: z3.boolean().optional(),
+    includeExtraHeaders: z3.boolean().optional(),
+    populateAccess: z3.unknown().optional()
   }).passthrough().optional()
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query"]));
-var countBodySchema = z2.object({
+var countBodySchema = z3.object({
   filter: objectOrArraySchema.optional(),
-  options: z2.object({
-    access: z2.unknown().optional()
+  options: z3.object({
+    access: z3.unknown().optional()
   }).passthrough().optional()
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query", "access"]));
-var readFilterBodySchema = z2.object({
+var readFilterBodySchema = z3.object({
   filter: objectOrArraySchema.optional(),
   select: projectionSchema.optional(),
   sort: sortSchema.optional(),
   populate: populateSchema.optional(),
   include: includeSchema.optional(),
   tasks: tasksSchema.optional(),
-  options: z2.object({
-    skim: z2.boolean().optional(),
-    includePermissions: z2.boolean().optional(),
-    tryList: z2.boolean().optional(),
-    populateAccess: z2.unknown().optional()
+  options: z3.object({
+    skim: z3.boolean().optional(),
+    includePermissions: z3.boolean().optional(),
+    tryList: z3.boolean().optional(),
+    populateAccess: z3.unknown().optional()
   }).passthrough().optional()
 }).passthrough();
-var readByIdBodySchema = z2.object({
+var readByIdBodySchema = z3.object({
   select: projectionSchema.optional(),
   populate: populateSchema.optional(),
   include: includeSchema.optional(),
   tasks: tasksSchema.optional(),
-  options: z2.object({
-    skim: z2.boolean().optional(),
-    includePermissions: z2.boolean().optional(),
-    tryList: z2.boolean().optional(),
-    populateAccess: z2.unknown().optional()
+  options: z3.object({
+    skim: z3.boolean().optional(),
+    includePermissions: z3.boolean().optional(),
+    tryList: z3.boolean().optional(),
+    populateAccess: z3.unknown().optional()
   }).passthrough().optional()
 }).passthrough();
-var advancedCreateBodySchema = z2.object({
-  data: z2.unknown(),
+var advancedCreateBodySchema = z3.object({
+  data: z3.unknown(),
   select: projectionSchema.optional(),
   populate: populateSchema.optional(),
   tasks: tasksSchema.optional(),
-  options: z2.object({
-    includePermissions: z2.boolean().optional(),
-    populateAccess: z2.unknown().optional()
+  options: z3.object({
+    includePermissions: z3.boolean().optional(),
+    populateAccess: z3.unknown().optional()
   }).passthrough().optional()
 }).passthrough();
-var createBodySchema = z2.union([
-  z2.record(z2.string(), z2.unknown()),
-  z2.array(z2.record(z2.string(), z2.unknown()))
+var createBodySchema = z3.union([
+  z3.record(z3.string(), z3.unknown()),
+  z3.array(z3.record(z3.string(), z3.unknown()))
 ]);
-var updateBodySchema = z2.record(z2.string(), z2.unknown());
-var advancedUpdateBodySchema = z2.object({
-  data: z2.unknown(),
+var updateBodySchema = z3.record(z3.string(), z3.unknown());
+var advancedUpdateBodySchema = z3.object({
+  data: z3.unknown(),
   select: projectionSchema.optional(),
   populate: populateSchema.optional(),
   tasks: tasksSchema.optional(),
-  options: z2.object({
-    returningAll: z2.boolean().optional(),
-    includePermissions: z2.boolean().optional(),
-    populateAccess: z2.unknown().optional()
+  options: z3.object({
+    returningAll: z3.boolean().optional(),
+    includePermissions: z3.boolean().optional(),
+    populateAccess: z3.unknown().optional()
   }).passthrough().optional()
 }).passthrough();
-var upsertBodySchema = z2.record(z2.string(), z2.unknown());
-var advancedUpsertBodySchema = z2.object({
-  data: z2.record(z2.string(), z2.unknown()),
+var upsertBodySchema = z3.record(z3.string(), z3.unknown());
+var advancedUpsertBodySchema = z3.object({
+  data: z3.record(z3.string(), z3.unknown()),
   select: projectionSchema.optional(),
   populate: populateSchema.optional(),
   tasks: tasksSchema.optional(),
-  options: z2.object({
-    returningAll: z2.boolean().optional(),
-    includePermissions: z2.boolean().optional(),
-    populateAccess: z2.unknown().optional()
+  options: z3.object({
+    returningAll: z3.boolean().optional(),
+    includePermissions: z3.boolean().optional(),
+    populateAccess: z3.unknown().optional()
   }).passthrough().optional()
 }).passthrough();
-var distinctBodySchema = z2.object({
+var distinctBodySchema = z3.object({
   filter: objectOrArraySchema.optional()
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query"]));
-var subListBodySchema = z2.object({
-  filter: z2.record(z2.string(), z2.unknown()).optional(),
+var subListBodySchema = z3.object({
+  filter: z3.record(z3.string(), z3.unknown()).optional(),
   select: fieldsSchema.optional()
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["fields"]));
-var subMutationBodySchema = z2.union([
-  z2.record(z2.string(), z2.unknown()),
-  z2.array(z2.record(z2.string(), z2.unknown()))
+var subMutationBodySchema = z3.union([
+  z3.record(z3.string(), z3.unknown()),
+  z3.array(z3.record(z3.string(), z3.unknown()))
 ]);
-var subReadBodySchema = z2.object({
+var subReadBodySchema = z3.object({
   select: fieldsSchema.optional(),
   populate: subPopulateSchema.optional()
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["fields"]));
@@ -3700,54 +3965,54 @@ var requestSchemas = {
 };
 
 // src/validation/data-router.ts
-import { z as z3 } from "zod";
-var dataListBodySchema = z3.object({
+import { z as z4 } from "zod";
+var dataListBodySchema = z4.object({
   filter: objectOrArraySchema.optional(),
   select: projectionSchema.optional(),
-  sort: z3.string().optional(),
-  skip: z3.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  limit: z3.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  page: z3.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  pageSize: z3.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  options: z3.object({
-    includeCount: z3.boolean().optional(),
-    includeExtraHeaders: z3.boolean().optional()
+  sort: z4.string().optional(),
+  skip: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  limit: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  page: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  pageSize: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  options: z4.object({
+    includeCount: z4.boolean().optional(),
+    includeExtraHeaders: z4.boolean().optional()
   }).passthrough().optional()
 }).passthrough();
-var dataReadFilterBodySchema = z3.object({
+var dataReadFilterBodySchema = z4.object({
   filter: objectOrArraySchema.optional(),
   select: projectionSchema.optional()
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["options"]));
-var dataReadByIdBodySchema = z3.object({
+var dataReadByIdBodySchema = z4.object({
   select: projectionSchema.optional()
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["options"]));
 
 // src/validation/root-router.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var rootEntryBaseSchema = {
-  target: z4.enum(["model", "data"]),
-  name: z4.string().min(1),
-  order: z4.number().int().optional()
+  target: z5.enum(["model", "data"]),
+  name: z5.string().min(1),
+  order: z5.number().int().optional()
 };
-var rootModelListArgsSchema = z4.object({
+var rootModelListArgsSchema = z5.object({
   select: projectionSchema.optional(),
   populate: populateSchema.optional(),
   include: includeSchema.optional(),
   sort: sortSchema.optional(),
-  skip: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  limit: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  page: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  pageSize: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  skip: z5.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  limit: z5.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  page: z5.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  pageSize: z5.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
   tasks: tasksSchema.optional()
 }).passthrough();
-var rootModelListOptionsSchema = z4.object({
-  skim: z4.boolean().optional(),
-  includePermissions: z4.boolean().optional(),
-  includeCount: z4.boolean().optional(),
-  populateAccess: z4.unknown().optional(),
-  lean: z4.boolean().optional()
+var rootModelListOptionsSchema = z5.object({
+  skim: z5.boolean().optional(),
+  includePermissions: z5.boolean().optional(),
+  includeCount: z5.boolean().optional(),
+  populateAccess: z5.unknown().optional(),
+  lean: z5.boolean().optional()
 }).passthrough();
-var rootModelReadArgsSchema = z4.object({
+var rootModelReadArgsSchema = z5.object({
   select: projectionSchema.optional(),
   populate: populateSchema.optional(),
   include: includeSchema.optional(),
@@ -3756,210 +4021,219 @@ var rootModelReadArgsSchema = z4.object({
 var rootModelReadFilterArgsSchema = rootModelReadArgsSchema.extend({
   sort: sortSchema.optional()
 });
-var rootModelReadOptionsSchema = z4.object({
-  skim: z4.boolean().optional(),
-  includePermissions: z4.boolean().optional(),
-  tryList: z4.boolean().optional(),
-  populateAccess: z4.unknown().optional(),
-  lean: z4.boolean().optional()
+var rootModelReadOptionsSchema = z5.object({
+  skim: z5.boolean().optional(),
+  includePermissions: z5.boolean().optional(),
+  tryList: z5.boolean().optional(),
+  populateAccess: z5.unknown().optional(),
+  lean: z5.boolean().optional()
 }).passthrough();
-var rootModelCreateArgsSchema = z4.object({
+var rootModelCreateArgsSchema = z5.object({
   select: projectionSchema.optional(),
   populate: populateSchema.optional(),
   tasks: tasksSchema.optional()
 }).passthrough();
-var rootModelCreateOptionsSchema = z4.object({
-  skim: z4.boolean().optional(),
-  includePermissions: z4.boolean().optional(),
-  populateAccess: z4.unknown().optional()
+var rootModelCreateOptionsSchema = z5.object({
+  skim: z5.boolean().optional(),
+  includePermissions: z5.boolean().optional(),
+  populateAccess: z5.unknown().optional()
 }).passthrough();
-var rootModelUpdateArgsSchema = z4.object({
+var rootModelUpdateArgsSchema = z5.object({
   select: projectionSchema.optional(),
   populate: populateSchema.optional(),
   tasks: tasksSchema.optional()
 }).passthrough();
-var rootModelUpdateOptionsSchema = z4.object({
-  skim: z4.boolean().optional(),
-  returningAll: z4.boolean().optional(),
-  includePermissions: z4.boolean().optional(),
-  populateAccess: z4.unknown().optional()
+var rootModelUpdateOptionsSchema = z5.object({
+  skim: z5.boolean().optional(),
+  returningAll: z5.boolean().optional(),
+  includePermissions: z5.boolean().optional(),
+  populateAccess: z5.unknown().optional()
 }).passthrough();
 var rootModelUpsertArgsSchema = rootModelUpdateArgsSchema;
 var rootModelUpsertOptionsSchema = rootModelUpdateOptionsSchema;
-var rootModelSubListArgsSchema = z4.object({
+var rootModelSubListArgsSchema = z5.object({
   select: fieldsSchema.optional()
 }).passthrough();
-var rootModelSubReadArgsSchema = z4.object({
+var rootModelSubReadArgsSchema = z5.object({
   select: fieldsSchema.optional(),
   populate: subPopulateSchema.optional()
 }).passthrough();
-var rootModelCountOptionsSchema = z4.object({
-  access: z4.unknown().optional()
+var rootModelCountOptionsSchema = z5.object({
+  access: z5.unknown().optional()
 }).passthrough();
-var rootDataListArgsSchema = z4.object({
+var rootDataListArgsSchema = z5.object({
   select: projectionSchema.optional(),
-  sort: z4.string().optional(),
-  skip: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  limit: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  page: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
-  pageSize: z4.union([nonNegativeIntegerSchema, positiveIntegerString]).optional()
+  sort: z5.string().optional(),
+  skip: z5.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  limit: z5.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  page: z5.union([nonNegativeIntegerSchema, positiveIntegerString]).optional(),
+  pageSize: z5.union([nonNegativeIntegerSchema, positiveIntegerString]).optional()
 }).passthrough();
-var rootDataListOptionsSchema = z4.object({
-  includeCount: z4.boolean().optional()
+var rootDataListOptionsSchema = z5.object({
+  includeCount: z5.boolean().optional()
 }).passthrough();
-var rootDataReadArgsSchema = z4.object({
+var rootDataReadArgsSchema = z5.object({
   select: projectionSchema.optional()
 }).passthrough();
-var rootModelQueryEntrySchema = z4.union([
-  z4.object({ ...rootEntryBaseSchema, target: z4.literal("model"), op: z4.literal("new") }).passthrough(),
-  z4.object({
+var rootModelQueryEntrySchema = z5.union([
+  z5.object({ ...rootEntryBaseSchema, target: z5.literal("model"), op: z5.literal("new") }).passthrough(),
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("list"),
+    target: z5.literal("model"),
+    op: z5.literal("list"),
     filter: objectOrArraySchema.optional(),
     args: rootModelListArgsSchema.optional(),
     options: rootModelListOptionsSchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("read"),
-    id: z4.string().min(1),
+    target: z5.literal("model"),
+    op: z5.literal("read"),
+    id: z5.string().min(1),
     args: rootModelReadArgsSchema.optional(),
     options: rootModelReadOptionsSchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("read"),
+    target: z5.literal("model"),
+    op: z5.literal("read"),
     filter: objectOrArraySchema,
     args: rootModelReadFilterArgsSchema.optional(),
     options: rootModelReadOptionsSchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("create"),
-    data: z4.unknown(),
+    target: z5.literal("model"),
+    op: z5.literal("create"),
+    data: z5.unknown(),
     args: rootModelCreateArgsSchema.optional(),
     options: rootModelCreateOptionsSchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("update"),
-    id: z4.string().min(1),
-    data: z4.unknown(),
+    target: z5.literal("model"),
+    op: z5.literal("update"),
+    id: z5.string().min(1),
+    data: z5.unknown(),
     args: rootModelUpdateArgsSchema.optional(),
     options: rootModelUpdateOptionsSchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("upsert"),
-    data: z4.record(z4.string(), z4.unknown()),
+    target: z5.literal("model"),
+    op: z5.literal("upsert"),
+    data: z5.record(z5.string(), z5.unknown()),
     args: rootModelUpsertArgsSchema.optional(),
     options: rootModelUpsertOptionsSchema.optional()
   }).passthrough(),
-  z4.object({ ...rootEntryBaseSchema, target: z4.literal("model"), op: z4.literal("delete"), id: z4.string().min(1) }).passthrough(),
-  z4.object({
+  z5.object({ ...rootEntryBaseSchema, target: z5.literal("model"), op: z5.literal("delete"), id: z5.string().min(1) }).passthrough(),
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("subList"),
-    id: z4.string().min(1),
-    sub: z4.string().min(1),
-    filter: z4.record(z4.string(), z4.unknown()).optional(),
+    target: z5.literal("model"),
+    op: z5.literal("subList"),
+    id: z5.string().min(1),
+    sub: z5.string().min(1),
+    filter: z5.record(z5.string(), z5.unknown()).optional(),
     args: rootModelSubListArgsSchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("subRead"),
-    id: z4.string().min(1),
-    sub: z4.string().min(1),
-    subId: z4.string().min(1),
+    target: z5.literal("model"),
+    op: z5.literal("subRead"),
+    id: z5.string().min(1),
+    sub: z5.string().min(1),
+    subId: z5.string().min(1),
     args: rootModelSubReadArgsSchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("subCreate"),
-    id: z4.string().min(1),
-    sub: z4.string().min(1),
-    data: z4.union([z4.record(z4.string(), z4.unknown()), z4.array(z4.record(z4.string(), z4.unknown()))])
+    target: z5.literal("model"),
+    op: z5.literal("subCreate"),
+    id: z5.string().min(1),
+    sub: z5.string().min(1),
+    data: z5.union([z5.record(z5.string(), z5.unknown()), z5.array(z5.record(z5.string(), z5.unknown()))])
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("subUpdate"),
-    id: z4.string().min(1),
-    sub: z4.string().min(1),
-    subId: z4.string().min(1),
-    data: z4.union([z4.record(z4.string(), z4.unknown()), z4.array(z4.record(z4.string(), z4.unknown()))])
+    target: z5.literal("model"),
+    op: z5.literal("subUpdate"),
+    id: z5.string().min(1),
+    sub: z5.string().min(1),
+    subId: z5.string().min(1),
+    data: z5.union([z5.record(z5.string(), z5.unknown()), z5.array(z5.record(z5.string(), z5.unknown()))])
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("subBulkUpdate"),
-    id: z4.string().min(1),
-    sub: z4.string().min(1),
-    data: z4.union([z4.record(z4.string(), z4.unknown()), z4.array(z4.record(z4.string(), z4.unknown()))])
+    target: z5.literal("model"),
+    op: z5.literal("subBulkUpdate"),
+    id: z5.string().min(1),
+    sub: z5.string().min(1),
+    data: z5.union([z5.record(z5.string(), z5.unknown()), z5.array(z5.record(z5.string(), z5.unknown()))])
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("subDelete"),
-    id: z4.string().min(1),
-    sub: z4.string().min(1),
-    subId: z4.string().min(1)
+    target: z5.literal("model"),
+    op: z5.literal("subDelete"),
+    id: z5.string().min(1),
+    sub: z5.string().min(1),
+    subId: z5.string().min(1)
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("distinct"),
-    field: z4.string().min(1),
+    target: z5.literal("model"),
+    op: z5.literal("distinct"),
+    field: z5.string().min(1),
     filter: objectOrArraySchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("model"),
-    op: z4.literal("count"),
+    target: z5.literal("model"),
+    op: z5.literal("count"),
     filter: objectOrArraySchema.optional(),
     options: rootModelCountOptionsSchema.optional()
   }).passthrough()
 ]);
-var rootDataQueryEntrySchema = z4.union([
-  z4.object({
+var rootDataQueryEntrySchema = z5.union([
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("data"),
-    op: z4.literal("list"),
+    target: z5.literal("data"),
+    op: z5.literal("list"),
     filter: objectOrArraySchema.optional(),
     args: rootDataListArgsSchema.optional(),
     options: rootDataListOptionsSchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("data"),
-    op: z4.literal("read"),
-    id: z4.string().min(1),
+    target: z5.literal("data"),
+    op: z5.literal("read"),
+    id: z5.string().min(1),
     args: rootDataReadArgsSchema.optional()
   }).passthrough(),
-  z4.object({
+  z5.object({
     ...rootEntryBaseSchema,
-    target: z4.literal("data"),
-    op: z4.literal("read"),
+    target: z5.literal("data"),
+    op: z5.literal("read"),
     filter: objectOrArraySchema,
     args: rootDataReadArgsSchema.optional()
   }).passthrough()
 ]);
-var rootQuerySchema = z4.array(z4.union([rootModelQueryEntrySchema, rootDataQueryEntrySchema]));
+var rootQuerySchema = z5.array(z5.union([rootModelQueryEntrySchema, rootDataQueryEntrySchema]));
 
 // src/routers/shared.ts
-var parseBooleanString = (str, defaultValue) => str ? str === "true" : defaultValue;
+import { parseBooleanString } from "@web-ts-toolkit/utils";
 
 // src/routers/model-router-collection-routes.ts
 function setModelCollectionRoutes(context) {
   const { router, options } = context;
+  const getAdvancedCreateOpenApiBody = () => {
+    const advancedCreateSchema = context.getRequestSchema("requestSchemas.advancedCreate");
+    const dataSchema = context.getRequestSchema("requestSchemas.advancedCreate.data") ?? getNestedOpenApiSchemaDataSource(advancedCreateSchema);
+    const bodySchema = unwrapNestedOpenApiSchemaSource(
+      context.getRequestSchema("requestSchemas.advancedCreate.default") ?? advancedCreateSchema,
+      advancedCreateBodySchema
+    );
+    return dataSchema ? patchOpenApiObjectSchema(bodySchema, { data: dataSchema }) : bodySchema;
+  };
   router.get("", async (req) => {
     await context.assertAllowed(req, "list");
     const { skip, limit, page, page_size, skim, include_permissions, include_count, include_extra_headers } = parseQuery(requestSchemas.listQuery, req.query);
@@ -3978,6 +4252,13 @@ function setModelCollectionRoutes(context) {
     handleResultError(result);
     return formatModelListResponse(req, result, includeCount, includeExtraHeaders);
   });
+  context.registerOpenApiRoute({
+    method: "get",
+    path: "",
+    operationId: `${context.modelName}.list`,
+    summary: `List ${context.modelName} documents`,
+    query: requestSchemas.listQuery
+  });
   router.post(`/${options.queryRouteSegment}`, async (req) => {
     await context.assertAllowed(req, "list");
     const body = await parseBodyWithSchema(
@@ -4003,6 +4284,13 @@ function setModelCollectionRoutes(context) {
     handleResultError(result);
     return formatModelListResponse(req, result, includeCount, includeExtraHeaders);
   });
+  context.registerOpenApiRoute({
+    method: "post",
+    path: `/${options.queryRouteSegment}`,
+    operationId: `${context.modelName}.listAdvanced`,
+    summary: `Advanced list ${context.modelName} documents`,
+    body: defineOpenApiSchemaResolver(() => context.getRequestSchema("requestSchemas.advancedList") ?? listBodySchema)
+  });
   router.post("", async (req) => {
     await context.assertAllowed(req, "create");
     const { include_permissions } = parseQuery(requestSchemas.createQuery, req.query);
@@ -4016,6 +4304,14 @@ function setModelCollectionRoutes(context) {
     handleResultError(result);
     return formatModelCreatedResponse(result);
   });
+  context.registerOpenApiRoute({
+    method: "post",
+    path: "",
+    operationId: `${context.modelName}.create`,
+    summary: `Create a ${context.modelName} document`,
+    query: requestSchemas.createQuery,
+    body: defineOpenApiSchemaResolver(() => context.getRequestSchema("requestSchemas.create") ?? createBodySchema)
+  });
   router.post(`/${options.mutationRouteSegment}`, async (req) => {
     await context.assertAllowed(req, "create");
     const { include_permissions } = parseQuery(requestSchemas.createQuery, req.query);
@@ -4045,17 +4341,49 @@ function setModelCollectionRoutes(context) {
     handleResultError(result);
     return formatModelCreatedResponse(result);
   });
+  context.registerOpenApiRoute({
+    method: "post",
+    path: `/${options.mutationRouteSegment}`,
+    operationId: `${context.modelName}.createAdvanced`,
+    summary: `Advanced create a ${context.modelName} document`,
+    query: requestSchemas.createQuery,
+    body: defineOpenApiSchemaResolver(getAdvancedCreateOpenApiBody)
+  });
   router.get("/new", async (req) => {
     const svc = context.getPublicService(req);
     const result = await svc._new();
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "get",
+    path: "/new",
+    operationId: `${context.modelName}.new`,
+    summary: `Get a new ${context.modelName} document template`
+  });
 }
 
 // src/routers/model-router-document-routes.ts
 function setModelDocumentRoutes(context) {
   const { router, options, modelName } = context;
+  const getAdvancedUpdateOpenApiBody = () => {
+    const advancedUpdateSchema = context.getRequestSchema("requestSchemas.advancedUpdate");
+    const dataSchema = context.getRequestSchema("requestSchemas.advancedUpdate.data") ?? getNestedOpenApiSchemaDataSource(advancedUpdateSchema);
+    const bodySchema = unwrapNestedOpenApiSchemaSource(
+      context.getRequestSchema("requestSchemas.advancedUpdate.default") ?? advancedUpdateSchema,
+      advancedUpdateBodySchema
+    );
+    return dataSchema ? patchOpenApiObjectSchema(bodySchema, { data: dataSchema }) : bodySchema;
+  };
+  const getAdvancedUpsertOpenApiBody = () => {
+    const advancedUpsertSchema = context.getRequestSchema("requestSchemas.advancedUpsert");
+    const dataSchema = context.getRequestSchema("requestSchemas.advancedUpsert.data") ?? getNestedOpenApiSchemaDataSource(advancedUpsertSchema);
+    const bodySchema = unwrapNestedOpenApiSchemaSource(
+      context.getRequestSchema("requestSchemas.advancedUpsert.default") ?? advancedUpsertSchema,
+      advancedUpsertBodySchema
+    );
+    return dataSchema ? patchOpenApiObjectSchema(bodySchema, { data: dataSchema }) : bodySchema;
+  };
   router.get("/count", async (req) => {
     await context.assertAllowed(req, "count");
     const svc = context.getPublicService(req);
@@ -4063,6 +4391,12 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "get",
+    path: "/count",
+    operationId: `${modelName}.count`,
+    summary: `Count ${modelName} documents`
+  });
   router.post("/count", async (req) => {
     await context.assertAllowed(req, "count");
     const { filter: filter2, options: countOptions = {} } = await parseBodyWithSchema(
@@ -4078,6 +4412,13 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "post",
+    path: "/count",
+    operationId: `${modelName}.countWithFilter`,
+    summary: `Count ${modelName} documents with a filter`,
+    body: defineOpenApiSchemaResolver(() => context.getRequestSchema("requestSchemas.count") ?? countBodySchema)
+  });
   router.get(`/:${options.idParam}`, async (req) => {
     await context.assertAllowed(req, "read");
     const id = parsePathParam(req.params[options.idParam], options.idParam);
@@ -4094,6 +4435,13 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "get",
+    path: `/:${options.idParam}`,
+    operationId: `${modelName}.read`,
+    summary: `Read a ${modelName} document`,
+    query: requestSchemas.readQuery
+  });
   router.post(`/${options.queryRouteSegment}/__filter`, async (req) => {
     await context.assertAllowed(req, "read");
     const body = await parseBodyWithSchema(
@@ -4113,6 +4461,15 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "post",
+    path: `/${options.queryRouteSegment}/__filter`,
+    operationId: `${modelName}.readByFilterAdvanced`,
+    summary: `Read a ${modelName} document by filter`,
+    body: defineOpenApiSchemaResolver(
+      () => context.getRequestSchema("requestSchemas.advancedReadFilter") ?? readFilterBodySchema
+    )
+  });
   router.post(`/${options.queryRouteSegment}/:${options.idParam}`, async (req) => {
     await context.assertAllowed(req, "read");
     const id = parsePathParam(req.params[options.idParam], options.idParam);
@@ -4133,6 +4490,15 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "post",
+    path: `/${options.queryRouteSegment}/:${options.idParam}`,
+    operationId: `${modelName}.readAdvanced`,
+    summary: `Read a ${modelName} document with advanced options`,
+    body: defineOpenApiSchemaResolver(
+      () => context.getRequestSchema("requestSchemas.advancedRead") ?? readByIdBodySchema
+    )
+  });
   router.patch(`/:${options.idParam}`, async (req) => {
     await context.assertAllowed(req, "update");
     const id = parsePathParam(req.params[options.idParam], options.idParam);
@@ -4155,6 +4521,14 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "patch",
+    path: `/:${options.idParam}`,
+    operationId: `${modelName}.update`,
+    summary: `Update a ${modelName} document`,
+    query: requestSchemas.updateQuery,
+    body: defineOpenApiSchemaResolver(() => context.getRequestSchema("requestSchemas.update") ?? updateBodySchema)
+  });
   router.patch(`/${options.mutationRouteSegment}/:${options.idParam}`, async (req) => {
     await context.assertAllowed(req, "update");
     const id = parsePathParam(req.params[options.idParam], options.idParam);
@@ -4187,6 +4561,14 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "patch",
+    path: `/${options.mutationRouteSegment}/:${options.idParam}`,
+    operationId: `${modelName}.updateAdvanced`,
+    summary: `Advanced update a ${modelName} document`,
+    query: requestSchemas.updateQuery,
+    body: defineOpenApiSchemaResolver(getAdvancedUpdateOpenApiBody)
+  });
   router.put(`/`, async (req) => {
     await context.assertAllowed(req, "upsert");
     const svc = context.getPublicService(req);
@@ -4207,6 +4589,14 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return formatModelUpsertResponse(result);
   });
+  context.registerOpenApiRoute({
+    method: "put",
+    path: "/",
+    operationId: `${modelName}.upsert`,
+    summary: `Upsert a ${modelName} document`,
+    query: requestSchemas.upsertQuery,
+    body: defineOpenApiSchemaResolver(() => context.getRequestSchema("requestSchemas.upsert") ?? upsertBodySchema)
+  });
   router.put(`/${options.mutationRouteSegment}`, async (req) => {
     await context.assertAllowed(req, "upsert");
     const svc = context.getPublicService(req);
@@ -4237,6 +4627,14 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return formatModelUpsertResponse(result);
   });
+  context.registerOpenApiRoute({
+    method: "put",
+    path: `/${options.mutationRouteSegment}`,
+    operationId: `${modelName}.upsertAdvanced`,
+    summary: `Advanced upsert a ${modelName} document`,
+    query: requestSchemas.upsertQuery,
+    body: defineOpenApiSchemaResolver(getAdvancedUpsertOpenApiBody)
+  });
   router.delete(`/:${options.idParam}`, async (req) => {
     await context.assertAllowed(req, "delete");
     const id = parsePathParam(req.params[options.idParam], options.idParam);
@@ -4245,6 +4643,12 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "delete",
+    path: `/:${options.idParam}`,
+    operationId: `${modelName}.delete`,
+    summary: `Delete a ${modelName} document`
+  });
   router.get("/distinct/:field", async (req) => {
     await context.assertAllowed(req, "distinct");
     const field = parsePathParam(req.params.field, "field");
@@ -4253,6 +4657,12 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "get",
+    path: "/distinct/:field",
+    operationId: `${modelName}.distinct`,
+    summary: `Get distinct values for a ${modelName} field`
+  });
   router.post("/distinct/:field", async (req) => {
     await context.assertAllowed(req, "distinct");
     const field = parsePathParam(req.params.field, "field");
@@ -4266,6 +4676,13 @@ function setModelDocumentRoutes(context) {
     handleResultError(result);
     return unwrapServiceData(result);
   });
+  context.registerOpenApiRoute({
+    method: "post",
+    path: "/distinct/:field",
+    operationId: `${modelName}.distinctWithFilter`,
+    summary: `Get distinct values for a ${modelName} field with a filter`,
+    body: defineOpenApiSchemaResolver(() => context.getRequestSchema("requestSchemas.distinct") ?? distinctBodySchema)
+  });
 }
 
 // src/routers/model-router-subdocument-routes.ts
@@ -4282,6 +4699,12 @@ function setModelSubDocumentRoutes(context) {
       handleResultError(result);
       return unwrapServiceData(result);
     });
+    context.registerOpenApiRoute({
+      method: "get",
+      path: `/:${context.options.idParam}/${sub}`,
+      operationId: `${context.modelName}.${sub}.list`,
+      summary: `List ${sub} subdocuments`
+    });
     context.router.post(
       `/:${context.options.idParam}/${sub}/${context.options.queryRouteSegment}`,
       async (req) => {
@@ -4298,6 +4721,13 @@ function setModelSubDocumentRoutes(context) {
         return unwrapServiceData(result);
       }
     );
+    context.registerOpenApiRoute({
+      method: "post",
+      path: `/:${context.options.idParam}/${sub}/${context.options.queryRouteSegment}`,
+      operationId: `${context.modelName}.${sub}.listAdvanced`,
+      summary: `Advanced list ${sub} subdocuments`,
+      body: defineOpenApiSchemaResolver(() => context.getRequestSchema("requestSchemas.subList") ?? subListBodySchema)
+    });
     context.router.patch(`/:${context.options.idParam}/${sub}`, async (req) => {
       await context.assertAllowed(req, `subs.${sub}.update`);
       const id = parsePathParam(req.params[context.options.idParam], context.options.idParam);
@@ -4311,6 +4741,15 @@ function setModelSubDocumentRoutes(context) {
       handleResultError(result);
       return unwrapServiceData(result);
     });
+    context.registerOpenApiRoute({
+      method: "patch",
+      path: `/:${context.options.idParam}/${sub}`,
+      operationId: `${context.modelName}.${sub}.bulkUpdate`,
+      summary: `Bulk update ${sub} subdocuments`,
+      body: defineOpenApiSchemaResolver(
+        () => context.getRequestSchema("requestSchemas.subBulkUpdate") ?? subMutationBodySchema
+      )
+    });
     context.router.get(`/:${context.options.idParam}/${sub}/:subId`, async (req) => {
       await context.assertAllowed(req, `subs.${sub}.read`);
       const id = parsePathParam(req.params[context.options.idParam], context.options.idParam);
@@ -4320,6 +4759,12 @@ function setModelSubDocumentRoutes(context) {
       handleResultError(result);
       return unwrapServiceData(result);
     });
+    context.registerOpenApiRoute({
+      method: "get",
+      path: `/:${context.options.idParam}/${sub}/:subId`,
+      operationId: `${context.modelName}.${sub}.read`,
+      summary: `Read a ${sub} subdocument`
+    });
     context.router.post(
       `/:${context.options.idParam}/${sub}/:subId/${context.options.queryRouteSegment}`,
       async (req) => {
@@ -4339,6 +4784,13 @@ function setModelSubDocumentRoutes(context) {
         return unwrapServiceData(result);
       }
     );
+    context.registerOpenApiRoute({
+      method: "post",
+      path: `/:${context.options.idParam}/${sub}/:subId/${context.options.queryRouteSegment}`,
+      operationId: `${context.modelName}.${sub}.readAdvanced`,
+      summary: `Advanced read a ${sub} subdocument`,
+      body: defineOpenApiSchemaResolver(() => context.getRequestSchema("requestSchemas.subRead") ?? subReadBodySchema)
+    });
     context.router.patch(`/:${context.options.idParam}/${sub}/:subId`, async (req) => {
       await context.assertAllowed(req, `subs.${sub}.update`);
       const id = parsePathParam(req.params[context.options.idParam], context.options.idParam);
@@ -4353,6 +4805,15 @@ function setModelSubDocumentRoutes(context) {
       handleResultError(result);
       return unwrapServiceData(result);
     });
+    context.registerOpenApiRoute({
+      method: "patch",
+      path: `/:${context.options.idParam}/${sub}/:subId`,
+      operationId: `${context.modelName}.${sub}.update`,
+      summary: `Update a ${sub} subdocument`,
+      body: defineOpenApiSchemaResolver(
+        () => context.getRequestSchema("requestSchemas.subUpdate") ?? subMutationBodySchema
+      )
+    });
     context.router.post(`/:${context.options.idParam}/${sub}`, async (req) => {
       await context.assertAllowed(req, `subs.${sub}.create`);
       const id = parsePathParam(req.params[context.options.idParam], context.options.idParam);
@@ -4366,6 +4827,15 @@ function setModelSubDocumentRoutes(context) {
       handleResultError(result);
       return formatModelCreatedResponse(result);
     });
+    context.registerOpenApiRoute({
+      method: "post",
+      path: `/:${context.options.idParam}/${sub}`,
+      operationId: `${context.modelName}.${sub}.create`,
+      summary: `Create a ${sub} subdocument`,
+      body: defineOpenApiSchemaResolver(
+        () => context.getRequestSchema("requestSchemas.subCreate") ?? subMutationBodySchema
+      )
+    });
     context.router.delete(`/:${context.options.idParam}/${sub}/:subId`, async (req) => {
       await context.assertAllowed(req, `subs.${sub}.delete`);
       const id = parsePathParam(req.params[context.options.idParam], context.options.idParam);
@@ -4375,9 +4845,25 @@ function setModelSubDocumentRoutes(context) {
       handleResultError(result);
       return unwrapServiceData(result);
     });
+    context.registerOpenApiRoute({
+      method: "delete",
+      path: `/:${context.options.idParam}/${sub}/:subId`,
+      operationId: `${context.modelName}.${sub}.delete`,
+      summary: `Delete a ${sub} subdocument`
+    });
   }
 }
 
+// src/openapi/route-registration.ts
+import { normalizeUrlPath } from "@web-ts-toolkit/utils";
+function registerOpenApiRoute(runtime, basePath, defaultTag, route) {
+  runtime.registerOpenApiRoute({
+    ...route,
+    path: normalizeUrlPath(basePath + route.path),
+    tags: route.tags ?? [defaultTag]
+  });
+}
+
 // src/routers/model-router.ts
 var clientErrors2 = JsonRouter5.clientErrors;
 function setOption(parentKey, optionKey, option) {
@@ -4543,7 +5029,7 @@ var ModelRouter = class {
     this.runtime.setModelOptions(modelName, initialOptions);
     attachRuntimeToModel(modelName, this.runtime);
     this.options = this.runtime.getModelOptions(modelName);
-    this.fullBasePath = normalizeUrlPath(this.options.parentPath + this.options.basePath);
+    this.fullBasePath = normalizeUrlPath2(this.options.parentPath + this.options.basePath);
     this.modelName = modelName;
     this.router = new JsonRouter5(this.options.basePath, createSetCore(this.runtime), accessRouterResponseHandler);
     this.model = new model_default(modelName);
@@ -4568,6 +5054,9 @@ var ModelRouter = class {
     const allowed = await req.macl.isAllowed(this.modelName, access);
     if (!allowed) throw new clientErrors2.UnauthorizedError();
   }
+  registerOpenApiRoute(route) {
+    registerOpenApiRoute(this.runtime, this.fullBasePath, this.modelName, route);
+  }
   ///////////////////////
   // Collection Routes //
   ///////////////////////
@@ -4578,7 +5067,8 @@ var ModelRouter = class {
       options: this.options,
       getRequestSchema: this.getRequestSchema.bind(this),
       getPublicService: this.getPublicService.bind(this),
-      assertAllowed: this.assertAllowed.bind(this)
+      assertAllowed: this.assertAllowed.bind(this),
+      registerOpenApiRoute: this.registerOpenApiRoute.bind(this)
     });
   }
   /////////////////////
@@ -4591,7 +5081,8 @@ var ModelRouter = class {
       options: this.options,
       getRequestSchema: this.getRequestSchema.bind(this),
       getPublicService: this.getPublicService.bind(this),
-      assertAllowed: this.assertAllowed.bind(this)
+      assertAllowed: this.assertAllowed.bind(this),
+      registerOpenApiRoute: this.registerOpenApiRoute.bind(this)
     });
   }
   /////////////////////////
@@ -4604,13 +5095,14 @@ var ModelRouter = class {
       options: this.options,
       getRequestSchema: this.getRequestSchema.bind(this),
       getPublicService: this.getPublicService.bind(this),
-      assertAllowed: this.assertAllowed.bind(this)
+      assertAllowed: this.assertAllowed.bind(this),
+      registerOpenApiRoute: this.registerOpenApiRoute.bind(this)
     });
   }
   logEndpoints() {
     runWithRuntime(this.runtime, () => {
-      forEach7(this.router.endpoints, ({ method, path }) => {
-        logger.info(`${padEnd(method, 6)} ${normalizeUrlPath(this.options.parentPath + path)}`);
+      forEach8(this.router.endpoints, ({ method, path }) => {
+        logger.info(`${padEnd(method, 6)} ${normalizeUrlPath2(this.options.parentPath + path)}`);
       });
     });
   }
@@ -4623,7 +5115,7 @@ var ModelRouter = class {
         value
       );
     }
-    if (arguments.length === 1 && isPlainObject9(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject12(keyOrOptions)) {
       assertMutableRouterOptions("model", keyOrOptions);
       this.runtime.setModelOptions(this.modelName, keyOrOptions);
     }
@@ -4646,7 +5138,7 @@ var ModelRouter = class {
 
 // src/routers/root-router.ts
 import JsonRouter6 from "@web-ts-toolkit/express-json-router";
-import { isNumber as _isNumber, isString as isString10, orderBy as _orderBy } from "@web-ts-toolkit/utils";
+import { isNumber as _isNumber, isString as isString10, normalizeUrlPath as normalizeUrlPath3, orderBy as _orderBy } from "@web-ts-toolkit/utils";
 
 // src/core-data.ts
 var DataCore = class {
@@ -4892,6 +5384,9 @@ var RootRouter = class {
     );
     this.setRoutes();
   }
+  registerOpenApiRoute(route) {
+    registerOpenApiRoute(this.runtime, normalizeUrlPath3(this.basename), "root", route);
+  }
   wrapResult(index, item, result) {
     return {
       index,
@@ -4977,6 +5472,13 @@ var RootRouter = class {
       }
       return _orderBy(results, ["index"], ["asc"]);
     });
+    this.registerOpenApiRoute({
+      method: "post",
+      path: "",
+      operationId: "root.query",
+      summary: "Execute batched model and data operations",
+      body: rootQuerySchema
+    });
   }
   get routes() {
     return this.router.original;
@@ -4985,7 +5487,7 @@ var RootRouter = class {
 
 // src/routers/data-router.ts
 import JsonRouter7 from "@web-ts-toolkit/express-json-router";
-import { isPlainObject as isPlainObject10, isString as isString11, isUndefined as isUndefined3, normalizeUrlPath as normalizeUrlPath2 } from "@web-ts-toolkit/utils";
+import { isPlainObject as isPlainObject13, isString as isString11, isUndefined as isUndefined3, normalizeUrlPath as normalizeUrlPath4 } from "@web-ts-toolkit/utils";
 var clientErrors4 = JsonRouter7.clientErrors;
 function setOption2(parentKey, optionKey, option) {
   const key = isUndefined3(option) ? parentKey : `${parentKey}.${optionKey}`;
@@ -5025,7 +5527,7 @@ var DataRouter = class {
     this.runtime = runtime;
     this.runtime.setDataOptions(dataName, initialOptions);
     this.options = this.runtime.getDataOptions(dataName);
-    this.fullBasePath = normalizeUrlPath2(this.options.parentPath + this.options.basePath);
+    this.fullBasePath = normalizeUrlPath4(this.options.parentPath + this.options.basePath);
     this.dataName = dataName;
     this.router = new JsonRouter7(this.options.basePath, createSetDataCore(this.runtime), accessRouterResponseHandler);
     this.setCollectionRoutes();
@@ -5044,6 +5546,9 @@ var DataRouter = class {
     const allowed = await req.dacl.isAllowed(this.dataName, access);
     if (!allowed) throw new clientErrors4.UnauthorizedError();
   }
+  registerOpenApiRoute(route) {
+    registerOpenApiRoute(this.runtime, this.fullBasePath, this.dataName, route);
+  }
   ///////////////////////
   // Collection Routes //
   ///////////////////////
@@ -5068,6 +5573,13 @@ var DataRouter = class {
       const decoratedResult = await decorateDataListResult(svc, result);
       return formatListResponse(req, decoratedResult, includeCount, includeExtraHeaders);
     });
+    this.registerOpenApiRoute({
+      method: "get",
+      path: "",
+      operationId: `${this.dataName}.list`,
+      summary: `List ${this.dataName} records`,
+      query: requestSchemas.listQuery
+    });
     this.router.post(`/${this.options.queryRouteSegment}`, async (req) => {
       await this.assertAllowed(req, "list");
       let {
@@ -5091,6 +5603,15 @@ var DataRouter = class {
       const decoratedResult = await decorateDataListResult(svc, result);
       return formatListResponse(req, decoratedResult, includeCount, includeExtraHeaders);
     });
+    this.registerOpenApiRoute({
+      method: "post",
+      path: `/${this.options.queryRouteSegment}`,
+      operationId: `${this.dataName}.listAdvanced`,
+      summary: `Advanced list ${this.dataName} records`,
+      body: defineOpenApiSchemaResolver(
+        () => this.getRequestSchema("requestSchemas.advancedList") ?? dataListBodySchema
+      )
+    });
   }
   /////////////////////
   // Document Routes //
@@ -5105,6 +5626,12 @@ var DataRouter = class {
       const decoratedResult = await decorateDataSingleResult(svc, result);
       return decoratedResult.data;
     });
+    this.registerOpenApiRoute({
+      method: "get",
+      path: `/:${this.options.idParam}`,
+      operationId: `${this.dataName}.read`,
+      summary: `Read a ${this.dataName} record`
+    });
     this.router.post(`/${this.options.queryRouteSegment}/__filter`, async (req) => {
       await this.assertAllowed(req, "read");
       let { filter: filter2, select } = await parseBodyWithSchema(
@@ -5118,6 +5645,15 @@ var DataRouter = class {
       const decoratedResult = await decorateDataSingleResult(svc, result);
       return decoratedResult.data;
     });
+    this.registerOpenApiRoute({
+      method: "post",
+      path: `/${this.options.queryRouteSegment}/__filter`,
+      operationId: `${this.dataName}.readByFilter`,
+      summary: `Read a ${this.dataName} record by filter`,
+      body: defineOpenApiSchemaResolver(
+        () => this.getRequestSchema("requestSchemas.advancedReadFilter") ?? dataReadFilterBodySchema
+      )
+    });
     this.router.post(`/${this.options.queryRouteSegment}/:${this.options.idParam}`, async (req) => {
       await this.assertAllowed(req, "read");
       const id = parsePathParam(req.params[this.options.idParam], this.options.idParam);
@@ -5132,13 +5668,22 @@ var DataRouter = class {
       const decoratedResult = await decorateDataSingleResult(svc, result);
       return decoratedResult.data;
     });
+    this.registerOpenApiRoute({
+      method: "post",
+      path: `/${this.options.queryRouteSegment}/:${this.options.idParam}`,
+      operationId: `${this.dataName}.readAdvanced`,
+      summary: `Advanced read a ${this.dataName} record`,
+      body: defineOpenApiSchemaResolver(
+        () => this.getRequestSchema("requestSchemas.advancedRead") ?? dataReadByIdBodySchema
+      )
+    });
   }
   set(keyOrOptions, value) {
     if (arguments.length === 2 && isString11(keyOrOptions)) {
       assertMutableRouterOption("data", keyOrOptions);
       this.runtime.setDataOption(this.dataName, keyOrOptions, value);
     }
-    if (arguments.length === 1 && isPlainObject10(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject13(keyOrOptions)) {
       assertMutableRouterOptions("data", keyOrOptions);
       this.runtime.setDataOptions(this.dataName, keyOrOptions);
     }
@@ -5161,6 +5706,62 @@ var DataRouter = class {
 
 // src/routers/index.ts
 import JsonRouter8 from "@web-ts-toolkit/express-json-router";
+
+// src/openapi/router.ts
+import express from "express";
+import { posix } from "path";
+var escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+var renderDocsHtml = (specPath, title, cssUrl, bundleUrl) => `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${escapeHtml(title)}</title>
+  <link rel="stylesheet" href="${escapeHtml(cssUrl)}" />
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="${escapeHtml(bundleUrl)}"></script>
+  <script>
+    window.ui = SwaggerUIBundle({
+      url: ${JSON.stringify(specPath)},
+      dom_id: '#swagger-ui',
+      deepLinking: true,
+      presets: [SwaggerUIBundle.presets.apis],
+      layout: 'BaseLayout',
+    });
+  </script>
+</body>
+</html>`;
+var getRelativeSpecPath = (docsPath, jsonPath) => {
+  const docsDir = posix.dirname(docsPath.startsWith("/") ? docsPath : `/${docsPath}`);
+  const normalizedJsonPath = jsonPath.startsWith("/") ? jsonPath : `/${jsonPath}`;
+  return posix.relative(docsDir, normalizedJsonPath) || posix.basename(normalizedJsonPath);
+};
+function createOpenApiRouter(runtime, options = {}) {
+  const router = express.Router();
+  const jsonPath = options.jsonPath ?? "/openapi.json";
+  const docsPath = options.docsPath ?? "/docs";
+  const swaggerUiCssUrl = options.swaggerUiCssUrl ?? "https://unpkg.com/swagger-ui-dist@5/swagger-ui.css";
+  const swaggerUiBundleUrl = options.swaggerUiBundleUrl ?? "https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js";
+  const info = {
+    title: options.title ?? "Access Router API",
+    version: options.version ?? "0.0.0",
+    description: options.description,
+    servers: options.servers
+  };
+  router.get(jsonPath, (_req, res) => {
+    res.json(runtime.getOpenApiSpec(info));
+  });
+  if (docsPath !== false) {
+    router.get(docsPath, (_req, res) => {
+      res.type("html").send(renderDocsHtml(getRelativeSpecPath(docsPath, jsonPath), info.title, swaggerUiCssUrl, swaggerUiBundleUrl));
+    });
+  }
+  return router;
+}
+
+// src/routers/index.ts
 var hasRoutes = (input) => {
   return typeof input === "object" && input !== null && "routes" in input;
 };
@@ -5168,7 +5769,7 @@ var resolveRoutes = (input) => {
   return hasRoutes(input) ? input.routes : input;
 };
 function combineRoutes(...inputs) {
-  const router = express.Router();
+  const router = express2.Router();
   inputs.forEach((input) => {
     router.use(resolveRoutes(input));
   });
@@ -5180,7 +5781,7 @@ var accessRouterResponseHandler = JsonRouter8.createHandler({
 });
 accessRouterResponseHandler.errorMessageProvider = function(error) {
   const errorLike = error;
-  console.error(error);
+  logger.error(error);
   return errorLike.message || errorLike._message || String(error);
 };
 
@@ -5207,12 +5808,15 @@ function createRuntimeApi(runtime) {
   wtt2.createDataRouter = function(dataName, options) {
     return new DataRouter(dataName, options, runtime);
   };
+  wtt2.createOpenApiRouter = function(options) {
+    return createOpenApiRouter(runtime, options);
+  };
   wtt2.combineRoutes = combineRoutes;
   wtt2.set = function(keyOrOptions, value) {
     if (arguments.length === 2 && isString12(keyOrOptions)) {
       return runtime.setGlobalOption(keyOrOptions, value);
     }
-    if (arguments.length === 1 && isPlainObject11(keyOrOptions)) {
+    if (arguments.length === 1 && isPlainObject14(keyOrOptions)) {
       return runtime.setGlobalOptions(keyOrOptions);
     }
   };
@@ -5249,6 +5853,7 @@ export {
   acl,
   combineRoutes,
   createAccessRuntime,
+  createOpenApiRouter,
   index_default as default,
   defineRequestSchema,
   fromAjv,