@web-ts-toolkit/access-router 0.44.0 → 0.46.0

package/advanced.mjs

@@ -56,13 +56,20 @@ import {
   isNil as isNil2,
   isPlainObject as isPlainObject9,
   isString as isString3,
-  keys
+  keys,
+  normalizeUrlPath
 } from "@web-ts-toolkit/utils";
 
 // src/helpers/query.ts
 import { flattenDeep, isNil, isPlainObject, isString, reduce } from "@web-ts-toolkit/utils";
 var DEFAULT_LIST_HARD_LIMIT = 1e3;
 
+// src/helpers/sort-policy.ts
+var fieldPathPattern = /^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)*$/;
+function isValidFieldPath(field) {
+  return typeof field === "string" && fieldPathPattern.test(field);
+}
+
 // src/helpers/index.ts
 import { forEach, isArray, isEmpty, isObject, isPlainObject as isPlainObject3, isString as isString2 } from "@web-ts-toolkit/utils";
 
@@ -645,7 +652,9 @@ var defaultRequestComplexity = {
   maxIncludeCount: 10,
   maxSubQueryCount: 10,
   maxBulkConcurrency: 10,
-  maxHookConcurrency: 10
+  maxHookConcurrency: 10,
+  maxCorrelatedQueries: 100,
+  maxCorrelatedDepth: 5
 };
 var normalizePositiveInteger = (value, fallback) => {
   return Number.isSafeInteger(value) && Number(value) > 0 ? Number(value) : fallback;
@@ -665,6 +674,14 @@ var resolveRequestComplexity = (options) => ({
   maxHookConcurrency: normalizePositiveInteger(
     options?.maxHookConcurrency,
     defaultRequestComplexity.maxHookConcurrency
+  ),
+  maxCorrelatedQueries: normalizePositiveInteger(
+    options?.maxCorrelatedQueries,
+    defaultRequestComplexity.maxCorrelatedQueries
+  ),
+  maxCorrelatedDepth: normalizePositiveInteger(
+    options?.maxCorrelatedDepth,
+    defaultRequestComplexity.maxCorrelatedDepth
   )
 });
 function validateRequestComplexity(value, options, scope = "request") {
@@ -857,6 +874,7 @@ var AccessRuntime = class {
     this.modelAtts = {};
     this.modelInstances = {};
     this.openApiRegistry = new OpenApiRegistry();
+    this.openApiPathPrefix = "";
     this.allowGlobalModelLookup = options.allowGlobalModelLookup ?? false;
     ensureMongooseJsonSchemaInitialized();
   }
@@ -885,7 +903,24 @@ var AccessRuntime = class {
     return global;
   }
   registerOpenApiRoute(route) {
-    this.openApiRegistry.register(route);
+    this.openApiRegistry.register(
+      this.openApiPathPrefix ? { ...route, path: normalizeUrlPath(`${this.openApiPathPrefix}/${route.path}`) } : route
+    );
+  }
+  /**
+   * Compose OpenAPI paths while synchronously constructing mounted routers.
+   * Prefixes apply before collision checks; prior descriptors and Express paths
+   * are unchanged. Nested calls compose and the prior scope is restored even on
+   * failure. The callback must finish registration synchronously (no async work).
+   */
+  withOpenApiPathPrefix(prefix, build) {
+    const previous = this.openApiPathPrefix;
+    this.openApiPathPrefix = normalizeUrlPath(`${previous}/${prefix}`);
+    try {
+      return build();
+    } finally {
+      this.openApiPathPrefix = previous;
+    }
   }
   /**
    * Enable strict OpenAPI collision detection for the remainder of this
@@ -1173,6 +1208,175 @@ var getGlobalOption = (key, defaultValue) => {
 
 // src/validation/common.ts
 import { z as z2 } from "zod";
+import { isPlainObject as isPlainObject11 } from "@web-ts-toolkit/utils";
+
+// src/correlated-includes.ts
+import { cloneDeep, isArray as isArray5, isPlainObject as isPlainObject10 } from "@web-ts-toolkit/utils";
+var PARENT_MARKER_KEY = "$parent";
+var ESCAPE_WRAPPER_KEY = "$escape";
+var SUBQUERY_PAYLOAD_KEYS = /* @__PURE__ */ new Set(["$$sq", "$$date"]);
+var MARKER_FORBIDDEN_OPERATOR_KEYS = /* @__PURE__ */ new Set(["$text", "$where", "$comment"]);
+var LOGICAL_CLAUSE_KEYS = /* @__PURE__ */ new Set(["$and", "$or", "$nor"]);
+var DANGEROUS_PATH_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+var FIELD_SEGMENT_PATTERN = /^[A-Za-z_][A-Za-z0-9_$]*$/;
+var ARRAY_INDEX_SEGMENT_PATTERN = /^(0|[1-9]\d*)$/;
+var ownKeys = (value) => Object.keys(value);
+function isParentRefMarker(value) {
+  return isPlainObject10(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === PARENT_MARKER_KEY;
+}
+function isEscapedParentRef(value) {
+  return isPlainObject10(value) && ownKeys(value).length === 1 && ownKeys(value)[0] === ESCAPE_WRAPPER_KEY;
+}
+function hasMarkerKey(value) {
+  return ownKeys(value).includes(PARENT_MARKER_KEY) || ownKeys(value).includes(ESCAPE_WRAPPER_KEY);
+}
+function isValidParentRefPath(path) {
+  if (typeof path !== "string" || path.length === 0) return false;
+  const segments = path.split(".");
+  return segments.every(
+    (segment) => (FIELD_SEGMENT_PATTERN.test(segment) || ARRAY_INDEX_SEGMENT_PATTERN.test(segment)) && !DANGEROUS_PATH_SEGMENTS.has(segment)
+  );
+}
+function isValidCorrelatedOutputPath(path) {
+  return typeof path === "string" && path.length > 0 && isValidFieldPath(path) && path !== "_id" && !path.startsWith("$");
+}
+function containsParentMarkerShape(value) {
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (current) => {
+    if (isParentRefMarker(current) || isEscapedParentRef(current)) return true;
+    if (isArray5(current)) {
+      if (seen.has(current)) return false;
+      seen.add(current);
+      return current.some(visit);
+    }
+    if (isPlainObject10(current)) {
+      if (seen.has(current)) return false;
+      seen.add(current);
+      if (hasMarkerKey(current)) return true;
+      return Object.values(current).some(visit);
+    }
+    return false;
+  };
+  return visit(value);
+}
+function scanTemplateValueNode(value, path, issues) {
+  if (isEscapedParentRef(value)) {
+    const inner = value.$escape;
+    if (!isParentRefMarker(inner) || typeof inner.$parent !== "string" || (inner.$parent?.length ?? 0) === 0) {
+      issues.push({
+        message: 'Invalid $escape payload: expected { "$escape": { "$parent": "<field>" } }',
+        path
+      });
+    }
+    return;
+  }
+  if (isParentRefMarker(value)) {
+    if (!isValidParentRefPath(value.$parent)) {
+      issues.push({
+        message: `Invalid $parent reference path at ${path.length === 0 ? "#" : path.join(".")}`,
+        path
+      });
+    }
+    return;
+  }
+  if (isPlainObject10(value)) {
+    if (hasMarkerKey(value)) {
+      issues.push({
+        message: 'Malformed $parent reference: objects carrying $parent must be exactly { "$parent": "<field>" }',
+        path
+      });
+      return;
+    }
+    scanTemplateObjectEntries(value, path, issues);
+    return;
+  }
+  if (isArray5(value)) {
+    value.forEach((item, index) => scanTemplateValueNode(item, [...path, index], issues));
+  }
+}
+function scanTemplateObjectEntries(obj, basePath, issues) {
+  for (const [key, child] of Object.entries(obj)) {
+    const childPath = [...basePath, key];
+    if (key === PARENT_MARKER_KEY) {
+      issues.push({ message: "$parent is never a field name in correlated templates", path: childPath });
+      continue;
+    }
+    if (SUBQUERY_PAYLOAD_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        issues.push({
+          message: `Unsupported $parent reference inside ${key}: markers are not resolved in subquery payloads`,
+          path: childPath
+        });
+      }
+      continue;
+    }
+    if (MARKER_FORBIDDEN_OPERATOR_KEYS.has(key)) {
+      if (containsParentMarkerShape(child)) {
+        issues.push({
+          message: `Unsupported $parent reference inside ${key}: markers are not resolved in ${key} values`,
+          path: childPath
+        });
+      }
+      continue;
+    }
+    if (key === "$elemMatch") {
+      if (isParentRefMarker(child) || isEscapedParentRef(child)) {
+        issues.push({
+          message: "Unsupported $parent reference as a direct $elemMatch value",
+          path: childPath
+        });
+        continue;
+      }
+      scanTemplateValueNode(child, childPath, issues);
+      continue;
+    }
+    if (LOGICAL_CLAUSE_KEYS.has(key)) {
+      if (!isArray5(child)) {
+        scanTemplateValueNode(child, childPath, issues);
+        continue;
+      }
+      child.forEach((clause, index) => {
+        const clausePath = [...childPath, index];
+        if (isParentRefMarker(clause) || isEscapedParentRef(clause)) {
+          issues.push({
+            message: `Unsupported $parent reference as a direct ${key} clause: clauses must be filter objects`,
+            path: clausePath
+          });
+          return;
+        }
+        if (isPlainObject10(clause)) {
+          scanTemplateObjectEntries(clause, clausePath, issues);
+        }
+      });
+      continue;
+    }
+    scanTemplateValueNode(child, childPath, issues);
+  }
+}
+function validateCorrelatedFilterTemplate(filter) {
+  const issues = [];
+  if (!isPlainObject10(filter)) {
+    issues.push({ message: "Correlated include filter must be an object", path: [] });
+    return issues;
+  }
+  if (isParentRefMarker(filter) || isEscapedParentRef(filter)) {
+    issues.push({ message: "Correlated include filter must not itself be a $parent reference", path: [] });
+    return issues;
+  }
+  scanTemplateObjectEntries(filter, [], issues);
+  return issues;
+}
+function findArgsMarkerIssue(value, where) {
+  if (value !== void 0 && containsParentMarkerShape(value)) {
+    return {
+      message: `Unsupported $parent reference in ${where}: references are only supported in filter and id positions`,
+      path: []
+    };
+  }
+  return null;
+}
+
+// src/validation/common.ts
 var stringOrStringArray = z2.union([z2.string(), z2.array(z2.string())]);
 var safeIntegerString = (min, message) => z2.string().regex(/^\d+$/, message).refine((value) => Number.isSafeInteger(Number(value)), "Expected a safe integer").refine((value) => Number(value) >= min, message);
 var queryBooleanString = z2.enum(["true", "false"]);
@@ -1233,7 +1437,8 @@ var subPopulateSchema = z2.union([
     select: projectionSchema.optional()
   }).passthrough()
 ]);
-var includeItemSchema = z2.object({
+var legacyIncludeItemSchema = z2.object({
+  mode: z2.enum(["legacy"]).optional(),
   model: z2.string().min(1),
   op: z2.enum(["list", "read", "count"]),
   path: z2.string().min(1),
@@ -1242,8 +1447,139 @@ var includeItemSchema = z2.object({
   foreignField: z2.string().min(1),
   args: z2.unknown().optional().describe("Forwarded to list/read includes. Count includes ignore pagination fields so counts remain exact."),
   options: z2.unknown().optional()
-}).passthrough();
-var includeSchema = z2.union([includeItemSchema, z2.array(includeItemSchema)]);
+}).passthrough().superRefine((entry, ctx) => {
+  if (entry.filter !== void 0 && containsParentMarkerShape(entry.filter)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: 'Legacy includes must not contain $parent markers; use a correlated include (mode: "correlated")',
+      path: ["filter"]
+    });
+  }
+});
+var parentRefSchema = z2.object({ $parent: z2.string().min(1) }).strict().superRefine((value, ctx) => {
+  if (!isValidParentRefPath(value.$parent)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: `Invalid $parent reference path: ${value.$parent}`,
+      path: ["$parent"]
+    });
+  }
+});
+var correlatedIdSchema = z2.union([z2.string().min(1), parentRefSchema]);
+var correlatedFilterSchema = z2.record(z2.string(), z2.unknown()).superRefine((filter, ctx) => {
+  for (const issue of validateCorrelatedFilterTemplate(filter)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: issue.message,
+      path: issue.path.map(String)
+    });
+  }
+});
+var correlatedEmptyOptionsSchema = z2.unknown().refine(
+  (value) => value === void 0 || isPlainObject11(value) && Object.keys(value).length === 0,
+  "Correlated include options must be absent or empty"
+).optional();
+var correlatedPathSchema = z2.string().min(1).superRefine((path, ctx) => {
+  if (!isValidCorrelatedOutputPath(path)) {
+    ctx.addIssue({
+      code: z2.ZodIssueCode.custom,
+      message: `Invalid correlated include output path: ${path}`,
+      path: []
+    });
+  }
+});
+var checkArgsMarkers = (select, sort, ctx) => {
+  const selectIssue = findArgsMarkerIssue(select, "args.select");
+  if (selectIssue) {
+    ctx.addIssue({ code: z2.ZodIssueCode.custom, message: selectIssue.message, path: ["select"] });
+  }
+  const sortIssue = findArgsMarkerIssue(sort, "args.sort");
+  if (sortIssue) {
+    ctx.addIssue({ code: z2.ZodIssueCode.custom, message: sortIssue.message, path: ["sort"] });
+  }
+};
+var correlatedReadArgsSchema = z2.object({
+  select: projectionSchema.optional(),
+  sort: sortSchema.optional(),
+  include: z2.lazy(() => correlatedNestedIncludeSchema).optional()
+}).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
+var correlatedListArgsSchema = z2.object({
+  select: projectionSchema.optional(),
+  sort: sortSchema.optional(),
+  skip: z2.union([nonNegativeIntegerSchema, nonNegativeIntegerString]).optional(),
+  limit: z2.union([positiveIntegerSchema, positiveIntegerString]).optional(),
+  page: z2.union([nonNegativeIntegerSchema, nonNegativeIntegerString]).optional(),
+  pageSize: z2.union([positiveIntegerSchema, positiveIntegerString]).optional(),
+  include: z2.lazy(() => correlatedNestedIncludeSchema).optional()
+}).strict().superRefine((args, ctx) => checkArgsMarkers(args.select, args.sort, ctx));
+var correlatedCountArgsSchema = z2.unknown().refine(
+  (value) => value === void 0 || isPlainObject11(value) && Object.keys(value).length === 0,
+  "Count includes accept no args"
+).optional();
+var correlatedReadByIdSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("read"),
+  path: correlatedPathSchema,
+  id: correlatedIdSchema,
+  args: correlatedReadArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedReadByFilterSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("read"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedReadArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedListSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("list"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedListArgsSchema.optional(),
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var correlatedCountSchema = z2.object({
+  mode: z2.literal("correlated"),
+  model: z2.string().min(1),
+  op: z2.literal("count"),
+  path: correlatedPathSchema,
+  filter: correlatedFilterSchema,
+  args: correlatedCountArgsSchema,
+  options: correlatedEmptyOptionsSchema
+}).strict();
+var includeItemSchema = z2.union([
+  legacyIncludeItemSchema,
+  correlatedReadByIdSchema,
+  correlatedReadByFilterSchema,
+  correlatedListSchema,
+  correlatedCountSchema
+]);
+var correlatedNestedIncludeSchema = z2.union([includeItemSchema, z2.array(includeItemSchema)]);
+var rejectDuplicateCorrelatedPaths = (items, ctx) => {
+  const seen = /* @__PURE__ */ new Set();
+  items.forEach((item, index) => {
+    if (isPlainObject11(item) && item.mode === "correlated" && typeof item.path === "string") {
+      if (seen.has(item.path)) {
+        ctx.addIssue({
+          code: z2.ZodIssueCode.custom,
+          message: `Duplicate correlated include output path: ${item.path}`,
+          path: [index, "path"]
+        });
+      } else {
+        seen.add(item.path);
+      }
+    }
+  });
+};
+var includeSchema = z2.union([
+  includeItemSchema,
+  z2.array(includeItemSchema).superRefine(rejectDuplicateCorrelatedPaths)
+]);
 var fieldsSchema = z2.array(z2.string().min(1));
 var taskSchema = z2.object({
   type: z2.string().min(1),
@@ -1426,19 +1762,12 @@ function fromJoi(schema) {
 }
 function fromAjv(validator) {
   return async (value) => {
-    const outcome = validator(value);
-    if (isThenable(outcome)) {
+    if (validator.$async === true) {
       try {
-        const data = await outcome;
-        if (data === false) {
-          return {
-            success: false,
-            issues: normalizeAjvIssues(validator.errors ?? [])
-          };
-        }
+        const data = await validator(value);
         return {
           success: true,
-          data: data === true ? value : data
+          data
         };
       } catch (error) {
         if (!isAjvValidationError(error)) {
@@ -1446,11 +1775,21 @@ function fromAjv(validator) {
         }
         return {
           success: false,
-          issues: normalizeAjvIssues(error.errors ?? [])
+          issues: normalizeAjvIssues(error.errors)
         };
       }
     }
-    const errorsSnapshot = validator.errors ? [...validator.errors] : [];
+    const outcome = validator(value);
+    if (isThenable(outcome)) {
+      void Promise.resolve(outcome).catch(() => {
+      });
+      throw new TypeError(
+        "fromAjv: promise/thenable validators must declare $async: true and resolve with validated data"
+      );
+    }
+    if (typeof outcome !== "boolean") {
+      throw new TypeError("fromAjv: synchronous validators must return a boolean verdict");
+    }
     if (outcome) {
       return {
         success: true,
@@ -1459,7 +1798,9 @@ function fromAjv(validator) {
     }
     return {
       success: false,
-      issues: normalizeAjvIssues(errorsSnapshot)
+      // Normalize immediately, copying message/path before another call can
+      // replace the errors array or mutate its entries.
+      issues: normalizeAjvIssues(validator.errors ?? [])
     };
   };
 }
@@ -1689,14 +2030,14 @@ function isArkTypeErrors(value) {
   return record.arkKind === "errors" || record[" arkKind"] === "errors";
 }
 function isThenable(value) {
-  return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+  return (typeof value === "object" || typeof value === "function") && value !== null && "then" in value && typeof value.then === "function";
 }
 function isAjvValidationError(error) {
   if (typeof error !== "object" || error === null || !("errors" in error)) {
     return false;
   }
-  const errors = error.errors;
-  return errors == null || Array.isArray(errors);
+  const candidate = error;
+  return candidate.ajv === true && candidate.validation === true && Array.isArray(candidate.errors);
 }
 function isVineValidationError(error) {
   if (typeof error !== "object" || error === null || !("messages" in error)) {
@@ -1780,7 +2121,7 @@ var listBodySchema = z3.object({
 }).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query"]));
 var countBodySchema = z3.object({
   filter: objectOrArraySchema.optional()
-}).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query", "access", "options"]));
+}).passthrough().superRefine((body, ctx) => rejectKeys(body, ctx, ["query", "access", "options", "include"]));
 var readFilterBodySchema = z3.object({
   filter: objectOrArraySchema.optional(),
   select: projectionSchema.optional(),