@veams/status-quo-query 0.11.0 → 0.12.0

package/dist/react/hooks/use-query-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 QueryHandle and return its latest snapshot.
+export function useQueryHandle(
+// Receive the external query handle instance to subscribe to.
+queryHandle) {
+    // 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 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);
+}
+//# sourceMappingURL=use-query-handle.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-query-handle.js","sourceRoot":"","sources":["../../../src/react/hooks/use-query-handle.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,oDAAoD;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAelE,+EAA+E;AAC/E,MAAM,UAAU,cAAc;AAC5B,8DAA8D;AAC9D,WAAuC;IAEvC,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,CAA4C,IAAI,CAAC,CAAC;IAEvF,kEAAkE;IAClE,MAAM,SAAS,GAAG,WAAW;IAC3B,6EAA6E;IAC7E,CAAC,QAAkB,EAAE,EAAE;IACrB,gDAAgD;IAChD,WAAW,CAAC,SAAS,CAAC,GAAG,EAAE;QACzB,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,WAAW,CAAC,CACd,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,oFAAoF;QACpF,MAAM,QAAQ,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;QAC3C,kEAAkE;QAClE,gBAAgB,CAAC,OAAO,GAAG;YACzB,QAAQ;YACR,OAAO;SACR,CAAC;QAEF,6CAA6C;QAC7C,OAAO,QAAQ,CAAC;IAClB,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAElB,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,0EAA0E;QAC1E,MAAM,QAAQ,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;QAC3C,gDAAgD;QAChD,sBAAsB,CAAC,OAAO,GAAG,QAAQ,CAAC;QAE1C,2CAA2C;QAC3C,OAAO,QAAQ,CAAC;IAClB,CAAC,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC;IAElB,4FAA4F;IAC5F,OAAO,oBAAoB,CAAC,SAAS,EAAE,WAAW,EAAE,iBAAiB,CAAC,CAAC;AACzE,CAAC"}

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

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

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

@@ -1,73 +1,2 @@
-// 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);
-}
+export { useQueryHandle, useQuerySubscription } from './use-query-handle.js';
 //# sourceMappingURL=use-query-subscription.js.map

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

@@ -1 +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"}
+{"version":3,"file":"use-query-subscription.js","sourceRoot":"","sources":["../../../src/react/hooks/use-query-subscription.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/react/index.d.ts

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

package/dist/react/index.js

@@ -1,2 +1,2 @@
-export { useQuerySubscription } from './hooks/index.js';
+export { useQueryHandle } 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,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo-query",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "TanStack Query service layer for the VEAMS StatusQuo ecosystem.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -39,13 +39,6 @@
         "default": "./dist/provider.js"
       },
       "require": "./dist/provider.js"
-    },
-    "./query-registry": {
-      "import": {
-        "types": "./dist/query-registry.d.ts",
-        "default": "./dist/query-registry.js"
-      },
-      "require": "./dist/query-registry.js"
     }
   },
   "types": "dist/index.d.ts",

package/src/__tests__/provider.spec.ts

@@ -10,6 +10,7 @@ describe('Query Manager API', () => {
     const cancelQueriesSpy = jest.spyOn(queryClient, 'cancelQueries');
     const resetQueriesSpy = jest.spyOn(queryClient, 'resetQueries');
     const removeQueriesSpy = jest.spyOn(queryClient, 'removeQueries');
+    const getQueryStateSpy = jest.spyOn(queryClient, 'getQueryState');
     const fetchUser = jest.fn().mockResolvedValue({ id: 7 });
     const fetchQuerySpy = jest.spyOn(queryClient, 'fetchQuery');
     const manager = setupQueryManager(queryClient);
@@ -17,6 +18,12 @@ describe('Query Manager API', () => {
     manager.setQueryData<{ id: number }>(['user', 42], { id: 42 });
 
     expect(manager.getQueryData<{ id: number }>(['user', 42])).toEqual({ id: 42 });
+    expect(manager.getQueryState(['user', 42])).toEqual(
+      expect.objectContaining({
+        data: { id: 42 },
+        status: 'success',
+      })
+    );
     expect(manager.unsafe_getClient()).toBe(queryClient);
     await expect(
       manager.fetchQuery({
@@ -37,6 +44,7 @@ describe('Query Manager API', () => {
       queryFn: fetchUser,
       staleTime: 60_000,
     });
+    expect(getQueryStateSpy).toHaveBeenCalledWith(['user', 42]);
     expect(invalidateQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
     expect(refetchQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
     expect(cancelQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });

package/src/index.ts

@@ -4,8 +4,6 @@ export * from './mutation.js';
 export * from './query.js';
 // Re-export all provider-related types and functions for cache management.
 export * from './provider.js';
-// Re-export query registry helpers for memoizing query services by key.
-export * from './query-registry.js';
 // Re-export tracked dependency types used by the additive tracked facade.
 export type {
   TrackedDependencyRecord,

package/src/provider.ts

@@ -56,9 +56,9 @@ export interface CreateQueryAndMutation {
 export interface QueryManager {
   // Factory for creating a dependency-tracked mutation service within the context of this provider.
   createMutation: CreateMutation;
-  // Factory for creating a dependency-tracked query service within the context of this provider.
+  // Factory for creating a dependency-tracked query handle within the context of this provider.
   createQuery: CreateQuery;
-  // Factory for creating an untracked query service within the context of this provider.
+  // 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.
   createUntrackedMutation: CreateUntrackedMutation;
@@ -70,6 +70,8 @@ export interface QueryManager {
   fetchQuery: QueryClient['fetchQuery'];
   // Synchronously retrieves a snapshot of the current query data.
   getQueryData: QueryClient['getQueryData'];
+  // Synchronously retrieves the raw TanStack query state for one query key.
+  getQueryState: QueryClient['getQueryState'];
   // Marks queries as invalid to trigger a refetch if they are active.
   invalidateQueries: QueryClient['invalidateQueries'];
   // Forces a refetch of queries matching the specified filters.
@@ -155,6 +157,8 @@ export function setupQueryManager(queryClient: QueryClient): QueryManager {
     fetchQuery: queryClient.fetchQuery.bind(queryClient),
     // Proxy for retrieving query data with this client context.
     getQueryData: queryClient.getQueryData.bind(queryClient),
+    // Proxy for retrieving raw query state with this client context.
+    getQueryState: queryClient.getQueryState.bind(queryClient),
     // Proxy for invalidating queries with this client context.
     invalidateQueries: queryClient.invalidateQueries.bind(queryClient),
     // Proxy for refetching queries with this client context.

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);
@@ -551,7 +571,7 @@ function createDependencyController<
   };
 }
 
-function splitQueryServiceOptions<
+function splitQueryHandleOptions<
   TQueryFnData = unknown,
   TError = Error,
   TData = TQueryFnData,
@@ -559,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 {
@@ -588,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