@veams/status-quo-query 0.4.0 → 0.5.0

package/src/__tests__/tracked.spec.ts

@@ -0,0 +1,276 @@
+import { QueryClient } from '@tanstack/query-core';
+
+import { setupQueryManager } from '../provider';
+
+describe('Tracked Query Invalidation', () => {
+  it('registers tracked queries from deps and ignores view data during invalidation', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+      'applicationId',
+      'productId',
+    ] as const);
+
+    createTrackedQuery(
+      [
+        'product',
+        {
+          deps: { applicationId: 'app-1', productId: 'product-1' },
+          view: { page: 2, sort: 'name' },
+        },
+      ],
+      jest.fn().mockResolvedValue('product'),
+      { enabled: false }
+    );
+
+    const mutation = createTrackedMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    await mutation.mutate({
+      applicationId: 'app-1',
+      productId: 'product-1',
+      productName: 'Renamed',
+    });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      exact: true,
+      queryKey: [
+        'product',
+        {
+          deps: { applicationId: 'app-1', productId: 'product-1' },
+          view: { page: 2, sort: 'name' },
+        },
+      ],
+    });
+  });
+
+  it('rejects tracked query keys without a deps object', () => {
+    const manager = setupQueryManager(new QueryClient());
+
+    expect(() =>
+      manager.createTrackedQuery(
+        ['invalid', { view: { page: 1 } }] as never,
+        jest.fn().mockResolvedValue('nope')
+      )
+    ).toThrow('Tracked queries require queryKey[queryKey.length - 1].deps to be a plain object.');
+  });
+
+  it('supports partial dependency invalidation by matching only the provided keys', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+      'applicationId',
+      'productId',
+    ] as const);
+
+    createTrackedQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+      jest.fn().mockResolvedValue('page-1'),
+      { enabled: false }
+    );
+    createTrackedQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-2' }, view: { page: 2 } }],
+      jest.fn().mockResolvedValue('page-2'),
+      { enabled: false }
+    );
+
+    const mutation = createTrackedMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    await mutation.mutate({ applicationId: 'app-1', productName: 'Shared update' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('supports union matching and dedupes invalidation calls per query', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+      'applicationId',
+      'productId',
+    ] as const);
+
+    createTrackedQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+      jest.fn().mockResolvedValue('product-1'),
+      { enabled: false }
+    );
+    createTrackedQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-2' }, view: { page: 2 } }],
+      jest.fn().mockResolvedValue('product-2'),
+      { enabled: false }
+    );
+    createTrackedQuery(
+      ['product', { deps: { applicationId: 'app-2', productId: 'product-1' }, view: { page: 3 } }],
+      jest.fn().mockResolvedValue('product-3'),
+      { enabled: false }
+    );
+
+    const mutation = createTrackedMutation(jest.fn().mockResolvedValue({ ok: true as const }), {
+      matchMode: 'union',
+    });
+
+    await mutation.mutate({ applicationId: 'app-1', productId: 'product-1' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(3);
+  });
+
+  it('supports custom dependency resolution for nested mutation variables', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+
+    manager.createTrackedQuery(
+      ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+      jest.fn().mockResolvedValue('product'),
+      { enabled: false }
+    );
+
+    const mutation = manager.createTrackedMutation(
+      jest.fn().mockResolvedValue({ ok: true as const }),
+      {
+        resolveDependencies: (variables: {
+          payload: { applicationId: string };
+          product: { id: string };
+        }) => ({
+          applicationId: variables.payload.applicationId,
+          productId: variables.product.id,
+        }),
+      }
+    );
+
+    await mutation.mutate({
+      payload: { applicationId: 'app-1' },
+      product: { id: 'product-1' },
+    });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('supports error and settled invalidation timing', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+      'applicationId',
+    ] as const);
+
+    createTrackedQuery(
+      ['product', { deps: { applicationId: 'app-1' }, view: { page: 1 } }],
+      jest.fn().mockResolvedValue('product'),
+      { enabled: false }
+    );
+
+    const invalidateOnError = createTrackedMutation(jest.fn().mockRejectedValue(new Error('boom')), {
+      invalidateOn: 'error',
+    });
+    const invalidateOnSettled = createTrackedMutation(
+      jest.fn().mockRejectedValue(new Error('boom again')),
+      {
+        invalidateOn: 'settled',
+      }
+    );
+
+    await expect(invalidateOnError.mutate({ applicationId: 'app-1' })).rejects.toThrow('boom');
+    await expect(invalidateOnSettled.mutate({ applicationId: 'app-1' })).rejects.toThrow(
+      'boom again'
+    );
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it('cleans removed query hashes out of dependency buckets', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const cacheGetSpy = jest.spyOn(queryClient.getQueryCache(), 'get');
+    const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+      'applicationId',
+    ] as const);
+
+    const removedQueryKey = [
+      'product',
+      { deps: { applicationId: 'app-1' }, view: { page: 1 } },
+    ] as const;
+
+    createTrackedQuery(removedQueryKey, jest.fn().mockResolvedValue('page-1'), {
+      enabled: false,
+    });
+    queryClient.removeQueries({ exact: true, queryKey: removedQueryKey });
+
+    createTrackedQuery(
+      ['product', { deps: { applicationId: 'app-1' }, view: { page: 2 } }],
+      jest.fn().mockResolvedValue('page-2'),
+      { enabled: false }
+    );
+    cacheGetSpy.mockClear();
+
+    const mutation = createTrackedMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    await mutation.mutate({ applicationId: 'app-1' });
+
+    expect(cacheGetSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-registers tracked queries on refetch after TanStack cache removal', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+      'applicationId',
+    ] as const);
+    const queryKey = ['product', { deps: { applicationId: 'app-1' }, view: { page: 1 } }] as const;
+    const query = createTrackedQuery(queryKey, jest.fn().mockResolvedValue('product'), {
+      enabled: false,
+    });
+    const mutation = createTrackedMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    queryClient.removeQueries({ exact: true, queryKey });
+
+    await mutation.mutate({ applicationId: 'app-1' });
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(0);
+
+    await query.refetch();
+    await mutation.mutate({ applicationId: 'app-1' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-registers tracked queries on subscribe after TanStack cache removal', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+      'applicationId',
+    ] as const);
+    const queryKey = ['product', { deps: { applicationId: 'app-1' }, view: { page: 1 } }] as const;
+    const query = createTrackedQuery(queryKey, jest.fn().mockResolvedValue('product'), {
+      enabled: false,
+    });
+    const mutation = createTrackedMutation(jest.fn().mockResolvedValue({ ok: true as const }));
+
+    queryClient.removeQueries({ exact: true, queryKey });
+
+    const unsubscribe = query.subscribe(() => undefined);
+    await mutation.mutate({ applicationId: 'app-1' });
+    unsubscribe();
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/index.ts

@@ -4,3 +4,12 @@ export * from './mutation';
 export * from './query';
 // Re-export all provider-related types and functions for cache management.
 export * from './provider';
+// Re-export tracked dependency types used by the additive tracked facade.
+export type {
+  TrackedDependencyRecord,
+  TrackedDependencyValue,
+  TrackedInvalidateOn,
+  TrackedMatchMode,
+  TrackedQueryKey,
+  TrackedQueryKeySegment,
+} from './tracking';

package/src/mutation.ts

@@ -15,6 +15,17 @@ import {
   type QueryClient,
 } from '@tanstack/query-core';
 
+import {
+  type TrackedDependencyRecord,
+  type TrackingRegistry,
+  type TrackedInvalidateOn,
+  type TrackedMatchMode,
+  type TrackedDependencyValue,
+  pickTrackedDependencies,
+  resolveTrackedQueries,
+  toTrackedDependencyEntries,
+} from './tracking';
+
 // Re-export MutationStatus for consistent naming within the service.
 export type MutationStatus = TanstackMutationStatus;
 
@@ -88,6 +99,46 @@ export interface CreateMutation {
   ): MutationService<TData, TError, TVariables, TOnMutateResult>;
 }
 
+/**
+ * Additional options for tracked mutations that invalidate queries automatically.
+ *
+ * The tracked mutation still behaves like a normal mutation service from the outside. These
+ * 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<
+  TDeps extends TrackedDependencyRecord = TrackedDependencyRecord,
+  TData = unknown,
+  TError = Error,
+  TVariables = void,
+  TOnMutateResult = unknown,
+> extends MutationServiceOptions<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.
+  resolveDependencies?: (variables: TVariables) => Partial<TDeps>;
+  // Lifecycle hook that triggers automatic invalidation.
+  invalidateOn?: TrackedInvalidateOn;
+  // Matching strategy for resolved dependencies.
+  matchMode?: TrackedMatchMode;
+}
+
+/**
+ * Function signature for tracked mutation factories.
+ */
+export interface CreateTrackedMutation {
+  <
+    TDeps extends TrackedDependencyRecord = TrackedDependencyRecord,
+    TData = unknown,
+    TError = Error,
+    TVariables = void,
+    TOnMutateResult = unknown,
+  >(
+    mutationFn: MutationFunction<TData, TVariables>,
+    options?: TrackedMutationServiceOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
+  ): MutationService<TData, TError, TVariables, TOnMutateResult>;
+}
+
 /**
  * Prepares the mutation factory by binding it to a specific QueryClient instance.
  */
@@ -102,30 +153,98 @@ 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,
-      {
-        ...options,
-        mutationFn,
-      }
-    );
+    return createMutationService(queryClient, mutationFn, options);
+  };
+}
+
+/**
+ * Prepares a tracked mutation factory that coordinates invalidation through the shared registry.
+ *
+ * The implementation intentionally wraps the normal mutation service instead of re-implementing
+ * TanStack lifecycle behavior. TanStack still owns retries, callbacks, and state transitions;
+ * the facade only adds dependency resolution plus the follow-up invalidation pass.
+ */
+export function setupTrackedMutation(
+  queryClient: QueryClient,
+  trackingRegistry: TrackingRegistry,
+  defaultDependencyKeys?: readonly string[]
+): CreateTrackedMutation {
+  return function createTrackedMutation<
+    TDeps extends TrackedDependencyRecord = TrackedDependencyRecord,
+    TData = unknown,
+    TError = Error,
+    TVariables = void,
+    TOnMutateResult = unknown,
+  >(
+    mutationFn: MutationFunction<TData, TVariables>,
+    options?: TrackedMutationServiceOptions<TDeps, TData, TError, TVariables, TOnMutateResult>
+  ): MutationService<TData, TError, TVariables, TOnMutateResult> {
+    // Split tracked-only options from the underlying TanStack mutation observer options.
+    const {
+      dependencyKeys,
+      invalidateOn = 'success',
+      matchMode = 'intersection',
+      resolveDependencies,
+      ...mutationOptions
+    } = options ?? {};
+    // Reuse the normal mutation service so snapshots and subscription behavior stay identical.
+    const service = createMutationService(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);
+
+    const invalidateTrackedQueries = async (variables: TVariables) => {
+      // Resolve the mutation variables into the same named dependency shape that tracked queries
+      // registered under when they were created.
+      const dependencies = resolveTrackedMutationDependencies(
+        variables,
+        resolvedDependencyKeys,
+        resolveDependencies
+      );
+      // Ask the registry for matching query hashes using the selected invalidation breadth.
+      const queryHashes = trackingRegistry.match(
+        toTrackedDependencyEntries(dependencies, 'Tracked mutation dependency resolution'),
+        matchMode
+      );
+      // Filter the registry result down to currently live TanStack queries before invalidating.
+      const queries = resolveTrackedQueries(queryClient, queryHashes);
+
+      await Promise.all(
+        queries.map((query) =>
+          queryClient.invalidateQueries({
+            exact: true,
+            queryKey: query.queryKey,
+          })
+        )
+      );
+    };
 
-    // 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(),
+      ...service,
+      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);
+
+          if (invalidateOn === 'success' || invalidateOn === 'settled') {
+            await invalidateTrackedQueries(variables);
+          }
+
+          return result;
+        } catch (error) {
+          if (invalidateOn === 'error' || invalidateOn === 'settled') {
+            try {
+              await invalidateTrackedQueries(variables);
+            } catch {
+              // Preserve the original mutation failure as the primary rejection. If invalidation
+              // also fails here, the caller still sees the mutation error that triggered this path.
+            }
+          }
+
+          throw error;
+        }
+      },
     };
   };
 }
@@ -148,3 +267,58 @@ function toMutationServiceSnapshot<TData, TError, TVariables, TOnMutateResult>(
     isSuccess: result.isSuccess,
   };
 }
+
+function createMutationService<
+  TData = unknown,
+  TError = Error,
+  TVariables = void,
+  TOnMutateResult = unknown,
+>(
+  queryClient: QueryClient,
+  mutationFn: MutationFunction<TData, TVariables>,
+  options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
+): MutationService<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, {
+    ...options,
+    mutationFn,
+  });
+
+  return {
+    getSnapshot: () => toMutationServiceSnapshot(observer.getCurrentResult()),
+    subscribe: (listener) =>
+      observer.subscribe((result) => {
+        listener(toMutationServiceSnapshot(result));
+      }),
+    mutate: (variables, mutateOptions) => observer.mutate(variables, mutateOptions),
+    reset: () => observer.reset(),
+    unsafe_getResult: () => observer.getCurrentResult(),
+  };
+}
+
+function resolveTrackedMutationDependencies<
+  TDeps extends TrackedDependencyRecord,
+  TVariables,
+>(
+  variables: TVariables,
+  dependencyKeys: readonly (keyof TDeps & string)[] | undefined,
+  resolveDependencies:
+    | ((variables: TVariables) => Partial<TDeps>)
+    | undefined
+): Partial<Record<string, TrackedDependencyValue>> {
+  // A custom resolver takes precedence because it can adapt nested payloads or renamed fields.
+  if (resolveDependencies) {
+    return resolveDependencies(variables);
+  }
+
+  // Without a custom resolver, tracked mutations need known dependency keys so the default
+  // variable picker knows which fields are invalidation-relevant.
+  if (!dependencyKeys || dependencyKeys.length === 0) {
+    throw new Error(
+      'Tracked mutations require resolveDependencies or dependencyKeys to derive invalidation targets.'
+    );
+  }
+
+  return pickTrackedDependencies(dependencyKeys, variables);
+}

package/src/provider.ts

@@ -1,11 +1,54 @@
 import {
   // Import the central QueryClient to handle management and state management.
   type QueryClient,
+  type MutationFunction,
 } 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';
+import {
+  type CreateMutation,
+  type CreateTrackedMutation,
+  type MutationService,
+  type TrackedMutationServiceOptions,
+  setupMutation,
+  setupTrackedMutation,
+} from './mutation';
+import { type CreateQuery, type CreateTrackedQuery, setupQuery, setupTrackedQuery } from './query';
+import {
+  createTrackingRegistry,
+  type TrackedDependencyValue,
+} from './tracking';
+
+/**
+ * Mutation factory returned by the paired tracked helper.
+ *
+ * This omits `dependencyKeys` on purpose because the paired helper already captured those keys
+ * once at setup time and injects them automatically for each tracked mutation it creates.
+ */
+export interface CreateTrackedMutationWithDefaults<TDependencyKey extends string> {
+  <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(
+    mutationFn: MutationFunction<TData, TVariables>,
+    options?: Omit<
+      TrackedMutationServiceOptions<
+        Record<TDependencyKey, TrackedDependencyValue>,
+        TData,
+        TError,
+        TVariables,
+        TOnMutateResult
+      >,
+      'dependencyKeys'
+    >
+  ): MutationService<TData, TError, TVariables, TOnMutateResult>;
+}
+
+/**
+ * Paired tracked helper that captures dependency keys once for default mutation resolution.
+ */
+export interface CreateTrackedQueryAndMutation {
+  <const TDependencyKeys extends readonly string[]>(
+    dependencyKeys: TDependencyKeys
+  ): readonly [CreateTrackedQuery, CreateTrackedMutationWithDefaults<TDependencyKeys[number]>];
+}
 
 /**
  * Defines the public API for the query manager facade.
@@ -15,6 +58,12 @@ export interface QueryManager {
   createMutation: CreateMutation;
   // Factory for creating a query service within the context of this provider.
   createQuery: CreateQuery;
+  // Factory for creating tracked query services with dependency-aware query keys.
+  createTrackedQuery: CreateTrackedQuery;
+  // Factory for creating tracked mutation services with automatic invalidation.
+  createTrackedMutation: CreateTrackedMutation;
+  // Convenience helper that shares dependency keys between tracked queries and mutations.
+  createTrackedQueryAndMutation: CreateTrackedQueryAndMutation;
   // Cancels active queries for the specified filters.
   cancelQueries: QueryClient['cancelQueries'];
   // Synchronously retrieves a snapshot of the current query data.
@@ -37,12 +86,65 @@ export interface QueryManager {
  * Prepares the query manager facade by binding all actions to a specific QueryClient instance.
  */
 export function setupQueryManager(queryClient: QueryClient): QueryManager {
+  // One shared registry is the whole point of the manager-only tracked API. Queries and
+  // mutations created from the same manager can now coordinate invalidation through it.
+  const trackingRegistry = createTrackingRegistry();
+  const trackedQueryFactory = setupTrackedQuery(queryClient, trackingRegistry);
+  const trackedMutationFactory = setupTrackedMutation(queryClient, trackingRegistry);
+
+  queryClient.getQueryCache().subscribe((event) => {
+    if (event.type === 'removed') {
+      // When TanStack GC removes a query from the live cache, drop its hash from our registry too.
+      // A later tracked `refetch()` or first `subscribe()` will re-register it if it becomes live
+      // again. This keeps the registry aligned with TanStack's actual cache lifetime.
+      trackingRegistry.unregister(event.query.queryHash);
+    }
+  });
+
   // 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),
+    // Bind tracked query factory to this client and registry.
+    createTrackedQuery: trackedQueryFactory,
+    // Bind tracked mutation factory to this client and registry.
+    createTrackedMutation: trackedMutationFactory,
+    // Provide a paired helper that captures dependency keys once.
+    createTrackedQueryAndMutation: <const TDependencyKeys extends readonly string[]>(
+      dependencyKeys: TDependencyKeys
+    ) => {
+      const createTrackedMutationWithDefaults: CreateTrackedMutationWithDefaults<
+        TDependencyKeys[number]
+      > = <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(
+        mutationFn: MutationFunction<TData, TVariables>,
+        options?: Omit<
+          TrackedMutationServiceOptions<
+            Record<TDependencyKeys[number], TrackedDependencyValue>,
+            TData,
+            TError,
+            TVariables,
+            TOnMutateResult
+          >,
+          'dependencyKeys'
+        >
+      ) =>
+        // Inject the dependency keys once so the paired mutation factory can derive dependency
+        // values directly from mutation variables without repeating the mapping each time.
+        trackedMutationFactory<
+          Record<TDependencyKeys[number], TrackedDependencyValue>,
+          TData,
+          TError,
+          TVariables,
+          TOnMutateResult
+        >(mutationFn, {
+          ...options,
+          dependencyKeys,
+        });
+
+      return [trackedQueryFactory, createTrackedMutationWithDefaults] as const;
+    },
     // Proxy for canceling queries with this client context.
     cancelQueries: queryClient.cancelQueries.bind(queryClient),
     // Proxy for retrieving query data with this client context.