use-abcd 0.0.1

package/README.md

@@ -0,0 +1,93 @@
+# use-abcd (alpha)
+
+[![Build Status](https://github.com/smtrd3/common-state/workflows/CI/badge.svg)](https://github.com/smtrd3/common-state/actions)
+
+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
+- ⚡ Optimistic updates
+- 🗄️ Built-in caching
+- 🎯 Type-safe
+- 🚫 Automatic error handling
+- ⏳ Debounce support
+- 🔍 Request cancellation
+
+## Installation
+
+```bash
+npm install use-abcd
+# or
+yarn add use-abcd
+# or
+bun add use-abcd
+```
+
+## Quick Example
+
+```typescript
+import { useCrud } from "use-crud";
+
+type Todo = {
+  id: string;
+  title: string;
+  completed: boolean;
+};
+
+function TodoList() {
+  const { items, isLoading, create, update, remove } = useCrud<Todo>({
+    id: "todos",
+    context: {},
+    // Configure caching (optional)
+    caching: {
+      capacity: 10,
+      age: 60000, // 1 minute
+    },
+    // Fetch todos from API
+    fetch: async ({ signal }) => {
+      const response = await fetch("https://api.example.com/todos", { signal });
+      const items = await response.json();
+      return { items, metadata: {} };
+    },
+    // Create new todo
+    create: async (todo) => {
+      const response = await fetch("https://api.example.com/todos", {
+        method: "POST",
+        body: JSON.stringify(todo),
+      });
+      const { id } = await response.json();
+      return { id };
+    },
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <button onClick={() => create({ title: "New Todo", completed: false })}>Add Todo</button>
+      {items.map((item) => (
+        <div key={item.data.id}>
+          <span>{item.data.title}</span>
+          <button
+            onClick={() =>
+              update(item.data, (draft) => {
+                draft.completed = !draft.completed;
+              })
+            }
+          >
+            Toggle
+          </button>
+          <button onClick={() => remove(item.data)}>Delete</button>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## License
+
+MIT

package/dist/useCrud.d.ts

@@ -0,0 +1,139 @@
+declare type CachedItem = {
+    data: unknown;
+    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> = {
+    id: string;
+    context: C;
+    debounce?: number;
+    caching?: {
+        capacity: number;
+        age: number;
+    };
+    fetch?: FetchFn<T>;
+    create?: TransitionFn<T>;
+    update?: TransitionFn<T>;
+    remove?: TransitionFn<T>;
+    getServerSnapshot?: () => StoreState<T>;
+};
+
+export declare function customLog(title?: string, ...messages: any[]): void;
+
+/**
+ * Cache implementation for storing and managing fetch results
+ * with configurable age and capacity limits.
+ */
+export declare class FetchCache {
+    age: number;
+    capacity: number;
+    storage: Map<string, CachedItem>;
+    constructor(age?: number, capacity?: number);
+    invalidate(): void;
+    reset(age: number, capacity: number): void;
+    get(id: string): unknown;
+    put(id: string, item: unknown): void;
+    remove(id: string): void;
+    withCache: (id: string, callback: () => Promise<unknown>) => Promise<unknown>;
+}
+
+export declare type FetchFn<T extends Item = Item> = (option: QueryOption) => Promise<{
+    items: T[];
+    metadata: unknown;
+}>;
+
+export declare type Item = {
+    id: string;
+} & Record<string, unknown>;
+
+export declare type ItemWithState<T extends Item = Item> = {
+    data: T;
+    state: "create" | "update" | "delete" | "idle" | "error";
+    optimistic: boolean;
+    errors: string[];
+    input?: T;
+};
+
+export declare type QueryOption = {
+    signal: AbortSignal;
+    context: unknown;
+};
+
+export declare type StoreOptions<T extends Item = Item> = {
+    initialData?: T[];
+} & Pick<CrudConfig, "caching" | "debounce">;
+
+export declare type StoreState<T extends Item = Item> = {
+    fetchState: {
+        isLoading: boolean;
+        errors: string[];
+        metadata?: unknown;
+    };
+    items: Map<string, ItemWithState<T>>;
+};
+
+export declare type TransitionFn<T extends Item = Item> = (item: Partial<T>, option: QueryOption) => Promise<{
+    id: string;
+}>;
+
+export declare type Updater<T> = (updatable: T) => void;
+
+/**
+ * Main hook for managing CRUD operations with automatic state management.
+ * Provides access to items, metadata, loading states, and CRUD operations.
+ * @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 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: "create" | "update" | "delete" | "idle" | "error";
+        optimistic: boolean;
+        errors: string[];
+        input?: T;
+    }[];
+    metadata: unknown;
+    isLoading: boolean;
+    hasError: boolean;
+    errors: string[];
+    create: (item: Omit<T, "id">) => void;
+    update: (item: T, updater: Updater<T>, isOptimistic?: boolean) => void;
+    remove: (item: 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;
+    refetch: () => void;
+    create: (item: Omit<T, "id">) => void;
+    update: (item: T, updater: Updater<T>, isOptimistic?: boolean) => void;
+    remove: (item: T) => void;
+    cancelFetch: () => void;
+    cancelOperation: (id: string) => void;
+};
+
+export declare const useMemoDeepEquals: <T>(value: T) => T;
+
+export { }