@veams/status-quo-query 0.2.0 → 0.4.0

package/.turbo/turbo-build.log

@@ -1,12 +1,14 @@
-
-> @veams/status-quo-query@0.1.0 build
-> npm-run-all compile
-
-
-> @veams/status-quo-query@0.1.0 compile
-> npm-run-all bundle:ts
-
-
-> @veams/status-quo-query@0.1.0 bundle:ts
-> tsc --project tsconfig.json
-
+
+
+> @veams/status-quo-query@0.3.0 build
+> npm-run-all compile
+
+
+> @veams/status-quo-query@0.3.0 compile
+> npm-run-all bundle:ts
+
+
+> @veams/status-quo-query@0.3.0 bundle:ts
+> tsc --project tsconfig.json
+
+⠙⠙⠙

package/README.md

@@ -12,7 +12,7 @@ npm install @veams/status-quo-query @tanstack/query-core
 
 Root exports:
 
-- `setupQueryProvider`
+- `setupQueryManager`
 - `setupQuery`
 - `setupMutation`
 - `isQueryLoading`
@@ -20,7 +20,7 @@ Root exports:
 - `QueryFetchStatus`
 - `QueryStatus`
 - `MutationStatus`
-- `CacheApi`
+- `QueryManager`
 - `CreateQuery`
 - `CreateMutation`
 - `QueryService`
@@ -43,32 +43,32 @@ Subpath exports:
 ```ts
 import { QueryClient } from '@tanstack/query-core';
 import {
-  setupQueryProvider,
+  setupQueryManager,
 } from '@veams/status-quo-query';
 
 const queryClient = new QueryClient();
-const cache = setupQueryProvider(queryClient);
+const manager = setupQueryManager(queryClient);
 
-const userQuery = cache.createQuery(['user', 42], () => fetchUser(42), {
+const userQuery = manager.createQuery(['user', 42], () => fetchUser(42), {
   enabled: false,
 });
 await userQuery.refetch();
 await userQuery.invalidate({ refetchType: 'none' });
 
-const updateUser = cache.createMutation((payload: UpdateUserPayload) => saveUser(payload));
+const updateUser = manager.createMutation((payload: UpdateUserPayload) => saveUser(payload));
 await updateUser.mutate({ id: 42 });
 
-await cache.invalidateQueries({ queryKey: ['user'] });
-cache.setQueryData(['user', 42], (current) => current);
+await manager.invalidateQueries({ queryKey: ['user'] });
+manager.setQueryData(['user', 42], (current) => current);
 ```
 
 ## API
 
-### `setupQueryProvider(queryClient)`
+### `setupQueryManager(queryClient)`
 
-Creates the package-level cache facade around an existing TanStack `QueryClient`.
+Creates the package-level query manager facade around an existing TanStack `QueryClient`.
 
-Returns `CacheApi` with:
+Returns `QueryManager` with:
 
 - `createQuery(queryKey, queryFn, options?)`
 - `createMutation(mutationFn, options?)`
@@ -81,7 +81,7 @@ Returns `CacheApi` with:
 - `setQueryData(...)`
 - `unsafe_getClient()`
 
-All cache methods forward directly to the corresponding `QueryClient` methods. `unsafe_getClient()` returns the raw TanStack client as an explicit escape hatch.
+All manager methods forward directly to the corresponding `QueryClient` methods. `unsafe_getClient()` returns the raw TanStack client as an explicit escape hatch.
 
 ### `setupQuery(queryClient)`
 
@@ -170,4 +170,4 @@ Creates a `createMutation` factory bound to a `QueryClient`.
 - `getSnapshot()` always returns passive state only.
 - Commands live on the handle itself: `refetch`, `invalidate`, `mutate`, `reset`.
 - Raw TanStack observer and client access is explicit through `unsafe_getResult()` and `unsafe_getClient()`.
-- Cache-level operations live on `setupQueryProvider()`, not on individual snapshots.
+- Manager-level operations live on `setupQueryManager()`, not on individual snapshots.

package/dist/index.js

@@ -1,4 +1,7 @@
+// Re-export all mutation-related types and functions.
 export * from './mutation';
+// Re-export all query-related types and functions.
 export * from './query';
+// Re-export all provider-related types and functions for cache management.
 export * from './provider';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/mutation.d.ts

@@ -1,5 +1,8 @@
 import { type MutationFunction, type MutateOptions, type MutationObserverOptions, type MutationObserverResult, type MutationStatus as TanstackMutationStatus, type QueryClient } from '@tanstack/query-core';
 export type MutationStatus = TanstackMutationStatus;
+/**
+ * Represents a stable snapshot of the mutation service's state.
+ */
 export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVariables = void> {
     data: TData | undefined;
     error: TError | null;
@@ -10,6 +13,9 @@ export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVaria
     isPending: boolean;
     isSuccess: boolean;
 }
+/**
+ * Defines the public API for a mutation service.
+ */
 export interface MutationService<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> {
     getSnapshot: () => MutationServiceSnapshot<TData, TError, TVariables>;
     subscribe: (listener: (snapshot: MutationServiceSnapshot<TData, TError, TVariables>) => void) => () => void;
@@ -17,8 +23,17 @@ export interface MutationService<TData = unknown, TError = Error, TVariables = v
     reset: () => void;
     unsafe_getResult: () => MutationObserverResult<TData, TError, TVariables, TOnMutateResult>;
 }
+/**
+ * Configuration options for creating a mutation service, excluding the mutation function itself.
+ */
 export type MutationServiceOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> = Omit<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationFn'>;
+/**
+ * Function signature for the mutation factory.
+ */
 export interface CreateMutation {
     <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationFn: MutationFunction<TData, TVariables>, options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>): MutationService<TData, TError, TVariables, TOnMutateResult>;
 }
+/**
+ * Prepares the mutation factory by binding it to a specific QueryClient instance.
+ */
 export declare function setupMutation(queryClient: QueryClient): CreateMutation;

package/dist/mutation.js

@@ -1,22 +1,39 @@
-import { MutationObserver, } from '@tanstack/query-core';
+import { 
+// Import MutationObserver to observe and manage mutations.
+MutationObserver, } from '@tanstack/query-core';
+/**
+ * Prepares the mutation factory by binding it to a specific QueryClient instance.
+ */
 export function setupMutation(queryClient) {
+    // Returns the actual factory function for creating individual mutation services.
     return function createMutation(mutationFn, options) {
+        // Create a new MutationObserver instance to manage this specific mutation's lifecycle.
         const observer = new MutationObserver(queryClient, {
             ...options,
             mutationFn,
         });
+        // Return the implementation of the MutationService interface.
         return {
+            // Map the current observer state to our service's snapshot format.
             getSnapshot: () => toMutationServiceSnapshot(observer.getCurrentResult()),
+            // Subscribe to observer changes and notify the listener with updated snapshots.
             subscribe: (listener) => observer.subscribe((result) => {
                 listener(toMutationServiceSnapshot(result));
             }),
+            // Proxy the mutate call to the underlying observer.
             mutate: (variables, mutateOptions) => observer.mutate(variables, mutateOptions),
+            // Reset the underlying observer state.
             reset: () => observer.reset(),
+            // Provide direct access to the raw observer result when needed.
             unsafe_getResult: () => observer.getCurrentResult(),
         };
     };
 }
+/**
+ * Internal helper to transform a raw Tanstack mutation result into our public snapshot format.
+ */
 function toMutationServiceSnapshot(result) {
+    // Extract and return the relevant fields for the UI or other services.
     return {
         data: result.data,
         error: result.error,

package/dist/mutation.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutation.js","sourceRoot":"","sources":["../src/mutation.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,GAOjB,MAAM,sBAAsB,CAAC;AA+C9B,MAAM,UAAU,aAAa,CAAC,WAAwB;IACpD,OAAO,SAAS,cAAc,CAM5B,UAA+C,EAC/C,OAA4E;QAE5E,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CACnC,WAAW,EACX;YACE,GAAG,OAAO;YACV,UAAU;SACX,CACF,CAAC;QAEF,OAAO;YACL,WAAW,EAAE,GAAG,EAAE,CAAC,yBAAyB,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC;YACzE,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CACtB,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE;gBAC5B,QAAQ,CAAC,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9C,CAAC,CAAC;YACJ,MAAM,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC;YAC/E,KAAK,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE;YAC7B,gBAAgB,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE;SACpD,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,yBAAyB,CAChC,MAA0E;IAE1E,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"mutation.js","sourceRoot":"","sources":["../src/mutation.ts"],"names":[],"mappings":"AAAA,OAAO;AACL,2DAA2D;AAC3D,gBAAgB,GAajB,MAAM,sBAAsB,CAAC;AA2E9B;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,WAAwB;IACpD,iFAAiF;IACjF,OAAO,SAAS,cAAc,CAM5B,UAA+C,EAC/C,OAA4E;QAE5E,uFAAuF;QACvF,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CACnC,WAAW,EACX;YACE,GAAG,OAAO;YACV,UAAU;SACX,CACF,CAAC;QAEF,8DAA8D;QAC9D,OAAO;YACL,mEAAmE;YACnE,WAAW,EAAE,GAAG,EAAE,CAAC,yBAAyB,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC;YACzE,gFAAgF;YAChF,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CACtB,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE;gBAC5B,QAAQ,CAAC,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC9C,CAAC,CAAC;YACJ,oDAAoD;YACpD,MAAM,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC;YAC/E,uCAAuC;YACvC,KAAK,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE;YAC7B,gEAAgE;YAChE,gBAAgB,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE;SACpD,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,yBAAyB,CAChC,MAA0E;IAE1E,uEAAuE;IACvE,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC;AACJ,CAAC"}

package/dist/provider.d.ts

@@ -1,7 +1,10 @@
 import { type QueryClient } from '@tanstack/query-core';
 import { type CreateMutation } from './mutation';
 import { type CreateQuery } from './query';
-export interface CacheApi {
+/**
+ * Defines the public API for the query manager facade.
+ */
+export interface QueryManager {
     createMutation: CreateMutation;
     createQuery: CreateQuery;
     cancelQueries: QueryClient['cancelQueries'];
@@ -13,4 +16,7 @@ export interface CacheApi {
     setQueryData: QueryClient['setQueryData'];
     unsafe_getClient: () => QueryClient;
 }
-export declare function setupQueryProvider(queryClient: QueryClient): CacheApi;
+/**
+ * Prepares the query manager facade by binding all actions to a specific QueryClient instance.
+ */
+export declare function setupQueryManager(queryClient: QueryClient): QueryManager;

package/dist/provider.js

@@ -1,16 +1,31 @@
+// Import mutation and query setup functions and their factory types.
 import { setupMutation } from './mutation';
 import { setupQuery } from './query';
-export function setupQueryProvider(queryClient) {
+/**
+ * Prepares the query manager facade by binding all actions to a specific QueryClient instance.
+ */
+export function setupQueryManager(queryClient) {
+    // Return the implementation of the QueryManager interface.
     return {
+        // Bind mutation factory to this QueryClient.
         createMutation: setupMutation(queryClient),
+        // Bind query factory to this QueryClient.
         createQuery: setupQuery(queryClient),
+        // Proxy for canceling queries with this client context.
         cancelQueries: queryClient.cancelQueries.bind(queryClient),
+        // Proxy for retrieving query data with this client context.
         getQueryData: queryClient.getQueryData.bind(queryClient),
+        // Proxy for invalidating queries with this client context.
         invalidateQueries: queryClient.invalidateQueries.bind(queryClient),
+        // Proxy for refetching queries with this client context.
         refetchQueries: queryClient.refetchQueries.bind(queryClient),
+        // Proxy for removing queries with this client context.
         removeQueries: queryClient.removeQueries.bind(queryClient),
+        // Proxy for resetting queries with this client context.
         resetQueries: queryClient.resetQueries.bind(queryClient),
+        // Proxy for setting query data with this client context.
         setQueryData: queryClient.setQueryData.bind(queryClient),
+        // Provide an accessor for the raw client instance.
         unsafe_getClient: () => queryClient,
     };
 }

package/dist/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,aAAa,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAoB,UAAU,EAAE,MAAM,SAAS,CAAC;AAevD,MAAM,UAAU,kBAAkB,CAAC,WAAwB;IACzD,OAAO;QACL,cAAc,EAAE,aAAa,CAAC,WAAW,CAAC;QAC1C,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC;QACpC,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,iBAAiB,EAAE,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC;QAClE,cAAc,EAAE,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC;QAC5D,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,gBAAgB,EAAE,GAAG,EAAE,CAAC,WAAW;KACpC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAKA,qEAAqE;AACrE,OAAO,EAAuB,aAAa,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAoB,UAAU,EAAE,MAAM,SAAS,CAAC;AA4BvD;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAwB;IACxD,2DAA2D;IAC3D,OAAO;QACL,6CAA6C;QAC7C,cAAc,EAAE,aAAa,CAAC,WAAW,CAAC;QAC1C,0CAA0C;QAC1C,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC;QACpC,wDAAwD;QACxD,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,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"}

package/dist/query.d.ts

@@ -1,6 +1,9 @@
 import { type FetchStatus, type InvalidateOptions, type InvalidateQueryFilters, type QueryClient, type QueryFunction, type QueryKey, type QueryObserverOptions, type QueryObserverResult, type RefetchOptions, type QueryStatus as TanstackQueryStatus } from '@tanstack/query-core';
 export type QueryFetchStatus = FetchStatus;
 export type QueryStatus = TanstackQueryStatus;
+/**
+ * Represents a stable snapshot of the query service's state.
+ */
 export interface QueryServiceSnapshot<TData, TError> {
     data: TData | undefined;
     error: TError | null;
@@ -11,10 +14,16 @@ export interface QueryServiceSnapshot<TData, TError> {
     isPending: boolean;
     isSuccess: boolean;
 }
+/**
+ * Defines a subset of query state containing only the status and fetch status.
+ */
 export interface QueryMetaState {
     fetchStatus: QueryFetchStatus;
     status: QueryStatus;
 }
+/**
+ * Defines the public API for a query service.
+ */
 export interface QueryService<TData, TError> {
     getSnapshot: () => QueryServiceSnapshot<TData, TError>;
     subscribe: (listener: (snapshot: QueryServiceSnapshot<TData, TError>) => void) => () => void;
@@ -22,12 +31,30 @@ export interface QueryService<TData, TError> {
     invalidate: (options?: QueryInvalidateOptions) => Promise<void>;
     unsafe_getResult: () => QueryObserverResult<TData, TError>;
 }
+/**
+ * Combines options for invalidation behavior and filtering.
+ */
 export interface QueryInvalidateOptions extends Pick<InvalidateOptions, 'cancelRefetch' | 'throwOnError'>, Pick<InvalidateQueryFilters, 'refetchType'> {
 }
+/**
+ * Function signature for the query factory.
+ */
 export interface CreateQuery {
     <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>): QueryService<TData, TError>;
 }
+/**
+ * Configuration options for creating a query service, excluding function and key.
+ */
 export type QueryServiceOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, 'queryFn' | 'queryKey'>;
+/**
+ * Extracts and maps status and fetchStatus to our QueryMetaState interface.
+ */
 export declare function toQueryMetaState<TData, TError>(snapshot: Pick<QueryServiceSnapshot<TData, TError>, 'fetchStatus' | 'status'>): QueryMetaState;
+/**
+ * Helper function to check if the query is in its initial loading state.
+ */
 export declare function isQueryLoading(query: QueryMetaState): boolean;
+/**
+ * Prepares the query factory by binding it to a specific QueryClient instance.
+ */
 export declare function setupQuery(queryClient: QueryClient): CreateQuery;

package/dist/query.js

@@ -1,36 +1,61 @@
-import { QueryObserver, } from '@tanstack/query-core';
+import { 
+// Import QueryObserver to monitor and manage individual queries.
+QueryObserver, } from '@tanstack/query-core';
+/**
+ * Extracts and maps status and fetchStatus to our QueryMetaState interface.
+ */
 export function toQueryMetaState(snapshot) {
+    // Return a simplified state object for UI or other services.
     return {
         fetchStatus: snapshot.fetchStatus,
         status: snapshot.status,
     };
 }
+/**
+ * Helper function to check if the query is in its initial loading state.
+ */
 export function isQueryLoading(query) {
+    // Returns true if the query is both pending and actively fetching.
     return query.status === 'pending' && query.fetchStatus === 'fetching';
 }
+/**
+ * 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.
     return function createQuery(queryKey, queryFn, options) {
+        // Create a new QueryObserver instance to manage this specific query's lifecycle.
         const observer = new QueryObserver(queryClient, {
             ...options,
             queryFn,
             queryKey,
         });
+        // Return the implementation of the QueryService interface.
         return {
+            // Map the current observer state to our service's snapshot format.
             getSnapshot: () => toQueryServiceSnapshot(observer.getCurrentResult()),
+            // Subscribe to observer changes and notify the listener with updated snapshots.
             subscribe: (listener) => observer.subscribe((result) => {
                 listener(toQueryServiceSnapshot(result));
             }),
+            // Proxy the refetch call and map the async result back to a snapshot.
             refetch: async (options) => toQueryServiceSnapshot(await observer.refetch(options)),
+            // Trigger a targeted invalidation using the query's key and custom options.
             invalidate: (options) => queryClient.invalidateQueries({
                 exact: true,
                 queryKey,
                 ...(options?.refetchType === undefined ? {} : { refetchType: options.refetchType }),
             }, toInvalidateOptions(options)),
+            // Provide direct access to the raw observer result when needed.
             unsafe_getResult: () => observer.getCurrentResult(),
         };
     };
 }
+/**
+ * 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.
     return {
         data: result.data,
         error: result.error,
@@ -42,14 +67,20 @@ function toQueryServiceSnapshot(result) {
         isSuccess: result.isSuccess,
     };
 }
+/**
+ * Internal helper to safely transform our QueryInvalidateOptions to Tanstack InvalidateOptions.
+ */
 function toInvalidateOptions(options) {
+    // Return undefined if no options were provided.
     if (options === undefined) {
         return undefined;
     }
+    // Construct and filter the options object to avoid passing undefined values.
     const invalidateOptions = {
         ...(options.cancelRefetch === undefined ? {} : { cancelRefetch: options.cancelRefetch }),
         ...(options.throwOnError === undefined ? {} : { throwOnError: options.throwOnError }),
     };
+    // Return the resulting object if it contains any relevant properties.
     return Object.keys(invalidateOptions).length > 0 ? invalidateOptions : undefined;
 }
 //# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -1 +1 @@
-{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,aAAa,GAKd,MAAM,sBAAsB,CAAC;AA0D9B,MAAM,UAAU,gBAAgB,CAC9B,QAA6E;IAE7E,OAAO;QACL,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,MAAM,EAAE,QAAQ,CAAC,MAAM;KACxB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,OAAO,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,WAAW,KAAK,UAAU,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,WAAwB;IACjD,OAAO,SAAS,WAAW,CAOzB,QAAmB,EACnB,OAA+C,EAC/C,OAAiF;QAEjF,MAAM,QAAQ,GAAG,IAAI,aAAa,CAChC,WAAW,EACX;YACE,GAAG,OAAO;YACV,OAAO;YACP,QAAQ;SACT,CACF,CAAC;QAEF,OAAO;YACL,WAAW,EAAE,GAAG,EAAE,CAAC,sBAAsB,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC;YACtE,SAAS,EAAE,CAAC,QAAQ,EAAE,EAAE,CACtB,QAAQ,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,EAAE;gBAC5B,QAAQ,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC;YAC3C,CAAC,CAAC;YACJ,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAAC,sBAAsB,CAAC,MAAM,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACnF,UAAU,EAAE,CAAC,OAAO,EAAE,EAAE,CACtB,WAAW,CAAC,iBAAiB,CAC3B;gBACE,KAAK,EAAE,IAAI;gBACX,QAAQ;gBACR,GAAG,CAAC,OAAO,EAAE,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;aACpF,EACD,mBAAmB,CAAC,OAAO,CAAC,CAC7B;YACH,gBAAgB,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE;SACpD,CAAC;IACJ,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAC7B,MAA0C;IAE1C,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,SAAS,EAAE,MAAM,CAAC,SAAS;KAC5B,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAAC,OAAgC;IAC3D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,iBAAiB,GAAsB;QAC3C,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;QACxF,GAAG,CAAC,OAAO,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;KACtF,CAAC;IAEF,OAAO,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC;AACnF,CAAC"}
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo-query",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "TanStack Query service layer for the VEAMS StatusQuo ecosystem.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/__tests__/provider.spec.ts

@@ -1,27 +1,27 @@
 import { QueryClient } from '@tanstack/query-core';
 
-import { setupQueryProvider } from '../provider';
+import { setupQueryManager } from '../provider';
 
-describe('Cache API', () => {
-  it('exposes cache-level query client operations', async () => {
+describe('Query Manager API', () => {
+  it('exposes manager-level query client operations', async () => {
     const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
     const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
     const refetchQueriesSpy = jest.spyOn(queryClient, 'refetchQueries');
     const cancelQueriesSpy = jest.spyOn(queryClient, 'cancelQueries');
     const resetQueriesSpy = jest.spyOn(queryClient, 'resetQueries');
     const removeQueriesSpy = jest.spyOn(queryClient, 'removeQueries');
-    const cache = setupQueryProvider(queryClient);
+    const manager = setupQueryManager(queryClient);
 
-    cache.setQueryData<{ id: number }>(['user', 42], { id: 42 });
+    manager.setQueryData<{ id: number }>(['user', 42], { id: 42 });
 
-    expect(cache.getQueryData<{ id: number }>(['user', 42])).toEqual({ id: 42 });
-    expect(cache.unsafe_getClient()).toBe(queryClient);
+    expect(manager.getQueryData<{ id: number }>(['user', 42])).toEqual({ id: 42 });
+    expect(manager.unsafe_getClient()).toBe(queryClient);
 
-    await cache.invalidateQueries({ queryKey: ['user'] });
-    await cache.refetchQueries({ queryKey: ['user'] });
-    await cache.cancelQueries({ queryKey: ['user'] });
-    await cache.resetQueries({ queryKey: ['user'] });
-    cache.removeQueries({ queryKey: ['user'] });
+    await manager.invalidateQueries({ queryKey: ['user'] });
+    await manager.refetchQueries({ queryKey: ['user'] });
+    await manager.cancelQueries({ queryKey: ['user'] });
+    await manager.resetQueries({ queryKey: ['user'] });
+    manager.removeQueries({ queryKey: ['user'] });
 
     expect(invalidateQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
     expect(refetchQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });

package/src/index.ts

@@ -1,3 +1,6 @@
+// Re-export all mutation-related types and functions.
 export * from './mutation';
+// Re-export all query-related types and functions.
 export * from './query';
+// Re-export all provider-related types and functions for cache management.
 export * from './provider';

package/src/mutation.ts

@@ -1,44 +1,74 @@
 import {
+  // Import MutationObserver to observe and manage mutations.
   MutationObserver,
+  // Import type for the mutation function itself.
   type MutationFunction,
+  // Import options for executing a mutation.
   type MutateOptions,
+  // Import configuration options for the mutation observer.
   type MutationObserverOptions,
+  // Import the shape of the result returned by the mutation observer.
   type MutationObserverResult,
+  // Import the status enum for mutations from Tanstack Query.
   type MutationStatus as TanstackMutationStatus,
+  // Import the central QueryClient to interact with the cache.
   type QueryClient,
 } from '@tanstack/query-core';
 
+// Re-export MutationStatus for consistent naming within the service.
 export type MutationStatus = TanstackMutationStatus;
 
+/**
+ * Represents a stable snapshot of the mutation service's state.
+ */
 export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVariables = void> {
+  // The data returned from a successful mutation.
   data: TData | undefined;
+  // The error object if the mutation failed.
   error: TError | null;
+  // The current lifecycle status (idle, pending, success, error).
   status: MutationStatus;
+  // The variables used for the most recent mutation call.
   variables: TVariables | undefined;
+  // Convenience flag: true if the status is 'error'.
   isError: boolean;
+  // Convenience flag: true if the status is 'idle'.
   isIdle: boolean;
+  // Convenience flag: true if the status is 'pending'.
   isPending: boolean;
+  // Convenience flag: true if the status is 'success'.
   isSuccess: boolean;
 }
 
+/**
+ * Defines the public API for a mutation service.
+ */
 export interface MutationService<
   TData = unknown,
   TError = Error,
   TVariables = void,
   TOnMutateResult = unknown,
 > {
+  // Returns the current state snapshot of the mutation.
   getSnapshot: () => MutationServiceSnapshot<TData, TError, TVariables>;
+  // Subscribes a listener to state changes; returns an unsubscribe function.
   subscribe: (
     listener: (snapshot: MutationServiceSnapshot<TData, TError, TVariables>) => void
   ) => () => void;
+  // Triggers the mutation with the given variables and optional lifecycle callbacks.
   mutate: (
     variables: TVariables,
     options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>
   ) => Promise<TData>;
+  // Resets the mutation state back to its initial idle state.
   reset: () => void;
+  // Escape hatch: provides direct access to the underlying Tanstack Query observer result.
   unsafe_getResult: () => MutationObserverResult<TData, TError, TVariables, TOnMutateResult>;
 }
 
+/**
+ * Configuration options for creating a mutation service, excluding the mutation function itself.
+ */
 export type MutationServiceOptions<
   TData = unknown,
   TError = Error,
@@ -46,14 +76,23 @@ export type MutationServiceOptions<
   TOnMutateResult = unknown,
 > = Omit<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationFn'>;
 
+/**
+ * Function signature for the mutation factory.
+ */
 export interface CreateMutation {
   <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(
+    // 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>;
 }
 
+/**
+ * Prepares the mutation factory by binding it to a specific QueryClient instance.
+ */
 export function setupMutation(queryClient: QueryClient): CreateMutation {
+  // Returns the actual factory function for creating individual mutation services.
   return function createMutation<
     TData = unknown,
     TError = Error,
@@ -63,6 +102,7 @@ export function setupMutation(queryClient: QueryClient): CreateMutation {
     mutationFn: MutationFunction<TData, TVariables>,
     options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
   ): MutationService<TData, TError, TVariables, TOnMutateResult> {
+    // Create a new MutationObserver instance to manage this specific mutation's lifecycle.
     const observer = new MutationObserver<TData, TError, TVariables, TOnMutateResult>(
       queryClient,
       {
@@ -71,22 +111,32 @@ export function setupMutation(queryClient: QueryClient): CreateMutation {
       }
     );
 
+    // Return the implementation of the MutationService interface.
     return {
+      // Map the current observer state to our service's snapshot format.
       getSnapshot: () => toMutationServiceSnapshot(observer.getCurrentResult()),
+      // Subscribe to observer changes and notify the listener with updated snapshots.
       subscribe: (listener) =>
         observer.subscribe((result) => {
           listener(toMutationServiceSnapshot(result));
         }),
+      // Proxy the mutate call to the underlying observer.
       mutate: (variables, mutateOptions) => observer.mutate(variables, mutateOptions),
+      // Reset the underlying observer state.
       reset: () => observer.reset(),
+      // Provide direct access to the raw observer result when needed.
       unsafe_getResult: () => observer.getCurrentResult(),
     };
   };
 }
 
+/**
+ * Internal helper to transform a raw Tanstack mutation result into our public snapshot format.
+ */
 function toMutationServiceSnapshot<TData, TError, TVariables, TOnMutateResult>(
   result: MutationObserverResult<TData, TError, TVariables, TOnMutateResult>
 ): MutationServiceSnapshot<TData, TError, TVariables> {
+  // Extract and return the relevant fields for the UI or other services.
   return {
     data: result.data,
     error: result.error,

package/src/provider.ts

@@ -1,34 +1,63 @@
 import {
+  // Import the central QueryClient to handle management and state management.
   type QueryClient,
 } from '@tanstack/query-core';
 
+// Import mutation and query setup functions and their factory types.
 import { type CreateMutation, setupMutation } from './mutation';
 import { type CreateQuery, setupQuery } from './query';
 
-export interface CacheApi {
+/**
+ * Defines the public API for the query manager facade.
+ */
+export interface QueryManager {
+  // Factory for creating a mutation service within the context of this provider.
   createMutation: CreateMutation;
+  // Factory for creating a query service within the context of this provider.
   createQuery: CreateQuery;
+  // Cancels active queries for the specified filters.
   cancelQueries: QueryClient['cancelQueries'];
+  // Synchronously retrieves a snapshot of the current query data.
   getQueryData: QueryClient['getQueryData'];
+  // Marks queries as invalid to trigger a refetch if they are active.
   invalidateQueries: QueryClient['invalidateQueries'];
+  // Forces a refetch of queries matching the specified filters.
   refetchQueries: QueryClient['refetchQueries'];
+  // Removes queries from the management without canceling ongoing requests.
   removeQueries: QueryClient['removeQueries'];
+  // Resets queries to their initial state and refetches them.
   resetQueries: QueryClient['resetQueries'];
+  // Manually sets or updates data for a specific query in the manager.
   setQueryData: QueryClient['setQueryData'];
+  // Escape hatch: provides direct access to the underlying Tanstack QueryClient.
   unsafe_getClient: () => QueryClient;
 }
 
-export function setupQueryProvider(queryClient: QueryClient): CacheApi {
+/**
+ * Prepares the query manager facade by binding all actions to a specific QueryClient instance.
+ */
+export function setupQueryManager(queryClient: QueryClient): QueryManager {
+  // Return the implementation of the QueryManager interface.
   return {
+    // Bind mutation factory to this QueryClient.
     createMutation: setupMutation(queryClient),
+    // Bind query factory to this QueryClient.
     createQuery: setupQuery(queryClient),
+    // Proxy for canceling queries with this client context.
     cancelQueries: queryClient.cancelQueries.bind(queryClient),
+    // Proxy for retrieving query data with this client context.
     getQueryData: queryClient.getQueryData.bind(queryClient),
+    // Proxy for invalidating queries with this client context.
     invalidateQueries: queryClient.invalidateQueries.bind(queryClient),
+    // Proxy for refetching queries with this client context.
     refetchQueries: queryClient.refetchQueries.bind(queryClient),
+    // Proxy for removing queries with this client context.
     removeQueries: queryClient.removeQueries.bind(queryClient),
+    // Proxy for resetting queries with this client context.
     resetQueries: queryClient.resetQueries.bind(queryClient),
+    // Proxy for setting query data with this client context.
     setQueryData: queryClient.setQueryData.bind(queryClient),
+    // Provide an accessor for the raw client instance.
     unsafe_getClient: () => queryClient,
   };
 }

package/src/query.ts

@@ -1,48 +1,88 @@
 import {
+  // Import the fetch status enum (idle, fetching, paused).
   type FetchStatus,
+  // Import options for invalidating queries from the cache.
   type InvalidateOptions,
+  // Import filters to target specific queries during invalidation.
   type InvalidateQueryFilters,
+  // Import the central QueryClient to interact with the cache.
   type QueryClient,
+  // Import the function signature for an individual query.
   type QueryFunction,
+  // Import the stable identifier for a specific query in the cache.
   type QueryKey,
+  // Import QueryObserver to monitor and manage individual queries.
   QueryObserver,
+  // Import configuration options for the query observer.
   type QueryObserverOptions,
+  // Import the result shape returned by the query observer.
   type QueryObserverResult,
+  // Import options for manually refetching a query.
   type RefetchOptions,
+  // Import the status enum for query results (pending, success, error).
   type QueryStatus as TanstackQueryStatus,
 } from '@tanstack/query-core';
 
+// Re-export FetchStatus and QueryStatus for internal naming consistency.
 export type QueryFetchStatus = FetchStatus;
 export type QueryStatus = TanstackQueryStatus;
 
+/**
+ * Represents a stable snapshot of the query service's state.
+ */
 export interface QueryServiceSnapshot<TData, TError> {
+  // The data retrieved from a successful query.
   data: TData | undefined;
+  // The error object if the query failed.
   error: TError | null;
+  // The current network fetch status (idle, fetching, paused).
   fetchStatus: QueryFetchStatus;
+  // The current lifecycle status of the query (pending, success, error).
   status: QueryStatus;
+  // Convenience flag: true if the status is 'error'.
   isError: boolean;
+  // Convenience flag: true if the query is currently fetching data.
   isFetching: boolean;
+  // Convenience flag: true if the query is in the pending state.
   isPending: boolean;
+  // Convenience flag: true if the status is 'success'.
   isSuccess: boolean;
 }
 
+/**
+ * Defines a subset of query state containing only the status and fetch status.
+ */
 export interface QueryMetaState {
   fetchStatus: QueryFetchStatus;
   status: QueryStatus;
 }
 
+/**
+ * Defines the public API for a query service.
+ */
 export interface QueryService<TData, TError> {
+  // Returns the current state snapshot of the query.
   getSnapshot: () => QueryServiceSnapshot<TData, TError>;
+  // Subscribes a listener to state changes; returns an unsubscribe function.
   subscribe: (listener: (snapshot: QueryServiceSnapshot<TData, TError>) => void) => () => void;
+  // Manually triggers a refetch of this query.
   refetch: (options?: RefetchOptions) => Promise<QueryServiceSnapshot<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.
   unsafe_getResult: () => QueryObserverResult<TData, TError>;
 }
 
+/**
+ * Combines options for invalidation behavior and filtering.
+ */
 export interface QueryInvalidateOptions
   extends Pick<InvalidateOptions, 'cancelRefetch' | 'throwOnError'>,
     Pick<InvalidateQueryFilters, 'refetchType'> {}
 
+/**
+ * Function signature for the query factory.
+ */
 export interface CreateQuery {
   <
     TQueryFnData = unknown,
@@ -51,12 +91,18 @@ export interface CreateQuery {
     TQueryData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
+    // The key that uniquely identifies the query in the cache.
     queryKey: TQueryKey,
+    // 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>
   ): QueryService<TData, TError>;
 }
 
+/**
+ * Configuration options for creating a query service, excluding function and key.
+ */
 export type QueryServiceOptions<
   TQueryFnData = unknown,
   TError = Error,
@@ -68,20 +114,32 @@ export type QueryServiceOptions<
   'queryFn' | 'queryKey'
 >;
 
+/**
+ * Extracts and maps status and fetchStatus to our QueryMetaState interface.
+ */
 export function toQueryMetaState<TData, TError>(
   snapshot: Pick<QueryServiceSnapshot<TData, TError>, 'fetchStatus' | 'status'>
 ): QueryMetaState {
+  // Return a simplified state object for UI or other services.
   return {
     fetchStatus: snapshot.fetchStatus,
     status: snapshot.status,
   };
 }
 
+/**
+ * Helper function to check if the query is in its initial loading state.
+ */
 export function isQueryLoading(query: QueryMetaState): boolean {
+  // Returns true if the query is both pending and actively fetching.
   return query.status === 'pending' && query.fetchStatus === 'fetching';
 }
 
+/**
+ * Prepares the query factory by binding it to a specific QueryClient instance.
+ */
 export function setupQuery(queryClient: QueryClient): CreateQuery {
+  // Returns the actual factory function for creating individual query services.
   return function createQuery<
     TQueryFnData = unknown,
     TError = Error,
@@ -93,6 +151,7 @@ export function setupQuery(queryClient: QueryClient): CreateQuery {
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
     options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
   ): QueryService<TData, TError> {
+    // Create a new QueryObserver instance to manage this specific query's lifecycle.
     const observer = new QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>(
       queryClient,
       {
@@ -102,13 +161,18 @@ export function setupQuery(queryClient: QueryClient): CreateQuery {
       }
     );
 
+    // Return the implementation of the QueryService interface.
     return {
+      // Map the current observer state to our service's snapshot format.
       getSnapshot: () => toQueryServiceSnapshot(observer.getCurrentResult()),
+      // Subscribe to observer changes and notify the listener with updated snapshots.
       subscribe: (listener) =>
         observer.subscribe((result) => {
           listener(toQueryServiceSnapshot(result));
         }),
+      // Proxy the refetch call and map the async result back to a snapshot.
       refetch: async (options) => toQueryServiceSnapshot(await observer.refetch(options)),
+      // Trigger a targeted invalidation using the query's key and custom options.
       invalidate: (options) =>
         queryClient.invalidateQueries(
           {
@@ -118,14 +182,19 @@ export function setupQuery(queryClient: QueryClient): CreateQuery {
           },
           toInvalidateOptions(options)
         ),
+      // Provide direct access to the raw observer result when needed.
       unsafe_getResult: () => observer.getCurrentResult(),
     };
   };
 }
 
+/**
+ * Internal helper to transform a raw Tanstack query result into our public snapshot format.
+ */
 function toQueryServiceSnapshot<TData, TError>(
   result: QueryObserverResult<TData, TError>
 ): QueryServiceSnapshot<TData, TError> {
+  // Extract and return the relevant fields for the UI or other services.
   return {
     data: result.data,
     error: result.error,
@@ -138,15 +207,21 @@ function toQueryServiceSnapshot<TData, TError>(
   };
 }
 
+/**
+ * Internal helper to safely transform our QueryInvalidateOptions to Tanstack InvalidateOptions.
+ */
 function toInvalidateOptions(options?: QueryInvalidateOptions): InvalidateOptions | undefined {
+  // Return undefined if no options were provided.
   if (options === undefined) {
     return undefined;
   }
 
+  // Construct and filter the options object to avoid passing undefined values.
   const invalidateOptions: InvalidateOptions = {
     ...(options.cancelRefetch === undefined ? {} : { cancelRefetch: options.cancelRefetch }),
     ...(options.throwOnError === undefined ? {} : { throwOnError: options.throwOnError }),
   };
 
+  // Return the resulting object if it contains any relevant properties.
   return Object.keys(invalidateOptions).length > 0 ? invalidateOptions : undefined;
 }