@veams/status-quo-query 0.12.0 → 0.13.0

package/.turbo/turbo-build.log

@@ -1,14 +1,14 @@
 
 
-> @veams/status-quo-query@0.3.0 build
+> @veams/status-quo-query@0.12.0 build
 > npm-run-all compile
 
 
-> @veams/status-quo-query@0.3.0 compile
+> @veams/status-quo-query@0.12.0 compile
 > npm-run-all bundle:ts
 
 
-> @veams/status-quo-query@0.3.0 bundle:ts
+> @veams/status-quo-query@0.12.0 bundle:ts
 > tsc --project tsconfig.json
 
 ⠙⠙⠙

package/README.md

@@ -19,11 +19,11 @@ npm install react
 Status Quo Query deliberately keeps the public surface small:
 
 - `QueryHandle<TData, TError>` is the read handle for one query.
-- `MutationService<TData, TError, TVariables>` is the write handle for one mutation.
+- `MutationHandle<TData, TError, TVariables>` is the write handle for one mutation.
 - snapshots are passive state objects returned from `getSnapshot()` and `subscribe(...)`.
 - commands stay on the handle: `refetch()`, `invalidate()`, `mutate()`, `reset()`.
 - `QueryManager` is the broader coordination layer for cross-query work.
-- `@veams/status-quo-query/react` is optional and adds one React subscription hook over the same handle shape.
+- `@veams/status-quo-query/react` is optional and adds React subscription hooks (`useQueryHandle`, `useMutationHandle`) over the same handle shape.
 
 That keeps the package usable in service code, query handlers, state handlers, and React components without changing the core query or mutation API.
 
@@ -49,13 +49,13 @@ Root exports:
 - `CreateUntrackedMutation`
 - `QueryHandle`
 - `QueryHandleData`
-- `MutationService`
+- `MutationHandle`
 - `QueryHandleSnapshot`
-- `MutationServiceSnapshot`
+- `MutationHandleSnapshot`
 - `QueryDependencyTuple`
 - `QueryHandleOptions`
-- `MutationServiceOptions`
-- `TrackedMutationServiceOptions`
+- `MutationHandleOptions`
+- `TrackedMutationHandleOptions`
 - `QueryInvalidateOptions`
 - `QueryMetaState`
 - `TrackedDependencyRecord`
@@ -70,7 +70,7 @@ Subpath exports:
 - `@veams/status-quo-query/provider`
 - `@veams/status-quo-query/query`
 - `@veams/status-quo-query/mutation`
-- `@veams/status-quo-query/react`
+- `@veams/status-quo-query/react` (`useQueryHandle`, `useMutationHandle`)
 
 ## Quickstart
 
@@ -133,8 +133,9 @@ await userQuery.invalidate({ refetchType: 'none' });
 
 ## React Bindings
 
-The React entrypoint exposes `useQueryHandle(...)` and keeps `react` optional unless you
-import `@veams/status-quo-query/react`.
+The React entrypoint exposes `useQueryHandle(...)` and `useMutationHandle(...)` and keeps `react` optional unless you import `@veams/status-quo-query/react`.
+
+### `useQueryHandle`
 
 ```tsx
 import { useQueryHandle } from '@veams/status-quo-query/react';
@@ -153,6 +154,35 @@ Use the hook when a component should subscribe directly to a query handle and re
 - call `query.refetch()` or `query.invalidate()` on the handle itself
 - derive view-specific values in the component instead of adding selector logic to the hook
 
+### `useMutationHandle`
+
+```tsx
+import { useMutationHandle } from '@veams/status-quo-query/react';
+import type { MutationHandle } from '@veams/status-quo-query';
+
+function SaveButton({
+  mutation,
+  payload,
+}: {
+  mutation: MutationHandle<{ ok: boolean }, Error, { name: string }>;
+  payload: { name: string };
+}) {
+  const snapshot = useMutationHandle(mutation);
+
+  return (
+    <button onClick={() => mutation.mutate(payload)} disabled={snapshot.isPending}>
+      {snapshot.isPending ? 'Saving…' : 'Save'}
+    </button>
+  );
+}
+```
+
+Use `useMutationHandle` when a component should react to mutation state (pending, success, error). Keep imperative calls on the handle itself:
+
+- read `status`, `isPending`, `isError`, `isSuccess`, `data`, `error`, `variables` from the snapshot
+- call `mutation.mutate(variables)` or `mutation.reset()` on the handle itself
+- the hook does not trigger the mutation — it only subscribes to its state
+
 ## Status Quo Integration
 
 The same query handle can also feed a `status-quo` handler through `bindSubscribable(...)`.
@@ -763,7 +793,7 @@ Only `deps` participates in automatic invalidation tracking. `view` is optional
 
 `createQuery(queryKey, queryFn, options?)` returns the same `QueryHandle<TData, TError>` shape as `createUntrackedQuery(...)`, but it registers the query hash under every `deps` entry, re-registers on `refetch()` or the first `subscribe(...)` if TanStack has removed the cache entry in the meantime, and keeps the registry in sync when `dependsOn` derives a new tracked key at runtime.
 
-`createMutation(mutationFn, options?)` returns the same `MutationService<TData, TError, TVariables, TOnMutateResult>` shape as `createUntrackedMutation(...)`, but adds:
+`createMutation(mutationFn, options?)` returns the same `MutationHandle<TData, TError, TVariables, TOnMutateResult>` shape as `createUntrackedMutation(...)`, but adds:
 
 - `dependencyKeys?`
 - `resolveDependencies?`
@@ -786,7 +816,7 @@ Captures dependency names once and returns:
 - the tracked query factory
 - a tracked mutation factory whose default resolver reads `variables[dependencyKey]`
 
-The tracked query factory still expects a query key with a final `{ deps, view? }` segment. The tracked mutation factory keeps the same `MutationService` shape as `createMutation(...)`, but no longer needs `dependencyKeys` repeated in each call.
+The tracked query factory still expects a query key with a final `{ deps, view? }` segment. The tracked mutation factory keeps the same `MutationHandle` shape as `createMutation(...)`, but no longer needs `dependencyKeys` repeated in each call.
 
 Reach for standalone `createMutation(...)` when:
 
@@ -844,11 +874,11 @@ It also adds:
 
 Creates a `createUntrackedMutation` factory bound to a `QueryClient`.
 
-`createUntrackedMutation(mutationFn, options?)` returns `MutationService<TData, TError, TVariables, TOnMutateResult>`.
+`createUntrackedMutation(mutationFn, options?)` returns `MutationHandle<TData, TError, TVariables, TOnMutateResult>`.
 
-`MutationServiceOptions` is based on TanStack `MutationObserverOptions`, without `mutationFn` because it is provided directly to `createUntrackedMutation`.
+`MutationHandleOptions` is based on TanStack `MutationObserverOptions`, without `mutationFn` because it is provided directly to `createUntrackedMutation`.
 
-`MutationService` methods:
+`MutationHandle` methods:
 
 - `getSnapshot()`
 - `subscribe(listener)`
@@ -856,7 +886,7 @@ Creates a `createUntrackedMutation` factory bound to a `QueryClient`.
 - `reset()`
 - `unsafe_getResult()`
 
-`MutationServiceSnapshot<TData, TError, TVariables>` fields:
+`MutationHandleSnapshot<TData, TError, TVariables>` fields:
 
 - `data`
 - `error`

package/dist/mutation.d.ts

@@ -4,7 +4,7 @@ export type MutationStatus = TanstackMutationStatus;
 /**
  * Represents a stable snapshot of the mutation service's state.
  */
-export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVariables = void> {
+export interface MutationHandleSnapshot<TData = unknown, TError = Error, TVariables = void> {
     data: TData | undefined;
     error: TError | null;
     status: MutationStatus;
@@ -17,9 +17,9 @@ export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVaria
 /**
  * Defines the public API for a mutation service.
  */
-export interface MutationService<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> {
-    getSnapshot: () => MutationServiceSnapshot<TData, TError, TVariables>;
-    subscribe: (listener: (snapshot: MutationServiceSnapshot<TData, TError, TVariables>) => void) => () => void;
+export interface MutationHandle<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> {
+    getSnapshot: () => MutationHandleSnapshot<TData, TError, TVariables>;
+    subscribe: (listener: (snapshot: MutationHandleSnapshot<TData, TError, TVariables>) => void) => () => void;
     mutate: (variables: TVariables, options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>) => Promise<TData>;
     reset: () => void;
     unsafe_getResult: () => MutationObserverResult<TData, TError, TVariables, TOnMutateResult>;
@@ -27,12 +27,12 @@ export interface MutationService<TData = unknown, TError = Error, TVariables = v
 /**
  * Configuration options for creating a mutation service, excluding the mutation function itself.
  */
-export type MutationServiceOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> = Omit<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationFn'>;
+export type MutationHandleOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> = Omit<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationFn'>;
 /**
  * Function signature for the untracked mutation factory.
  */
 export interface CreateUntrackedMutation {
-    <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: MutationHandleOptions<TData, TError, TVariables, TOnMutateResult>): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 /**
  * Additional options for tracked mutations that invalidate queries automatically.
@@ -41,7 +41,7 @@ export interface CreateUntrackedMutation {
  * options only describe how the facade should derive dependency values and when it should
  * invalidate matching tracked queries after the mutation lifecycle settles.
  */
-export interface TrackedMutationServiceOptions<TDeps extends TrackedDependencyRecord = TrackedDependencyRecord, TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> extends MutationServiceOptions<TData, TError, TVariables, TOnMutateResult> {
+export interface TrackedMutationHandleOptions<TDeps extends TrackedDependencyRecord = TrackedDependencyRecord, TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> extends MutationHandleOptions<TData, TError, TVariables, TOnMutateResult> {
     dependencyKeys?: readonly (keyof TDeps & string)[];
     resolveDependencies?: (variables: TVariables) => Partial<TDeps>;
     invalidateOn?: TrackedInvalidateOn;
@@ -51,7 +51,7 @@ export interface TrackedMutationServiceOptions<TDeps extends TrackedDependencyRe
  * Function signature for the default mutation factory with automatic invalidation.
  */
 export interface CreateMutation {
-    <TDeps extends TrackedDependencyRecord = TrackedDependencyRecord, TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: TrackedMutationServiceOptions<TDeps, TData, TError, TVariables, TOnMutateResult>): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    <TDeps extends TrackedDependencyRecord = TrackedDependencyRecord, TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: TrackedMutationHandleOptions<TDeps, TData, TError, TVariables, TOnMutateResult>): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 /**
  * Prepares the mutation factory by binding it to a specific QueryClient instance.

package/dist/mutation.js

@@ -8,7 +8,7 @@ import { pickTrackedDependencies, resolveTrackedQueries, toTrackedDependencyEntr
 export function setupMutation(queryClient) {
     // Returns the actual factory function for creating individual mutation services.
     return function createMutation(mutationFn, options) {
-        return createMutationService(queryClient, mutationFn, options);
+        return createMutationHandle(queryClient, mutationFn, options);
     };
 }
 /**
@@ -22,8 +22,8 @@ export function setupTrackedMutation(queryClient, trackingRegistry, defaultDepen
     return function createMutation(mutationFn, options) {
         // Split tracked-only options from the underlying TanStack mutation observer options.
         const { dependencyKeys, invalidateOn = 'success', matchMode = 'intersection', resolveDependencies, ...mutationOptions } = options ?? {};
-        // Reuse the normal mutation service so snapshots and subscription behavior stay identical.
-        const service = createMutationService(queryClient, mutationFn, mutationOptions);
+        // Reuse the normal mutation handle so snapshots and subscription behavior stay identical.
+        const handle = createMutationHandle(queryClient, mutationFn, mutationOptions);
         // The paired helper injects dependency keys here, while standalone tracked mutations can
         // still provide them directly or bypass them with a custom resolver.
         const resolvedDependencyKeys = (dependencyKeys ?? defaultDependencyKeys);
@@ -41,12 +41,12 @@ export function setupTrackedMutation(queryClient, trackingRegistry, defaultDepen
             })));
         };
         return {
-            ...service,
+            ...handle,
             mutate: async (variables, mutateOptions) => {
                 try {
                     // Let TanStack finish the mutation first so its own callbacks and state machine remain
                     // authoritative. The facade only coordinates the follow-up invalidation.
-                    const result = await service.mutate(variables, mutateOptions);
+                    const result = await handle.mutate(variables, mutateOptions);
                     if (invalidateOn === 'success' || invalidateOn === 'settled') {
                         await invalidateTrackedQueries(variables);
                     }
@@ -71,7 +71,7 @@ export function setupTrackedMutation(queryClient, trackingRegistry, defaultDepen
 /**
  * Internal helper to transform a raw Tanstack mutation result into our public snapshot format.
  */
-function toMutationServiceSnapshot(result) {
+function toMutationHandleSnapshot(result) {
     // Extract and return the relevant fields for the UI or other services.
     return {
         data: result.data,
@@ -84,7 +84,7 @@ function toMutationServiceSnapshot(result) {
         isSuccess: result.isSuccess,
     };
 }
-function createMutationService(queryClient, mutationFn, options) {
+function createMutationHandle(queryClient, mutationFn, options) {
     // Keep the original mutation implementation in one place so tracked and untracked mutations
     // always expose the same observer-backed runtime behavior.
     const observer = new MutationObserver(queryClient, {
@@ -92,9 +92,9 @@ function createMutationService(queryClient, mutationFn, options) {
         mutationFn,
     });
     return {
-        getSnapshot: () => toMutationServiceSnapshot(observer.getCurrentResult()),
+        getSnapshot: () => toMutationHandleSnapshot(observer.getCurrentResult()),
         subscribe: (listener) => observer.subscribe((result) => {
-            listener(toMutationServiceSnapshot(result));
+            listener(toMutationHandleSnapshot(result));
         }),
         mutate: (variables, mutateOptions) => observer.mutate(variables, mutateOptions),
         reset: () => observer.reset(),

package/dist/mutation.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutation.js","sourceRoot":"","sources":["../src/mutation.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mutation.js","sourceRoot":"","sources":["../src/mutation.ts"],"names":[],"mappings":"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"}

package/dist/provider.d.ts

@@ -1,5 +1,5 @@
 import { type QueryClient, type MutationFunction } from '@tanstack/query-core';
-import { type CreateMutation, type CreateUntrackedMutation, type MutationService, type TrackedMutationServiceOptions } from './mutation.js';
+import { type CreateMutation, type CreateUntrackedMutation, type MutationHandle, type TrackedMutationHandleOptions } from './mutation.js';
 import { type CreateQuery, type CreateUntrackedQuery } from './query.js';
 import { type TrackedDependencyValue } from './tracking.js';
 /**
@@ -9,7 +9,7 @@ import { type TrackedDependencyValue } from './tracking.js';
  * once at setup time and injects them automatically for each tracked mutation it creates.
  */
 export interface CreateMutationWithDefaults<TDependencyKey extends string> {
-    <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: Omit<TrackedMutationServiceOptions<Record<TDependencyKey, TrackedDependencyValue>, TData, TError, TVariables, TOnMutateResult>, 'dependencyKeys'>): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: Omit<TrackedMutationHandleOptions<Record<TDependencyKey, TrackedDependencyValue>, TData, TError, TVariables, TOnMutateResult>, 'dependencyKeys'>): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 /**
  * Paired tracked helper that captures dependency keys once for default mutation resolution.

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

@@ -1 +1,2 @@
 export { useQueryHandle } from './use-query-handle.js';
+export { useMutationHandle } from './use-mutation-handle.js';

package/dist/react/hooks/index.js

@@ -1,2 +1,3 @@
 export { useQueryHandle } from './use-query-handle.js';
+export { useMutationHandle } from './use-mutation-handle.js';
 //# sourceMappingURL=index.js.map

package/dist/react/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/react/hooks/use-mutation-handle.d.ts

@@ -0,0 +1,2 @@
+import type { MutationHandle, MutationHandleSnapshot } from '../../mutation.js';
+export declare function useMutationHandle<TData, TError = Error, TVariables = void>(mutationHandle: MutationHandle<TData, TError, TVariables>): MutationHandleSnapshot<TData, TError, TVariables>;

package/dist/react/hooks/use-mutation-handle.js

@@ -0,0 +1,71 @@
+// Import the React hooks needed to memoize callbacks, hold mutable cache state,
+// and connect an external store to React rendering.
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+// Subscribe a React component to a MutationHandle and return its latest snapshot.
+export function useMutationHandle(
+// Receive the external mutation handle instance to subscribe to.
+mutationHandle) {
+    // Count store notifications so we can tell when our cached snapshot is stale.
+    const snapshotVersionRef = useRef(0);
+    // Cache one client-side snapshot per observed version to keep getSnapshot stable.
+    const snapshotCacheRef = useRef(null);
+    // Cache the server snapshot separately for the useSyncExternalStore SSR fallback.
+    const serverSnapshotCacheRef = useRef(null);
+    // Create the subscribe function expected by useSyncExternalStore.
+    const subscribe = useCallback(
+    // React passes a listener that must run whenever the external store changes.
+    (listener) => 
+    // Forward the subscription to the mutation handle.
+    mutationHandle.subscribe(() => {
+        // Bump the version so later reads know the previous cache is outdated.
+        snapshotVersionRef.current += 1;
+        // Drop the cached client snapshot because the store just changed.
+        snapshotCacheRef.current = null;
+        // Drop the cached server snapshot for the same reason.
+        serverSnapshotCacheRef.current = null;
+        // Notify React that it should read a fresh snapshot.
+        listener();
+    }), 
+    // Recreate the subscription function only when the handle instance changes.
+    [mutationHandle]);
+    // Read the current client snapshot in a referentially stable way for React.
+    const getSnapshot = useCallback(() => {
+        // Read the latest store version number.
+        const version = snapshotVersionRef.current;
+        // Read the last cached client snapshot, if there is one.
+        const cachedSnapshot = snapshotCacheRef.current;
+        // Reuse the cached snapshot when it was produced for the current version.
+        if (cachedSnapshot && cachedSnapshot.version === version) {
+            // Return the cached snapshot so repeated reads in the same render stay stable.
+            return cachedSnapshot.snapshot;
+        }
+        // Ask the mutation handle for the latest snapshot because the cache is empty or stale.
+        const snapshot = mutationHandle.getSnapshot();
+        // Store the new snapshot together with the version it belongs to.
+        snapshotCacheRef.current = {
+            snapshot,
+            version,
+        };
+        // Return the freshly read snapshot to React.
+        return snapshot;
+    }, [mutationHandle]);
+    // Read the server snapshot used by React during SSR or hydration fallback paths.
+    const getServerSnapshot = useCallback(() => {
+        // Read the cached server snapshot, if one was stored earlier.
+        const cachedSnapshot = serverSnapshotCacheRef.current;
+        // Reuse the cached server snapshot to keep server reads stable.
+        if (cachedSnapshot) {
+            // Return the cached server snapshot directly.
+            return cachedSnapshot;
+        }
+        // Ask the mutation handle for a snapshot because no server cache exists yet.
+        const snapshot = mutationHandle.getSnapshot();
+        // Cache that snapshot for the next server read.
+        serverSnapshotCacheRef.current = snapshot;
+        // Return the freshly read server snapshot.
+        return snapshot;
+    }, [mutationHandle]);
+    // Let React subscribe to the external store and read snapshots through the callbacks above.
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+//# sourceMappingURL=use-mutation-handle.js.map

package/dist/react/hooks/use-mutation-handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-mutation-handle.js","sourceRoot":"","sources":["../../../src/react/hooks/use-mutation-handle.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,oDAAoD;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAelE,kFAAkF;AAClF,MAAM,UAAU,iBAAiB;AAC/B,iEAAiE;AACjE,cAAyD;IAEzD,8EAA8E;IAC9E,MAAM,kBAAkB,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACrC,kFAAkF;IAClF,MAAM,gBAAgB,GAAG,MAAM,CAAuD,IAAI,CAAC,CAAC;IAC5F,kFAAkF;IAClF,MAAM,sBAAsB,GAAG,MAAM,CACnC,IAAI,CACL,CAAC;IAEF,kEAAkE;IAClE,MAAM,SAAS,GAAG,WAAW;IAC3B,6EAA6E;IAC7E,CAAC,QAAkB,EAAE,EAAE;IACrB,mDAAmD;IACnD,cAAc,CAAC,SAAS,CAAC,GAAG,EAAE;QAC5B,uEAAuE;QACvE,kBAAkB,CAAC,OAAO,IAAI,CAAC,CAAC;QAChC,kEAAkE;QAClE,gBAAgB,CAAC,OAAO,GAAG,IAAI,CAAC;QAChC,uDAAuD;QACvD,sBAAsB,CAAC,OAAO,GAAG,IAAI,CAAC;QACtC,qDAAqD;QACrD,QAAQ,EAAE,CAAC;IACb,CAAC,CAAC;IACJ,4EAA4E;IAC5E,CAAC,cAAc,CAAC,CACjB,CAAC;IAEF,4EAA4E;IAC5E,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE;QACnC,wCAAwC;QACxC,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC;QAC3C,yDAAyD;QACzD,MAAM,cAAc,GAAG,gBAAgB,CAAC,OAAO,CAAC;QAEhD,0EAA0E;QAC1E,IAAI,cAAc,IAAI,cAAc,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YACzD,+EAA+E;YAC/E,OAAO,cAAc,CAAC,QAAQ,CAAC;QACjC,CAAC;QAED,uFAAuF;QACvF,MAAM,QAAQ,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC;QAC9C,kEAAkE;QAClE,gBAAgB,CAAC,OAAO,GAAG;YACzB,QAAQ;YACR,OAAO;SACR,CAAC;QAEF,6CAA6C;QAC7C,OAAO,QAAQ,CAAC;IAClB,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;IAErB,iFAAiF;IACjF,MAAM,iBAAiB,GAAG,WAAW,CAAC,GAAG,EAAE;QACzC,8DAA8D;QAC9D,MAAM,cAAc,GAAG,sBAAsB,CAAC,OAAO,CAAC;QAEtD,gEAAgE;QAChE,IAAI,cAAc,EAAE,CAAC;YACnB,8CAA8C;YAC9C,OAAO,cAAc,CAAC;QACxB,CAAC;QAED,6EAA6E;QAC7E,MAAM,QAAQ,GAAG,cAAc,CAAC,WAAW,EAAE,CAAC;QAC9C,gDAAgD;QAChD,sBAAsB,CAAC,OAAO,GAAG,QAAQ,CAAC;QAE1C,2CAA2C;QAC3C,OAAO,QAAQ,CAAC;IAClB,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC;IAErB,4FAA4F;IAC5F,OAAO,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC;AACzE,CAAC"}

package/dist/react/index.d.ts

@@ -1 +1 @@
-export { useQueryHandle } from './hooks/index.js';
+export { useQueryHandle, useMutationHandle } from './hooks/index.js';

package/dist/react/index.js

@@ -1,2 +1,2 @@
-export { useQueryHandle } from './hooks/index.js';
+export { useQueryHandle, useMutationHandle } from './hooks/index.js';
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo-query",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "TanStack Query service layer for the VEAMS StatusQuo ecosystem.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/mutation.ts

@@ -32,7 +32,7 @@ export type MutationStatus = TanstackMutationStatus;
 /**
  * Represents a stable snapshot of the mutation service's state.
  */
-export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVariables = void> {
+export interface MutationHandleSnapshot<TData = unknown, TError = Error, TVariables = void> {
   // The data returned from a successful mutation.
   data: TData | undefined;
   // The error object if the mutation failed.
@@ -54,17 +54,17 @@ export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVaria
 /**
  * Defines the public API for a mutation service.
  */
-export interface MutationService<
+export interface MutationHandle<
   TData = unknown,
   TError = Error,
   TVariables = void,
   TOnMutateResult = unknown,
 > {
   // Returns the current state snapshot of the mutation.
-  getSnapshot: () => MutationServiceSnapshot<TData, TError, TVariables>;
+  getSnapshot: () => MutationHandleSnapshot<TData, TError, TVariables>;
   // Subscribes a listener to state changes; returns an unsubscribe function.
   subscribe: (
-    listener: (snapshot: MutationServiceSnapshot<TData, TError, TVariables>) => void
+    listener: (snapshot: MutationHandleSnapshot<TData, TError, TVariables>) => void
   ) => () => void;
   // Triggers the mutation with the given variables and optional lifecycle callbacks.
   mutate: (
@@ -80,7 +80,7 @@ export interface MutationService<
 /**
  * Configuration options for creating a mutation service, excluding the mutation function itself.
  */
-export type MutationServiceOptions<
+export type MutationHandleOptions<
   TData = unknown,
   TError = Error,
   TVariables = void,
@@ -95,8 +95,8 @@ export interface CreateUntrackedMutation {
     // The asynchronous function that performs the mutation.
     mutationFn: MutationFunction<TData, TVariables>,
     // Optional configuration for behavior like retry or lifecycle hooks.
-    options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
-  ): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    options?: MutationHandleOptions<TData, TError, TVariables, TOnMutateResult>
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 
 /**
@@ -106,13 +106,13 @@ export interface CreateUntrackedMutation {
  * options only describe how the facade should derive dependency values and when it should
  * invalidate matching tracked queries after the mutation lifecycle settles.
  */
-export interface TrackedMutationServiceOptions<
+export interface TrackedMutationHandleOptions<
   TDeps extends TrackedDependencyRecord = TrackedDependencyRecord,
   TData = unknown,
   TError = Error,
   TVariables = void,
   TOnMutateResult = unknown,
-> extends MutationServiceOptions<TData, TError, TVariables, TOnMutateResult> {
+> extends MutationHandleOptions<TData, TError, TVariables, TOnMutateResult> {
   // Optional dependency keys used by the default variable reader.
   dependencyKeys?: readonly (keyof TDeps & string)[];
   // Optional custom resolver when mutation variables do not expose dependency fields directly.
@@ -135,8 +135,8 @@ export interface CreateMutation {
     TOnMutateResult = unknown,
   >(
     mutationFn: MutationFunction<TData, TVariables>,
-    options?: TrackedMutationServiceOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
-  ): MutationService<TData, TError, TVariables, TOnMutateResult>;
+    options?: TrackedMutationHandleOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 
 /**
@@ -151,9 +151,9 @@ export function setupMutation(queryClient: QueryClient): CreateUntrackedMutation
     TOnMutateResult = unknown,
   >(
     mutationFn: MutationFunction<TData, TVariables>,
-    options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
-  ): MutationService<TData, TError, TVariables, TOnMutateResult> {
-    return createMutationService(queryClient, mutationFn, options);
+    options?: MutationHandleOptions<TData, TError, TVariables, TOnMutateResult>
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult> {
+    return createMutationHandle(queryClient, mutationFn, options);
   };
 }
 
@@ -177,8 +177,8 @@ export function setupTrackedMutation(
     TOnMutateResult = unknown,
   >(
     mutationFn: MutationFunction<TData, TVariables>,
-    options?: TrackedMutationServiceOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
-  ): MutationService<TData, TError, TVariables, TOnMutateResult> {
+    options?: TrackedMutationHandleOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult> {
     // Split tracked-only options from the underlying TanStack mutation observer options.
     const {
       dependencyKeys,
@@ -187,8 +187,8 @@ export function setupTrackedMutation(
       resolveDependencies,
       ...mutationOptions
     } = options ?? {};
-    // Reuse the normal mutation service so snapshots and subscription behavior stay identical.
-    const service = createMutationService(queryClient, mutationFn, mutationOptions);
+    // Reuse the normal mutation handle so snapshots and subscription behavior stay identical.
+    const handle = createMutationHandle(queryClient, mutationFn, mutationOptions);
     // The paired helper injects dependency keys here, while standalone tracked mutations can
     // still provide them directly or bypass them with a custom resolver.
     const resolvedDependencyKeys = (dependencyKeys ?? defaultDependencyKeys);
@@ -220,12 +220,12 @@ export function setupTrackedMutation(
     };
 
     return {
-      ...service,
+      ...handle,
       mutate: async (variables, mutateOptions) => {
         try {
           // Let TanStack finish the mutation first so its own callbacks and state machine remain
           // authoritative. The facade only coordinates the follow-up invalidation.
-          const result = await service.mutate(variables, mutateOptions);
+          const result = await handle.mutate(variables, mutateOptions);
 
           if (invalidateOn === 'success' || invalidateOn === 'settled') {
             await invalidateTrackedQueries(variables);
@@ -252,9 +252,9 @@ export function setupTrackedMutation(
 /**
  * Internal helper to transform a raw Tanstack mutation result into our public snapshot format.
  */
-function toMutationServiceSnapshot<TData, TError, TVariables, TOnMutateResult>(
+function toMutationHandleSnapshot<TData, TError, TVariables, TOnMutateResult>(
   result: MutationObserverResult<TData, TError, TVariables, TOnMutateResult>
-): MutationServiceSnapshot<TData, TError, TVariables> {
+): MutationHandleSnapshot<TData, TError, TVariables> {
   // Extract and return the relevant fields for the UI or other services.
   return {
     data: result.data,
@@ -268,7 +268,7 @@ function toMutationServiceSnapshot<TData, TError, TVariables, TOnMutateResult>(
   };
 }
 
-function createMutationService<
+function createMutationHandle<
   TData = unknown,
   TError = Error,
   TVariables = void,
@@ -276,8 +276,8 @@ function createMutationService<
 >(
   queryClient: QueryClient,
   mutationFn: MutationFunction<TData, TVariables>,
-  options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
-): MutationService<TData, TError, TVariables, TOnMutateResult> {
+  options?: MutationHandleOptions<TData, TError, TVariables, TOnMutateResult>
+): MutationHandle<TData, TError, TVariables, TOnMutateResult> {
   // Keep the original mutation implementation in one place so tracked and untracked mutations
   // always expose the same observer-backed runtime behavior.
   const observer = new MutationObserver<TData, TError, TVariables, TOnMutateResult>(queryClient, {
@@ -286,10 +286,10 @@ function createMutationService<
   });
 
   return {
-    getSnapshot: () => toMutationServiceSnapshot(observer.getCurrentResult()),
+    getSnapshot: () => toMutationHandleSnapshot(observer.getCurrentResult()),
     subscribe: (listener) =>
       observer.subscribe((result) => {
-        listener(toMutationServiceSnapshot(result));
+        listener(toMutationHandleSnapshot(result));
       }),
     mutate: (variables, mutateOptions) => observer.mutate(variables, mutateOptions),
     reset: () => observer.reset(),

package/src/provider.ts

@@ -8,8 +8,8 @@ import {
 import {
   type CreateMutation,
   type CreateUntrackedMutation,
-  type MutationService,
-  type TrackedMutationServiceOptions,
+  type MutationHandle,
+  type TrackedMutationHandleOptions,
   setupMutation,
   setupTrackedMutation,
 } from './mutation.js';
@@ -29,7 +29,7 @@ export interface CreateMutationWithDefaults<TDependencyKey extends string> {
   <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(
     mutationFn: MutationFunction<TData, TVariables>,
     options?: Omit<
-      TrackedMutationServiceOptions<
+      TrackedMutationHandleOptions<
         Record<TDependencyKey, TrackedDependencyValue>,
         TData,
         TError,
@@ -38,7 +38,7 @@ export interface CreateMutationWithDefaults<TDependencyKey extends string> {
       >,
       'dependencyKeys'
     >
-  ): MutationService<TData, TError, TVariables, TOnMutateResult>;
+  ): MutationHandle<TData, TError, TVariables, TOnMutateResult>;
 }
 
 /**
@@ -54,13 +54,13 @@ export interface CreateQueryAndMutation {
  * Defines the public API for the query manager facade.
  */
 export interface QueryManager {
-  // Factory for creating a dependency-tracked mutation service within the context of this provider.
+  // Factory for creating a dependency-tracked mutation handle within the context of this provider.
   createMutation: CreateMutation;
   // Factory for creating a dependency-tracked query handle within the context of this provider.
   createQuery: CreateQuery;
   // Factory for creating an untracked query handle within the context of this provider.
   createUntrackedQuery: CreateUntrackedQuery;
-  // Factory for creating an untracked mutation service within the context of this provider.
+  // Factory for creating an untracked mutation handle within the context of this provider.
   createUntrackedMutation: CreateUntrackedMutation;
   // Convenience helper that shares dependency keys between tracked queries and mutations.
   createQueryAndMutation: CreateQueryAndMutation;
@@ -126,7 +126,7 @@ export function setupQueryManager(queryClient: QueryClient): QueryManager {
       > = <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(
         mutationFn: MutationFunction<TData, TVariables>,
         options?: Omit<
-          TrackedMutationServiceOptions<
+          TrackedMutationHandleOptions<
             Record<TDependencyKeys[number], TrackedDependencyValue>,
             TData,
             TError,

package/src/react/__tests__/use-mutation-handle.spec.tsx

@@ -0,0 +1,107 @@
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { QueryClient } from '@tanstack/query-core';
+
+import { setupMutation } from '../../mutation.js';
+import { useMutationHandle } from '../hooks/use-mutation-handle.js';
+
+import type { MutationHandle, MutationHandleSnapshot } from '../../mutation.js';
+
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+
+describe('useMutationHandle', () => {
+  let container: HTMLDivElement;
+
+  beforeAll(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+  });
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+  });
+
+  afterEach(() => {
+    container.remove();
+  });
+
+  it('renders the latest mutation snapshot', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { mutations: { retry: 0 } } });
+    const createMutation = setupMutation(queryClient);
+    const mutationFn = jest.fn((_payload: { name: string }) =>
+      Promise.resolve({ ok: true as const })
+    );
+    const handle = createMutation(mutationFn);
+    const statuses: string[] = [];
+
+    const Consumer = () => {
+      const snapshot = useMutationHandle(handle);
+      statuses.push(snapshot.status);
+
+      return <span>{snapshot.status}</span>;
+    };
+
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(<Consumer />);
+    });
+
+    expect(container.textContent).toBe('idle');
+
+    await act(async () => {
+      await handle.mutate({ name: 'Ada' });
+    });
+
+    expect(container.textContent).toBe('success');
+    expect(statuses).toContain('idle');
+    expect(statuses).toContain('pending');
+    expect(statuses).toContain('success');
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+
+  it('cleans up the store subscription on unmount', async () => {
+    const snapshot: MutationHandleSnapshot<{ ok: true }, Error, void> = {
+      data: { ok: true },
+      error: null,
+      status: 'success',
+      variables: undefined,
+      isError: false,
+      isIdle: false,
+      isPending: false,
+      isSuccess: true,
+    };
+    const unsubscribe = jest.fn();
+    const handle: MutationHandle<{ ok: true }, Error, void> = {
+      getSnapshot: () => snapshot,
+      subscribe: jest.fn(() => unsubscribe),
+      mutate: jest.fn(async () => ({ ok: true as const })),
+      reset: jest.fn(),
+      unsafe_getResult: jest.fn(),
+    };
+
+    const root = createRoot(container);
+
+    const Consumer = () => {
+      useMutationHandle(handle);
+      return <span>ready</span>;
+    };
+
+    await act(async () => {
+      root.render(<Consumer />);
+    });
+
+    expect(handle.subscribe).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      root.unmount();
+    });
+
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});

package/src/react/hooks/index.ts

@@ -1 +1,2 @@
 export { useQueryHandle } from './use-query-handle.js';
+export { useMutationHandle } from './use-mutation-handle.js';

package/src/react/hooks/use-mutation-handle.ts

@@ -0,0 +1,98 @@
+// Import the React hooks needed to memoize callbacks, hold mutable cache state,
+// and connect an external store to React rendering.
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+
+// Import the mutation-handle contract and the stable snapshot shape the hook returns.
+import type { MutationHandle, MutationHandleSnapshot } from '../../mutation.js';
+// Describe the no-argument listener shape expected by useSyncExternalStore.
+type Listener = () => void;
+
+// Store one cached snapshot together with the store version it belongs to.
+type SnapshotCacheEntry<TData, TError, TVariables> = {
+  // Hold the snapshot returned by the mutation handle for this version.
+  snapshot: MutationHandleSnapshot<TData, TError, TVariables>;
+  // Track which subscription version produced the cached snapshot.
+  version: number;
+};
+
+// Subscribe a React component to a MutationHandle and return its latest snapshot.
+export function useMutationHandle<TData, TError = Error, TVariables = void>(
+  // Receive the external mutation handle instance to subscribe to.
+  mutationHandle: MutationHandle<TData, TError, TVariables>
+) {
+  // Count store notifications so we can tell when our cached snapshot is stale.
+  const snapshotVersionRef = useRef(0);
+  // Cache one client-side snapshot per observed version to keep getSnapshot stable.
+  const snapshotCacheRef = useRef<SnapshotCacheEntry<TData, TError, TVariables> | null>(null);
+  // Cache the server snapshot separately for the useSyncExternalStore SSR fallback.
+  const serverSnapshotCacheRef = useRef<MutationHandleSnapshot<TData, TError, TVariables> | null>(
+    null
+  );
+
+  // Create the subscribe function expected by useSyncExternalStore.
+  const subscribe = useCallback(
+    // React passes a listener that must run whenever the external store changes.
+    (listener: Listener) =>
+      // Forward the subscription to the mutation handle.
+      mutationHandle.subscribe(() => {
+        // Bump the version so later reads know the previous cache is outdated.
+        snapshotVersionRef.current += 1;
+        // Drop the cached client snapshot because the store just changed.
+        snapshotCacheRef.current = null;
+        // Drop the cached server snapshot for the same reason.
+        serverSnapshotCacheRef.current = null;
+        // Notify React that it should read a fresh snapshot.
+        listener();
+      }),
+    // Recreate the subscription function only when the handle instance changes.
+    [mutationHandle]
+  );
+
+  // Read the current client snapshot in a referentially stable way for React.
+  const getSnapshot = useCallback(() => {
+    // Read the latest store version number.
+    const version = snapshotVersionRef.current;
+    // Read the last cached client snapshot, if there is one.
+    const cachedSnapshot = snapshotCacheRef.current;
+
+    // Reuse the cached snapshot when it was produced for the current version.
+    if (cachedSnapshot && cachedSnapshot.version === version) {
+      // Return the cached snapshot so repeated reads in the same render stay stable.
+      return cachedSnapshot.snapshot;
+    }
+
+    // Ask the mutation handle for the latest snapshot because the cache is empty or stale.
+    const snapshot = mutationHandle.getSnapshot();
+    // Store the new snapshot together with the version it belongs to.
+    snapshotCacheRef.current = {
+      snapshot,
+      version,
+    };
+
+    // Return the freshly read snapshot to React.
+    return snapshot;
+  }, [mutationHandle]);
+
+  // Read the server snapshot used by React during SSR or hydration fallback paths.
+  const getServerSnapshot = useCallback(() => {
+    // Read the cached server snapshot, if one was stored earlier.
+    const cachedSnapshot = serverSnapshotCacheRef.current;
+
+    // Reuse the cached server snapshot to keep server reads stable.
+    if (cachedSnapshot) {
+      // Return the cached server snapshot directly.
+      return cachedSnapshot;
+    }
+
+    // Ask the mutation handle for a snapshot because no server cache exists yet.
+    const snapshot = mutationHandle.getSnapshot();
+    // Cache that snapshot for the next server read.
+    serverSnapshotCacheRef.current = snapshot;
+
+    // Return the freshly read server snapshot.
+    return snapshot;
+  }, [mutationHandle]);
+
+  // Let React subscribe to the external store and read snapshots through the callbacks above.
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/react/index.ts

@@ -1 +1 @@
-export { useQueryHandle } from './hooks/index.js';
+export { useQueryHandle, useMutationHandle } from './hooks/index.js';