Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
data-path is a modern, zero-dependency TypeScript library designed to solve the inherent fragility of string-based object property paths (e.g., "user.profile.name"). By utilizing Proxy-based lambda expressions, it allows developers to build, compare, and manipulate paths with 100% type safety, IDE autocomplete, and compile-time validation.
The library is stack-agnostic and works across environments like React, Vue, Node.js, or vanilla JavaScript. Its primary scope is to provide a robust alternative to manual string manipulation for deep object structures, state management updates, and form field binding.
Sources: README.md:1-10, README.md:83-90
Installation and Setup
To begin using data-path, install the package via your preferred package manager. The library requires TypeScript 5.0 or higher to support its advanced type inference features.
npm install data-path
Sources: README.md:46, package.json:62
Local Development Environment
If you are contributing to the project or need to run it locally, the setup is straightforward using npm.
| Command | Description |
|---|---|
npm ci | Install exact dependencies for development. |
npm run dev | Starts the tsup watcher to rebuild the project on file changes. |
npm run lint | Runs Biome for code formatting and linting. |
npm test | Executes the Vitest suite, including type-checking tests. |
Sources: CONTRIBUTING.md:25-45, package.json:15-25
Core Architecture
The architecture of data-path revolves around a Proxy-based capture mechanism. When you provide a lambda expression like p => p.user.id, the library passes a Proxy object into the function. This Proxy intercepts every property access and records the keys as segments.
Path Construction Flow
The following diagram illustrates how a path is transformed from a lambda expression into a concrete Path object:
The createPathProxy utility is responsible for recursive trapping of property keys, including handling numeric indices for arrays.
Sources: src/path.ts:45-60, src/utils.ts:33-47
Component Hierarchy
The library uses a class-based implementation for paths, separating standard paths from template paths (wildcards).
Basic Usage
Path Creation Methods
There are three primary ways to initialize a path, depending on your needs for type safety or dynamic behavior.
| Method | Syntax | Use Case |
|---|---|---|
| Typed Lambda | path<T>(p => p.a.b) | Recommended for static, compile-time paths. |
| Root Path | path<T>() | Starting point for building paths incrementally. |
| Unsafe String | unsafePath<T>("a.b") | For dynamic paths received from APIs or Zod errors. |
Sources: src/path.ts:34-43, src/path.ts:85-93, README.md:120-134
Reading and Writing Data
The .get() and .set() methods provide safe interaction with data objects.
.get(data): Safely traverses the object. If an intermediate property is missing, it returnsundefinedinstead of throwing..set(data, value): Performs an immutable update, returning a new structural clone of the object with the value updated at the specified path.
Sources: src/impl/path-impl.ts:70-130, README.md:136-148
Templates and Wildcards
Templates allow you to target multiple elements simultaneously using wildcards: * (single level) and ** (deep scan).
A TemplatePath is generated when calling .each() or .deep() on an existing path. When expand(data) is called, the library walks the provided data object to find all concrete paths that match the template pattern.
Sources: src/impl/template-path-impl.ts:64-115, README.md:183-200
Common Workflows
data-path is frequently integrated into frontend frameworks and state management libraries to ensure type safety across deep updates.
Workflow: Immutable State Updates
When using useState or Zustand, path.set() simplifies updates without requiring manual spreading.
const themePath = path<AppState>(p => p.settings.profile.theme);
// Inside a React component or Store
const setTheme = (newTheme: string) => {
setState(prev => themePath.set(prev, newTheme));
};
Sources: README.md:275-295, skills/data-path/SKILL.md:52-58
Workflow: Form Integration
Libraries like React Hook Form accept string-based paths. You can use the .$ property to provide these safely.
const namePath = path<FormValues>(p => p.users[i].firstName);
// Use namePath.$ which resolves to "users.0.firstName"
<input {...register(namePath.$)} />
Sources: README.md:235-255, skills/data-path/SKILL.md:44-50
Summary
The data-path library provides a robust foundation for property access by shifting path definition from fragile strings to type-safe TypeScript expressions. Its core features—including immutable writes, template-based bulk operations, and relational algebra—make it an essential tool for managing complex data structures in modern TypeScript applications.