@spoosh/plugin-optimistic 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spoosh
+
+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,103 @@
+# @spoosh/plugin-optimistic
+
+Optimistic updates plugin for Spoosh - instant UI updates with automatic rollback on error.
+
+**[Documentation](https://spoosh.dev/docs/plugins/optimistic)** · **Requirements:** TypeScript >= 5.0 · **Peer Dependencies:** `@spoosh/core`, `@spoosh/plugin-invalidation`
+
+## Installation
+
+```bash
+npm install @spoosh/plugin-optimistic @spoosh/plugin-invalidation
+```
+
+Note: This plugin requires `@spoosh/plugin-invalidation` as a peer dependency.
+
+> By default, if optimistic updates are used, `autoInvalidate` from `@spoosh/plugin-invalidation` is set to `"none"` to prevent immediate cache invalidation for this request.
+> If you want to keep auto-invalidation, set `autoInvalidate` to `"all"` or `"self"` or target with `invalidate` manually.
+
+## Usage
+
+```typescript
+import { optimisticPlugin } from "@spoosh/plugin-optimistic";
+import { invalidationPlugin } from "@spoosh/plugin-invalidation";
+
+const plugins = [invalidationPlugin(), optimisticPlugin()];
+
+const { trigger } = useWrite((api) => api.posts[id].$delete);
+
+trigger({
+  // Optimistic delete - instantly remove item from list
+  optimistic: ($, api) =>
+    $({
+      for: api.posts.$get,
+      updater: (posts) => posts.filter((p) => p.id !== id),
+      rollbackOnError: true,
+    }),
+});
+
+// Optimistic update with response data
+trigger({
+  optimistic: ($, api) =>
+    $({
+      for: api.posts.$get,
+      timing: "onSuccess",
+      updater: (posts, newPost) => [newPost!, ...posts],
+    }),
+});
+
+// Multiple targets
+trigger({
+  optimistic: ($, api) => [
+    $({
+      for: api.posts.$get,
+      updater: (posts) => posts.filter((p) => p.id !== id),
+    }),
+    $({
+      for: api.stats.$get,
+      updater: (stats) => ({ ...stats, count: stats.count - 1 }),
+    }),
+  ],
+});
+
+// Filter by request params
+trigger({
+  optimistic: ($, api) =>
+    $({
+      for: api.posts.$get,
+      match: (request) => request.query?.page === 1,
+      updater: (posts, newPost) => [newPost!, ...posts],
+    }),
+});
+```
+
+## Options
+
+### Per-Request Options
+
+| Option       | Type                             | Description                           |
+| ------------ | -------------------------------- | ------------------------------------- |
+| `optimistic` | `($, api) => config \| config[]` | Callback to define optimistic updates |
+
+### Config Object
+
+| Property          | Type                         | Default       | Description                          |
+| ----------------- | ---------------------------- | ------------- | ------------------------------------ |
+| `for`             | `api.endpoint.$get`          | required      | The endpoint to update               |
+| `updater`         | `(data, response?) => data`  | required      | Function to update cached data       |
+| `match`           | `(request) => boolean`       | -             | Filter which cache entries to update |
+| `timing`          | `"immediate" \| "onSuccess"` | `"immediate"` | When to apply the update (see below) |
+| `rollbackOnError` | `boolean`                    | `true`        | Whether to rollback on error         |
+| `onError`         | `(error) => void`            | -             | Error callback                       |
+
+### Result
+
+| Property       | Type      | Description                                         |
+| -------------- | --------- | --------------------------------------------------- |
+| `isOptimistic` | `boolean` | `true` if current data is from an optimistic update |
+
+### Timing Modes
+
+| Mode          | Description                                                                 |
+| ------------- | --------------------------------------------------------------------------- |
+| `"immediate"` | Update cache instantly before request completes. Rollback on error.         |
+| `"onSuccess"` | Wait for successful response, then update cache with response data applied. |

package/dist/index.d.mts

@@ -0,0 +1,113 @@
+import { SpooshResponse, QuerySchemaHelper, SpooshPlugin } from '@spoosh/core';
+
+type ExtractResponseData<T> = T extends SpooshResponse<infer D, unknown, unknown> ? D : unknown;
+type ExtractRequestOptions<T> = T extends SpooshResponse<unknown, unknown, infer R> ? R : never;
+type CleanRequestOptions<T> = unknown extends T ? never : keyof T extends never ? never : T;
+type CacheConfig<TFor extends () => Promise<SpooshResponse<unknown, unknown, unknown>>, TResponse = unknown, TData = ExtractResponseData<Awaited<ReturnType<TFor>>>, TRequest = CleanRequestOptions<ExtractRequestOptions<Awaited<ReturnType<TFor>>>>> = {
+    for: TFor;
+    match?: [TRequest] extends [never] ? never : (request: TRequest) => boolean;
+    timing?: "immediate" | "onSuccess";
+    updater: (data: TData, response?: TResponse) => TData;
+    rollbackOnError?: boolean;
+    onError?: (error: unknown) => void;
+};
+type ResolvedCacheConfig = {
+    for: (...args: any[]) => Promise<SpooshResponse<unknown, unknown>>;
+    match?: (request: Record<string, unknown>) => boolean;
+    timing?: "immediate" | "onSuccess";
+    updater: (data: unknown, response?: unknown) => unknown;
+    rollbackOnError?: boolean;
+    onError?: (error: unknown) => void;
+};
+type OptimisticCallbackFn<TSchema = unknown, TResponse = unknown> = ($: <TFor extends () => Promise<SpooshResponse<unknown, unknown, unknown>>>(config: CacheConfig<TFor, TResponse>) => ResolvedCacheConfig, api: QuerySchemaHelper<TSchema>) => ResolvedCacheConfig | ResolvedCacheConfig[];
+type OptimisticPluginConfig = object;
+interface OptimisticWriteOptions<TSchema = unknown> {
+    optimistic?: OptimisticCallbackFn<TSchema>;
+}
+type OptimisticReadOptions = object;
+type OptimisticInfiniteReadOptions = object;
+interface OptimisticReadResult {
+    isOptimistic: boolean;
+}
+type OptimisticWriteResult = object;
+declare module "@spoosh/core" {
+    interface PluginResolvers<TContext> {
+        optimistic: OptimisticCallbackFn<TContext["schema"]> | undefined;
+    }
+}
+
+declare const OPTIMISTIC_SNAPSHOTS_KEY = "optimistic:snapshots";
+/**
+ * Enables optimistic updates for mutations.
+ *
+ * Immediately updates cached data before the mutation completes,
+ * with automatic rollback on error.
+ *
+ * When using optimistic updates, `autoInvalidate` defaults to `"none"` to prevent
+ * unnecessary refetches that would override the optimistic data. You can override
+ * this by explicitly setting `autoInvalidate` or using the `invalidate` option.
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/optimistic | Optimistic Plugin Documentation}
+ *
+ * @returns Optimistic plugin instance
+ *
+ * @example
+ * ```ts
+ * const plugins = [optimisticPlugin()];
+ *
+ * // In useWrite - autoInvalidate defaults to "none" when optimistic is used
+ * trigger({
+ *   optimistic: ($, api) => $({
+ *     for: api.posts.$get,
+ *     updater: (posts) => posts.filter(p => p.id !== deletedId),
+ *     rollbackOnError: true,
+ *   }),
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Multiple targets
+ * trigger({
+ *   optimistic: ($, api) => [
+ *     $({ for: api.posts.$get, updater: (posts) => posts.filter(p => p.id !== deletedId) }),
+ *     $({ for: api.stats.$get, updater: (stats) => ({ ...stats, count: stats.count - 1 }) }),
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optimistic update with explicit invalidation
+ * trigger({
+ *   optimistic: ($, api) => $({
+ *     for: api.posts.$get,
+ *     updater: (posts) => posts.filter(p => p.id !== deletedId),
+ *   }),
+ *   // By default autoInvalidate is "none" when using optimistic updates
+ *   autoInvalidate: "all", // You can override to enable refetching after mutation
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Filtering by request
+ * trigger({
+ *   optimistic: ($, api) => $({
+ *     for: api.items.$get,
+ *     timing: "onSuccess",
+ *     match: (request) => request.query?.page === 1,
+ *     updater: (items, newItem) => [newItem!, ...items],
+ *   }),
+ * });
+ * ```
+ */
+declare function optimisticPlugin(): SpooshPlugin<{
+    readOptions: OptimisticReadOptions;
+    writeOptions: OptimisticWriteOptions;
+    infiniteReadOptions: OptimisticInfiniteReadOptions;
+    readResult: OptimisticReadResult;
+    writeResult: OptimisticWriteResult;
+}>;
+
+export { type CacheConfig, OPTIMISTIC_SNAPSHOTS_KEY, type OptimisticCallbackFn, type OptimisticInfiniteReadOptions, type OptimisticPluginConfig, type OptimisticReadOptions, type OptimisticReadResult, type OptimisticWriteOptions, type OptimisticWriteResult, type ResolvedCacheConfig, optimisticPlugin };

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import { SpooshResponse, QuerySchemaHelper, SpooshPlugin } from '@spoosh/core';
+
+type ExtractResponseData<T> = T extends SpooshResponse<infer D, unknown, unknown> ? D : unknown;
+type ExtractRequestOptions<T> = T extends SpooshResponse<unknown, unknown, infer R> ? R : never;
+type CleanRequestOptions<T> = unknown extends T ? never : keyof T extends never ? never : T;
+type CacheConfig<TFor extends () => Promise<SpooshResponse<unknown, unknown, unknown>>, TResponse = unknown, TData = ExtractResponseData<Awaited<ReturnType<TFor>>>, TRequest = CleanRequestOptions<ExtractRequestOptions<Awaited<ReturnType<TFor>>>>> = {
+    for: TFor;
+    match?: [TRequest] extends [never] ? never : (request: TRequest) => boolean;
+    timing?: "immediate" | "onSuccess";
+    updater: (data: TData, response?: TResponse) => TData;
+    rollbackOnError?: boolean;
+    onError?: (error: unknown) => void;
+};
+type ResolvedCacheConfig = {
+    for: (...args: any[]) => Promise<SpooshResponse<unknown, unknown>>;
+    match?: (request: Record<string, unknown>) => boolean;
+    timing?: "immediate" | "onSuccess";
+    updater: (data: unknown, response?: unknown) => unknown;
+    rollbackOnError?: boolean;
+    onError?: (error: unknown) => void;
+};
+type OptimisticCallbackFn<TSchema = unknown, TResponse = unknown> = ($: <TFor extends () => Promise<SpooshResponse<unknown, unknown, unknown>>>(config: CacheConfig<TFor, TResponse>) => ResolvedCacheConfig, api: QuerySchemaHelper<TSchema>) => ResolvedCacheConfig | ResolvedCacheConfig[];
+type OptimisticPluginConfig = object;
+interface OptimisticWriteOptions<TSchema = unknown> {
+    optimistic?: OptimisticCallbackFn<TSchema>;
+}
+type OptimisticReadOptions = object;
+type OptimisticInfiniteReadOptions = object;
+interface OptimisticReadResult {
+    isOptimistic: boolean;
+}
+type OptimisticWriteResult = object;
+declare module "@spoosh/core" {
+    interface PluginResolvers<TContext> {
+        optimistic: OptimisticCallbackFn<TContext["schema"]> | undefined;
+    }
+}
+
+declare const OPTIMISTIC_SNAPSHOTS_KEY = "optimistic:snapshots";
+/**
+ * Enables optimistic updates for mutations.
+ *
+ * Immediately updates cached data before the mutation completes,
+ * with automatic rollback on error.
+ *
+ * When using optimistic updates, `autoInvalidate` defaults to `"none"` to prevent
+ * unnecessary refetches that would override the optimistic data. You can override
+ * this by explicitly setting `autoInvalidate` or using the `invalidate` option.
+ *
+ * @see {@link https://spoosh.dev/docs/plugins/optimistic | Optimistic Plugin Documentation}
+ *
+ * @returns Optimistic plugin instance
+ *
+ * @example
+ * ```ts
+ * const plugins = [optimisticPlugin()];
+ *
+ * // In useWrite - autoInvalidate defaults to "none" when optimistic is used
+ * trigger({
+ *   optimistic: ($, api) => $({
+ *     for: api.posts.$get,
+ *     updater: (posts) => posts.filter(p => p.id !== deletedId),
+ *     rollbackOnError: true,
+ *   }),
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Multiple targets
+ * trigger({
+ *   optimistic: ($, api) => [
+ *     $({ for: api.posts.$get, updater: (posts) => posts.filter(p => p.id !== deletedId) }),
+ *     $({ for: api.stats.$get, updater: (stats) => ({ ...stats, count: stats.count - 1 }) }),
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Optimistic update with explicit invalidation
+ * trigger({
+ *   optimistic: ($, api) => $({
+ *     for: api.posts.$get,
+ *     updater: (posts) => posts.filter(p => p.id !== deletedId),
+ *   }),
+ *   // By default autoInvalidate is "none" when using optimistic updates
+ *   autoInvalidate: "all", // You can override to enable refetching after mutation
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Filtering by request
+ * trigger({
+ *   optimistic: ($, api) => $({
+ *     for: api.items.$get,
+ *     timing: "onSuccess",
+ *     match: (request) => request.query?.page === 1,
+ *     updater: (items, newItem) => [newItem!, ...items],
+ *   }),
+ * });
+ * ```
+ */
+declare function optimisticPlugin(): SpooshPlugin<{
+    readOptions: OptimisticReadOptions;
+    writeOptions: OptimisticWriteOptions;
+    infiniteReadOptions: OptimisticInfiniteReadOptions;
+    readResult: OptimisticReadResult;
+    writeResult: OptimisticWriteResult;
+}>;
+
+export { type CacheConfig, OPTIMISTIC_SNAPSHOTS_KEY, type OptimisticCallbackFn, type OptimisticInfiniteReadOptions, type OptimisticPluginConfig, type OptimisticReadOptions, type OptimisticReadResult, type OptimisticWriteOptions, type OptimisticWriteResult, type ResolvedCacheConfig, optimisticPlugin };

package/dist/index.js

@@ -0,0 +1,200 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  OPTIMISTIC_SNAPSHOTS_KEY: () => OPTIMISTIC_SNAPSHOTS_KEY,
+  optimisticPlugin: () => optimisticPlugin
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/plugin.ts
+var import_core = require("@spoosh/core");
+var import_plugin_invalidation = require("@spoosh/plugin-invalidation");
+var OPTIMISTIC_SNAPSHOTS_KEY = "optimistic:snapshots";
+function extractTagsFromFor(forFn) {
+  return (0, import_core.generateTags)((0, import_core.extractPathFromSelector)(forFn));
+}
+function getExactMatchPath(tags) {
+  return tags.length > 0 ? tags[tags.length - 1] : void 0;
+}
+function findInObject(obj, key) {
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    return void 0;
+  }
+  const record = obj;
+  if (key in record) {
+    return record[key];
+  }
+  for (const value of Object.values(record)) {
+    const found = findInObject(value, key);
+    if (found !== void 0) return found;
+  }
+  return void 0;
+}
+function parseRequestFromKey(key) {
+  try {
+    const parsed = JSON.parse(key);
+    return {
+      query: findInObject(parsed, "query"),
+      params: findInObject(parsed, "params"),
+      body: findInObject(parsed, "body")
+    };
+  } catch {
+    return void 0;
+  }
+}
+function resolveOptimisticConfigs(context) {
+  const pluginOptions = context.pluginOptions;
+  if (!pluginOptions?.optimistic) return [];
+  const $ = (config) => ({
+    for: config.for,
+    match: config.match,
+    timing: config.timing,
+    updater: config.updater,
+    rollbackOnError: config.rollbackOnError,
+    onError: config.onError
+  });
+  const apiProxy = (0, import_core.createSelectorProxy)();
+  const optimisticConfigs = pluginOptions.optimistic(
+    $,
+    apiProxy
+  );
+  return Array.isArray(optimisticConfigs) ? optimisticConfigs : [optimisticConfigs];
+}
+function applyOptimisticUpdate(stateManager, config) {
+  const tags = extractTagsFromFor(config.for);
+  const targetSelfTag = getExactMatchPath(tags);
+  if (!targetSelfTag) return [];
+  const snapshots = [];
+  const entries = stateManager.getCacheEntriesBySelfTag(targetSelfTag);
+  for (const { key, entry } of entries) {
+    if (key.includes('"type":"infinite-tracker"')) continue;
+    if (!key.includes('"method":"$get"')) continue;
+    if (config.match) {
+      const request = parseRequestFromKey(key);
+      if (!request || !config.match(request)) continue;
+    }
+    if (entry.state.data === void 0) continue;
+    snapshots.push({ key, previousData: entry.state.data });
+    stateManager.setCache(key, {
+      previousData: entry.state.data,
+      state: {
+        ...entry.state,
+        data: config.updater(entry.state.data, void 0)
+      }
+    });
+    stateManager.setPluginResult(key, { isOptimistic: true });
+  }
+  return snapshots;
+}
+function confirmOptimistic(stateManager, snapshots) {
+  for (const { key } of snapshots) {
+    const entry = stateManager.getCache(key);
+    if (entry) {
+      stateManager.setCache(key, {
+        previousData: void 0
+      });
+      stateManager.setPluginResult(key, { isOptimistic: false });
+    }
+  }
+}
+function rollbackOptimistic(stateManager, snapshots) {
+  for (const { key, previousData } of snapshots) {
+    const entry = stateManager.getCache(key);
+    if (entry) {
+      stateManager.setCache(key, {
+        previousData: void 0,
+        state: {
+          ...entry.state,
+          data: previousData
+        }
+      });
+      stateManager.setPluginResult(key, { isOptimistic: false });
+    }
+  }
+}
+function optimisticPlugin() {
+  return {
+    name: "spoosh:optimistic",
+    operations: ["write"],
+    dependencies: ["spoosh:invalidation"],
+    middleware: async (context, next) => {
+      const { stateManager } = context;
+      const configs = resolveOptimisticConfigs(context);
+      if (configs.length > 0) {
+        context.plugins.get("spoosh:invalidation")?.setAutoInvalidateDefault("none");
+      }
+      const immediateConfigs = configs.filter((c) => c.timing !== "onSuccess");
+      const allSnapshots = [];
+      for (const config of immediateConfigs) {
+        const snapshots2 = applyOptimisticUpdate(stateManager, config);
+        allSnapshots.push(...snapshots2);
+      }
+      if (allSnapshots.length > 0) {
+        context.metadata.set(OPTIMISTIC_SNAPSHOTS_KEY, allSnapshots);
+      }
+      const response = await next();
+      const snapshots = context.metadata.get(
+        OPTIMISTIC_SNAPSHOTS_KEY
+      ) ?? [];
+      if (response.error) {
+        const shouldRollback = configs.some(
+          (c) => c.rollbackOnError !== false && c.timing !== "onSuccess"
+        );
+        if (shouldRollback && snapshots.length > 0) {
+          rollbackOptimistic(stateManager, snapshots);
+        }
+        for (const config of configs) {
+          if (config.onError) {
+            config.onError(response.error);
+          }
+        }
+      } else {
+        if (snapshots.length > 0) {
+          confirmOptimistic(stateManager, snapshots);
+        }
+        const onSuccessConfigs = configs.filter(
+          (c) => c.timing === "onSuccess"
+        );
+        for (const config of onSuccessConfigs) {
+          const tags = extractTagsFromFor(config.for);
+          const targetSelfTag = getExactMatchPath(tags);
+          if (!targetSelfTag) continue;
+          const entries = stateManager.getCacheEntriesBySelfTag(targetSelfTag);
+          for (const { key, entry } of entries) {
+            if (!key.includes('"method":"$get"')) continue;
+            if (config.match) {
+              const request = parseRequestFromKey(key);
+              if (!request || !config.match(request)) continue;
+            }
+            stateManager.setCache(key, {
+              state: {
+                ...entry.state,
+                data: config.updater(entry.state.data, response.data)
+              }
+            });
+          }
+        }
+      }
+      return response;
+    }
+  };
+}

package/dist/index.mjs

@@ -0,0 +1,181 @@
+// src/plugin.ts
+import {
+  createSelectorProxy,
+  extractPathFromSelector,
+  generateTags
+} from "@spoosh/core";
+import "@spoosh/plugin-invalidation";
+var OPTIMISTIC_SNAPSHOTS_KEY = "optimistic:snapshots";
+function extractTagsFromFor(forFn) {
+  return generateTags(extractPathFromSelector(forFn));
+}
+function getExactMatchPath(tags) {
+  return tags.length > 0 ? tags[tags.length - 1] : void 0;
+}
+function findInObject(obj, key) {
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+    return void 0;
+  }
+  const record = obj;
+  if (key in record) {
+    return record[key];
+  }
+  for (const value of Object.values(record)) {
+    const found = findInObject(value, key);
+    if (found !== void 0) return found;
+  }
+  return void 0;
+}
+function parseRequestFromKey(key) {
+  try {
+    const parsed = JSON.parse(key);
+    return {
+      query: findInObject(parsed, "query"),
+      params: findInObject(parsed, "params"),
+      body: findInObject(parsed, "body")
+    };
+  } catch {
+    return void 0;
+  }
+}
+function resolveOptimisticConfigs(context) {
+  const pluginOptions = context.pluginOptions;
+  if (!pluginOptions?.optimistic) return [];
+  const $ = (config) => ({
+    for: config.for,
+    match: config.match,
+    timing: config.timing,
+    updater: config.updater,
+    rollbackOnError: config.rollbackOnError,
+    onError: config.onError
+  });
+  const apiProxy = createSelectorProxy();
+  const optimisticConfigs = pluginOptions.optimistic(
+    $,
+    apiProxy
+  );
+  return Array.isArray(optimisticConfigs) ? optimisticConfigs : [optimisticConfigs];
+}
+function applyOptimisticUpdate(stateManager, config) {
+  const tags = extractTagsFromFor(config.for);
+  const targetSelfTag = getExactMatchPath(tags);
+  if (!targetSelfTag) return [];
+  const snapshots = [];
+  const entries = stateManager.getCacheEntriesBySelfTag(targetSelfTag);
+  for (const { key, entry } of entries) {
+    if (key.includes('"type":"infinite-tracker"')) continue;
+    if (!key.includes('"method":"$get"')) continue;
+    if (config.match) {
+      const request = parseRequestFromKey(key);
+      if (!request || !config.match(request)) continue;
+    }
+    if (entry.state.data === void 0) continue;
+    snapshots.push({ key, previousData: entry.state.data });
+    stateManager.setCache(key, {
+      previousData: entry.state.data,
+      state: {
+        ...entry.state,
+        data: config.updater(entry.state.data, void 0)
+      }
+    });
+    stateManager.setPluginResult(key, { isOptimistic: true });
+  }
+  return snapshots;
+}
+function confirmOptimistic(stateManager, snapshots) {
+  for (const { key } of snapshots) {
+    const entry = stateManager.getCache(key);
+    if (entry) {
+      stateManager.setCache(key, {
+        previousData: void 0
+      });
+      stateManager.setPluginResult(key, { isOptimistic: false });
+    }
+  }
+}
+function rollbackOptimistic(stateManager, snapshots) {
+  for (const { key, previousData } of snapshots) {
+    const entry = stateManager.getCache(key);
+    if (entry) {
+      stateManager.setCache(key, {
+        previousData: void 0,
+        state: {
+          ...entry.state,
+          data: previousData
+        }
+      });
+      stateManager.setPluginResult(key, { isOptimistic: false });
+    }
+  }
+}
+function optimisticPlugin() {
+  return {
+    name: "spoosh:optimistic",
+    operations: ["write"],
+    dependencies: ["spoosh:invalidation"],
+    middleware: async (context, next) => {
+      const { stateManager } = context;
+      const configs = resolveOptimisticConfigs(context);
+      if (configs.length > 0) {
+        context.plugins.get("spoosh:invalidation")?.setAutoInvalidateDefault("none");
+      }
+      const immediateConfigs = configs.filter((c) => c.timing !== "onSuccess");
+      const allSnapshots = [];
+      for (const config of immediateConfigs) {
+        const snapshots2 = applyOptimisticUpdate(stateManager, config);
+        allSnapshots.push(...snapshots2);
+      }
+      if (allSnapshots.length > 0) {
+        context.metadata.set(OPTIMISTIC_SNAPSHOTS_KEY, allSnapshots);
+      }
+      const response = await next();
+      const snapshots = context.metadata.get(
+        OPTIMISTIC_SNAPSHOTS_KEY
+      ) ?? [];
+      if (response.error) {
+        const shouldRollback = configs.some(
+          (c) => c.rollbackOnError !== false && c.timing !== "onSuccess"
+        );
+        if (shouldRollback && snapshots.length > 0) {
+          rollbackOptimistic(stateManager, snapshots);
+        }
+        for (const config of configs) {
+          if (config.onError) {
+            config.onError(response.error);
+          }
+        }
+      } else {
+        if (snapshots.length > 0) {
+          confirmOptimistic(stateManager, snapshots);
+        }
+        const onSuccessConfigs = configs.filter(
+          (c) => c.timing === "onSuccess"
+        );
+        for (const config of onSuccessConfigs) {
+          const tags = extractTagsFromFor(config.for);
+          const targetSelfTag = getExactMatchPath(tags);
+          if (!targetSelfTag) continue;
+          const entries = stateManager.getCacheEntriesBySelfTag(targetSelfTag);
+          for (const { key, entry } of entries) {
+            if (!key.includes('"method":"$get"')) continue;
+            if (config.match) {
+              const request = parseRequestFromKey(key);
+              if (!request || !config.match(request)) continue;
+            }
+            stateManager.setCache(key, {
+              state: {
+                ...entry.state,
+                data: config.updater(entry.state.data, response.data)
+              }
+            });
+          }
+        }
+      }
+      return response;
+    }
+  };
+}
+export {
+  OPTIMISTIC_SNAPSHOTS_KEY,
+  optimisticPlugin
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@spoosh/plugin-optimistic",
+  "version": "0.1.0-beta.0",
+  "description": "Optimistic updates plugin for Spoosh - instant UI updates with automatic rollback",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nxnom/spoosh.git",
+    "directory": "packages/plugin-optimistic"
+  },
+  "bugs": {
+    "url": "https://github.com/nxnom/spoosh/issues"
+  },
+  "homepage": "https://spoosh.dev/docs/plugins/optimistic",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spoosh",
+    "plugin",
+    "optimistic",
+    "api-client",
+    "mutations"
+  ],
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@spoosh/core": ">=0.1.0",
+    "@spoosh/plugin-invalidation": ">=0.1.0"
+  },
+  "devDependencies": {
+    "@spoosh/core": "0.1.0-beta.0",
+    "@spoosh/plugin-invalidation": "0.1.0-beta.0",
+    "@spoosh/test-utils": "0.1.0-beta.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --max-warnings 0",
+    "format": "prettier --write 'src/**/*.ts'"
+  }
+}