@veams/status-quo-query 0.7.2 → 0.8.1

package/README.md

@@ -31,6 +31,7 @@ Root exports:
 - `MutationService`
 - `QueryServiceSnapshot`
 - `MutationServiceSnapshot`
+- `QueryDependencyTuple`
 - `QueryServiceOptions`
 - `MutationServiceOptions`
 - `TrackedMutationServiceOptions`
@@ -393,6 +394,96 @@ Standalone tracked mutations need either:
 - `dependencyKeys`
 - or `resolveDependencies`
 
+### Reactive Query Dependencies
+
+Use `dependsOn` when a query needs data from other queries before it can run.
+
+`dependsOn` accepts a `QueryDependencyTuple`:
+
+- an ordered list of source query keys to observe
+- a `deriveOptions(...)` callback that returns only `queryKey` and/or `enabled`
+
+The watcher starts on the first `subscribe(...)` or `refetch()`, reads the current cache immediately, and stops after the last unsubscribe.
+
+Untracked example:
+
+```ts
+import { QueryClient } from '@tanstack/query-core';
+import { setupQuery, type QueryDependencyTuple } from '@veams/status-quo-query';
+
+type User = { companyId: string };
+type Config = { region: string; companyProfileEnabled: boolean };
+
+const queryClient = new QueryClient();
+const createQuery = setupQuery(queryClient);
+const userKey = ['user', 42] as const;
+const configKey = ['config', 'global'] as const;
+
+const companyProfileQuery = createQuery(
+  ['company-profile', { companyId: undefined as string | undefined, region: undefined as string | undefined }],
+  ({ queryKey }) => fetchCompanyProfile(queryKey[1].companyId!, queryKey[1].region!),
+  {
+    enabled: false,
+    dependsOn: <QueryDependencyTuple<[User, Config]>>[
+      [userKey, configKey],
+      ([userSnapshot, configSnapshot]) => {
+        if (!userSnapshot.data?.companyId || !configSnapshot.data?.region) {
+          return { enabled: false };
+        }
+
+        return {
+          enabled: configSnapshot.data.companyProfileEnabled,
+          queryKey: [
+            'company-profile',
+            {
+              companyId: userSnapshot.data.companyId,
+              region: configSnapshot.data.region,
+            },
+          ],
+        };
+      },
+    ],
+  }
+);
+```
+
+Tracked example:
+
+```ts
+import { QueryClient } from '@tanstack/query-core';
+import { setupQueryManager } from '@veams/status-quo-query';
+
+const queryClient = new QueryClient();
+const manager = setupQueryManager(queryClient);
+const selectionKey = ['selection'] as const;
+
+const productQuery = manager.createQuery(
+  ['product', { deps: { applicationId: 'pending' }, view: { page: 0 } }],
+  ({ queryKey }) => fetchProduct(queryKey[1].deps.applicationId),
+  {
+    enabled: false,
+    dependsOn: [
+      [selectionKey],
+      ([selectionSnapshot]) =>
+        selectionSnapshot.data?.applicationId
+          ? {
+              enabled: true,
+              queryKey: [
+                'product',
+                {
+                  deps: { applicationId: selectionSnapshot.data.applicationId },
+                  view: { page: 1 },
+                },
+              ],
+            }
+          : { enabled: false },
+    ],
+  }
+);
+```
+
+For tracked queries, keep the placeholder key valid too. The initial key and every derived key must still end with `{ deps, view? }`.
+
 ## FAQ
 
 ### Is `view` still part of the TanStack cache key?
@@ -474,7 +565,7 @@ Tracked queries embed dependency metadata into the final query-key segment:
 
 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.
+`createQuery(queryKey, queryFn, options?)` returns the same `QueryService<TData, TError>` shape as `createUntrackedQuery(...)`, but it registers the query hash under every `deps` entry, re-registers on `refetch()` or the first `subscribe(...)` if TanStack has removed the cache entry in the meantime, and keeps the registry in sync when `dependsOn` derives a new tracked key at runtime.
 
 `createMutation(mutationFn, options?)` returns the same `MutationService<TData, TError, TVariables, TOnMutateResult>` shape as `createUntrackedMutation(...)`, but adds:
 
@@ -515,6 +606,12 @@ Creates a `createUntrackedQuery` factory bound to a `QueryClient`.
 
 `QueryServiceOptions` is based on TanStack `QueryObserverOptions`, without `queryKey` and `queryFn` because those are provided directly to `createUntrackedQuery`.
 
+It also adds:
+
+- `dependsOn?: QueryDependencyTuple<[...sources]>`
+
+`dependsOn` observes the listed source keys through TanStack `QueriesObserver` and lets the downstream query derive only `queryKey` and `enabled`. The public `QueryService` API does not change when this option is used.
+
 `QueryService` methods:
 
 - `getSnapshot()`

package/dist/query.d.ts

@@ -37,11 +37,23 @@ export interface QueryService<TData, TError> {
  */
 export interface QueryInvalidateOptions extends Pick<InvalidateOptions, 'cancelRefetch' | 'throwOnError'>, Pick<InvalidateQueryFilters, 'refetchType'> {
 }
+type QueryDependencyDerivedOptions<TQueryKey extends QueryKey = QueryKey> = {
+    enabled?: boolean;
+    queryKey?: TQueryKey;
+};
+export type QueryDependencyTuple<TSources extends readonly unknown[], TQueryKey extends QueryKey = QueryKey> = readonly [
+    sourceKeys: {
+        readonly [K in keyof TSources]: QueryKey;
+    },
+    deriveOptions: (sourceSnapshots: {
+        readonly [K in keyof TSources]: QueryServiceSnapshot<TSources[K], Error>;
+    }) => QueryDependencyDerivedOptions<TQueryKey>
+];
 /**
  * Function signature for the untracked query factory.
  */
 export interface CreateUntrackedQuery {
-    <TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(queryKey: TQueryKey, queryFn: QueryFunction<TQueryFnData, TQueryKey>, options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryService<TData, TError>;
+    <TSources extends readonly unknown[] = [], TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(queryKey: TQueryKey, queryFn: QueryFunction<TQueryFnData, TQueryKey>, options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>): QueryService<TData, TError>;
 }
 /**
  * Function signature for the default query factory that derives dependencies from the final
@@ -51,12 +63,14 @@ export interface CreateUntrackedQuery {
  * The only extra behavior is invisible: dependency registration and on-demand re-registration.
  */
 export interface CreateQuery {
-    <TDeps extends TrackedDependencyRecord, TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends TrackedQueryKey<TDeps> = TrackedQueryKey<TDeps>>(queryKey: TQueryKey, queryFn: QueryFunction<TQueryFnData, TQueryKey>, options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): QueryService<TData, TError>;
+    <TDeps extends TrackedDependencyRecord, TSources extends readonly unknown[] = [], TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends TrackedQueryKey<TDeps> = TrackedQueryKey<TDeps>>(queryKey: TQueryKey, queryFn: QueryFunction<TQueryFnData, TQueryKey>, options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>): QueryService<TData, TError>;
 }
 /**
  * Configuration options for creating a query service, excluding function and key.
  */
-export type QueryServiceOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, 'queryFn' | 'queryKey'>;
+export type QueryServiceOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends QueryKey = QueryKey, TSources extends readonly unknown[] = []> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, 'queryFn' | 'queryKey'> & {
+    dependsOn?: QueryDependencyTuple<TSources, TQueryKey>;
+};
 /**
  * Extracts and maps status and fetchStatus to our QueryMetaState interface.
  */
@@ -80,3 +94,4 @@ export declare function setupQuery(queryClient: QueryClient): CreateUntrackedQue
  * query handles call `ensureRegistered()` before they become active again.
  */
 export declare function setupTrackedQuery(queryClient: QueryClient, trackingRegistry: TrackingRegistry): CreateQuery;
+export {};

package/dist/query.js

@@ -1,6 +1,6 @@
 import { 
 // Import QueryObserver to monitor and manage individual queries.
-QueryObserver, } from '@tanstack/query-core';
+QueryObserver, QueriesObserver, } from '@tanstack/query-core';
 import { extractTrackedDependencies, } from './tracking.js';
 /**
  * Extracts and maps status and fetchStatus to our QueryMetaState interface.
@@ -25,7 +25,12 @@ export function isQueryLoading(query) {
 export function setupQuery(queryClient) {
     // Returns the actual factory function for creating individual query services.
     return function createQuery(queryKey, queryFn, options) {
-        return createQueryService(queryClient, queryKey, queryFn, options).service;
+        const { dependsOn, runtimeOptions } = splitQueryServiceOptions(options);
+        const service = createQueryService(queryClient, queryKey, queryFn, runtimeOptions);
+        if (!dependsOn) {
+            return service.service;
+        }
+        return bindQueryDependencies(queryClient, service, queryKey, dependsOn);
     };
 }
 /**
@@ -40,27 +45,41 @@ export function setupQuery(queryClient) {
  */
 export function setupTrackedQuery(queryClient, trackingRegistry) {
     return function createQuery(queryKey, queryFn, options) {
-        // Validate and normalize the dependency entries once when the handle is created.
-        const dependencies = extractTrackedDependencies(queryKey);
+        const { dependsOn, runtimeOptions } = splitQueryServiceOptions(options);
         // Reuse the same core query service implementation as the untracked API.
-        const service = createQueryService(queryClient, queryKey, queryFn, options);
+        const service = createQueryService(queryClient, queryKey, queryFn, runtimeOptions);
         // We only need re-registration on the transition from zero to one subscribers.
         let subscriberCount = 0;
         // Register the current query hash immediately so future tracked mutations can find it.
-        trackingRegistry.register(service.observer.getCurrentQuery().queryHash, dependencies);
+        trackingRegistry.register(service.observer.getCurrentQuery().queryHash, extractTrackedDependencies(service.getCurrentQueryKey()));
+        const applyTrackedDerivedState = (derivedOptions) => {
+            const previousQueryHash = service.observer.getCurrentQuery().queryHash;
+            service.setDerivedState(derivedOptions);
+            const nextQueryHash = service.observer.getCurrentQuery().queryHash;
+            if (nextQueryHash === previousQueryHash) {
+                return;
+            }
+            trackingRegistry.unregister(previousQueryHash);
+            trackingRegistry.register(nextQueryHash, extractTrackedDependencies(service.getCurrentQueryKey()));
+        };
+        const dependencyController = dependsOn
+            ? createDependencyController(queryClient, queryKey, applyTrackedDerivedState, dependsOn)
+            : undefined;
         const ensureRegistered = () => {
             // Build resolves the current live TanStack query for the stored observer options. This is
             // the same mechanism TanStack uses internally when a query gets recreated after GC.
-            const liveQuery = queryClient.getQueryCache().build(queryClient, toQueryOptions(queryKey, queryFn, options));
+            const liveQuery = queryClient.getQueryCache().build(queryClient, service.getCurrentObserverOptions());
+            const liveDependencies = extractTrackedDependencies(service.getCurrentQueryKey());
             // Re-register only when TanStack has recreated the query and the registry has already
             // cleaned up the previous hash. This keeps the edge-case handling cheap in the common case.
             if (!trackingRegistry.has(liveQuery.queryHash)) {
-                trackingRegistry.register(liveQuery.queryHash, dependencies);
+                trackingRegistry.register(liveQuery.queryHash, liveDependencies);
             }
         };
         return {
             ...service.service,
             refetch: async (refetchOptions) => {
+                dependencyController?.evaluateOnce();
                 // Refetch is one of the two explicit reactivation paths agreed on in the design.
                 ensureRegistered();
                 return service.service.refetch(refetchOptions);
@@ -69,6 +88,7 @@ export function setupTrackedQuery(queryClient, trackingRegistry) {
                 // The first active subscriber is the other reactivation path. Re-running registration
                 // here makes a previously removed query visible to tracked invalidation again.
                 if (subscriberCount === 0) {
+                    dependencyController?.activate();
                     ensureRegistered();
                 }
                 subscriberCount += 1;
@@ -76,6 +96,9 @@ export function setupTrackedQuery(queryClient, trackingRegistry) {
                 return () => {
                     // Keep the counter bounded so accidental double-unsubscribe cannot push it negative.
                     subscriberCount = Math.max(0, subscriberCount - 1);
+                    if (subscriberCount === 0) {
+                        dependencyController?.deactivate();
+                    }
                     unsubscribe();
                 };
             },
@@ -99,9 +122,25 @@ function toQueryServiceSnapshot(result) {
     };
 }
 function createQueryService(queryClient, queryKey, queryFn, options) {
-    const observer = new QueryObserver(queryClient, toQueryOptions(queryKey, queryFn, options));
+    const baseQueryKey = queryKey;
+    const baseOptions = options;
+    let resolvedQueryKey = baseQueryKey;
+    let resolvedOptions = baseOptions;
+    const observer = new QueryObserver(queryClient, toQueryOptions(resolvedQueryKey, queryFn, resolvedOptions));
+    const setDerivedState = (derivedOptions) => {
+        resolvedQueryKey = derivedOptions.queryKey ?? baseQueryKey;
+        resolvedOptions = {
+            ...baseOptions,
+            ...(derivedOptions.enabled === undefined ? {} : { enabled: derivedOptions.enabled }),
+        };
+        observer.setOptions(toQueryOptions(resolvedQueryKey, queryFn, resolvedOptions));
+    };
+    const getCurrentObserverOptions = () => toQueryOptions(resolvedQueryKey, queryFn, resolvedOptions);
     return {
         observer,
+        getCurrentObserverOptions,
+        getCurrentQueryKey: () => resolvedQueryKey,
+        setDerivedState,
         service: {
             getSnapshot: () => toQueryServiceSnapshot(observer.getCurrentResult()),
             subscribe: (listener) => observer.subscribe((result) => {
@@ -110,7 +149,7 @@ function createQueryService(queryClient, queryKey, queryFn, options) {
             refetch: async (refetchOptions) => toQueryServiceSnapshot(await observer.refetch(refetchOptions)),
             invalidate: (invalidateOptions) => queryClient.invalidateQueries({
                 exact: true,
-                queryKey,
+                queryKey: resolvedQueryKey,
                 ...(invalidateOptions?.refetchType === undefined
                     ? {}
                     : { refetchType: invalidateOptions.refetchType }),
@@ -119,6 +158,85 @@ function createQueryService(queryClient, queryKey, queryFn, options) {
         },
     };
 }
+function bindQueryDependencies(queryClient, queryService, queryKey, dependsOn) {
+    const dependencyController = createDependencyController(queryClient, queryKey, queryService.setDerivedState, dependsOn);
+    let subscriberCount = 0;
+    return {
+        ...queryService.service,
+        refetch: async (refetchOptions) => {
+            dependencyController.evaluateOnce();
+            return queryService.service.refetch(refetchOptions);
+        },
+        subscribe: (listener) => {
+            if (subscriberCount === 0) {
+                dependencyController.activate();
+            }
+            subscriberCount += 1;
+            const unsubscribe = queryService.service.subscribe(listener);
+            return () => {
+                subscriberCount = Math.max(0, subscriberCount - 1);
+                if (subscriberCount === 0) {
+                    dependencyController.deactivate();
+                }
+                unsubscribe();
+            };
+        },
+    };
+}
+function createDependencyController(queryClient, baseQueryKey, setDerivedState, dependsOn) {
+    const [sourceKeys, deriveOptions] = dependsOn;
+    let queriesObserver;
+    let unsubscribe;
+    const evaluateBinding = (results) => {
+        const snapshots = results.map((result) => toQueryServiceSnapshot(result));
+        const derivedOptions = deriveOptions(snapshots);
+        setDerivedState({
+            queryKey: derivedOptions.queryKey ?? baseQueryKey,
+            ...(derivedOptions.enabled === undefined ? {} : { enabled: derivedOptions.enabled }),
+        });
+    };
+    const createObserver = () => new QueriesObserver(queryClient, sourceKeys.map((sourceKey) => ({
+        enabled: false,
+        queryKey: sourceKey,
+    })));
+    return {
+        activate: () => {
+            if (queriesObserver) {
+                return;
+            }
+            queriesObserver = createObserver();
+            evaluateBinding(queriesObserver.getCurrentResult());
+            unsubscribe = queriesObserver.subscribe(evaluateBinding);
+        },
+        deactivate: () => {
+            unsubscribe?.();
+            unsubscribe = undefined;
+            queriesObserver = undefined;
+        },
+        evaluateOnce: () => {
+            if (queriesObserver) {
+                evaluateBinding(queriesObserver.getCurrentResult());
+                return;
+            }
+            const transientObserver = createObserver();
+            evaluateBinding(transientObserver.getCurrentResult());
+            transientObserver.destroy();
+        },
+    };
+}
+function splitQueryServiceOptions(options) {
+    if (options === undefined) {
+        return {
+            dependsOn: undefined,
+            runtimeOptions: undefined,
+        };
+    }
+    const { dependsOn, ...runtimeOptions } = options;
+    return {
+        dependsOn,
+        runtimeOptions,
+    };
+}
 function toQueryOptions(queryKey, queryFn, options) {
     // Centralize option assembly so both normal queries and tracked queries build observers and
     // live TanStack query instances from exactly the same inputs.

package/dist/query.js.map

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

package/package.json

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

package/src/__tests__/query.spec.ts

@@ -3,6 +3,11 @@ import { QueryClient } from '@tanstack/query-core';
 import { isQueryLoading, setupQuery, toQueryMetaState } from '../query';
 
 describe('Query Service', () => {
+  async function flushTasks() {
+    await Promise.resolve();
+    await Promise.resolve();
+  }
+
   it('returns data after refetch', async () => {
     const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
     const createQuery = setupQuery(queryClient);
@@ -58,6 +63,235 @@ describe('Query Service', () => {
     );
   });
 
+  it('derives query activation and key updates from upstream cache state', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const createQuery = setupQuery(queryClient);
+    const userKey = ['user', 42] as const;
+    const configKey = ['config', 'global'] as const;
+    const queryFn = jest
+      .fn()
+      .mockImplementation(({ queryKey }) => `${queryKey[1].companyId}:${queryKey[1].region}`);
+
+    const service = createQuery(
+      ['crefo', { companyId: undefined as string | undefined, region: undefined as string | undefined }],
+      queryFn,
+      {
+        enabled: false,
+        dependsOn: [
+          [userKey, configKey],
+          ([userSnapshot, configSnapshot]) => {
+            if (!userSnapshot.data?.companyId || !configSnapshot.data?.region) {
+              return { enabled: false };
+            }
+
+            return {
+              enabled: true,
+              queryKey: [
+                'crefo',
+                {
+                  companyId: userSnapshot.data.companyId,
+                  region: configSnapshot.data.region,
+                },
+              ],
+            };
+          },
+        ],
+      }
+    );
+
+    const snapshots: string[] = [];
+    const unsubscribe = service.subscribe((snapshot) => {
+      snapshots.push(snapshot.status);
+    });
+
+    queryClient.setQueryData(userKey, { companyId: 'company-1' });
+    queryClient.setQueryData(configKey, { region: 'eu' });
+    await flushTasks();
+
+    expect(queryFn).toHaveBeenCalledTimes(1);
+    expect(queryFn).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        queryKey: ['crefo', { companyId: 'company-1', region: 'eu' }],
+      })
+    );
+    expect(service.getSnapshot().data).toBe('company-1:eu');
+    expect(snapshots).toContain('success');
+
+    unsubscribe();
+  });
+
+  it('uses warm upstream cache data when dependsOn is evaluated on first refetch', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const createQuery = setupQuery(queryClient);
+    const selectionKey = ['selection'] as const;
+    const queryFn = jest.fn().mockImplementation(async ({ queryKey }) => queryKey[1].id);
+
+    queryClient.setQueryData(selectionKey, { id: 'item-2' });
+
+    const service = createQuery(
+      ['details', { id: undefined as string | undefined }],
+      queryFn,
+      {
+        enabled: false,
+        dependsOn: [
+          [selectionKey],
+          ([selectionSnapshot]) =>
+            selectionSnapshot.data?.id
+              ? {
+                  enabled: true,
+                  queryKey: ['details', { id: selectionSnapshot.data.id }],
+                }
+              : { enabled: false },
+        ],
+      }
+    );
+
+    const result = await service.refetch();
+
+    expect(result.data).toBe('item-2');
+    expect(queryFn).toHaveBeenCalledWith(
+      expect.objectContaining({
+        queryKey: ['details', { id: 'item-2' }],
+      })
+    );
+  });
+
+  it('preserves source snapshot tuple order in dependsOn', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const createQuery = setupQuery(queryClient);
+    const firstKey = ['source', 'first'] as const;
+    const secondKey = ['source', 'second'] as const;
+    const observedOrders: Array<[string | undefined, string | undefined]> = [];
+
+    queryClient.setQueryData(firstKey, { label: 'first' });
+    queryClient.setQueryData(secondKey, { label: 'second' });
+
+    const service = createQuery(
+      ['ordered', { left: undefined as string | undefined, right: undefined as string | undefined }],
+      jest.fn().mockResolvedValue('ok'),
+      {
+        enabled: false,
+        dependsOn: [
+          [firstKey, secondKey],
+          ([firstSnapshot, secondSnapshot]) => {
+            observedOrders.push([firstSnapshot.data?.label, secondSnapshot.data?.label]);
+
+            return {
+              enabled: false,
+              queryKey: [
+                'ordered',
+                {
+                  left: firstSnapshot.data?.label,
+                  right: secondSnapshot.data?.label,
+                },
+              ],
+            };
+          },
+        ],
+      }
+    );
+
+    await service.refetch();
+
+    expect(observedOrders).toContainEqual(['first', 'second']);
+  });
+
+  it('invalidates the current derived query key after dependsOn updates it', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const createQuery = setupQuery(queryClient);
+    const selectionKey = ['selection'] as const;
+
+    queryClient.setQueryData(selectionKey, { id: 'item-3' });
+
+    const service = createQuery(
+      ['details', { id: undefined as string | undefined }],
+      jest.fn().mockResolvedValue('item-3'),
+      {
+        enabled: false,
+        dependsOn: [
+          [selectionKey],
+          ([selectionSnapshot]) =>
+            selectionSnapshot.data?.id
+              ? {
+                  enabled: true,
+                  queryKey: ['details', { id: selectionSnapshot.data.id }],
+                }
+              : { enabled: false },
+        ],
+      }
+    );
+
+    await service.refetch();
+    await service.invalidate({ refetchType: 'none' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith(
+      {
+        exact: true,
+        queryKey: ['details', { id: 'item-3' }],
+        refetchType: 'none',
+      },
+      undefined
+    );
+  });
+
+  it('stops reacting to upstream cache updates after the last unsubscribe', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const createQuery = setupQuery(queryClient);
+    const selectionKey = ['selection'] as const;
+    const queryFn = jest.fn().mockImplementation(async ({ queryKey }) => queryKey[1].id);
+
+    queryClient.setQueryData(selectionKey, { id: 'item-1' });
+
+    const service = createQuery(
+      ['details', { id: undefined as string | undefined }],
+      queryFn,
+      {
+        enabled: false,
+        dependsOn: [
+          [selectionKey],
+          ([selectionSnapshot]) =>
+            selectionSnapshot.data?.id
+              ? {
+                  enabled: true,
+                  queryKey: ['details', { id: selectionSnapshot.data.id }],
+                }
+              : { enabled: false },
+        ],
+      }
+    );
+
+    const unsubscribe = service.subscribe(() => undefined);
+    await flushTasks();
+    unsubscribe();
+
+    queryClient.setQueryData(selectionKey, { id: 'item-2' });
+    await flushTasks();
+
+    expect(queryFn).toHaveBeenCalledTimes(1);
+
+    await service.invalidate({ refetchType: 'none' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith(
+      {
+        exact: true,
+        queryKey: ['details', { id: 'item-1' }],
+        refetchType: 'none',
+      },
+      undefined
+    );
+
+    await service.refetch();
+
+    expect(queryFn).toHaveBeenCalledTimes(2);
+    expect(queryFn).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        queryKey: ['details', { id: 'item-2' }],
+      })
+    );
+  });
+
   it('derives loading state from query metadata', () => {
     expect(
       isQueryLoading(

package/src/__tests__/tracked.spec.ts

@@ -3,6 +3,11 @@ import { QueryClient } from '@tanstack/query-core';
 import { setupQueryManager } from '../provider';
 
 describe('Tracked Query Invalidation', () => {
+  async function flushTasks() {
+    await Promise.resolve();
+    await Promise.resolve();
+  }
+
   it('registers tracked queries from deps and ignores view data during invalidation', async () => {
     const queryClient = new QueryClient({
       defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
@@ -273,4 +278,126 @@ describe('Tracked Query Invalidation', () => {
 
     expect(invalidateQueriesSpy).toHaveBeenCalledTimes(1);
   });
+
+  it('moves tracked registrations to the derived key when dependsOn updates the query', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const selectionKey = ['selection'] as const;
+
+    queryClient.setQueryData(selectionKey, { applicationId: 'app-1' });
+
+    const query = manager.createQuery(
+      ['product', { deps: { applicationId: 'pending' }, view: { page: 0 } }],
+      jest.fn().mockResolvedValue('product'),
+      {
+        enabled: false,
+        dependsOn: [
+          [selectionKey],
+          ([selectionSnapshot]) =>
+            selectionSnapshot.data?.applicationId
+              ? {
+                  enabled: true,
+                  queryKey: [
+                    'product',
+                    {
+                      deps: { applicationId: selectionSnapshot.data.applicationId },
+                      view: { page: 1 },
+                    },
+                  ],
+                }
+              : { enabled: false },
+        ],
+      }
+    );
+
+    const mutation = manager.createMutation(jest.fn().mockResolvedValue({ ok: true as const }), {
+      dependencyKeys: ['applicationId'],
+    });
+
+    await query.refetch();
+    await mutation.mutate({ applicationId: 'pending' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(0);
+
+    await mutation.mutate({ applicationId: 'app-1' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      exact: true,
+      queryKey: ['product', { deps: { applicationId: 'app-1' }, view: { page: 1 } }],
+    });
+  });
+
+  it('re-registers the latest derived tracked key after cache removal and a later refetch', async () => {
+    const queryClient = new QueryClient({
+      defaultOptions: { mutations: { retry: 0 }, queries: { retry: 0 } },
+    });
+    const manager = setupQueryManager(queryClient);
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const selectionKey = ['selection'] as const;
+    const initialDerivedKey = [
+      'product',
+      { deps: { applicationId: 'app-1' }, view: { page: 1 } },
+    ] as const;
+    const latestDerivedKey = [
+      'product',
+      { deps: { applicationId: 'app-2' }, view: { page: 1 } },
+    ] as const;
+
+    queryClient.setQueryData(selectionKey, { applicationId: 'app-1' });
+
+    const query = manager.createQuery(
+      ['product', { deps: { applicationId: 'pending' }, view: { page: 0 } }],
+      jest.fn().mockResolvedValue('product'),
+      {
+        enabled: false,
+        dependsOn: [
+          [selectionKey],
+          ([selectionSnapshot]) =>
+            selectionSnapshot.data?.applicationId
+              ? {
+                  enabled: true,
+                  queryKey: [
+                    'product',
+                    {
+                      deps: { applicationId: selectionSnapshot.data.applicationId },
+                      view: { page: 1 },
+                    },
+                  ],
+                }
+              : { enabled: false },
+        ],
+      }
+    );
+
+    const mutation = manager.createMutation(jest.fn().mockResolvedValue({ ok: true as const }), {
+      dependencyKeys: ['applicationId'],
+    });
+
+    await query.refetch();
+    queryClient.removeQueries({ exact: true, queryKey: initialDerivedKey });
+    queryClient.setQueryData(selectionKey, { applicationId: 'app-2' });
+    await flushTasks();
+
+    invalidateQueriesSpy.mockClear();
+
+    await mutation.mutate({ applicationId: 'app-2' });
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(0);
+
+    await query.refetch();
+    await mutation.mutate({ applicationId: 'app-2' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({
+      exact: true,
+      queryKey: latestDerivedKey,
+    });
+
+    invalidateQueriesSpy.mockClear();
+
+    await mutation.mutate({ applicationId: 'pending' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledTimes(0);
+  });
 });

package/src/query.ts

@@ -13,6 +13,7 @@ import {
   type QueryKey,
   // Import QueryObserver to monitor and manage individual queries.
   QueryObserver,
+  QueriesObserver,
   type QueryOptions,
   // Import configuration options for the query observer.
   type QueryObserverOptions,
@@ -88,11 +89,38 @@ export interface QueryInvalidateOptions
   extends Pick<InvalidateOptions, 'cancelRefetch' | 'throwOnError'>,
     Pick<InvalidateQueryFilters, 'refetchType'> {}
 
+type QueryDependencyDerivedOptions<TQueryKey extends QueryKey = QueryKey> = {
+  enabled?: boolean;
+  queryKey?: TQueryKey;
+};
+
+type QueryServiceRuntimeOptions<
+  TQueryFnData = unknown,
+  TError = Error,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = Omit<
+  QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
+  'dependsOn'
+>;
+
+export type QueryDependencyTuple<
+  TSources extends readonly unknown[],
+  TQueryKey extends QueryKey = QueryKey,
+> = readonly [
+  sourceKeys: { readonly [K in keyof TSources]: QueryKey },
+  deriveOptions: (
+    sourceSnapshots: { readonly [K in keyof TSources]: QueryServiceSnapshot<TSources[K], Error> }
+  ) => QueryDependencyDerivedOptions<TQueryKey>,
+];
+
 /**
  * Function signature for the untracked query factory.
  */
 export interface CreateUntrackedQuery {
   <
+    TSources extends readonly unknown[] = [],
     TQueryFnData = unknown,
     TError = Error,
     TData = TQueryFnData,
@@ -104,7 +132,7 @@ export interface CreateUntrackedQuery {
     // The asynchronous function that performs the data fetch.
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
     // Optional configuration for behavior like staleness, retry, and refetching.
-    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
   ): QueryService<TData, TError>;
 }
 
@@ -118,6 +146,7 @@ export interface CreateUntrackedQuery {
 export interface CreateQuery {
   <
     TDeps extends TrackedDependencyRecord,
+    TSources extends readonly unknown[] = [],
     TQueryFnData = unknown,
     TError = Error,
     TData = TQueryFnData,
@@ -126,7 +155,7 @@ export interface CreateQuery {
   >(
     queryKey: TQueryKey,
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
   ): QueryService<TData, TError>;
 }
 
@@ -139,10 +168,13 @@ export type QueryServiceOptions<
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
+  TSources extends readonly unknown[] = [],
 > = Omit<
   QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
   'queryFn' | 'queryKey'
->;
+> & {
+  dependsOn?: QueryDependencyTuple<TSources, TQueryKey>;
+};
 
 /**
  * Extracts and maps status and fetchStatus to our QueryMetaState interface.
@@ -171,6 +203,7 @@ export function isQueryLoading(query: QueryMetaState): boolean {
 export function setupQuery(queryClient: QueryClient): CreateUntrackedQuery {
   // Returns the actual factory function for creating individual query services.
   return function createQuery<
+    TSources extends readonly unknown[] = [],
     TQueryFnData = unknown,
     TError = Error,
     TData = TQueryFnData,
@@ -179,9 +212,16 @@ export function setupQuery(queryClient: QueryClient): CreateUntrackedQuery {
   >(
     queryKey: TQueryKey,
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
   ): QueryService<TData, TError> {
-    return createQueryService(queryClient, queryKey, queryFn, options).service;
+    const { dependsOn, runtimeOptions } = splitQueryServiceOptions(options);
+    const service = createQueryService(queryClient, queryKey, queryFn, runtimeOptions);
+
+    if (!dependsOn) {
+      return service.service;
+    }
+
+    return bindQueryDependencies(queryClient, service, queryKey, dependsOn);
   };
 }
 
@@ -201,6 +241,7 @@ export function setupTrackedQuery(
 ): CreateQuery {
   return function createQuery<
     TDeps extends TrackedDependencyRecord,
+    TSources extends readonly unknown[] = [],
     TQueryFnData = unknown,
     TError = Error,
     TData = TQueryFnData,
@@ -209,36 +250,64 @@ export function setupTrackedQuery(
   >(
     queryKey: TQueryKey,
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
   ): QueryService<TData, TError> {
-    // Validate and normalize the dependency entries once when the handle is created.
-    const dependencies = extractTrackedDependencies(queryKey);
+    const { dependsOn, runtimeOptions } = splitQueryServiceOptions(options);
     // Reuse the same core query service implementation as the untracked API.
-    const service = createQueryService(queryClient, queryKey, queryFn, options);
+    const service = createQueryService(queryClient, queryKey, queryFn, runtimeOptions);
     // We only need re-registration on the transition from zero to one subscribers.
     let subscriberCount = 0;
 
     // Register the current query hash immediately so future tracked mutations can find it.
-    trackingRegistry.register(service.observer.getCurrentQuery().queryHash, dependencies);
+    trackingRegistry.register(
+      service.observer.getCurrentQuery().queryHash,
+      extractTrackedDependencies(service.getCurrentQueryKey())
+    );
+
+    const applyTrackedDerivedState = (derivedOptions: QueryDependencyDerivedOptions<TQueryKey>) => {
+      const previousQueryHash = service.observer.getCurrentQuery().queryHash;
+
+      service.setDerivedState(derivedOptions);
+
+      const nextQueryHash = service.observer.getCurrentQuery().queryHash;
+
+      if (nextQueryHash === previousQueryHash) {
+        return;
+      }
+
+      trackingRegistry.unregister(previousQueryHash);
+      trackingRegistry.register(nextQueryHash, extractTrackedDependencies(service.getCurrentQueryKey()));
+    };
+
+    const dependencyController = dependsOn
+      ? createDependencyController(
+          queryClient,
+          queryKey,
+          applyTrackedDerivedState,
+          dependsOn
+        )
+      : undefined;
 
     const ensureRegistered = () => {
       // Build resolves the current live TanStack query for the stored observer options. This is
       // the same mechanism TanStack uses internally when a query gets recreated after GC.
       const liveQuery = queryClient.getQueryCache().build(
         queryClient,
-        toQueryOptions(queryKey, queryFn, options)
+        service.getCurrentObserverOptions()
       );
+      const liveDependencies = extractTrackedDependencies(service.getCurrentQueryKey());
 
       // Re-register only when TanStack has recreated the query and the registry has already
       // cleaned up the previous hash. This keeps the edge-case handling cheap in the common case.
       if (!trackingRegistry.has(liveQuery.queryHash)) {
-        trackingRegistry.register(liveQuery.queryHash, dependencies);
+        trackingRegistry.register(liveQuery.queryHash, liveDependencies);
       }
     };
 
     return {
       ...service.service,
       refetch: async (refetchOptions) => {
+        dependencyController?.evaluateOnce();
         // Refetch is one of the two explicit reactivation paths agreed on in the design.
         ensureRegistered();
         return service.service.refetch(refetchOptions);
@@ -247,6 +316,7 @@ export function setupTrackedQuery(
         // The first active subscriber is the other reactivation path. Re-running registration
         // here makes a previously removed query visible to tracked invalidation again.
         if (subscriberCount === 0) {
+          dependencyController?.activate();
           ensureRegistered();
         }
 
@@ -257,6 +327,9 @@ export function setupTrackedQuery(
         return () => {
           // Keep the counter bounded so accidental double-unsubscribe cannot push it negative.
           subscriberCount = Math.max(0, subscriberCount - 1);
+          if (subscriberCount === 0) {
+            dependencyController?.deactivate();
+          }
           unsubscribe();
         };
       },
@@ -293,20 +366,43 @@ function createQueryService<
   queryClient: QueryClient,
   queryKey: TQueryKey,
   queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-  options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  options?: QueryServiceRuntimeOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
 ): {
   // Expose the observer internally so tracked queries can access the current query hash.
   observer: QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
   // Preserve the public query-service shape for all callers.
   service: QueryService<TData, TError>;
+  getCurrentObserverOptions: () => QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey> &
+    QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;
+  getCurrentQueryKey: () => TQueryKey;
+  setDerivedState: (derivedOptions: QueryDependencyDerivedOptions<TQueryKey>) => void;
 } {
+  const baseQueryKey = queryKey;
+  const baseOptions = options;
+  let resolvedQueryKey = baseQueryKey;
+  let resolvedOptions = baseOptions;
+
   const observer = new QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>(
     queryClient,
-    toQueryOptions(queryKey, queryFn, options)
+    toQueryOptions(resolvedQueryKey, queryFn, resolvedOptions)
   );
 
+  const setDerivedState = (derivedOptions: QueryDependencyDerivedOptions<TQueryKey>) => {
+    resolvedQueryKey = derivedOptions.queryKey ?? baseQueryKey;
+    resolvedOptions = {
+      ...baseOptions,
+      ...(derivedOptions.enabled === undefined ? {} : { enabled: derivedOptions.enabled }),
+    };
+    observer.setOptions(toQueryOptions(resolvedQueryKey, queryFn, resolvedOptions));
+  };
+
+  const getCurrentObserverOptions = () => toQueryOptions(resolvedQueryKey, queryFn, resolvedOptions);
+
   return {
     observer,
+    getCurrentObserverOptions,
+    getCurrentQueryKey: () => resolvedQueryKey,
+    setDerivedState,
     service: {
       getSnapshot: () => toQueryServiceSnapshot(observer.getCurrentResult()),
       subscribe: (listener) =>
@@ -319,7 +415,7 @@ function createQueryService<
         queryClient.invalidateQueries(
           {
             exact: true,
-            queryKey,
+            queryKey: resolvedQueryKey,
             ...(invalidateOptions?.refetchType === undefined
               ? {}
               : { refetchType: invalidateOptions.refetchType }),
@@ -331,6 +427,149 @@ function createQueryService<
   };
 }
 
+function bindQueryDependencies<
+  TSources extends readonly unknown[] = [],
+  TQueryFnData = unknown,
+  TError = Error,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  queryClient: QueryClient,
+  queryService: ReturnType<
+    typeof createQueryService<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  >,
+  queryKey: TQueryKey,
+  dependsOn: QueryDependencyTuple<TSources, TQueryKey>
+): QueryService<TData, TError> {
+  const dependencyController = createDependencyController(
+    queryClient,
+    queryKey,
+    queryService.setDerivedState,
+    dependsOn
+  );
+  let subscriberCount = 0;
+
+  return {
+    ...queryService.service,
+    refetch: async (refetchOptions) => {
+      dependencyController.evaluateOnce();
+      return queryService.service.refetch(refetchOptions);
+    },
+    subscribe: (listener) => {
+      if (subscriberCount === 0) {
+        dependencyController.activate();
+      }
+
+      subscriberCount += 1;
+
+      const unsubscribe = queryService.service.subscribe(listener);
+
+      return () => {
+        subscriberCount = Math.max(0, subscriberCount - 1);
+        if (subscriberCount === 0) {
+          dependencyController.deactivate();
+        }
+        unsubscribe();
+      };
+    },
+  };
+}
+
+function createDependencyController<
+  TSources extends readonly unknown[] = [],
+  TQueryFnData = unknown,
+  TError = Error,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  queryClient: QueryClient,
+  baseQueryKey: TQueryKey,
+  setDerivedState: (derivedOptions: QueryDependencyDerivedOptions<TQueryKey>) => void,
+  dependsOn: QueryDependencyTuple<TSources, TQueryKey>
+) {
+  const [sourceKeys, deriveOptions] = dependsOn;
+  let queriesObserver: QueriesObserver | undefined;
+  let unsubscribe: (() => void) | undefined;
+
+  const evaluateBinding = (results: QueryObserverResult[]) => {
+    const snapshots = results.map((result) =>
+      toQueryServiceSnapshot(result)
+    ) as Parameters<typeof deriveOptions>[0];
+    const derivedOptions = deriveOptions(snapshots);
+
+    setDerivedState({
+      queryKey: derivedOptions.queryKey ?? baseQueryKey,
+      ...(derivedOptions.enabled === undefined ? {} : { enabled: derivedOptions.enabled }),
+    });
+  };
+
+  const createObserver = () =>
+    new QueriesObserver(
+      queryClient,
+      sourceKeys.map((sourceKey) => ({
+        enabled: false,
+        queryKey: sourceKey,
+      }))
+    );
+
+  return {
+    activate: () => {
+      if (queriesObserver) {
+        return;
+      }
+
+      queriesObserver = createObserver();
+      evaluateBinding(queriesObserver.getCurrentResult());
+      unsubscribe = queriesObserver.subscribe(evaluateBinding);
+    },
+    deactivate: () => {
+      unsubscribe?.();
+      unsubscribe = undefined;
+      queriesObserver = undefined;
+    },
+    evaluateOnce: () => {
+      if (queriesObserver) {
+        evaluateBinding(queriesObserver.getCurrentResult());
+        return;
+      }
+
+      const transientObserver = createObserver();
+      evaluateBinding(transientObserver.getCurrentResult());
+      transientObserver.destroy();
+    },
+  };
+}
+
+function splitQueryServiceOptions<
+  TQueryFnData = unknown,
+  TError = Error,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+  TSources extends readonly unknown[] = [],
+>(
+  options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TSources>
+): {
+  dependsOn?: QueryDependencyTuple<TSources, TQueryKey>;
+  runtimeOptions: QueryServiceRuntimeOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> | undefined;
+} {
+  if (options === undefined) {
+    return {
+      dependsOn: undefined,
+      runtimeOptions: undefined,
+    };
+  }
+
+  const { dependsOn, ...runtimeOptions } = options;
+
+  return {
+    dependsOn,
+    runtimeOptions,
+  };
+}
+
 function toQueryOptions<
   TQueryFnData = unknown,
   TError = Error,
@@ -340,7 +579,7 @@ function toQueryOptions<
 >(
   queryKey: TQueryKey,
   queryFn: QueryFunction<TQueryFnData, TQueryKey>,
-  options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  options?: QueryServiceRuntimeOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
 ): QueryOptions<TQueryFnData, TError, TQueryData, TQueryKey> &
   QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> {
   // Centralize option assembly so both normal queries and tracked queries build observers and