@web-ts-toolkit/access-router 0.32.0 → 0.34.0

package/processors.d.mts

@@ -1,11 +1,82 @@
+/**
+ * A depopulate copy operation consumed by {@link copyAndDepopulate}.
+ */
 interface ProcessCopy {
+    /**
+     * Dotted source path on `docObject` whose populated value should be
+     * relocated to {@link ProcessCopy.dest}. {@link copyAndDepopulate} walks
+     * intermediate segments and, at the leaf, copies the original objects to
+     * {@link ProcessCopy.dest} and replaces the leaf with the `idField`
+     * value(s) of those objects.
+     *
+     * Examples:
+     *   `src: 'items'`        -> depopulate `docObject.items`
+     *   `src: 'pear.items'`   -> depopulate `docObject.pear.items`
+     *
+     * Empty strings are treated as safe no-ops. Unsafe segments
+     * (`__proto__`, `prototype`, `constructor`) throw a descriptive
+     * `ProcessorPathError`.
+     */
     src: string;
+    /**
+     * Dotted destination path on `docObject` where the moved objects will be
+     * written. Unsafe segments (`__proto__`, `prototype`, `constructor`)
+     * throw a descriptive `ProcessorPathError`. Empty and missing
+     * destinations are safe no-ops.
+     */
     dest: string;
 }
+/**
+ * Options for {@link copyAndDepopulate}.
+ */
 interface CopyAndDepopulateOptions {
+    /**
+     * 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. Both modes produce value-identical output; only object
+     * identity differs.
+     */
     mutable?: boolean;
+    /**
+     * Identifier field pulled from each relocated record to replace the
+     * original populated value. Defaults to `'_id'`.
+     *
+     * For nested populated arrays, every leaf record must carry this field.
+     * Records missing the id field throw a descriptive `ProcessorPathError`.
+     * Primitive array members (non-record scalars) cannot be depopulated and
+     * are left in place as a safe no-op.
+     */
     idField?: string;
 }
+/**
+ * Hardened processor that relocates populated documents to a destination
+ * path and replaces the original location with their proposed
+ * "depopulated" form: a single id for plain-object values, or an array of
+ * ids for populated arrays.
+ *
+ * Key semantics:
+ * - Operations run sequentially in the order supplied. Each operation
+ *   sees the state produced by the previous one. Two operations that
+ *   reference the same `src` therefore intentionally chain - the second
+ *   operation will find the id value/type left by the first and treat it
+ *   as a safe no-op if it can no longer be depopulated (e.g. it is now an
+ *   array of primitive ids rather than records).
+ * - Missing, null, or scalar intermediate segments in `src` are safe
+ *   no-ops: nothing is copied, nothing is replaced, and no error is
+ *   thrown. The object identity of intermediates is unchanged.
+ * - An array leaf whose members are all plain records is depopulated to
+ *   an array of ids. Records missing the id field throw a descriptive
+ *   error; primitive/scalar array members prevent depopulation and the
+ *   leaf is left in place as a safe no-op.
+ * - A plain-object leaf is depopulated to a single id value; a missing id
+ *   field throws a descriptive error.
+ * - `__proto__`, `prototype`, and `constructor` segments in either `src`
+ *   or `dest` throw a descriptive error. No operation can mutate
+ *   `Object.prototype` or any object's prototype.
+ * - Empty `src` or `dest` strings are safe no-ops.
+ *
+ * @typeParam T - Object shape produced by the depopulation.
+ */
 declare const copyAndDepopulate: <T extends object>(docObject: T, operations: ProcessCopy[], options?: CopyAndDepopulateOptions) => T;
 
-export { copyAndDepopulate };
+export { type CopyAndDepopulateOptions, type ProcessCopy, copyAndDepopulate };

package/processors.d.ts

@@ -1,11 +1,82 @@
+/**
+ * A depopulate copy operation consumed by {@link copyAndDepopulate}.
+ */
 interface ProcessCopy {
+    /**
+     * Dotted source path on `docObject` whose populated value should be
+     * relocated to {@link ProcessCopy.dest}. {@link copyAndDepopulate} walks
+     * intermediate segments and, at the leaf, copies the original objects to
+     * {@link ProcessCopy.dest} and replaces the leaf with the `idField`
+     * value(s) of those objects.
+     *
+     * Examples:
+     *   `src: 'items'`        -> depopulate `docObject.items`
+     *   `src: 'pear.items'`   -> depopulate `docObject.pear.items`
+     *
+     * Empty strings are treated as safe no-ops. Unsafe segments
+     * (`__proto__`, `prototype`, `constructor`) throw a descriptive
+     * `ProcessorPathError`.
+     */
     src: string;
+    /**
+     * Dotted destination path on `docObject` where the moved objects will be
+     * written. Unsafe segments (`__proto__`, `prototype`, `constructor`)
+     * throw a descriptive `ProcessorPathError`. Empty and missing
+     * destinations are safe no-ops.
+     */
     dest: string;
 }
+/**
+ * Options for {@link copyAndDepopulate}.
+ */
 interface CopyAndDepopulateOptions {
+    /**
+     * 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. Both modes produce value-identical output; only object
+     * identity differs.
+     */
     mutable?: boolean;
+    /**
+     * Identifier field pulled from each relocated record to replace the
+     * original populated value. Defaults to `'_id'`.
+     *
+     * For nested populated arrays, every leaf record must carry this field.
+     * Records missing the id field throw a descriptive `ProcessorPathError`.
+     * Primitive array members (non-record scalars) cannot be depopulated and
+     * are left in place as a safe no-op.
+     */
     idField?: string;
 }
+/**
+ * Hardened processor that relocates populated documents to a destination
+ * path and replaces the original location with their proposed
+ * "depopulated" form: a single id for plain-object values, or an array of
+ * ids for populated arrays.
+ *
+ * Key semantics:
+ * - Operations run sequentially in the order supplied. Each operation
+ *   sees the state produced by the previous one. Two operations that
+ *   reference the same `src` therefore intentionally chain - the second
+ *   operation will find the id value/type left by the first and treat it
+ *   as a safe no-op if it can no longer be depopulated (e.g. it is now an
+ *   array of primitive ids rather than records).
+ * - Missing, null, or scalar intermediate segments in `src` are safe
+ *   no-ops: nothing is copied, nothing is replaced, and no error is
+ *   thrown. The object identity of intermediates is unchanged.
+ * - An array leaf whose members are all plain records is depopulated to
+ *   an array of ids. Records missing the id field throw a descriptive
+ *   error; primitive/scalar array members prevent depopulation and the
+ *   leaf is left in place as a safe no-op.
+ * - A plain-object leaf is depopulated to a single id value; a missing id
+ *   field throws a descriptive error.
+ * - `__proto__`, `prototype`, and `constructor` segments in either `src`
+ *   or `dest` throw a descriptive error. No operation can mutate
+ *   `Object.prototype` or any object's prototype.
+ * - Empty `src` or `dest` strings are safe no-ops.
+ *
+ * @typeParam T - Object shape produced by the depopulation.
+ */
 declare const copyAndDepopulate: <T extends object>(docObject: T, operations: ProcessCopy[], options?: CopyAndDepopulateOptions) => T;
 
-export { copyAndDepopulate };
+export { type CopyAndDepopulateOptions, type ProcessCopy, copyAndDepopulate };

package/processors.js

@@ -23,29 +23,77 @@ __export(processors_exports, {
 });
 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) {
+  throw new Error(
+    `copyAndDepopulate: 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) {
+  const segs = path.split(".");
+  for (const seg of segs) {
+    if (seg.length === 0) continue;
+    if (UNSAFE_PATH_KEYS.has(seg)) {
+      failUnsafeSegment(path);
+    }
+  }
+}
 var copyAndDepopulate = (docObject, operations, options = { mutable: true, idField: "_id" }) => {
-  const obj = (0, import_utils.get)(options, "mutable", true) ? docObject : (0, import_utils.cloneDeep)(docObject);
-  const idField = (0, import_utils.get)(options, "idField", "_id");
-  (0, import_utils.forEach)((0, import_utils.castArray)(operations), (op) => {
-    if (!op.src || !op.dest) return;
+  const mutable = options.mutable !== false;
+  const idField = options.idField ?? "_id";
+  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);
+    assertSafePath(dest);
     let targets = [obj];
-    const segs = op.src.split(".");
+    const segs = src.split(".");
     (0, import_utils.forEach)(segs, (seg, ind) => {
       if (segs.length === ind + 1) {
         (0, import_utils.forEach)(targets, (target) => {
+          if (!(0, import_utils.isPlainObject)(target)) return;
           const targetObject = target;
-          (0, import_utils.set)(targetObject, op.dest, (0, import_utils.get)(targetObject, seg));
-          (0, import_utils.set)(
-            targetObject,
-            seg,
-            (0, import_utils.isArray)(targetObject[seg]) ? (0, import_utils.map)(targetObject[seg], idField) : (0, import_utils.get)(targetObject, `${seg}.${idField}`)
-          );
+          const leaf = targetObject[seg];
+          const sourceForDest = leaf;
+          let depopulated;
+          if ((0, import_utils.isArray)(leaf)) {
+            if (leaf.length === 0) {
+              depopulated = [];
+            } else if (leaf.every((item) => (0, import_utils.isPlainObject)(item))) {
+              depopulated = (0, import_utils.map)(leaf, idField).map((id, i) => {
+                if (id === void 0) {
+                  failMissingId(`${src}[${i}]`);
+                }
+                return id;
+              });
+            } else {
+              return;
+            }
+          } else if ((0, import_utils.isPlainObject)(leaf)) {
+            const id = (0, import_utils.get)(leaf, idField);
+            if (id === void 0) {
+              failMissingId(src);
+            }
+            depopulated = id;
+          } else {
+            return;
+          }
+          (0, import_utils.set)(targetObject, dest, sourceForDest);
+          (0, import_utils.set)(targetObject, seg, depopulated);
         });
       } else {
         targets = targets.reduce((ret, target) => {
+          if (!(0, import_utils.isPlainObject)(target)) return ret;
           const targetObject = target;
-          if ((0, import_utils.isArray)(targetObject[seg])) ret.push(...targetObject[seg]);
-          else ret.push(targetObject[seg]);
+          const next = targetObject[seg];
+          if ((0, import_utils.isArray)(next)) ret.push(...next);
+          else if (next !== null && next !== void 0) ret.push(next);
           return ret;
         }, []);
       }

package/processors.mjs

@@ -1,28 +1,76 @@
 // src/processors.ts
-import { castArray, cloneDeep, forEach, get, isArray, map, set } from "@web-ts-toolkit/utils";
+import { cloneDeep, forEach, get, isArray, isPlainObject, map, set } from "@web-ts-toolkit/utils";
+var UNSAFE_PATH_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+function failUnsafeSegment(path) {
+  throw new Error(
+    `copyAndDepopulate: 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) {
+  const segs = path.split(".");
+  for (const seg of segs) {
+    if (seg.length === 0) continue;
+    if (UNSAFE_PATH_KEYS.has(seg)) {
+      failUnsafeSegment(path);
+    }
+  }
+}
 var copyAndDepopulate = (docObject, operations, options = { mutable: true, idField: "_id" }) => {
-  const obj = get(options, "mutable", true) ? docObject : cloneDeep(docObject);
-  const idField = get(options, "idField", "_id");
-  forEach(castArray(operations), (op) => {
-    if (!op.src || !op.dest) return;
+  const mutable = options.mutable !== false;
+  const idField = options.idField ?? "_id";
+  const obj = mutable ? docObject : cloneDeep(docObject);
+  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);
+    assertSafePath(dest);
     let targets = [obj];
-    const segs = op.src.split(".");
+    const segs = src.split(".");
     forEach(segs, (seg, ind) => {
       if (segs.length === ind + 1) {
         forEach(targets, (target) => {
+          if (!isPlainObject(target)) return;
           const targetObject = target;
-          set(targetObject, op.dest, get(targetObject, seg));
-          set(
-            targetObject,
-            seg,
-            isArray(targetObject[seg]) ? map(targetObject[seg], idField) : get(targetObject, `${seg}.${idField}`)
-          );
+          const leaf = targetObject[seg];
+          const sourceForDest = leaf;
+          let depopulated;
+          if (isArray(leaf)) {
+            if (leaf.length === 0) {
+              depopulated = [];
+            } else if (leaf.every((item) => isPlainObject(item))) {
+              depopulated = map(leaf, idField).map((id, i) => {
+                if (id === void 0) {
+                  failMissingId(`${src}[${i}]`);
+                }
+                return id;
+              });
+            } else {
+              return;
+            }
+          } else if (isPlainObject(leaf)) {
+            const id = get(leaf, idField);
+            if (id === void 0) {
+              failMissingId(src);
+            }
+            depopulated = id;
+          } else {
+            return;
+          }
+          set(targetObject, dest, sourceForDest);
+          set(targetObject, seg, depopulated);
         });
       } else {
         targets = targets.reduce((ret, target) => {
+          if (!isPlainObject(target)) return ret;
           const targetObject = target;
-          if (isArray(targetObject[seg])) ret.push(...targetObject[seg]);
-          else ret.push(targetObject[seg]);
+          const next = targetObject[seg];
+          if (isArray(next)) ret.push(...next);
+          else if (next !== null && next !== void 0) ret.push(next);
           return ret;
         }, []);
       }