@veams/status-quo-query 0.10.0 → 0.12.0

package/README.md

@@ -8,6 +8,25 @@ TanStack Query service helpers with a small subscribable surface that fits natur
 npm install @veams/status-quo-query @tanstack/query-core
 ```
 
+React bindings are available through an optional peer dependency:
+
+```bash
+npm install react
+```
+
+## Mental Model
+
+Status Quo Query deliberately keeps the public surface small:
+
+- `QueryHandle<TData, TError>` is the read handle for one query.
+- `MutationService<TData, TError, TVariables>` is the write handle for one mutation.
+- snapshots are passive state objects returned from `getSnapshot()` and `subscribe(...)`.
+- commands stay on the handle: `refetch()`, `invalidate()`, `mutate()`, `reset()`.
+- `QueryManager` is the broader coordination layer for cross-query work.
+- `@veams/status-quo-query/react` is optional and adds one React subscription hook over the same handle shape.
+
+That keeps the package usable in service code, query handlers, state handlers, and React components without changing the core query or mutation API.
+
 ## Package Exports
 
 Root exports:
@@ -16,6 +35,7 @@ Root exports:
 - `setupQuery`
 - `setupMutation`
 - `isQueryLoading`
+- `toQueryHandleData`
 - `toQueryMetaState`
 - `QueryFetchStatus`
 - `QueryStatus`
@@ -27,12 +47,13 @@ Root exports:
 - `CreateMutationWithDefaults`
 - `CreateUntrackedQuery`
 - `CreateUntrackedMutation`
-- `QueryService`
+- `QueryHandle`
+- `QueryHandleData`
 - `MutationService`
-- `QueryServiceSnapshot`
+- `QueryHandleSnapshot`
 - `MutationServiceSnapshot`
 - `QueryDependencyTuple`
-- `QueryServiceOptions`
+- `QueryHandleOptions`
 - `MutationServiceOptions`
 - `TrackedMutationServiceOptions`
 - `QueryInvalidateOptions`
@@ -49,6 +70,7 @@ Subpath exports:
 - `@veams/status-quo-query/provider`
 - `@veams/status-quo-query/query`
 - `@veams/status-quo-query/mutation`
+- `@veams/status-quo-query/react`
 
 ## Quickstart
 
@@ -109,6 +131,86 @@ await userQuery.refetch();
 await userQuery.invalidate({ refetchType: 'none' });
 ```
 
+## React Bindings
+
+The React entrypoint exposes `useQueryHandle(...)` and keeps `react` optional unless you
+import `@veams/status-quo-query/react`.
+
+```tsx
+import { useQueryHandle } from '@veams/status-quo-query/react';
+import type { QueryHandle } from '@veams/status-quo-query';
+
+function ProductName({ query }: { query: QueryHandle<{ name: string }, Error> }) {
+  const snapshot = useQueryHandle(query);
+
+  return <span>{snapshot.data?.name ?? 'loading'}</span>;
+}
+```
+
+Use the hook when a component should subscribe directly to a query handle and render from its latest snapshot. Keep mapping at the component level:
+
+- read `data`, `status`, `fetchStatus`, and flags like `isPending` from the snapshot
+- call `query.refetch()` or `query.invalidate()` on the handle itself
+- derive view-specific values in the component instead of adding selector logic to the hook
+
+## Status Quo Integration
+
+The same query handle can also feed a `status-quo` handler through `bindSubscribable(...)`.
+
+```ts
+import { NativeStateHandler } from '@veams/status-quo';
+import {
+  toQueryMetaState,
+  type QueryMetaState,
+  type QueryHandle,
+} from '@veams/status-quo-query';
+
+type Product = {
+  id: string;
+  name: string;
+};
+
+type ProductCardState = {
+  product: Product | undefined;
+  query: QueryMetaState;
+};
+
+type ProductCardActions = {
+  refresh: () => Promise<void>;
+};
+
+export class ProductCardHandler extends NativeStateHandler<ProductCardState, ProductCardActions> {
+  constructor(private readonly productQuery: QueryHandle<Product, Error>) {
+    super({
+      initialState: {
+        product: productQuery.getSnapshot().data,
+        query: toQueryMetaState(productQuery.getSnapshot()),
+      },
+    });
+
+    this.bindSubscribable(productQuery, (snapshot) => {
+      this.setState(
+        {
+          product: snapshot.data,
+          query: toQueryMetaState(snapshot),
+        },
+        'query:update'
+      );
+    });
+  }
+
+  getActions(): ProductCardActions {
+    return {
+      refresh: async () => {
+        await this.productQuery.refetch();
+      },
+    };
+  }
+}
+```
+
+Use that approach when query state is only one input into a broader UI state model and the handler should remain the view-facing boundary.
+
 ## Why Tracked Invalidation
 
 TanStack Query gives you flexible invalidation primitives, but the application still has to know which keys to invalidate after every mutation. Tracked invalidation moves that bookkeeping into the facade:
@@ -400,7 +502,7 @@ Use `dependsOn` when a query needs data from other queries before it can run.
 
 `dependsOn` accepts a `QueryDependencyTuple`:
 
-- an ordered list of source query services
+- an ordered list of source query handles
 - a `deriveOptions(...)` callback that returns only `queryKey` and/or `enabled`
 
 The watcher starts on the first `subscribe(...)` or `refetch()`, reads the current source snapshots immediately, and stops after the last unsubscribe. A downstream `refetch()` refetches all source services first, then refetches the derived query.
@@ -550,6 +652,7 @@ Returns `QueryManager` with:
 - `cancelQueries(...)`
 - `fetchQuery(...)`
 - `getQueryData(...)`
+- `getQueryState(...)`
 - `invalidateQueries(...)`
 - `refetchQueries(...)`
 - `removeQueries(...)`
@@ -559,6 +662,95 @@ Returns `QueryManager` with:
 
 All manager methods forward directly to the corresponding `QueryClient` methods. `fetchQuery(...)` covers the common one-off read path without dropping to the raw client, while `unsafe_getClient()` remains the explicit escape hatch for unsupported TanStack APIs.
 
+### How to write a service
+
+Do not memoize `QueryHandle` instances in a package-level registry.
+
+TanStack already deduplicates cached queries by `queryKey`. A `QueryHandle` is a handle over that cached state, closer to a TanStack `QueryObserver` than to the cached query entry itself. Creating a fresh handle per service method call is fine when the caller wants a live query handle.
+
+Use this split in a query handler:
+
+- return fresh query handles from methods that expose `refetch()`, `subscribe(...)`, or `invalidate()`
+- read cache state directly from `QueryManager` in state-only methods
+- add smaller data-only methods when callers do not need fetch metadata
+
+Example:
+
+```ts
+import type {
+  QueryHandle,
+  QueryHandleData,
+  QueryHandleSnapshot,
+} from '@veams/status-quo-query';
+
+type Company = {
+  id: string;
+  name: string;
+};
+
+// Shared key factories keep the live handle path and snapshot path aligned.
+const companiesQueryKey = ['companies'] as const;
+const companyByIdQueryKey = (companyId: string) => ['company', companyId] as const;
+
+export interface CompanyQueryHandler {
+  getCompaniesQuery: () => QueryHandle<Company[], Error>;
+  getCompanyQueryById: (companyId: string) => QueryHandle<Company, Error>;
+  getCompanyStateById: (companyId: string) => QueryHandleSnapshot<Company, Error>;
+  getCompanyDataById: (companyId: string) => QueryHandleData<Company, Error>;
+}
+
+export function createCompanyQueryHandler(): CompanyQueryHandler {
+  const manager = getQueryManager();
+
+  return {
+    // Return a fresh query handle when callers need commands or subscriptions.
+    getCompaniesQuery() {
+      return manager.createUntrackedQuery(companiesQueryKey, fetchCompanies, {
+        staleTime: companyStaleTime,
+      });
+    },
+    // Parameterized query handles are cheap and map directly to the final query key.
+    getCompanyQueryById(companyId) {
+      const queryKey = companyByIdQueryKey(companyId);
+
+      return manager.createUntrackedQuery(queryKey, () => fetchCompanyById(companyId), {
+        staleTime: companyStaleTime,
+      });
+    },
+    // Snapshot-only reads should use the manager cache APIs instead of building another handle.
+    getCompanyStateById(companyId) {
+      const queryKey = companyByIdQueryKey(companyId);
+      const state = manager.getQueryState(queryKey);
+
+      return {
+        data: manager.getQueryData(queryKey),
+        error: (state?.error as Error | null | undefined) ?? null,
+        fetchStatus: state?.fetchStatus ?? 'idle',
+        status: state?.status ?? 'pending',
+        isError: state?.status === 'error',
+        isFetching: state?.fetchStatus === 'fetching',
+        isPending: state?.status === 'pending',
+        isSuccess: state?.status === 'success',
+      };
+    },
+    // Data-only reads can stay even smaller when the caller does not need fetch meta state.
+    getCompanyDataById(companyId) {
+      const queryKey = companyByIdQueryKey(companyId);
+      const state = manager.getQueryState(queryKey);
+
+      return {
+        data: manager.getQueryData(queryKey),
+        error: (state?.error as Error | null | undefined) ?? null,
+      };
+    },
+  };
+}
+```
+
+In this example, `getQueryManager()` is your application-level accessor for the shared `QueryManager`.
+
+This keeps the query handler focused on one feature area, supports parameterized query methods naturally, and offers both full state reads and smaller data-only reads without creating extra handle instances.
+
 ### Tracked Queries and Mutations
 
 Tracked queries embed dependency metadata into the final query-key segment:
@@ -569,7 +761,7 @@ Tracked queries embed dependency metadata into the final query-key segment:
 
 Only `deps` participates in automatic invalidation tracking. `view` is optional and is treated as normal query-key data.
 
-`createQuery(queryKey, queryFn, options?)` returns the same `QueryService<TData, TError>` shape as `createUntrackedQuery(...)`, but it registers the query hash under every `deps` entry, re-registers on `refetch()` or the first `subscribe(...)` if TanStack has removed the cache entry in the meantime, and keeps the registry in sync when `dependsOn` derives a new tracked key at runtime.
+`createQuery(queryKey, queryFn, options?)` returns the same `QueryHandle<TData, TError>` shape as `createUntrackedQuery(...)`, but it registers the query hash under every `deps` entry, re-registers on `refetch()` or the first `subscribe(...)` if TanStack has removed the cache entry in the meantime, and keeps the registry in sync when `dependsOn` derives a new tracked key at runtime.
 
 `createMutation(mutationFn, options?)` returns the same `MutationService<TData, TError, TVariables, TOnMutateResult>` shape as `createUntrackedMutation(...)`, but adds:
 
@@ -606,17 +798,17 @@ Reach for standalone `createMutation(...)` when:
 
 Creates a `createUntrackedQuery` factory bound to a `QueryClient`.
 
-`createUntrackedQuery(queryKey, queryFn, options?)` returns `QueryService<TData, TError>`.
+`createUntrackedQuery(queryKey, queryFn, options?)` returns `QueryHandle<TData, TError>`.
 
-`QueryServiceOptions` is based on TanStack `QueryObserverOptions`, without `queryKey` and `queryFn` because those are provided directly to `createUntrackedQuery`.
+`QueryHandleOptions` is based on TanStack `QueryObserverOptions`, without `queryKey` and `queryFn` because those are provided directly to `createUntrackedQuery`.
 
 It also adds:
 
 - `dependsOn?: QueryDependencyTuple<[...sources]>`
 
-`dependsOn` observes the listed source query services and lets the downstream query derive only `queryKey` and `enabled`. Source services are activated while the downstream query is active, and downstream `refetch()` refetches the sources first. The public `QueryService` API does not change when this option is used.
+`dependsOn` observes the listed source query handles and lets the downstream query derive only `queryKey` and `enabled`. Source handles are activated while the downstream query is active, and downstream `refetch()` refetches the sources first. The public `QueryHandle` API does not change when this option is used.
 
-`QueryService` methods:
+`QueryHandle` methods:
 
 - `getSnapshot()`
 - `subscribe(listener)`
@@ -624,7 +816,7 @@ It also adds:
 - `invalidate(options?)`
 - `unsafe_getResult()`
 
-`QueryServiceSnapshot<TData, TError>` fields:
+`QueryHandleSnapshot<TData, TError>` fields:
 
 - `data`
 - `error`
@@ -635,6 +827,11 @@ It also adds:
 - `isPending`
 - `isSuccess`
 
+`QueryHandleData<TData, TError>` fields:
+
+- `data`
+- `error`
+
 `invalidate(options?)` invalidates the query by its exact key. `QueryInvalidateOptions` supports:
 
 - `refetchType`
@@ -674,6 +871,11 @@ Creates a `createUntrackedMutation` factory bound to a `QueryClient`.
 
 ### Query Helpers
 
+`toQueryHandleData(snapshot)` reduces a query snapshot to:
+
+- `data`
+- `error`
+
 `toQueryMetaState(snapshot)` reduces a query snapshot to:
 
 - `status`

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export * from './mutation.js';
 export * from './query.js';
 export * from './provider.js';
-export * from './query-registry.js';
 export type { TrackedDependencyRecord, TrackedDependencyValue, TrackedInvalidateOn, TrackedMatchMode, TrackedQueryKey, TrackedQueryKeySegment, } from './tracking.js';

package/dist/index.js

@@ -4,6 +4,4 @@ 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';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,cAAc,eAAe,CAAC;AAC9B,mDAAmD;AACnD,cAAc,YAAY,CAAC;AAC3B,2EAA2E;AAC3E,cAAc,eAAe,CAAC;AAC9B,wEAAwE;AACxE,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,cAAc,eAAe,CAAC;AAC9B,mDAAmD;AACnD,cAAc,YAAY,CAAC;AAC3B,2EAA2E;AAC3E,cAAc,eAAe,CAAC"}

package/dist/provider.d.ts

@@ -29,6 +29,7 @@ export interface QueryManager {
     cancelQueries: QueryClient['cancelQueries'];
     fetchQuery: QueryClient['fetchQuery'];
     getQueryData: QueryClient['getQueryData'];
+    getQueryState: QueryClient['getQueryState'];
     invalidateQueries: QueryClient['invalidateQueries'];
     refetchQueries: QueryClient['refetchQueries'];
     removeQueries: QueryClient['removeQueries'];

package/dist/provider.js

@@ -48,6 +48,8 @@ export function setupQueryManager(queryClient) {
         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/dist/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAMA,qEAAqE;AACrE,OAAO,EAKL,aAAa,EACb,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAA+C,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EACL,sBAAsB,GAEvB,MAAM,eAAe,CAAC;AAmEvB;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAwB;IACxD,sFAAsF;IACtF,sFAAsF;IACtF,MAAM,gBAAgB,GAAG,sBAAsB,EAAE,CAAC;IAClD,MAAM,YAAY,GAAG,iBAAiB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IACtE,MAAM,eAAe,GAAG,oBAAoB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IAC5E,MAAM,qBAAqB,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACtD,MAAM,wBAAwB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAE5D,WAAW,CAAC,aAAa,EAAE,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,6FAA6F;YAC7F,4FAA4F;YAC5F,gFAAgF;YAChF,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,2DAA2D;IAC3D,OAAO;QACL,6CAA6C;QAC7C,cAAc,EAAE,eAAe;QAC/B,0CAA0C;QAC1C,WAAW,EAAE,YAAY;QACzB,oDAAoD;QACpD,oBAAoB,EAAE,qBAAqB;QAC3C,uDAAuD;QACvD,uBAAuB,EAAE,wBAAwB;QACjD,8DAA8D;QAC9D,sBAAsB,EAAE,CACtB,cAA+B,EAC/B,EAAE;YACF,MAAM,0BAA0B,GAE5B,CACF,UAA+C,EAC/C,OASC,EACD,EAAE;YACF,uFAAuF;YACvF,mFAAmF;YACnF,eAAe,CAMb,UAAU,EAAE;gBACZ,GAAG,OAAO;gBACV,cAAc;aACf,CAAC,CAAC;YAEL,OAAO,CAAC,YAAY,EAAE,0BAA0B,CAAU,CAAC;QAC7D,CAAC;QACD,wDAAwD;QACxD,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,yDAAyD;QACzD,UAAU,EAAE,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC;QACpD,4DAA4D;QAC5D,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,2DAA2D;QAC3D,iBAAiB,EAAE,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC;QAClE,yDAAyD;QACzD,cAAc,EAAE,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC;QAC5D,uDAAuD;QACvD,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,wDAAwD;QACxD,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,yDAAyD;QACzD,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,mDAAmD;QACnD,gBAAgB,EAAE,GAAG,EAAE,CAAC,WAAW;KACpC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAMA,qEAAqE;AACrE,OAAO,EAKL,aAAa,EACb,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAA+C,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EACL,sBAAsB,GAEvB,MAAM,eAAe,CAAC;AAqEvB;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAwB;IACxD,sFAAsF;IACtF,sFAAsF;IACtF,MAAM,gBAAgB,GAAG,sBAAsB,EAAE,CAAC;IAClD,MAAM,YAAY,GAAG,iBAAiB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IACtE,MAAM,eAAe,GAAG,oBAAoB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IAC5E,MAAM,qBAAqB,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACtD,MAAM,wBAAwB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAE5D,WAAW,CAAC,aAAa,EAAE,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,6FAA6F;YAC7F,4FAA4F;YAC5F,gFAAgF;YAChF,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,2DAA2D;IAC3D,OAAO;QACL,6CAA6C;QAC7C,cAAc,EAAE,eAAe;QAC/B,0CAA0C;QAC1C,WAAW,EAAE,YAAY;QACzB,oDAAoD;QACpD,oBAAoB,EAAE,qBAAqB;QAC3C,uDAAuD;QACvD,uBAAuB,EAAE,wBAAwB;QACjD,8DAA8D;QAC9D,sBAAsB,EAAE,CACtB,cAA+B,EAC/B,EAAE;YACF,MAAM,0BAA0B,GAE5B,CACF,UAA+C,EAC/C,OASC,EACD,EAAE;YACF,uFAAuF;YACvF,mFAAmF;YACnF,eAAe,CAMb,UAAU,EAAE;gBACZ,GAAG,OAAO;gBACV,cAAc;aACf,CAAC,CAAC;YAEL,OAAO,CAAC,YAAY,EAAE,0BAA0B,CAAU,CAAC;QAC7D,CAAC;QACD,wDAAwD;QACxD,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,yDAAyD;QACzD,UAAU,EAAE,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC;QACpD,4DAA4D;QAC5D,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,iEAAiE;QACjE,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,2DAA2D;QAC3D,iBAAiB,EAAE,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC;QAClE,yDAAyD;QACzD,cAAc,EAAE,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC;QAC5D,uDAAuD;QACvD,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,wDAAwD;QACxD,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,yDAAyD;QACzD,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,mDAAmD;QACnD,gBAAgB,EAAE,GAAG,EAAE,CAAC,WAAW;KACpC,CAAC;AACJ,CAAC"}

package/dist/query.d.ts

@@ -3,9 +3,9 @@ import { type TrackedDependencyRecord, type TrackingRegistry, type TrackedQueryK
 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> {
     data: TData | undefined;
     error: TError | null;
     fetchStatus: QueryFetchStatus;
@@ -15,6 +15,13 @@ export interface QueryServiceSnapshot<TData, TError> {
     isPending: boolean;
     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.
  */
@@ -23,12 +30,12 @@ export interface QueryMetaState {
     status: QueryStatus;
 }
 /**
- * Defines the public API for a query service.
+ * Defines the public API for a query handle.
  */
-export interface QueryService<TData, TError> {
-    getSnapshot: () => QueryServiceSnapshot<TData, TError>;
-    subscribe: (listener: (snapshot: QueryServiceSnapshot<TData, TError>) => void) => () => void;
-    refetch: (options?: RefetchOptions) => Promise<QueryServiceSnapshot<TData, TError>>;
+export interface QueryHandle<TData, TError> {
+    getSnapshot: () => QueryHandleSnapshot<TData, TError>;
+    subscribe: (listener: (snapshot: QueryHandleSnapshot<TData, TError>) => void) => () => void;
+    refetch: (options?: RefetchOptions) => Promise<QueryHandleSnapshot<TData, TError>>;
     invalidate: (options?: QueryInvalidateOptions) => Promise<void>;
     unsafe_getResult: () => QueryObserverResult<TData, TError>;
 }
@@ -43,38 +50,42 @@ type QueryDependencyDerivedOptions<TQueryKey extends QueryKey = QueryKey> = {
 };
 export type QueryDependencyTuple<TSources extends readonly unknown[], TQueryKey extends QueryKey = QueryKey> = readonly [
     sources: {
-        readonly [K in keyof TSources]: QueryService<TSources[K], Error>;
+        readonly [K in keyof TSources]: QueryHandle<TSources[K], Error>;
     },
     deriveOptions: (sourceSnapshots: {
-        readonly [K in keyof TSources]: QueryServiceSnapshot<TSources[K], Error>;
+        readonly [K in keyof TSources]: QueryHandleSnapshot<TSources[K], Error>;
     }) => QueryDependencyDerivedOptions<TQueryKey>
 ];
 /**
  * Function signature for the untracked query factory.
  */
 export interface CreateUntrackedQuery {
-    <TSources extends readonly unknown[] = [], TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(queryKey: TQueryKey, queryFn: QueryFunction<TQueryFnData, TQueryKey>, options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>): QueryService<TData, TError>;
+    <TSources extends readonly unknown[] = [], TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(queryKey: TQueryKey, queryFn: QueryFunction<TQueryFnData, TQueryKey>, 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 {
-    <TDeps extends TrackedDependencyRecord, TSources extends readonly unknown[] = [], TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends TrackedQueryKey<TDeps> = TrackedQueryKey<TDeps>>(queryKey: TQueryKey, queryFn: QueryFunction<TQueryFnData, TQueryKey>, options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>): QueryService<TData, TError>;
+    <TDeps extends TrackedDependencyRecord, TSources extends readonly unknown[] = [], TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends TrackedQueryKey<TDeps> = TrackedQueryKey<TDeps>>(queryKey: TQueryKey, queryFn: QueryFunction<TQueryFnData, TQueryKey>, 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<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TSources extends readonly unknown[] = []> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, 'queryFn' | 'queryKey'> & {
+export type QueryHandleOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TSources extends readonly unknown[] = []> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, 'queryFn' | 'queryKey'> & {
     dependsOn?: QueryDependencyTuple<TSources, TQueryKey>;
 };
 /**
  * Extracts and maps status and fetchStatus to our QueryMetaState interface.
  */
-export declare function toQueryMetaState<TData, TError>(snapshot: Pick<QueryServiceSnapshot<TData, TError>, 'fetchStatus' | 'status'>): QueryMetaState;
+export declare function toQueryMetaState<TData, TError>(snapshot: Pick<QueryHandleSnapshot<TData, TError>, 'fetchStatus' | 'status'>): QueryMetaState;
+/**
+ * Extracts only data and error from a query snapshot.
+ */
+export declare function toQueryHandleData<TData, TError>(snapshot: Pick<QueryHandleSnapshot<TData, TError>, 'data' | 'error'>): QueryHandleData<TData, TError>;
 /**
  * Helper function to check if the query is in its initial loading state.
  */

package/dist/query.js

@@ -12,6 +12,15 @@ export function toQueryMetaState(snapshot) {
         status: snapshot.status,
     };
 }
+/**
+ * Extracts only data and error from a query snapshot.
+ */
+export function toQueryHandleData(snapshot) {
+    return {
+        data: snapshot.data,
+        error: snapshot.error,
+    };
+}
 /**
  * Helper function to check if the query is in its initial loading state.
  */
@@ -23,14 +32,14 @@ export function isQueryLoading(query) {
  * Prepares the query factory by binding it to a specific QueryClient instance.
  */
 export function setupQuery(queryClient) {
-    // Returns the actual factory function for creating individual query services.
+    // Returns the actual factory function for creating individual query handles.
     return function createQuery(queryKey, queryFn, options) {
-        const { dependsOn, runtimeOptions } = splitQueryServiceOptions(options);
-        const service = createQueryService(queryClient, queryKey, queryFn, runtimeOptions);
+        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);
     };
 }
 /**
@@ -45,22 +54,22 @@ export function setupQuery(queryClient) {
  */
 export function setupTrackedQuery(queryClient, trackingRegistry) {
     return function createQuery(queryKey, queryFn, options) {
-        const { dependsOn, runtimeOptions } = splitQueryServiceOptions(options);
-        // Reuse the same core query service implementation as the untracked API.
-        const service = createQueryService(queryClient, queryKey, queryFn, runtimeOptions);
+        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()));
+        trackingRegistry.register(handle.observer.getCurrentQuery().queryHash, extractTrackedDependencies(handle.getCurrentQueryKey()));
         const applyTrackedDerivedState = (derivedOptions) => {
-            const previousQueryHash = service.observer.getCurrentQuery().queryHash;
-            service.setDerivedState(derivedOptions);
-            const nextQueryHash = service.observer.getCurrentQuery().queryHash;
+            const previousQueryHash = handle.observer.getCurrentQuery().queryHash;
+            handle.setDerivedState(derivedOptions);
+            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
             ? createDependencyController(queryKey, applyTrackedDerivedState, dependsOn)
@@ -68,8 +77,8 @@ export function setupTrackedQuery(queryClient, trackingRegistry) {
         const ensureRegistered = () => {
             // Build resolves the current live TanStack query for the stored observer options. This is
             // the same mechanism TanStack uses internally when a query gets recreated after GC.
-            const liveQuery = queryClient.getQueryCache().build(queryClient, service.getCurrentObserverOptions());
-            const liveDependencies = extractTrackedDependencies(service.getCurrentQueryKey());
+            const liveQuery = queryClient.getQueryCache().build(queryClient, handle.getCurrentObserverOptions());
+            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.
             if (!trackingRegistry.has(liveQuery.queryHash)) {
@@ -77,12 +86,12 @@ export function setupTrackedQuery(queryClient, trackingRegistry) {
             }
         };
         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
@@ -92,7 +101,7 @@ export function setupTrackedQuery(queryClient, trackingRegistry) {
                     ensureRegistered();
                 }
                 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.
                     subscriberCount = Math.max(0, subscriberCount - 1);
@@ -108,8 +117,8 @@ export function setupTrackedQuery(queryClient, trackingRegistry) {
 /**
  * Internal helper to transform a raw Tanstack query result into our public snapshot format.
  */
-function toQueryServiceSnapshot(result) {
-    // Extract and return the relevant fields for the UI or other services.
+function toQueryHandleSnapshot(result) {
+    // Extract and return the relevant fields for the UI or other handle consumers.
     return {
         data: result.data,
         error: result.error,
@@ -121,7 +130,7 @@ function toQueryServiceSnapshot(result) {
         isSuccess: result.isSuccess,
     };
 }
-function createQueryService(queryClient, queryKey, queryFn, options) {
+function createQueryHandle(queryClient, queryKey, queryFn, options) {
     const baseQueryKey = queryKey;
     const baseOptions = options;
     let resolvedQueryKey = baseQueryKey;
@@ -141,12 +150,12 @@ function createQueryService(queryClient, queryKey, queryFn, options) {
         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)),
+            refetch: async (refetchOptions) => toQueryHandleSnapshot(await observer.refetch(refetchOptions)),
             invalidate: (invalidateOptions) => queryClient.invalidateQueries({
                 exact: true,
                 queryKey: resolvedQueryKey,
@@ -158,21 +167,21 @@ function createQueryService(queryClient, queryKey, queryFn, options) {
         },
     };
 }
-function bindQueryDependencies(queryService, queryKey, dependsOn) {
-    const dependencyController = createDependencyController(queryKey, queryService.setDerivedState, dependsOn);
+function bindQueryDependencies(queryHandle, queryKey, dependsOn) {
+    const dependencyController = createDependencyController(queryKey, 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) {
                 dependencyController.activate();
             }
             subscriberCount += 1;
-            const unsubscribe = queryService.service.subscribe(listener);
+            const unsubscribe = queryHandle.handle.subscribe(listener);
             return () => {
                 subscriberCount = Math.max(0, subscriberCount - 1);
                 if (subscriberCount === 0) {
@@ -239,7 +248,7 @@ function createDependencyController(baseQueryKey, setDerivedState, dependsOn) {
         },
     };
 }
-function splitQueryServiceOptions(options) {
+function splitQueryHandleOptions(options) {
     if (options === undefined) {
         return {
             dependsOn: undefined,