data-path 1.0.0

package/dist/index.mjs

@@ -0,0 +1,499 @@
+// src/constants.ts
+var PATH_SEGMENTS = /* @__PURE__ */ Symbol("PATH_SEGMENTS");
+var WILDCARD = "*";
+var DEEP_WILDCARD = "**";
+
+// src/utils.ts
+function isCanonicalArrayIndex(key) {
+  const num = Number(key);
+  return Number.isInteger(num) && num >= 0 && num < 2 ** 32 && String(num) === key;
+}
+function resolveSegments(target) {
+  if (typeof target === "function") {
+    const proxy = createPathProxy([]);
+    const result = target(proxy);
+    return result?.[PATH_SEGMENTS] ?? [];
+  }
+  if (target && typeof target === "object" && "segments" in target) {
+    return target.segments;
+  }
+  return [];
+}
+function createPathProxy(segments) {
+  return new Proxy(
+    { [PATH_SEGMENTS]: 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);
+      }
+    }
+  );
+}
+function segmentsEqual(a, b) {
+  if (a.length !== b.length) return false;
+  return a.every((s, i) => s === b[i]);
+}
+function matchesPrefix(full, prefix) {
+  if (prefix.length > full.length) return false;
+  let p = 0;
+  let f = 0;
+  while (p < prefix.length && f < full.length) {
+    if (prefix[p] === DEEP_WILDCARD) {
+      if (p === prefix.length - 1) return true;
+      const restPrefix = prefix.slice(p + 1);
+      for (let skip = 0; f + skip <= full.length; skip++) {
+        if (matchesPrefix(full.slice(f + skip), restPrefix)) return true;
+      }
+      return false;
+    }
+    if (prefix[p] !== WILDCARD && prefix[p] !== full[f]) return false;
+    p++;
+    f++;
+  }
+  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])
+      return false;
+  }
+  return true;
+}
+
+// src/impl/path-impl.ts
+var TemplatePathCtor;
+function setTemplatePathCtor(ctor) {
+  TemplatePathCtor = ctor;
+}
+var PathImpl = class _PathImpl {
+  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(".");
+  }
+  /**
+   * 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) {
+      if (current == null) return void 0;
+      current = current[seg];
+    }
+    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) => {
+      if (segs.length === 1) {
+        const key = segs[0];
+        if (Array.isArray(obj)) {
+          const arr = [...obj];
+          arr[key] = val;
+          return arr;
+        }
+        return { ...obj, [key]: val };
+      }
+      const [first, ...rest] = segs;
+      const baseObj2 = obj;
+      const next = baseObj2[first];
+      const nextCopy = next != null && typeof next === "object" ? Array.isArray(next) ? [...next] : { ...next } : typeof rest[0] === "number" ? [] : {};
+      if (Array.isArray(baseObj2)) {
+        const arr = [...baseObj2];
+        arr[first] = setAt(nextCopy, rest, val);
+        return arr;
+      }
+      return { ...baseObj2, [first]: setAt(nextCopy, rest, val) };
+    };
+    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
+   */
+  each(expr) {
+    let tailSegments = [];
+    if (expr) {
+      const proxy = createPathProxy([]);
+      const result = expr(proxy);
+      tailSegments = result?.[PATH_SEGMENTS] ?? [];
+    }
+    return new TemplatePathCtor([...this.segments, WILDCARD, ...tailSegments]);
+  }
+  /**
+   * 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([
+      ...this.segments,
+      DEEP_WILDCARD,
+      ...tailSegments
+    ]);
+  }
+  /**
+   * 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));
+  }
+  /**
+   * 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);
+  }
+  /**
+   * 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));
+  }
+  /**
+   * 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 null;
+  }
+  /**
+   * 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
+   */
+  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;
+      }
+    }
+    const merged = overlapLen > 0 ? [...a.slice(0, -overlapLen), ...b] : [...a, ...b];
+    return new _PathImpl(merged);
+  }
+  /**
+   * 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) {
+    const a = this.segments;
+    const b = resolveSegments(other);
+    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;
+  }
+  /**
+   * 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);
+  }
+  /**
+   * 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] ?? [];
+    }
+    return new _TemplatePathImpl([
+      ...this.segments,
+      WILDCARD,
+      ...tailSegments
+    ]);
+  }
+  /**
+   * 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] ?? [];
+    }
+    return new _TemplatePathImpl([
+      ...this.segments,
+      DEEP_WILDCARD,
+      ...tailSegments
+    ]);
+  }
+  /**
+   * 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, ...]
+   */
+  expand(data) {
+    const results = [];
+    const walk = (currentData, segmentIdx, currentPath) => {
+      if (segmentIdx >= this.segments.length) {
+        results.push(new PathImpl(currentPath));
+        return;
+      }
+      const seg = this.segments[segmentIdx];
+      if (seg === WILDCARD) {
+        if (currentData != null && typeof currentData === "object") {
+          const keys = Array.isArray(currentData) ? Array.from(currentData.keys()) : Object.keys(currentData);
+          for (const key of keys) {
+            walk(
+              currentData[key],
+              segmentIdx + 1,
+              [...currentPath, 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);
+          for (const key of keys) {
+            walk(
+              currentData[key],
+              segmentIdx,
+              [...currentPath, key]
+            );
+          }
+        }
+      } else {
+        if (currentData != null && typeof currentData === "object" && seg in currentData) {
+          walk(
+            currentData[seg],
+            segmentIdx + 1,
+            [...currentPath, 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);
+    }
+    return current;
+  }
+};
+
+// src/path.ts
+setTemplatePathCtor(TemplatePathImpl);
+function path(baseOrExpr, expr) {
+  if (!baseOrExpr) {
+    return new PathImpl([]);
+  }
+  if (typeof baseOrExpr === "function") {
+    const proxy = createPathProxy([]);
+    const result = baseOrExpr(proxy);
+    const segments = result?.[PATH_SEGMENTS] ?? [];
+    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
+      ]);
+    }
+  }
+  return new PathImpl(baseSegments);
+}
+function unsafePath(raw) {
+  const segments = raw ? raw.split(".").map((s) => s === "" ? s : isCanonicalArrayIndex(s) ? Number(s) : s) : [];
+  return new PathImpl(segments);
+}
+export {
+  path,
+  unsafePath
+};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "data-path",
+  "version": "1.0.0",
+  "description": "A simple, modern, zero-dependency, and fully type-safe library for building, comparing, and manipulating object property paths using TypeScript lambda expressions.",
+  "license": "ISC",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "npm run build -- --watch",
+    "lint": "biome check src",
+    "lint:fix": "biome check --write src",
+    "prepare": "husky",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest --typecheck"
+  },
+  "keywords": [
+    "typescript",
+    "path",
+    "object-path",
+    "type-safe",
+    "proxy",
+    "dot-notation",
+    "property-path",
+    "accessor",
+    "data-path"
+  ],
+  "author": {
+    "name": "Sergei Shmakov",
+    "url": "https://github.com/sergeyshmakov"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sergeyshmakov/data-path.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sergeyshmakov/data-path/issues"
+  },
+  "homepage": "https://github.com/sergeyshmakov/data-path#readme",
+  "release": {
+    "branches": [
+      "main"
+    ]
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.6",
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.4.3",
+    "husky": "^9.1.7",
+    "semantic-release": "^25.0.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "volta": {
+    "node": "24.14.0"
+  }
+}