use-abcd 0.1.1 → 0.2.0

package/README.md

@@ -29,14 +29,17 @@ bun add use-abcd
 ## Quick Example
 
 ```typescript
+// biome-ignore assist/source/organizeImports: useless
 import React, { useCallback } from "react";
+import { useCrud, useItemState, type CrudConfig, type ItemWithState } from "../useCrud";
 import { map } from "lodash-es";
-import { useCrud, useCrudOperations, type CrudConfig, type ItemWithState } from "use-abcd";
+import { wait } from "../utils";
 
 type Todo = {
+  userId: string;
   id: string;
-  description: string;
-  complete: boolean;
+  title: string;
+  completed: boolean;
 };
 
 const TodoCrud: CrudConfig<Todo> = {
@@ -47,59 +50,75 @@ const TodoCrud: CrudConfig<Todo> = {
     capacity: 10,
   },
   fetch: async () => {
-    await new Promise((resolve) => {
-      setTimeout(resolve, 200);
-    });
     return {
-      items: [
-        { id: "one", description: "Shop for electronics", complete: false },
-        { id: "two", description: "Find time for learning", complete: false },
-        { id: "three", description: "Pick stocks", complete: false },
-      ],
+      items: await fetch("https://jsonplaceholder.typicode.com/todos")
+        .then((r) => r.json())
+        .then((items) => items.slice(0, 10)),
       metadata: {},
     };
   },
+  update: async (item, { signal }) => {
+    await wait(1000, signal);
+    return { id: item.id };
+  },
 };
 
-const Item = React.memo((props: { item: ItemWithState<Todo> }) => {
-  const item = props.item;
-  const data = item.data;
-  const { update } = useCrudOperations(TodoCrud);
+const Item = React.memo(function Item(props: { item: ItemWithState<Todo> }) {
+  const { item } = props;
+  const [data, { update, states }] = useItemState("todo-crud", item);
 
   const markComplete = useCallback(() => {
-    update(item, (draft) => {
-      draft.complete = !item.data.complete;
+    update((draft) => {
+      draft.completed = !data.completed;
     });
-  }, [update, item]);
+  }, [update, data]);
 
   return (
-    <div key={data.id} className="flex gap-2 mb-1">
-      <div className={data.complete ? "line-through" : ""}>{data.description}</div>
+    <div key={data.id} className="flex justify-between gap-2 mb-1 min-w-[500px]">
+      <div
+        className={
+          data.completed ? "line-through font-bold text-gray-700" : "font-bold text-gray-700"
+        }
+      >
+        {data.title}
+      </div>
       <button
-        className="bg-blue-300 px-2 rounded active:bg-blue-400 cursor-pointer font-bold"
+        type="button"
+        className="bg-blue-300 px-2 rounded active:bg-blue-400 cursor-pointer font-bold disabled:opacity-40"
         onClick={markComplete}
+        disabled={states.has("update")}
       >
-        Complete
+        {states.has("update")
+          ? "Updating..."
+          : data.completed
+          ? "Mark incomplete"
+          : "Mark complete"}
       </button>
     </div>
   );
 });
 
-export function Todo() {
-  const { items, isLoading } = useCrud(TodoCrud);
+export const Todo = React.memo(function Todo() {
+  const {
+    items,
+    fetchState: { isLoading },
+  } = useCrud(TodoCrud);
 
   if (isLoading) {
     return <div>Loading...</div>;
   }
 
   return (
-    <div className="p-2">
-      {map(items, (item) => (
-        <Item item={item} />
-      ))}
+    <div>
+      <h2 className="font-bold text-3xl mt-4">Todo with useCrud()</h2>
+      <div className="p-2">
+        {map(items, (item) => (
+          <Item key={item.data.id} item={item} />
+        ))}
+      </div>
     </div>
   );
-}
+});
 ```
 
 > **Note**: This is a single-file library with a focused scope. Please read the source code for a deeper understanding of its implementation and capabilities.

package/dist/useCrud.d.ts

@@ -3,17 +3,7 @@ declare type CachedItem = {
     ts: number;
 };
 
-export declare type CreateStoreConfig<T extends Item = Item> = {
-    id: string;
-    initialData?: T[];
-    debounce?: number;
-    caching?: {
-        capacity: number;
-        age: number;
-    };
-};
-
-export declare type CrudConfig<T extends Item = Item, C = any> = {
+export declare type CrudConfig<T extends Item = Item, C extends object = object, M extends object = object> = {
     id: string;
     context: C;
     debounce?: number;
@@ -21,7 +11,7 @@ export declare type CrudConfig<T extends Item = Item, C = any> = {
         capacity: number;
         age: number;
     };
-    fetch?: FetchFn<T>;
+    fetch?: FetchFn<T, M>;
     create?: TransitionFn<T>;
     update?: TransitionFn<T>;
     remove?: TransitionFn<T>;
@@ -32,7 +22,7 @@ export declare type CrudConfig<T extends Item = Item, C = any> = {
  * Cache implementation for storing and managing fetch results
  * with configurable age and capacity limits.
  */
-export declare class FetchCache {
+declare class FetchCache {
     age: number;
     capacity: number;
     storage: Map<string, CachedItem>;
@@ -45,21 +35,20 @@ export declare class FetchCache {
     withCache: (id: string, callback: () => Promise<unknown>) => Promise<unknown>;
 }
 
-export declare type FetchFn<T extends Item = Item> = (option: QueryOption) => Promise<{
+export declare type FetchFn<T extends Item = Item, M extends object = object> = (option: QueryOption) => Promise<{
     items: T[];
-    metadata: unknown;
+    metadata?: M;
 }>;
 
 export declare type Item = {
     id: string;
 } & Record<string, any>;
 
-export declare type ItemWithState<T extends Item = Item> = {
+export declare type ItemWithState<T extends Item = Item, State extends TransitionStates = TransitionStates> = {
     data: T;
-    state: TransitionStates;
     optimistic: boolean;
-    errors: string[];
-    action?: [TransitionStates, T];
+    errors: Map<string, string[]>;
+    transitions: Map<string | "default", [State, State extends "idle" ? undefined : T, ts: number]>;
 };
 
 export declare type QueryOption = {
@@ -67,24 +56,68 @@ export declare type QueryOption = {
     context: unknown;
 };
 
-export declare type StoreOptions<T extends Item = Item> = {
-    initialData?: T[];
-} & Pick<CrudConfig, "caching" | "debounce">;
+/**
+ * Core state management store for CRUD operations.
+ * Handles data fetching, caching, and state transitions for items.
+ * @template T - Type of items managed by the store, must extend Item base type
+ */
+declare class Store<T extends Item = Item, C extends object = object, M extends object = object> {
+    private id;
+    private config;
+    batched: boolean;
+    state: StoreState<T, C, M>;
+    subscribers: Set<() => void>;
+    controllers: Map<string, AbortController>;
+    fetchController: AbortController;
+    fetchCache: FetchCache;
+    constructor(id: string, config: CrudConfig<T, C, M>);
+    executeFetch: (newContext: C) => Promise<void>;
+    executeRemove: (input: T) => Promise<void>;
+    executeUpdate: ({ item, updater, isOptimistic, skipSave, tag, }: {
+        item: T;
+        updater?: Updater<T>;
+        isOptimistic?: boolean;
+        skipSave?: boolean;
+        tag?: string;
+    }) => Promise<void>;
+    executeCreate: (input: Partial<T>) => Promise<void>;
+    private getCacheKey;
+    private getControlerId;
+    customLog: (title?: string, ...messages: any[]) => void;
+    private batch;
+    private setItems;
+    private setMetadata;
+    private setContext;
+    private remove;
+    private updateItem;
+    clearFetchCache: () => void;
+    private startFetch;
+    private endFetch;
+    cancelFetch: () => void;
+    cancelOperation: (id: string, tag?: string) => void;
+    private startTransition;
+    private notify;
+    getSnapshot: () => StoreState<T, C, M>;
+    subscribe: (fn: () => void) => () => void;
+    static instances: Map<string, Store<any>>;
+    static createStore<T extends Item = Item, C extends object = object, M extends object = object>(config: CrudConfig<T, C, M>): Store<T, C>;
+}
 
-export declare type StoreState<T extends Item = Item> = {
+export declare type StoreState<T extends Item = Item, C extends object = object, M extends object = object> = {
+    context: C;
+    items: Map<string, ItemWithState<T>>;
     fetchState: {
         isLoading: boolean;
         errors: string[];
-        metadata?: unknown;
+        metadata?: M;
     };
-    items: Map<string, ItemWithState<T>>;
 };
 
 export declare type TransitionFn<T extends Item = Item> = (item: Partial<T>, option: QueryOption) => Promise<{
     id: string;
 }>;
 
-export declare type TransitionStates = "create" | "update" | "delete" | "idle" | "error" | "changed";
+export declare type TransitionStates = "create" | "update" | "delete" | "idle" | "changed";
 
 export declare type Updater<T> = (updatable: T) => void;
 
@@ -96,50 +129,41 @@ export declare type Updater<T> = (updatable: T) => void;
  * @param config - Configuration object for CRUD operations
  * @returns Object containing items, state information, and CRUD operation handlers
  */
-export declare function useCrud<T extends Item = Item, C extends Record<string, any> = any>(config: CrudConfig<T, C>): {
-    itemsById: Map<string, ItemWithState<T>>;
-    items: {
-        id: string;
-        data: T;
-        state: TransitionStates;
-        optimistic: boolean;
+export declare function useCrud<T extends Item = Item, C extends object = object, M extends object = object>(config: CrudConfig<T, C, M>): {
+    itemsById: Map<string, ItemWithState<T, TransitionStates>>;
+    items: ItemWithState<T, TransitionStates>[];
+    fetchState: {
+        isLoading: boolean;
         errors: string[];
-        action?: [TransitionStates, T];
-    }[];
-    metadata: unknown;
-    isLoading: boolean;
+        metadata?: M;
+    };
     hasError: boolean;
-    errors: string[];
-    create: (item: Omit<T, "id">) => void;
-    update: (item: ItemWithState<T>, updater: Updater<T>, isOptimistic?: boolean) => void;
-    change: (item: ItemWithState<T>, updater: Updater<T>) => void;
-    retry: (item: ItemWithState<T>) => void;
-    save: (item: ItemWithState<T>) => void;
-    remove: (item: ItemWithState<T>) => void;
     cancelFetch: () => void;
-    cancelOperation: (id: string) => void;
-};
-
-/**
- * Hook that provides CRUD operation handlers for managing items.
- * @template T - Type of items to manage, must extend Item base type
- * @template C - Type of context object used in operations
- * @param config - Configuration object for CRUD operations
- * @returns Object containing CRUD operation handlers and cancellation functions
- */
-export declare function useCrudOperations<T extends Item = Item, C extends Record<string, any> = any>(config: CrudConfig<T, C>): {
-    fetch: () => void;
+    cancelOperation: (id: string, tag?: string) => void;
     refetch: () => void;
-    create: (item: Omit<T, "id">) => void;
-    update: (item: ItemWithState<T>, updater: Updater<T>, isOptimistic?: boolean) => void;
-    change: (item: ItemWithState<T>, updater: Updater<T>) => void;
-    save: (item: ItemWithState<T>) => void;
-    retry: (item: ItemWithState<T>) => void;
-    remove: (item: ItemWithState<T>) => void;
-    cancelFetch: () => void;
-    cancelOperation: (id: string) => void;
+    create: (item: Partial<T>) => void;
+    remove: (item: T) => void;
+    store: Store<T, C, object>;
 };
 
-export declare const useMemoDeepEquals: <T>(value: T) => T;
+export declare function useItemState<T extends Item = Item>(storeId: string, item: ItemWithState<T>): [
+T,
+    {
+    errors: Map<string, string[]>;
+    states: Set<string>;
+    save: () => void;
+    change: (cb: Updater<T>, tag?: string) => void;
+    update: (cb: Updater<T>, options?: {
+        tag?: string;
+        isOptimistic?: boolean;
+    }) => void;
+    remove: () => void;
+    cancel: () => void;
+    hasError: boolean;
+    errorCount: number;
+    itemWithState: ItemWithState<T>;
+    store: Store<T>;
+}
+];
 
 export { }