@rimbu/deep 1.1.0 → 2.0.1

package/dist/cjs/deep.cjs

@@ -1,590 +1,211 @@
 "use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/deep.mts
-var deep_exports = {};
-__export(deep_exports, {
-  getAt: () => getAt,
-  getAtWith: () => getAtWith,
-  match: () => match,
-  matchAt: () => matchAt,
-  matchAtWith: () => matchAtWith,
-  matchWith: () => matchWith,
-  patch: () => patch,
-  patchAt: () => patchAt,
-  patchAtWith: () => patchAtWith,
-  patchWith: () => patchWith,
-  protect: () => protect,
-  select: () => select,
-  selectAt: () => selectAt,
-  selectAtWith: () => selectAtWith,
-  selectWith: () => selectWith,
-  withType: () => withType
-});
-module.exports = __toCommonJS(deep_exports);
-
-// src/path.mts
-var Path;
-((Path2) => {
-  Path2.stringSplitRegex = /\?\.|\.|\[|\]/g;
-  function stringSplit(path) {
-    return path.split(Path2.stringSplitRegex);
-  }
-  Path2.stringSplit = stringSplit;
-})(Path || (Path = {}));
-function getAt(source, path) {
-  if (path === "") {
-    return source;
-  }
-  const items = Path.stringSplit(path);
-  let result = source;
-  for (const item of items) {
-    if (void 0 === item || item === "" || item === "[") {
-      continue;
-    }
-    if (void 0 === result || null === result) {
-      return void 0;
-    }
-    result = result[item];
-  }
-  return result;
-}
-function patchAt(source, path, patchItem) {
-  if (path === "") {
-    return deep_exports.patch(source, patchItem);
-  }
-  const items = Path.stringSplit(path);
-  function createPatchPart(index, target) {
-    if (index === items.length) {
-      return patchItem;
-    }
-    const item = items[index];
-    if (void 0 === item || item === "") {
-      return createPatchPart(index + 1, target);
-    }
-    if (item === "[") {
-      return createPatchPart(index + 1, target);
-    }
-    const result = {
-      [item]: createPatchPart(index + 1, target[item])
-    };
-    if (Array.isArray(target)) {
-      return result;
-    }
-    return [result];
-  }
-  return deep_exports.patch(source, createPatchPart(0, source));
-}
-
-// src/match.mts
-var import_base = require("@rimbu/base");
-function match(source, matcher, failureLog) {
-  return matchEntry(source, source, source, matcher, failureLog);
-}
-function matchEntry(source, parent, root, matcher, failureLog) {
-  if (Object.is(source, matcher)) {
-    return true;
-  }
-  if (matcher === null || matcher === void 0) {
-    failureLog?.push(
-      `value ${JSON.stringify(source)} did not match matcher ${matcher}`
-    );
-    return false;
-  }
-  if (typeof source === "function") {
-    const result = Object.is(source, matcher);
-    if (!result) {
-      failureLog?.push(
-        `both value and matcher are functions, but they do not have the same reference`
-      );
-    }
-    return result;
-  }
-  if (typeof matcher === "function") {
-    const matcherResult = matcher(source, parent, root);
-    if (typeof matcherResult === "boolean") {
-      if (!matcherResult) {
-        failureLog?.push(
-          `function matcher returned false for value ${JSON.stringify(source)}`
-        );
-      }
-      return matcherResult;
-    }
-    return matchEntry(source, parent, root, matcherResult, failureLog);
-  }
-  if ((0, import_base.isPlainObj)(source)) {
-    return matchPlainObj(source, parent, root, matcher, failureLog);
-  }
-  if (Array.isArray(source)) {
-    return matchArr(source, parent, root, matcher, failureLog);
-  }
-  failureLog?.push(
-    `value ${JSON.stringify(
-      source
-    )} does not match given matcher ${JSON.stringify(matcher)}`
-  );
-  return false;
-}
-function matchArr(source, parent, root, matcher, failureLog) {
-  if (Array.isArray(matcher)) {
-    const length = source.length;
-    if (length !== matcher.length) {
-      failureLog?.push(
-        `array lengths are not equal: value length ${source.length} !== matcher length ${matcher.length}`
-      );
-      return false;
-    }
-    let index = -1;
-    while (++index < length) {
-      if (!matchEntry(source[index], source, root, matcher[index], failureLog)) {
-        failureLog?.push(
-          `index ${index} does not match with value ${JSON.stringify(
-            source[index]
-          )} and matcher ${matcher[index]}`
-        );
-        return false;
-      }
-    }
-    return true;
-  }
-  if (typeof matcher === "object" && null !== matcher) {
-    if (`every` in matcher) {
-      return matchCompound(
-        source,
-        parent,
-        root,
-        ["every", ...matcher.every],
-        failureLog
-      );
-    }
-    if (`some` in matcher) {
-      return matchCompound(
-        source,
-        parent,
-        root,
-        ["some", ...matcher.some],
-        failureLog
-      );
-    }
-    if (`none` in matcher) {
-      return matchCompound(
-        source,
-        parent,
-        root,
-        ["none", ...matcher.none],
-        failureLog
-      );
-    }
-    if (`single` in matcher) {
-      return matchCompound(
-        source,
-        parent,
-        root,
-        ["single", ...matcher.single],
-        failureLog
-      );
-    }
-    if (`someItem` in matcher) {
-      return matchTraversal(
-        source,
-        root,
-        "someItem",
-        matcher.someItem,
-        failureLog
-      );
-    }
-    if (`everyItem` in matcher) {
-      return matchTraversal(
-        source,
-        root,
-        "everyItem",
-        matcher.everyItem,
-        failureLog
-      );
-    }
-    if (`noneItem` in matcher) {
-      return matchTraversal(
-        source,
-        root,
-        "noneItem",
-        matcher.noneItem,
-        failureLog
-      );
-    }
-    if (`singleItem` in matcher) {
-      return matchTraversal(
-        source,
-        root,
-        "singleItem",
-        matcher.singleItem,
-        failureLog
-      );
-    }
-  }
-  for (const index in matcher) {
-    const matcherAtIndex = matcher[index];
-    if (!(index in source)) {
-      failureLog?.push(
-        `index ${index} does not exist in source ${JSON.stringify(
-          source
-        )} but should match matcher ${JSON.stringify(matcherAtIndex)}`
-      );
-      return false;
-    }
-    const result = matchEntry(
-      source[index],
-      source,
-      root,
-      matcherAtIndex,
-      failureLog
-    );
-    if (!result) {
-      failureLog?.push(
-        `index ${index} does not match with value ${JSON.stringify(
-          source[index]
-        )} and matcher ${JSON.stringify(matcherAtIndex)}`
-      );
-      return false;
-    }
-  }
-  return true;
-}
-function matchPlainObj(source, parent, root, matcher, failureLog) {
-  if (Array.isArray(matcher)) {
-    return matchCompound(source, parent, root, matcher, failureLog);
-  }
-  for (const key in matcher) {
-    if (!(key in source)) {
-      failureLog?.push(
-        `key ${key} is specified in matcher but not present in value ${JSON.stringify(
-          source
-        )}`
-      );
-      return false;
-    }
-    const result = matchEntry(
-      source[key],
-      source,
-      root,
-      matcher[key],
-      failureLog
-    );
-    if (!result) {
-      failureLog?.push(
-        `key ${key} does not match in value ${JSON.stringify(
-          source[key]
-        )} with matcher ${JSON.stringify(matcher[key])}`
-      );
-      return false;
-    }
-  }
-  return true;
-}
-function matchCompound(source, parent, root, compound, failureLog) {
-  const matchType = compound[0];
-  const length = compound.length;
-  let index = 0;
-  switch (matchType) {
-    case "every": {
-      while (++index < length) {
-        const result = matchEntry(
-          source,
-          parent,
-          root,
-          compound[index],
-          failureLog
-        );
-        if (!result) {
-          failureLog?.push(
-            `in compound "every": match at index ${index} failed`
-          );
-          return false;
-        }
-      }
-      return true;
-    }
-    case "none": {
-      while (++index < length) {
-        const result = matchEntry(
-          source,
-          parent,
-          root,
-          compound[index],
-          failureLog
-        );
-        if (result) {
-          failureLog?.push(
-            `in compound "none": match at index ${index} succeeded`
-          );
-          return false;
-        }
-      }
-      return true;
-    }
-    case "single": {
-      let onePassed = false;
-      while (++index < length) {
-        const result = matchEntry(
-          source,
-          parent,
-          root,
-          compound[index],
-          failureLog
-        );
-        if (result) {
-          if (onePassed) {
-            failureLog?.push(
-              `in compound "single": multiple matches succeeded`
-            );
-            return false;
-          }
-          onePassed = true;
-        }
-      }
-      if (!onePassed) {
-        failureLog?.push(`in compound "single": no matches succeeded`);
-      }
-      return onePassed;
-    }
-    case "some": {
-      while (++index < length) {
-        const result = matchEntry(
-          source,
-          parent,
-          root,
-          compound[index],
-          failureLog
-        );
-        if (result) {
-          return true;
-        }
-      }
-      failureLog?.push(`in compound "some": no matches succeeded`);
-      return false;
-    }
-  }
-}
-function matchTraversal(source, root, matchType, matcher, failureLog) {
-  let index = -1;
-  const length = source.length;
-  switch (matchType) {
-    case "someItem": {
-      while (++index < length) {
-        if (matchEntry(source[index], source, root, matcher, failureLog)) {
-          return true;
-        }
-      }
-      failureLog?.push(
-        `in array traversal "someItem": no items matched given matcher`
-      );
-      return false;
-    }
-    case "everyItem": {
-      while (++index < length) {
-        if (!matchEntry(source[index], source, root, matcher, failureLog)) {
-          failureLog?.push(
-            `in array traversal "everyItem": at least one item did not match given matcher`
-          );
-          return false;
-        }
-      }
-      return true;
-    }
-    case "noneItem": {
-      while (++index < length) {
-        if (matchEntry(source[index], source, root, matcher, failureLog)) {
-          failureLog?.push(
-            `in array traversal "noneItem": at least one item matched given matcher`
-          );
-          return false;
-        }
-      }
-      return true;
-    }
-    case "singleItem": {
-      let singleMatched = false;
-      while (++index < length) {
-        if (matchEntry(source[index], source, root, matcher, failureLog)) {
-          if (singleMatched) {
-            failureLog?.push(
-              `in array traversal "singleItem": more than one item matched given matcher`
-            );
-            return false;
-          }
-          singleMatched = true;
-        }
-      }
-      if (!singleMatched) {
-        failureLog?.push(
-          `in array traversal "singleItem": no item matched given matcher`
-        );
-        return false;
-      }
-      return true;
-    }
-  }
-}
-
-// src/patch.mts
-var import_base2 = require("@rimbu/base");
-function patch(value, patchItem) {
-  return patchEntry(value, value, value, patchItem);
-}
-function patchEntry(value, parent, root, patchItem) {
-  if (Object.is(value, patchItem)) {
-    return value;
-  }
-  if (typeof value === "function") {
-    return patchItem;
-  }
-  if (typeof patchItem === "function") {
-    const item = patchItem(value, parent, root);
-    return patchEntry(value, parent, root, item);
-  }
-  if ((0, import_base2.isPlainObj)(value)) {
-    return patchPlainObj(value, root, patchItem);
-  }
-  if (Array.isArray(value)) {
-    return patchArr(value, root, patchItem);
-  }
-  return patchItem;
-}
-function patchPlainObj(value, root, patchItem) {
-  if (!Array.isArray(patchItem)) {
-    return patchItem;
-  }
-  const result = { ...value };
-  let anyChange = false;
-  for (const entry of patchItem) {
-    const currentRoot = value === root ? { ...result } : root;
-    const parent = { ...result };
-    for (const key in entry) {
-      const currentValue = result[key];
-      const newValue = patchEntry(
-        currentValue,
-        parent,
-        currentRoot,
-        entry[key]
-      );
-      if (!Object.is(currentValue, newValue)) {
-        anyChange = true;
-        result[key] = newValue;
-      }
-    }
-  }
-  if (anyChange) {
-    return result;
-  }
-  return value;
-}
-function patchArr(value, root, patchItem) {
-  if (Array.isArray(patchItem)) {
-    return patchItem;
-  }
-  const result = [...value];
-  let anyChange = false;
-  for (const index in patchItem) {
-    const numIndex = index;
-    const currentValue = result[numIndex];
-    const newValue = patchEntry(
-      currentValue,
-      value,
-      root,
-      patchItem[index]
-    );
-    if (!Object.is(newValue, currentValue)) {
-      anyChange = true;
-      result[numIndex] = newValue;
-    }
-  }
-  if (anyChange) {
-    return result;
-  }
-  return value;
-}
-
-// src/selector.mts
-function select(source, selector) {
-  if (typeof selector === "function") {
-    return selector(source);
-  } else if (typeof selector === "string") {
-    return deep_exports.getAt(source, selector);
-  } else if (Array.isArray(selector)) {
-    return selector.map((s) => select(source, s));
-  }
-  const result = {};
-  for (const key in selector) {
-    result[key] = select(source, selector[key]);
-  }
-  return result;
-}
-
-// src/deep.mts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withType = exports.selectAtWith = exports.selectAt = exports.selectWith = exports.matchAtWith = exports.matchAt = exports.matchWith = exports.patchAtWith = exports.patchWith = exports.getAtWith = exports.protect = exports.select = exports.patchAt = exports.getAt = exports.patch = exports.match = void 0;
+var internal_cjs_1 = require("./internal.cjs");
+var match_cjs_1 = require("./match.cjs");
+Object.defineProperty(exports, "match", { enumerable: true, get: function () { return match_cjs_1.match; } });
+var patch_cjs_1 = require("./patch.cjs");
+Object.defineProperty(exports, "patch", { enumerable: true, get: function () { return patch_cjs_1.patch; } });
+var path_cjs_1 = require("./path.cjs");
+Object.defineProperty(exports, "getAt", { enumerable: true, get: function () { return path_cjs_1.getAt; } });
+Object.defineProperty(exports, "patchAt", { enumerable: true, get: function () { return path_cjs_1.patchAt; } });
+var selector_cjs_1 = require("./selector.cjs");
+Object.defineProperty(exports, "select", { enumerable: true, get: function () { return selector_cjs_1.select; } });
+/**
+ * Returns the same value wrapped in the `Protected` type.
+ * @typeparam T - the source value type
+ * @param source - the value to wrap
+ * @note does not perform any runtime protection, it is only a utility to easily add the `Protected`
+ * type to a value
+ * @example
+ * ```ts
+ * const obj = Deep.protect({ a: 1, b: { c: true, d: [1] } })
+ * obj.a = 2        // compiler error: a is readonly
+ * obj.b.c = false  // compiler error: c is readonly
+ * obj.b.d.push(2)  // compiler error: d is a readonly array
+ * (obj as any).b.d.push(2)  // will actually mutate the object
+ * ```
+ */
 function protect(source) {
-  return source;
+    return source;
 }
+exports.protect = protect;
+/**
+ * Returns a function that gets the value at the given string `path` inside an object.
+ * @typeparam T - the input value type
+ * @typeparam P - the string literal path type in the object
+ * @param path - the string path in the object
+ * @param source - the value from which to extract the path value
+ * @example
+ * ```ts
+ * const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
+ * items.map(Deep.getAtWith('a.c'));
+ * // => ['a', 'b']
+ * ```
+ */
 function getAtWith(path) {
-  return (source) => deep_exports.getAt(source, path);
-}
+    return function (source) { return internal_cjs_1.Deep.getAt(source, path); };
+}
+exports.getAtWith = getAtWith;
+/**
+ * Returns a function that patches a given `source` with the given `patchItems`.
+ * @typeparam T - the patch value type
+ * @typeparam TE - utility type
+ * @typeparam TT - utility type
+ * @param patchItem - the `Patch` definition to update the given value of type `T` with.
+ * @param source - the value to use the given `patchItem` on.
+ * @example
+ * ```ts
+ * const items = [{ a: 1, b: 'a' }, { a: 2, b: 'b' }];
+ * items.map(Deep.patchWith([{ a: v => v + 1 }]));
+ * // => [{ a: 2, b: 'a' }, { a: 3, b: 'b' }]
+ * ```
+ */
 function patchWith(patchItem) {
-  return (source) => deep_exports.patch(source, patchItem);
-}
+    return function (source) { return internal_cjs_1.Deep.patch(source, patchItem); };
+}
+exports.patchWith = patchWith;
+/**
+ * Returns a function that patches a given `value` with the given `patchItems` at the given `path`.
+ * @typeparam T - the patch value type
+ * @typeparam P - the string literal path type in the object
+ * @typeparam TE - utility type
+ * @typeparam TT - utility type
+ * @param path - the string path in the object
+ * @param patchItem - the `Patch` definition to update the value at the given `path` in `T` with.
+ * @param source - the value to use the given `patchItem` on at the given `path`.
+ * @example
+ * ```ts
+ * const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
+ * items.map(Deep.patchAtWith('a', [{ b: (v) => v + 1 }]));
+ * // => [{ a: { b: 2, c: 'a' } }, { a: { b: 3, c: 'b' } }]
+ * ```
+ */
 function patchAtWith(path, patchItem) {
-  return (source) => deep_exports.patchAt(source, path, patchItem);
-}
+    return function (source) { return internal_cjs_1.Deep.patchAt(source, path, patchItem); };
+}
+exports.patchAtWith = patchAtWith;
+/**
+ * Returns a function that matches a given `value` with the given `matcher`.
+ * @typeparam T - the patch value type
+ * @param matcher - a matcher object that matches input values.
+ * @param source - the value to use the given `patchItem` on at the given `path`.
+ * @example
+ * ```ts
+ * const items = [{ a: 1, b: 'a' }, { a: 2, b: 'b' }];
+ * items.filter(Deep.matchWith({ a: 2 }));
+ * // => [{ a: 2, b: 'b' }]
+ * ```
+ */
 function matchWith(matcher) {
-  return (source) => deep_exports.match(source, matcher);
-}
+    return function (source) { return internal_cjs_1.Deep.match(source, matcher); };
+}
+exports.matchWith = matchWith;
+/**
+ * Returns true if the given `value` object matches the given `matcher` at the given `path`, false otherwise.
+ * @typeparam T - the input value type
+ * @typeparam P - the string literal path type in the object
+ * @param source - the input value
+ * @param path - the string path in the object
+ * @param matcher - a matcher object or a function taking the matcher API and returning a match object
+ * @example
+ * ```ts
+ * const input = { a: 1, b: { c: true, d: 'a' } }
+ * Deep.matchAt(input, 'b', { c: true })
+ * // => true
+ * ```
+ */
 function matchAt(source, path, matcher) {
-  return deep_exports.match(deep_exports.getAt(source, path), matcher);
-}
+    return internal_cjs_1.Deep.match(internal_cjs_1.Deep.getAt(source, path), matcher);
+}
+exports.matchAt = matchAt;
+/**
+ * Returns a function that matches a given `value` with the given `matcher` at the given string `path`.
+ * @typeparam T - the patch value type
+ * @typeparam P - the string literal path type in the object
+ * @typeparam TE - utility type
+ * @param path - the string path in the object
+ * @param matcher - a matcher object that matches input values.
+ * @param source - the value to use the given `matcher` on at the given `path`.
+ * @example
+ * ```ts
+ * const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
+ * items.filter(Deep.matchAtWith('a.b', 2));
+ * // => [{ a: 2, b: 'b' }]
+ * ```
+ */
 function matchAtWith(path, matcher) {
-  return (source) => deep_exports.matchAt(source, path, matcher);
-}
+    return function (source) { return internal_cjs_1.Deep.matchAt(source, path, matcher); };
+}
+exports.matchAtWith = matchAtWith;
+/**
+ * Returns a function that selects a certain shape from a given `value` with the given `selector`.
+ * @typeparam T - the patch value type
+ * @typeparam SL - the selector shape type
+ * @param selector - a shape indicating the selection from the source values
+ * @param source - the value to use the given `selector` on.
+ * @example
+ * ```ts
+ * const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
+ * items.map(Deep.selectWith({ q: 'a.c', z: ['a.b', v => v.a.b + 1] as const }));
+ * // => [{ q: 'a', z: [1, 2] }, { q: 'b', z: [2, 3] }]
+ * ```
+ */
 function selectWith(selector) {
-  return (source) => deep_exports.select(source, selector);
-}
+    return function (source) { return internal_cjs_1.Deep.select(source, selector); };
+}
+exports.selectWith = selectWith;
+/**
+ * Returns the result of applying the given `selector` shape to the given `source` value.
+ * @typeparam T - the patch value type
+ * @typeparam P - the string literal path type in the object
+ * @typeparam SL - the selector shape type
+ * @param source - the source value to select from
+ * @param path - the string path in the object
+ * @param selector - a shape indicating the selection from the source value at the given path
+ * @example
+ * ```ts
+ * const item = { a: { b:  1, c: 'a' } };
+ * Deep.selectAt(item, 'a', { q: 'c', z: ['b', v => v.b + 1] as const });
+ * // => { q: 'a', z: [1, 2] }
+ * ```
+ */
 function selectAt(source, path, selector) {
-  return deep_exports.select(deep_exports.getAt(source, path), selector);
-}
+    return internal_cjs_1.Deep.select(internal_cjs_1.Deep.getAt(source, path), selector);
+}
+exports.selectAt = selectAt;
+/**
+ * Returns a function that selects a certain shape from a given `value` with the given `selector` at the given string `path`.
+ * @typeparam T - the patch value type
+ * @typeparam P - the string literal path type in the object
+ * @typeparam SL - the selector shape type
+ * @param path - the string path in the object
+ * @param selector - a shape indicating the selection from the source values
+ * @example
+ * ```ts
+ * const items = [{ a: { b:  1, c: 'a' } }, { a: { b: 2, c: 'b' } }];
+ * items.map(Deep.selectAtWith('a', { q: 'c', z: ['b', v => v.b + 1] as const }));
+ * // => [{ q: 'a', z: [1, 2] }, { q: 'b', z: [2, 3] }]
+ * ```
+ */
 function selectAtWith(path, selector) {
-  return (source) => deep_exports.selectAt(source, path, selector);
-}
+    return function (source) { return internal_cjs_1.Deep.selectAt(source, path, selector); };
+}
+exports.selectAtWith = selectAtWith;
+/**
+ * Returns a curried API with a known target type. This can be useful for using the methods in
+ * contexts where the target type can be inferred from the usage.
+ * @typeparam T - the target type
+ * @example
+ * ```ts
+ * const s = { a: 1, b: { c: 'a', d: true }}
+ * const upd = Deep.withType<typeof s>().patchWith([{ d: (v) => !v }])
+ * upd(s)
+ * // => { a: 1, b: { c: 'a', d: false }}
+ * ```
+ */
 function withType() {
-  return deep_exports;
+    return internal_cjs_1.Deep;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  getAt,
-  getAtWith,
-  match,
-  matchAt,
-  matchAtWith,
-  matchWith,
-  patch,
-  patchAt,
-  patchAtWith,
-  patchWith,
-  protect,
-  select,
-  selectAt,
-  selectAtWith,
-  selectWith,
-  withType
-});
+exports.withType = withType;
+//# sourceMappingURL=deep.cjs.map