@veams/status-quo-query 0.11.0 → 0.13.0

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/__tests__/{query-subscription.spec.tsx → use-query-handle.spec.tsx}

@@ -3,15 +3,15 @@ import { createRoot } from 'react-dom/client';
 import { QueryClient } from '@tanstack/query-core';
 
 import { setupQuery } from '../../query.js';
-import { useQuerySubscription } from '../hooks/use-query-subscription.js';
+import { useQueryHandle } from '../hooks/use-query-handle.js';
 
-import type { QueryService, QueryServiceSnapshot } from '../../query.js';
+import type { QueryHandle, QueryHandleSnapshot } from '../../query.js';
 
 declare global {
   var IS_REACT_ACT_ENVIRONMENT: boolean;
 }
 
-describe('useQuerySubscription', () => {
+describe('useQueryHandle', () => {
   let container: HTMLDivElement;
 
   beforeAll(() => {
@@ -36,7 +36,7 @@ describe('useQuerySubscription', () => {
     const renderStates: Array<string | undefined> = [];
 
     const Consumer = () => {
-      const snapshot = useQuerySubscription(query);
+      const snapshot = useQueryHandle(query);
       renderStates.push(snapshot.data?.name);
 
       return <span>{snapshot.data?.name ?? 'pending'}</span>;
@@ -63,7 +63,7 @@ describe('useQuerySubscription', () => {
     });
   });
   it('cleans up the store subscription on unmount', async () => {
-    const snapshot: QueryServiceSnapshot<{ name: string }, Error> = {
+    const snapshot: QueryHandleSnapshot<{ name: string }, Error> = {
       data: { name: 'Ada' },
       error: null,
       fetchStatus: 'idle',
@@ -74,7 +74,7 @@ describe('useQuerySubscription', () => {
       isSuccess: true,
     };
     const unsubscribe = jest.fn();
-    const query: QueryService<{ name: string }, Error> = {
+    const query: QueryHandle<{ name: string }, Error> = {
       getSnapshot: () => snapshot,
       subscribe: jest.fn(() => unsubscribe),
       refetch: jest.fn(async () => snapshot),
@@ -85,7 +85,7 @@ describe('useQuerySubscription', () => {
     const root = createRoot(container);
 
     const Consumer = () => {
-      useQuerySubscription(query);
+      useQueryHandle(query);
       return <span>ready</span>;
     };
 

package/src/react/hooks/index.ts

@@ -1 +1,2 @@
-export { useQuerySubscription } from './use-query-subscription.js';
+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/hooks/{use-query-subscription.ts → use-query-handle.ts}

@@ -2,37 +2,37 @@
 // and connect an external store to React rendering.
 import { useCallback, useRef, useSyncExternalStore } from 'react';
 
-// Import the query service contract and the stable snapshot shape the hook returns.
-import type { QueryService, QueryServiceSnapshot } from '../../query.js';
+// Import the query-handle contract and the stable snapshot shape the hook returns.
+import type { QueryHandle, QueryHandleSnapshot } from '../../query.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> = {
-  // Hold the snapshot returned by the query service for this version.
-  snapshot: QueryServiceSnapshot<TData, TError>;
+  // Hold the snapshot returned by the query handle for this version.
+  snapshot: QueryHandleSnapshot<TData, TError>;
   // Track which subscription version produced the cached snapshot.
   version: number;
 };
 
-// Subscribe a React component to a QueryService and return its latest snapshot.
-export function useQuerySubscription<TData, TError>(
-  // Receive the external query service instance to subscribe to.
-  queryService: QueryService<TData, TError>
+// Subscribe a React component to a QueryHandle and return its latest snapshot.
+export function useQueryHandle<TData, TError>(
+  // Receive the external query handle instance to subscribe to.
+  queryHandle: QueryHandle<TData, TError>
 ) {
   // 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> | null>(null);
   // Cache the server snapshot separately for the useSyncExternalStore SSR fallback.
-  const serverSnapshotCacheRef = useRef<QueryServiceSnapshot<TData, TError> | null>(null);
+  const serverSnapshotCacheRef = useRef<QueryHandleSnapshot<TData, TError> | 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 query service.
-      queryService.subscribe(() => {
+      // Forward the subscription to the query handle.
+      queryHandle.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.
@@ -42,8 +42,8 @@ export function useQuerySubscription<TData, TError>(
         // Notify React that it should read a fresh snapshot.
         listener();
       }),
-    // Recreate the subscription function only when the service instance changes.
-    [queryService]
+    // Recreate the subscription function only when the handle instance changes.
+    [queryHandle]
   );
 
   // Read the current client snapshot in a referentially stable way for React.
@@ -59,8 +59,8 @@ export function useQuerySubscription<TData, TError>(
       return cachedSnapshot.snapshot;
     }
 
-    // Ask the query service for the latest snapshot because the cache is empty or stale.
-    const snapshot = queryService.getSnapshot();
+    // Ask the query handle for the latest snapshot because the cache is empty or stale.
+    const snapshot = queryHandle.getSnapshot();
     // Store the new snapshot together with the version it belongs to.
     snapshotCacheRef.current = {
       snapshot,
@@ -69,8 +69,7 @@ export function useQuerySubscription<TData, TError>(
 
     // Return the freshly read snapshot to React.
     return snapshot;
-    // Recreate this getter only when the service instance changes.
-  }, [queryService]);
+  }, [queryHandle]);
 
   // Read the server snapshot used by React during SSR or hydration fallback paths.
   const getServerSnapshot = useCallback(() => {
@@ -83,15 +82,14 @@ export function useQuerySubscription<TData, TError>(
       return cachedSnapshot;
     }
 
-    // Ask the query service for a snapshot because no server cache exists yet.
-    const snapshot = queryService.getSnapshot();
+    // Ask the query handle for a snapshot because no server cache exists yet.
+    const snapshot = queryHandle.getSnapshot();
     // Cache that snapshot for the next server read.
     serverSnapshotCacheRef.current = snapshot;
 
     // Return the freshly read server snapshot.
     return snapshot;
-    // Recreate this getter only when the service instance changes.
-  }, [queryService]);
+  }, [queryHandle]);
 
   // 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 { useQuerySubscription } from './hooks/index.js';
+export { useQueryHandle, useMutationHandle } from './hooks/index.js';

package/dist/query-registry.d.ts

@@ -1,9 +0,0 @@
-import type { QueryService } from './query.js';
-export interface QueryRegistry<TParams, TKey extends readonly unknown[]> {
-    clear: () => void;
-    getKey: (params: TParams) => TKey;
-    name: string;
-    resolve: <TData, TError = Error>(params: TParams, create: (queryKey: TKey) => QueryService<TData, TError>) => QueryService<TData, TError>;
-}
-export declare function createQueryRegistry<TParams, TKey extends readonly unknown[]>(name: string, createKey: (params: TParams) => TKey): QueryRegistry<TParams, TKey>;
-export declare function serializeQueryKey(queryKey: readonly unknown[]): string;

package/dist/query-registry.js

@@ -1,28 +0,0 @@
-import { hashKey } from '@tanstack/query-core';
-export function createQueryRegistry(name, createKey) {
-    const entries = new Map();
-    return {
-        name,
-        clear() {
-            entries.clear();
-        },
-        getKey(params) {
-            return createKey(params);
-        },
-        resolve(params, create) {
-            const queryKey = createKey(params);
-            const cacheKey = serializeQueryKey(queryKey);
-            const existingEntry = entries.get(cacheKey);
-            if (existingEntry) {
-                return existingEntry;
-            }
-            const nextEntry = create(queryKey);
-            entries.set(cacheKey, nextEntry);
-            return nextEntry;
-        },
-    };
-}
-export function serializeQueryKey(queryKey) {
-    return hashKey(queryKey);
-}
-//# sourceMappingURL=query-registry.js.map

package/dist/query-registry.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"query-registry.js","sourceRoot":"","sources":["../src/query-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAc/C,MAAM,UAAU,mBAAmB,CACjC,IAAY,EACZ,SAAoC;IAEpC,MAAM,OAAO,GAAG,IAAI,GAAG,EAA0C,CAAC;IAElE,OAAO;QACL,IAAI;QACJ,KAAK;YACH,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;QACD,MAAM,CAAC,MAAM;YACX,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC;QAC3B,CAAC;QACD,OAAO,CACL,MAAe,EACf,MAAuD;YAEvD,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;YACnC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;YAC7C,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAA4C,CAAC;YAEvF,IAAI,aAAa,EAAE,CAAC;gBAClB,OAAO,aAAa,CAAC;YACvB,CAAC;YAED,MAAM,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;YAEnC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,SAA2C,CAAC,CAAC;YAEnE,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAA4B;IAC5D,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC3B,CAAC"}

package/src/__tests__/query-registry.spec.ts

@@ -1,101 +0,0 @@
-import type { QueryService } from '../query';
-import { createQueryRegistry, serializeQueryKey } from '../query-registry';
-
-describe('createQueryRegistry', () => {
-  it('reuses the same entry for identical params', () => {
-    const registry = createQueryRegistry('branches', (params: { branchId: string }) => [
-      'branch',
-      {
-        deps: {
-          branchId: params.branchId,
-        },
-      },
-    ] as const);
-    const createEntry = jest.fn((queryKey) => ({ queryKey }));
-
-    const firstEntry = registry.resolve({ branchId: 'branch-1' }, createEntry as never);
-    const secondEntry = registry.resolve({ branchId: 'branch-1' }, createEntry as never);
-
-    expect(firstEntry).toBe(secondEntry);
-    expect(createEntry).toHaveBeenCalledTimes(1);
-  });
-
-  it('creates separate entries for different params', () => {
-    const registry = createQueryRegistry('branches', (params: { branchId: string }) => [
-      'branch',
-      {
-        deps: {
-          branchId: params.branchId,
-        },
-      },
-    ] as const);
-    const createEntry = jest.fn((queryKey) => ({ queryKey }));
-
-    const firstEntry = registry.resolve({ branchId: 'branch-1' }, createEntry as never);
-    const secondEntry = registry.resolve({ branchId: 'branch-2' }, createEntry as never);
-
-    expect(firstEntry).not.toBe(secondEntry);
-    expect(createEntry).toHaveBeenCalledTimes(2);
-  });
-
-  it('exposes the generated query key', () => {
-    const registry = createQueryRegistry('branches', (params: { branchId: string }) => [
-      'branch',
-      {
-        deps: {
-          branchId: params.branchId,
-        },
-      },
-    ] as const);
-
-    expect(registry.getKey({ branchId: 'branch-1' })).toEqual([
-      'branch',
-      {
-        deps: {
-          branchId: 'branch-1',
-        },
-      },
-    ]);
-  });
-
-  it('uses TanStack-compatible stable hashing for object keys', () => {
-    const firstKey = ['branch', { deps: { branchId: 'branch-1', companyId: 'company-1' } }] as const;
-    const secondKey = ['branch', { deps: { companyId: 'company-1', branchId: 'branch-1' } }] as const;
-
-    expect(serializeQueryKey(firstKey)).toBe(serializeQueryKey(secondKey));
-  });
-
-  it('infers the query service type from the creator callback', () => {
-    const registry = createQueryRegistry('branches', (params: { branchId: string }) => [
-      'branch',
-      {
-        deps: {
-          branchId: params.branchId,
-        },
-      },
-    ] as const);
-
-    const query = registry.resolve({ branchId: 'branch-1' }, () => {
-      return {
-        getSnapshot: () => ({
-          data: { id: 'branch-1' },
-          error: null,
-          fetchStatus: 'idle',
-          isError: false,
-          isFetching: false,
-          isPending: false,
-          isSuccess: true,
-          status: 'success',
-        }),
-        invalidate: jest.fn(),
-        refetch: jest.fn(),
-        subscribe: jest.fn(),
-        unsafe_getResult: jest.fn(),
-      } as unknown as QueryService<{ id: string }, Error>;
-    });
-
-    const typedQuery: QueryService<{ id: string }, Error> = query;
-
-    expect(typedQuery).toBe(query);
-  });
-});

package/src/query-registry.ts

@@ -1,52 +0,0 @@
-import { hashKey } from '@tanstack/query-core';
-
-import type { QueryService } from './query.js';
-
-export interface QueryRegistry<TParams, TKey extends readonly unknown[]> {
-  clear: () => void;
-  getKey: (params: TParams) => TKey;
-  name: string;
-  resolve: <TData, TError = Error>(
-    params: TParams,
-    create: (queryKey: TKey) => QueryService<TData, TError>
-  ) => QueryService<TData, TError>;
-}
-
-export function createQueryRegistry<TParams, TKey extends readonly unknown[]>(
-  name: string,
-  createKey: (params: TParams) => TKey
-): QueryRegistry<TParams, TKey> {
-  const entries = new Map<string, QueryService<unknown, unknown>>();
-
-  return {
-    name,
-    clear() {
-      entries.clear();
-    },
-    getKey(params) {
-      return createKey(params);
-    },
-    resolve<TData, TError = Error>(
-      params: TParams,
-      create: (queryKey: TKey) => QueryService<TData, TError>
-    ) {
-      const queryKey = createKey(params);
-      const cacheKey = serializeQueryKey(queryKey);
-      const existingEntry = entries.get(cacheKey) as QueryService<TData, TError> | undefined;
-
-      if (existingEntry) {
-        return existingEntry;
-      }
-
-      const nextEntry = create(queryKey);
-
-      entries.set(cacheKey, nextEntry as QueryService<unknown, unknown>);
-
-      return nextEntry;
-    },
-  };
-}
-
-export function serializeQueryKey(queryKey: readonly unknown[]): string {
-  return hashKey(queryKey);
-}