use-abcd 1.4.3 → 1.6.1

package/README.md

@@ -1,487 +1,306 @@
-# use-abcd (alpha)
+# use-abcd
 
-[![Build Status](https://github.com/smtrd3/common-state/workflows/CI/badge.svg)](https://github.com/smtrd3/common-state/actions)
+State management library purpose-built for CRUD applications. Manages collections of records with optimistic mutations, automatic syncing, and built-in retry logic. Includes a fullstack component for implementing state synchronization between client and server.
 
-Most apps are just CRUD operations in disguise. Stop fighting complex state management frameworks and reinventing patterns. This library gives you optimized CRUD state management with built-in sync and offline-first support. Get zero-latency updates, no loading screens, and effortless API integration. Your code stays simple, your users get instant responses.
-
-A powerful React hook for managing ABCD (or CRUD) operations with optimistic updates, caching, and automatic state management.
-
-> **Note on Package Name**: The package is published as `use-abcd` on npm due to naming availability, where ABCD stands for Add, Browse, Change, and Delete - which maps directly to the traditional CRUD (Create, Read, Update, Delete) operations. While the package name uses ABCD, all internal APIs and documentation use CRUD terminology for familiarity and consistency with common programming patterns.
-
-## Features
-
-- 🔄 Automatic state management with React 19 compatible hooks
-- ⚡ Optimistic updates for instant UI feedback
-- 🗄️ Built-in caching with configurable TTL and capacity
-- 🎯 Type-safe with full TypeScript support
-- ⏳ Debounced sync with configurable delays
-- 🔄 Sync queue management with pause/resume/retry
-- 🎨 Context-based filtering and pagination
-- 🔌 End-to-end type-safe client-server sync utilities
-
-## Installation
-
-```bash
+```
 npm install use-abcd
-# or
-yarn add use-abcd
-# or
-bun add use-abcd
 ```
 
-## Package Exports
-
-The package provides multiple entry points:
-
-```typescript
-// Main package - React hooks and client-side sync utilities
-import { useCrud, Collection, createSyncClient } from "use-abcd";
-
-// Runtime client - Client & server sync utilities (for isomorphic code)
-import { createSyncClient, createSyncServer } from "use-abcd/runtime/client";
+## Basic Usage
 
-// Runtime server - Server-side sync utilities only
-import { createSyncServer, serverSyncSuccess } from "use-abcd/runtime/server";
-```
-
-## Quick Start
+A collection is defined by a `Config` object with an `id`, an `initialContext` (the query parameters), and a `handler` that fetches and syncs data.
 
-```typescript
-import { useCrud, type Config } from "use-abcd";
+```ts
+import { useCrud, createSyncClient } from "use-abcd";
 
 interface Todo {
   id: string;
   title: string;
-  completed: boolean;
+  done: boolean;
 }
 
-const TodoConfig: Config<Todo, {}> = {
-  id: "todos",
-  initialContext: {},
-  getId: (item) => item.id,
-
-  onFetch: async (context, signal) => {
-    const response = await fetch("/api/todos", { signal });
-    const data = await response.json();
-    return data.items;
-  },
-
-  onSync: async (changes, signal) => {
-    // Handle create, update, delete operations
-    const results = [];
-    for (const change of changes) {
-      // Process each change and return results
-      results.push({ id: change.id, status: "success" });
-    }
-    return results;
-  },
-};
-
-function TodoList() {
-  const { items, loading, create, update, remove } = useCrud(TodoConfig);
-
-  // Use items, create, update, remove in your UI
+interface Query {
+  status: "all" | "active" | "done";
 }
-```
-
-## Core Concepts
-
-### Config
 
-The `Config` object defines how your data is fetched, synced, and managed:
-
-```typescript
-type Config<T extends object, C> = {
-  id: string; // Unique identifier for this collection
-  initialContext: C; // Initial context (filters, pagination, etc.)
-  getId: (item: T) => string; // Extract ID from item
-  setId?: (item: T, newId: string) => T; // Optional: for ID remapping on create
-
-  // Optional sync configuration
-  syncDebounce?: number; // Debounce delay for sync (default: 300ms)
-  syncRetries?: number; // Max retry attempts (default: 3)
-
-  // Optional cache configuration
-  cacheCapacity?: number; // Max cache entries (default: 10)
-  cacheTtl?: number; // Cache TTL in ms (default: 60000)
-
-  // Required handlers
-  onFetch: (context: C, signal: AbortSignal) => Promise<T[]>;
-  onSync?: (changes: Change<T>[], signal: AbortSignal) => Promise<SyncResult[]>;
+const config = {
+  id: "todos",
+  initialContext: { status: "all" } as Query,
+  handler: createSyncClient<Todo, Query>("/api/todos"),
 };
 ```
 
-### Hook API
-
-The `useCrud` hook returns:
-
-```typescript
-{
-  // State
-  items: Map<string, T>;         // Current items
-  context: C;                    // Current context
-  loading: boolean;              // Fetch loading state
-  syncing: boolean;              // Sync in progress
-  syncQueue: SyncQueueState<T>;  // Sync queue state
-
-  // Item operations (optimistic)
-  create: (item: T) => void;
-  update: (id: string, mutate: (draft: T) => void) => void;
-  remove: (id: string) => void;
-  getItem: (id: string) => Item<T, C>;
-  getItemStatus: (id: string) => ItemStatus | null;
-
-  // Context & refresh
-  setContext: (mutate: (draft: C) => void) => void;
-  refresh: () => Promise<void>;
-
-  // Sync controls
-  pauseSync: () => void;
-  resumeSync: () => void;
-  retrySync: (id?: string) => void;
+The `handler` is a single function that serves both fetching and syncing. When the collection needs data it calls the handler with `{ query }`. When local mutations need to be pushed it calls with `{ changes }`. `createSyncClient` creates a handler that talks to a remote endpoint over HTTP.
+
+### `useCrud`
+
+The main hook. Returns the collection's items, state flags, and mutation functions.
+
+```tsx
+function TodoApp() {
+  const {
+    items,        // Map<string, Todo>
+    loading,      // true during initial fetch
+    syncing,      // true while pushing changes
+    context,      // current query context
+    create,       // (item: Omit<Todo, "id">) => string
+    update,       // (id, (draft) => void) => void
+    remove,       // (id) => void
+    setContext,   // (mutator) => void — triggers refetch
+    getItem,      // (id) => Item<Todo>
+    getItemStatus,// (id) => ItemStatus | null
+    refresh,      // () => Promise<void>
+    pauseSync,    // () => void
+    resumeSync,   // () => void
+    retrySync,    // (id?) => void
+  } = useCrud(config);
+
+  // ...render
 }
 ```
 
-## Examples
-
-The repository includes examples demonstrating various use cases:
-
-- **Products** - Full CRUD with filtering, search, and error handling
-- **Pagination** - Context-based pagination with dynamic page size
-- **Optimistic Updates** - Comments with instant UI feedback and sync queue visualization
-- **Blog Post** - Simple single-item editing
-- **Todo List** - Basic list operations
+Mutations are optimistic — `create`, `update`, and `remove` update local state immediately and queue changes for sync in the background. The sync queue batches changes, debounces flushes, and retries on failure.
 
-Run locally: `bun run dev` or `npm run dev` and visit `http://localhost:5173`
+### `useItem`
 
-## Advanced Usage
+Subscribe to a single item without re-rendering on unrelated changes. Takes an `Item` reference from `getItem`.
 
-### Individual Item Management
+```tsx
+function TodoRow({ item }: { item: Item<Todo> }) {
+  const { data, status, update, remove, exists } = useItem(item);
 
-Use `getItem()` with `useItem()` for managing individual items:
+  // ...render
+}
+```
 
-```typescript
-import { useCrud, useItem } from "use-abcd";
+### Context
 
-function ProductList() {
-  const { items, getItem } = useCrud(ProductsConfig);
+Context drives the query sent to the handler on fetch. Changing it triggers a refetch.
 
-  return (
-    <div>
-      {Array.from(items.keys()).map((id) => (
-        <ProductItem key={id} item={getItem(id)} />
-      ))}
-    </div>
-  );
-}
+```tsx
+setContext((draft) => {
+  draft.status = "active";
+});
+```
 
-function ProductItem({ item }: { item: Item<Product, ProductContext> }) {
-  const { data, status, update, remove, exists } = useItem(item);
+### Config Options
 
-  if (!exists) return null;
-
-  return (
-    <div>
-      <h3>{data?.name}</h3>
-      <p>Status: {status?.status || "synced"}</p>
-      <button onClick={() => update((draft) => { draft.stock += 1; })}>
-        Add Stock
-      </button>
-      <button onClick={() => remove()}>Delete</button>
-    </div>
-  );
+```ts
+{
+  id: string;               // unique collection identifier
+  initialContext: C;         // starting query state
+  handler?: CrudHandler;    // fetch + sync function
+  serverItems?: T[];        // initial items for SSR hydration
+
+  // Sync
+  syncDebounce?: number;    // ms, default 300
+  syncRetries?: number;     // default 3
+  refetchOnMutation?: boolean; // refetch after create/delete, default false
+
+  // Cache
+  cacheCapacity?: number;   // context cache slots, default 10
+  cacheTtl?: number;        // ms, default 60000
+
+  // Fetch
+  fetchRetries?: number;    // default 0
 }
 ```
 
-**Benefits:**
+## Tree State
 
-- `useItem()` subscribes only to that specific item's changes
-- React re-renders only when that item's data changes (automatic optimization via WeakMap cache)
-- Clean separation of list and item concerns
+The library supports tree-shaped state using `useCrudTree`. Nodes are stored as a flat key-value map internally, with parent-child relationships encoded in the node IDs using a separator (default `.`). A node with id `root.settings.theme` is a child of `root.settings`.
 
-### Context-Based Filtering & Pagination
+```ts
+import { useCrudTree, type TreeConfig } from "use-abcd";
 
-Use context to manage filters, pagination, sorting:
-
-```typescript
-interface ProductContext {
-  page: number;
-  limit: number;
-  category?: string;
-  search?: string;
+interface FieldValue {
+  label: string;
 }
 
-const { items, context, setContext } = useCrud<Product, ProductContext>(config);
+type NodeType = "object" | "array" | "primitive";
 
-// Update context to refetch
-setContext((draft) => {
-  draft.category = "electronics";
-  draft.page = 1;
-});
+const config: TreeConfig<FieldValue, {}, NodeType> = {
+  id: "tree-editor",
+  initialContext: {},
+  rootId: "root",
+  // nodeSeparator: ".", // default
+  handler: createSyncClient("/api/tree"),
+};
 ```
 
-### Sync Queue Monitoring
+### `useCrudTree`
 
-Track pending changes and errors:
+Returns the root node, selection state, serialization, and all the standard sync controls.
 
-```typescript
-const { syncQueue, pauseSync, resumeSync, retrySync } = useCrud(config);
+```tsx
+function TreeEditor() {
+  const {
+    rootNode,       // Node | null
+    selectedNode,   // Node | null
+    selectedNodeId, // string | null
+    selectNode,     // (id) => void
+    deselectNode,   // () => void
+    getNode,        // (id) => Node
+    toJson,         // () => object | null
+    // ...same sync controls as useCrud
+  } = useCrudTree(config);
 
-// Check queue state
-console.log({
-  pending: syncQueue.queue.size,
-  inFlight: syncQueue.inFlight.size,
-  errors: syncQueue.errors.size,
-});
-
-// Control sync
-pauseSync();
-resumeSync();
-retrySync(); // Retry all failed items
-retrySync(itemId); // Retry specific item
+  // ...render
+}
 ```
 
-### ID Remapping for Optimistic Creates
-
-Handle temporary IDs that get replaced by server-assigned IDs:
-
-```typescript
-onSync: async (changes, signal) => {
-  for (const change of changes) {
-    if (change.type === "create") {
-      const response = await fetch("/api/items", {
-        method: "POST",
-        body: JSON.stringify(change.data),
-        signal,
-      });
-      const data = await response.json();
-
-      // Return newId to remap temp ID to server ID
-      return {
-        id: change.id, // Temporary ID (e.g., "temp-123")
-        status: "success",
-        newId: data.id, // Server-assigned ID (e.g., "456")
-      };
-    }
-    // ... handle update and delete
-  }
-};
+### `useNode`
+
+Subscribe to a single tree node. Provides navigation, mutation, and reordering operations.
+
+```tsx
+function TreeNodeRow({ node }: { node: Node<FieldValue, {}, NodeType> }) {
+  const {
+    data,        // TreeNode<FieldValue, NodeType> | undefined
+    children,    // Node[]
+    depth,       // nesting level
+    exists,      // boolean
+    isSelected,  // boolean
+    status,      // ItemStatus
+
+    // Tree mutations
+    append,      // (value, type?) => string — add child at end
+    prepend,     // (value, type?) => string — add child at start
+    moveUp,      // () => void
+    moveDown,    // () => void
+    move,        // (position, targetParent?) => void — reparent
+    clone,       // () => Map — deep clone subtree
+
+    // Node mutations
+    updateProp,  // (draft => void) => void — update value
+    remove,      // () => void — remove node and descendants
+
+    // Selection
+    select,      // () => void
+    deselect,    // () => void
+
+    // Navigation
+    getParent,   // () => Node | null
+  } = useNode(node);
+
+  // ...render
+}
 ```
 
-The library automatically:
+Each `TreeNode` stored in the collection has this shape:
 
-1. Updates the item's key in the `items` Map
-2. Updates the item's `id` property
-3. Updates any `Item` references
-4. Triggers UI re-render
-
-## End-to-End Type-Safe CRUD with createSyncClient & createSyncServer
+```ts
+{
+  id: string;        // e.g. "root.settings.theme"
+  position: number;  // sort order among siblings
+  value: T;          // the node's data
+  type: NodeType;    // e.g. "object" | "array" | "primitive"
+}
+```
 
-Build a complete type-safe CRUD solution with minimal boilerplate:
+### `useSelectedNode`
 
-### Client Setup
+Convenience hook to access the currently selected node from anywhere, by collection ID.
 
-```typescript
-import { useCrud, createSyncClientFromEndpoint } from "use-abcd";
+```tsx
+function Inspector() {
+  const { data, isPresent } = useSelectedNode<FieldValue, {}, NodeType>("tree-editor");
 
-interface User {
-  id: string;
-  name: string;
-  email: string;
+  // ...render
 }
+```
 
-interface UserQuery {
-  page: number;
-  limit: number;
-  search?: string;
-}
+## Server Contract
 
-const UserConfig: Config<User, UserQuery> = {
-  id: "users",
-  initialContext: { page: 1, limit: 10 },
-  getId: (user) => user.id,
+The library communicates with the server through a single `POST` endpoint. Every request and response follows a fixed shape.
 
-  // Use createSyncClientFromEndpoint for unified fetch + sync
-  ...createSyncClientFromEndpoint<User, UserQuery>("/api/users"),
-};
+### Request body
 
-function UserList() {
-  const { items, loading, create, update, remove, setContext } = useCrud(UserConfig);
-
-  return (
-    <div>
-      {loading ? <p>Loading...</p> : (
-        <>
-          {Array.from(items.values()).map((user) => (
-            <div key={user.id}>
-              <span>{user.name} - {user.email}</span>
-              <button onClick={() => update(user.id, (draft) => {
-                draft.name = "Updated Name";
-              })}>
-                Update
-              </button>
-              <button onClick={() => remove(user.id)}>Delete</button>
-            </div>
-          ))}
-          <button onClick={() => create({
-            id: `temp-${Date.now()}`,
-            name: "New User",
-            email: "new@example.com",
-          })}>
-            Add User
-          </button>
-        </>
-      )}
-    </div>
-  );
+```ts
+{
+  scope?: string;           // optional namespace
+  query?: Q;                // present on fetch requests
+  changes?: Change<T>[];    // present on sync requests
 }
 ```
 
-### Server Setup
-
-```typescript
-import { createSyncServer, serverSyncSuccess } from "use-abcd/runtime/server";
-
-// Define your handlers
-const usersHandler = createSyncServer<User, UserQuery>({
-  fetch: async (query) => {
-    // Handle pagination and search
-    return db.users.findMany({
-      skip: (query.page - 1) * query.limit,
-      take: query.limit,
-      where: query.search ? { name: { contains: query.search } } : undefined,
-    });
-  },
-
-  create: async (data) => {
-    const user = await db.users.create({ data });
-    return serverSyncSuccess({ newId: user.id });
-  },
-
-  update: async (id, data) => {
-    await db.users.update({ where: { id }, data });
-    return serverSyncSuccess();
-  },
-
-  delete: async (id) => {
-    await db.users.delete({ where: { id } });
-    return serverSyncSuccess();
-  },
-});
-
-// Use with your framework
-// Next.js App Router
-export const POST = usersHandler.handler;
-
-// Hono
-app.post("/api/users", (c) => usersHandler.handler(c.req.raw));
+A request contains `query` (to fetch data), `changes` (to push mutations), or both.
 
-// Bun.serve
-Bun.serve({
-  fetch(req) {
-    if (new URL(req.url).pathname === "/api/users") {
-      return usersHandler.handler(req);
-    }
-  },
-});
+Each change:
+```ts
+{ id: string; type: "create" | "update" | "delete"; data: T }
 ```
 
-### What You Get
-
-- **Type safety**: Full TypeScript inference from data types to API calls
-- **Automatic ID remapping**: Temporary IDs are replaced with server-assigned IDs
-- **Batch operations**: Multiple changes are sent in a single request
-- **Optimistic updates**: UI updates instantly, syncs in background
-- **Error handling**: Failed operations are tracked and can be retried
-- **Unified endpoint**: Single POST endpoint handles fetch + create/update/delete
-
-### Request/Response Format
-
-```typescript
-// Fetch + Sync in one request
-POST /api/users
-Body: {
-  query: { page: 1, limit: 10, search: "john" },
-  changes: [
-    { id: "temp-123", type: "create", data: { ... } },
-    { id: "456", type: "update", data: { ... } },
-    { id: "789", type: "delete", data: { ... } }
-  ]
-}
+### Response body
 
-Response: {
-  results: [...users],  // Fetched items
-  syncResults: [        // Sync results
-    { id: "temp-123", status: "success", newId: "999" },
-    { id: "456", status: "success" },
-    { id: "789", status: "success" }
-  ]
+```ts
+{
+  serverSyncedAt: string;   // required — server timestamp (ULID)
+  items?: T[];              // returned items from a fetch
+  syncResults?: Result[];   // per-change results from a sync
+  serverState?: S;          // optional server-side metadata
 }
 ```
 
-## API Reference
+Each result:
+```ts
+{ id: string; type: ChangeType; status: "success" | "error"; serverSyncedAt: string; error?: string }
+```
 
-### Types
+### Using the built-in runtime
 
-```typescript
-type Config<T extends object, C> = {
-  id: string;
-  initialContext: C;
-  getId: (item: T) => string;
-  setId?: (item: T, newId: string) => T;
-  syncDebounce?: number;
-  syncRetries?: number;
-  cacheCapacity?: number;
-  cacheTtl?: number;
-  onFetch: (context: C, signal: AbortSignal) => Promise<T[]>;
-  onSync?: (changes: Change<T>[], signal: AbortSignal) => Promise<SyncResult[]>;
-};
+The library ships client and server helpers that implement this contract.
 
-type Change<T> = {
-  id: string;
-  type: "create" | "update" | "delete";
-  data: T;
-};
+**Client** — creates a `handler` for your config:
 
-type SyncResult = {
-  id: string;
-  status: "success" | "error";
-  error?: string;
-  newId?: string; // For creates: server-assigned ID
-};
+```ts
+import { createSyncClient } from "use-abcd";
 
-type ItemStatus = {
-  type: "create" | "update" | "delete";
-  status: "pending" | "syncing" | "success" | "error";
-  retries: number;
-  error?: string;
-} | null;
+const handler = createSyncClient<Todo, Query>("/api/todos");
+// or with options:
+const handler = createSyncClient<Todo, Query>({
+  endpoint: "/api/todos",
+  headers: { Authorization: "Bearer ..." },
+  scope: "workspace-123",
+});
 ```
 
-## Best Practices
-
-1. **Use Optimistic Updates** - Let users see changes immediately while syncing in the background
-2. **Handle Errors Gracefully** - Show error states and provide retry mechanisms
-3. **Leverage Context** - Use context for filters, pagination, and search to trigger automatic refetches
-4. **Use getItem() + useItem()** - For individual item management with automatic React optimization
-5. **Monitor Sync Queue** - Display pending changes and errors to users for transparency
-6. **Use createSyncClient/Server** - For end-to-end type-safe CRUD with minimal boilerplate
-
-## Architecture
-
-The library is built on several core concepts:
+**Server** — creates a request handler from CRUD callbacks:
+
+```ts
+import { createCrudHandler, createSyncServer } from "use-abcd/runtime/server";
+
+const handler = createSyncServer(
+  createCrudHandler<Todo, Query>({
+    fetch: ({ scope, query }) => {
+      return db.todos.findMany({ where: { status: query.status } });
+    },
+    create: (record) => {
+      db.todos.insert(record.data);
+    },
+    update: (record) => {
+      db.todos.update(record.data.id, record.data);
+    },
+    remove: (record) => {
+      db.todos.delete(record.data.id);
+    },
+  }),
+);
+```
 
-- **Collection** - Manages the item collection, sync queue, and fetch handler
-- **SyncQueue** - Handles debounced synchronization with retry logic
-- **FetchHandler** - Manages data fetching with caching
-- **Item** - Represents individual items with WeakMap-based caching for React optimization
+`createSyncServer` returns a `(Request) => Promise<Response>` function compatible with any server that uses the Web Request/Response API (Bun, Deno, Cloudflare Workers, Next.js route handlers, etc.).
 
-All state updates use [Mutative](https://github.com/unadlib/mutative) for immutable updates, ensuring React can efficiently detect changes.
+Each callback receives a `ServerRecord<T>`:
+```ts
+{ id: string; data: T; serverSyncedAt: string; deleted: boolean }
+```
 
-## Contributing
+The `fetch` callback can return a plain array or an object with `items` and optional `serverState` for passing metadata (totals, pagination cursors, etc.) back to the client.
 
-This is an alpha release. Please read the source code for a deeper understanding of its implementation and capabilities. Contributions and feedback are welcome!
+### Custom backend
 
-## License
+If you are not using the built-in runtime, implement the POST endpoint yourself following the request/response shapes above. The key requirements:
 
-MIT
+1. Always return `serverSyncedAt` — a monotonically increasing string (ULIDs recommended). The client uses this for ordering and conflict detection.
+2. Return `syncResults` for each change in the request. Each result must include the change's `id`, `type`, and a `status` of `"success"` or `"error"`. Missing results cause the sync queue to stall.
+3. Return `items` when the request contains a `query`.