use-abcd 1.4.0 → 1.4.2

package/dist/item-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/item.d.ts

@@ -1,15 +1,11 @@
 import { Draft } from 'mutative';
 import { Collection } from './collection';
 import { ItemStatus } from './types';
-export declare class Item<T, C = unknown> {
+export declare class Item<T extends object, C = unknown> {
     private _collection;
     private _id;
     private _cachedStatus;
-    private _refCount;
     constructor(collection: Collection<T, C>, id: string);
-    _retain(): void;
-    _release(): void;
-    get refCount(): number;
     get id(): string;
     get data(): T | undefined;
     update(mutate: (draft: Draft<T>) => void): void;

package/dist/node.d.ts

@@ -0,0 +1,50 @@
+import { Draft } from 'mutative';
+import { Collection } from './collection';
+import { ItemStatus } from './types';
+export type TreeNode<T, NodeType = string> = {
+    id: string;
+    position: number;
+    value: T;
+    type: NodeType;
+};
+export declare class Node<T extends object, C = unknown, NodeType = string> {
+    private _id;
+    private _collection;
+    private _cachedStatus;
+    constructor(collection: Collection<TreeNode<T, NodeType>, C>, id: string);
+    private get _separator();
+    get id(): string;
+    get data(): TreeNode<T, NodeType> | undefined;
+    get collection(): Collection<TreeNode<T, NodeType>, C>;
+    get depth(): number;
+    exists(): boolean;
+    getStatus(): ItemStatus;
+    getParent(): Node<T, C, NodeType> | null;
+    getChildren(): Node<T, C, NodeType>[];
+    private _generateChildId;
+    append(value: T, type?: NodeType): string;
+    prepend(value: T, type?: NodeType): string;
+    /**
+     * Move node to a new position within the same parent (reordering)
+     * or to a different parent (reparenting).
+     *
+     * @param targetPosition - The target position among siblings
+     * @param targetParent - Optional target parent node. If not provided, moves within current parent.
+     */
+    move(targetPosition: number, targetParent?: Node<T, C, NodeType>): void;
+    /**
+     * Clone this node and all its descendants into a Map with remapped IDs.
+     * The root of the clone has a temporary ID that will be remapped when merged.
+     * @returns Map of cloned nodes keyed by their relative path from clone root
+     */
+    clone(): Map<string, TreeNode<T, NodeType>>;
+    /**
+     * Internal method to merge a cloned subset under this node.
+     * The cloned nodes will have their IDs prefixed with this node's ID.
+     */
+    _mergeClonedSubset(clonedSubset: Map<string, TreeNode<T, NodeType>>, position?: number): string | undefined;
+    updateProp(mutate: (draft: Draft<T>) => void): void;
+    remove(): void;
+    select(): void;
+    _updateId(newId: string): void;
+}

package/dist/node.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sync-queue.d.ts

@@ -2,6 +2,12 @@ import { Change, SyncQueueState, SyncResult, IdMapping } from './types';
 export type SyncQueueConfig<T> = {
     debounce: number;
     maxRetries: number;
+    /**
+     * Maximum number of changes to send per sync call.
+     * Useful for rate limiting or API constraints.
+     * Default: Infinity (send all queued changes)
+     */
+    batchSize?: number;
     onSync: (changes: Change<T>[], signal: AbortSignal) => Promise<SyncResult[]>;
     onIdRemap?: (mappings: IdMapping[]) => void;
 };
@@ -24,7 +30,37 @@ export declare class SyncQueue<T> {
     private _updateState;
     private _scheduleFlush;
     private _clearTimer;
+    /**
+     * Flush pending changes to the server.
+     *
+     * Flow:
+     * 1. Move queued items to inFlight (atomic swap prevents duplicate sends)
+     * 2. Flatten all changes and optionally batch by batchSize
+     * 3. Send to server via onSync callback
+     * 4. Process results (handle success, retries, ID remapping)
+     * 5. Schedule next flush if more items queued
+     */
     private _flush;
+    /**
+     * Process sync results and update state accordingly.
+     *
+     * For each item in flight:
+     * - If ALL operations succeeded: clear errors, collect ID remappings
+     * - If ANY operation failed: increment retry counter, re-queue if under maxRetries
+     *
+     * ID Remapping: When server assigns new IDs to created items (e.g., temp ID -> DB ID),
+     * we collect these mappings and notify via onIdRemap callback so the collection
+     * can update its local state.
+     */
     private _processResults;
+    /**
+     * Handle network or unexpected errors during sync.
+     *
+     * Two scenarios:
+     * 1. Aborted (e.g., SyncQueue destroyed): Re-queue all items without incrementing retries
+     * 2. Actual error: Increment retries, re-queue if under limit, record error
+     *
+     * This ensures no data loss - failed operations are preserved for retry.
+     */
     private _handleError;
 }

package/dist/types.d.ts

@@ -45,7 +45,7 @@ export type SyncQueueState<T> = {
     isSyncing: boolean;
 };
 export type FetchState = "idle" | "fetching" | "error";
-export type Config<T, C> = {
+export type Config<T extends object, C> = {
     id: string;
     initialContext: C;
     getId: (item: T) => string;
@@ -56,6 +56,9 @@ export type Config<T, C> = {
     cacheCapacity?: number;
     cacheTtl?: number;
     fetchRetries?: number;
+    rootId?: string;
+    getNodeId?: () => string;
+    nodeSeparator?: string;
     onFetch: (context: C, signal: AbortSignal) => Promise<T[]>;
     onSync?: (changes: Change<T>[], signal: AbortSignal) => Promise<SyncResult[]>;
 };

package/dist/useCrud.d.ts

@@ -1,7 +1,7 @@
 import { Draft } from 'mutative';
 import { Config, Mutator } from './types';
 export type { Config, Change, SyncResult, ItemStatus, SyncQueueState, SyncState, ChangeType, ItemSyncStatus, FetchState, } from './types';
-export declare function useCrud<T, C>(config: Config<T, C>): {
+export declare function useCrud<T extends object, C>(config: Config<T, C>): {
     items: Map<string, T>;
     context: C;
     syncState: import('./types').SyncState;

package/dist/useCrud.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/useCrudTree.d.ts

@@ -0,0 +1,45 @@
+import { Node, TreeNode } from './node';
+import { Config, Mutator } from './types';
+/**
+ * Config for useCrudTree - same as Config but with rootId required
+ */
+export type TreeConfig<T extends object, C, NodeType = string> = Omit<Config<TreeNode<T, NodeType>, C>, "rootId"> & {
+    rootId: string;
+};
+/**
+ * Hook for tree-based CRUD operations.
+ * This is a replacement for useCrud when working with tree structures.
+ * It requires rootId in the config and returns the root node along with
+ * all the standard useCrud properties.
+ *
+ * @param config - Tree collection configuration with required rootId
+ * @returns Object with crud operations, state, and the root node
+ */
+export declare function useCrudTree<T extends object, C, NodeType = string>(config: TreeConfig<T, C, NodeType>): {
+    rootNode: Node<T, C, NodeType>;
+    items: Map<string, TreeNode<T, NodeType>>;
+    context: C;
+    syncState: import('./types').SyncState;
+    syncQueue: import('./types').SyncQueueState<TreeNode<T, NodeType>>;
+    loading: boolean;
+    syncing: boolean;
+    fetchStatus: import('./types').FetchState;
+    fetchError: string;
+    getNode: (id: string) => Node<T, C, NodeType>;
+    getNodeStatus: (id: string) => {
+        type: import('./types').ChangeType;
+        status: import('./types').ItemSyncStatus;
+        retries: number;
+        error?: string;
+    };
+    setContext: (patchContext: Mutator<C>) => void;
+    refresh: () => Promise<void>;
+    pauseSync: () => void;
+    resumeSync: () => void;
+    retrySync: (id?: string) => void;
+    selectNode: (id: string) => void;
+    deselectNode: () => void;
+    selectedNodeId: string;
+    selectedNode: Node<T, C, NodeType>;
+    toJson: () => object;
+};

package/dist/useCrudTree.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/useItem.d.ts

@@ -8,4 +8,4 @@ export type UseItemResult<T> = {
     remove: () => void;
     exists: boolean;
 };
-export declare function useItem<T, C>(item: Item<T, C>): UseItemResult<T>;
+export declare function useItem<T extends object, C>(item: Item<T, C>): UseItemResult<T>;

package/dist/useNode.d.ts

@@ -0,0 +1,25 @@
+import { Draft } from 'mutative';
+import { Node, TreeNode } from './node';
+import { ItemStatus } from './types';
+/**
+ * Result type for useNode hook - contains all node data and operations
+ */
+export type UseNodeResult<T extends object, C, NodeType = string> = {
+    isPresent: boolean;
+    data: TreeNode<T, NodeType> | undefined;
+    status: ItemStatus;
+    exists: boolean;
+    isSelected: boolean;
+    depth: number;
+    getParent: () => Node<T, C, NodeType> | null;
+    children: Node<T, C, NodeType>[];
+    append: (value: T, type?: NodeType) => string;
+    prepend: (value: T, type?: NodeType) => string;
+    move: (targetPosition: number, targetParent?: Node<T, C, NodeType>) => void;
+    clone: () => Map<string, TreeNode<T, NodeType>>;
+    updateProp: (mutate: (draft: Draft<T>) => void) => void;
+    remove: () => void;
+    select: () => void;
+    deselect: () => void;
+};
+export declare function useNode<T extends object, C, NodeType = string>(node: Node<T, C, NodeType>): UseNodeResult<T, C, NodeType>;

package/dist/useSelectedNode.d.ts

@@ -0,0 +1,12 @@
+import { UseNodeResult } from './useNode';
+/**
+ * Hook for accessing and operating on the currently selected node in a collection.
+ *
+ * This is a wrapper around useNode that automatically tracks the selected node.
+ * Use this in components that need to operate on whatever node is currently selected
+ * (e.g., toolbars, property panels, context menus).
+ *
+ * @param collectionId - The ID of the collection to get the selected node from
+ * @returns UseNodeResult with isPresent=true when a node is selected, or isPresent=false with empty data
+ */
+export declare function useSelectedNode<T extends object, C, NodeType = string>(collectionId: string): UseNodeResult<T, C, NodeType>;

package/dist/useSyncState.d.ts

@@ -0,0 +1,20 @@
+import { SyncState, Change, SyncError } from './types';
+export type UseSyncStateResult<T = unknown> = {
+    syncState: SyncState;
+    syncing: boolean;
+    queue: Map<string, Change<T>[]>;
+    inFlight: Map<string, Change<T>[]>;
+    errors: Map<string, SyncError<T>>;
+    isPaused: boolean;
+    isSyncing: boolean;
+};
+/**
+ * Hook for accessing the sync state of a collection by ID.
+ *
+ * Use this when you need to display sync status in a component that
+ * doesn't have access to the full useCrud hook.
+ *
+ * @param collectionId - The ID of the collection
+ * @returns Flat object with syncState and all syncQueue properties
+ */
+export declare function useSyncState<T = unknown>(collectionId: string): UseSyncStateResult<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-abcd",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "description": "Simple react hook for CRUD type apps",
   "repository": {
     "url": "https://github.com/smtrd3/use-abcd"
@@ -53,6 +53,7 @@
     "@vitejs/plugin-react": "^5.0.0",
     "@vitest/coverage-v8": "^3.2.4",
     "ajv": "^8.17.1",
+    "baseline-browser-mapping": "^2.9.14",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",