@veams/status-quo-query 0.3.0 → 0.5.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,17 +20,28 @@ Root exports:
 - `QueryFetchStatus`
 - `QueryStatus`
 - `MutationStatus`
-- `CacheApi`
+- `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,36 +53,347 @@ Subpath exports:
 
 ```ts
 import { QueryClient } from '@tanstack/query-core';
-import {
-  setupQueryProvider,
-} from '@veams/status-quo-query';
+import { setupQueryManager } from '@veams/status-quo-query';
 
 const queryClient = new QueryClient();
-const cache = setupQueryProvider(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 = cache.createQuery(['user', 42], () => fetchUser(42), {
+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:
+
+```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 [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',
+});
+```
 
-const updateUser = cache.createMutation((payload: UpdateUserPayload) => saveUser(payload));
-await updateUser.mutate({ id: 42 });
+Supported values:
 
-await cache.invalidateQueries({ queryKey: ['user'] });
-cache.setQueryData(['user', 42], (current) => current);
+- `'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
 
-### `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?)`
+- `createTrackedQuery(queryKey, queryFn, options?)`
+- `createTrackedMutation(mutationFn, options?)`
+- `createTrackedQueryAndMutation(dependencyKeys)`
 - `cancelQueries(...)`
 - `getQueryData(...)`
 - `invalidateQueries(...)`
@@ -81,7 +403,50 @@ 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.
+
+### 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)`
 
@@ -170,4 +535,5 @@ 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.
+- 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/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,9 @@
 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.
+ */
 export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVariables = void> {
     data: TData | undefined;
     error: TError | null;
@@ -10,6 +14,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 +24,44 @@ 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>;
 }
+/**
+ * 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;