@veams/status-quo-query 0.10.0 → 0.12.0

package/src/query.ts

@@ -36,9 +36,9 @@ export type QueryFetchStatus = FetchStatus;
 export type QueryStatus = TanstackQueryStatus;
 
 /**
- * Represents a stable snapshot of the query service's state.
+ * Represents a stable snapshot of one query handle's state.
  */
-export interface QueryServiceSnapshot<TData, TError> {
+export interface QueryHandleSnapshot<TData, TError> {
   // The data retrieved from a successful query.
   data: TData | undefined;
   // The error object if the query failed.
@@ -57,6 +57,14 @@ export interface QueryServiceSnapshot<TData, TError> {
   isSuccess: boolean;
 }
 
+/**
+ * Represents the lightweight data/error read model for one query handle.
+ */
+export interface QueryHandleData<TData, TError> {
+  data: TData | undefined;
+  error: TError | null;
+}
+
 /**
  * Defines a subset of query state containing only the status and fetch status.
  */
@@ -66,15 +74,15 @@ export interface QueryMetaState {
 }
 
 /**
- * Defines the public API for a query service.
+ * Defines the public API for a query handle.
  */
-export interface QueryService<TData, TError> {
+export interface QueryHandle<TData, TError> {
   // Returns the current state snapshot of the query.
-  getSnapshot: () => QueryServiceSnapshot<TData, TError>;
+  getSnapshot: () => QueryHandleSnapshot<TData, TError>;
   // Subscribes a listener to state changes; returns an unsubscribe function.
-  subscribe: (listener: (snapshot: QueryServiceSnapshot<TData, TError>) => void) => () => void;
+  subscribe: (listener: (snapshot: QueryHandleSnapshot<TData, TError>) => void) => () => void;
   // Manually triggers a refetch of this query.
-  refetch: (options?: RefetchOptions) => Promise<QueryServiceSnapshot<TData, TError>>;
+  refetch: (options?: RefetchOptions) => Promise<QueryHandleSnapshot<TData, TError>>;
   // Marks this specific query as invalid in the cache to trigger a refetch if active.
   invalidate: (options?: QueryInvalidateOptions) => Promise<void>;
   // Escape hatch: provides direct access to the underlying Tanstack Query observer result.
@@ -93,14 +101,14 @@ type QueryDependencyDerivedOptions<TQueryKey extends QueryKey = QueryKey> = {
   queryKey?: TQueryKey;
 };
 
-type QueryServiceRuntimeOptions<
+type QueryHandleRuntimeOptions<
   TQueryFnData = unknown,
   TError = Error,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > = Omit<
-  QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
+  QueryHandleOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
   'dependsOn'
 >;
 
@@ -108,9 +116,9 @@ export type QueryDependencyTuple<
   TSources extends readonly unknown[],
   TQueryKey extends QueryKey = QueryKey,
 > = readonly [
-  sources: { readonly [K in keyof TSources]: QueryService<TSources[K], Error> },
+  sources: { readonly [K in keyof TSources]: QueryHandle<TSources[K], Error> },
   deriveOptions: (
-    sourceSnapshots: { readonly [K in keyof TSources]: QueryServiceSnapshot<TSources[K], Error> }
+    sourceSnapshots: { readonly [K in keyof TSources]: QueryHandleSnapshot<TSources[K], Error> }
   ) => QueryDependencyDerivedOptions<TQueryKey>,
 ];
 
@@ -131,15 +139,15 @@ export interface CreateUntrackedQuery {
     // The asynchronous function that performs the data fetch.
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
     // Optional configuration for behavior like staleness, retry, and refetching.
-    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
-  ): QueryService<TData, TError>;
+    options?: QueryHandleOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
+  ): QueryHandle<TData, TError>;
 }
 
 /**
  * Function signature for the default query factory that derives dependencies from the final
  * query-key segment.
  *
- * The tracked query handle deliberately stays API-compatible with the normal query service.
+ * The tracked query handle deliberately stays API-compatible with the normal query handle.
  * The only extra behavior is invisible: dependency registration and on-demand re-registration.
  */
 export interface CreateQuery {
@@ -154,14 +162,14 @@ export interface CreateQuery {
   >(
     queryKey: TQueryKey,
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
-  ): QueryService<TData, TError>;
+    options?: QueryHandleOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
+  ): QueryHandle<TData, TError>;
 }
 
 /**
- * Configuration options for creating a query service, excluding function and key.
+ * Configuration options for creating a query handle, excluding function and key.
  */
-export type QueryServiceOptions<
+export type QueryHandleOptions<
   TQueryFnData = unknown,
   TError = Error,
   TData = TQueryFnData,
@@ -179,7 +187,7 @@ export type QueryServiceOptions<
  * Extracts and maps status and fetchStatus to our QueryMetaState interface.
  */
 export function toQueryMetaState<TData, TError>(
-  snapshot: Pick<QueryServiceSnapshot<TData, TError>, 'fetchStatus' | 'status'>
+  snapshot: Pick<QueryHandleSnapshot<TData, TError>, 'fetchStatus' | 'status'>
 ): QueryMetaState {
   // Return a simplified state object for UI or other services.
   return {
@@ -188,6 +196,18 @@ export function toQueryMetaState<TData, TError>(
   };
 }
 
+/**
+ * Extracts only data and error from a query snapshot.
+ */
+export function toQueryHandleData<TData, TError>(
+  snapshot: Pick<QueryHandleSnapshot<TData, TError>, 'data' | 'error'>
+): QueryHandleData<TData, TError> {
+  return {
+    data: snapshot.data,
+    error: snapshot.error,
+  };
+}
+
 /**
  * Helper function to check if the query is in its initial loading state.
  */
@@ -200,7 +220,7 @@ export function isQueryLoading(query: QueryMetaState): boolean {
  * Prepares the query factory by binding it to a specific QueryClient instance.
  */
 export function setupQuery(queryClient: QueryClient): CreateUntrackedQuery {
-  // Returns the actual factory function for creating individual query services.
+  // Returns the actual factory function for creating individual query handles.
   return function createQuery<
     TSources extends readonly unknown[] = [],
     TQueryFnData = unknown,
@@ -211,16 +231,16 @@ export function setupQuery(queryClient: QueryClient): CreateUntrackedQuery {
   >(
     queryKey: TQueryKey,
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
-  ): QueryService<TData, TError> {
-    const { dependsOn, runtimeOptions } = splitQueryServiceOptions(options);
-    const service = createQueryService(queryClient, queryKey, queryFn, runtimeOptions);
+    options?: QueryHandleOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
+  ): QueryHandle<TData, TError> {
+    const { dependsOn, runtimeOptions } = splitQueryHandleOptions(options);
+    const handle = createQueryHandle(queryClient, queryKey, queryFn, runtimeOptions);
 
     if (!dependsOn) {
-      return service.service;
+      return handle.handle;
     }
 
-    return bindQueryDependencies(service, queryKey, dependsOn);
+    return bindQueryDependencies(handle, queryKey, dependsOn);
   };
 }
 
@@ -249,33 +269,33 @@ export function setupTrackedQuery(
   >(
     queryKey: TQueryKey,
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
-  ): QueryService<TData, TError> {
-    const { dependsOn, runtimeOptions } = splitQueryServiceOptions(options);
-    // Reuse the same core query service implementation as the untracked API.
-    const service = createQueryService(queryClient, queryKey, queryFn, runtimeOptions);
+    options?: QueryHandleOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
+  ): QueryHandle<TData, TError> {
+    const { dependsOn, runtimeOptions } = splitQueryHandleOptions(options);
+    // Reuse the same core query-handle implementation as the untracked API.
+    const handle = createQueryHandle(queryClient, queryKey, queryFn, runtimeOptions);
     // We only need re-registration on the transition from zero to one subscribers.
     let subscriberCount = 0;
 
     // Register the current query hash immediately so future tracked mutations can find it.
     trackingRegistry.register(
-      service.observer.getCurrentQuery().queryHash,
-      extractTrackedDependencies(service.getCurrentQueryKey())
+      handle.observer.getCurrentQuery().queryHash,
+      extractTrackedDependencies(handle.getCurrentQueryKey())
     );
 
     const applyTrackedDerivedState = (derivedOptions: QueryDependencyDerivedOptions<TQueryKey>) => {
-      const previousQueryHash = service.observer.getCurrentQuery().queryHash;
+      const previousQueryHash = handle.observer.getCurrentQuery().queryHash;
 
-      service.setDerivedState(derivedOptions);
+      handle.setDerivedState(derivedOptions);
 
-      const nextQueryHash = service.observer.getCurrentQuery().queryHash;
+      const nextQueryHash = handle.observer.getCurrentQuery().queryHash;
 
       if (nextQueryHash === previousQueryHash) {
         return;
       }
 
       trackingRegistry.unregister(previousQueryHash);
-      trackingRegistry.register(nextQueryHash, extractTrackedDependencies(service.getCurrentQueryKey()));
+      trackingRegistry.register(nextQueryHash, extractTrackedDependencies(handle.getCurrentQueryKey()));
     };
 
     const dependencyController = dependsOn
@@ -291,9 +311,9 @@ export function setupTrackedQuery(
       // the same mechanism TanStack uses internally when a query gets recreated after GC.
       const liveQuery = queryClient.getQueryCache().build(
         queryClient,
-        service.getCurrentObserverOptions()
+        handle.getCurrentObserverOptions()
       );
-      const liveDependencies = extractTrackedDependencies(service.getCurrentQueryKey());
+      const liveDependencies = extractTrackedDependencies(handle.getCurrentQueryKey());
 
       // Re-register only when TanStack has recreated the query and the registry has already
       // cleaned up the previous hash. This keeps the edge-case handling cheap in the common case.
@@ -303,12 +323,12 @@ export function setupTrackedQuery(
     };
 
     return {
-      ...service.service,
+      ...handle.handle,
       refetch: async (refetchOptions) => {
         await dependencyController?.evaluateForRefetch();
         // Refetch is one of the two explicit reactivation paths agreed on in the design.
         ensureRegistered();
-        return service.service.refetch(refetchOptions);
+        return handle.handle.refetch(refetchOptions);
       },
       subscribe: (listener) => {
         // The first active subscriber is the other reactivation path. Re-running registration
@@ -320,7 +340,7 @@ export function setupTrackedQuery(
 
         subscriberCount += 1;
 
-        const unsubscribe = service.service.subscribe(listener);
+        const unsubscribe = handle.handle.subscribe(listener);
 
         return () => {
           // Keep the counter bounded so accidental double-unsubscribe cannot push it negative.
@@ -338,10 +358,10 @@ export function setupTrackedQuery(
 /**
  * Internal helper to transform a raw Tanstack query result into our public snapshot format.
  */
-function toQueryServiceSnapshot<TData, TError>(
+function toQueryHandleSnapshot<TData, TError>(
   result: QueryObserverResult<TData, TError>
-): QueryServiceSnapshot<TData, TError> {
-  // Extract and return the relevant fields for the UI or other services.
+): QueryHandleSnapshot<TData, TError> {
+  // Extract and return the relevant fields for the UI or other handle consumers.
   return {
     data: result.data,
     error: result.error,
@@ -354,7 +374,7 @@ function toQueryServiceSnapshot<TData, TError>(
   };
 }
 
-function createQueryService<
+function createQueryHandle<
   TQueryFnData = unknown,
   TError = Error,
   TData = TQueryFnData,
@@ -364,12 +384,12 @@ function createQueryService<
   queryClient: QueryClient,
   queryKey: TQueryKey,
   queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-  options?: QueryServiceRuntimeOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  options?: QueryHandleRuntimeOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
 ): {
   // Expose the observer internally so tracked queries can access the current query hash.
   observer: QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
-  // Preserve the public query-service shape for all callers.
-  service: QueryService<TData, TError>;
+  // Preserve the public query-handle shape for all callers.
+  handle: QueryHandle<TData, TError>;
   getCurrentObserverOptions: () => QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey> &
     QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
   getCurrentQueryKey: () => TQueryKey;
@@ -401,14 +421,14 @@ function createQueryService<
     getCurrentObserverOptions,
     getCurrentQueryKey: () => resolvedQueryKey,
     setDerivedState,
-    service: {
-      getSnapshot: () => toQueryServiceSnapshot(observer.getCurrentResult()),
+    handle: {
+      getSnapshot: () => toQueryHandleSnapshot(observer.getCurrentResult()),
       subscribe: (listener) =>
         observer.subscribe((result) => {
-          listener(toQueryServiceSnapshot(result));
+          listener(toQueryHandleSnapshot(result));
         }),
       refetch: async (refetchOptions) =>
-        toQueryServiceSnapshot(await observer.refetch(refetchOptions)),
+        toQueryHandleSnapshot(await observer.refetch(refetchOptions)),
       invalidate: (invalidateOptions) =>
         queryClient.invalidateQueries(
           {
@@ -433,24 +453,24 @@ function bindQueryDependencies<
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 >(
-  queryService: ReturnType<
-    typeof createQueryService<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  queryHandle: ReturnType<
+    typeof createQueryHandle<TQueryFnData, TError, TData, TQueryData, TQueryKey>
   >,
   queryKey: TQueryKey,
   dependsOn: QueryDependencyTuple<TSources, TQueryKey>
-): QueryService<TData, TError> {
+): QueryHandle<TData, TError> {
   const dependencyController = createDependencyController(
     queryKey,
-    queryService.setDerivedState,
+    queryHandle.setDerivedState,
     dependsOn
   );
   let subscriberCount = 0;
 
   return {
-    ...queryService.service,
+    ...queryHandle.handle,
     refetch: async (refetchOptions) => {
       await dependencyController.evaluateForRefetch();
-      return queryService.service.refetch(refetchOptions);
+      return queryHandle.handle.refetch(refetchOptions);
     },
     subscribe: (listener) => {
       if (subscriberCount === 0) {
@@ -459,7 +479,7 @@ function bindQueryDependencies<
 
       subscriberCount += 1;
 
-      const unsubscribe = queryService.service.subscribe(listener);
+      const unsubscribe = queryHandle.handle.subscribe(listener);
 
       return () => {
         subscriberCount = Math.max(0, subscriberCount - 1);
@@ -474,10 +494,6 @@ function bindQueryDependencies<
 
 function createDependencyController<
   TSources extends readonly unknown[] = [],
-  TQueryFnData = unknown,
-  TError = Error,
-  TData = TQueryFnData,
-  TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 >(
   baseQueryKey: TQueryKey,
@@ -555,7 +571,7 @@ function createDependencyController<
   };
 }
 
-function splitQueryServiceOptions<
+function splitQueryHandleOptions<
   TQueryFnData = unknown,
   TError = Error,
   TData = TQueryFnData,
@@ -563,10 +579,10 @@ function splitQueryServiceOptions<
   TQueryKey extends QueryKey = QueryKey,
   TSources extends readonly unknown[] = [],
 >(
-  options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
+  options?: QueryHandleOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
 ): {
   dependsOn?: QueryDependencyTuple<TSources, TQueryKey>;
-  runtimeOptions: QueryServiceRuntimeOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> | undefined;
+  runtimeOptions: QueryHandleRuntimeOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> | undefined;
 } {
   if (options === undefined) {
     return {
@@ -592,7 +608,7 @@ function toQueryOptions<
 >(
   queryKey: TQueryKey,
   queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-  options?: QueryServiceRuntimeOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  options?: QueryHandleRuntimeOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
 ): QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey> &
   QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> {
   // Centralize option assembly so both normal queries and tracked queries build observers and

package/src/react/__tests__/use-query-handle.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 { useQueryHandle } from '../hooks/use-query-handle.js';
+
+import type { QueryHandle, QueryHandleSnapshot } from '../../query.js';
+
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+
+describe('useQueryHandle', () => {
+  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 = useQueryHandle(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: QueryHandleSnapshot<{ 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: QueryHandle<{ 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 = () => {
+      useQueryHandle(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 { useQueryHandle } from './use-query-handle.js';

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

@@ -0,0 +1,96 @@
+// 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-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 handle for this version.
+  snapshot: QueryHandleSnapshot<TData, TError>;
+  // Track which subscription version produced the cached snapshot.
+  version: number;
+};
+
+// 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<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 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.
+        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.
+    [queryHandle]
+  );
+
+  // 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 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,
+      version,
+    };
+
+    // Return the freshly read snapshot to React.
+    return snapshot;
+  }, [queryHandle]);
+
+  // 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 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;
+  }, [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

@@ -0,0 +1 @@
+export { useQueryHandle } 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",

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"}