@spoosh/plugin-optimistic 0.4.3 → 0.5.0

package/README.md

@@ -22,7 +22,7 @@ import { Spoosh } from "@spoosh/core";
 import { optimisticPlugin } from "@spoosh/plugin-optimistic";
 import { invalidationPlugin } from "@spoosh/plugin-invalidation";
 
-const client = new Spoosh<ApiSchema, Error>("/api").use([
+const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
   invalidationPlugin(),
   optimisticPlugin(),
 ]);

package/dist/index.d.mts

@@ -215,61 +215,6 @@ declare module "@spoosh/core" {
     }
 }
 
-/**
- * Enables optimistic updates for mutations.
- *
- * Immediately updates cached data before the mutation completes,
- * with automatic rollback on error.
- *
- * When using optimistic updates, invalidation mode defaults to `"none"` to prevent
- * unnecessary refetches that would override the optimistic data. You can override
- * this by explicitly setting the `invalidate` option with a mode string or array.
- *
- * @see {@link https://spoosh.dev/docs/react/plugins/optimistic | Optimistic Plugin Documentation}
- *
- * @returns Optimistic plugin instance
- *
- * @example
- * ```ts
- * import { Spoosh } from "@spoosh/core";
- *
- * const client = new Spoosh<ApiSchema, Error>("/api")
- *   .use([
- *     // ... other plugins
- *     optimisticPlugin(),
- *   ]);
- *
- * // Methods can be chained in any order
- * trigger({
- *   optimistic: (api) => api("posts")
- *     .GET()
- *     .UPDATE_CACHE(posts => posts.filter(p => p.id !== deletedId)),
- * });
- * ```
- *
- * @example
- * ```ts
- * // With WHERE filter and disable rollback
- * trigger({
- *   optimistic: (api) => api("posts")
- *     .GET()
- *     .NO_ROLLBACK()
- *     .WHERE(entry => entry.query.page === 1)
- *     .UPDATE_CACHE(posts => [newPost, ...posts]),
- * });
- * ```
- *
- * @example
- * ```ts
- * // Apply after success with typed response
- * trigger({
- *   optimistic: (api) => api("posts")
- *     .GET()
- *     .ON_SUCCESS()
- *     .UPDATE_CACHE((posts, newPost) => [...posts, newPost]),
- * });
- * ```
- */
 declare function optimisticPlugin(): SpooshPlugin<{
     readOptions: OptimisticReadOptions;
     writeOptions: OptimisticWriteOptions;

package/dist/index.d.ts

@@ -215,61 +215,6 @@ declare module "@spoosh/core" {
     }
 }
 
-/**
- * Enables optimistic updates for mutations.
- *
- * Immediately updates cached data before the mutation completes,
- * with automatic rollback on error.
- *
- * When using optimistic updates, invalidation mode defaults to `"none"` to prevent
- * unnecessary refetches that would override the optimistic data. You can override
- * this by explicitly setting the `invalidate` option with a mode string or array.
- *
- * @see {@link https://spoosh.dev/docs/react/plugins/optimistic | Optimistic Plugin Documentation}
- *
- * @returns Optimistic plugin instance
- *
- * @example
- * ```ts
- * import { Spoosh } from "@spoosh/core";
- *
- * const client = new Spoosh<ApiSchema, Error>("/api")
- *   .use([
- *     // ... other plugins
- *     optimisticPlugin(),
- *   ]);
- *
- * // Methods can be chained in any order
- * trigger({
- *   optimistic: (api) => api("posts")
- *     .GET()
- *     .UPDATE_CACHE(posts => posts.filter(p => p.id !== deletedId)),
- * });
- * ```
- *
- * @example
- * ```ts
- * // With WHERE filter and disable rollback
- * trigger({
- *   optimistic: (api) => api("posts")
- *     .GET()
- *     .NO_ROLLBACK()
- *     .WHERE(entry => entry.query.page === 1)
- *     .UPDATE_CACHE(posts => [newPost, ...posts]),
- * });
- * ```
- *
- * @example
- * ```ts
- * // Apply after success with typed response
- * trigger({
- *   optimistic: (api) => api("posts")
- *     .GET()
- *     .ON_SUCCESS()
- *     .UPDATE_CACHE((posts, newPost) => [...posts, newPost]),
- * });
- * ```
- */
 declare function optimisticPlugin(): SpooshPlugin<{
     readOptions: OptimisticReadOptions;
     writeOptions: OptimisticWriteOptions;

package/dist/index.js

@@ -90,7 +90,7 @@ function resolveOptimisticTargets(context) {
   const targets = Array.isArray(result) ? result : [result];
   return targets;
 }
-function applyOptimisticUpdate(stateManager, target) {
+function applyOptimisticUpdate(stateManager, target, t) {
   if (!target.updater) return [];
   const tags = extractTagsFromPath(target.path);
   const targetSelfTag = getExactMatchPath(tags);
@@ -113,19 +113,24 @@ function applyOptimisticUpdate(stateManager, target) {
     if (entry.state.data === void 0) {
       continue;
     }
-    snapshots.push({ key, previousData: entry.state.data });
+    const afterData = target.updater(entry.state.data, void 0);
+    snapshots.push({ key, previousData: entry.state.data, afterData });
     stateManager.setCache(key, {
       previousData: entry.state.data,
       state: {
         ...entry.state,
-        data: target.updater(entry.state.data, void 0)
+        data: afterData
       }
     });
     stateManager.setMeta(key, { isOptimistic: true });
+    t?.log("Marked as optimistic", {
+      color: "info",
+      info: [{ value: { isOptimistic: true } }]
+    });
   }
   return snapshots;
 }
-function confirmOptimistic(stateManager, snapshots) {
+function confirmOptimistic(stateManager, snapshots, t) {
   for (const { key } of snapshots) {
     const entry = stateManager.getCache(key);
     if (entry) {
@@ -133,10 +138,14 @@ function confirmOptimistic(stateManager, snapshots) {
         previousData: void 0
       });
       stateManager.setMeta(key, { isOptimistic: false });
+      t?.log("Optimistic confirmed", {
+        color: "success",
+        info: [{ value: { isOptimistic: false } }]
+      });
     }
   }
 }
-function rollbackOptimistic(stateManager, snapshots) {
+function rollbackOptimistic(stateManager, snapshots, t) {
   for (const { key, previousData } of snapshots) {
     const entry = stateManager.getCache(key);
     if (entry) {
@@ -148,33 +157,66 @@ function rollbackOptimistic(stateManager, snapshots) {
         }
       });
       stateManager.setMeta(key, { isOptimistic: false });
+      t?.log("Optimistic rolled back", {
+        color: "warning",
+        info: [{ value: { isOptimistic: false } }]
+      });
     }
   }
 }
+function buildSnapshotDiff(snapshots, mode = "apply") {
+  const first = snapshots[0];
+  const label = mode === "apply" ? "Optimistic update to cache" : mode === "rollback" ? "Rollback optimistic changes" : "Apply onSuccess updates";
+  if (snapshots.length === 1) {
+    return mode === "apply" || mode === "onSuccess" ? { before: first.previousData, after: first.afterData, label } : { before: first.afterData, after: first.previousData, label };
+  }
+  return mode === "apply" || mode === "onSuccess" ? {
+    before: snapshots.map((s) => ({ key: s.key, data: s.previousData })),
+    after: snapshots.map((s) => ({ key: s.key, data: s.afterData })),
+    label
+  } : {
+    before: snapshots.map((s) => ({ key: s.key, data: s.afterData })),
+    after: snapshots.map((s) => ({ key: s.key, data: s.previousData })),
+    label
+  };
+}
+var PLUGIN_NAME = "spoosh:optimistic";
 function optimisticPlugin() {
   return {
-    name: "spoosh:optimistic",
+    name: PLUGIN_NAME,
     operations: ["write"],
     dependencies: ["spoosh:invalidation"],
     middleware: async (context, next) => {
+      const t = context.tracer?.(PLUGIN_NAME);
       const { stateManager } = context;
       const targets = resolveOptimisticTargets(context);
-      if (targets.length > 0) {
-        context.plugins.get("spoosh:invalidation")?.setDefaultMode("none");
+      if (targets.length === 0) {
+        t?.skip("No optimistic targets");
+        return next();
       }
-      const immediateTargets = targets.filter((t) => t.timing !== "onSuccess");
+      context.plugins.get("spoosh:invalidation")?.setDefaultMode("none");
+      const immediateTargets = targets.filter((t2) => t2.timing !== "onSuccess");
       const allSnapshots = [];
       for (const target of immediateTargets) {
-        const snapshots = applyOptimisticUpdate(stateManager, target);
+        const snapshots = applyOptimisticUpdate(stateManager, target, t);
         allSnapshots.push(...snapshots);
       }
+      if (allSnapshots.length > 0) {
+        t?.log(`Applied ${allSnapshots.length} immediate update(s)`, {
+          diff: buildSnapshotDiff(allSnapshots)
+        });
+      }
       const response = await next();
       if (response.error) {
         const shouldRollback = targets.some(
-          (t) => t.rollbackOnError && t.timing !== "onSuccess"
+          (t2) => t2.rollbackOnError && t2.timing !== "onSuccess"
         );
         if (shouldRollback && allSnapshots.length > 0) {
-          rollbackOptimistic(stateManager, allSnapshots);
+          rollbackOptimistic(stateManager, allSnapshots, t);
+          t?.log(`Rolled back ${allSnapshots.length} update(s)`, {
+            color: "warning",
+            diff: buildSnapshotDiff(allSnapshots, "rollback")
+          });
         }
         for (const target of targets) {
           if (target.onError) {
@@ -183,11 +225,12 @@ function optimisticPlugin() {
         }
       } else {
         if (allSnapshots.length > 0) {
-          confirmOptimistic(stateManager, allSnapshots);
+          confirmOptimistic(stateManager, allSnapshots, t);
         }
         const onSuccessTargets = targets.filter(
-          (t) => t.timing === "onSuccess"
+          (target) => target.timing === "onSuccess"
         );
+        const onSuccessSnapshots = [];
         for (const target of onSuccessTargets) {
           if (!target.updater) continue;
           const tags = extractTagsFromPath(target.path);
@@ -210,14 +253,26 @@ function optimisticPlugin() {
             if (entry.state.data === void 0) {
               continue;
             }
+            const afterData = target.updater(entry.state.data, response.data);
+            onSuccessSnapshots.push({
+              key,
+              previousData: entry.state.data,
+              afterData
+            });
             stateManager.setCache(key, {
               state: {
                 ...entry.state,
-                data: target.updater(entry.state.data, response.data)
+                data: afterData
               }
             });
           }
         }
+        if (onSuccessSnapshots.length > 0) {
+          t?.log(`Applied ${onSuccessSnapshots.length} onSuccess update(s)`, {
+            color: "success",
+            diff: buildSnapshotDiff(onSuccessSnapshots, "onSuccess")
+          });
+        }
       }
       return response;
     }

package/dist/index.mjs

@@ -64,7 +64,7 @@ function resolveOptimisticTargets(context) {
   const targets = Array.isArray(result) ? result : [result];
   return targets;
 }
-function applyOptimisticUpdate(stateManager, target) {
+function applyOptimisticUpdate(stateManager, target, t) {
   if (!target.updater) return [];
   const tags = extractTagsFromPath(target.path);
   const targetSelfTag = getExactMatchPath(tags);
@@ -87,19 +87,24 @@ function applyOptimisticUpdate(stateManager, target) {
     if (entry.state.data === void 0) {
       continue;
     }
-    snapshots.push({ key, previousData: entry.state.data });
+    const afterData = target.updater(entry.state.data, void 0);
+    snapshots.push({ key, previousData: entry.state.data, afterData });
     stateManager.setCache(key, {
       previousData: entry.state.data,
       state: {
         ...entry.state,
-        data: target.updater(entry.state.data, void 0)
+        data: afterData
       }
     });
     stateManager.setMeta(key, { isOptimistic: true });
+    t?.log("Marked as optimistic", {
+      color: "info",
+      info: [{ value: { isOptimistic: true } }]
+    });
   }
   return snapshots;
 }
-function confirmOptimistic(stateManager, snapshots) {
+function confirmOptimistic(stateManager, snapshots, t) {
   for (const { key } of snapshots) {
     const entry = stateManager.getCache(key);
     if (entry) {
@@ -107,10 +112,14 @@ function confirmOptimistic(stateManager, snapshots) {
         previousData: void 0
       });
       stateManager.setMeta(key, { isOptimistic: false });
+      t?.log("Optimistic confirmed", {
+        color: "success",
+        info: [{ value: { isOptimistic: false } }]
+      });
     }
   }
 }
-function rollbackOptimistic(stateManager, snapshots) {
+function rollbackOptimistic(stateManager, snapshots, t) {
   for (const { key, previousData } of snapshots) {
     const entry = stateManager.getCache(key);
     if (entry) {
@@ -122,33 +131,66 @@ function rollbackOptimistic(stateManager, snapshots) {
         }
       });
       stateManager.setMeta(key, { isOptimistic: false });
+      t?.log("Optimistic rolled back", {
+        color: "warning",
+        info: [{ value: { isOptimistic: false } }]
+      });
     }
   }
 }
+function buildSnapshotDiff(snapshots, mode = "apply") {
+  const first = snapshots[0];
+  const label = mode === "apply" ? "Optimistic update to cache" : mode === "rollback" ? "Rollback optimistic changes" : "Apply onSuccess updates";
+  if (snapshots.length === 1) {
+    return mode === "apply" || mode === "onSuccess" ? { before: first.previousData, after: first.afterData, label } : { before: first.afterData, after: first.previousData, label };
+  }
+  return mode === "apply" || mode === "onSuccess" ? {
+    before: snapshots.map((s) => ({ key: s.key, data: s.previousData })),
+    after: snapshots.map((s) => ({ key: s.key, data: s.afterData })),
+    label
+  } : {
+    before: snapshots.map((s) => ({ key: s.key, data: s.afterData })),
+    after: snapshots.map((s) => ({ key: s.key, data: s.previousData })),
+    label
+  };
+}
+var PLUGIN_NAME = "spoosh:optimistic";
 function optimisticPlugin() {
   return {
-    name: "spoosh:optimistic",
+    name: PLUGIN_NAME,
     operations: ["write"],
     dependencies: ["spoosh:invalidation"],
     middleware: async (context, next) => {
+      const t = context.tracer?.(PLUGIN_NAME);
       const { stateManager } = context;
       const targets = resolveOptimisticTargets(context);
-      if (targets.length > 0) {
-        context.plugins.get("spoosh:invalidation")?.setDefaultMode("none");
+      if (targets.length === 0) {
+        t?.skip("No optimistic targets");
+        return next();
       }
-      const immediateTargets = targets.filter((t) => t.timing !== "onSuccess");
+      context.plugins.get("spoosh:invalidation")?.setDefaultMode("none");
+      const immediateTargets = targets.filter((t2) => t2.timing !== "onSuccess");
       const allSnapshots = [];
       for (const target of immediateTargets) {
-        const snapshots = applyOptimisticUpdate(stateManager, target);
+        const snapshots = applyOptimisticUpdate(stateManager, target, t);
         allSnapshots.push(...snapshots);
       }
+      if (allSnapshots.length > 0) {
+        t?.log(`Applied ${allSnapshots.length} immediate update(s)`, {
+          diff: buildSnapshotDiff(allSnapshots)
+        });
+      }
       const response = await next();
       if (response.error) {
         const shouldRollback = targets.some(
-          (t) => t.rollbackOnError && t.timing !== "onSuccess"
+          (t2) => t2.rollbackOnError && t2.timing !== "onSuccess"
         );
         if (shouldRollback && allSnapshots.length > 0) {
-          rollbackOptimistic(stateManager, allSnapshots);
+          rollbackOptimistic(stateManager, allSnapshots, t);
+          t?.log(`Rolled back ${allSnapshots.length} update(s)`, {
+            color: "warning",
+            diff: buildSnapshotDiff(allSnapshots, "rollback")
+          });
         }
         for (const target of targets) {
           if (target.onError) {
@@ -157,11 +199,12 @@ function optimisticPlugin() {
         }
       } else {
         if (allSnapshots.length > 0) {
-          confirmOptimistic(stateManager, allSnapshots);
+          confirmOptimistic(stateManager, allSnapshots, t);
         }
         const onSuccessTargets = targets.filter(
-          (t) => t.timing === "onSuccess"
+          (target) => target.timing === "onSuccess"
         );
+        const onSuccessSnapshots = [];
         for (const target of onSuccessTargets) {
           if (!target.updater) continue;
           const tags = extractTagsFromPath(target.path);
@@ -184,14 +227,26 @@ function optimisticPlugin() {
             if (entry.state.data === void 0) {
               continue;
             }
+            const afterData = target.updater(entry.state.data, response.data);
+            onSuccessSnapshots.push({
+              key,
+              previousData: entry.state.data,
+              afterData
+            });
             stateManager.setCache(key, {
               state: {
                 ...entry.state,
-                data: target.updater(entry.state.data, response.data)
+                data: afterData
               }
             });
           }
         }
+        if (onSuccessSnapshots.length > 0) {
+          t?.log(`Applied ${onSuccessSnapshots.length} onSuccess update(s)`, {
+            color: "success",
+            diff: buildSnapshotDiff(onSuccessSnapshots, "onSuccess")
+          });
+        }
       }
       return response;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/plugin-optimistic",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Optimistic updates plugin for Spoosh - instant UI updates with automatic rollback",
   "license": "MIT",
   "repository": {
@@ -33,13 +33,13 @@
     }
   },
   "peerDependencies": {
-    "@spoosh/core": ">=0.11.1",
+    "@spoosh/core": ">=0.13.0",
     "@spoosh/plugin-invalidation": ">=0.4.0"
   },
   "devDependencies": {
-    "@spoosh/core": "0.11.1",
-    "@spoosh/test-utils": "0.1.6",
-    "@spoosh/plugin-invalidation": "0.5.6"
+    "@spoosh/core": "0.13.0",
+    "@spoosh/test-utils": "0.2.0",
+    "@spoosh/plugin-invalidation": "0.6.0"
   },
   "scripts": {
     "dev": "tsup --watch",