@veams/status-quo-query 0.11.0 → 0.13.0

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/mutation.ts

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

package/src/provider.ts

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