data-path 1.0.2 → 2.0.0

package/dist/index.js

@@ -1,34 +1,7 @@
-"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/index.ts
-var index_exports = {};
-__export(index_exports, {
-  path: () => path,
-  unsafePath: () => unsafePath
-});
-module.exports = __toCommonJS(index_exports);
-
 // src/constants.ts
 var PATH_SEGMENTS = /* @__PURE__ */ Symbol("PATH_SEGMENTS");
-var WILDCARD = "*";
-var DEEP_WILDCARD = "**";
+var WILDCARD = /* @__PURE__ */ Symbol("WILDCARD");
+var DEEP_WILDCARD = /* @__PURE__ */ Symbol("DEEP_WILDCARD");
 
 // src/utils.ts
 function isCanonicalArrayIndex(key) {
@@ -41,7 +14,7 @@ function resolveSegments(target) {
     const result = target(proxy);
     return result?.[PATH_SEGMENTS] ?? [];
   }
-  if (target && typeof target === "object" && "segments" in target) {
+  if (target != null && typeof target === "object" && "segments" in target) {
     return target.segments;
   }
   return [];
@@ -53,11 +26,9 @@ function createPathProxy(segments) {
       get(target, key) {
         if (key === PATH_SEGMENTS)
           return target[PATH_SEGMENTS];
-        if (typeof key === "string" && key !== "Symbol") {
-          const next = isCanonicalArrayIndex(key) ? Number(key) : key;
-          return createPathProxy([...segments, next]);
-        }
-        return typeof key === "symbol" ? void 0 : createPathProxy(segments);
+        if (typeof key === "symbol") return void 0;
+        const next = isCanonicalArrayIndex(key) ? Number(key) : key;
+        return createPathProxy([...segments, next]);
       }
     }
   );
@@ -67,10 +38,12 @@ function segmentsEqual(a, b) {
   return a.every((s, i) => s === b[i]);
 }
 function matchesPrefix(full, prefix) {
-  if (prefix.length > full.length) return false;
+  let minPrefixLen = 0;
+  for (const s of prefix) if (s !== DEEP_WILDCARD) minPrefixLen++;
+  if (minPrefixLen > full.length) return false;
   let p = 0;
   let f = 0;
-  while (p < prefix.length && f < full.length) {
+  while (p < prefix.length) {
     if (prefix[p] === DEEP_WILDCARD) {
       if (p === prefix.length - 1) return true;
       const restPrefix = prefix.slice(p + 1);
@@ -79,6 +52,7 @@ function matchesPrefix(full, prefix) {
       }
       return false;
     }
+    if (f >= full.length) return false;
     if (prefix[p] !== WILDCARD && prefix[p] !== full[f]) return false;
     p++;
     f++;
@@ -86,57 +60,76 @@ function matchesPrefix(full, prefix) {
   return p === prefix.length;
 }
 function patternMatches(pattern, concrete) {
-  if (pattern.length !== concrete.length) return false;
-  for (let i = 0; i < pattern.length; i++) {
-    if (pattern[i] !== WILDCARD && pattern[i] !== DEEP_WILDCARD && pattern[i] !== concrete[i])
+  function walk(pi, ci) {
+    if (pi === pattern.length) return ci === concrete.length;
+    const seg = pattern[pi];
+    if (seg === DEEP_WILDCARD) {
+      for (let skip = 0; ci + skip <= concrete.length; skip++) {
+        if (walk(pi + 1, ci + skip)) return true;
+      }
       return false;
+    }
+    if (ci === concrete.length) return false;
+    if (seg === WILDCARD) return walk(pi + 1, ci + 1);
+    if (seg !== concrete[ci]) return false;
+    return walk(pi + 1, ci + 1);
   }
-  return true;
+  return walk(0, 0);
 }
-
-// src/impl/path-impl.ts
-var TemplatePathCtor;
-function setTemplatePathCtor(ctor) {
-  TemplatePathCtor = ctor;
+function hasWildcardSegment(segments) {
+  for (const s of segments) {
+    if (s === WILDCARD || s === DEEP_WILDCARD) return true;
+  }
+  return false;
 }
-var PathImpl = class _PathImpl {
+
+// src/impl/base-path-impl.ts
+var AbstractPathImpl = class {
   segments;
   constructor(segments) {
     this.segments = segments;
   }
-  /**
-   * The number of segments in this path.
-   */
   get length() {
     return this.segments.length;
   }
-  /**
-   * The string representation of the path (e.g. "users.0.name").
-   * Useful for binding paths to form libraries or UI components.
-   *
-   * @example
-   * path<Root>().users[0].name.$; // "users.0.name"
-   */
   get $() {
     return this.toString();
   }
-  /**
-   * Returns the string representation of the path (e.g. "users.0.name").
-   *
-   * @example
-   * path<Root>().users[0].name.toString(); // "users.0.name"
-   */
   toString() {
-    return this.segments.join(".");
+    return this.segments.map(
+      (s) => s === WILDCARD ? "*" : s === DEEP_WILDCARD ? "**" : String(s)
+    ).join(".");
+  }
+  startsWith(other) {
+    return matchesPrefix(this.segments, resolveSegments(other));
+  }
+  covers(other) {
+    return matchesPrefix(resolveSegments(other), this.segments);
+  }
+  equals(other) {
+    return segmentsEqual(this.segments, resolveSegments(other));
+  }
+  match(other) {
+    const otherSegs = resolveSegments(other);
+    if (segmentsEqual(this.segments, otherSegs)) return { relation: "equals" };
+    if (patternMatches(this.segments, otherSegs)) return { relation: "covers" };
+    if (patternMatches(otherSegs, this.segments))
+      return { relation: "covered-by" };
+    if (!hasWildcardSegment(otherSegs) && matchesPrefix(this.segments, otherSegs) && this.segments.length > otherSegs.length)
+      return { relation: "child" };
+    if (!hasWildcardSegment(this.segments) && matchesPrefix(otherSegs, this.segments) && otherSegs.length > this.segments.length)
+      return { relation: "parent" };
+    return null;
+  }
+};
+
+// src/impl/path-impl.ts
+var PathImpl = class extends AbstractPathImpl {
+  fn;
+  constructor(segments) {
+    super(segments);
+    this.fn = (data) => this.get(data);
   }
-  /**
-   * Extracts the value at this path from the given data object.
-   * Safely handles missing intermediate properties by returning `undefined` instead of throwing an error.
-   *
-   * @example
-   * const namePath = path<User>().name;
-   * const name = namePath.get({ name: "Alice" }); // "Alice"
-   */
   get(data) {
     let current = data;
     for (const seg of this.segments) {
@@ -145,25 +138,6 @@ var PathImpl = class _PathImpl {
     }
     return current;
   }
-  /**
-   * Returns an accessor function that extracts the value at this path from the given data object.
-   * Useful for array methods like `.map()` or `.filter()`.
-   *
-   * @example
-   * const names = users.map(path<User>().name.fn);
-   */
-  get fn() {
-    return (data) => this.get(data);
-  }
-  /**
-   * Sets the value at this path in the given data object, returning a new updated object (immutable).
-   * If intermediate properties are missing, they are automatically created as objects or arrays
-   * depending on the segment types (numeric keys become arrays).
-   *
-   * @example
-   * const namePath = path<User>().name;
-   * const updatedUser = namePath.set({ name: "Alice" }, "Bob"); // { name: "Bob" }
-   */
   set(data, value) {
     if (this.segments.length === 0) return value;
     const setAt = (obj, segs, val) => {
@@ -190,308 +164,211 @@ var PathImpl = class _PathImpl {
     const baseObj = typeof data === "object" && data !== null ? Array.isArray(data) ? [...data] : { ...data } : data;
     return setAt(baseObj, this.segments, value);
   }
-  /**
-   * Traverses into a collection (Array or Record) to operate on each item.
-   *
-   * @example
-   * const users = path<Root>().users;
-   * const userNames = users.each(u => u.name); // Path matches all names
-   */
+  update(data, updater) {
+    return this.set(data, updater(this.get(data)));
+  }
+  parent() {
+    if (this.segments.length === 0) return null;
+    return makeConcrete(
+      this.segments.slice(0, -1)
+    );
+  }
+  subtract(prefix) {
+    const a = this.segments;
+    const b = resolveSegments(prefix);
+    if (b.length > a.length) return null;
+    if (!segmentsEqual(a.slice(0, b.length), b)) return null;
+    return makeConcrete(a.slice(b.length));
+  }
+  slice(start, end) {
+    return makeConcrete(
+      this.segments.slice(start, end)
+    );
+  }
   each(expr) {
-    let tailSegments = [];
-    if (expr) {
-      const proxy = createPathProxy([]);
-      const result = expr(proxy);
-      tailSegments = result?.[PATH_SEGMENTS] ?? [];
-    }
-    return new TemplatePathCtor([...this.segments, WILDCARD, ...tailSegments]);
+    const tail = expr ? evalExpr(expr) : [];
+    return new TemplatePathImpl([
+      ...this.segments,
+      WILDCARD,
+      ...tail
+    ]);
   }
-  /**
-   * Traverses deeply into a structure, matching any nested property.
-   *
-   * @example
-   * const root = path<Root>();
-   * const allIds = root.deep(node => node.id); // Path matches any 'id' at any depth
-   */
   deep(expr) {
-    let tailSegments = [];
-    if (expr) {
-      const proxy = createPathProxy([]);
-      const result = expr(proxy);
-      tailSegments = result?.[PATH_SEGMENTS] ?? [];
-    }
-    return new TemplatePathCtor([
+    const tail = expr ? evalExpr(expr) : [];
+    return new TemplatePathImpl([
       ...this.segments,
       DEEP_WILDCARD,
-      ...tailSegments
+      ...tail
     ]);
   }
-  /**
-   * Checks if this path starts with the segments of another path.
-   *
-   * @example
-   * const a = path<Root>().users[0].name;
-   * const b = path<Root>().users;
-   * a.startsWith(b); // true
-   */
-  startsWith(other) {
-    return matchesPrefix(this.segments, resolveSegments(other));
+  to(relative) {
+    return makeFromSegments([
+      ...this.segments,
+      ...resolveSegments(relative)
+    ]);
   }
-  /**
-   * Checks if this path encompasses the segments of another path (i.e., this path is a prefix of the other).
-   *
-   * @example
-   * const a = path<Root>().users;
-   * const b = path<Root>().users[0].name;
-   * a.includes(b); // true
-   */
-  includes(other) {
-    return matchesPrefix(resolveSegments(other), this.segments);
+  merge(other) {
+    return makeFromSegments(
+      mergeSegments(this.segments, resolveSegments(other))
+    );
   }
-  /**
-   * Checks if this path is exactly equal to another path.
-   *
-   * @example
-   * const a = path<Root>().users;
-   * const b = path<Root>().users;
-   * a.equals(b); // true
-   */
-  equals(other) {
-    return segmentsEqual(this.segments, resolveSegments(other));
+};
+function makeFromSegments(segments) {
+  return hasWildcard(segments) ? new TemplatePathImpl(segments) : new PathImpl(segments);
+}
+function hasWildcard(segments) {
+  for (const s of segments) {
+    if (s === WILDCARD || s === DEEP_WILDCARD) return true;
   }
-  /**
-   * Matches this path against another path, returning their relationship.
-   *
-   * @example
-   * const a = path<Root>().users[0];
-   * const b = path<Root>().users;
-   * a.match(b); // { relation: 'child', params: {} }
-   */
-  match(other) {
-    const otherSegs = resolveSegments(other);
-    if (segmentsEqual(this.segments, otherSegs)) {
-      return { relation: "equals", params: {} };
-    }
-    if (matchesPrefix(this.segments, otherSegs) && this.segments.length > otherSegs.length) {
-      return { relation: "child", params: {} };
-    }
-    if (matchesPrefix(otherSegs, this.segments) && otherSegs.length > this.segments.length) {
-      return { relation: "parent", params: {} };
-    }
-    if (patternMatches(this.segments, otherSegs)) {
-      return { relation: "includes", params: {} };
-    }
-    if (patternMatches(otherSegs, this.segments)) {
-      return { relation: "included-by", params: {} };
+  return false;
+}
+var TemplatePathImpl = class _TemplatePathImpl extends AbstractPathImpl {
+  // fn returns V[] (not V|undefined) — no covariance conflict since we don't
+  // extend PathImpl; the declared type here matches TemplatePath<T,V>.fn.
+  fn;
+  constructor(segments) {
+    super(segments);
+    this.fn = (data) => this.get(data);
+  }
+  get(data) {
+    return this.expand(data).map(
+      // expand() only returns paths where the key exists in data, so get() is safe
+      (p) => p.get(data)
+    );
+  }
+  set(data, value) {
+    const paths = this.expand(data);
+    let current = data;
+    for (const p of paths) {
+      current = p.set(current, value);
     }
-    return null;
+    return current;
   }
   /**
-   * Appends another path to the end of this path. If the end of this path matches
-   * the beginning of the other path, the overlapping segments are intelligently deduplicated.
-   *
-   * @example
-   * const base = path<Root>().users;
-   * const full = base.merge(p => p[0].name); // equivalent to path<Root>().users[0].name
+   * Applies `updater` to each matched value individually (per-item transform).
+   * Use `.set(data, constant)` to assign the same value to every match.
    */
-  merge(other) {
-    const a = this.segments;
-    const b = resolveSegments(other);
-    let overlapLen = 0;
-    for (let len = Math.min(a.length, b.length); len >= 1; len--) {
-      const aSuffix = a.slice(-len);
-      const bPrefix = b.slice(0, len);
-      if (segmentsEqual(aSuffix, bPrefix)) {
-        overlapLen = len;
-        break;
-      }
+  update(data, updater) {
+    const paths = this.expand(data);
+    let current = data;
+    for (const p of paths) {
+      current = p.set(current, updater(p.get(current)));
     }
-    const merged = overlapLen > 0 ? [...a.slice(0, -overlapLen), ...b] : [...a, ...b];
-    return new _PathImpl(merged);
+    return current;
   }
-  /**
-   * Removes the segments of another path from either the beginning or the end of this path.
-   * Returns `null` if the other path is neither a prefix nor a suffix.
-   *
-   * @example
-   * const full = path<Root>().users[0].name;
-   * const base = path<Root>().users;
-   * const remainder = full.subtract(base); // equivalent to path()[0].name
-   */
-  subtract(other) {
+  parent() {
+    if (this.segments.length === 0) return null;
+    return makeFromSegments(
+      this.segments.slice(0, -1)
+    );
+  }
+  subtract(prefix) {
     const a = this.segments;
-    const b = resolveSegments(other);
+    const b = resolveSegments(prefix);
     if (b.length > a.length) return null;
-    if (segmentsEqual(a, b)) return new _PathImpl([]);
-    if (segmentsEqual(a.slice(0, b.length), b)) {
-      return new _PathImpl(a.slice(b.length));
-    }
-    if (segmentsEqual(a.slice(-b.length), b)) {
-      return new _PathImpl(a.slice(0, -b.length));
-    }
-    return null;
+    if (!segmentsEqual(a.slice(0, b.length), b)) return null;
+    return makeFromSegments(a.slice(b.length));
   }
-  /**
-   * Returns a new path containing a subset of the segments, similar to Array.prototype.slice.
-   *
-   * @example
-   * const full = path<Root>().users[0].name;
-   * full.slice(0, 1); // equivalent to path<Root>().users
-   */
   slice(start, end) {
-    const s = this.segments.slice(start, end);
-    return new _PathImpl(s);
+    return makeFromSegments(
+      this.segments.slice(start, end)
+    );
   }
-  /**
-   * Extends the current path using a lambda expression starting from the resolved value.
-   *
-   * @example
-   * const userPath = path<Root>().users[0];
-   * const namePath = userPath.to(u => u.name);
-   */
-  to(expr) {
-    const proxy = createPathProxy([]);
-    const result = expr(proxy);
-    const tailSegments = result?.[PATH_SEGMENTS] ?? [];
-    return new _PathImpl([...this.segments, ...tailSegments]);
-  }
-};
-
-// src/impl/template-path-impl.ts
-var TemplatePathImpl = class _TemplatePathImpl extends PathImpl {
-  /**
-   * Traverses into a collection (Array or Record) to operate on each item, returning a TemplatePath.
-   *
-   * @example
-   * const users = path<Root>().users;
-   * const userNames = users.each(u => u.name); // TemplatePath matching all names
-   */
   each(expr) {
-    let tailSegments = [];
-    if (expr) {
-      const proxy = createPathProxy([]);
-      const result = expr(proxy);
-      tailSegments = result?.[PATH_SEGMENTS] ?? [];
-    }
+    const tail = expr ? evalExpr(expr) : [];
     return new _TemplatePathImpl([
       ...this.segments,
       WILDCARD,
-      ...tailSegments
+      ...tail
     ]);
   }
-  /**
-   * Traverses deeply into a structure, matching any nested property, returning a TemplatePath.
-   *
-   * @example
-   * const root = path<Root>();
-   * const allIds = root.deep(node => node.id); // TemplatePath matching any 'id' at any depth
-   */
   deep(expr) {
-    let tailSegments = [];
-    if (expr) {
-      const proxy = createPathProxy([]);
-      const result = expr(proxy);
-      tailSegments = result?.[PATH_SEGMENTS] ?? [];
-    }
+    const tail = expr ? evalExpr(expr) : [];
     return new _TemplatePathImpl([
       ...this.segments,
       DEEP_WILDCARD,
-      ...tailSegments
+      ...tail
+    ]);
+  }
+  to(relative) {
+    const tail = resolveSegments(relative);
+    return new _TemplatePathImpl([
+      ...this.segments,
+      ...tail
     ]);
   }
+  merge(other) {
+    return new _TemplatePathImpl(
+      mergeSegments(this.segments, resolveSegments(other))
+    );
+  }
   /**
-   * Resolves this template path against actual data to return an array of concrete paths
-   * that exist in the given data.
-   *
-   * @example
-   * const template = path<Root>().users.each().name;
-   * const concretePaths = template.expand(data); // [path<Root>().users[0].name, ...]
+   * Resolves this template to all concrete paths that exist in `data`.
    */
   expand(data) {
     const results = [];
-    const walk = (currentData, segmentIdx, currentPath) => {
-      if (segmentIdx >= this.segments.length) {
-        results.push(new PathImpl(currentPath));
+    const walk = (current, idx, acc) => {
+      if (idx >= this.segments.length) {
+        results.push(new PathImpl(acc));
         return;
       }
-      const seg = this.segments[segmentIdx];
+      const seg = this.segments[idx];
       if (seg === WILDCARD) {
-        if (currentData != null && typeof currentData === "object") {
-          const keys = Array.isArray(currentData) ? Array.from(currentData.keys()) : Object.keys(currentData);
+        if (current != null && typeof current === "object") {
+          const keys = Array.isArray(current) ? Array.from(current.keys()) : Object.keys(current);
           for (const key of keys) {
-            walk(
-              currentData[key],
-              segmentIdx + 1,
-              [...currentPath, key]
-            );
+            walk(current[key], idx + 1, [
+              ...acc,
+              key
+            ]);
           }
         }
       } else if (seg === DEEP_WILDCARD) {
-        walk(currentData, segmentIdx + 1, currentPath);
-        if (currentData != null && typeof currentData === "object") {
-          const keys = Array.isArray(currentData) ? Array.from(currentData.keys()) : Object.keys(currentData);
+        walk(current, idx + 1, acc);
+        if (current != null && typeof current === "object") {
+          const keys = Array.isArray(current) ? Array.from(current.keys()) : Object.keys(current);
           for (const key of keys) {
-            walk(
-              currentData[key],
-              segmentIdx,
-              [...currentPath, key]
-            );
+            walk(current[key], idx, [
+              ...acc,
+              key
+            ]);
           }
         }
       } else {
-        if (currentData != null && typeof currentData === "object" && seg in currentData) {
-          walk(
-            currentData[seg],
-            segmentIdx + 1,
-            [...currentPath, seg]
-          );
+        if (current != null && typeof current === "object" && seg in current) {
+          walk(current[seg], idx + 1, [
+            ...acc,
+            seg
+          ]);
         }
       }
     };
     walk(data, 0, []);
     return results;
   }
-  /**
-   * Extracts an array of values at this template path from the given data object.
-   *
-   * @example
-   * const names = path<Root>().users.each().name.get(data); // string[]
-   */
-  // @ts-expect-error Overriding get to return an array instead of a single value
-  get(data) {
-    return this.expand(data).map((p) => p.get(data));
-  }
-  /**
-   * Returns an accessor function that extracts an array of values at this template path from the given data object.
-   * Useful for array methods like `.map()` or `.filter()`.
-   *
-   * @example
-   * const allNames = companies.map(path<Company>().departments.each().name.fn);
-   */
-  // @ts-expect-error Overriding fn to return an array instead of a single value
-  get fn() {
-    return (data) => this.get(data);
-  }
-  /**
-   * Sets the provided value to all matching paths immutably.
-   *
-   * @example
-   * const updatedData = path<Root>().users.each().name.set(data, "Bob");
-   */
-  set(data, value) {
-    const paths = this.expand(data);
-    let current = data;
-    for (const p of paths) {
-      current = p.set(current, value);
+};
+function makeConcrete(segments) {
+  return new PathImpl(segments);
+}
+function evalExpr(expr) {
+  const proxy = createPathProxy([]);
+  const result = expr(proxy);
+  return result?.[PATH_SEGMENTS] ?? [];
+}
+function mergeSegments(a, b) {
+  let overlapLen = 0;
+  for (let len = Math.min(a.length, b.length); len >= 1; len--) {
+    if (segmentsEqual(a.slice(-len), b.slice(0, len))) {
+      overlapLen = len;
+      break;
     }
-    return current;
   }
-};
+  return overlapLen > 0 ? [...a.slice(0, -overlapLen), ...b] : [...a, ...b];
+}
 
 // src/path.ts
-setTemplatePathCtor(TemplatePathImpl);
 function path(baseOrExpr, expr) {
-  if (!baseOrExpr) {
+  if (baseOrExpr === void 0) {
     return new PathImpl([]);
   }
   if (typeof baseOrExpr === "function") {
@@ -501,18 +378,11 @@ function path(baseOrExpr, expr) {
     return new PathImpl(segments);
   }
   const baseSegments = baseOrExpr.segments;
-  if (expr) {
-    if (typeof expr === "function") {
-      const proxy = createPathProxy([]);
-      const result = expr(proxy);
-      const tailSegments = result?.[PATH_SEGMENTS] ?? [];
-      return new PathImpl([...baseSegments, ...tailSegments]);
-    } else if (typeof expr === "object" && "segments" in expr) {
-      return new PathImpl([
-        ...baseSegments,
-        ...expr.segments
-      ]);
-    }
+  if (expr !== void 0) {
+    const proxy = createPathProxy([]);
+    const result = expr(proxy);
+    const tailSegments = result?.[PATH_SEGMENTS] ?? [];
+    return new PathImpl([...baseSegments, ...tailSegments]);
   }
   return new PathImpl(baseSegments);
 }
@@ -520,8 +390,10 @@ function unsafePath(raw) {
   const segments = raw ? raw.split(".").map((s) => s === "" ? s : isCanonicalArrayIndex(s) ? Number(s) : s) : [];
   return new PathImpl(segments);
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
+export {
+  DEEP_WILDCARD,
+  WILDCARD,
   path,
   unsafePath
-});
+};
+//# sourceMappingURL=index.js.map