@veams/status-quo-query 0.7.1 → 0.8.0

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?
@@ -453,6 +544,7 @@ Returns `QueryManager` with:
 - `createUntrackedQuery(queryKey, queryFn, options?)`
 - `createUntrackedMutation(mutationFn, options?)`
 - `cancelQueries(...)`
+- `fetchQuery(...)`
 - `getQueryData(...)`
 - `invalidateQueries(...)`
 - `refetchQueries(...)`
@@ -461,7 +553,7 @@ Returns `QueryManager` with:
 - `setQueryData(...)`
 - `unsafe_getClient()`
 
-All manager 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. `fetchQuery(...)` covers the common one-off read path without dropping to the raw client, while `unsafe_getClient()` remains the explicit escape hatch for unsupported TanStack APIs.
 
 ### Tracked Queries and Mutations
 
@@ -473,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:
 
@@ -514,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/provider.d.ts

@@ -27,6 +27,7 @@ export interface QueryManager {
     createUntrackedMutation: CreateUntrackedMutation;
     createQueryAndMutation: CreateQueryAndMutation;
     cancelQueries: QueryClient['cancelQueries'];
+    fetchQuery: QueryClient['fetchQuery'];
     getQueryData: QueryClient['getQueryData'];
     invalidateQueries: QueryClient['invalidateQueries'];
     refetchQueries: QueryClient['refetchQueries'];

package/dist/provider.js

@@ -44,6 +44,8 @@ export function setupQueryManager(queryClient) {
         },
         // Proxy for canceling queries with this client context.
         cancelQueries: queryClient.cancelQueries.bind(queryClient),
+        // Proxy for fetching one query with this client context.
+        fetchQuery: queryClient.fetchQuery.bind(queryClient),
         // Proxy for retrieving query data with this client context.
         getQueryData: queryClient.getQueryData.bind(queryClient),
         // Proxy for invalidating queries with this client context.

package/dist/provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAMA,qEAAqE;AACrE,OAAO,EAKL,aAAa,EACb,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAA+C,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EACL,sBAAsB,GAEvB,MAAM,eAAe,CAAC;AAiEvB;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAwB;IACxD,sFAAsF;IACtF,sFAAsF;IACtF,MAAM,gBAAgB,GAAG,sBAAsB,EAAE,CAAC;IAClD,MAAM,YAAY,GAAG,iBAAiB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IACtE,MAAM,eAAe,GAAG,oBAAoB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IAC5E,MAAM,qBAAqB,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACtD,MAAM,wBAAwB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAE5D,WAAW,CAAC,aAAa,EAAE,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,6FAA6F;YAC7F,4FAA4F;YAC5F,gFAAgF;YAChF,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,2DAA2D;IAC3D,OAAO;QACL,6CAA6C;QAC7C,cAAc,EAAE,eAAe;QAC/B,0CAA0C;QAC1C,WAAW,EAAE,YAAY;QACzB,oDAAoD;QACpD,oBAAoB,EAAE,qBAAqB;QAC3C,uDAAuD;QACvD,uBAAuB,EAAE,wBAAwB;QACjD,8DAA8D;QAC9D,sBAAsB,EAAE,CACtB,cAA+B,EAC/B,EAAE;YACF,MAAM,0BAA0B,GAE5B,CACF,UAA+C,EAC/C,OASC,EACD,EAAE;YACF,uFAAuF;YACvF,mFAAmF;YACnF,eAAe,CAMb,UAAU,EAAE;gBACZ,GAAG,OAAO;gBACV,cAAc;aACf,CAAC,CAAC;YAEL,OAAO,CAAC,YAAY,EAAE,0BAA0B,CAAU,CAAC;QAC7D,CAAC;QACD,wDAAwD;QACxD,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,4DAA4D;QAC5D,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,2DAA2D;QAC3D,iBAAiB,EAAE,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC;QAClE,yDAAyD;QACzD,cAAc,EAAE,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC;QAC5D,uDAAuD;QACvD,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,wDAAwD;QACxD,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,yDAAyD;QACzD,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,mDAAmD;QACnD,gBAAgB,EAAE,GAAG,EAAE,CAAC,WAAW;KACpC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAMA,qEAAqE;AACrE,OAAO,EAKL,aAAa,EACb,oBAAoB,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAA+C,UAAU,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACxG,OAAO,EACL,sBAAsB,GAEvB,MAAM,eAAe,CAAC;AAmEvB;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,WAAwB;IACxD,sFAAsF;IACtF,sFAAsF;IACtF,MAAM,gBAAgB,GAAG,sBAAsB,EAAE,CAAC;IAClD,MAAM,YAAY,GAAG,iBAAiB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IACtE,MAAM,eAAe,GAAG,oBAAoB,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;IAC5E,MAAM,qBAAqB,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IACtD,MAAM,wBAAwB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAE5D,WAAW,CAAC,aAAa,EAAE,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9C,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,6FAA6F;YAC7F,4FAA4F;YAC5F,gFAAgF;YAChF,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACrD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,2DAA2D;IAC3D,OAAO;QACL,6CAA6C;QAC7C,cAAc,EAAE,eAAe;QAC/B,0CAA0C;QAC1C,WAAW,EAAE,YAAY;QACzB,oDAAoD;QACpD,oBAAoB,EAAE,qBAAqB;QAC3C,uDAAuD;QACvD,uBAAuB,EAAE,wBAAwB;QACjD,8DAA8D;QAC9D,sBAAsB,EAAE,CACtB,cAA+B,EAC/B,EAAE;YACF,MAAM,0BAA0B,GAE5B,CACF,UAA+C,EAC/C,OASC,EACD,EAAE;YACF,uFAAuF;YACvF,mFAAmF;YACnF,eAAe,CAMb,UAAU,EAAE;gBACZ,GAAG,OAAO;gBACV,cAAc;aACf,CAAC,CAAC;YAEL,OAAO,CAAC,YAAY,EAAE,0BAA0B,CAAU,CAAC;QAC7D,CAAC;QACD,wDAAwD;QACxD,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,yDAAyD;QACzD,UAAU,EAAE,WAAW,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC;QACpD,4DAA4D;QAC5D,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,2DAA2D;QAC3D,iBAAiB,EAAE,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC;QAClE,yDAAyD;QACzD,cAAc,EAAE,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC;QAC5D,uDAAuD;QACvD,aAAa,EAAE,WAAW,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC;QAC1D,wDAAwD;QACxD,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,yDAAyD;QACzD,YAAY,EAAE,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC;QACxD,mDAAmD;QACnD,gBAAgB,EAAE,GAAG,EAAE,CAAC,WAAW;KACpC,CAAC;AACJ,CAAC"}

package/dist/query.d.ts

@@ -37,6 +37,18 @@ 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.
  */
@@ -56,7 +68,9 @@ export interface CreateQuery {
 /**
  * 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> = Omit<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>, 'queryFn' | 'queryKey'> & {
+    dependsOn?: QueryDependencyTuple<any[], 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.1",
+  "version": "0.8.0",
   "description": "TanStack Query service layer for the VEAMS StatusQuo ecosystem.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/__tests__/provider.spec.ts

@@ -10,12 +10,21 @@ describe('Query Manager API', () => {
     const cancelQueriesSpy = jest.spyOn(queryClient, 'cancelQueries');
     const resetQueriesSpy = jest.spyOn(queryClient, 'resetQueries');
     const removeQueriesSpy = jest.spyOn(queryClient, 'removeQueries');
+    const fetchUser = jest.fn().mockResolvedValue({ id: 7 });
+    const fetchQuerySpy = jest.spyOn(queryClient, 'fetchQuery');
     const manager = setupQueryManager(queryClient);
 
     manager.setQueryData<{ id: number }>(['user', 42], { id: 42 });
 
     expect(manager.getQueryData<{ id: number }>(['user', 42])).toEqual({ id: 42 });
     expect(manager.unsafe_getClient()).toBe(queryClient);
+    await expect(
+      manager.fetchQuery({
+        queryKey: ['user', 7],
+        queryFn: fetchUser,
+        staleTime: 60_000,
+      })
+    ).resolves.toEqual({ id: 7 });
 
     await manager.invalidateQueries({ queryKey: ['user'] });
     await manager.refetchQueries({ queryKey: ['user'] });
@@ -23,6 +32,11 @@ describe('Query Manager API', () => {
     await manager.resetQueries({ queryKey: ['user'] });
     manager.removeQueries({ queryKey: ['user'] });
 
+    expect(fetchQuerySpy).toHaveBeenCalledWith({
+      queryKey: ['user', 7],
+      queryFn: fetchUser,
+      staleTime: 60_000,
+    });
     expect(invalidateQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
     expect(refetchQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
     expect(cancelQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });

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/provider.ts

@@ -66,6 +66,8 @@ export interface QueryManager {
   createQueryAndMutation: CreateQueryAndMutation;
   // Cancels active queries for the specified filters.
   cancelQueries: QueryClient['cancelQueries'];
+  // Fetches one query through the shared QueryClient and returns the resolved data.
+  fetchQuery: QueryClient['fetchQuery'];
   // Synchronously retrieves a snapshot of the current query data.
   getQueryData: QueryClient['getQueryData'];
   // Marks queries as invalid to trigger a refetch if they are active.
@@ -149,6 +151,8 @@ export function setupQueryManager(queryClient: QueryClient): QueryManager {
     },
     // Proxy for canceling queries with this client context.
     cancelQueries: queryClient.cancelQueries.bind(queryClient),
+    // Proxy for fetching one query with this client context.
+    fetchQuery: queryClient.fetchQuery.bind(queryClient),
     // Proxy for retrieving query data with this client context.
     getQueryData: queryClient.getQueryData.bind(queryClient),
     // Proxy for invalidating queries with this client context.

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,6 +89,32 @@ 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.
  */
@@ -142,7 +169,9 @@ export type QueryServiceOptions<
 > = Omit<
   QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
   'queryFn' | 'queryKey'
->;
+> & {
+  dependsOn?: QueryDependencyTuple<any[], TQueryKey>;
+};
 
 /**
  * Extracts and maps status and fetchStatus to our QueryMetaState interface.
@@ -181,7 +210,14 @@ export function setupQuery(queryClient: QueryClient): CreateUntrackedQuery {
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
     options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
   ): 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);
   };
 }
 
@@ -211,34 +247,62 @@ export function setupTrackedQuery(
     queryFn: QueryFunction<TQueryFnData, TQueryKey>,
     options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
   ): 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 +311,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 +322,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 +361,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 +410,7 @@ function createQueryService<
         queryClient.invalidateQueries(
           {
             exact: true,
-            queryKey,
+            queryKey: resolvedQueryKey,
             ...(invalidateOptions?.refetchType === undefined
               ? {}
               : { refetchType: invalidateOptions.refetchType }),
@@ -331,6 +422,146 @@ function createQueryService<
   };
 }
 
+function bindQueryDependencies<
+  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<any[], 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<
+  TQueryFnData = unknown,
+  TError = Error,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+>(
+  queryClient: QueryClient,
+  baseQueryKey: TQueryKey,
+  setDerivedState: (derivedOptions: QueryDependencyDerivedOptions<TQueryKey>) => void,
+  dependsOn: QueryDependencyTuple<any[], 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,
+>(
+  options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+): {
+  dependsOn?: QueryDependencyTuple<any[], 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 +571,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