swr-catalyst 0.1.0

package/dist/hooks/shared/helpers/applyOptimisticUpdate/index.d.ts

@@ -0,0 +1,46 @@
+import { Cache, ScopedMutator } from 'swr';
+import { SWRKey } from '../../../../types';
+/**
+ * Applies an optimistic update to the SWR cache before the mutation completes.
+ *
+ * This function immediately updates the cache with optimistic data, allowing the UI
+ * to reflect changes instantly before the server responds. It saves the original data
+ * so it can be rolled back if the mutation fails.
+ *
+ * @template TData - The type of data being mutated
+ * @template TCache - The type of the cached data
+ *
+ * @param cache - The SWR cache instance from useSWRConfig()
+ * @param mutate - The SWR mutate function from useSWRConfig()
+ * @param stableKey - The stable SWR cache key to update
+ * @param payload - Configuration object containing:
+ *   - `data`: The new data being sent to the server
+ *   - `optimisticUpdateFn`: Function that receives current cache data and new data,
+ *     and returns the optimistically updated cache
+ *
+ * @returns The original cache data before the optimistic update, for potential rollback
+ *
+ * @example
+ * // Add new todo optimistically
+ * const originalData = await applyOptimisticUpdate(cache, mutate, key, {
+ *   data: newTodo,
+ *   optimisticUpdateFn: (todos, newTodo) => [...todos, { ...newTodo, id: 'temp' }]
+ * });
+ *
+ * @example
+ * // Update todo optimistically
+ * const originalData = await applyOptimisticUpdate(cache, mutate, key, {
+ *   data: { id: 123, title: 'Updated' },
+ *   optimisticUpdateFn: (todos, update) =>
+ *     todos.map(t => t.id === update.id ? { ...t, ...update } : t)
+ * });
+ *
+ * @remarks
+ * - This function is used internally by mutation hooks when `optimisticUpdate` option is provided
+ * - The mutation is applied without revalidation (false flag) to prevent immediate server fetch
+ * - Always save the return value to enable rollback on error
+ */
+export declare function applyOptimisticUpdate<TData, TCache>(cache: Cache, mutate: ScopedMutator, stableKey: SWRKey, payload: {
+    data: TData;
+    optimisticUpdateFn: (currentData: TCache | undefined, newData: TData) => TCache;
+}): Promise<TCache | undefined>;

package/dist/hooks/shared/helpers/createMutationError/index.d.ts

@@ -0,0 +1,46 @@
+import { MutationError } from '../../../../errors';
+import { SWRKey } from '../../../../types';
+/**
+ * Creates a standardized MutationError with contextual information.
+ *
+ * This helper function constructs a consistent error object across all mutation hooks,
+ * including the operation type, resource information, and original error. It generates
+ * a descriptive error message that includes the operation, resource name, and any ID.
+ *
+ * @param operation - The type of mutation operation: 'create', 'update', or 'delete'
+ * @param stableKey - The SWR cache key that was being mutated (or null if unknown)
+ * @param err - The original error thrown by the mutation function
+ * @param additionalContext - Optional additional context:
+ *   - `data`: The data being sent (for create/update operations)
+ *   - `id`: The resource ID (for update/delete operations)
+ *
+ * @returns A new MutationError instance with full context
+ *
+ * @example
+ * // Create error for failed creation
+ * const error = createMutationError('create', key, err, {
+ *   data: { title: 'New todo' }
+ * });
+ * // Error message: "Failed to create resource "todos". Network error"
+ *
+ * @example
+ * // Create error for failed update with ID
+ * const error = createMutationError('update', key, err, {
+ *   data: { title: 'Updated' },
+ *   id: 123
+ * });
+ * // Error message: "Failed to update resource "todos" with ID 123. Validation error"
+ *
+ * @example
+ * // Create error for failed deletion
+ * const error = createMutationError('delete', key, err, { id: 123 });
+ * // Error message: "Failed to delete resource "todos" with ID 123. Not found"
+ *
+ * @remarks
+ * This function is used internally by all mutation hooks to create consistent error objects.
+ * The resulting MutationError includes helper methods like `isNetworkError()` and `getUserMessage()`.
+ */
+export declare function createMutationError(operation: "create" | "update" | "delete", stableKey: SWRKey, err: unknown, additionalContext?: {
+    data?: unknown;
+    id?: string | number;
+}): MutationError;

package/dist/hooks/shared/helpers/executeMutation/index.d.ts

@@ -0,0 +1,51 @@
+import { ScopedMutator } from 'swr';
+import { MutationError } from '../../../../errors';
+import { SWRKey } from '../../../../types';
+/**
+ * Executes a mutation function with automatic error handling and cache rollback.
+ *
+ * This helper function orchestrates the mutation execution flow:
+ * 1. Executes the mutation function
+ * 2. On success: Revalidates the cache
+ * 3. On error: Optionally rolls back optimistic updates, calls error handler, and re-throws
+ *
+ * @template TResult - The type of data returned by the mutation
+ * @template TCache - The type of the cached data
+ *
+ * @param mutationFn - The async function to execute (API call)
+ * @param options - Configuration object:
+ *   - `mutate`: The SWR mutate function from useSWRConfig()
+ *   - `stableKey`: The stable SWR cache key
+ *   - `shouldRollback`: Whether to rollback optimistic update on error
+ *   - `originalData`: The original cache data to restore on rollback
+ *   - `onError`: Callback function to handle errors (typically sets error state)
+ *
+ * @returns The result from the mutation function
+ * @throws Re-throws the MutationError after handling rollback and error callback
+ *
+ * @example
+ * // Used internally by mutation hooks
+ * const result = await executeMutation(
+ *   () => api.post('/todos', newTodo),
+ *   {
+ *     mutate,
+ *     stableKey,
+ *     shouldRollback: rollbackOnError && !!optimisticUpdate,
+ *     originalData,
+ *     onError: (err) => setError(err)
+ *   }
+ * );
+ *
+ * @remarks
+ * - This function is used internally by mutation hooks to reduce code duplication
+ * - Automatically revalidates cache on success
+ * - Handles rollback only if both shouldRollback is true and originalData exists
+ * - Always calls onError callback before re-throwing to allow state updates
+ */
+export declare function executeMutation<TResult, TCache>(mutationFn: () => Promise<TResult>, options: {
+    mutate: ScopedMutator;
+    stableKey: SWRKey;
+    shouldRollback: boolean;
+    originalData?: TCache;
+    onError: (error: MutationError) => void;
+}): Promise<TResult>;

package/dist/hooks/shared/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export { applyOptimisticUpdate } from './applyOptimisticUpdate';
+export { createMutationError } from './createMutationError';
+export { executeMutation } from './executeMutation';
+export { rollbackOptimisticUpdate } from './rollbackOptimisticUpdate';

package/dist/hooks/shared/helpers/rollbackOptimisticUpdate/index.d.ts

@@ -0,0 +1,31 @@
+import { ScopedMutator } from 'swr';
+import { SWRKey } from '../../../../types';
+/**
+ * Rolls back an optimistic update by restoring the original cache data.
+ *
+ * This function is called when a mutation fails and `rollbackOnError` is true.
+ * It restores the cache to its state before the optimistic update was applied,
+ * ensuring the UI accurately reflects the server state.
+ *
+ * @param mutate - The SWR mutate function from useSWRConfig()
+ * @param stableKey - The stable SWR cache key to restore
+ * @param originalData - The original cache data to restore (saved from applyOptimisticUpdate)
+ *
+ * @returns Promise that resolves when the rollback is complete
+ *
+ * @example
+ * // Used internally by mutation hooks on error
+ * try {
+ *   const result = await apiCall();
+ * } catch (error) {
+ *   // Restore original data if mutation fails
+ *   await rollbackOptimisticUpdate(mutate, key, originalData);
+ *   throw error;
+ * }
+ *
+ * @remarks
+ * - This function is automatically called by mutation hooks when `rollbackOnError: true` (default)
+ * - The mutation is applied without revalidation (false flag) for immediate UI update
+ * - Set `rollbackOnError: false` in mutation options to keep optimistic data on error
+ */
+export declare function rollbackOptimisticUpdate(mutate: ScopedMutator, stableKey: SWRKey, originalData: unknown): Promise<void>;

package/dist/hooks/shared/index.d.ts

@@ -0,0 +1 @@
+export * from './helpers';

package/dist/hooks/useSWRCreate/index.d.ts

@@ -0,0 +1,89 @@
+import { MutateOptions, SWRKey } from '../../types';
+import { CreateFunction } from './types';
+/**
+ * A hook for creating new data with SWR cache management and optimistic updates.
+ *
+ * @template TData - The type of data being created (e.g., `{ title: string }` for a new todo)
+ * @template TCache - The type of the cached data (e.g., `Todo[]` for a list of todos)
+ * @template TError - The type of error that might be thrown (defaults to `Error`)
+ *
+ * @param key - The structured SWR cache key to revalidate after creation.
+ *   Must be an object with `id`, optional `group`, and `data` properties, or `null`.
+ *   **Important:** The `key` object should have a stable reference (use `useMemo` if creating inline).
+ *   The `data` property should be a primitive value (string, number) or a stable reference.
+ *   Example: `{ id: 'todos', group: 'lists', data: '/api/todos' }`
+ *
+ * @param createFunction - The async function that performs the API call.
+ *   Should accept the new data and return the created item from the server.
+ *   Example: `async (newTodo) => api.post('/todos', newTodo)`
+ *
+ * @param options - Optional configuration:
+ *   - `optimisticUpdate`: Function to update cache immediately before API call completes.
+ *     Receives `(currentData, newData)` and should return the optimistically updated cache.
+ *     Example: `(todos, newTodo) => [...todos, { ...newTodo, id: 'temp-id' }]`
+ *   - `rollbackOnError`: Whether to revert optimistic update if API fails (default: `true`)
+ *
+ * @returns An object containing:
+ *   - `trigger`: Async function to call when creating data. Returns the created data from server.
+ *   - `isMutating`: Boolean indicating if mutation is in progress (useful for loading states)
+ *   - `error`: Error object if mutation failed, otherwise `null`
+ *
+ * @example
+ * // Basic usage with structured key
+ * const { trigger, isMutating, error } = useSWRCreate(
+ *   { id: 'todos', group: 'lists', data: '/api/todos' },
+ *   async (newTodo) => api.post('/todos', newTodo)
+ * );
+ *
+ * await trigger({ title: 'Buy milk' });
+ *
+ * @example
+ * // With optimistic updates
+ * const { trigger, isMutating } = useSWRCreate(
+ *   { id: 'todos', data: '/api/todos' },
+ *   createTodoAPI,
+ *   {
+ *     optimisticUpdate: (todos, newTodo) => [
+ *       ...todos,
+ *       { ...newTodo, id: 'temp-' + Date.now() }
+ *     ],
+ *     rollbackOnError: true
+ *   }
+ * );
+ *
+ * // UI updates immediately, then syncs with server
+ * await trigger({ title: 'New task', completed: false });
+ *
+ * @example
+ * // With error handling
+ * const { trigger, error } = useSWRCreate(
+ *   { id: 'todos', data: '/api/todos' },
+ *   createTodoAPI
+ * );
+ *
+ * try {
+ *   const created = await trigger({ title: 'New todo' });
+ *   console.log('Created with ID:', created.id);
+ * } catch (err) {
+ *   console.error('Failed to create:', err);
+ * }
+ *
+ * // Or use the error state
+ * if (error) {
+ *   return <div>Error: {error.message}</div>;
+ * }
+ *
+ * @example
+ * // Using with group for batch cache operations
+ * const { trigger } = useSWRCreate(
+ *   { id: 'user-todos', group: 'user-data', data: '/api/user/todos' },
+ *   createTodoAPI
+ * );
+ *
+ * // Later, you can use mutateByGroup('user-data') to revalidate all related caches
+ */
+export declare function useSWRCreate<TData = unknown, TCache = unknown, TError = Error>(key: SWRKey<TData>, createFunction: CreateFunction<TData, TCache>, options?: MutateOptions<TCache, TData>): {
+    trigger: (data: TData) => Promise<TCache | undefined>;
+    isMutating: boolean;
+    error: TError | null;
+};

package/dist/hooks/useSWRCreate/index.test.d.ts

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

package/dist/hooks/useSWRCreate/types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Function type for creating a new resource via API.
+ *
+ * @template TData - The type of data being sent to create the resource
+ * @template TResult - The type of data returned from the API
+ *
+ * @param data - The data for the new resource
+ * @returns Promise resolving to the created resource from the server
+ *
+ * @example
+ * // Basic create function
+ * const createTodo: CreateFunction<TodoInput, Todo> = async (data) => {
+ *   const response = await fetch('/api/todos', {
+ *     method: 'POST',
+ *     body: JSON.stringify(data),
+ *   });
+ *   return response.json();
+ * };
+ *
+ * @example
+ * // With axios
+ * const createUser: CreateFunction<UserInput, User> = async (data) => {
+ *   const { data: user } = await axios.post('/api/users', data);
+ *   return user;
+ * };
+ */
+export type CreateFunction<TData, TResult> = (data: TData) => Promise<TResult>;

package/dist/hooks/useSWRDelete/index.d.ts

@@ -0,0 +1,103 @@
+import { MutateOptions, SWRKey } from '../../types';
+import { DeleteFunction } from './types';
+/**
+ * A hook for deleting data with SWR cache management and optimistic updates.
+ *
+ * @template TCache - The type of the cached data (e.g., `Todo[]` for a list of todos)
+ * @template TResult - The type of the result returned by the delete API (e.g., `{ success: boolean }`)
+ * @template TError - The type of error that might be thrown (defaults to `Error`)
+ *
+ * @param key - The structured SWR cache key to revalidate after deletion.
+ *   Must be an object with `id`, optional `group`, and `data` properties, or `null`.
+ *   **Important:** The `key` object should have a stable reference (use `useMemo` if creating inline).
+ *   The `data` property should be a primitive value (string, number) or a stable reference.
+ *   Example: `{ id: 'todos', group: 'lists', data: '/api/todos' }`
+ *
+ * @param deleteFunction - The async function that performs the API delete call.
+ *   Should accept an ID and return the result from the server.
+ *   Example: `async (todoId) => api.delete(\`/todos/\${todoId}\`)`
+ *
+ * @param options - Optional configuration:
+ *   - `optimisticUpdate`: Function to update cache immediately before API call completes.
+ *     Receives `(currentData, itemId)` and should return the optimistically updated cache.
+ *     Example: `(todos, id) => todos.filter(todo => todo.id !== id)`
+ *   - `rollbackOnError`: Whether to revert optimistic update if API fails (default: `true`)
+ *
+ * @returns An object containing:
+ *   - `trigger`: Async function to call when deleting data. Accepts the ID and returns the API result.
+ *   - `isMutating`: Boolean indicating if mutation is in progress (useful for loading states)
+ *   - `error`: Error object if mutation failed, otherwise `null`
+ *
+ * @example
+ * // Basic usage with structured key
+ * const { trigger, isMutating, error } = useSWRDelete(
+ *   { id: 'todos', group: 'lists', data: '/api/todos' },
+ *   async (todoId) => api.delete(\`/todos/\${todoId}\`)
+ * );
+ *
+ * await trigger(123);
+ *
+ * @example
+ * // With optimistic updates (instant removal from UI)
+ * const { trigger, isMutating } = useSWRDelete(
+ *   { id: 'todos', data: '/api/todos' },
+ *   deleteTodoAPI,
+ *   {
+ *     optimisticUpdate: (todos, todoId) =>
+ *       todos.filter(todo => todo.id !== todoId),
+ *     rollbackOnError: true
+ *   }
+ * );
+ *
+ * // Todo disappears immediately, then syncs with server
+ * await trigger(todoId);
+ *
+ * @example
+ * // With error handling
+ * const { trigger, error } = useSWRDelete(
+ *   { id: 'todos', data: '/api/todos' },
+ *   deleteTodoAPI
+ * );
+ *
+ * try {
+ *   const result = await trigger(todoId);
+ *   console.log('Deleted:', result);
+ * } catch (err) {
+ *   console.error('Failed to delete:', err);
+ * }
+ *
+ * // Or use the error state
+ * if (error) {
+ *   return <div>Error: {error.message}</div>;
+ * }
+ *
+ * @example
+ * // With loading state for button
+ * const { trigger, isMutating } = useSWRDelete(
+ *   { id: 'todos', data: '/api/todos' },
+ *   deleteTodoAPI
+ * );
+ *
+ * return (
+ *   <button
+ *     onClick={() => trigger(todoId)}
+ *     disabled={isMutating}
+ *   >
+ *     {isMutating ? 'Deleting...' : 'Delete'}
+ *   </button>
+ * );
+ *
+ * @example
+ * // Using with group for batch cache operations
+ * const { trigger } = useSWRDelete(
+ *   { id: 'user-todos', group: 'user-data', data: '/api/user/todos' },
+ *   deleteTodoAPI
+ * );
+ *
+ * // Later, you can use mutateByGroup('user-data') to revalidate all related caches
+ */
+export declare function useSWRDelete<TCache = unknown, TResult = unknown, TError = Error>(key: SWRKey, deleteFunction: DeleteFunction<TResult>, options?: MutateOptions<TCache, string | number>): {
+    trigger: (id: string | number) => Promise<TResult | undefined>;
+    isMutating: boolean;
+    error: TError | null;
+};

package/dist/hooks/useSWRDelete/index.test.d.ts

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

package/dist/hooks/useSWRDelete/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Function type for deleting a resource via API.
+ *
+ * @template TResult - The type of data returned from the API (e.g., confirmation message, deleted item)
+ *
+ * @param id - The unique identifier of the resource to delete
+ * @returns Promise resolving to the API response (often a success message or the deleted item)
+ *
+ * @example
+ * // Basic delete function
+ * const deleteTodo: DeleteFunction<{ success: boolean }> = async (id) => {
+ *   const response = await fetch(`/api/todos/${id}`, {
+ *     method: 'DELETE',
+ *   });
+ *   return response.json();
+ * };
+ *
+ * @example
+ * // With axios, returning deleted item
+ * const deleteUser: DeleteFunction<User> = async (id) => {
+ *   const { data } = await axios.delete(`/api/users/${id}`);
+ *   return data;
+ * };
+ *
+ * @example
+ * // With error handling
+ * const deletePost: DeleteFunction<void> = async (id) => {
+ *   const response = await fetch(`/api/posts/${id}`, {
+ *     method: 'DELETE',
+ *   });
+ *   if (!response.ok) {
+ *     throw new Error(`Failed to delete: ${response.statusText}`);
+ *   }
+ * };
+ *
+ * @example
+ * // Returning just status code
+ * const deleteComment: DeleteFunction<number> = async (id) => {
+ *   const response = await fetch(`/api/comments/${id}`, {
+ *     method: 'DELETE',
+ *   });
+ *   return response.status;
+ * };
+ */
+export type DeleteFunction<TResult> = (id: string | number) => Promise<TResult>;

package/dist/hooks/useSWRUpdate/index.d.ts

@@ -0,0 +1,121 @@
+import { MutateOptions, SWRKey } from '../../types';
+import { UpdateFunction } from './types';
+/**
+ * A hook for updating existing data with SWR cache management and optimistic updates.
+ *
+ * @template TData - The type of data being updated (e.g., `{ title: string }` for updating a todo)
+ * @template TCache - The type of the cached data (e.g., `Todo[]` for a list of todos)
+ * @template TError - The type of error that might be thrown (defaults to `Error`)
+ *
+ * @param key - The structured SWR cache key to revalidate after update.
+ *   Must be an object with `id`, optional `group`, and `data` properties, or `null`.
+ *   **Important:** The `key` object should have a stable reference (use `useMemo` if creating inline).
+ *   The `data` property should be a primitive value (string, number) or a stable reference.
+ *   Example: `{ id: 'todos', group: 'lists', data: '/api/todos' }`
+ *
+ * @param updateFunction - The async function that performs the API update call.
+ *   Should accept an ID and the update data, returning the updated item from the server.
+ *   Example: `async (todoId, updates) => api.patch(\`/todos/\${todoId}\`, updates)`
+ *
+ * @param options - Optional configuration:
+ *   - `optimisticUpdate`: Function to update cache immediately before API call completes.
+ *     Receives `(currentData, { id, data })` and should return the optimistically updated cache.
+ *     Example: `(todos, { id, data }) => todos.map(t => t.id === id ? { ...t, ...data } : t)`
+ *   - `rollbackOnError`: Whether to revert optimistic update if API fails (default: `true`)
+ *
+ * @returns An object containing:
+ *   - `trigger`: Async function to call when updating data. Accepts ID and data, returns updated item.
+ *   - `isMutating`: Boolean indicating if mutation is in progress (useful for loading states)
+ *   - `error`: Error object if mutation failed, otherwise `null`
+ *
+ * @example
+ * // Basic usage with structured key
+ * const { trigger, isMutating, error } = useSWRUpdate(
+ *   { id: 'todos', group: 'lists', data: '/api/todos' },
+ *   async (todoId, updates) => api.patch(\`/todos/\${todoId}\`, updates)
+ * );
+ *
+ * await trigger(123, { completed: true });
+ *
+ * @example
+ * // With optimistic updates (instant UI update)
+ * const { trigger, isMutating } = useSWRUpdate(
+ *   { id: 'todos', data: '/api/todos' },
+ *   updateTodoAPI,
+ *   {
+ *     optimisticUpdate: (todos, { id, data }) =>
+ *       todos.map(todo =>
+ *         todo.id === id ? { ...todo, ...data } : todo
+ *       ),
+ *     rollbackOnError: true
+ *   }
+ * );
+ *
+ * // Todo updates immediately, then syncs with server
+ * await trigger(todoId, { title: 'Updated title' });
+ *
+ * @example
+ * // With error handling
+ * const { trigger, error } = useSWRUpdate(
+ *   { id: 'todos', data: '/api/todos' },
+ *   updateTodoAPI
+ * );
+ *
+ * try {
+ *   const updated = await trigger(todoId, { completed: true });
+ *   console.log('Updated:', updated);
+ * } catch (err) {
+ *   console.error('Failed to update:', err);
+ * }
+ *
+ * // Or use the error state
+ * if (error) {
+ *   return <div>Error: {error.message}</div>;
+ * }
+ *
+ * @example
+ * // With loading state for inline editing
+ * const { trigger, isMutating } = useSWRUpdate(
+ *   { id: 'todos', data: '/api/todos' },
+ *   updateTodoAPI
+ * );
+ *
+ * return (
+ *   <input
+ *     onBlur={(e) => trigger(todoId, { title: e.target.value })}
+ *     disabled={isMutating}
+ *   />
+ * );
+ *
+ * @example
+ * // Toggle boolean field
+ * const { trigger } = useSWRUpdate(
+ *   { id: 'todos', data: '/api/todos' },
+ *   updateTodoAPI,
+ *   {
+ *     optimisticUpdate: (todos, { id, data }) =>
+ *       todos.map(t => t.id === id ? { ...t, ...data } : t)
+ *   }
+ * );
+ *
+ * const toggleComplete = (todo) => {
+ *   trigger(todo.id, { completed: !todo.completed });
+ * };
+ *
+ * @example
+ * // Using with group for batch cache operations
+ * const { trigger } = useSWRUpdate(
+ *   { id: 'user-todos', group: 'user-data', data: '/api/user/todos' },
+ *   updateTodoAPI
+ * );
+ *
+ * // Later, you can use mutateByGroup('user-data') to revalidate all related caches
+ */
+export declare function useSWRUpdate<TData = unknown, TCache = unknown, TError = Error>(key: SWRKey, updateFunction: UpdateFunction<TData, TCache>, options?: MutateOptions<TCache, {
+    id: string | number;
+    data: TData;
+}>): {
+    trigger: (id: string | number, data: TData) => Promise<TCache | undefined>;
+    isMutating: boolean;
+    error: TError | null;
+};

package/dist/hooks/useSWRUpdate/index.test.d.ts

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

package/dist/hooks/useSWRUpdate/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Function type for updating an existing resource via API.
+ *
+ * @template TData - The type of data being sent to update the resource
+ * @template TResult - The type of data returned from the API
+ *
+ * @param id - The unique identifier of the resource to update
+ * @param data - The partial or complete data to update the resource with
+ * @returns Promise resolving to the updated resource from the server
+ *
+ * @example
+ * // Basic update function with PATCH
+ * const updateTodo: UpdateFunction<TodoUpdate, Todo> = async (id, data) => {
+ *   const response = await fetch(`/api/todos/${id}`, {
+ *     method: 'PATCH',
+ *     body: JSON.stringify(data),
+ *   });
+ *   return response.json();
+ * };
+ *
+ * @example
+ * // With axios and PUT
+ * const updateUser: UpdateFunction<UserUpdate, User> = async (id, data) => {
+ *   const { data: user } = await axios.put(`/api/users/${id}`, data);
+ *   return user;
+ * };
+ *
+ * @example
+ * // With error handling
+ * const updatePost: UpdateFunction<PostUpdate, Post> = async (id, data) => {
+ *   const response = await fetch(`/api/posts/${id}`, {
+ *     method: 'PATCH',
+ *     body: JSON.stringify(data),
+ *   });
+ *   if (!response.ok) {
+ *     throw new Error(`Failed to update post: ${response.statusText}`);
+ *   }
+ *   return response.json();
+ * };
+ */
+export type UpdateFunction<TData, TResult> = (id: string | number, data: TData) => Promise<TResult>;

package/dist/hooks/useStableKey/index.d.ts

@@ -0,0 +1,52 @@
+import { SWRKey } from '../../types';
+/**
+ * Creates a stable reference for SWR keys to prevent unnecessary re-renders.
+ *
+ * This hook memoizes the SWR key based on its individual properties (id, group, data)
+ * using deep equality comparison. This ensures that the key object remains stable
+ * across renders when its properties haven't changed by value, not just by reference.
+ *
+ * **Key Feature:** Handles object data with deep comparison, so you don't need to
+ * wrap complex data in `useMemo` yourself. The hook automatically detects when the
+ * actual values change vs when only the object reference changes.
+ *
+ * @template T - The type of the data property in the SWR key
+ *
+ * @param key - The SWR key object to stabilize, or null if not ready
+ *
+ * @returns A memoized SWR key with stable reference, or null if key is null or invalid
+ *
+ * @example
+ * // Works with primitive data (string URLs)
+ * const { trigger } = useSWRCreate(
+ *   { id: 'todos', data: '/api/todos' },
+ *   createTodo
+ * );
+ *
+ * @example
+ * // Also works with object data - no useMemo needed!
+ * function TodoList({ userId }: { userId: number }) {
+ *   const { trigger } = useSWRCreate(
+ *     // This is now safe! Hook handles object comparison
+ *     { id: 'todos', data: { url: '/api/todos', userId } },
+ *     createTodo
+ *   );
+ * }
+ *
+ * @example
+ * // Stable reference even with dynamic query params
+ * function FilteredList({ filter }: { filter: string }) {
+ *   const { trigger } = useSWRCreate(
+ *     // Hook detects when filter value changes, not just object reference
+ *     { id: 'todos', data: { url: '/api/todos', params: { filter } } },
+ *     createTodo
+ *   );
+ * }
+ *
+ * @remarks
+ * - Uses deep equality comparison via JSON serialization for object data
+ * - Falls back to reference equality for non-serializable values
+ * - Small performance cost (~1ms) for deep comparison on each render
+ * - This hook is used internally by all mutation hooks (useSWRCreate, useSWRUpdate, useSWRDelete)
+ */
+export declare function useStableKey<T = unknown>(key: SWRKey<T> | null): SWRKey<T> | null;