@veams/status-quo-query 0.4.0 → 0.6.0

package/README.md

@@ -23,14 +23,25 @@ Root exports:
 - `QueryManager`
 - `CreateQuery`
 - `CreateMutation`
+- `CreateQueryAndMutation`
+- `CreateMutationWithDefaults`
+- `CreateUntrackedQuery`
+- `CreateUntrackedMutation`
 - `QueryService`
 - `MutationService`
 - `QueryServiceSnapshot`
 - `MutationServiceSnapshot`
 - `QueryServiceOptions`
 - `MutationServiceOptions`
+- `TrackedMutationServiceOptions`
 - `QueryInvalidateOptions`
 - `QueryMetaState`
+- `TrackedDependencyRecord`
+- `TrackedDependencyValue`
+- `TrackedInvalidateOn`
+- `TrackedMatchMode`
+- `TrackedQueryKey`
+- `TrackedQueryKeySegment`
 
 Subpath exports:
 
@@ -42,26 +53,392 @@ 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 userQuery = manager.createQuery(['user', 42], () => fetchUser(42), {
+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 fetchUser = async (userId: number) => ({ id: userId, name: 'Ada' });
+
+const [createQuery, createMutation] = manager.createQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+const productQuery = createQuery(
+  ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+  () => fetchProduct('app-1', 'product-1'),
+  {
+    enabled: false,
+  }
+);
+
+const updateProduct = createMutation(saveProduct, {
+  invalidateOn: 'success',
+});
+
+await productQuery.refetch();
+await updateProduct.mutate({
+  applicationId: 'app-1',
+  productId: 'product-1',
+  productName: 'Ada',
+});
+
+const userQuery = manager.createUntrackedQuery(['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:
+
+```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';
+
+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 [createQuery, createMutation] = manager.createQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+const productQuery = createQuery(
+  ['product', { deps: { applicationId, productId }, view: { page: 1 } }],
+  () => fetchProduct(applicationId, productId),
+  { enabled: false }
+);
+
+const saveProductMutation = createMutation(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 [createQuery, createMutation] = manager.createQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+createQuery(
+  ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+  () => fetchProduct('app-1', 'product-1')
+);
+
+createQuery(
+  ['product', { deps: { applicationId: 'app-1', productId: 'product-2' }, view: { page: 1 } }],
+  () => fetchProduct('app-1', 'product-2')
+);
+
+const renameProduct = createMutation(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 [createQuery, createMutation] = manager.createQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+createQuery(
+  ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+  () => fetchProduct('app-1', 'product-1')
+);
+
+createQuery(
+  ['product', { deps: { applicationId: 'app-2', productId: 'product-1' }, view: { page: 1 } }],
+  () => fetchProduct('app-2', 'product-1')
+);
+
+const syncProduct = createMutation(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 [createQuery, createMutation] = manager.createQueryAndMutation([
+  'applicationId',
+  'productId',
+] as const);
+
+createQuery(
+  ['product', { deps: { applicationId: 'app-1', productId: 'product-1' }, view: { page: 1 } }],
+  async () => ({ applicationId: 'app-1', productId: 'product-1' })
+);
+
+const refreshApplicationProducts = createMutation(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 updateUser = manager.createMutation((payload: UpdateUserPayload) => saveUser(payload));
-await updateUser.mutate({ id: 42 });
+const removeProduct = async (variables: { applicationId: string }) => variables;
 
-await manager.invalidateQueries({ queryKey: ['user'] });
-manager.setQueryData(['user', 42], (current) => current);
+const [createQuery, createMutation] = manager.createQueryAndMutation([
+  'applicationId',
+] as const);
+
+createQuery(
+  ['product-list', { deps: { applicationId: 'app-1' }, view: { page: 1 } }],
+  async () => [{ applicationId: 'app-1', productId: 'product-1' }]
+);
+
+const cleanupMutation = createMutation(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.createMutation(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`
+
+## FAQ
+
+### Is `view` still part of the TanStack cache key?
+
+Yes. TanStack uses the full query key for cache identity, so these are different cache entries:
+
+```ts
+['products', { deps: { applicationId: 'app-1' }, view: { page: 1 } }]
+['products', { deps: { applicationId: 'app-1' }, view: { page: 2 } }]
+```
+
+That means `view` still matters for pagination, sorting, filtering, and any other cache variant you want TanStack to separate.
+
+### Why does tracked invalidation ignore `view`?
+
+Because `view` usually describes how the same domain data is presented, not what domain entity the query depends on.
+
+If tracked invalidation matched on `view`, mutations would often miss related cache entries:
+
+- renaming one product can change alphabetical sort order
+- creating or deleting one product can shift pagination boundaries
+- changing one record can affect multiple filtered views
+
+Keeping `deps` for invalidation and `view` for cache partitioning makes that distinction explicit.
+
+### What if I need to invalidate page 2 but not page 1?
+
+That is a valid case, but it is intentionally not the default tracked behavior.
+
+Use one of these options:
+
+- call `query.invalidate()` on the exact query handle you want to refresh
+- call `manager.invalidateQueries({ queryKey, exact: true })` with the specific key
+- move `page` from `view` into `deps` only if page is truly part of the invalidation semantics in your domain
+
+If page-specific invalidation is an exception, manual exact invalidation is usually the better choice.
+
+### When is broad tracked invalidation the right tradeoff?
+
+It is usually correct when one mutation can affect multiple views of the same domain slice:
+
+- product creation can change counts and membership across multiple pages
+- deletion can pull later items forward into earlier pages
+- renaming can move items between sorted pages
+- updates can move records in or out of filtered lists
+
 ## API
 
 ### `setupQueryManager(queryClient)`
@@ -72,6 +449,9 @@ Returns `QueryManager` with:
 
 - `createQuery(queryKey, queryFn, options?)`
 - `createMutation(mutationFn, options?)`
+- `createQueryAndMutation(dependencyKeys)`
+- `createUntrackedQuery(queryKey, queryFn, options?)`
+- `createUntrackedMutation(mutationFn, options?)`
 - `cancelQueries(...)`
 - `getQueryData(...)`
 - `invalidateQueries(...)`
@@ -83,13 +463,56 @@ 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.
+
+`createQuery(queryKey, queryFn, options?)` returns the same `QueryService<TData, TError>` shape as `createUntrackedQuery(...)`, 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.
+
+`createMutation(mutationFn, options?)` returns the same `MutationService<TData, TError, TVariables, TOnMutateResult>` shape as `createUntrackedMutation(...)`, but adds:
+
+- `dependencyKeys?`
+- `resolveDependencies?`
+- `invalidateOn?` with `'success' | 'error' | 'settled'`
+- `matchMode?` with `'intersection' | 'union'`
+
+Standalone tracked mutations need either `dependencyKeys` or `resolveDependencies`.
+
+`createQueryAndMutation(dependencyKeys)` captures dependency keys once and returns:
+
+- the tracked `createQuery` factory
+- a tracked `createMutation` factory whose default resolver reads `variables[dependencyKey]`
+
+Use `resolveDependencies` when the mutation variables do not expose the tracked dependency fields directly.
+
+### `createQueryAndMutation(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 `createMutation(...)` 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`.
+Creates a `createUntrackedQuery` factory bound to a `QueryClient`.
 
-`createQuery(queryKey, queryFn, options?)` returns `QueryService<TData, TError>`.
+`createUntrackedQuery(queryKey, queryFn, options?)` returns `QueryService<TData, TError>`.
 
-`QueryServiceOptions` is based on TanStack `QueryObserverOptions`, without `queryKey` and `queryFn` because those are provided directly to `createQuery`.
+`QueryServiceOptions` is based on TanStack `QueryObserverOptions`, without `queryKey` and `queryFn` because those are provided directly to `createUntrackedQuery`.
 
 `QueryService` methods:
 
@@ -120,11 +543,11 @@ Creates a `createQuery` factory bound to a `QueryClient`.
 
 ### `setupMutation(queryClient)`
 
-Creates a `createMutation` factory bound to a `QueryClient`.
+Creates a `createUntrackedMutation` factory bound to a `QueryClient`.
 
-`createMutation(mutationFn, options?)` returns `MutationService<TData, TError, TVariables, TOnMutateResult>`.
+`createUntrackedMutation(mutationFn, options?)` returns `MutationService<TData, TError, TVariables, TOnMutateResult>`.
 
-`MutationServiceOptions` is based on TanStack `MutationObserverOptions`, without `mutationFn` because it is provided directly to `createMutation`.
+`MutationServiceOptions` is based on TanStack `MutationObserverOptions`, without `mutationFn` because it is provided directly to `createUntrackedMutation`.
 
 `MutationService` methods:
 
@@ -171,3 +594,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.
@@ -28,12 +29,39 @@ export interface MutationService<TData = unknown, TError = Error, TVariables = v
  */
 export type MutationServiceOptions<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown> = Omit<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationFn'>;
 /**
- * Function signature for the mutation factory.
+ * Function signature for the untracked mutation factory.
  */
-export interface CreateMutation {
+export interface CreateUntrackedMutation {
     <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 the default mutation factory with automatic invalidation.
+ */
+export interface CreateMutation {
+    <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;
+export declare function setupMutation(queryClient: QueryClient): CreateUntrackedMutation;
+/**
+ * Prepares the default 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[]): CreateMutation;