API Cheatsheet

Relevant source files

The following files were used as context for generating this wiki page:

• skills/data-path/references/api.md
• src/types.ts
• src/path.ts
• src/impl/path-impl.ts
• src/impl/template-path-impl.ts
• src/utils.ts
• README.md

The data-path library provides a type-safe way to create, manipulate, and utilize object property paths using TypeScript lambda expressions. It eliminates the risks associated with string-based paths by leveraging Proxy-based builders to capture property accesses at development time.

This cheatsheet serves as a technical reference for the core modules, including path creation, data access, relational algebra, and template-based wildcard operations.

Path Creation

Paths can be created starting from a root type, inferred from a lambda, or extended from an existing path. The library uses a Proxy-based mechanism to intercept property accesses within the lambda to build the internal segment array.

Method	Description
path<T>()	Creates a root path representing the object itself.
path<T>(p => p.a.b)	Creates a path from a lambda expression with a specified generic type.
path((p: T) => p.a.b)	Creates a path where the root type is inferred from the lambda argument.
path(base, p => p.c)	Extends an existing base path with additional segments.
unsafePath<T>("a.b")	Creates a path from a raw string; useful for dynamic paths from external sources.

Sources: src/path.ts:25-54, skills/data-path/references/api.md:5-11

Creation Flow

The following diagram illustrates how the path() function processes different input types to produce a Path instance.

Core Properties and Data Access

Every path object exposes metadata about its structure and provides methods to interact with data objects immutably.

Property/Method	Type	Description
path.$	string	The dot-notation string representation (e.g., "users.0.name").
path.segments	Segment[]	Read-only array of strings or numbers representing path parts.
path.length	number	The total count of segments in the path.
path.get(data)	V	Safely retrieves the value; returns undefined if the path is broken.
path.set(data, value)	T	Immutably updates the value and returns a new object reference.
path.fn	Function	An accessor function (data: T) => V for use in .map() or .filter().

Sources: src/types.ts:109-158, src/impl/path-impl.ts:38-112, skills/data-path/references/api.md:15-26

Relational Algebra

data-path allows for programmatic comparison of paths, which is essential for permissions systems and validation mapping.

Comparison Methods

• startsWith(other): Returns true if the current path's segments begin with the other path's segments.
• includes(other): Returns true if the current path is a prefix of the other path.
• equals(other): Performs a segment-by-segment identity check.
• match(other): Returns a MatchResult object containing the specific MatchRelation.

Sources: src/impl/path-impl.ts:178-232, skills/data-path/references/api.md:46-51

Path Manipulation

Paths can be composed or sliced like arrays, facilitating reusable components that operate on relative data structures.

Method	Description
merge(other)	Appends another path, intelligently deduplicating overlapping segments.
subtract(other)	Removes a prefix or suffix from the path; returns null if no match.
slice(start, end)	Returns a new path containing a subset of segments.
to(expr)	Extends the current path using a lambda starting from the current leaf type.

Sources: src/impl/path-impl.ts:241-301, skills/data-path/references/api.md:37-41

Templates and Wildcards

Template paths allow operations on multiple elements simultaneously using wildcards (* for single levels, ** for deep recursion).

Wildcard Types

• each(expr?): Targets all items in a collection (Array or Record). Results in a * segment.
• deep(expr?): Recursively targets properties at any depth. Results in a ** segment.

Template Operations

The TemplatePath interface overrides standard behavior for bulk operations:

1. get(data): Returns an array of all values matching the template.
2. set(data, value): Immutably updates every matching location with the same value.
3. expand(data): Resolves the template into an array of concrete Path objects based on existing data.

Sources: src/impl/template-path-impl.ts:24-150, src/types.ts:233-289, skills/data-path/references/api.md:30-33

Technical Architecture

The library structure separates type definitions from implementation logic to maintain zero-dependency footprints and high-performance execution.

Summary

The data-path API provides a robust framework for handling nested data structures. By using path() for static definitions and unsafePath() for dynamic strings, developers can ensure type safety across form bindings, state updates, and complex data transformations. The inclusion of relational algebra and template-based wildcards makes it suitable for advanced scenarios like bulk updates and hierarchical data traversal.