data-path 1.0.2 → 2.0.0

package/README.md

@@ -1,444 +1,97 @@
 # data-path
 
-A simple, modern, zero-dependency, and fully type-safe library for building, comparing, and manipulating object property paths using TypeScript lambda expressions.
+Type-safe object property paths in TypeScript — build, compare, and manipulate with lambda expressions. Zero dependencies.
 
-[![npm version](https://badge.fury.io/js/data-path.svg)](https://badge.fury.io/js/data-path)
-[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+[![npm version](https://img.shields.io/npm/v/data-path.svg)](https://www.npmjs.com/package/data-path)
+[![CI](https://github.com/sergeyshmakov/data-path/actions/workflows/pr.yml/badge.svg)](https://github.com/sergeyshmakov/data-path/actions/workflows/pr.yml)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/data-path)](https://bundlephobia.com/package/data-path)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## ⚠️ The Problem
+**Documentation:** https://sergeyshmakov.github.io/data-path/
 
-When working with deep object structures, forms, or nested state, we often rely on string-based paths (e.g., `"users.0.name"` or `"company.departments[1].budget"`). This approach is fundamentally flawed in modern TypeScript development:
+---
 
-- **No Type Safety:** String paths are opaque to the compiler. A typo goes unnoticed until runtime.
-- **Refactoring Nightmares:** Renaming a property doesn't update string literals scattered across your codebase.
-- **No Autocomplete:** Your IDE cannot guide you through the object structure.
-- **No Mathematics:** It is difficult to programmatically determine if path `A` is a child of path `B`, or if they overlap.
+## Before / after
 
-## 🚀 The Solution
-
-`data-path` solves this by using **Proxy-based lambda expressions** to capture paths. It gives you 100% type safety, IDE autocomplete, and a rich API for interacting with data and other paths.
-
-```typescript
-import { path } from "data-path";
-
-type User = {
-    id: string;
-    profile: {
-        firstName: string;
-        lastName: string;
-    };
-    tags: string[];
-};
-
-// 1. Create a path with full IDE autocomplete
-const firstNamePath = path<User>(p => p.profile.firstName);
-
-// 2. Output as a string (e.g., for form libraries)
-console.log(firstNamePath.$); // "profile.firstName"
-
-// 3. Read data safely (no "Cannot read properties of undefined" errors)
-const user = {
-    id: "1",
-    profile: { firstName: "Alice", lastName: "Smith" },
-    tags: [],
-};
-console.log(firstNamePath.get(user)); // "Alice"
-
-// 4. Update data immutably (returns a new structural clone)
-const updatedUser = firstNamePath.set(user, "Bob");
-console.log(updatedUser.profile.firstName); // "Bob"
+```ts
+// Before — string literals, invisible to the compiler
+register("users.0.profile.firstName");
+table.getColumn("contact.email");
+set(state => ({ ...state, settings: { ...state.settings, theme } }));
 ```
 
-## 📦 Installation
-
-```bash
-npm install data-path
+```ts
+// After — typed, IDE-autocompleted, refactor-safe
+register(path((u: FormData) => u.users[0].profile.firstName).$);
+table.getColumn(emailPath.$);
+set(state => themePath.set(state, theme));
 ```
 
-_(or use `yarn add data-path`, `pnpm add data-path`, `bun add data-path`)_
+## What it is
 
-## 🤖 AI Ready
+A zero-dependency TypeScript library that captures object property paths via proxy-based lambdas. Build a path once — use it as a string, read and write data through it, compose paths together, or match one against another.
 
-This package is available in [Context7](https://context7.com/) MCP, so AI assistants can load it directly into context when working with your object property paths.
+- Typed root to leaf — renaming a property breaks the path at compile time
+- Safe `get`, immutable `set`, read-modify-write `update`
+- Template paths (`each`, `deep`) for bulk operations across collections and trees
+- Path algebra: `merge`, `subtract`, `slice`, `to`
+- Runtime indices and closure variables work natively inside lambdas
 
-It also ships an [Agent Skills](https://agentskills.io/) – compatible skill. Install it so your AI assistant loads data-path guidance:
+## Install
 
 ```bash
-npx ctx7 skills install /sergeyshmakov/data-path data-path
-```
-
-The skill lives in [skills/data-path/SKILL.md](skills/data-path/SKILL.md).
-
-## 💡 Philosophy
-
-- **Stack Agnostic:** Pure data manipulation. Works perfectly with React, Vue, Node.js, or vanilla JavaScript.
-- **Zero Dependencies:** A tiny, efficient footprint that doesn't bloat your bundle.
-- **Fully Type-Safe:** Built strictly for TypeScript. If the structure changes, the compiler will instantly catch broken paths.
-- **Immutable:** All `.set()` operations return structurally cloned objects, making it the perfect companion for modern state managers (Redux, Zustand) and reactive frameworks.
-
-## 📚 Core API
-
-### 🏷️ API Cheatsheet
-
-| API | Description |
-|-----|-------------|
-| **Creation** | |
-| `path<T>()` | Create root path |
-| `path<T>(p => p.a.b)` | Create path from lambda, generic type |
-| `path((p: T) => p.a.b)` | Create path from lambda, infer type |
-| `path(base, p => p.c)` | Extend existing path |
-| `unsafePath<T>("a.b")` | Create path from raw string |
-| **Properties** | |
-| `path.$` | String representation (e.g. `"users.0.name"`) |
-| `path.segments` | Array of segments |
-| `path.length` | Number of segments |
-| `path.fn` | Accessor function for `.map()`, `.filter()` |
-| **Data Access** | |
-| `path.get(data)` | Read value at path (returns `undefined` if missing) |
-| `path.set(data, value)` | Immutable write, returns new object |
-| **Traversal** | |
-| `path.to(p => p.x)` | Extend path from current value |
-| `path.each(p => p.x)` | Template: match all items in collection |
-| `path.each().to(p => p.x)` | Same as above |
-| `path.deep(node => node.id)` | Template: match property at any depth |
-| **Manipulation** | |
-| `path.merge(other)` | Append path (deduplicates overlap) |
-| `path.subtract(other)` | Remove prefix/suffix, or `null` |
-| `path.slice(start?, end?)` | Slice segments (like `Array.prototype.slice`) |
-| **Relational** | |
-| `path.startsWith(other)` | True if path is prefix |
-| `path.includes(other)` | True if path contains other |
-| `path.equals(other)` | True if paths are identical |
-| `path.match(other)` | Returns `{ relation, params }` or `null` |
-| **Template-only** | |
-| `templatePath.expand(data)` | Resolve template to concrete paths |
-
-### Path Creation
-
-You can create paths starting from the root of a type, using a lambda expression, or unsafely from a raw string.
-
-```typescript
-// From root
-const root = path<User>();
-const profile = root.to(p => p.profile);
-
-// Direct lambda
-const tagsPath = path<User>(p => p.tags[0]);
-
-// Infer type from argument (often preferred)
-const lastNamePath = path((user: User) => user.profile.lastName);
-
-// From raw string (dynamic contexts)
-import { unsafePath } from "data-path";
-const dynamicPath = unsafePath<User>("profile.firstName");
-```
-
-### Data Access
-
-```typescript
-const namePath = path<User>(p => p.profile.firstName);
-
-// Read
-namePath.get(user); // "Alice"
-
-// Accessor shorthand (perfect for arrays)
-const users = [user1, user2];
-const names = users.map(namePath.fn);
-
-// Write (Immutable)
-const updated = namePath.set(user, "Alice 2.0");
-```
-
-### Manipulation
-
-You can programmatically compose, subtract, and slice paths. This is ideal when working with reusable components that don't know their absolute location in a global store.
-
-```typescript
-// 1. We have a specific record's path
-const employeePath = path<Company>(p => p.departments[0].employees[5]);
-
-// 2. We have a generic sub-path
-const nameSubPath = path<Employee>(p => p.profile.firstName);
-
-// Merge them! (Smart deduplication if they overlap)
-const absoluteNamePath = employeePath.merge(nameSubPath);
-console.log(absoluteNamePath.$); // "departments.0.employees.5.profile.firstName"
-
-// Subtract a base path to find the relative path
-const relative = absoluteNamePath.subtract(employeePath);
-console.log(relative?.$); // "profile.firstName"
-
-// Slice segments (just like Array.prototype.slice)
-const sliced = absoluteNamePath.slice(0, 3);
-console.log(sliced.$); // "departments.0.employees"
-```
-
-### Templates & Wildcards
-
-Templates allow you to target multiple elements at once (e.g., all items in an array, or all properties matching a name deep in a tree). This unlocks powerful bulk-operations.
-
-```typescript
-type AppData = { users: Array<{ id: string; name: string }> };
-const data: AppData = {
-    users: [
-        { id: "1", name: "Alice" },
-        { id: "2", name: "Bob" },
-    ],
-};
-
-// 1. Create a template targeting ALL users
-const allUsersPath = path<AppData>(p => p.users).each();
-console.log(allUsersPath.$); // "users.*"
-
-// 2. Create a template targeting ALL user names
-const allNamesPath = path<AppData>(p => p.users).each(u => u.name);
-console.log(allNamesPath.$); // "users.*.name"
-
-// 3. Bulk Read: extract an array of all matched values
-const names = allNamesPath.get(data);
-console.log(names); // ["Alice", "Bob"]
-
-// 4. Bulk Write: immutably update all matches in one go!
-const anonymizedData = allNamesPath.set(data, "Hidden");
-console.log(anonymizedData.users[0].name); // "Hidden"
-console.log(anonymizedData.users[1].name); // "Hidden"
-
-// 5. Expand: resolve the template into concrete paths based on actual data
-const concretePaths = allNamesPath.expand(data);
-console.log(concretePaths.map(p => p.$));
-// ["users.0.name", "users.1.name"]
-
-// 6. Deep Scan: target a property at any depth
-const deepIds = path<AppData>().deep(node => node.id);
-console.log(deepIds.$); // "**.id"
-```
-
-### Runtime Variables & Indices
-
-Because `data-path` executes the lambda once during creation to build the path, you can seamlessly use runtime variables, indexers, and local scope variables directly inside the path definition.
-
-```typescript
-function getUserPropertyPath(userIdx: number, property: "name" | "email") {
-    // Capture function arguments directly in the path!
-    return path<AppData>(p => p.users[userIdx][property]);
-}
-
-const namePath = getUserPropertyPath(2, "name");
-console.log(namePath.$); // "users.2.name"
-
-const emailPath = getUserPropertyPath(5, "email");
-console.log(emailPath.$); // "users.5.email"
-```
-
-### Relational Algebra
-
-Path algebra is extremely useful for permissions, validation, and complex UI logic where you need to know how two paths relate to each other.
-
-```typescript
-const userPath = path<User>();
-const profilePath = userPath.to(p => p.profile);
-const namePath = userPath.to(p => p.profile.firstName);
-
-// Check relationships
-namePath.startsWith(profilePath); // true
-profilePath.includes(namePath); // true
-namePath.includes(profilePath); // false
-namePath.equals(namePath); // true
-
-// .match() provides detailed relational context:
-// returns 'includes', 'included-by', 'equals', 'parent', 'child', or null
-namePath.match(profilePath); // { relation: 'child', params: {} }
-profilePath.match(namePath); // { relation: 'parent', params: {} }
-```
-
-### Utility Types
-
-The library exports several TypeScript types that are useful when writing helper functions or React components that accept paths as props:
-
-```typescript
-import type { Path, TemplatePath, ResolvedType } from "data-path";
-
-// 1. Accept a specific path structure
-function NameInput({ fieldPath }: { fieldPath: Path<User, string> }) {
-    return <input name={fieldPath.$} />;
-}
-
-// 2. Extract the resolved value type from an existing path
-const agePath = path<User>(p => p.profile.age);
-type Age = ResolvedType<typeof agePath>; // number
-```
-
-## 💼 Real-World Examples
-
-### 1. React Hook Form
-
-Bind deeply nested fields with 100% type safety. Use runtime indices (like `i` from `useFieldArray`'s map) directly inside the path lambda. React Hook Form's `register` accepts dot-notation names (e.g. `users.0.firstName`).
-
-```tsx
-import { useForm, useFieldArray } from "react-hook-form";
-import { path } from "data-path";
-
-type FormValues = { users: Array<{ id: string; firstName: string }> };
-
-function UsersForm() {
-    const { register, control } = useForm<FormValues>({
-        defaultValues: { users: [{ id: "1", firstName: "" }] },
-    });
-    const { fields } = useFieldArray({ control, name: "users" });
-
-    return (
-        <form>
-            {fields.map((field, i) => {
-                const namePath = path<FormValues>(p => p.users[i].firstName);
-                return (
-                    <input
-                        key={field.id}
-                        {...register(namePath.$)}
-                        placeholder="First name"
-                    />
-                );
-            })}
-        </form>
-    );
-}
-```
-
-### 2. TanStack Form
-
-Define exact field accessors for complex interactive forms, even inside deeply nested arrays. TanStack Form's `Field` uses `name` (dot-notation for nested paths) and a render prop with `field.state.value` and `field.handleChange`.
-
-```tsx
-import { useForm } from "@tanstack/react-form";
-import { path } from "data-path";
-
-type FormValues = { users: Array<{ firstName: string }> };
-
-function UsersForm() {
-    const form = useForm<FormValues>({
-        defaultValues: { users: [{ firstName: "" }] },
-        onSubmit: ({ value }) => console.log(value),
-    });
-
-    return (
-        <form>
-            {form.state.values.users.map((_, i) => {
-                const namePath = path<FormValues>(p => p.users[i].firstName);
-                return (
-                    <form.Field key={i} name={namePath.$}>
-                        {field => (
-                            <input
-                                name={field.name}
-                                value={field.state.value}
-                                onChange={e =>
-                                    field.handleChange(e.target.value)
-                                }
-                            />
-                        )}
-                    </form.Field>
-                );
-            })}
-        </form>
-    );
-}
-```
-
-### 3. Zustand
-
-Update deeply nested state easily without needing Immer. Pass a function to `set` that receives the current state and returns the updated state via `path.set()`.
-
-```typescript
-import { create } from "zustand";
-import { path } from "data-path";
-
-type StoreState = {
-    settings: { profile: { theme: string } };
-    setTheme: (theme: string) => void;
-};
-
-const themePath = path<StoreState>(p => p.settings.profile.theme);
-
-const useStore = create<StoreState>(set => ({
-    settings: { profile: { theme: "light" } },
-    setTheme: newTheme => set(state => themePath.set(state, newTheme)),
-}));
+npm install data-path
 ```
 
-### 4. React `useState`
+Requirements: Node `>=20`, TypeScript `>=5.0`
 
-Update deeply nested state with the functional updater. React requires a new object reference; `path.set()` returns a structural clone so you avoid manual spreading.
+## Quick start
 
-```tsx
-import { useState } from "react";
+```ts
 import { path } from "data-path";
 
-type AppState = { settings: { profile: { theme: string } } };
-
-const themePath = path<AppState>(p => p.settings.profile.theme);
+type User = { profile: { firstName: string; lastName: string }; tags: string[] };
 
-function ThemeToggle() {
-    const [state, setState] = useState<AppState>({
-        settings: { profile: { theme: "light" } },
-    });
+const firstNamePath = path((u: User) => u.profile.firstName);
 
-    const setTheme = (theme: string) => {
-        setState(prev => themePath.set(prev, theme));
-    };
-
-    return <button onClick={() => setTheme("dark")}>{state.settings.profile.theme}</button>;
-}
+firstNamePath.$                        // "profile.firstName"
+firstNamePath.get(user)                // "Alice" | undefined
+firstNamePath.set(user, "Bob")         // returns a new User — original unchanged
+firstNamePath.fn                       // stable (u: User) => string | undefined
 ```
 
-### 5. Zod / Validation Mapping
-
-Map Zod validation errors to specific UI fields. Zod's `ZodError` has an `issues` array; each issue has a `path` (e.g. `["user", "age"]`) that you can join to compare with `data-path`.
-
-```typescript
-import { z } from "zod";
-import { unsafePath, path } from "data-path";
+## Works well with
 
-const schema = z.object({
-    user: z.object({ age: z.number().min(18) }),
-});
-type FormData = z.infer<typeof schema>;
-const agePath = path<FormData>(p => p.user.age);
+| Package | How it helps |
+|---------|--------------|
+| [React Hook Form](https://sergeyshmakov.github.io/data-path/integrations/react-hook-form/) | Type-safe field names for `register`, `watch`, `setValue` |
+| [TanStack Form](https://sergeyshmakov.github.io/data-path/integrations/tanstack-form/) | Typed field names with runtime index support |
+| [TanStack Table](https://sergeyshmakov.github.io/data-path/integrations/tanstack-table/) | Typed column accessors — no manual `id` strings |
+| [Zustand](https://sergeyshmakov.github.io/data-path/integrations/zustand/) | Immutable nested state updates without Immer |
+| [Zod](https://sergeyshmakov.github.io/data-path/integrations/zod/) | Map `ZodError.issues` paths to specific form fields |
+| [React `useState`](https://sergeyshmakov.github.io/data-path/integrations/react-usestate/) | Structural clones for deeply nested state |
 
-const result = schema.safeParse(data);
-if (!result.success) {
-    for (const issue of result.error.issues) {
-        const errorPath = unsafePath<FormData>(issue.path.join("."));
-        if (errorPath.equals(agePath)) {
-            console.log("Age must be at least 18!");
-        }
-    }
-}
-```
-
-### 6. TanStack Table
-
-Define type-safe column accessors. `createColumnHelper.accessor()` accepts an accessor function; use `path.fn` for the extractor and `path.$` for the column `id` (required when using an accessor function).
+## Guides
 
-```typescript
-import { createColumnHelper } from "@tanstack/react-table";
-import { path } from "data-path";
+- [Data access](https://sergeyshmakov.github.io/data-path/guides/data-access/) — `get`, `set`, `update`, `fn`
+- [Templates](https://sergeyshmakov.github.io/data-path/guides/templates/) — `each`, `deep`, bulk writes across collections
+- [Path algebra](https://sergeyshmakov.github.io/data-path/guides/path-algebra/) — `merge`, `subtract`, `slice`, `to`
+- [Relational](https://sergeyshmakov.github.io/data-path/guides/relational/) — `startsWith`, `covers`, `match`
+- [Runtime variables](https://sergeyshmakov.github.io/data-path/guides/runtime-variables/) — dynamic indices and closures
 
-type User = { id: string; contact: { email: string } };
+## AI tooling
 
-const columnHelper = createColumnHelper<User>();
-const emailPath = path<User>(p => p.contact.email);
+This package is available in [Context7](https://context7.com/) and documented in a [Cubic wiki](https://www.cubic.dev/wikis/sergeyshmakov/data-path). An [Agent Skills](https://agentskills.io/)-compatible skill is included:
 
-const columns = [
-    columnHelper.accessor(emailPath.fn, {
-        id: emailPath.$,
-        header: "Email",
-        cell: info => info.getValue(),
-    }),
-];
+```bash
+npx ctx7 skills install /sergeyshmakov/data-path data-path
 ```
 
-## 🤝 Contributing
+## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## 📄 License
+## License
 
-This project is licensed under the [ISC License](LICENSE).
+[MIT License](LICENSE)