@veams/status-quo-query 0.4.0 → 0.5.0

package/README.md

@@ -23,14 +23,25 @@ Root exports:
 - `QueryManager`
 - `CreateQuery`
 - `CreateMutation`
+- `CreateTrackedQuery`
+- `CreateTrackedMutation`
+- `CreateTrackedQueryAndMutation`
+- `CreateTrackedMutationWithDefaults`
 - `QueryService`
 - `MutationService`
 - `QueryServiceSnapshot`
 - `MutationServiceSnapshot`
 - `QueryServiceOptions`
 - `MutationServiceOptions`
+- `TrackedMutationServiceOptions`
 - `QueryInvalidateOptions`
 - `QueryMetaState`
+- `TrackedDependencyRecord`
+- `TrackedDependencyValue`
+- `TrackedInvalidateOn`
+- `TrackedMatchMode`
+- `TrackedQueryKey`
+- `TrackedQueryKeySegment`
 
 Subpath exports:
 
@@ -42,26 +53,334 @@ Subpath exports:
 
 ```ts
 import { QueryClient } from '@tanstack/query-core';
-import {
-  setupQueryManager,
-} from '@veams/status-quo-query';
+import { setupQueryManager } from '@veams/status-quo-query';
 
 const queryClient = new QueryClient();
 const manager = setupQueryManager(queryClient);
+const applicationId = 'app-1';
+const productId = 'product-1';
+
+const fetchProduct = async (currentApplicationId: string, currentProductId: string) => ({
+  applicationId: currentApplicationId,
+  name: 'Ada',
+  productId: currentProductId,
+});
+
+const saveProduct = async (variables: {
+  applicationId: string;
+  productId: string;
+  productName: string;
+}) => ({
+  ...variables,
+  saved: true as const,
+});
+
+const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+const productQuery = createTrackedQuery(
+  ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+  () => fetchProduct('app-1', 'product-1'),
+  {
+    enabled: false,
+  }
+);
+
+const updateProduct = createTrackedMutation(saveProduct, {
+  invalidateOn: 'success',
+});
+
+await productQuery.refetch();
+await updateProduct.mutate({
+  applicationId: 'app-1',
+  productId: 'product-1',
+  productName: 'Ada',
+});
 
 const userQuery = manager.createQuery(['user', 42], () => fetchUser(42), {
   enabled: false,
 });
 await userQuery.refetch();
 await userQuery.invalidate({ refetchType: 'none' });
+```
+
+## 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:
+
+- queries declare their domain dependencies once in `queryKey[..., { deps, view }]`
+- tracked mutations resolve the same dependency names from their variables
+- the manager invalidates matching queries automatically
+
+That changes the developer workflow from "remember which cache keys this mutation affects" to "describe which domain entities this query and mutation belong to".
+
+Benefits:
+
+- less manual cache invalidation code spread across features
+- lower risk of stale UI because one dependent query was forgotten
+- clearer separation between invalidation semantics in `deps` and UI variants in `view`
+- typed paired helpers that remove repeated dependency mapping in the common case
+
+## Examples
+
+Tracked query keys use a final object segment:
 
-const updateUser = manager.createMutation((payload: UpdateUserPayload) => saveUser(payload));
-await updateUser.mutate({ id: 42 });
+```ts
+['products', { deps: { applicationId, productId }, view: { page, sort } }]
+```
+
+Rules:
+
+- `deps` is required for tracked queries
+- only `deps` is used for invalidation matching
+- `view` is optional and recommended for pagination, sorting, filtering, and other cache variants
+- tracked invalidation is manager-only because queries and mutations need one shared registry
+
+### Paired Helper With Default Dependency Resolution
+
+Use the paired helper when mutation variables already expose the dependency keys directly:
+
+```ts
+import { QueryClient } from '@tanstack/query-core';
+import { setupQueryManager } from '@veams/status-quo-query';
 
-await manager.invalidateQueries({ queryKey: ['user'] });
-manager.setQueryData(['user', 42], (current) => current);
+const queryClient = new QueryClient();
+const manager = setupQueryManager(queryClient);
+const applicationId = 'app-1';
+const productId = 'product-1';
+
+const fetchProduct = async (currentApplicationId: string, currentProductId: string) => ({
+  applicationId: currentApplicationId,
+  name: 'Ada',
+  productId: currentProductId,
+});
+
+const saveProduct = async (variables: {
+  applicationId: string;
+  productId: string;
+  productName: string;
+}) => variables;
+
+const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+const productQuery = createTrackedQuery(
+  ['product', { deps: { applicationId, productId }, view: { page: 1 } }],
+  () => fetchProduct(applicationId, productId),
+  { enabled: false }
+);
+
+const saveProductMutation = createTrackedMutation(saveProduct);
+
+await saveProductMutation.mutate({
+  applicationId,
+  productId,
+  productName: 'New title',
+});
 ```
 
+In this shape the mutation does not need `resolveDependencies`, because the paired helper already knows which dependency keys to read from the mutation variables.
+
+### Default `intersection` Matching
+
+`intersection` is the default. A mutation invalidates only queries that match all provided dependency pairs:
+
+```ts
+import { QueryClient } from '@tanstack/query-core';
+import { setupQueryManager } from '@veams/status-quo-query';
+
+const queryClient = new QueryClient();
+const manager = setupQueryManager(queryClient);
+
+const fetchProduct = async (applicationId: string, productId: string) => ({
+  applicationId,
+  name: 'Ada',
+  productId,
+});
+
+const saveProduct = async (variables: {
+  applicationId: string;
+  productId: string;
+  productName: string;
+}) => variables;
+
+const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+createTrackedQuery(
+  ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+  () => fetchProduct('app-1', 'product-1')
+);
+
+createTrackedQuery(
+  ['product', { deps: { applicationId: 'app-1', productId: 'product-2' }, view: { page: 1 } }],
+  () => fetchProduct('app-1', 'product-2')
+);
+
+const renameProduct = createTrackedMutation(saveProduct);
+
+await renameProduct.mutate({
+  applicationId: 'app-1',
+  productId: 'product-1',
+  productName: 'Ada',
+});
+```
+
+Only the `app-1` / `product-1` query is invalidated.
+
+### `union` Matching
+
+Use `matchMode: 'union'` when a mutation should invalidate anything that matches any provided dependency pair:
+
+```ts
+import { QueryClient } from '@tanstack/query-core';
+import { setupQueryManager } from '@veams/status-quo-query';
+
+const queryClient = new QueryClient();
+const manager = setupQueryManager(queryClient);
+
+const fetchProduct = async (applicationId: string, productId: string) => ({
+  applicationId,
+  name: 'Ada',
+  productId,
+});
+
+const syncProductData = async (variables: {
+  applicationId: string;
+  productId: string;
+}) => variables;
+
+const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+createTrackedQuery(
+  ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+  () => fetchProduct('app-1', 'product-1')
+);
+
+createTrackedQuery(
+  ['product', { deps: { applicationId: 'app-2', productId: 'product-1' }, view: { page: 1 } }],
+  () => fetchProduct('app-2', 'product-1')
+);
+
+const syncProduct = createTrackedMutation(syncProductData, {
+  matchMode: 'union',
+});
+
+await syncProduct.mutate({
+  applicationId: 'app-1',
+  productId: 'product-1',
+});
+```
+
+This invalidates tracked queries that match:
+
+- `applicationId === 'app-1'`
+- or `productId === 'product-1'`
+
+Use it when a mutation affects a wider slice of cached state and exact intersection would be too narrow.
+
+### Partial Dependency Invalidation
+
+Tracked mutations may resolve only some dependency keys:
+
+```ts
+import { QueryClient } from '@tanstack/query-core';
+import { setupQueryManager } from '@veams/status-quo-query';
+
+const queryClient = new QueryClient();
+const manager = setupQueryManager(queryClient);
+
+const syncApplicationProducts = async (variables: { applicationId: string }) => variables;
+
+const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+const refreshApplicationProducts = createTrackedMutation(syncApplicationProducts);
+
+await refreshApplicationProducts.mutate({
+  applicationId: 'app-1',
+});
+```
+
+This invalidates all tracked queries that match `applicationId === 'app-1'`, regardless of `productId`.
+
+### Lifecycle Timing
+
+Automatic invalidation runs on success by default. Change `invalidateOn` when the mutation workflow needs different timing:
+
+```ts
+import { QueryClient } from '@tanstack/query-core';
+import { setupQueryManager } from '@veams/status-quo-query';
+
+const queryClient = new QueryClient();
+const manager = setupQueryManager(queryClient);
+
+const removeProduct = async (variables: { applicationId: string }) => variables;
+
+const [createTrackedQuery, createTrackedMutation] = manager.createTrackedQueryAndMutation([
+  'applicationId',
+] as const);
+
+const cleanupMutation = createTrackedMutation(removeProduct, {
+  invalidateOn: 'settled',
+});
+```
+
+Supported values:
+
+- `'success'` invalidates only after a successful mutation
+- `'error'` invalidates only after a failed mutation
+- `'settled'` invalidates after either outcome
+
+### Custom Dependency Resolution
+
+Use `resolveDependencies` when mutation variables do not expose the tracked keys directly:
+
+```ts
+import { QueryClient } from '@tanstack/query-core';
+import { setupQueryManager } from '@veams/status-quo-query';
+
+const queryClient = new QueryClient();
+const manager = setupQueryManager(queryClient);
+
+const saveProduct = async (variables: {
+  payload: { applicationId: string };
+  product: { id: string };
+  productName: string;
+}) => variables;
+
+const nestedMutation = manager.createTrackedMutation(saveProduct, {
+  resolveDependencies: (variables: {
+    payload: { applicationId: string };
+    product: { id: string };
+  }) => ({
+    applicationId: variables.payload.applicationId,
+    productId: variables.product.id,
+  }),
+});
+
+await nestedMutation.mutate({
+  payload: { applicationId: 'app-1' },
+  product: { id: 'product-1' },
+});
+```
+
+Standalone tracked mutations need either:
+
+- `dependencyKeys`
+- or `resolveDependencies`
+
 ## API
 
 ### `setupQueryManager(queryClient)`
@@ -72,6 +391,9 @@ Returns `QueryManager` with:
 
 - `createQuery(queryKey, queryFn, options?)`
 - `createMutation(mutationFn, options?)`
+- `createTrackedQuery(queryKey, queryFn, options?)`
+- `createTrackedMutation(mutationFn, options?)`
+- `createTrackedQueryAndMutation(dependencyKeys)`
 - `cancelQueries(...)`
 - `getQueryData(...)`
 - `invalidateQueries(...)`
@@ -83,6 +405,49 @@ Returns `QueryManager` with:
 
 All manager methods forward directly to the corresponding `QueryClient` methods. `unsafe_getClient()` returns the raw TanStack client as an explicit escape hatch.
 
+### Tracked Queries and Mutations
+
+Tracked queries embed dependency metadata into the final query-key segment:
+
+```ts
+['products', { deps: { applicationId, productId }, view: { page, sort } }]
+```
+
+Only `deps` participates in automatic invalidation tracking. `view` is optional and is treated as normal query-key data.
+
+`createTrackedQuery(queryKey, queryFn, options?)` returns the same `QueryService<TData, TError>` shape as `createQuery(...)`, but it registers the query hash under every `deps` entry and re-registers on `refetch()` or the first `subscribe(...)` if TanStack has removed the cache entry in the meantime.
+
+`createTrackedMutation(mutationFn, options?)` returns the same `MutationService<TData, TError, TVariables, TOnMutateResult>` shape as `createMutation(...)`, but adds:
+
+- `dependencyKeys?`
+- `resolveDependencies?`
+- `invalidateOn?` with `'success' | 'error' | 'settled'`
+- `matchMode?` with `'intersection' | 'union'`
+
+Standalone tracked mutations need either `dependencyKeys` or `resolveDependencies`.
+
+`createTrackedQueryAndMutation(dependencyKeys)` captures dependency keys once and returns:
+
+- the tracked query factory
+- a tracked mutation factory whose default resolver reads `variables[dependencyKey]`
+
+Use `resolveDependencies` when the mutation variables do not expose the tracked dependency fields directly.
+
+### `createTrackedQueryAndMutation(dependencyKeys)`
+
+Captures dependency names once and returns:
+
+- the tracked query factory
+- a tracked mutation factory whose default resolver reads `variables[dependencyKey]`
+
+The tracked query factory still expects a query key with a final `{ deps, view? }` segment. The tracked mutation factory keeps the same `MutationService` shape as `createMutation(...)`, but no longer needs `dependencyKeys` repeated in each call.
+
+Reach for standalone `createTrackedMutation(...)` when:
+
+- query and mutation do not share one dependency-key list
+- mutation variables need a custom `resolveDependencies(...)`
+- you want one tracked mutation without pairing it to one tracked query workflow
+
 ### `setupQuery(queryClient)`
 
 Creates a `createQuery` factory bound to a `QueryClient`.
@@ -171,3 +536,4 @@ Creates a `createMutation` factory bound to a `QueryClient`.
 - Commands live on the handle itself: `refetch`, `invalidate`, `mutate`, `reset`.
 - Raw TanStack observer and client access is explicit through `unsafe_getResult()` and `unsafe_getClient()`.
 - Manager-level operations live on `setupQueryManager()`, not on individual snapshots.
+- Tracked invalidation is manager-only because the registry must be shared across query and mutation handles.

package/dist/index.d.ts

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

package/dist/mutation.d.ts

@@ -1,4 +1,5 @@
 import { type MutationFunction, type MutateOptions, type MutationObserverOptions, type MutationObserverResult, type MutationStatus as TanstackMutationStatus, type QueryClient } from '@tanstack/query-core';
+import { type TrackedDependencyRecord, type TrackingRegistry, type TrackedInvalidateOn, type TrackedMatchMode } from './tracking';
 export type MutationStatus = TanstackMutationStatus;
 /**
  * Represents a stable snapshot of the mutation service's state.
@@ -33,7 +34,34 @@ export type MutationServiceOptions<TData = unknown, TError = Error, TVariables =
 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>;
 }
+/**
+ * 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> {
+    dependencyKeys?: readonly (keyof TDeps & string)[];
+    resolveDependencies?: (variables: TVariables) => Partial<TDeps>;
+    invalidateOn?: TrackedInvalidateOn;
+    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.
  */
 export declare function setupMutation(queryClient: QueryClient): CreateMutation;
+/**
+ * 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 declare function setupTrackedMutation(queryClient: QueryClient, trackingRegistry: TrackingRegistry, defaultDependencyKeys?: readonly string[]): CreateTrackedMutation;

package/dist/mutation.js

@@ -1,31 +1,70 @@
 import { 
 // Import MutationObserver to observe and manage mutations.
 MutationObserver, } from '@tanstack/query-core';
+import { pickTrackedDependencies, resolveTrackedQueries, toTrackedDependencyEntries, } from './tracking';
 /**
  * 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 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, trackingRegistry, defaultDependencyKeys) {
+    return function createTrackedMutation(mutationFn, options) {
+        // 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) => {
+            // 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 {
-            // 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;
+                }
+            },
         };
     };
 }
@@ -45,4 +84,33 @@ function toMutationServiceSnapshot(result) {
         isSuccess: result.isSuccess,
     };
 }
+function createMutationService(queryClient, mutationFn, options) {
+    // 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(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(variables, dependencyKeys, resolveDependencies) {
+    // 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);
+}
 //# sourceMappingURL=mutation.js.map

package/dist/mutation.js.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"mutation.js","sourceRoot":"","sources":["../src/mutation.ts"],"names":[],"mappings":"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"}

package/dist/provider.d.ts

@@ -1,12 +1,31 @@
-import { type QueryClient } from '@tanstack/query-core';
-import { type CreateMutation } from './mutation';
-import { type CreateQuery } from './query';
+import { type QueryClient, type MutationFunction } from '@tanstack/query-core';
+import { type CreateMutation, type CreateTrackedMutation, type MutationService, type TrackedMutationServiceOptions } from './mutation';
+import { type CreateQuery, type CreateTrackedQuery } from './query';
+import { 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.
  */
 export interface QueryManager {
     createMutation: CreateMutation;
     createQuery: CreateQuery;
+    createTrackedQuery: CreateTrackedQuery;
+    createTrackedMutation: CreateTrackedMutation;
+    createTrackedQueryAndMutation: CreateTrackedQueryAndMutation;
     cancelQueries: QueryClient['cancelQueries'];
     getQueryData: QueryClient['getQueryData'];
     invalidateQueries: QueryClient['invalidateQueries'];