swr-catalyst 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pedro Barbosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,457 @@
+# swr-catalyst
+
+<div align="center">
+
+**A lightweight, type-safe library for effortless data mutations with SWR**
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/swr-catalyst)](https://bundlephobia.com/package/swr-catalyst)
+
+[Features](#features) • [Installation](#installation) • [Quick Start](#quick-start) • [API Reference](#api-reference)
+
+</div>
+
+---
+
+## Why swr-catalyst?
+
+SWR excels at data fetching, but mutations (create, update, delete) require significant boilerplate—especially with optimistic updates. **swr-catalyst** eliminates this repetition with declarative hooks that handle:
+
+- ✅ **Optimistic UI updates** with automatic rollback
+- ✅ **Loading and error states** out of the box
+- ✅ **Type-safe mutations** with full TypeScript support
+- ✅ **Advanced cache management** utilities
+- ✅ **Zero configuration** required
+
+## Features
+
+- 🎯 **Three core hooks**: `useSWRCreate`, `useSWRUpdate`, `useSWRDelete`
+- 🚀 **Optimistic updates**: Instant UI feedback with automatic error rollback
+- 📦 **Tiny footprint**: ~3KB minified + gzipped
+- 🔒 **Type-safe**: Full TypeScript support with generics
+- 🛠️ **Cache utilities**: Batch operations with `mutateById`, `mutateByGroup`, `resetCache`
+- 🔑 **Structured keys**: Uses typed `SWRKey` objects for enhanced cache management
+- ⚡ **Smart error handling**: Custom `MutationError` class with helpful context
+
+## Installation
+
+```bash
+npm install swr-catalyst
+```
+
+```bash
+pnpm add swr-catalyst
+```
+
+```bash
+yarn add swr-catalyst
+```
+
+> **Note:** This library requires `react` and `swr` as peer dependencies. Make sure you have them installed in your project.
+
+## Quick Start
+
+### Basic CRUD Operations
+
+```tsx
+import { useSWRCreate, useSWRUpdate, useSWRDelete } from 'swr-catalyst';
+
+// Create
+const { trigger: createTodo, isMutating, error } = useSWRCreate(
+  { id: 'todos', data: '/api/todos' },
+  async (newTodo) => api.post('/todos', newTodo)
+);
+
+await createTodo({ title: 'Buy milk' });
+
+// Update
+const { trigger: updateTodo } = useSWRUpdate(
+  { id: 'todos', data: '/api/todos' },
+  async (id, data) => api.patch(`/todos/${id}`, data)
+);
+
+await updateTodo(1, { completed: true });
+
+// Delete
+const { trigger: deleteTodo } = useSWRDelete(
+  { id: 'todos', data: '/api/todos' },
+  async (id) => api.delete(`/todos/${id}`)
+);
+
+await deleteTodo(1);
+```
+
+### Optimistic Updates
+
+Make your UI feel instant with optimistic updates:
+
+```tsx
+import { useSWRCreate } from 'swr-catalyst';
+
+const { trigger: addTodo } = useSWRCreate(
+  { id: 'todos', data: '/api/todos' },
+  createTodoAPI,
+  {
+    optimisticUpdate: (currentTodos, newTodo) => [
+      ...(currentTodos || []),
+      { ...newTodo, id: `temp-${Date.now()}` }
+    ],
+    rollbackOnError: true // Automatically reverts on failure
+  }
+);
+
+// UI updates immediately, syncs with server in background
+await addTodo({ title: 'New task' });
+```
+
+### Loading and Error States
+
+```tsx
+import { useSWRCreate } from 'swr-catalyst';
+
+function AddTodoForm() {
+  const { trigger: addTodo, isMutating, error } = useSWRCreate(
+    { id: 'todos', data: '/api/todos' },
+    createTodoAPI
+  );
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    const formData = new FormData(e.currentTarget);
+    
+    try {
+      await addTodo({ title: formData.get('title') });
+      e.currentTarget.reset();
+    } catch (err) {
+      // Error state is automatically updated
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="title" type="text" disabled={isMutating} />
+      <button type="submit" disabled={isMutating}>
+        {isMutating ? 'Adding...' : 'Add Todo'}
+      </button>
+      {error && <p className="error">Failed to add todo: {error.message}</p>}
+    </form>
+  );
+}
+```
+
+### Error Handling
+
+All hooks return a custom `MutationError` when mutations fail. This error class provides rich context and helpful methods for handling failures gracefully.
+
+#### Properties
+
+- `name`: Always `"MutationError"`
+- `message`: Human-readable error description
+- `context`: Object containing mutation details:
+  - `operation`: The type of mutation (`"create"`, `"update"`, or `"delete"`)
+  - `key`: The `SWRKey` that was being mutated
+  - `data`: The payload data (for create/update operations)
+  - `id`: The resource ID (for update/delete operations)
+  - `timestamp`: When the error occurred (milliseconds since epoch)
+- `originalError`: The underlying error that caused the failure
+- `stack`: Error stack trace
+
+#### Methods
+
+**`getUserMessage(): string`**
+
+Returns a user-friendly error message suitable for displaying in UI.
+
+```typescript
+const error = mutationError.getUserMessage();
+// Returns: "Failed to add todos. Please try again."
+```
+
+**`isNetworkError(): boolean`**
+
+Checks if the error was caused by network-related issues (connection failures, timeouts, etc.).
+
+```typescript
+if (error.isNetworkError()) {
+  toast.error('Network error. Check your connection and try again.', {
+    action: { label: 'Retry', onClick: handleRetry }
+  });
+}
+```
+
+**`isValidationError(): boolean`**
+
+Checks if the error was caused by validation failures (invalid data, required fields, etc.).
+
+```typescript
+if (error.isValidationError()) {
+  // Show validation-specific message
+  toast.error('Please check your input and try again.');
+} else {
+  // Show generic error with retry option
+  toast.error('Something went wrong', { action: 'Retry' });
+}
+```
+
+**`toJSON(): object`**
+
+Serializes the error to a JSON-compatible object for logging and error tracking services.
+
+```typescript
+// Send to error tracking service
+Sentry.captureException(mutationError.toJSON());
+
+// Log for debugging
+console.error('Mutation failed:', mutationError.toJSON());
+```
+
+#### Complete Example
+
+```typescript
+import { useSWRCreate, MutationError } from 'swr-catalyst';
+
+function TodoForm() {
+  const { trigger, error } = useSWRCreate(
+    { id: 'todos', data: '/api/todos' },
+    createTodoAPI
+  );
+
+  const handleSubmit = async (data) => {
+    try {
+      await trigger(data);
+    } catch (err) {
+      if (err instanceof MutationError) {
+        // Use helper methods for better UX
+        if (err.isNetworkError()) {
+          toast.error('Network error. Please check your connection.');
+        } else if (err.isValidationError()) {
+          toast.error(err.getUserMessage());
+        } else {
+          // Generic error handling
+          toast.error('Something went wrong. Please try again.');
+        }
+        
+        // Log detailed error for debugging
+        console.error('Mutation context:', err.context);
+        console.error('Original error:', err.originalError);
+      }
+    }
+  };
+
+  // Or use the error state directly
+  if (error) {
+    return <Alert>{error.getUserMessage()}</Alert>;
+  }
+
+  return <form onSubmit={handleSubmit}>...</form>;
+}
+```
+
+## Key Structure
+
+**Important:** swr-catalyst requires a specific key structure for all hooks and utilities to work properly.
+
+### SWRKey Type
+
+```typescript
+type SWRKey<T = unknown> = {
+  id: string;      // Required: Unique identifier for the cache entry
+  group?: string;  // Optional: Group name for batch operations
+  data: T;         // Required: The actual SWR key (URL, array, etc.)
+} | null;
+```
+
+### Why Structured Keys?
+
+The structured key format enables powerful cache management features:
+
+- **`id`**: Allows `mutateById()` to update specific cache entries
+- **`group`**: Enables `mutateByGroup()` to batch-update related caches
+- **`data`**: The actual key passed to SWR's fetcher function
+
+## Key Management
+
+The library handles key stability internally using deep equality comparison, so you don't need to wrap the key object yourself. The `useStableKey` hook automatically detects when values change, even for complex nested objects.
+
+```typescript
+// ✅ Simple primitive value for data
+const { trigger: createTodo } = useSWRCreate(
+  { id: 'todos', data: '/api/todos' },
+  createTodoAPI
+);
+
+// ✅ Complex object data - no useMemo needed!
+// The library handles deep equality automatically
+const { trigger: createTodo } = useSWRCreate(
+  { id: 'todos', data: { url: '/api/todos', userId: user.id } },
+  createTodoAPI
+);
+
+// ✅ Even deeply nested objects work automatically
+const { trigger: createTodo } = useSWRCreate(
+  { 
+    id: 'todos', 
+    data: { 
+      url: '/api/todos', 
+      params: { userId: user.id, filter: 'active' } 
+    } 
+  },
+  createTodoAPI
+);
+```
+
+## API Reference
+
+This library exports a set of hooks and utility functions to streamline your data mutation workflow.
+
+### Hooks
+
+#### `useSWRCreate(key, createFunction, options)`
+
+A hook for creating new data. It handles optimistic updates, loading states, and revalidates the cache upon success.
+
+*   **`key`**: A `SWRKey` object that will be revalidated after creation.
+*   **`createFunction`**: An async function `(data) => Promise<NewData>` that performs the API call.
+*   **`options`** (optional): Configuration for optimistic updates (`optimisticUpdate`, `rollbackOnError`).
+
+**Returns:** `{ trigger, isMutating, error }`
+
+#### `useSWRUpdate(key, updateFunction, options)`
+
+A hook for updating existing data.
+
+*   **`key`**: A `SWRKey` object that will be revalidated after the update.
+*   **`updateFunction`**: An async function `(id, data) => Promise<UpdatedData>` that performs the API call.
+*   **`options`** (optional): Configuration for optimistic updates.
+
+**Returns:** `{ trigger, isMutating, error }`
+
+#### `useSWRDelete(key, deleteFunction, options)`
+
+A hook for deleting data.
+
+*   **`key`**: A `SWRKey` object that will be revalidated after deletion.
+*   **`deleteFunction`**: An async function `(id) => Promise<void>` that performs the API call.
+*   **`options`** (optional): Configuration for optimistic updates.
+
+**Returns:** `{ trigger, isMutating, error }`
+
+#### `useStableKey(key)`
+
+A utility hook that memoizes an `SWRKey` using deep equality comparison. This prevents unnecessary re-renders in child components when a key's object reference changes but its values do not. It is used internally by all mutation hooks.
+
+*   **`key`**: The `SWRKey` object to stabilize.
+
+**Returns:** A memoized `SWRKey` with a stable reference.
+
+### Utilities
+
+#### `mutateById(ids, newData, options)`
+
+Mutates all SWR cache entries whose key `id` matches one or more provided IDs.
+
+*   **`ids`**: A single ID string or an array of IDs.
+*   **`newData`** (optional): The new data to set for the matched keys. If omitted, matching keys are revalidated.
+*   **`options`** (optional): SWR mutator options (`revalidate`, `populateCache`, etc.).
+
+**Example:**
+```typescript
+// Revalidate all caches related to 'user' and 'profile'
+await mutateById(['user', 'profile']);
+```
+
+#### `mutateByGroup(groups, newData, options)`
+
+Mutates all SWR cache entries whose key `group` matches one or more provided group names.
+
+*   **`groups`**: A single group string or an array of groups.
+*   **`newData`** (optional): The new data to set for the matched keys. If omitted, matching keys are revalidated.
+*   **`options`** (optional): SWR mutator options.
+
+**Example:**
+```typescript
+// Update all caches in the 'user-data' group without revalidating
+await mutateByGroup('user-data', updatedData, { revalidate: false });
+```
+
+#### `resetCache(preservedKeys)`
+
+Clears the entire SWR cache, with an option to preserve specific entries by their `id`.
+
+*   **`preservedKeys`** (optional): A single ID string or an array of IDs to exclude from the reset.
+
+**Example:**
+```typescript
+// On logout, clear all data except for public content
+await resetCache(['public-posts', 'app-config']);
+```
+
+#### `to(promise)`
+
+Wraps any promise and converts it into a `[data, error]` tuple, inspired by Go's error handling style. This avoids `try/catch` blocks for cleaner async code.
+
+*   **Returns:** A promise that always resolves with `[data, null]` on success or `[null, error]` on failure.
+
+**Example:**
+```tsx
+import { to } from 'swr-catalyst';
+
+const [result, error] = await to(createTodo({ title: 'New item' }));
+
+if (error) {
+  console.error('Mutation failed:', error);
+}
+```
+
+#### `swrMutate(mutate, key, data, shouldRevalidate)`
+
+A type-safe wrapper around SWR's `mutate` function that correctly handles the structured `SWRKey` object.
+
+*   **`mutate`**: The `mutate` function from `useSWRConfig()`.
+*   **`key`**: The `SWRKey` to mutate.
+*   **`data`** (optional): The new data to update the cache with.
+*   **`shouldRevalidate`** (optional): Whether to revalidate after mutation.
+
+**Example:**
+```typescript
+// Perform an optimistic update without revalidation
+await swrMutate(mutate, key, optimisticData, false);
+```
+
+#### `swrGetCache(cache, key)`
+
+A type-safe wrapper around SWR's `cache.get()` method that correctly handles the structured `SWRKey` object.
+
+*   **`cache`**: The `cache` object from `useSWRConfig()`.
+*   **`key`**: The `SWRKey` to look up.
+
+**Returns:** The cached data or `undefined`.
+
+**Example:**
+```typescript
+const { cache } = useSWRConfig();
+const cachedTodos = swrGetCache(cache, { id: 'todos', data: '/api/todos' });
+```
+
+## Bundle Size
+
+| Package | Minified | Minified + Gzipped |
+|---------|----------|-------------------|
+| swr-catalyst | ~11.7KB | ~3.2KB |
+
+Zero dependencies beyond peer dependencies (`react` and `swr`).
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [Pedro Barbosa](https://github.com/pedroab0)
+
+---
+
+<div align="center">
+Made with ❤️ for the SWR community
+</div>

package/dist/errors/MutationErrors/index.d.ts

@@ -0,0 +1,120 @@
+import { MutationErrorContext } from './types';
+/**
+ * Custom error class for mutation operations.
+ * Provides consistent error handling with context across all hooks and utilities.
+ */
+export declare class MutationError extends Error {
+    readonly name = "MutationError";
+    readonly context: MutationErrorContext;
+    readonly originalError: unknown;
+    /**
+     * Creates a new MutationError with context and original error information.
+     *
+     * @param message - Human-readable error message describing what failed
+     * @param context - Contextual information about the mutation operation
+     * @param context.operation - Type of mutation: 'create', 'update', or 'delete'
+     * @param context.key - The SWR cache key that was being mutated
+     * @param context.data - The data that was being sent (for create/update)
+     * @param context.id - The ID of the resource (for update/delete)
+     * @param context.timestamp - When the error occurred (milliseconds since epoch)
+     * @param originalError - The underlying error that caused the mutation to fail
+     *
+     * @example
+     * throw new MutationError(
+     *   'Failed to create todo',
+     *   {
+     *     operation: 'create',
+     *     key: { id: 'todos', data: '/api/todos' },
+     *     data: { title: 'New todo' },
+     *     timestamp: Date.now()
+     *   },
+     *   new Error('Network request failed')
+     * );
+     */
+    constructor(message: string, context: MutationErrorContext, originalError: unknown);
+    /**
+     * Returns a user-friendly error message suitable for displaying in UI.
+     *
+     * Converts technical operation names to user-friendly verbs and includes
+     * the resource name from the cache key.
+     *
+     * @returns A formatted error message like "Failed to add todos. Please try again."
+     *
+     * @example
+     * const error = new MutationError(
+     *   'Failed to create resource "todos"',
+     *   { operation: 'create', key: { id: 'todos' }, timestamp: Date.now() },
+     *   originalErr
+     * );
+     * console.log(error.getUserMessage()); // "Failed to add todos. Please try again."
+     */
+    getUserMessage(): string;
+    /**
+     * Serializes the error to a JSON-compatible object for logging and monitoring.
+     *
+     * Useful for sending error details to error tracking services like Sentry,
+     * LogRocket, or custom logging systems.
+     *
+     * @returns An object containing all error details including context and original error
+     *
+     * @example
+     * const errorData = mutationError.toJSON();
+     * Sentry.captureException(errorData);
+     *
+     * @example
+     * // Returns:
+     * // {
+     * //   name: 'MutationError',
+     * //   message: 'Failed to create resource "todos"',
+     * //   context: { operation: 'create', key: {...}, ... },
+     * //   originalError: { name: 'Error', message: '...', stack: '...' },
+     * //   stack: '...'
+     * // }
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        context: MutationErrorContext;
+        originalError: string | {
+            name: string;
+            message: string;
+            stack: string | undefined;
+        };
+        stack: string | undefined;
+    };
+    /**
+     * Determines if the error was caused by network-related issues.
+     *
+     * Checks the original error's name and message for common network error indicators
+     * like 'NetworkError', 'fetch', 'network', or 'timeout'.
+     *
+     * @returns `true` if the error appears to be network-related, `false` otherwise
+     *
+     * @example
+     * if (error.isNetworkError()) {
+     *   // Show retry button
+     *   toast.error('Network error. Please try again.', {
+     *     action: { label: 'Retry', onClick: handleRetry }
+     *   });
+     * }
+     */
+    isNetworkError(): boolean;
+    /**
+     * Determines if the error was caused by validation failures.
+     *
+     * Checks the original error's message for common validation error indicators
+     * like 'validation', 'invalid', or 'required'.
+     *
+     * @returns `true` if the error appears to be validation-related, `false` otherwise
+     *
+     * @example
+     * if (error.isValidationError()) {
+     *   // Show validation message without retry option
+     *   toast.error(error.getUserMessage());
+     * } else {
+     *   // Show generic error with retry
+     *   toast.error('Something went wrong', { action: 'Retry' });
+     * }
+     */
+    isValidationError(): boolean;
+}

package/dist/errors/MutationErrors/types.d.ts

@@ -0,0 +1,98 @@
+import { SWRKey } from '../../types';
+/**
+ * The type of mutation operation that was being performed.
+ *
+ * @remarks
+ * Used in error context to identify what operation failed and generate appropriate error messages.
+ */
+export type MutationOperation = "create" | "update" | "delete";
+/**
+ * Contextual information about a failed mutation operation.
+ *
+ * This context is attached to every MutationError to provide detailed information
+ * about what operation failed, which resource was involved, and when it happened.
+ * This data is useful for error tracking, debugging, and user feedback.
+ *
+ * @example
+ * // Context for a failed create operation
+ * {
+ *   operation: 'create',
+ *   key: { id: 'todos', data: '/api/todos' },
+ *   data: { title: 'New todo' },
+ *   timestamp: 1698345600000
+ * }
+ *
+ * @example
+ * // Context for a failed update operation
+ * {
+ *   operation: 'update',
+ *   key: { id: 'todos', data: '/api/todos' },
+ *   data: { title: 'Updated title' },
+ *   id: 123,
+ *   timestamp: 1698345600000
+ * }
+ *
+ * @example
+ * // Context for a failed delete operation
+ * {
+ *   operation: 'delete',
+ *   key: { id: 'todos', data: '/api/todos' },
+ *   id: 123,
+ *   timestamp: 1698345600000
+ * }
+ */
+export type MutationErrorContext = {
+    /**
+     * The type of mutation that failed: 'create', 'update', or 'delete'.
+     */
+    operation: MutationOperation;
+    /**
+     * The structured SWR cache key that was being mutated.
+     * Contains the resource ID, optional group, and data endpoint.
+     * Can be null if the error occurred outside of a specific cache context.
+     */
+    key: SWRKey | null;
+    /**
+     * The data that was being sent to the server.
+     * Present for 'create' and 'update' operations.
+     *
+     * @example { title: 'New todo', completed: false }
+     */
+    data?: unknown;
+    /**
+     * The ID of the resource being modified.
+     * Present for 'update' and 'delete' operations.
+     *
+     * @example 123, "todo-abc", "user-456"
+     */
+    id?: string | number;
+    /**
+     * Timestamp (milliseconds since Unix epoch) when the error occurred.
+     * Useful for error tracking and debugging timing-related issues.
+     *
+     * @example 1698345600000
+     */
+    timestamp: number;
+};
+/**
+ * Extended Error constructor type with V8's captureStackTrace method.
+ *
+ * This type is used to properly type the Error constructor when calling
+ * the V8-specific `captureStackTrace` method, which is not part of the
+ * standard ECMAScript Error type but is available in V8-based environments
+ * (Node.js, Chrome, Edge, etc.).
+ *
+ * @remarks
+ * This is an internal type used for better stack trace handling in MutationError.
+ * The type assertion is necessary because TypeScript's built-in Error type doesn't
+ * include V8-specific extensions.
+ */
+export type ErrorConstructorWithStackTrace = typeof Error & {
+    /**
+     * V8-specific method to capture a stack trace.
+     *
+     * @param targetObject - The object to attach the stack trace to
+     * @param constructorOpt - Optional constructor to exclude from the stack trace
+     */
+    captureStackTrace(targetObject: object, constructorOpt?: unknown): void;
+};

package/dist/errors/index.d.ts

@@ -0,0 +1,2 @@
+export { MutationError } from './MutationErrors';
+export type { MutationErrorContext, MutationOperation, } from './MutationErrors/types';

package/dist/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export { useStableKey } from './useStableKey';
+export { useSWRCreate } from './useSWRCreate';
+export { useSWRDelete } from './useSWRDelete';
+export { useSWRUpdate } from './useSWRUpdate';