swr-catalyst 0.2.2 → 0.3.0

package/README.md

@@ -11,6 +11,7 @@
 [![npm downloads](https://img.shields.io/npm/dm/swr-catalyst)](https://www.npmjs.com/package/swr-catalyst)
 [![CI](https://github.com/pedroab0/swr-catalyst/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroab0/swr-catalyst/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/github/pedroab0/swr-catalyst/graph/badge.svg?token=IL8XFDVYHU)](https://codecov.io/github/pedroab0/swr-catalyst)
+[![CodeScene Average Code Health](https://codescene.io/projects/73545/status-badges/average-code-health)](https://codescene.io/projects/73545)
 
 [Features](#features) • [Installation](#installation) • [Quick Start](#quick-start) • [API Reference](#api-reference)
 

package/dist/__tests__/integration/errors/index.d.ts

@@ -0,0 +1,12 @@
+import { ValidationErrorResponse } from '../types';
+/**
+ * Custom error class for API errors with status code and response body
+ */
+export declare class ApiError extends Error {
+    status: number;
+    code?: string;
+    details?: Record<string, string>;
+    constructor(message: string, status: number, body?: ValidationErrorResponse);
+    isValidationError(): boolean;
+    isNotFound(): boolean;
+}

package/dist/__tests__/integration/helpers/fetchers.d.ts

@@ -0,0 +1,12 @@
+import { Todo } from '../types';
+export declare function fetchTodos(): Promise<Todo[]>;
+export declare function fetchTodoById(id: number): Promise<Todo>;
+export declare function createTodo(todo: Todo): Promise<Todo>;
+export declare function updateTodo(id: string | number, data: Partial<{
+    title: string;
+    completed: boolean;
+}>): Promise<Todo>;
+export declare function deleteTodo(id: string | number): Promise<{
+    success: boolean;
+    id: number;
+}>;

package/dist/__tests__/integration/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export type { Todo, ValidationErrorResponse } from '../types';
+export { ApiError } from '../errors';
+export { createTodo, deleteTodo, fetchTodoById, fetchTodos, updateTodo, } from './fetchers';
+export { createMockTodo, renderHookWithGlobalCache, renderHookWithSWR, uniqueKeyId, } from './testHelpers';

package/dist/__tests__/integration/helpers/testHelpers.d.ts

@@ -0,0 +1,17 @@
+import { Todo } from '../types';
+/**
+ * Renders a hook with an isolated SWR cache.
+ * Use for hook tests where all hooks share the same wrapper context.
+ */
+export declare function renderHookWithSWR<T>(hook: () => T): import('@testing-library/react').RenderHookResult<T, unknown>;
+/**
+ * Renders a hook using the global SWR cache.
+ * Use for utility tests (mutateById, mutateByGroup, resetCache)
+ * where utilities operate on the global cache via `import { mutate } from 'swr'`.
+ */
+export declare function renderHookWithGlobalCache<T>(hook: () => T): import('@testing-library/react').RenderHookResult<T, unknown>;
+/**
+ * Generates a unique key ID to prevent cache collisions in global cache tests.
+ */
+export declare function uniqueKeyId(prefix: string): string;
+export declare function createMockTodo(overrides?: Partial<Todo>): Todo;

package/dist/__tests__/integration/hooks/concurrent.integration.test.d.ts

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

package/dist/__tests__/integration/hooks/useSWRCreate.integration.test.d.ts

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

package/dist/__tests__/integration/hooks/useSWRDelete.integration.test.d.ts

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

package/dist/__tests__/integration/hooks/useSWRUpdate.integration.test.d.ts

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

package/dist/__tests__/integration/scenarios/cacheConsistency.integration.test.d.ts

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

package/dist/__tests__/integration/scenarios/errorRecovery.integration.test.d.ts

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

package/dist/__tests__/integration/setup/basic.integration.test.d.ts

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

package/dist/__tests__/integration/setup/server.d.ts

@@ -0,0 +1,3 @@
+export declare const handlers: import('msw').HttpHandler[];
+export declare const server: import('msw/node').SetupServerApi;
+export declare function resetServerData(): void;

package/dist/__tests__/integration/setup/vitest.setup.d.ts

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

package/dist/__tests__/integration/types/index.d.ts

@@ -0,0 +1,10 @@
+export type Todo = {
+    id: number;
+    title: string;
+    completed: boolean;
+};
+export type ValidationErrorResponse = {
+    error: string;
+    code: string;
+    details?: Record<string, string>;
+};

package/dist/__tests__/integration/utilities/mutateByGroup.integration.test.d.ts

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

package/dist/__tests__/integration/utilities/mutateById.integration.test.d.ts

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

package/dist/__tests__/integration/utilities/resetCache.integration.test.d.ts

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

package/dist/errors/index.d.ts

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

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

@@ -1,5 +1,5 @@
-import { MutationError } from '../../../../errors';
 import { SWRKey } from '../../../../types';
+import { MutationError } from '../../../../errors';
 /**
  * Creates a standardized MutationError with contextual information.
  *

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

@@ -82,8 +82,8 @@ import { CreateFunction } from './types';
  *
  * // 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>;
+export declare function useSWRCreate<TData = unknown, TCache = unknown, TError = Error>(key: SWRKey<TData>, createFunction: CreateFunction<TData>, options?: MutateOptions<TCache, TData>): {
+    trigger: (data: TData) => Promise<unknown>;
     isMutating: boolean;
     error: TError | null;
 };

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

@@ -2,14 +2,13 @@
  * 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 createTodo: CreateFunction<TodoInput> = async (data) => {
  *   const response = await fetch('/api/todos', {
  *     method: 'POST',
  *     body: JSON.stringify(data),
@@ -19,9 +18,9 @@
  *
  * @example
  * // With axios
- * const createUser: CreateFunction<UserInput, User> = async (data) => {
+ * const createUser: CreateFunction<UserInput> = async (data) => {
  *   const { data: user } = await axios.post('/api/users', data);
  *   return user;
  * };
  */
-export type CreateFunction<TData, TResult> = (data: TData) => Promise<TResult>;
+export type CreateFunction<TData> = (data: TData) => Promise<unknown>;

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

@@ -96,8 +96,8 @@ import { DeleteFunction } from './types';
  *
  * // 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>;
+export declare function useSWRDelete<TCache = unknown, TError = Error>(key: SWRKey, deleteFunction: DeleteFunction, options?: MutateOptions<TCache, string | number>): {
+    trigger: (id: string | number) => Promise<unknown>;
     isMutating: boolean;
     error: TError | null;
 };

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

@@ -1,14 +1,12 @@
 /**
  * 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 deleteTodo: DeleteFunction = async (id) => {
  *   const response = await fetch(`/api/todos/${id}`, {
  *     method: 'DELETE',
  *   });
@@ -17,14 +15,14 @@
  *
  * @example
  * // With axios, returning deleted item
- * const deleteUser: DeleteFunction<User> = async (id) => {
+ * const deleteUser: DeleteFunction = async (id) => {
  *   const { data } = await axios.delete(`/api/users/${id}`);
  *   return data;
  * };
  *
  * @example
  * // With error handling
- * const deletePost: DeleteFunction<void> = async (id) => {
+ * const deletePost: DeleteFunction = async (id) => {
  *   const response = await fetch(`/api/posts/${id}`, {
  *     method: 'DELETE',
  *   });
@@ -35,11 +33,11 @@
  *
  * @example
  * // Returning just status code
- * const deleteComment: DeleteFunction<number> = async (id) => {
+ * const deleteComment: DeleteFunction = async (id) => {
  *   const response = await fetch(`/api/comments/${id}`, {
  *     method: 'DELETE',
  *   });
  *   return response.status;
  * };
  */
-export type DeleteFunction<TResult> = (id: string | number) => Promise<TResult>;
+export type DeleteFunction = (id: string | number) => Promise<unknown>;

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

@@ -111,11 +111,11 @@ import { UpdateFunction } from './types';
  *
  * // 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, {
+export declare function useSWRUpdate<TData = unknown, TCache = unknown, TError = Error>(key: SWRKey, updateFunction: UpdateFunction<TData>, options?: MutateOptions<TCache, {
     id: string | number;
     data: TData;
 }>): {
-    trigger: (id: string | number, data: TData) => Promise<TCache | undefined>;
+    trigger: (id: string | number, data: TData) => Promise<unknown>;
     isMutating: boolean;
     error: TError | null;
 };

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

@@ -2,7 +2,6 @@
  * 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
@@ -10,7 +9,7 @@
  *
  * @example
  * // Basic update function with PATCH
- * const updateTodo: UpdateFunction<TodoUpdate, Todo> = async (id, data) => {
+ * const updateTodo: UpdateFunction<TodoUpdate> = async (id, data) => {
  *   const response = await fetch(`/api/todos/${id}`, {
  *     method: 'PATCH',
  *     body: JSON.stringify(data),
@@ -20,14 +19,14 @@
  *
  * @example
  * // With axios and PUT
- * const updateUser: UpdateFunction<UserUpdate, User> = async (id, data) => {
+ * const updateUser: UpdateFunction<UserUpdate> = 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 updatePost: UpdateFunction<PostUpdate> = async (id, data) => {
  *   const response = await fetch(`/api/posts/${id}`, {
  *     method: 'PATCH',
  *     body: JSON.stringify(data),
@@ -38,4 +37,4 @@
  *   return response.json();
  * };
  */
-export type UpdateFunction<TData, TResult> = (id: string | number, data: TData) => Promise<TResult>;
+export type UpdateFunction<TData> = (id: string | number, data: TData) => Promise<unknown>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export * from './errors';
+export * from './utils';
 export * from './hooks';
 export * from './types';
-export * from './utils';

package/dist/swr-catalyst.js

@@ -1,5 +1,5 @@
-import { useRef as S, useState as p, useEffect as $, useCallback as k } from "react";
-import { mutate as R, useSWRConfig as U } from "swr";
+import { mutate as $, useSWRConfig as k } from "swr";
+import { useRef as S, useState as p, useEffect as R, useCallback as U } from "react";
 class h extends Error {
   name = "MutationError";
   context;
@@ -141,44 +141,24 @@ class h extends Error {
     return !1;
   }
 }
-function v(r, t) {
-  if (r === t)
-    return !0;
-  if (r == null || t == null)
-    return r === t;
-  if (typeof r != "object" || typeof t != "object")
-    return !1;
-  try {
-    return JSON.stringify(r) === JSON.stringify(t);
-  } catch {
-    return !1;
-  }
-}
-function x(r) {
-  const t = r?.id, e = r?.group, i = r?.data, n = S(null);
-  if (!r || !(t && i))
-    return n.current = null, n.current;
-  const a = n.current;
-  return (!a || a.id !== t || a.group !== e || !v(a.data, i)) && (n.current = { id: t, group: e, data: i }), n.current;
-}
-const A = /#id:"((?:[^"\\]|\\.)*)"/, j = /group:"((?:[^"\\]|\\.)*)"/, I = /data:"((?:[^"\\]|\\.)*)"/;
+const v = /#id:"((?:[^"\\]|\\.)*)"/, A = /group:"((?:[^"\\]|\\.)*)"/, j = /data:"((?:[^"\\]|\\.)*)"/;
 function M(r) {
   return r.replace(/\\(.)/g, "$1");
 }
-function C(r) {
+function I(r) {
   if (!r.startsWith("#id:"))
     return null;
-  const t = r.match(A);
+  const t = r.match(v);
   if (!t)
     return null;
-  const e = r.match(j), i = r.match(I);
+  const e = r.match(A), i = r.match(j);
   return {
     id: M(t[1]),
     group: e ? M(e[1]) : void 0,
     data: i ? M(i[1]) : void 0
   };
 }
-function P(r) {
+function C(r) {
   try {
     const t = JSON.parse(r);
     if (t && typeof t == "object" && "id" in t)
@@ -187,23 +167,23 @@ function P(r) {
   }
   return null;
 }
-function O(r) {
+function x(r) {
   if (typeof r == "object" && r !== null && "id" in r)
     return r;
   if (typeof r != "string")
     return null;
-  const t = C(r);
+  const t = I(r);
   if (t)
     return t;
-  const e = P(r);
+  const e = C(r);
   return e || null;
 }
 async function L(r, t, e) {
   const i = Array.isArray(r) ? r : [r];
   try {
-    await R(
+    await $(
       (n) => {
-        const a = O(n);
+        const a = x(n);
         return a?.group ? i.includes(a.group) : !1;
       },
       t ? () => t : void 0,
@@ -228,9 +208,9 @@ async function L(r, t, e) {
 async function q(r, t, e) {
   const i = typeof r == "string" ? [r] : r;
   try {
-    await R(
+    await $(
       (n) => {
-        const a = O(n);
+        const a = x(n);
         return a ? i.includes(a?.id) : !1;
       },
       t ? () => t : void 0,
@@ -256,11 +236,11 @@ const B = async (r = []) => {
   let t;
   Array.isArray(r) ? t = r : r ? t = [r] : t = null;
   try {
-    await R(
+    await $(
       (e) => {
         if (!t)
           return !0;
-        const i = O(e);
+        const i = x(e);
         return i ? !t.includes(i.id) : !0;
       },
       void 0,
@@ -278,7 +258,7 @@ const B = async (r = []) => {
     );
   }
 };
-function W(r, t) {
+function P(r, t) {
   if (t)
     return r.get(t);
 }
@@ -296,8 +276,28 @@ async function _(r) {
     return [null, t];
   }
 }
+function W(r, t) {
+  if (r === t)
+    return !0;
+  if (r == null || t == null)
+    return r === t;
+  if (typeof r != "object" || typeof t != "object")
+    return !1;
+  try {
+    return JSON.stringify(r) === JSON.stringify(t);
+  } catch {
+    return !1;
+  }
+}
+function O(r) {
+  const t = r?.id, e = r?.group, i = r?.data, n = S(null);
+  if (!r || !(t && i))
+    return n.current = null, n.current;
+  const a = n.current;
+  return (!a || a.id !== t || a.group !== e || !W(a.data, i)) && (n.current = { id: t, group: e, data: i }), n.current;
+}
 async function T(r, t, e, i) {
-  const n = W(r, e)?.data, a = i.optimisticUpdateFn(n, i.data);
+  const n = P(r, e)?.data, a = i.optimisticUpdateFn(n, i.data);
   return await y(t, e, a, !1), n;
 }
 function b(r, t, e, i) {
@@ -317,14 +317,14 @@ async function D(r, t, e) {
   await y(r, t, e, !1);
 }
 function V(r, t, e = {}) {
-  const { cache: i, mutate: n } = U(), { optimisticUpdate: a, rollbackOnError: l = !0 } = e, [E, d] = p(!1), [w, m] = p(null), o = S(!0), s = x(r);
-  return $(
+  const { cache: i, mutate: n } = k(), { optimisticUpdate: a, rollbackOnError: l = !0 } = e, [E, d] = p(!1), [w, m] = p(null), o = S(!0), s = O(r);
+  return R(
     () => () => {
       o.current = !1;
     },
     []
   ), {
-    trigger: k(
+    trigger: U(
       async (u) => {
         if (!o.current)
           return;
@@ -361,14 +361,14 @@ function V(r, t, e = {}) {
   };
 }
 function z(r, t, e = {}) {
-  const { cache: i, mutate: n } = U(), { optimisticUpdate: a, rollbackOnError: l = !0 } = e, [E, d] = p(!1), [w, m] = p(null), o = S(!0), s = x(r);
-  return $(
+  const { cache: i, mutate: n } = k(), { optimisticUpdate: a, rollbackOnError: l = !0 } = e, [E, d] = p(!1), [w, m] = p(null), o = S(!0), s = O(r);
+  return R(
     () => () => {
       o.current = !1;
     },
     []
   ), {
-    trigger: k(
+    trigger: U(
       async (u) => {
         if (!o.current)
           return;
@@ -405,14 +405,14 @@ function z(r, t, e = {}) {
   };
 }
 function H(r, t, e = {}) {
-  const { cache: i, mutate: n } = U(), { optimisticUpdate: a, rollbackOnError: l = !0 } = e, [E, d] = p(!1), [w, m] = p(null), o = S(!0), s = x(r);
-  return $(
+  const { cache: i, mutate: n } = k(), { optimisticUpdate: a, rollbackOnError: l = !0 } = e, [E, d] = p(!1), [w, m] = p(null), o = S(!0), s = O(r);
+  return R(
     () => () => {
       o.current = !1;
     },
     []
   ), {
-    trigger: k(
+    trigger: U(
       async (u, g) => {
         if (!o.current)
           return;
@@ -451,15 +451,15 @@ function H(r, t, e = {}) {
 }
 export {
   h as MutationError,
-  O as extractSWRKey,
+  x as extractSWRKey,
   L as mutateByGroup,
   q as mutateById,
   B as resetCache,
-  W as swrGetCache,
+  P as swrGetCache,
   y as swrMutate,
   _ as to,
   V as useSWRCreate,
   z as useSWRDelete,
   H as useSWRUpdate,
-  x as useStableKey
+  O as useStableKey
 };

package/dist/swr-catalyst.umd.cjs

@@ -1 +1 @@
-(function(s,o){typeof exports=="object"&&typeof module<"u"?o(exports,require("react"),require("swr")):typeof define=="function"&&define.amd?define(["exports","react","swr"],o):(s=typeof globalThis<"u"?globalThis:s||self,o(s["swr-catalyst"]={},s.React,s.SWR))})(this,(function(s,o,E){"use strict";class y extends Error{name="MutationError";context;originalError;constructor(t,e,i){super(t),this.context=e,this.originalError=i,"captureStackTrace"in Error&&Error.captureStackTrace(this,y)}getUserMessage(){const{operation:t,key:e}=this.context,i=e?.id||"resource";return`Failed to ${{create:"add",update:"update",delete:"delete"}[t]} ${i}. Please try again.`}toJSON(){return{name:this.name,message:this.message,context:this.context,originalError:this.originalError instanceof Error?{name:this.originalError.name,message:this.originalError.message,stack:this.originalError.stack}:String(this.originalError),stack:this.stack}}isNetworkError(){if(this.originalError instanceof Error){const t=this.originalError.message.toLowerCase();return this.originalError.name==="NetworkError"||t.includes("fetch")||t.includes("network")||t.includes("timeout")}return!1}isValidationError(){if(this.originalError instanceof Error){const t=this.originalError.message.toLowerCase();return t.includes("validation")||t.includes("invalid")||t.includes("required")}return!1}}function D(r,t){if(r===t)return!0;if(r==null||t==null)return r===t;if(typeof r!="object"||typeof t!="object")return!1;try{return JSON.stringify(r)===JSON.stringify(t)}catch{return!1}}function M(r){const t=r?.id,e=r?.group,i=r?.data,n=o.useRef(null);if(!r||!(t&&i))return n.current=null,n.current;const a=n.current;return(!a||a.id!==t||a.group!==e||!D(a.data,i))&&(n.current={id:t,group:e,data:i}),n.current}const j=/#id:"((?:[^"\\]|\\.)*)"/,v=/group:"((?:[^"\\]|\\.)*)"/,F=/data:"((?:[^"\\]|\\.)*)"/;function $(r){return r.replace(/\\(.)/g,"$1")}function N(r){if(!r.startsWith("#id:"))return null;const t=r.match(j);if(!t)return null;const e=r.match(v),i=r.match(F);return{id:$(t[1]),group:e?$(e[1]):void 0,data:i?$(i[1]):void 0}}function A(r){try{const t=JSON.parse(r);if(t&&typeof t=="object"&&"id"in t)return t}catch{}return null}function k(r){if(typeof r=="object"&&r!==null&&"id"in r)return r;if(typeof r!="string")return null;const t=N(r);if(t)return t;const e=A(r);return e||null}async function I(r,t,e){const i=Array.isArray(r)?r:[r];try{await E.mutate(n=>{const a=k(n);return a?.group?i.includes(a.group):!1},t?()=>t:void 0,{revalidate:e?.revalidate??!t,...e})}catch(n){throw new y(`Failed to mutate cache by group(s): ${i.join(", ")}. ${n instanceof Error?n.message:String(n)}`,{operation:"update",key:null,data:t,timestamp:Date.now()},n)}}async function P(r,t,e){const i=typeof r=="string"?[r]:r;try{await E.mutate(n=>{const a=k(n);return a?i.includes(a?.id):!1},t?()=>t:void 0,{revalidate:e?.revalidate??!t,...e})}catch(n){throw new y(`Failed to mutate cache by ID(s): ${i.join(", ")}. ${n instanceof Error?n.message:String(n)}`,{operation:"update",key:null,data:t,timestamp:Date.now()},n)}}const G=async(r=[])=>{let t;Array.isArray(r)?t=r:r?t=[r]:t=null;try{await E.mutate(e=>{if(!t)return!0;const i=k(e);return i?!t.includes(i.id):!0},void 0,!1)}catch(e){throw new y(`Failed to reset cache${t?` (preserving: ${t.join(", ")})`:""}. ${e instanceof Error?e.message:String(e)}`,{operation:"delete",key:null,timestamp:Date.now()},e)}};function U(r,t){if(t)return r.get(t)}function w(r,t,e,i){return r(t,e,i)}async function J(r){try{return[await r,null]}catch(t){return[null,t]}}async function b(r,t,e,i){const n=U(r,e)?.data,a=i.optimisticUpdateFn(n,i.data);return await w(t,e,a,!1),n}function T(r,t,e,i){const n=t?.id||"unknown",a=i?.id?` with ID ${i.id}`:"",d=`Failed to ${r} resource "${n}"${a}. ${e instanceof Error?e.message:String(e)}`;return new y(d,{operation:r,key:t,...i,timestamp:Date.now()},e)}async function C(r,t,e){await w(r,t,e,!1)}function q(r,t,e={}){const{cache:i,mutate:n}=E.useSWRConfig(),{optimisticUpdate:a,rollbackOnError:d=!0}=e,[S,p]=o.useState(!1),[R,h]=o.useState(null),u=o.useRef(!0),c=M(r);return o.useEffect(()=>()=>{u.current=!1},[]),{trigger:o.useCallback(async f=>{if(!u.current)return;p(!0),h(null);let m;a&&(m=await b(i,n,c,{data:f,optimisticUpdateFn:a}));try{const l=await t(f);return u.current&&await w(n,c),l}catch(l){d&&a&&await C(n,c,m);const g=T("create",c,l,{data:f});throw u.current&&h(g),g}finally{u.current&&p(!1)}},[c,t,n,i,a,d]),isMutating:S,error:R}}function B(r,t,e={}){const{cache:i,mutate:n}=E.useSWRConfig(),{optimisticUpdate:a,rollbackOnError:d=!0}=e,[S,p]=o.useState(!1),[R,h]=o.useState(null),u=o.useRef(!0),c=M(r);return o.useEffect(()=>()=>{u.current=!1},[]),{trigger:o.useCallback(async f=>{if(!u.current)return;p(!0),h(null);let m;a&&(m=await b(i,n,c,{data:f,optimisticUpdateFn:a}));try{const l=await t(f);return u.current&&await w(n,c),l}catch(l){d&&a&&await C(n,c,m);const g=T("delete",c,l,{id:f});throw u.current&&h(g),g}finally{u.current&&p(!1)}},[c,t,n,i,a,d]),isMutating:S,error:R}}function L(r,t,e={}){const{cache:i,mutate:n}=E.useSWRConfig(),{optimisticUpdate:a,rollbackOnError:d=!0}=e,[S,p]=o.useState(!1),[R,h]=o.useState(null),u=o.useRef(!0),c=M(r);return o.useEffect(()=>()=>{u.current=!1},[]),{trigger:o.useCallback(async(f,m)=>{if(!u.current)return;p(!0),h(null);let l;a&&(l=await b(i,n,c,{data:{id:f,data:m},optimisticUpdateFn:a}));try{const g=await t(f,m);return u.current&&await w(n,c),g}catch(g){d&&a&&await C(n,c,l);const O=T("update",c,g,{data:m,id:f});throw u.current&&h(O),O}finally{u.current&&p(!1)}},[c,t,n,i,a,d]),isMutating:S,error:R}}s.MutationError=y,s.extractSWRKey=k,s.mutateByGroup=I,s.mutateById=P,s.resetCache=G,s.swrGetCache=U,s.swrMutate=w,s.to=J,s.useSWRCreate=q,s.useSWRDelete=B,s.useSWRUpdate=L,s.useStableKey=M,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})}));
+(function(o,d){typeof exports=="object"&&typeof module<"u"?d(exports,require("swr"),require("react")):typeof define=="function"&&define.amd?define(["exports","swr","react"],d):(o=typeof globalThis<"u"?globalThis:o||self,d(o["swr-catalyst"]={},o.SWR,o.React))})(this,(function(o,d,c){"use strict";class E extends Error{name="MutationError";context;originalError;constructor(t,e,i){super(t),this.context=e,this.originalError=i,"captureStackTrace"in Error&&Error.captureStackTrace(this,E)}getUserMessage(){const{operation:t,key:e}=this.context,i=e?.id||"resource";return`Failed to ${{create:"add",update:"update",delete:"delete"}[t]} ${i}. Please try again.`}toJSON(){return{name:this.name,message:this.message,context:this.context,originalError:this.originalError instanceof Error?{name:this.originalError.name,message:this.originalError.message,stack:this.originalError.stack}:String(this.originalError),stack:this.stack}}isNetworkError(){if(this.originalError instanceof Error){const t=this.originalError.message.toLowerCase();return this.originalError.name==="NetworkError"||t.includes("fetch")||t.includes("network")||t.includes("timeout")}return!1}isValidationError(){if(this.originalError instanceof Error){const t=this.originalError.message.toLowerCase();return t.includes("validation")||t.includes("invalid")||t.includes("required")}return!1}}const D=/#id:"((?:[^"\\]|\\.)*)"/,j=/group:"((?:[^"\\]|\\.)*)"/,v=/data:"((?:[^"\\]|\\.)*)"/;function $(r){return r.replace(/\\(.)/g,"$1")}function F(r){if(!r.startsWith("#id:"))return null;const t=r.match(D);if(!t)return null;const e=r.match(j),i=r.match(v);return{id:$(t[1]),group:e?$(e[1]):void 0,data:i?$(i[1]):void 0}}function N(r){try{const t=JSON.parse(r);if(t&&typeof t=="object"&&"id"in t)return t}catch{}return null}function M(r){if(typeof r=="object"&&r!==null&&"id"in r)return r;if(typeof r!="string")return null;const t=F(r);if(t)return t;const e=N(r);return e||null}async function A(r,t,e){const i=Array.isArray(r)?r:[r];try{await d.mutate(n=>{const a=M(n);return a?.group?i.includes(a.group):!1},t?()=>t:void 0,{revalidate:e?.revalidate??!t,...e})}catch(n){throw new E(`Failed to mutate cache by group(s): ${i.join(", ")}. ${n instanceof Error?n.message:String(n)}`,{operation:"update",key:null,data:t,timestamp:Date.now()},n)}}async function I(r,t,e){const i=typeof r=="string"?[r]:r;try{await d.mutate(n=>{const a=M(n);return a?i.includes(a?.id):!1},t?()=>t:void 0,{revalidate:e?.revalidate??!t,...e})}catch(n){throw new E(`Failed to mutate cache by ID(s): ${i.join(", ")}. ${n instanceof Error?n.message:String(n)}`,{operation:"update",key:null,data:t,timestamp:Date.now()},n)}}const P=async(r=[])=>{let t;Array.isArray(r)?t=r:r?t=[r]:t=null;try{await d.mutate(e=>{if(!t)return!0;const i=M(e);return i?!t.includes(i.id):!0},void 0,!1)}catch(e){throw new E(`Failed to reset cache${t?` (preserving: ${t.join(", ")})`:""}. ${e instanceof Error?e.message:String(e)}`,{operation:"delete",key:null,timestamp:Date.now()},e)}};function U(r,t){if(t)return r.get(t)}function w(r,t,e,i){return r(t,e,i)}async function G(r){try{return[await r,null]}catch(t){return[null,t]}}function J(r,t){if(r===t)return!0;if(r==null||t==null)return r===t;if(typeof r!="object"||typeof t!="object")return!1;try{return JSON.stringify(r)===JSON.stringify(t)}catch{return!1}}function k(r){const t=r?.id,e=r?.group,i=r?.data,n=c.useRef(null);if(!r||!(t&&i))return n.current=null,n.current;const a=n.current;return(!a||a.id!==t||a.group!==e||!J(a.data,i))&&(n.current={id:t,group:e,data:i}),n.current}async function b(r,t,e,i){const n=U(r,e)?.data,a=i.optimisticUpdateFn(n,i.data);return await w(t,e,a,!1),n}function T(r,t,e,i){const n=t?.id||"unknown",a=i?.id?` with ID ${i.id}`:"",g=`Failed to ${r} resource "${n}"${a}. ${e instanceof Error?e.message:String(e)}`;return new E(g,{operation:r,key:t,...i,timestamp:Date.now()},e)}async function C(r,t,e){await w(r,t,e,!1)}function q(r,t,e={}){const{cache:i,mutate:n}=d.useSWRConfig(),{optimisticUpdate:a,rollbackOnError:g=!0}=e,[S,h]=c.useState(!1),[R,y]=c.useState(null),s=c.useRef(!0),u=k(r);return c.useEffect(()=>()=>{s.current=!1},[]),{trigger:c.useCallback(async f=>{if(!s.current)return;h(!0),y(null);let p;a&&(p=await b(i,n,u,{data:f,optimisticUpdateFn:a}));try{const l=await t(f);return s.current&&await w(n,u),l}catch(l){g&&a&&await C(n,u,p);const m=T("create",u,l,{data:f});throw s.current&&y(m),m}finally{s.current&&h(!1)}},[u,t,n,i,a,g]),isMutating:S,error:R}}function B(r,t,e={}){const{cache:i,mutate:n}=d.useSWRConfig(),{optimisticUpdate:a,rollbackOnError:g=!0}=e,[S,h]=c.useState(!1),[R,y]=c.useState(null),s=c.useRef(!0),u=k(r);return c.useEffect(()=>()=>{s.current=!1},[]),{trigger:c.useCallback(async f=>{if(!s.current)return;h(!0),y(null);let p;a&&(p=await b(i,n,u,{data:f,optimisticUpdateFn:a}));try{const l=await t(f);return s.current&&await w(n,u),l}catch(l){g&&a&&await C(n,u,p);const m=T("delete",u,l,{id:f});throw s.current&&y(m),m}finally{s.current&&h(!1)}},[u,t,n,i,a,g]),isMutating:S,error:R}}function L(r,t,e={}){const{cache:i,mutate:n}=d.useSWRConfig(),{optimisticUpdate:a,rollbackOnError:g=!0}=e,[S,h]=c.useState(!1),[R,y]=c.useState(null),s=c.useRef(!0),u=k(r);return c.useEffect(()=>()=>{s.current=!1},[]),{trigger:c.useCallback(async(f,p)=>{if(!s.current)return;h(!0),y(null);let l;a&&(l=await b(i,n,u,{data:{id:f,data:p},optimisticUpdateFn:a}));try{const m=await t(f,p);return s.current&&await w(n,u),m}catch(m){g&&a&&await C(n,u,l);const O=T("update",u,m,{data:p,id:f});throw s.current&&y(O),O}finally{s.current&&h(!1)}},[u,t,n,i,a,g]),isMutating:S,error:R}}o.MutationError=E,o.extractSWRKey=M,o.mutateByGroup=A,o.mutateById=I,o.resetCache=P,o.swrGetCache=U,o.swrMutate=w,o.to=G,o.useSWRCreate=q,o.useSWRDelete=B,o.useSWRUpdate=L,o.useStableKey=k,Object.defineProperty(o,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swr-catalyst",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "A lightweight, declarative library to simplify data mutations with SWR.",
   "author": "Pedro Barbosa (https://github.com/pedroab0)",
   "license": "MIT",
@@ -33,6 +33,8 @@
   "scripts": {
     "build": "vite build",
     "test": "vitest",
+    "test:unit": "vitest run --exclude 'src/__tests__/**'",
+    "test:integration": "vitest run src/__tests__/integration",
     "test:coverage": "vitest run --coverage",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
@@ -48,19 +50,20 @@
     "swr": "^2.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.4",
+    "@biomejs/biome": "^2.3.7",
     "@size-limit/preset-small-lib": "^11.2.0",
     "@testing-library/react": "^16.3.0",
-    "@types/node": "^24.10.0",
-    "@vitest/coverage-v8": "^4.0.7",
-    "jsdom": "^27.1.0",
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.13",
+    "jsdom": "^27.2.0",
+    "msw": "^2.12.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "size-limit": "^11.2.0",
     "swr": "^2.3.6",
     "typescript": "^5.9.3",
-    "ultracite": "^6.3.2",
-    "vite": "^7.2.1",
+    "ultracite": "^6.3.6",
+    "vite": "^7.2.4",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.0.7"
   }