optimistic-colada 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prains
+
+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,249 @@
+# optimistic-colada
+
+Declarative optimistic updates for [Pinia Colada](https://pinia-colada.esm.dev/).
+
+A Pinia Colada plugin that snapshots the query cache when a mutation starts, writes the expected result immediately, rolls the cache back if the mutation fails, and invalidates the affected queries once it settles. All of it is configured with a single `optimistic` option on `useMutation` instead of hand-written `onMutate` / `onError` / `onSettled` hooks in every mutation.
+
+## Why
+
+The manual pattern for optimistic updates looks like this, repeated in every mutation:
+
+```ts
+const queryCache = useQueryCache()
+
+const { mutate: renameProject } = useMutation({
+  mutation: (input: { id: string; name: string }) => api.projects.rename(input),
+  onMutate(vars) {
+    const previous = queryCache.getQueryData<Project[]>(['projects'])
+    queryCache.setQueryData(
+      ['projects'],
+      previous?.map((p) => (p.id === vars.id ? { ...p, ...vars } : p))
+    )
+    return { previous }
+  },
+  onError(_error, _vars, context) {
+    queryCache.setQueryData(['projects'], context.previous)
+  },
+  onSettled() {
+    queryCache.invalidateQueries({ key: ['projects'] })
+  }
+})
+```
+
+This version handles exactly one query key. If the same record is cached under several keys — a list, a filtered list, a detail view — each one needs its own snapshot and rollback.
+
+With the plugin:
+
+```ts
+const { mutate: renameProject } = useMutation({
+  mutation: (input: { id: string; name: string }) => api.projects.rename(input),
+  optimistic: {
+    action: OptimisticAction.update,
+    key: ['projects']
+  }
+})
+```
+
+The plugin applies the update to **every** cache entry under `['projects']` (prefix match), snapshots each one for rollback, and invalidates them after the mutation settles.
+
+## Requirements
+
+- `vue` >= 3.5
+- `@pinia/colada` >= 1.3
+
+## Installation
+
+Not published to npm yet; install from GitHub:
+
+```sh
+npm install github:Prains/optimistic-colada
+```
+
+The package builds itself on install via the `prepare` script.
+
+## Setup
+
+Register the plugin in Pinia Colada options.
+
+Vue:
+
+```ts
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import { PiniaColada } from '@pinia/colada'
+import { createOptimisticPlugin } from 'optimistic-colada'
+
+const app = createApp(App)
+app.use(createPinia())
+app.use(PiniaColada, {
+  plugins: [createOptimisticPlugin()]
+})
+```
+
+Nuxt (with `@pinia/colada-nuxt`):
+
+```ts
+// colada.options.ts
+import type { PiniaColadaOptions } from '@pinia/colada'
+import { createOptimisticPlugin } from 'optimistic-colada'
+
+export default {
+  plugins: [createOptimisticPlugin()]
+} satisfies PiniaColadaOptions
+```
+
+## Usage
+
+### Update
+
+```ts
+import { useMutation } from '@pinia/colada'
+import { OptimisticAction } from 'optimistic-colada'
+
+const { mutate: renameProject } = useMutation({
+  mutation: (input: { id: string; name: string }) => api.projects.rename(input),
+  optimistic: {
+    action: OptimisticAction.update,
+    key: ['projects']
+  }
+})
+```
+
+On `renameProject({ id, name })`, every cached query whose key starts with `['projects']` is scanned for records whose `id` matches the mutation variables. Matched records are shallow-merged with the variables. If the request fails, the previous data is restored. When the mutation settles, queries under `['projects']` are invalidated, so active queries refetch and the cache converges to server state.
+
+### Delete
+
+```ts
+const { mutate: deleteProject } = useMutation({
+  mutation: (input: { id: string }) => api.projects.delete(input),
+  optimistic: {
+    action: OptimisticAction.delete,
+    key: ['projects']
+  }
+})
+```
+
+Matching records are removed from arrays and paginated results. In paginated shapes, `total` is decremented by the number of removed records.
+
+### Create
+
+There is no built-in updater for `create` — the shape of a new record cannot be inferred from mutation variables. Provide one:
+
+```ts
+import { OptimisticAction, createOptimisticId } from 'optimistic-colada'
+
+const { mutate: createTask } = useMutation({
+  mutation: (input: { title: string }) => api.tasks.create(input),
+  optimistic: {
+    action: OptimisticAction.create,
+    key: ['tasks'],
+    updater: (cached, input) => [
+      ...(cached as Task[]),
+      { id: createOptimisticId(), title: input.title, done: false }
+    ]
+  }
+})
+```
+
+`createOptimisticId()` returns a prefixed UUID for the placeholder record, and `isOptimisticId(id)` lets components tell placeholders from persisted records — for example, to disable row actions until the record is real. The invalidation after settle replaces placeholders with server data.
+
+### Custom updater
+
+An `updater` overrides the built-in behavior for any action. It is called once per matching cache entry with the current cached data and the mutation variables, and must return the new data without mutating the input. Return `undefined` or the same reference to leave an entry untouched.
+
+```ts
+optimistic: {
+  action: OptimisticAction.update,
+  key: ['tasks'],
+  updater: (cached, input) => {
+    if (!Array.isArray(cached)) return undefined // skip this entry
+    return cached.map((t) => (t.id === input.id ? { ...t, done: input.done } : t))
+  }
+}
+```
+
+### Skipping invalidation
+
+```ts
+optimistic: {
+  action: OptimisticAction.update,
+  key: ['settings'],
+  skipInvalidation: true
+}
+```
+
+By default, queries under `key` are invalidated after a successful mutation. Set `skipInvalidation: true` when the optimistic write already is the final state and a refetch adds nothing. On error, rollback and invalidation happen regardless of this flag.
+
+### Identity key
+
+Built-in updaters match records by `id`. If your records use a different field:
+
+```ts
+createOptimisticPlugin({ identityKey: 'uuid' })
+```
+
+## Supported cache shapes
+
+Built-in updaters detect the shape of each cache entry independently:
+
+| Shape     | Example                      | `update`                                    | `delete`                                   |
+| --------- | ---------------------------- | ------------------------------------------- | ------------------------------------------ |
+| Array     | `[{ id, ... }, ...]`         | shallow-merge variables into matched records | remove matched records                     |
+| Paginated | `{ items: [...], total? }`   | same, inside `items`                        | remove from `items`, decrement `total`     |
+| Single    | `{ id, ... }`                | shallow-merge when `id` matches             | skipped                                    |
+
+Entries with any other shape are skipped, with a console warning in dev builds. Entries that have no data yet are skipped silently.
+
+## How it works
+
+1. On `mutate`, the plugin reads the `optimistic` config from the mutation options and collects every cache entry matching `key` (prefix match, same semantics as `queryCache.getEntries`).
+2. For each entry it computes the optimistic data — via `updater` if provided, otherwise via the built-in updater for the action — takes a snapshot of the current data (deep clone, aware of arrays, plain objects, `Date`, `Map`, `Set`), and writes the optimistic data with `setQueryData`.
+3. On success, queries under `key` are invalidated (unless `skipInvalidation`), so active queries refetch and optimistic data is replaced with server state.
+4. On error, snapshots are restored and queries under `key` are invalidated to resynchronize with the server.
+
+## API
+
+### `createOptimisticPlugin(options?): PiniaColadaPlugin`
+
+| Option        | Type     | Default | Description                                        |
+| ------------- | -------- | ------- | -------------------------------------------------- |
+| `identityKey` | `string` | `'id'`  | Field used by built-in updaters to match records   |
+
+### The `optimistic` mutation option
+
+The package augments `UseMutationOptions`, so once it is imported anywhere in the project, `optimistic` is available and typed on every `useMutation` call.
+
+| Field              | Type                                        | Required       | Description                                                       |
+| ------------------ | ------------------------------------------- | -------------- | ----------------------------------------------------------------- |
+| `action`           | `OptimisticAction.create \| update \| delete` | yes            | Selects the built-in updater                                      |
+| `key`              | `EntryKey`                                  | yes            | Query key prefix; all matching entries are updated                |
+| `updater`          | `(cachedData, vars) => unknown`             | for `create`   | Custom per-entry transform, overrides the built-in updater        |
+| `skipInvalidation` | `boolean`                                   | no             | Skip query invalidation after a successful mutation               |
+
+### Standalone updaters
+
+`applyUpdate(data, input, identityKey)`, `applyDelete(data, input, identityKey)` and `detectShape(data)` are exported for reuse inside custom updaters and in tests.
+
+### Optimistic IDs
+
+`createOptimisticId()`, `isOptimisticId(id)`, `OPTIMISTIC_PREFIX` — helpers for placeholder records in `create` flows.
+
+## Behavior notes
+
+- Built-in updaters require the mutation variables to be a plain object carrying the identity key, e.g. `{ id, ...patch }`. With non-object variables and no `updater`, the mutation runs without an optimistic write.
+- `update` shallow-merges the full variables object into matched records. Variables that are not record fields (flags, nested filter params) will show up in the cached record until invalidation refetches it; use a custom `updater` in that case.
+- Rollback restores per-entry snapshots taken when the mutation started. If several mutations touch the same entries concurrently, a rollback can briefly restore data from before a neighboring mutation — the invalidation that follows brings the entries back to server state.
+- Mutations without an `optimistic` config are ignored by the plugin.
+
+## Development
+
+```sh
+npm install
+npm test        # vitest
+npm run typecheck
+npm run build   # tsup -> dist/
+```
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { EntryKey, PiniaColadaPlugin } from '@pinia/colada';
+
+declare enum OptimisticAction {
+    create = "create",
+    update = "update",
+    delete = "delete"
+}
+interface OptimisticConfig<TVars = unknown> {
+    action: OptimisticAction;
+    key: EntryKey;
+    updater?(cachedData: unknown, input: TVars): unknown;
+    skipInvalidation?: boolean;
+}
+interface OptimisticPluginOptions {
+    /** Field name used to identify records. Default: 'id' */
+    identityKey?: string;
+}
+declare module '@pinia/colada' {
+    interface UseMutationOptions<TData, TVars, TError, TContext> {
+        readonly __optimisticTypeParameters?: [TData, TError, TContext] extends [never, never, never] ? never : never;
+        optimistic?: OptimisticConfig<TVars>;
+    }
+    interface UseMutationOptionsGlobal {
+        optimistic?: OptimisticConfig;
+    }
+}
+
+declare function createOptimisticPlugin(options?: OptimisticPluginOptions): PiniaColadaPlugin;
+
+declare enum DataShape {
+    array = "array",
+    paginated = "paginated",
+    single = "single",
+    unknown = "unknown"
+}
+declare function detectShape(data: unknown): DataShape;
+declare function applyUpdate(data: unknown, input: Record<string, unknown>, identityKey: string): unknown;
+declare function applyDelete(data: unknown, input: Record<string, unknown>, identityKey: string): unknown;
+
+declare const OPTIMISTIC_PREFIX = "__optimistic_";
+declare function createOptimisticId(): string;
+declare function isOptimisticId(id: string): boolean;
+
+export { DataShape, OPTIMISTIC_PREFIX, OptimisticAction, type OptimisticConfig, type OptimisticPluginOptions, applyDelete, applyUpdate, createOptimisticId, createOptimisticPlugin, detectShape, isOptimisticId };

package/dist/index.js

@@ -0,0 +1,227 @@
+// src/plugin.ts
+import { useMutationCache } from "@pinia/colada";
+import { toRaw } from "vue";
+
+// src/types.ts
+var OptimisticAction = /* @__PURE__ */ ((OptimisticAction2) => {
+  OptimisticAction2["create"] = "create";
+  OptimisticAction2["update"] = "update";
+  OptimisticAction2["delete"] = "delete";
+  return OptimisticAction2;
+})(OptimisticAction || {});
+
+// src/updaters.ts
+var DataShape = /* @__PURE__ */ ((DataShape2) => {
+  DataShape2["array"] = "array";
+  DataShape2["paginated"] = "paginated";
+  DataShape2["single"] = "single";
+  DataShape2["unknown"] = "unknown";
+  return DataShape2;
+})(DataShape || {});
+function isOptimisticObject(data) {
+  return typeof data === "object" && data !== null && !Array.isArray(data);
+}
+function isOptimisticObjectArray(data) {
+  return Array.isArray(data) && data.every(isOptimisticObject);
+}
+function isPaginatedOptimisticData(data) {
+  return isOptimisticObject(data) && "items" in data && isOptimisticObjectArray(data.items);
+}
+function detectShape(data) {
+  if (isOptimisticObjectArray(data)) return "array" /* array */;
+  if (isPaginatedOptimisticData(data)) return "paginated" /* paginated */;
+  if (isOptimisticObject(data) && "id" in data) return "single" /* single */;
+  return "unknown" /* unknown */;
+}
+function applyUpdate(data, input, identityKey) {
+  const shape = detectShape(data);
+  const inputId = input[identityKey];
+  switch (shape) {
+    case "array" /* array */: {
+      if (!isOptimisticObjectArray(data)) return void 0;
+      const items = data;
+      let changed = false;
+      const mapped = items.map((item) => {
+        if (item[identityKey] !== inputId) return item;
+        changed = true;
+        return { ...item, ...input };
+      });
+      return changed ? mapped : data;
+    }
+    case "single" /* single */: {
+      if (!isOptimisticObject(data)) return void 0;
+      const object = data;
+      return object[identityKey] === inputId ? { ...object, ...input } : data;
+    }
+    case "paginated" /* paginated */: {
+      if (!isPaginatedOptimisticData(data)) return void 0;
+      const paged = data;
+      let changed = false;
+      const mapped = paged.items.map((item) => {
+        if (item[identityKey] !== inputId) return item;
+        changed = true;
+        return { ...item, ...input };
+      });
+      return changed ? { ...paged, items: mapped } : data;
+    }
+    case "unknown" /* unknown */: {
+      return void 0;
+    }
+  }
+}
+function applyDelete(data, input, identityKey) {
+  const shape = detectShape(data);
+  const inputId = input[identityKey];
+  switch (shape) {
+    case "array" /* array */: {
+      if (!isOptimisticObjectArray(data)) return void 0;
+      const items = data;
+      const filtered = items.filter((item) => item[identityKey] !== inputId);
+      return filtered.length === items.length ? data : filtered;
+    }
+    case "single" /* single */: {
+      return void 0;
+    }
+    case "paginated" /* paginated */: {
+      if (!isPaginatedOptimisticData(data)) return void 0;
+      const paged = data;
+      const filtered = paged.items.filter((item) => item[identityKey] !== inputId);
+      return {
+        ...paged,
+        items: filtered,
+        ...typeof paged.total === "number" ? { total: paged.total - (paged.items.length - filtered.length) } : {}
+      };
+    }
+    case "unknown" /* unknown */: {
+      return void 0;
+    }
+  }
+}
+
+// src/plugin.ts
+var SKIP = /* @__PURE__ */ Symbol("skip");
+function isPlainRecord(value) {
+  if (!value || typeof value !== "object") return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+function isOptimisticMutationEntry(value) {
+  return isPlainRecord(value) && isPlainRecord(value.options);
+}
+function cloneSnapshot(value) {
+  const raw = toRaw(value);
+  if (Array.isArray(raw)) {
+    return raw.map((item) => cloneSnapshot(item));
+  }
+  if (raw instanceof Date) {
+    return new Date(raw);
+  }
+  if (raw instanceof Map) {
+    return new Map(
+      [...raw.entries()].map(([key, mapValue]) => [cloneSnapshot(key), cloneSnapshot(mapValue)])
+    );
+  }
+  if (raw instanceof Set) {
+    return new Set([...raw.values()].map((item) => cloneSnapshot(item)));
+  }
+  if (isPlainRecord(raw)) {
+    return Object.fromEntries(
+      Object.entries(raw).map(([key, objectValue]) => [key, cloneSnapshot(objectValue)])
+    );
+  }
+  return raw;
+}
+function computeOptimisticData(config, currentData, variables, identityKey) {
+  if (config.updater) {
+    return config.updater(currentData, variables);
+  }
+  switch (config.action) {
+    case "create" /* create */: {
+      console.warn(
+        '[optimistic-colada] action "create" requires a custom updater. Skipping optimistic update.'
+      );
+      return SKIP;
+    }
+    case "update" /* update */: {
+      return applyUpdate(currentData, variables ?? {}, identityKey);
+    }
+    case "delete" /* delete */: {
+      return applyDelete(currentData, variables ?? {}, identityKey);
+    }
+  }
+}
+function warnUnknownShape(currentData, queryKey) {
+  if (!import.meta.env?.DEV) return;
+  const shape = detectShape(currentData);
+  if (shape === "unknown" /* unknown */) {
+    console.warn(
+      `[optimistic-colada] unknown data shape for query key ${JSON.stringify(queryKey)}. Skipping.`
+    );
+  }
+}
+function applyOptimisticEntries(queryCache, config, variables, identityKey) {
+  const entries = queryCache.getEntries({ key: config.key });
+  const snapshots = /* @__PURE__ */ new Map();
+  for (const queryEntry of entries) {
+    const currentData = queryEntry.state.value.data;
+    if (currentData === void 0) continue;
+    const updatedData = computeOptimisticData(config, currentData, variables, identityKey);
+    if (updatedData === SKIP) continue;
+    if (updatedData === void 0 && !config.updater) {
+      warnUnknownShape(currentData, queryEntry.key);
+      continue;
+    }
+    if (updatedData !== void 0 && updatedData !== currentData) {
+      snapshots.set(queryEntry.key, cloneSnapshot(currentData));
+      queryCache.setQueryData(queryEntry.key, updatedData);
+    }
+  }
+  return snapshots;
+}
+function createOptimisticPlugin(options) {
+  const identityKey = options?.identityKey ?? "id";
+  return ({ queryCache, pinia }) => {
+    const mutationCache = useMutationCache(pinia);
+    mutationCache.$onAction(({ name, args, after, onError }) => {
+      if (name !== "mutate") return;
+      const entry = args[0];
+      if (!isOptimisticMutationEntry(entry)) return;
+      const config = entry.options.optimistic;
+      if (!config) return;
+      const variables = isPlainRecord(entry.vars) ? entry.vars : void 0;
+      if (!variables && !config.updater) return;
+      const snapshots = applyOptimisticEntries(queryCache, config, variables, identityKey);
+      after(() => {
+        if (!config.skipInvalidation) {
+          queryCache.invalidateQueries({ key: config.key });
+        }
+      });
+      onError(() => {
+        for (const [key, data] of snapshots) {
+          queryCache.setQueryData(key, data);
+        }
+        queryCache.invalidateQueries({ key: config.key });
+      });
+    });
+  };
+}
+
+// src/helpers.ts
+var OPTIMISTIC_PREFIX = "__optimistic_";
+function createOptimisticId() {
+  return `${OPTIMISTIC_PREFIX}${crypto.randomUUID()}`;
+}
+function isOptimisticId(id) {
+  return typeof id === "string" && id.startsWith(OPTIMISTIC_PREFIX);
+}
+export {
+  DataShape,
+  OPTIMISTIC_PREFIX,
+  OptimisticAction,
+  applyDelete,
+  applyUpdate,
+  createOptimisticId,
+  createOptimisticPlugin,
+  detectShape,
+  isOptimisticId
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "optimistic-colada",
+  "version": "0.1.0",
+  "description": "Declarative optimistic updates plugin for Pinia Colada",
+  "type": "module",
+  "license": "MIT",
+  "author": "Prains",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Prains/optimistic-colada.git"
+  },
+  "homepage": "https://github.com/Prains/optimistic-colada#readme",
+  "bugs": "https://github.com/Prains/optimistic-colada/issues",
+  "keywords": [
+    "vue",
+    "pinia",
+    "pinia-colada",
+    "optimistic-updates",
+    "optimistic-ui",
+    "mutations",
+    "cache"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "prepack": "npm run build",
+    "prepare": "npm run build"
+  },
+  "peerDependencies": {
+    "@pinia/colada": "^1.3.0",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@pinia/colada": "^1.3.1",
+    "pinia": "^3.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0",
+    "vue": "^3.5.0"
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,9 @@
+export const OPTIMISTIC_PREFIX = '__optimistic_'
+
+export function createOptimisticId(): string {
+  return `${OPTIMISTIC_PREFIX}${crypto.randomUUID()}`
+}
+
+export function isOptimisticId(id: string): boolean {
+  return typeof id === 'string' && id.startsWith(OPTIMISTIC_PREFIX)
+}

package/src/import-meta.d.ts

@@ -0,0 +1,3 @@
+interface ImportMeta {
+  readonly env?: { readonly DEV?: boolean }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { createOptimisticPlugin } from './plugin'
+export * from './types'
+export * from './updaters'
+export * from './helpers'

package/src/plugin.ts

@@ -0,0 +1,161 @@
+import { useMutationCache } from '@pinia/colada'
+import type { PiniaColadaPlugin, EntryKey } from '@pinia/colada'
+import { toRaw } from 'vue'
+import { OptimisticAction } from './types'
+import type { OptimisticConfig, OptimisticPluginOptions } from './types'
+import { applyUpdate, applyDelete, detectShape, DataShape } from './updaters'
+
+const SKIP = Symbol('skip')
+
+type OptimisticMutationEntry = {
+  options: {
+    optimistic?: OptimisticConfig
+  }
+  vars?: unknown
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== 'object') return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype === Object.prototype || prototype === null
+}
+
+function isOptimisticMutationEntry(value: unknown): value is OptimisticMutationEntry {
+  return isPlainRecord(value) && isPlainRecord(value.options)
+}
+
+function cloneSnapshot(value: unknown): unknown {
+  const raw = toRaw(value)
+
+  if (Array.isArray(raw)) {
+    return raw.map((item) => cloneSnapshot(item))
+  }
+
+  if (raw instanceof Date) {
+    return new Date(raw)
+  }
+
+  if (raw instanceof Map) {
+    return new Map(
+      [...raw.entries()].map(([key, mapValue]) => [cloneSnapshot(key), cloneSnapshot(mapValue)])
+    )
+  }
+
+  if (raw instanceof Set) {
+    return new Set([...raw.values()].map((item) => cloneSnapshot(item)))
+  }
+
+  if (isPlainRecord(raw)) {
+    return Object.fromEntries(
+      Object.entries(raw).map(([key, objectValue]) => [key, cloneSnapshot(objectValue)])
+    )
+  }
+
+  return raw
+}
+
+/**
+ * Compute the optimistic data for a single query entry.
+ * Returns SKIP sentinel when entry should be skipped entirely.
+ */
+function computeOptimisticData(
+  config: OptimisticConfig,
+  currentData: unknown,
+  variables: Record<string, unknown> | undefined,
+  identityKey: string
+): unknown | typeof SKIP {
+  if (config.updater) {
+    return config.updater(currentData, variables)
+  }
+
+  switch (config.action) {
+    case OptimisticAction.create: {
+      console.warn(
+        '[optimistic-colada] action "create" requires a custom updater. Skipping optimistic update.'
+      )
+      return SKIP
+    }
+    case OptimisticAction.update: {
+      return applyUpdate(currentData, variables ?? {}, identityKey)
+    }
+    case OptimisticAction.delete: {
+      return applyDelete(currentData, variables ?? {}, identityKey)
+    }
+  }
+}
+
+function warnUnknownShape(currentData: unknown, queryKey: unknown) {
+  if (!import.meta.env?.DEV) return
+  const shape = detectShape(currentData)
+  if (shape === DataShape.unknown) {
+    console.warn(
+      `[optimistic-colada] unknown data shape for query key ${JSON.stringify(queryKey)}. Skipping.`
+    )
+  }
+}
+
+function applyOptimisticEntries(
+  queryCache: Parameters<PiniaColadaPlugin>[0]['queryCache'],
+  config: OptimisticConfig,
+  variables: Record<string, unknown> | undefined,
+  identityKey: string
+): Map<EntryKey, unknown> {
+  const entries = queryCache.getEntries({ key: config.key })
+  const snapshots = new Map<EntryKey, unknown>()
+
+  for (const queryEntry of entries) {
+    const currentData = queryEntry.state.value.data
+    if (currentData === undefined) continue
+
+    const updatedData = computeOptimisticData(config, currentData, variables, identityKey)
+
+    if (updatedData === SKIP) continue
+
+    if (updatedData === undefined && !config.updater) {
+      warnUnknownShape(currentData, queryEntry.key)
+      continue
+    }
+
+    if (updatedData !== undefined && updatedData !== currentData) {
+      snapshots.set(queryEntry.key, cloneSnapshot(currentData))
+      queryCache.setQueryData(queryEntry.key, updatedData)
+    }
+  }
+
+  return snapshots
+}
+
+export function createOptimisticPlugin(options?: OptimisticPluginOptions): PiniaColadaPlugin {
+  const identityKey = options?.identityKey ?? 'id'
+
+  return ({ queryCache, pinia }) => {
+    const mutationCache = useMutationCache(pinia)
+
+    mutationCache.$onAction(({ name, args, after, onError }) => {
+      if (name !== 'mutate') return
+
+      const entry = args[0]
+      if (!isOptimisticMutationEntry(entry)) return
+      const config = entry.options.optimistic
+      if (!config) return
+
+      const variables = isPlainRecord(entry.vars) ? entry.vars : undefined
+      if (!variables && !config.updater) return
+
+      const snapshots = applyOptimisticEntries(queryCache, config, variables, identityKey)
+
+      after(() => {
+        if (!config.skipInvalidation) {
+          queryCache.invalidateQueries({ key: config.key })
+        }
+      })
+
+      onError(() => {
+        for (const [key, data] of snapshots) {
+          queryCache.setQueryData(key, data)
+        }
+        queryCache.invalidateQueries({ key: config.key })
+      })
+    })
+  }
+}

package/src/types.ts

@@ -0,0 +1,35 @@
+import type { EntryKey } from '@pinia/colada'
+
+export enum OptimisticAction {
+  create = 'create',
+  update = 'update',
+  delete = 'delete'
+}
+
+export interface OptimisticConfig<TVars = unknown> {
+  action: OptimisticAction
+  key: EntryKey
+  // Method shorthand: bivariant input check. Mutation TVars and the
+  // updater's narrow input often differ structurally (e.g. Prisma's
+  // ProjectWhereUniqueInput vs. a hand-written `{ where: { id: number } }`).
+  // Updaters runtime-narrow via guards, so bivariance is safe in practice.
+  updater?(cachedData: unknown, input: TVars): unknown
+  skipInvalidation?: boolean
+}
+
+export interface OptimisticPluginOptions {
+  /** Field name used to identify records. Default: 'id' */
+  identityKey?: string
+}
+
+declare module '@pinia/colada' {
+  interface UseMutationOptions<TData, TVars, TError, TContext> {
+    readonly __optimisticTypeParameters?: [TData, TError, TContext] extends [never, never, never] ?
+      never
+    : never
+    optimistic?: OptimisticConfig<TVars>
+  }
+  interface UseMutationOptionsGlobal {
+    optimistic?: OptimisticConfig
+  }
+}

package/src/updaters.ts

@@ -0,0 +1,113 @@
+export enum DataShape {
+  array = 'array',
+  paginated = 'paginated',
+  single = 'single',
+  unknown = 'unknown'
+}
+
+type OptimisticObject = Record<string, unknown>
+type PaginatedOptimisticData = OptimisticObject & {
+  items: OptimisticObject[]
+  total?: number
+}
+
+function isOptimisticObject(data: unknown): data is OptimisticObject {
+  return typeof data === 'object' && data !== null && !Array.isArray(data)
+}
+
+function isOptimisticObjectArray(data: unknown): data is OptimisticObject[] {
+  return Array.isArray(data) && data.every(isOptimisticObject)
+}
+
+function isPaginatedOptimisticData(data: unknown): data is PaginatedOptimisticData {
+  return isOptimisticObject(data) && 'items' in data && isOptimisticObjectArray(data.items)
+}
+
+// DataShape.unknown is a deliberate safe fallback: applyUpdate/applyDelete
+// need object records to map/filter over, so a non-object payload (scalar,
+// mixed array) cannot be processed partially. The plugin logs a dev-only
+// warning and skips the optimistic write in that case (see plugin.ts).
+export function detectShape(data: unknown): DataShape {
+  if (isOptimisticObjectArray(data)) return DataShape.array
+  if (isPaginatedOptimisticData(data)) return DataShape.paginated
+  if (isOptimisticObject(data) && 'id' in data) return DataShape.single
+  return DataShape.unknown
+}
+
+export function applyUpdate(
+  data: unknown,
+  input: Record<string, unknown>,
+  identityKey: string
+): unknown {
+  const shape = detectShape(data)
+  const inputId = input[identityKey]
+
+  switch (shape) {
+    case DataShape.array: {
+      if (!isOptimisticObjectArray(data)) return undefined
+      const items = data
+      let changed = false
+      const mapped = items.map((item) => {
+        if (item[identityKey] !== inputId) return item
+        changed = true
+        return { ...item, ...input }
+      })
+      return changed ? mapped : data
+    }
+    case DataShape.single: {
+      if (!isOptimisticObject(data)) return undefined
+      const object = data
+      return object[identityKey] === inputId ? { ...object, ...input } : data
+    }
+    case DataShape.paginated: {
+      if (!isPaginatedOptimisticData(data)) return undefined
+      const paged = data
+      let changed = false
+      const mapped = paged.items.map((item) => {
+        if (item[identityKey] !== inputId) return item
+        changed = true
+        return { ...item, ...input }
+      })
+      return changed ? { ...paged, items: mapped } : data
+    }
+    case DataShape.unknown: {
+      return undefined
+    }
+  }
+}
+
+export function applyDelete(
+  data: unknown,
+  input: Record<string, unknown>,
+  identityKey: string
+): unknown {
+  const shape = detectShape(data)
+  const inputId = input[identityKey]
+
+  switch (shape) {
+    case DataShape.array: {
+      if (!isOptimisticObjectArray(data)) return undefined
+      const items = data
+      const filtered = items.filter((item) => item[identityKey] !== inputId)
+      return filtered.length === items.length ? data : filtered
+    }
+    case DataShape.single: {
+      return undefined
+    }
+    case DataShape.paginated: {
+      if (!isPaginatedOptimisticData(data)) return undefined
+      const paged = data
+      const filtered = paged.items.filter((item) => item[identityKey] !== inputId)
+      return {
+        ...paged,
+        items: filtered,
+        ...(typeof paged.total === 'number' ?
+          { total: paged.total - (paged.items.length - filtered.length) }
+        : {})
+      }
+    }
+    case DataShape.unknown: {
+      return undefined
+    }
+  }
+}