data-path 1.0.2 → 2.0.0

package/dist/index.d.cts

@@ -0,0 +1,376 @@
+/**
+ * Sentinel for a single-level wildcard segment (`each`).
+ *
+ * Stored as a unique Symbol — NOT the string `"*"` — so that a legitimate
+ * object key named `"*"` is preserved as a literal segment and never
+ * reinterpreted as a wildcard by `.get`, `.expand`, `.covers`, `.match`, etc.
+ *
+ * Renders as `"*"` in `toString()` / `.$` for dot-notation compatibility.
+ */
+declare const WILDCARD: unique symbol;
+/**
+ * Sentinel for a deep wildcard segment (`deep`).
+ *
+ * Same rationale as {@link WILDCARD}: stored as a unique Symbol so the
+ * literal string `"**"` remains a valid (literal) object key.
+ *
+ * Renders as `"**"` in `toString()` / `.$`.
+ */
+declare const DEEP_WILDCARD: unique symbol;
+
+/**
+ * Core type definitions for data-path.
+ */
+
+/**
+ * A path segment.
+ *
+ * - `string` — object key
+ * - `number` — array index
+ * - `typeof WILDCARD` — single-level wildcard sentinel (inserted by `.each()`)
+ * - `typeof DEEP_WILDCARD` — deep wildcard sentinel (inserted by `.deep()`)
+ *
+ * The wildcard sentinels are unique Symbols (not the strings `"*"` / `"**"`),
+ * so legitimate object keys named `"*"` or `"**"` are preserved as literal
+ * string segments and never reinterpreted as wildcards by any method.
+ *
+ * The sentinels render as `"*"` / `"**"` in `toString()` / `.$` so dot-notation
+ * output and form-library bindings are unaffected.
+ */
+type Segment = string | number | typeof WILDCARD | typeof DEEP_WILDCARD;
+/**
+ * The structural relation returned by `.match()`.
+ *
+ * Semantics when calling `a.match(b)`:
+ * - `"parent"`     — `a` is a prefix of `b`   (a is the parent, b is deeper)
+ * - `"child"`      — `b` is a prefix of `a`   (b is the parent, a is deeper)
+ * - `"equals"`     — `a` and `b` are identical
+ * - `"covers"`     — `a` (with wildcards) covers `b` as a concrete match
+ * - `"covered-by"` — `b` (with wildcards) covers `a` as a concrete match
+ */
+type MatchRelation = "covers" | "covered-by" | "equals" | "parent" | "child";
+/** Result of .match() — relation only; params are reserved for named-wildcard support */
+interface MatchResult {
+    relation: MatchRelation;
+}
+/**
+ * Extracts the resolved value type from a path object.
+ *
+ * @example
+ * const agePath = path<User>(p => p.profile.age);
+ * type Age = ResolvedType<typeof agePath>; // number
+ */
+type ResolvedType<P> = P extends {
+    get(data: any): (infer V)[];
+} ? V : P extends BasePath<any, infer V> ? V : never;
+/**
+ * Extracts the item type from a collection (Array or Record).
+ * Used by `.each()` to infer the traversal target.
+ */
+type CollectionItem<V> = V extends ReadonlyArray<infer U> ? U : V extends Record<PropertyKey, infer U> ? U : unknown;
+/** Primitive types that cannot be traversed — `.each()` and `.deep()` are hidden when V extends Primitive */
+type Primitive = string | number | boolean | symbol | bigint | null | undefined;
+/** Lambda used to build a path — receives a proxy typed as T, infers the path from property access */
+type PathExpression<T, R = unknown> = (proxy: T) => R;
+/**
+ * Flexible path argument — accepts an existing path, a `{segments}` shape, or a lambda expression.
+ * Used by all methods that accept a path as an argument.
+ */
+type ResolvablePath<T, V = unknown> = BasePath<T, V> | {
+    segments: readonly Segment[];
+} | PathExpression<T, V>;
+/**
+ * Traversal methods — only present when V is not a primitive type.
+ * Conditionally excluded by the Path and TemplatePath types.
+ */
+interface TraversablePathMethods<T, V> {
+    /**
+     * Traverses into a collection (Array or Record), inserting a `*` wildcard.
+     * Returns a TemplatePath that matches every item.
+     *
+     * @example
+     * path<Root>().users.each(u => u.name)  // TemplatePath — all names
+     * path<Root>().users.each()              // TemplatePath — all items
+     */
+    each<U = CollectionItem<V>>(expr?: (item: CollectionItem<V>) => U): TemplatePath<T, U>;
+    /**
+     * Traverses deeply into a structure, inserting a `**` wildcard.
+     * Returns a TemplatePath that matches the given property at any nesting depth.
+     *
+     * @example
+     * path<Root>().tree.deep(node => node.id)  // TemplatePath — any nested 'id'
+     * path<Root>().tree.deep()                 // TemplatePath — every descendant node
+     */
+    deep<U = V>(expr?: (leaf: V) => U): TemplatePath<T, U>;
+}
+/**
+ * The foundational interface shared by both Path and TemplatePath.
+ *
+ * @template T  Root data type the path operates on
+ * @template V  Resolved value type at the end of the path
+ */
+interface BasePath<T = unknown, V = unknown> {
+    /** Ordered array of string keys and numeric indices that compose this path. */
+    readonly segments: readonly Segment[];
+    /** Number of segments in this path. */
+    readonly length: number;
+    /**
+     * Dot-notation string representation (e.g. `"users.0.name"`).
+     * Convenient for binding paths to form libraries.
+     *
+     * @example
+     * path<Root>(r => r.users[0].name).$  // "users.0.name"
+     */
+    readonly $: string;
+    /** Returns the dot-notation string representation. */
+    toString(): string;
+    /**
+     * Extracts the value at this path from a data object.
+     * Returns `undefined` — rather than throwing — when any intermediate segment is missing.
+     *
+     * @example
+     * path<User>(u => u.profile.name).get(user)  // string | undefined
+     */
+    get(data: T): V | undefined;
+    /**
+     * Pre-bound accessor function. Useful for array higher-order methods.
+     *
+     * @example
+     * users.map(path<User>(u => u.name).fn)  // string | undefined[]
+     */
+    readonly fn: (data: T) => V | undefined;
+    /**
+     * Immutably sets the value at this path, returning a structurally-cloned object.
+     * Missing intermediates are created automatically:
+     * numeric next-segment → array, string next-segment → object.
+     *
+     * @example
+     * path<User>(u => u.name).set(user, "Alice")
+     */
+    set(data: T, value: V): T;
+    /**
+     * Reads the current value, passes it to `updater`, and writes the result back immutably.
+     * Combines `.get()` + `.set()` in a single expression.
+     * On a `TemplatePath`, `updater` is called once per expanded match (per-item transform).
+     *
+     * @example
+     * namePath.update(user, name => (name ?? "").toUpperCase())
+     */
+    update(data: T, updater: (current: V | undefined) => V): T;
+    /**
+     * Returns the parent path (all segments except the last), or `null` for a root/empty path.
+     * Value type becomes `unknown` — use a typed path expression if the parent type is needed.
+     *
+     * @example
+     * path<User>(u => u.profile.name).parent()?.$ // "profile"
+     * path<User>().parent()                        // null
+     */
+    parent(): Path<T, unknown> | null;
+    /**
+     * Returns `true` if this path's segments begin with all segments of `other`
+     * (i.e. `other` is a prefix of `this`). Supports wildcard segments.
+     */
+    startsWith(other: ResolvablePath<T>): boolean;
+    /**
+     * Returns `true` if this path's domain covers `other` — i.e. this path's segments
+     * are a prefix of `other`'s segments (or match `other` via wildcards). The inverse
+     * direction of {@link startsWith}.
+     *
+     * NOTE: this is NOT analogous to `Array.prototype.includes` / `String.prototype.includes`.
+     * Think "covers a location in the data tree", not "contains as an element".
+     *
+     * @example
+     * profilePath.covers(namePath)  // true  — "profile" covers "profile.name"
+     * namePath.covers(profilePath)  // false
+     */
+    covers(other: ResolvablePath<T>): boolean;
+    /** Returns `true` if this path is segment-by-segment identical to `other`. */
+    equals(other: ResolvablePath<T>): boolean;
+    /**
+     * Returns the structural relationship between this path and `other`, or `null` when unrelated.
+     *
+     * `"parent"` means **this** path is the parent (shorter prefix); `"child"` means **this** is deeper.
+     *
+     * @example
+     * profilePath.match(namePath)  // { relation: "parent" }  — profilePath IS the parent
+     * namePath.match(profilePath)  // { relation: "child" }   — namePath is deeper
+     */
+    match(other: ResolvablePath<T>): MatchResult | null;
+    /**
+     * Appends `other` (a T-rooted path) with smart suffix/prefix overlap deduplication.
+     * When the tail of this path matches the head of `other`, the overlap is collapsed once.
+     *
+     * If `other` carries wildcards (`*` / `**`), the result is a `TemplatePath` so the
+     * appended pattern still expands at `.get()` time; otherwise a concrete `Path`.
+     * Narrow at the call site if you need to disambiguate.
+     *
+     * @example
+     * const base = path<Root>(r => r.users[0].profile);
+     * base.merge(r => r.users[0].profile.name)  // "users.0.profile.name" (no duplication)
+     */
+    merge<U>(other: ResolvablePath<T, U>): Path<T, U> | TemplatePath<T, U>;
+    /**
+     * Removes `prefix` from the start of this path and returns the remaining tail.
+     * Returns `null` when `prefix` is not a leading segment-sequence of this path.
+     *
+     * The returned path carries the correct root type (`U` — the type `prefix` resolves to),
+     * so it can be passed directly to `.to()` or used independently.
+     *
+     * @example
+     * const full   = path<Company>(c => c.departments[0].employees[0].name);
+     * const prefix = path<Company>(c => c.departments[0]);
+     * full.subtract(prefix)  // Path<Department, string>
+     */
+    subtract<U>(prefix: ResolvablePath<T, U>): Path<U, V> | null;
+    /**
+     * Returns a new path over a slice of segments, following `Array.prototype.slice` semantics.
+     * Value type becomes `unknown` because the type at an arbitrary segment boundary is not statically inferable.
+     *
+     * @example
+     * path<Root>(r => r.users[0].name).slice(0, 2).$  // "users.0"
+     */
+    slice(start?: number, end?: number): Path<T, unknown>;
+    /**
+     * Extends this path with a relative path rooted at `V`.
+     * Accepts a lambda expression, a pre-built `Path<V, U>`, a `TemplatePath<V, U>`, or any `{segments}` object.
+     *
+     * If `relative` carries wildcards (`*` / `**`), the result is a `TemplatePath` so the
+     * appended pattern still expands at `.get()` time; otherwise a concrete `Path`.
+     * Narrow at the call site if you need to disambiguate.
+     *
+     * @example
+     * // Lambda form:
+     * employeePath.to(e => e.profile.firstName)
+     *
+     * // Pre-built path form (no extra lambda needed):
+     * const firstName = path<Employee>(e => e.profile.firstName);
+     * employeePath.to(firstName)
+     */
+    to<U>(relative: ResolvablePath<V, U>): Path<T, U> | TemplatePath<T, U>;
+}
+/**
+ * A strongly-typed object property path.
+ * `.each()` and `.deep()` are only present when `V` is not a primitive type.
+ *
+ * @template T  Root data type
+ * @template V  Resolved value type at the end of the path
+ */
+type Path<T = unknown, V = unknown> = BasePath<T, V> & ([V] extends [Primitive] ? {} : TraversablePathMethods<T, V>);
+/**
+ * A path that contains wildcards (`*` or `**`), matching multiple values at once.
+ *
+ * - `.get(data)` returns an array of all matched values.
+ * - `.set(data, value)` immutably sets every match to the same constant.
+ * - `.update(data, fn)` applies a per-item transform to every match.
+ * - `.expand(data)` resolves the template to an array of concrete `Path` objects.
+ *
+ * @template T  Root data type
+ * @template V  Item value type at the end of the template path
+ */
+type TemplatePath<T = unknown, V = unknown> = Omit<BasePath<T, V>, "get" | "fn" | "to" | "merge" | "subtract" | "parent" | "slice"> & {
+    /**
+     * Returns an array of all values matched by this template.
+     *
+     * @example
+     * path<Root>().users.each(u => u.name).get(data)  // string[]
+     */
+    get(data: T): V[];
+    /**
+     * Pre-bound accessor function returning an array of all matched values.
+     *
+     * @example
+     * companies.map(path<Company>().departments.each(d => d.name).fn)
+     */
+    readonly fn: (data: T) => V[];
+    /**
+     * Resolves this template to an array of concrete paths that exist in `data`.
+     *
+     * @example
+     * path<Root>().users.each().name.expand(data)
+     * // [path<Root>().users[0].name, path<Root>().users[1].name, ...]
+     */
+    expand(data: T): Path<T, V>[];
+    /**
+     * Extends this template with a relative path rooted at `V`, preserving wildcard expansion.
+     * Returns a `TemplatePath` so the full chain (including the appended segments) is template-aware.
+     *
+     * @example
+     * path<Root>(r => r.users).each().to(u => u.name)
+     * // TemplatePath — collects every user's name
+     */
+    to<U>(relative: ResolvablePath<V, U>): TemplatePath<T, U>;
+    /**
+     * Appends `other` with smart overlap deduplication, preserving wildcard behavior.
+     * Returns a `TemplatePath` because `this` carries wildcards.
+     */
+    merge<U>(other: ResolvablePath<T, U>): TemplatePath<T, U>;
+    /**
+     * Returns the parent path (all segments except the last), or `null` for an empty path.
+     * If the parent still contains wildcards (`*` / `**`) it remains a `TemplatePath`;
+     * otherwise a concrete `Path` is returned. Narrow at the call site if needed.
+     */
+    parent(): Path<T, unknown> | TemplatePath<T, unknown> | null;
+    /**
+     * Returns a new path over a slice of segments. If the slice still contains wildcards
+     * the result is a `TemplatePath`; otherwise a concrete `Path`.
+     */
+    slice(start?: number, end?: number): Path<T, unknown> | TemplatePath<T, unknown>;
+    /**
+     * Removes `prefix` from the start of this path and returns the remaining tail.
+     * If the tail still contains wildcards the result is a `TemplatePath<U, V>`;
+     * otherwise a concrete `Path<U, V>`. Returns `null` when `prefix` is not a leading segment-sequence.
+     */
+    subtract<U>(prefix: ResolvablePath<T, U>): Path<U, V> | TemplatePath<U, V> | null;
+} & ([V] extends [Primitive] ? {} : {
+    each<U = CollectionItem<V>>(expr?: (item: CollectionItem<V>) => U): TemplatePath<T, U>;
+    deep<U = V>(expr?: (leaf: V) => U): TemplatePath<T, U>;
+});
+/**
+ * The overloaded call signature of the `path()` function.
+ */
+type PathConstructor = {
+    <T>(): Path<T, T>;
+    <T, V = unknown>(expr: PathExpression<T, V>): Path<T, V>;
+    <T, U, V = unknown>(base: BasePath<T, U>, expr: PathExpression<U, V>): Path<T, V>;
+};
+/** Call signature of the `unsafePath()` function */
+type UnsafePathConstructor = <T, V = unknown>(raw: string) => Path<T, V>;
+
+/**
+ * Create a typed path from a lambda expression, from an existing base path, or as a root.
+ *
+ * @example
+ * // Lambda — recommended: annotate the parameter so both T and V are inferred
+ * const p = path((user: User) => user.profile.firstName);
+ *
+ * @example
+ * // Both generics explicit
+ * const p = path<User, string>((u) => u.profile.firstName);
+ *
+ * @example
+ * // Root path (no segments) — typically extended via .to() or path(root, expr)
+ * const root = path<User>();
+ *
+ * @example
+ * // Extend an existing base path
+ * const p2 = path(root, (u) => u.profile);
+ */
+declare function path<T>(): Path<T, T>;
+declare function path<T, V = unknown>(expr: PathExpression<T, V>): Path<T, V>;
+declare function path<T, U, V = unknown>(base: BasePath<T, U>, expr: PathExpression<U, V>): Path<T, V>;
+/**
+ * Create a path from a raw dot-separated string (e.g. `"users.0.name"`).
+ *
+ * Useful for dynamic paths from external sources (API responses, Zod issue paths, etc.).
+ * Segments that are canonical non-negative integers are stored as numbers; all others as strings.
+ *
+ * The optional second generic `V` declares the expected leaf type without a cast:
+ * ```ts
+ * unsafePath<User, string>("profile.firstName").get(user)  // string | undefined
+ * ```
+ *
+ * @param raw Dot-separated string. Empty string returns a zero-segment root path.
+ */
+declare function unsafePath<T, V = unknown>(raw: string): Path<T, V>;
+
+export { type BasePath, type CollectionItem, DEEP_WILDCARD, type MatchRelation, type MatchResult, type Path, type PathConstructor, type PathExpression, type Primitive, type ResolvablePath, type ResolvedType, type Segment, type TemplatePath, type TraversablePathMethods, type UnsafePathConstructor, WILDCARD, path, unsafePath };