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

package/processors.d.mts

@@ -47,6 +47,97 @@ interface CopyAndDepopulateOptions {
      */
     idField?: string;
 }
+/**
+ * A path copy operation consumed by {@link copyPaths} and the `COPY` task.
+ * Reuses the same `{ src, dest }` shape as {@link ProcessCopy}.
+ */
+type ProcessPathCopy = ProcessCopy;
+/**
+ * A path move operation consumed by {@link movePaths} and the `MOVE` task.
+ * Reuses the same `{ src, dest }` shape as {@link ProcessCopy}.
+ */
+type ProcessPathMove = ProcessCopy;
+/**
+ * A slice operation consumed by {@link sliceArrays} and the `SLICE` task.
+ */
+interface ProcessSlice {
+    /**
+     * Dotted source path of the array to slice. Intermediate segments fan out
+     * across arrays like {@link copyAndDepopulate}. Missing, null, or
+     * non-array leaves are safe no-ops.
+     */
+    src: string;
+    /**
+     * Dotted destination path (relative to the leaf parent) where the sliced
+     * window is written. When omitted, the slice is applied in place at `src`.
+     * Empty-string destinations are safe no-ops.
+     */
+    dest?: string;
+    /**
+     * Number of leading array members to skip. Defaults to `0`. Must be a
+     * non-negative safe integer when present.
+     */
+    skip?: number;
+    /**
+     * Maximum number of array members to keep from `skip`. When omitted, the
+     * tail from `skip` to the end is kept. When present it is clamped to
+     * `maxSlice` (default `1000`). Must be a non-negative safe integer.
+     */
+    limit?: number;
+}
+/**
+ * A count operation consumed by {@link countPaths} and the `COUNT` task.
+ */
+interface ProcessCount {
+    /**
+     * Dotted source path whose size is measured. Arrays measure length, plain
+     * objects measure key count, present scalars count as `1`, and
+     * null/undefined leaves count as `0`. Missing leaves are safe no-ops.
+     */
+    src: string;
+    /**
+     * Dotted destination path (relative to the leaf parent) where the numeric
+     * count is written. Empty destinations are safe no-ops.
+     */
+    dest: string;
+}
+/**
+ * A mask operation consumed by {@link maskPaths} and the `MASK` task.
+ */
+interface ProcessMask {
+    /**
+     * Dotted source path to redact. Each resolved leaf present on its parent
+     * is replaced with `replacement`. Missing leaves are safe no-ops.
+     */
+    src: string;
+    /**
+     * Replacement value written at `src`. Defaults to `'***'` when the key is
+     * absent. An explicitly provided value (including `null`) is used as-is.
+     */
+    replacement?: unknown;
+}
+/**
+ * Shared mutable/clone option for path processors.
+ */
+interface ProcessorOptions {
+    /**
+     * When `true` (default), `docObject` is mutated in place and returned.
+     * When `false`, a deep clone is produced via `cloneDeep` and the input is
+     * left untouched.
+     */
+    mutable?: boolean;
+}
+/**
+ * Options for {@link sliceArrays}.
+ */
+interface SliceProcessorOptions extends ProcessorOptions {
+    /**
+     * Upper bound applied to a client-requested `limit`. Defaults to `1000`,
+     * matching the `listHardLimit` default. Must be a non-negative safe
+     * integer when present.
+     */
+    maxSlice?: number;
+}
 /**
  * Conservative default output for {@link copyAndDepopulate}.
  *
@@ -90,5 +181,64 @@ type CopyAndDepopulateOutput = Record<string, unknown>;
  * `constructor`, or when a populated record is missing the configured id field.
  */
 declare const copyAndDepopulate: <Output extends object = CopyAndDepopulateOutput>(docObject: object, operations: ProcessCopy[], options?: CopyAndDepopulateOptions) => Output;
+/**
+ * Conservative default output for path processors.
+ */
+type ProcessorOutput = Record<string, unknown>;
+/**
+ * Copy the value at `src` to `dest` without modifying `src`.
+ *
+ * Semantics mirror {@link copyAndDepopulate} traversal: intermediate segments
+ * fan out across arrays, missing/null/scalar intermediates are safe no-ops,
+ * and unsafe (`__proto__`, `prototype`, `constructor`) or empty paths are
+ * handled the same way. The copied value is deep-cloned so later tasks in
+ * the chain cannot alias `src` through `dest`. Copying a path onto itself
+ * is a safe no-op.
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const copyPaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessCopy[], options?: ProcessorOptions) => Output;
+/**
+ * Move the value at `src` to `dest` and delete `src`.
+ *
+ * Traversal and safety semantics match {@link copyPaths}. Moving a path onto
+ * itself is a safe no-op. A `dest` nested under the moved leaf (for example
+ * `src: 'a'`, `dest: 'a.b'`) copies without deleting `src` so the freshly
+ * written destination is not removed.
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const movePaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessCopy[], options?: ProcessorOptions) => Output;
+/**
+ * Slice the array at `src` to `[skip, skip + limit)` and write the window to
+ * `dest` (default: in place at `src`).
+ *
+ * Missing, null, or non-array leaves are safe no-ops. `skip` defaults to `0`;
+ * an omitted `limit` keeps the tail from `skip`. A present `limit` is clamped
+ * to `maxSlice` (default `1000`) so client-requested windows stay bounded.
+ *
+ * @throws Error when a path contains an unsafe segment or when
+ * `skip`/`limit`/`maxSlice` is not a non-negative safe integer.
+ */
+declare const sliceArrays: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessSlice[], options?: SliceProcessorOptions) => Output;
+/**
+ * Write the size of `src` to `dest`: array length, plain-object key count,
+ * `0` for null/undefined leaves, and `1` for other present scalars.
+ *
+ * Missing leaves are safe no-ops (no destination is created).
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const countPaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessCount[], options?: ProcessorOptions) => Output;
+/**
+ * Replace the value at `src` with `replacement` (default `'***'`).
+ *
+ * Only existing leaves are redacted; missing paths are safe no-ops and no
+ * new keys are created. Intermediate segments fan out across arrays like
+ * {@link copyAndDepopulate}.
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const maskPaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessMask[], options?: ProcessorOptions) => Output;
 
-export { type CopyAndDepopulateOptions, type CopyAndDepopulateOutput, type ProcessCopy, copyAndDepopulate };
+export { type CopyAndDepopulateOptions, type CopyAndDepopulateOutput, type ProcessCopy, type ProcessCount, type ProcessMask, type ProcessPathCopy, type ProcessPathMove, type ProcessSlice, type ProcessorOptions, type ProcessorOutput, type SliceProcessorOptions, copyAndDepopulate, copyPaths, countPaths, maskPaths, movePaths, sliceArrays };

package/processors.d.ts

@@ -47,6 +47,97 @@ interface CopyAndDepopulateOptions {
      */
     idField?: string;
 }
+/**
+ * A path copy operation consumed by {@link copyPaths} and the `COPY` task.
+ * Reuses the same `{ src, dest }` shape as {@link ProcessCopy}.
+ */
+type ProcessPathCopy = ProcessCopy;
+/**
+ * A path move operation consumed by {@link movePaths} and the `MOVE` task.
+ * Reuses the same `{ src, dest }` shape as {@link ProcessCopy}.
+ */
+type ProcessPathMove = ProcessCopy;
+/**
+ * A slice operation consumed by {@link sliceArrays} and the `SLICE` task.
+ */
+interface ProcessSlice {
+    /**
+     * Dotted source path of the array to slice. Intermediate segments fan out
+     * across arrays like {@link copyAndDepopulate}. Missing, null, or
+     * non-array leaves are safe no-ops.
+     */
+    src: string;
+    /**
+     * Dotted destination path (relative to the leaf parent) where the sliced
+     * window is written. When omitted, the slice is applied in place at `src`.
+     * Empty-string destinations are safe no-ops.
+     */
+    dest?: string;
+    /**
+     * Number of leading array members to skip. Defaults to `0`. Must be a
+     * non-negative safe integer when present.
+     */
+    skip?: number;
+    /**
+     * Maximum number of array members to keep from `skip`. When omitted, the
+     * tail from `skip` to the end is kept. When present it is clamped to
+     * `maxSlice` (default `1000`). Must be a non-negative safe integer.
+     */
+    limit?: number;
+}
+/**
+ * A count operation consumed by {@link countPaths} and the `COUNT` task.
+ */
+interface ProcessCount {
+    /**
+     * Dotted source path whose size is measured. Arrays measure length, plain
+     * objects measure key count, present scalars count as `1`, and
+     * null/undefined leaves count as `0`. Missing leaves are safe no-ops.
+     */
+    src: string;
+    /**
+     * Dotted destination path (relative to the leaf parent) where the numeric
+     * count is written. Empty destinations are safe no-ops.
+     */
+    dest: string;
+}
+/**
+ * A mask operation consumed by {@link maskPaths} and the `MASK` task.
+ */
+interface ProcessMask {
+    /**
+     * Dotted source path to redact. Each resolved leaf present on its parent
+     * is replaced with `replacement`. Missing leaves are safe no-ops.
+     */
+    src: string;
+    /**
+     * Replacement value written at `src`. Defaults to `'***'` when the key is
+     * absent. An explicitly provided value (including `null`) is used as-is.
+     */
+    replacement?: unknown;
+}
+/**
+ * Shared mutable/clone option for path processors.
+ */
+interface ProcessorOptions {
+    /**
+     * When `true` (default), `docObject` is mutated in place and returned.
+     * When `false`, a deep clone is produced via `cloneDeep` and the input is
+     * left untouched.
+     */
+    mutable?: boolean;
+}
+/**
+ * Options for {@link sliceArrays}.
+ */
+interface SliceProcessorOptions extends ProcessorOptions {
+    /**
+     * Upper bound applied to a client-requested `limit`. Defaults to `1000`,
+     * matching the `listHardLimit` default. Must be a non-negative safe
+     * integer when present.
+     */
+    maxSlice?: number;
+}
 /**
  * Conservative default output for {@link copyAndDepopulate}.
  *
@@ -90,5 +181,64 @@ type CopyAndDepopulateOutput = Record<string, unknown>;
  * `constructor`, or when a populated record is missing the configured id field.
  */
 declare const copyAndDepopulate: <Output extends object = CopyAndDepopulateOutput>(docObject: object, operations: ProcessCopy[], options?: CopyAndDepopulateOptions) => Output;
+/**
+ * Conservative default output for path processors.
+ */
+type ProcessorOutput = Record<string, unknown>;
+/**
+ * Copy the value at `src` to `dest` without modifying `src`.
+ *
+ * Semantics mirror {@link copyAndDepopulate} traversal: intermediate segments
+ * fan out across arrays, missing/null/scalar intermediates are safe no-ops,
+ * and unsafe (`__proto__`, `prototype`, `constructor`) or empty paths are
+ * handled the same way. The copied value is deep-cloned so later tasks in
+ * the chain cannot alias `src` through `dest`. Copying a path onto itself
+ * is a safe no-op.
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const copyPaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessCopy[], options?: ProcessorOptions) => Output;
+/**
+ * Move the value at `src` to `dest` and delete `src`.
+ *
+ * Traversal and safety semantics match {@link copyPaths}. Moving a path onto
+ * itself is a safe no-op. A `dest` nested under the moved leaf (for example
+ * `src: 'a'`, `dest: 'a.b'`) copies without deleting `src` so the freshly
+ * written destination is not removed.
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const movePaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessCopy[], options?: ProcessorOptions) => Output;
+/**
+ * Slice the array at `src` to `[skip, skip + limit)` and write the window to
+ * `dest` (default: in place at `src`).
+ *
+ * Missing, null, or non-array leaves are safe no-ops. `skip` defaults to `0`;
+ * an omitted `limit` keeps the tail from `skip`. A present `limit` is clamped
+ * to `maxSlice` (default `1000`) so client-requested windows stay bounded.
+ *
+ * @throws Error when a path contains an unsafe segment or when
+ * `skip`/`limit`/`maxSlice` is not a non-negative safe integer.
+ */
+declare const sliceArrays: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessSlice[], options?: SliceProcessorOptions) => Output;
+/**
+ * Write the size of `src` to `dest`: array length, plain-object key count,
+ * `0` for null/undefined leaves, and `1` for other present scalars.
+ *
+ * Missing leaves are safe no-ops (no destination is created).
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const countPaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessCount[], options?: ProcessorOptions) => Output;
+/**
+ * Replace the value at `src` with `replacement` (default `'***'`).
+ *
+ * Only existing leaves are redacted; missing paths are safe no-ops and no
+ * new keys are created. Intermediate segments fan out across arrays like
+ * {@link copyAndDepopulate}.
+ *
+ * @throws Error when a path contains an unsafe segment.
+ */
+declare const maskPaths: <Output extends object = ProcessorOutput>(docObject: object, operations: ProcessMask[], options?: ProcessorOptions) => Output;
 
-export { type CopyAndDepopulateOptions, type CopyAndDepopulateOutput, type ProcessCopy, copyAndDepopulate };
+export { type CopyAndDepopulateOptions, type CopyAndDepopulateOutput, type ProcessCopy, type ProcessCount, type ProcessMask, type ProcessPathCopy, type ProcessPathMove, type ProcessSlice, type ProcessorOptions, type ProcessorOutput, type SliceProcessorOptions, copyAndDepopulate, copyPaths, countPaths, maskPaths, movePaths, sliceArrays };

package/processors.js

@@ -19,28 +19,68 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/processors.ts
 var processors_exports = {};
 __export(processors_exports, {
-  copyAndDepopulate: () => copyAndDepopulate
+  copyAndDepopulate: () => copyAndDepopulate,
+  copyPaths: () => copyPaths,
+  countPaths: () => countPaths,
+  maskPaths: () => maskPaths,
+  movePaths: () => movePaths,
+  sliceArrays: () => sliceArrays
 });
 module.exports = __toCommonJS(processors_exports);
 var import_utils = require("@web-ts-toolkit/utils");
 var UNSAFE_PATH_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
-function failUnsafeSegment(path) {
+var DEFAULT_MAX_SLICE = 1e3;
+var DEFAULT_MASK_REPLACEMENT = "***";
+function failUnsafeSegment(path, fn = "copyAndDepopulate") {
   throw new Error(
-    `copyAndDepopulate: refusing path '${path}' because it contains an unsafe segment (__proto__, prototype, or constructor).`
+    `${fn}: refusing path '${path}' because it contains an unsafe segment (__proto__, prototype, or constructor).`
   );
 }
 function failMissingId(path) {
   throw new Error(`copyAndDepopulate: path '${path}' resolved to a record missing the configured id field.`);
 }
-function assertSafePath(path) {
+function failInvalidSlice(value, field, fn) {
+  throw new Error(`${fn}: '${field}' must be a non-negative safe integer, received ${String(value)}.`);
+}
+function assertSafePath(path, fn = "copyAndDepopulate") {
   const segs = path.split(".");
   for (const seg of segs) {
     if (seg.length === 0) continue;
     if (UNSAFE_PATH_KEYS.has(seg)) {
-      failUnsafeSegment(path);
+      failUnsafeSegment(path, fn);
     }
   }
 }
+function assertNonNegativeSafeInteger(value, field, fn) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    failInvalidSlice(value, field, fn);
+  }
+}
+function resolveLeafParents(obj, src) {
+  const segs = src.split(".");
+  let targets = [obj];
+  for (let ind = 0; ind < segs.length - 1; ind += 1) {
+    const seg = segs[ind];
+    targets = targets.reduce((ret, target) => {
+      if (!(0, import_utils.isPlainObject)(target)) return ret;
+      const targetObject = target;
+      const next = targetObject[seg];
+      if ((0, import_utils.isArray)(next)) {
+        for (const item of next) {
+          ret.push(item);
+        }
+      } else if (next !== null && next !== void 0) ret.push(next);
+      return ret;
+    }, []);
+  }
+  const leaf = segs[segs.length - 1];
+  const pairs = [];
+  (0, import_utils.forEach)(targets, (target) => {
+    if (!(0, import_utils.isPlainObject)(target)) return;
+    pairs.push({ parent: target, leaf });
+  });
+  return pairs;
+}
 var copyAndDepopulate = (docObject, operations, options = { mutable: true, idField: "_id" }) => {
   const mutable = options.mutable !== false;
   const idField = options.idField ?? "_id";
@@ -104,7 +144,131 @@ var copyAndDepopulate = (docObject, operations, options = { mutable: true, idFie
   });
   return obj;
 };
+var copyPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : (0, import_utils.cloneDeep)(docObject);
+  (0, import_utils.forEach)(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
+    const src = op.src;
+    const dest = op.dest;
+    if (src.length === 0 || dest.length === 0) return;
+    assertSafePath(src, "copyPaths");
+    assertSafePath(dest, "copyPaths");
+    if (src === dest) return;
+    (0, import_utils.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!(0, import_utils.hasOwn)(parent, leaf)) return;
+      (0, import_utils.set)(parent, dest, (0, import_utils.cloneDeep)(parent[leaf]));
+    });
+  });
+  return obj;
+};
+var movePaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : (0, import_utils.cloneDeep)(docObject);
+  (0, import_utils.forEach)(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
+    const src = op.src;
+    const dest = op.dest;
+    if (src.length === 0 || dest.length === 0) return;
+    assertSafePath(src, "movePaths");
+    assertSafePath(dest, "movePaths");
+    if (src === dest) return;
+    (0, import_utils.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!(0, import_utils.hasOwn)(parent, leaf)) return;
+      const value = (0, import_utils.cloneDeep)(parent[leaf]);
+      (0, import_utils.set)(parent, dest, value);
+      if (dest === leaf || dest.startsWith(`${leaf}.`)) return;
+      delete parent[leaf];
+    });
+  });
+  return obj;
+};
+var sliceArrays = (docObject, operations, options = { mutable: true, maxSlice: DEFAULT_MAX_SLICE }) => {
+  const mutable = options.mutable !== false;
+  const maxSlice = options.maxSlice ?? DEFAULT_MAX_SLICE;
+  assertNonNegativeSafeInteger(maxSlice, "maxSlice", "sliceArrays");
+  const obj = mutable ? docObject : (0, import_utils.cloneDeep)(docObject);
+  (0, import_utils.forEach)(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string") return;
+    const src = op.src;
+    if (src.length === 0) return;
+    assertSafePath(src, "sliceArrays");
+    const rawDest = typeof op.dest === "undefined" ? void 0 : op.dest;
+    if (typeof rawDest !== "undefined") {
+      if (typeof rawDest !== "string" || rawDest.length === 0) return;
+      assertSafePath(rawDest, "sliceArrays");
+    }
+    const skip = op.skip ?? 0;
+    assertNonNegativeSafeInteger(skip, "skip", "sliceArrays");
+    let limit;
+    if (typeof op.limit !== "undefined") {
+      assertNonNegativeSafeInteger(op.limit, "limit", "sliceArrays");
+      limit = Math.min(op.limit, maxSlice);
+    }
+    (0, import_utils.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      const leafValue = parent[leaf];
+      if (!(0, import_utils.isArray)(leafValue)) return;
+      const end = typeof limit === "undefined" ? void 0 : skip + limit;
+      const window = leafValue.slice(skip, end);
+      if (typeof rawDest === "undefined") {
+        (0, import_utils.set)(parent, leaf, window);
+      } else {
+        (0, import_utils.set)(parent, rawDest, window);
+      }
+    });
+  });
+  return obj;
+};
+var countPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : (0, import_utils.cloneDeep)(docObject);
+  (0, import_utils.forEach)(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string" || typeof op.dest !== "string") return;
+    const src = op.src;
+    const dest = op.dest;
+    if (src.length === 0 || dest.length === 0) return;
+    assertSafePath(src, "countPaths");
+    assertSafePath(dest, "countPaths");
+    (0, import_utils.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!(0, import_utils.hasOwn)(parent, leaf)) return;
+      const leafValue = parent[leaf];
+      let count;
+      if ((0, import_utils.isArray)(leafValue)) {
+        count = leafValue.length;
+      } else if ((0, import_utils.isPlainObject)(leafValue)) {
+        count = Object.keys(leafValue).length;
+      } else if (leafValue === null || typeof leafValue === "undefined") {
+        count = 0;
+      } else {
+        count = 1;
+      }
+      (0, import_utils.set)(parent, dest, count);
+    });
+  });
+  return obj;
+};
+var maskPaths = (docObject, operations, options = { mutable: true }) => {
+  const mutable = options.mutable !== false;
+  const obj = mutable ? docObject : (0, import_utils.cloneDeep)(docObject);
+  (0, import_utils.forEach)(Array.isArray(operations) ? operations : [], (op) => {
+    if (!op || typeof op.src !== "string") return;
+    const src = op.src;
+    if (src.length === 0) return;
+    assertSafePath(src, "maskPaths");
+    const replacement = Object.prototype.hasOwnProperty.call(op, "replacement") ? op.replacement : DEFAULT_MASK_REPLACEMENT;
+    (0, import_utils.forEach)(resolveLeafParents(obj, src), ({ parent, leaf }) => {
+      if (!(0, import_utils.hasOwn)(parent, leaf)) return;
+      (0, import_utils.set)(parent, leaf, replacement);
+    });
+  });
+  return obj;
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  copyAndDepopulate
+  copyAndDepopulate,
+  copyPaths,
+  countPaths,
+  maskPaths,
+  movePaths,
+  sliceArrays
 });