@veams/status-quo-query 0.10.0 → 0.11.0

package/README.md

@@ -8,6 +8,25 @@ TanStack Query service helpers with a small subscribable surface that fits natur
 npm install @veams/status-quo-query @tanstack/query-core
 ```
 
+React bindings are available through an optional peer dependency:
+
+```bash
+npm install react
+```
+
+## Mental Model
+
+Status Quo Query deliberately keeps the public surface small:
+
+- `QueryService<TData, TError>` is the read handle for one query.
+- `MutationService<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.
+
+That keeps the package usable in service code, state handlers, and React components without changing the core query or mutation API.
+
 ## Package Exports
 
 Root exports:
@@ -49,6 +68,7 @@ Subpath exports:
 - `@veams/status-quo-query/provider`
 - `@veams/status-quo-query/query`
 - `@veams/status-quo-query/mutation`
+- `@veams/status-quo-query/react`
 
 ## Quickstart
 
@@ -109,6 +129,86 @@ await userQuery.refetch();
 await userQuery.invalidate({ refetchType: 'none' });
 ```
 
+## React Bindings
+
+The React entrypoint exposes `useQuerySubscription(...)` and keeps `react` optional unless you
+import `@veams/status-quo-query/react`.
+
+```tsx
+import { useQuerySubscription } from '@veams/status-quo-query/react';
+import type { QueryService } from '@veams/status-quo-query';
+
+function ProductName({ query }: { query: QueryService<{ name: string }, Error> }) {
+  const snapshot = useQuerySubscription(query);
+
+  return <span>{snapshot.data?.name ?? 'loading'}</span>;
+}
+```
+
+Use the hook when a component should subscribe directly to a query service and render from its latest snapshot. Keep mapping at the component level:
+
+- read `data`, `status`, `fetchStatus`, and flags like `isPending` from the snapshot
+- 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
+
+## Status Quo Integration
+
+The same query handle can also feed a `status-quo` handler through `bindSubscribable(...)`.
+
+```ts
+import { NativeStateHandler } from '@veams/status-quo';
+import {
+  toQueryMetaState,
+  type QueryMetaState,
+  type QueryService,
+} from '@veams/status-quo-query';
+
+type Product = {
+  id: string;
+  name: string;
+};
+
+type ProductCardState = {
+  product: Product | undefined;
+  query: QueryMetaState;
+};
+
+type ProductCardActions = {
+  refresh: () => Promise<void>;
+};
+
+export class ProductCardHandler extends NativeStateHandler<ProductCardState, ProductCardActions> {
+  constructor(private readonly productQuery: QueryService<Product, Error>) {
+    super({
+      initialState: {
+        product: productQuery.getSnapshot().data,
+        query: toQueryMetaState(productQuery.getSnapshot()),
+      },
+    });
+
+    this.bindSubscribable(productQuery, (snapshot) => {
+      this.setState(
+        {
+          product: snapshot.data,
+          query: toQueryMetaState(snapshot),
+        },
+        'query:update'
+      );
+    });
+  }
+
+  getActions(): ProductCardActions {
+    return {
+      refresh: async () => {
+        await this.productQuery.refetch();
+      },
+    };
+  }
+}
+```
+
+Use that approach when query state is only one input into a broader UI state model and the handler should remain the view-facing boundary.
+
 ## Why Tracked Invalidation
 
 TanStack Query gives you flexible invalidation primitives, but the application still has to know which keys to invalidate after every mutation. Tracked invalidation moves that bookkeeping into the facade:

package/dist/query.js.map

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

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

@@ -0,0 +1 @@
+export { useQuerySubscription } from './use-query-subscription.js';

package/dist/react/hooks/index.js

@@ -0,0 +1,2 @@
+export { useQuerySubscription } from './use-query-subscription.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/react/hooks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/react/hooks/use-query-subscription.d.ts

@@ -0,0 +1,2 @@
+import type { QueryService, QueryServiceSnapshot } from '../../query.js';
+export declare function useQuerySubscription<TData, TError>(queryService: QueryService<TData, TError>): QueryServiceSnapshot<TData, TError>;

package/dist/react/hooks/use-query-subscription.js

@@ -0,0 +1,73 @@
+// 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 QueryService and return its latest snapshot.
+export function useQuerySubscription(
+// Receive the external query service instance to subscribe to.
+queryService) {
+    // 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 query service.
+    queryService.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 service instance changes.
+    [queryService]);
+    // 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 query service for the latest snapshot because the cache is empty or stale.
+        const snapshot = queryService.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;
+        // Recreate this getter only when the service instance changes.
+    }, [queryService]);
+    // 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 query service for a snapshot because no server cache exists yet.
+        const snapshot = queryService.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]);
+    // Let React subscribe to the external store and read snapshots through the callbacks above.
+    return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+//# sourceMappingURL=use-query-subscription.js.map

package/dist/react/hooks/use-query-subscription.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-query-subscription.js","sourceRoot":"","sources":["../../../src/react/hooks/use-query-subscription.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,oDAAoD;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAelE,gFAAgF;AAChF,MAAM,UAAU,oBAAoB;AAClC,+DAA+D;AAC/D,YAAyC;IAEzC,8EAA8E;IAC9E,MAAM,kBAAkB,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACrC,kFAAkF;IAClF,MAAM,gBAAgB,GAAG,MAAM,CAA2C,IAAI,CAAC,CAAC;IAChF,kFAAkF;IAClF,MAAM,sBAAsB,GAAG,MAAM,CAA6C,IAAI,CAAC,CAAC;IAExF,kEAAkE;IAClE,MAAM,SAAS,GAAG,WAAW;IAC3B,6EAA6E;IAC7E,CAAC,QAAkB,EAAE,EAAE;IACrB,iDAAiD;IACjD,YAAY,CAAC,SAAS,CAAC,GAAG,EAAE;QAC1B,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,6EAA6E;IAC7E,CAAC,YAAY,CAAC,CACf,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,qFAAqF;QACrF,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;QAC5C,kEAAkE;QAClE,gBAAgB,CAAC,OAAO,GAAG;YACzB,QAAQ;YACR,OAAO;SACR,CAAC;QAEF,6CAA6C;QAC7C,OAAO,QAAQ,CAAC;QAChB,+DAA+D;IACjE,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IAEnB,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,2EAA2E;QAC3E,MAAM,QAAQ,GAAG,YAAY,CAAC,WAAW,EAAE,CAAC;QAC5C,gDAAgD;QAChD,sBAAsB,CAAC,OAAO,GAAG,QAAQ,CAAC;QAE1C,2CAA2C;QAC3C,OAAO,QAAQ,CAAC;QAChB,+DAA+D;IACjE,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC;IAEnB,4FAA4F;IAC5F,OAAO,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC;AACzE,CAAC"}

package/dist/react/index.d.ts

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

package/dist/react/index.js

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

package/dist/react/index.js.map

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

package/eslint.config.mjs

@@ -6,8 +6,8 @@ import globals from 'globals';
 import tseslint from 'typescript-eslint';
 
 const packageRoot = fileURLToPath(new URL('.', import.meta.url));
-const sourceFiles = ['src/**/*.ts'];
-const testFiles = ['src/**/*.{spec,test}.ts', 'src/**/__tests__/**/*.ts'];
+const sourceFiles = ['src/**/*.{ts,tsx}'];
+const testFiles = ['src/**/*.{spec,test}.{ts,tsx}', 'src/**/__tests__/**/*.{ts,tsx}'];
 
 export default defineConfig(
   {
@@ -20,9 +20,13 @@ export default defineConfig(
     files: sourceFiles,
     languageOptions: {
       globals: {
+        ...globals.browser,
         ...globals.node,
       },
       parserOptions: {
+        ecmaFeatures: {
+          jsx: true,
+        },
         project: './tsconfig.eslint.json',
         tsconfigRootDir: packageRoot,
       },
@@ -46,5 +50,12 @@ export default defineConfig(
         ...globals.jest,
       },
     },
+    rules: {
+      '@typescript-eslint/no-unsafe-argument': 'off',
+      '@typescript-eslint/no-unsafe-assignment': 'off',
+      '@typescript-eslint/no-unsafe-member-access': 'off',
+      '@typescript-eslint/no-unsafe-return': 'off',
+      '@typescript-eslint/require-await': 'off',
+    },
   }
 );

package/jest.config.cjs

@@ -1,5 +1,5 @@
 module.exports = {
-  extensionsToTreatAsEsm: ['.ts'],
+  extensionsToTreatAsEsm: ['.ts', '.tsx'],
   transformIgnorePatterns: [],
   transform: {
     '^.+\\.(t|j)sx?$': '@swc/jest',
@@ -18,5 +18,5 @@ module.exports = {
   testMatch: ['**/__tests__/**/?(*.)+(spec|test).[jt]s?(x)'],
   reporters: ['default'],
   moduleFileExtensions: ['mjs', 'js', 'ts', 'jsx', 'tsx'],
-  testEnvironment: 'node',
+  testEnvironment: 'jsdom',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo-query",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "TanStack Query service layer for the VEAMS StatusQuo ecosystem.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -12,6 +12,13 @@
       },
       "require": "./dist/index.js"
     },
+    "./react": {
+      "import": {
+        "types": "./dist/react/index.d.ts",
+        "default": "./dist/react/index.js"
+      },
+      "require": "./dist/react/index.js"
+    },
     "./mutation": {
       "import": {
         "types": "./dist/mutation.d.ts",
@@ -50,12 +57,18 @@
     "check:types": "tsc --skipLibCheck --noEmit",
     "compile": "npm-run-all bundle:ts",
     "lint": "npm run lint:ts",
-    "lint:ts": "eslint --fix \"src/**/*.ts\"",
+    "lint:ts": "eslint --fix \"src/**/*.{ts,tsx}\"",
     "test": "cross-env NODE_ENV=test jest --config jest.config.cjs",
     "release": "npm run build && release-it"
   },
   "peerDependencies": {
-    "@tanstack/query-core": ">=5.0.0"
+    "@tanstack/query-core": ">=5.0.0",
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@swc/core": "1.15.11",
@@ -63,9 +76,14 @@
     "@tanstack/query-core": "5.91.2",
     "@types/jest": "30.0.0",
     "@types/node": "25.2.3",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.0.0",
     "cross-env": "10.1.0",
     "jest": "30.3.0",
+    "jest-environment-jsdom": "30.3.0",
     "npm-run-all": "4.1.5",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
     "release-it": "19.2.4",
     "tslib": "2.8.1",
     "typescript": "5.9.3"

package/src/query.ts

@@ -474,10 +474,6 @@ function bindQueryDependencies<
 
 function createDependencyController<
   TSources extends readonly unknown[] = [],
-  TQueryFnData = unknown,
-  TError = Error,
-  TData = TQueryFnData,
-  TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 >(
   baseQueryKey: TQueryKey,

package/src/react/__tests__/query-subscription.spec.tsx

@@ -0,0 +1,104 @@
+import React, { act } from 'react';
+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 type { QueryService, QueryServiceSnapshot } from '../../query.js';
+
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+
+describe('useQuerySubscription', () => {
+  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 query snapshot', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const createQuery = setupQuery(queryClient);
+    const query = createQuery(['product', 1], jest.fn().mockResolvedValue({ name: 'Ada' }), {
+      enabled: false,
+    });
+    const renderStates: Array<string | undefined> = [];
+
+    const Consumer = () => {
+      const snapshot = useQuerySubscription(query);
+      renderStates.push(snapshot.data?.name);
+
+      return <span>{snapshot.data?.name ?? 'pending'}</span>;
+    };
+
+    const root = createRoot(container);
+
+    await act(async () => {
+      root.render(<Consumer />);
+    });
+
+    expect(container.textContent).toBe('pending');
+
+    await act(async () => {
+      await query.refetch();
+    });
+
+    expect(container.textContent).toBe('Ada');
+    expect(renderStates).toContain(undefined);
+    expect(renderStates).toContain('Ada');
+
+    await act(async () => {
+      root.unmount();
+    });
+  });
+  it('cleans up the store subscription on unmount', async () => {
+    const snapshot: QueryServiceSnapshot<{ name: string }, Error> = {
+      data: { name: 'Ada' },
+      error: null,
+      fetchStatus: 'idle',
+      status: 'success',
+      isError: false,
+      isFetching: false,
+      isPending: false,
+      isSuccess: true,
+    };
+    const unsubscribe = jest.fn();
+    const query: QueryService<{ name: string }, Error> = {
+      getSnapshot: () => snapshot,
+      subscribe: jest.fn(() => unsubscribe),
+      refetch: jest.fn(async () => snapshot),
+      invalidate: jest.fn(async () => undefined),
+      unsafe_getResult: jest.fn(),
+    };
+
+    const root = createRoot(container);
+
+    const Consumer = () => {
+      useQuerySubscription(query);
+      return <span>ready</span>;
+    };
+
+    await act(async () => {
+      root.render(<Consumer />);
+    });
+
+    expect(query.subscribe).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      root.unmount();
+    });
+
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});

package/src/react/hooks/index.ts

@@ -0,0 +1 @@
+export { useQuerySubscription } from './use-query-subscription.js';

package/src/react/hooks/use-query-subscription.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 query service contract and the stable snapshot shape the hook returns.
+import type { QueryService, QueryServiceSnapshot } 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>;
+  // 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>
+) {
+  // 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);
+
+  // 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(() => {
+        // 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 service instance changes.
+    [queryService]
+  );
+
+  // 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 query service for the latest snapshot because the cache is empty or stale.
+    const snapshot = queryService.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;
+    // Recreate this getter only when the service instance changes.
+  }, [queryService]);
+
+  // 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 query service for a snapshot because no server cache exists yet.
+    const snapshot = queryService.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]);
+
+  // Let React subscribe to the external store and read snapshots through the callbacks above.
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/react/index.ts

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

package/tsconfig.eslint.json

@@ -1,7 +1,8 @@
 {
   "extends": "./tsconfig.json",
   "include": [
-    "src/**/*.ts"
+    "src/**/*.ts",
+    "src/**/*.tsx"
   ],
   "exclude": [
     "coverage",

package/tsconfig.json

@@ -4,8 +4,10 @@
     "declaration": true,
     "declarationDir": "dist",
     "esModuleInterop": true,
+    "jsx": "react",
     "lib": [
-      "es2022"
+      "es2022",
+      "dom"
     ],
     "module": "es2022",
     "moduleResolution": "bundler",
@@ -19,7 +21,8 @@
     ]
   },
   "include": [
-    "src/**/*.ts"
+    "src/**/*.ts",
+    "src/**/*.tsx"
   ],
   "exclude": [
     "coverage",