@robohall/react-query-factory 2.2.0 → 3.0.0

package/README.md

@@ -417,6 +417,54 @@ The `.infinite()` key includes an `'infinite'` segment to keep it separate from
 
 ---
 
+## Dependency injection
+
+By default, whatever you pass as `params` is appended to the query key. That's exactly what you want for serializable inputs — but some `queryFn` inputs are **not** serializable and must not be in the key: an API client from React context, an auth token, a translator, a per-tenant SDK instance. Putting them in the key leaks them into the cache and devtools, and busts the cache every time they change identity.
+
+Declare such inputs as an optional **third argument** to `queryFn` — a `deps` bag. It is supplied at the call site via `.inject(deps)`, is passed to `queryFn` (and `select`), and is **never** added to the query key:
+
+```typescript
+const describeInstances = queryFactory({
+  queryKey: ['ec2:DescribeInstances'],
+  queryFn: (
+    params: DescribeInstancesCommandInput,
+    ctx,
+    deps: { client: EC2Client }, // ← non-serializable, never keyed
+  ) =>
+    deps.client.send(
+      new DescribeInstancesCommand({ ...params, NextToken: ctx.pageParam }),
+      { abortSignal: ctx.signal },
+    ),
+});
+
+function InstancesTable() {
+  const client = useContext(EC2ClientContext); // runtime dependency
+  const { data } = useQuery(
+    describeInstances({ MaxResults: 20 }).inject({ client }),
+  );
+  // query key is ['ec2:DescribeInstances', { MaxResults: 20 }] — no client in it
+}
+```
+
+When a factory declares deps, `.inject()` is **required by the type system** — the bare call returns a `PendingInjection` that is a compile error to pass to `useQuery`/`useInfiniteQuery`:
+
+```typescript
+useQuery(describeInstances({ MaxResults: 20 })); // ❌ Type error — call .inject({ client })
+useQuery(describeInstances({ MaxResults: 20 }).inject({ client })); // ✅
+```
+
+A factory that declares **no** deps is unaffected — its calls return options directly and there is no `.inject` to call. Nothing about the common path changes.
+
+Key points:
+
+- **`deps` never enters the query key** — that's the whole purpose. If a value should be part of cache identity, pass it as `params`, not `deps`.
+- **One shared bag.** `queryFn` and `select` receive the _same_ `deps`; their `deps` types must agree.
+- **Invalidation needs no deps.** The pending object still exposes the real `queryKey`, so `queryClient.invalidateQueries(describeInstances({ MaxResults: 20 }))` works without injecting anything. (`prefetchQuery`, which actually runs the `queryFn`, does require `.inject()`.)
+- **Composition inherits the requirement.** A select-only child of a factory that declares deps inherits the deps requirement automatically.
+- `.inject()` works the same on `.infinite()`: `describeInstances.infinite(params).inject({ client })`.
+
+---
+
 ## Performance
 
 TanStack Query's default `staleTime` is `0` — data is considered stale immediately, so a background refetch fires on every mount, window focus, and reconnect. For a single-page query that's one API call; for a crawling factory it's the full crawl repeated. Set `staleTime` in the factory config to match how often the underlying data actually changes:
@@ -458,19 +506,20 @@ Creates a child factory. Two overloads:
 
 All fields except `reduce` and `shouldFetchNextPage` are the standard TanStack Query API — the same types and semantics you'd pass to `useQuery` or `useInfiniteQuery`. The factory doesn't reinvent them; it just requires certain combinations to be present in order to activate crawling.
 
-| Field                               | Type                                                                                              | Notes                                                                                                                                                                                   |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `queryKey`                          | `QueryKey`                                                                                        | Namespace segments. Params are appended at call time.                                                                                                                                   |
-| `queryFn`                           | `(params: TParams, ctx: QueryFunctionContext) => TData \| Promise<TData> \| AsyncIterable<TData>` | Same as TanStack, with an extra leading `params` argument. Returns an `AsyncIterable` to use iterator-based crawling.                                                                   |
-| `select`                            | `(data: TData) => TSelected`                                                                      | Exact TanStack API. Composed automatically on child factories.                                                                                                                          |
-| `getNextPageParam`                  | `GetNextPageParamFunction<TPageParam, TData>`                                                     | Exact TanStack API. Required (with `shouldFetchNextPage`) to activate cursor-based crawling. Required (with `initialPageParam`) for `.infinite()`.                                      |
-| `initialPageParam`                  | `TPageParam`                                                                                      | Exact TanStack API. Drives `TPageParam` inference. Required for `.infinite()` to work at runtime.                                                                                       |
-| `getPreviousPageParam`              | `GetPreviousPageParamFunction<TPageParam, TData>`                                                 | Exact TanStack API. Passed through on `.infinite()`.                                                                                                                                    |
-| `shouldFetchNextPage`               | `(combined: TSelected \| undefined, crawlOptions: TCrawlOptions) => boolean`                      | Library addition. **Required to activate crawling.** Called after each page — return `true` to keep fetching, `false` to stop.                                                          |
-| `reduce`                            | `(acc: TSelected \| undefined, page: TData) => TSelected`                                         | Library addition. Optional. Folds crawled pages into a single `TSelected` value; when omitted the result is an array of all fetched raw pages (`TData[]`).                              |
-| + all `StandardQueryOptions` fields |                                                                                                   | `staleTime`, `gcTime`, `retry`, `enabled`, `refetchOnWindowFocus`, `placeholderData`, `initialData`, `meta`, etc. Function-form callbacks are supported wherever TanStack accepts them. |
-
-### `QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions>`
+| Field                               | Type                                                                                                           | Notes                                                                                                                                                                                                                                                                           |
+| ----------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `queryKey`                          | `QueryKey`                                                                                                     | Namespace segments. Params are appended at call time.                                                                                                                                                                                                                           |
+| `queryFn`                           | `(params: TParams, ctx: QueryFunctionContext, deps: TDeps) => TData \| Promise<TData> \| AsyncIterable<TData>` | Same as TanStack, with an extra leading `params` argument and an optional trailing `deps` argument for non-serializable dependencies (see [Dependency injection](#dependency-injection)). Returns an `AsyncIterable` to use iterator-based crawling.                            |
+| `select`                            | `(data: TData, deps: TDeps) => TSelected`                                                                      | Exact TanStack API, plus the same injected `deps` bag as `queryFn`. Composed automatically on child factories.                                                                                                                                                                  |
+| `getNextPageParam`                  | `GetNextPageParamFunction<TPageParam, TData>`                                                                  | Exact TanStack API. Required (with `shouldFetchNextPage`) to activate cursor-based crawling. Required (with `initialPageParam`) for `.infinite()`.                                                                                                                              |
+| `initialPageParam`                  | `TPageParam`                                                                                                   | Exact TanStack API. Drives `TPageParam` inference. Required for `.infinite()` to work at runtime.                                                                                                                                                                               |
+| `getPreviousPageParam`              | `GetPreviousPageParamFunction<TPageParam, TData>`                                                              | Exact TanStack API. Passed through on `.infinite()`.                                                                                                                                                                                                                            |
+| `shouldFetchNextPage`               | `(combined: TSelected \| undefined, crawlOptions: TCrawlOptions) => boolean`                                   | Library addition. **Required to activate crawling.** Called after each page — return `true` to keep fetching, `false` to stop.                                                                                                                                                  |
+| `reduce`                            | `(acc: TSelected \| undefined, page: TData) => TSelected`                                                      | Library addition. Optional. Folds crawled pages into a single `TSelected` value; when omitted the result is an array of all fetched raw pages (`TData[]`).                                                                                                                      |
+| `deps` (3rd `queryFn` arg)          | `TDeps`                                                                                                        | Library addition. Inferred from the optional third `queryFn` parameter. A bag of non-serializable dependencies supplied at the call site via `.inject(deps)`; passed to `queryFn`/`select` but never added to the query key. See [Dependency injection](#dependency-injection). |
+| + all `StandardQueryOptions` fields |                                                                                                                | `staleTime`, `gcTime`, `retry`, `enabled`, `refetchOnWindowFocus`, `placeholderData`, `initialData`, `meta`, etc. Function-form callbacks are supported wherever TanStack accepts them.                                                                                         |
+
+### `QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, THasReduce, TDeps>`
 
 The callable factory returned by `queryFactory()`.
 
@@ -479,6 +528,8 @@ factory(params: TParams, crawlOptions?: TCrawlOptions): ResolvedQueryOptions  //
 factory.infinite(params, crawlOptions?)                : ResolvedInfiniteOptions // → useInfiniteQuery()
 ```
 
+When the factory declares dependencies (`TDeps` is non-`void`), both calls instead return a `PendingInjection` and you must call `.inject(deps)` to obtain the usable options — see [Dependency injection](#dependency-injection).
+
 ### `ResolvedQueryOptions`
 
 Return type of `factory(params)`. Pass directly to `useQuery()`. Contains an `initialPageParam?: never` field that prevents accidental use with `useInfiniteQuery`.
@@ -507,6 +558,24 @@ import type { FactoryCrawlOptions } from '@robohall/react-query-factory';
 type CrawlOpts = FactoryCrawlOptions<typeof describeInstances>; // → { minResults?: number }
 ```
 
+### `FactoryDeps<F>`
+
+Extracts the injected-dependencies type from a factory — the argument to `.inject()`. Resolves to `void` for factories that declare no dependencies.
+
+```typescript
+import type { FactoryDeps } from '@robohall/react-query-factory';
+
+type Deps = FactoryDeps<typeof describeInstances>; // → { client: EC2Client }
+```
+
+### `PendingInjection<TDeps, TResolved>`
+
+Returned by `factory(params)` / `factory.infinite(params)` when the factory declares dependencies. Carries the real `queryKey` (so it can still be passed to `invalidateQueries` and other filter APIs) but its `queryFn` is branded so the object cannot be passed to `useQuery`/`useInfiniteQuery` until `.inject(deps)` supplies the dependencies. See [Dependency injection](#dependency-injection).
+
+### `WithInjection<TDeps, TResolved>`
+
+Resolves to `TResolved` when `TDeps` is `void`, or to `PendingInjection<TDeps, TResolved>` otherwise. This is what makes `.inject()` required exactly when — and only when — a factory declares dependencies.
+
 ---
 
 ## Running the sandbox
@@ -515,4 +584,4 @@ type CrawlOpts = FactoryCrawlOptions<typeof describeInstances>; // → { minResu
 npm run sandbox
 ```
 
-Starts a Vite dev server with interactive demos covering every pattern: basic single-page fetch, async iterator queryFns, crawl-then-render, render-while-crawling, on-demand infinite pagination, client-side search with early stopping, factory composition, and scoped cache invalidation.
+Starts a Vite dev server with interactive demos covering every pattern: basic single-page fetch, async iterator queryFns, crawl-then-render, render-while-crawling, on-demand infinite pagination, client-side search with early stopping, factory composition, dependency injection, and scoped cache invalidation.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { QueryObserverOptions, QueryKey, QueryFunctionContext, InfiniteData, GetNextPageParamFunction, GetPreviousPageParamFunction } from '@tanstack/react-query';
+import { QueryKey, QueryObserverOptions, QueryFunctionContext, InfiniteData, GetNextPageParamFunction, GetPreviousPageParamFunction } from '@tanstack/react-query';
 
 /**
  * All TanStack Query options that apply to both regular and infinite queries,
@@ -23,14 +23,18 @@ type StandardQueryOptions<TError = Error, TData = unknown> = Omit<QueryObserverO
  * mirrors TanStack's own API and ensures `TPageParam` is inferred from the
  * concrete initial value (so `ctx.pageParam` in `queryFn` is typed correctly).
  */
-type QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> = StandardQueryOptions<TError, TData> & {
+type QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void> = StandardQueryOptions<TError, TData> & {
     /** Namespace segments. Params are appended as the final element at call time,
      *  giving a full key of [...namespace, 'infinite'?, params, crawlOptions?]. */
     queryKey: QueryKey;
+    /** The optional third argument is a bag of non-serializable runtime dependencies
+     *  (an API client, a token, a translator…). It is supplied at the call site via
+     *  `factory(params).inject(deps)` and is deliberately NEVER part of the queryKey.
+     *  Declaring it makes `.inject()` required before the options can reach useQuery. */
     queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
-    select?: (data: TData) => TSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => TData | Promise<TData>;
+    select?: (data: TData, deps: TDeps) => TSelected;
     /** TanStack v5 generic order: GetNextPageParamFunction<TPageParam, TData> */
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     /** Drives TPageParam inference so ctx.pageParam in queryFn is typed as TPageParam.
@@ -82,6 +86,33 @@ type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unkno
     /** Required so this type satisfies useInfiniteQuery, which requires initialPageParam. */
     initialPageParam: TPageParam;
 };
+declare const INJECTION_REQUIRED: unique symbol;
+/**
+ * What `factory(params)` / `factory.infinite(params)` return when the factory's
+ * `queryFn`/`select` declare a non-serializable dependency bag (the third `queryFn`
+ * argument, `TDeps`).
+ *
+ * It carries the real `queryKey` — so it can still be handed to
+ * `invalidateQueries` and other filter APIs without supplying deps — but its
+ * `queryFn` is branded with a type that is NOT assignable to TanStack's
+ * `QueryFunction`. That makes it a compile error to pass directly to
+ * `useQuery`/`useInfiniteQuery`: the only way to obtain usable options is to call
+ * `.inject(deps)`, which returns the real `TResolved`.
+ *
+ * `deps` is deliberately never part of the query key.
+ */
+interface PendingInjection<TDeps, TResolved> {
+    queryKey: QueryKey;
+    queryFn: {
+        readonly [INJECTION_REQUIRED]: 'Call .inject({ ...deps }) before passing this to useQuery/useInfiniteQuery';
+    };
+    inject(deps: TDeps): TResolved;
+}
+/**
+ * Resolves to `TResolved` when the factory declares no dependencies (`TDeps` is
+ * `void`), or to a `PendingInjection` that forces `.inject(deps)` when it does.
+ */
+type WithInjection<TDeps, TResolved> = [TDeps] extends [void] ? TResolved : PendingInjection<TDeps, TResolved>;
 /**
  * A callable factory produced by `queryFactory()`.
  *
@@ -95,32 +126,38 @@ type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unkno
  * `params` is always optional. Calling with no arguments produces just the
  * namespace key, which is useful for broad cache invalidation:
  * `queryClient.invalidateQueries(factory())`
+ *
+ * When `TDeps` is non-`void` (the `queryFn` declares a third argument), both calls
+ * return a `PendingInjection` and the caller must `.inject(deps)` before the
+ * options can reach `useQuery`/`useInfiniteQuery`.
  */
-interface QueryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, THasReduce extends boolean = boolean> {
-    (params?: TParams, crawlOptions?: TCrawlOptions): ResolvedQueryOptions<TData, TError, TSelected>;
-    infinite(params?: TParams, crawlOptions?: TCrawlOptions): ResolvedInfiniteOptions<TData, TError, TPageParam, InfiniteData<TSelected, TPageParam>>;
+interface QueryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, THasReduce extends boolean = boolean, TDeps = void> {
+    (params?: TParams, crawlOptions?: TCrawlOptions): WithInjection<TDeps, ResolvedQueryOptions<TData, TError, TSelected>>;
+    infinite(params?: TParams, crawlOptions?: TCrawlOptions): WithInjection<TDeps, ResolvedInfiniteOptions<TData, TError, TPageParam, InfiniteData<TSelected, TPageParam>>>;
 }
 /** Extracts the params type from a factory — the first argument of a factory call. */
 type FactoryParams<F> = F extends QueryFactory<infer TParams, any, any, any, any, any, any> ? TParams : never;
 /** Extracts the crawl options type from a factory — the second argument of a factory call. */
 type FactoryCrawlOptions<F> = F extends QueryFactory<any, any, any, any, any, infer TCrawlOptions, any> ? TCrawlOptions : never;
+/** Extracts the injected-dependencies type from a factory — the argument to `.inject()`. */
+type FactoryDeps<F> = F extends QueryFactory<any, any, any, any, any, any, any, infer TDeps> ? TDeps : never;
 /**
  * Creates a standalone query factory with pagination and reduce. When `reduce` is
  * present, `shouldFetchNextPage` receives `TSelected` (never undefined) because
  * reduce always runs before the crawl-stop check.
  */
-declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(config: StandardQueryOptions<TError, TData> & {
     queryKey: QueryKey;
     queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
-    select?: (data: TData) => TSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => TData | Promise<TData>;
+    select?: (data: TData, deps: TDeps) => TSelected;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce: (accumulator: TSelected | undefined, page: TData) => TSelected;
     shouldFetchNextPage?: (combined: TSelected, crawlOptions: TCrawlOptions) => boolean;
-}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true>;
+}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true, TDeps>;
 /**
  * Creates a standalone query factory from a config object.
  *
@@ -131,24 +168,24 @@ declare function queryFactory<TParams = void, TData = unknown, TError = Error, T
  * });
  * // useQuery(usersFactory({ page: 1 }))
  */
-declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(config: QueryFactoryConfig<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions>): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false>;
+declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(config: QueryFactoryConfig<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, TDeps>): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false, TDeps>;
 /**
  * Creates a child factory whose queryFn returns an AsyncIterable (e.g. an AWS SDK v3
  * paginator). Inherits the parent's key namespace. Use this overload when switching
  * to a paginator-based fetch while keeping the same result shape and crawl options.
  */
-declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TParentSelected = TData, TChildSelected = TParentSelected, TParentParams = TChildParams, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, any, any>, config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TParentSelected = TData, TChildSelected = TParentSelected, TParentParams = TChildParams, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, any, any, any>, config: StandardQueryOptions<TError, TData> & {
     queryKey?: QueryKey;
     queryFn: (params: TChildParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => AsyncIterable<TData>;
-    select?: (data: TData) => TChildSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => AsyncIterable<TData>;
+    select?: (data: TData, deps: TDeps) => TChildSelected;
     reduce?: (accumulator: TChildSelected | undefined, page: TData) => TChildSelected;
     shouldFetchNextPage?: (combined: TChildSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
-}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean>;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean, TDeps>;
 /**
  * Creates a child factory that inherits the query key and standard options from
  * `parent` and introduces a new `queryFn`. The child's query key is appended to
@@ -156,10 +193,10 @@ declare function queryFactory<TChildParams extends TParentParams, TData = unknow
  *
  * Use this overload when the child fetches different data than the parent.
  */
-declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TChildSelected = TData, TParentParams = TChildParams, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(parent: QueryFactory<TParentParams, any, any, any, any, any, any>, config: Omit<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions>, 'queryKey' | 'queryFn'> & {
+declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TChildSelected = TData, TParentParams = TChildParams, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(parent: QueryFactory<TParentParams, any, any, any, any, any, any, any>, config: Omit<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, TDeps>, 'queryKey' | 'queryFn'> & {
     queryKey?: QueryKey;
-    queryFn: NonNullable<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam>['queryFn']>;
-}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean>;
+    queryFn: NonNullable<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, TDeps>['queryFn']>;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean, TDeps>;
 /**
  * Creates a child factory that reuses the parent's `queryFn` and pagination
  * config. Useful for adding a `select` transform, narrowing params, or
@@ -167,49 +204,49 @@ declare function queryFactory<TChildParams extends TParentParams, TData = unknow
  * without changing what data is fetched. Parent and child `select` functions
  * are automatically composed: `child.select(parent.select(data))`.
  */
-declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TParentSelected = TData, TChildSelected = TParentSelected, TParentParams = TChildParams, TPageParam = unknown, TParentCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TChildCrawlOptions extends Record<string, unknown> = TParentCrawlOptions, TParentHasReduce extends boolean = boolean>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, TParentCrawlOptions, TParentHasReduce>, config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TParentSelected = TData, TChildSelected = TParentSelected, TParentParams = TChildParams, TPageParam = unknown, TParentCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TChildCrawlOptions extends Record<string, unknown> = TParentCrawlOptions, TParentHasReduce extends boolean = boolean, TParentDeps = void>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, TParentCrawlOptions, TParentHasReduce, TParentDeps>, config: StandardQueryOptions<TError, TData> & {
     queryKey?: QueryKey;
     queryFn?: never;
-    select?: (data: TParentSelected) => TChildSelected;
+    select?: (data: TParentSelected, deps: TParentDeps) => TChildSelected;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce?: (accumulator: TChildSelected | undefined, page: TData) => TChildSelected;
     shouldFetchNextPage?: (combined: TParentHasReduce extends true ? TChildSelected : TChildSelected | undefined, crawlOptions: TChildCrawlOptions) => boolean;
-}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions, TParentHasReduce>;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions, TParentHasReduce, TParentDeps>;
 /**
  * Creates a standalone factory whose queryFn returns an AsyncIterable (e.g. an AWS SDK v3
  * paginator). The library drives the crawl with `for await...of`; `getNextPageParam` and
  * `initialPageParam` are not required for `useQuery` mode. When `reduce` is present,
  * `shouldFetchNextPage` receives `TSelected` (never undefined).
  */
-declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(config: StandardQueryOptions<TError, TData> & {
     queryKey: QueryKey;
     queryFn: (params: TParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => AsyncIterable<TData>;
-    select?: (data: TData) => TSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => AsyncIterable<TData>;
+    select?: (data: TData, deps: TDeps) => TSelected;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce: (accumulator: TSelected | undefined, page: TData) => TSelected;
     shouldFetchNextPage?: (combined: TSelected, crawlOptions: TCrawlOptions) => boolean;
-}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true>;
+}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true, TDeps>;
 /**
  * Creates a standalone factory whose queryFn returns an AsyncIterable, without a `reduce`
  * function. Result is `TData[]` (one element per yielded page).
  */
-declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(config: StandardQueryOptions<TError, TData> & {
     queryKey: QueryKey;
     queryFn: (params: TParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => AsyncIterable<TData>;
-    select?: (data: TData) => TSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => AsyncIterable<TData>;
+    select?: (data: TData, deps: TDeps) => TSelected;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce?: never;
     shouldFetchNextPage: (combined: TSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
-}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false>;
+}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false, TDeps>;
 
-export { type FactoryCrawlOptions, type FactoryParams, type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };
+export { type FactoryCrawlOptions, type FactoryDeps, type FactoryParams, type PendingInjection, type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, type WithInjection, queryFactory };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { QueryObserverOptions, QueryKey, QueryFunctionContext, InfiniteData, GetNextPageParamFunction, GetPreviousPageParamFunction } from '@tanstack/react-query';
+import { QueryKey, QueryObserverOptions, QueryFunctionContext, InfiniteData, GetNextPageParamFunction, GetPreviousPageParamFunction } from '@tanstack/react-query';
 
 /**
  * All TanStack Query options that apply to both regular and infinite queries,
@@ -23,14 +23,18 @@ type StandardQueryOptions<TError = Error, TData = unknown> = Omit<QueryObserverO
  * mirrors TanStack's own API and ensures `TPageParam` is inferred from the
  * concrete initial value (so `ctx.pageParam` in `queryFn` is typed correctly).
  */
-type QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> = StandardQueryOptions<TError, TData> & {
+type QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void> = StandardQueryOptions<TError, TData> & {
     /** Namespace segments. Params are appended as the final element at call time,
      *  giving a full key of [...namespace, 'infinite'?, params, crawlOptions?]. */
     queryKey: QueryKey;
+    /** The optional third argument is a bag of non-serializable runtime dependencies
+     *  (an API client, a token, a translator…). It is supplied at the call site via
+     *  `factory(params).inject(deps)` and is deliberately NEVER part of the queryKey.
+     *  Declaring it makes `.inject()` required before the options can reach useQuery. */
     queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
-    select?: (data: TData) => TSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => TData | Promise<TData>;
+    select?: (data: TData, deps: TDeps) => TSelected;
     /** TanStack v5 generic order: GetNextPageParamFunction<TPageParam, TData> */
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     /** Drives TPageParam inference so ctx.pageParam in queryFn is typed as TPageParam.
@@ -82,6 +86,33 @@ type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unkno
     /** Required so this type satisfies useInfiniteQuery, which requires initialPageParam. */
     initialPageParam: TPageParam;
 };
+declare const INJECTION_REQUIRED: unique symbol;
+/**
+ * What `factory(params)` / `factory.infinite(params)` return when the factory's
+ * `queryFn`/`select` declare a non-serializable dependency bag (the third `queryFn`
+ * argument, `TDeps`).
+ *
+ * It carries the real `queryKey` — so it can still be handed to
+ * `invalidateQueries` and other filter APIs without supplying deps — but its
+ * `queryFn` is branded with a type that is NOT assignable to TanStack's
+ * `QueryFunction`. That makes it a compile error to pass directly to
+ * `useQuery`/`useInfiniteQuery`: the only way to obtain usable options is to call
+ * `.inject(deps)`, which returns the real `TResolved`.
+ *
+ * `deps` is deliberately never part of the query key.
+ */
+interface PendingInjection<TDeps, TResolved> {
+    queryKey: QueryKey;
+    queryFn: {
+        readonly [INJECTION_REQUIRED]: 'Call .inject({ ...deps }) before passing this to useQuery/useInfiniteQuery';
+    };
+    inject(deps: TDeps): TResolved;
+}
+/**
+ * Resolves to `TResolved` when the factory declares no dependencies (`TDeps` is
+ * `void`), or to a `PendingInjection` that forces `.inject(deps)` when it does.
+ */
+type WithInjection<TDeps, TResolved> = [TDeps] extends [void] ? TResolved : PendingInjection<TDeps, TResolved>;
 /**
  * A callable factory produced by `queryFactory()`.
  *
@@ -95,32 +126,38 @@ type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unkno
  * `params` is always optional. Calling with no arguments produces just the
  * namespace key, which is useful for broad cache invalidation:
  * `queryClient.invalidateQueries(factory())`
+ *
+ * When `TDeps` is non-`void` (the `queryFn` declares a third argument), both calls
+ * return a `PendingInjection` and the caller must `.inject(deps)` before the
+ * options can reach `useQuery`/`useInfiniteQuery`.
  */
-interface QueryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, THasReduce extends boolean = boolean> {
-    (params?: TParams, crawlOptions?: TCrawlOptions): ResolvedQueryOptions<TData, TError, TSelected>;
-    infinite(params?: TParams, crawlOptions?: TCrawlOptions): ResolvedInfiniteOptions<TData, TError, TPageParam, InfiniteData<TSelected, TPageParam>>;
+interface QueryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, THasReduce extends boolean = boolean, TDeps = void> {
+    (params?: TParams, crawlOptions?: TCrawlOptions): WithInjection<TDeps, ResolvedQueryOptions<TData, TError, TSelected>>;
+    infinite(params?: TParams, crawlOptions?: TCrawlOptions): WithInjection<TDeps, ResolvedInfiniteOptions<TData, TError, TPageParam, InfiniteData<TSelected, TPageParam>>>;
 }
 /** Extracts the params type from a factory — the first argument of a factory call. */
 type FactoryParams<F> = F extends QueryFactory<infer TParams, any, any, any, any, any, any> ? TParams : never;
 /** Extracts the crawl options type from a factory — the second argument of a factory call. */
 type FactoryCrawlOptions<F> = F extends QueryFactory<any, any, any, any, any, infer TCrawlOptions, any> ? TCrawlOptions : never;
+/** Extracts the injected-dependencies type from a factory — the argument to `.inject()`. */
+type FactoryDeps<F> = F extends QueryFactory<any, any, any, any, any, any, any, infer TDeps> ? TDeps : never;
 /**
  * Creates a standalone query factory with pagination and reduce. When `reduce` is
  * present, `shouldFetchNextPage` receives `TSelected` (never undefined) because
  * reduce always runs before the crawl-stop check.
  */
-declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(config: StandardQueryOptions<TError, TData> & {
     queryKey: QueryKey;
     queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
-    select?: (data: TData) => TSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => TData | Promise<TData>;
+    select?: (data: TData, deps: TDeps) => TSelected;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce: (accumulator: TSelected | undefined, page: TData) => TSelected;
     shouldFetchNextPage?: (combined: TSelected, crawlOptions: TCrawlOptions) => boolean;
-}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true>;
+}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true, TDeps>;
 /**
  * Creates a standalone query factory from a config object.
  *
@@ -131,24 +168,24 @@ declare function queryFactory<TParams = void, TData = unknown, TError = Error, T
  * });
  * // useQuery(usersFactory({ page: 1 }))
  */
-declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(config: QueryFactoryConfig<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions>): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false>;
+declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(config: QueryFactoryConfig<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, TDeps>): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false, TDeps>;
 /**
  * Creates a child factory whose queryFn returns an AsyncIterable (e.g. an AWS SDK v3
  * paginator). Inherits the parent's key namespace. Use this overload when switching
  * to a paginator-based fetch while keeping the same result shape and crawl options.
  */
-declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TParentSelected = TData, TChildSelected = TParentSelected, TParentParams = TChildParams, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, any, any>, config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TParentSelected = TData, TChildSelected = TParentSelected, TParentParams = TChildParams, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, any, any, any>, config: StandardQueryOptions<TError, TData> & {
     queryKey?: QueryKey;
     queryFn: (params: TChildParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => AsyncIterable<TData>;
-    select?: (data: TData) => TChildSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => AsyncIterable<TData>;
+    select?: (data: TData, deps: TDeps) => TChildSelected;
     reduce?: (accumulator: TChildSelected | undefined, page: TData) => TChildSelected;
     shouldFetchNextPage?: (combined: TChildSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
-}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean>;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean, TDeps>;
 /**
  * Creates a child factory that inherits the query key and standard options from
  * `parent` and introduces a new `queryFn`. The child's query key is appended to
@@ -156,10 +193,10 @@ declare function queryFactory<TChildParams extends TParentParams, TData = unknow
  *
  * Use this overload when the child fetches different data than the parent.
  */
-declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TChildSelected = TData, TParentParams = TChildParams, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(parent: QueryFactory<TParentParams, any, any, any, any, any, any>, config: Omit<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions>, 'queryKey' | 'queryFn'> & {
+declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TChildSelected = TData, TParentParams = TChildParams, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(parent: QueryFactory<TParentParams, any, any, any, any, any, any, any>, config: Omit<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, TDeps>, 'queryKey' | 'queryFn'> & {
     queryKey?: QueryKey;
-    queryFn: NonNullable<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam>['queryFn']>;
-}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean>;
+    queryFn: NonNullable<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, TDeps>['queryFn']>;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean, TDeps>;
 /**
  * Creates a child factory that reuses the parent's `queryFn` and pagination
  * config. Useful for adding a `select` transform, narrowing params, or
@@ -167,49 +204,49 @@ declare function queryFactory<TChildParams extends TParentParams, TData = unknow
  * without changing what data is fetched. Parent and child `select` functions
  * are automatically composed: `child.select(parent.select(data))`.
  */
-declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TParentSelected = TData, TChildSelected = TParentSelected, TParentParams = TChildParams, TPageParam = unknown, TParentCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TChildCrawlOptions extends Record<string, unknown> = TParentCrawlOptions, TParentHasReduce extends boolean = boolean>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, TParentCrawlOptions, TParentHasReduce>, config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TChildParams extends TParentParams, TData = unknown, TError = Error, TParentSelected = TData, TChildSelected = TParentSelected, TParentParams = TChildParams, TPageParam = unknown, TParentCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TChildCrawlOptions extends Record<string, unknown> = TParentCrawlOptions, TParentHasReduce extends boolean = boolean, TParentDeps = void>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, TParentCrawlOptions, TParentHasReduce, TParentDeps>, config: StandardQueryOptions<TError, TData> & {
     queryKey?: QueryKey;
     queryFn?: never;
-    select?: (data: TParentSelected) => TChildSelected;
+    select?: (data: TParentSelected, deps: TParentDeps) => TChildSelected;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce?: (accumulator: TChildSelected | undefined, page: TData) => TChildSelected;
     shouldFetchNextPage?: (combined: TParentHasReduce extends true ? TChildSelected : TChildSelected | undefined, crawlOptions: TChildCrawlOptions) => boolean;
-}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions, TParentHasReduce>;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions, TParentHasReduce, TParentDeps>;
 /**
  * Creates a standalone factory whose queryFn returns an AsyncIterable (e.g. an AWS SDK v3
  * paginator). The library drives the crawl with `for await...of`; `getNextPageParam` and
  * `initialPageParam` are not required for `useQuery` mode. When `reduce` is present,
  * `shouldFetchNextPage` receives `TSelected` (never undefined).
  */
-declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(config: StandardQueryOptions<TError, TData> & {
     queryKey: QueryKey;
     queryFn: (params: TParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => AsyncIterable<TData>;
-    select?: (data: TData) => TSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => AsyncIterable<TData>;
+    select?: (data: TData, deps: TDeps) => TSelected;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce: (accumulator: TSelected | undefined, page: TData) => TSelected;
     shouldFetchNextPage?: (combined: TSelected, crawlOptions: TCrawlOptions) => boolean;
-}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true>;
+}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true, TDeps>;
 /**
  * Creates a standalone factory whose queryFn returns an AsyncIterable, without a `reduce`
  * function. Result is `TData[]` (one element per yielded page).
  */
-declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>>(config: StandardQueryOptions<TError, TData> & {
+declare function queryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>, TDeps = void>(config: StandardQueryOptions<TError, TData> & {
     queryKey: QueryKey;
     queryFn: (params: TParams, context: QueryFunctionContext<QueryKey, [
         unknown
-    ] extends [TPageParam] ? never : TPageParam>) => AsyncIterable<TData>;
-    select?: (data: TData) => TSelected;
+    ] extends [TPageParam] ? never : TPageParam>, deps: TDeps) => AsyncIterable<TData>;
+    select?: (data: TData, deps: TDeps) => TSelected;
     getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce?: never;
     shouldFetchNextPage: (combined: TSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
-}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false>;
+}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false, TDeps>;
 
-export { type FactoryCrawlOptions, type FactoryParams, type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };
+export { type FactoryCrawlOptions, type FactoryDeps, type FactoryParams, type PendingInjection, type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, type WithInjection, queryFactory };

package/dist/index.js

@@ -31,6 +31,9 @@ var noNextPage = () => void 0;
 function isAsyncIterable(value) {
   return value != null && typeof value[Symbol.asyncIterator] === "function";
 }
+function invokeQueryFn(queryFn, params, ctx, deps) {
+  return deps === void 0 ? queryFn(params, ctx) : queryFn(params, ctx, deps);
+}
 function resolveKey(namespace, params, crawlOptions) {
   const withParams = params === void 0 ? namespace : [...namespace, params];
   if (!crawlOptions) return withParams;
@@ -55,22 +58,22 @@ function buildChildKey(parentKey, ownSegments, params, crawlOptions, infinite) {
   const withInfinite = infinite ? [...withOwn, "infinite"] : withOwn;
   return defined ? [...withInfinite, defined] : withInfinite;
 }
-function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, select) {
+function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, select, deps) {
   return (lastPage, allPages, lastPageParam, allPageParams) => {
-    const combined = select ? select(lastPage) : lastPage;
+    const combined = select ? select(lastPage, deps) : lastPage;
     if (!shouldFetchNextPage(combined, crawlOptions)) return void 0;
     return getNextPageParam(lastPage, allPages, lastPageParam, allPageParams);
   };
 }
 function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shouldFetchNextPage, reduce) {
-  return async (params, crawlOptions, context) => {
+  return async (params, crawlOptions, deps, context) => {
     var _a, _b, _c;
     if ((_a = context.signal) == null ? void 0 : _a.aborted) {
       if (reduce) throw new DOMException("Aborted", "AbortError");
       return [];
     }
     const ctx = { ...context, pageParam: initialPageParam };
-    const initialResult = queryFn(params, ctx);
+    const initialResult = invokeQueryFn(queryFn, params, ctx, deps);
     if (isAsyncIterable(initialResult)) {
       const pages2 = [];
       let acc2 = void 0;
@@ -102,7 +105,12 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
       if (nextParam == null) break;
       currentParam = nextParam;
       ctx.pageParam = currentParam;
-      page = await queryFn(params, ctx);
+      page = await invokeQueryFn(
+        queryFn,
+        params,
+        ctx,
+        deps
+      );
     }
     if (reduce) {
       if (acc === void 0) throw new DOMException("Aborted", "AbortError");
@@ -111,13 +119,28 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
     return pages;
   };
 }
+function buildAutoConsumeQueryFn(queryFn, reduce) {
+  return async (params, deps, context) => {
+    var _a;
+    const result = await invokeQueryFn(queryFn, params, context, deps);
+    if (!isAsyncIterable(result)) return result;
+    const pages = [];
+    let acc = void 0;
+    for await (const page of result) {
+      if ((_a = context.signal) == null ? void 0 : _a.aborted) break;
+      pages.push(page);
+      if (reduce) acc = reduce(acc, page);
+    }
+    return reduce ? acc !== void 0 ? acc : pages : pages;
+  };
+}
 function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNextPage, reduce) {
-  return async (params, crawlOptions, context) => {
+  return async (params, crawlOptions, deps, context) => {
     var _a, _b, _c;
     if ((_a = context.signal) == null ? void 0 : _a.aborted)
       throw new DOMException("Aborted", "AbortError");
     const ctx = { ...context, pageParam: context.pageParam };
-    const initialResult = queryFn(params, ctx);
+    const initialResult = invokeQueryFn(queryFn, params, ctx, deps);
     if (isAsyncIterable(initialResult)) {
       const pages2 = [];
       const startParam = context.pageParam;
@@ -154,7 +177,12 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
       if (!shouldFetchNextPage(acc, crawlOptions)) break;
       currentParam = nextParam;
       ctx.pageParam = currentParam;
-      page = await queryFn(params, ctx);
+      page = await invokeQueryFn(
+        queryFn,
+        params,
+        ctx,
+        deps
+      );
     }
     if (acc === void 0) throw new DOMException("Aborted", "AbortError");
     return { data: acc, nextPageParam: nextBatchParam };
@@ -184,62 +212,76 @@ function buildFactory(cfg) {
     shouldFetchNextPage,
     reduce
   ) : void 0;
+  const autoConsumeFn = !hasCrawling && rawQueryFn !== void 0 ? buildAutoConsumeQueryFn(rawQueryFn, reduce) : void 0;
   const infiniteCrawlingFn = hasInfiniteCrawling ? buildInfiniteCrawlingQueryFn(
     rawQueryFn,
     getNextPageParam,
     shouldFetchNextPage,
     reduce
   ) : void 0;
-  const envelopeSelect = infiniteCrawlingFn ? (data) => ({
-    ...data,
-    pages: data.pages.map((e) => select ? select(e.data) : e.data)
-  }) : void 0;
-  const infiniteSelect = !infiniteCrawlingFn && select ? (data) => ({
-    ...data,
-    pages: data.pages.map(select)
-  }) : void 0;
+  const bindSelect = (deps) => select === void 0 ? void 0 : deps === void 0 ? select : (data) => select(data, deps);
   const factory = function(params, crawlOptions = {}) {
     const queryKey = parentKey !== void 0 ? buildChildKey(parentKey, ownSegments, params, crawlOptions) : resolveKey(namespace, params, crawlOptions);
-    const resolvedQueryFn = crawlingFn ? (ctx) => crawlingFn(params, crawlOptions, ctx) : rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
-    return {
-      ...standardOptions,
-      queryKey,
-      ...resolvedQueryFn !== void 0 && { queryFn: resolvedQueryFn },
-      ...select !== void 0 && { select },
-      [FACTORY_CONFIG]: cfg
+    const make = (deps) => {
+      const resolvedQueryFn = crawlingFn ? (ctx) => crawlingFn(params, crawlOptions, deps, ctx) : autoConsumeFn ? (ctx) => autoConsumeFn(params, deps, ctx) : void 0;
+      const boundSelect = bindSelect(deps);
+      return {
+        ...standardOptions,
+        queryKey,
+        ...resolvedQueryFn !== void 0 && { queryFn: resolvedQueryFn },
+        ...boundSelect !== void 0 && { select: boundSelect },
+        inject: (injected) => make(injected),
+        [FACTORY_CONFIG]: cfg
+      };
     };
+    return make(void 0);
   };
   factory.infinite = function(params, crawlOptions = {}) {
     const queryKey = parentKey !== void 0 ? buildChildKey(parentKey, ownSegments, params, crawlOptions, true) : resolveKey(infiniteNamespace, params, crawlOptions);
-    if (infiniteCrawlingFn) {
+    const make = (deps) => {
+      if (infiniteCrawlingFn) {
+        return {
+          ...standardOptions,
+          queryKey,
+          queryFn: (ctx) => infiniteCrawlingFn(params, crawlOptions, deps, ctx),
+          getNextPageParam: getEnvelopeNextPageParam,
+          initialPageParam,
+          select: (data) => ({
+            ...data,
+            pages: data.pages.map(
+              (e) => select ? select(e.data, deps) : e.data
+            )
+          }),
+          ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
+          inject: (injected) => make(injected),
+          [FACTORY_CONFIG]: cfg
+        };
+      }
+      const boundQueryFn = rawQueryFn ? (ctx) => invokeQueryFn(rawQueryFn, params, ctx, deps) : void 0;
+      const infiniteSelect = select ? (data) => ({
+        ...data,
+        pages: data.pages.map((p) => select(p, deps))
+      }) : void 0;
+      const infiniteGetNextPageParam = getNextPageParam && shouldFetchNextPage ? wrapGetNextPageParam(
+        getNextPageParam,
+        shouldFetchNextPage,
+        crawlOptions,
+        select,
+        deps
+      ) : getNextPageParam != null ? getNextPageParam : noNextPage;
       return {
         ...standardOptions,
         queryKey,
-        queryFn: (ctx) => infiniteCrawlingFn(params, crawlOptions, ctx),
-        getNextPageParam: getEnvelopeNextPageParam,
-        initialPageParam,
-        select: envelopeSelect,
+        ...boundQueryFn !== void 0 && { queryFn: boundQueryFn },
+        ...infiniteSelect !== void 0 && { select: infiniteSelect },
+        getNextPageParam: infiniteGetNextPageParam,
         ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
+        ...initialPageParam !== void 0 && { initialPageParam },
+        inject: (injected) => make(injected),
         [FACTORY_CONFIG]: cfg
       };
-    }
-    const boundQueryFn = rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
-    const infiniteGetNextPageParam = getNextPageParam && shouldFetchNextPage ? wrapGetNextPageParam(
-      getNextPageParam,
-      shouldFetchNextPage,
-      crawlOptions,
-      select
-    ) : getNextPageParam != null ? getNextPageParam : noNextPage;
-    return {
-      ...standardOptions,
-      queryKey,
-      ...boundQueryFn !== void 0 && { queryFn: boundQueryFn },
-      ...infiniteSelect !== void 0 && { select: infiniteSelect },
-      getNextPageParam: infiniteGetNextPageParam,
-      ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
-      ...initialPageParam !== void 0 && { initialPageParam },
-      [FACTORY_CONFIG]: cfg
     };
+    return make(void 0);
   };
   return factory;
 }
@@ -265,7 +307,7 @@ function queryFactory(configOrParent, childConfig) {
     } else if (childConfig.select && parentCfg.select) {
       const p = parentCfg.select;
       const c = childConfig.select;
-      resolvedSelect = (data) => c(p(data));
+      resolvedSelect = (data, deps) => c(p(data, deps), deps);
     } else {
       resolvedSelect = (_a = childConfig.select) != null ? _a : parentCfg.select;
     }

package/dist/index.mjs

@@ -5,6 +5,9 @@ var noNextPage = () => void 0;
 function isAsyncIterable(value) {
   return value != null && typeof value[Symbol.asyncIterator] === "function";
 }
+function invokeQueryFn(queryFn, params, ctx, deps) {
+  return deps === void 0 ? queryFn(params, ctx) : queryFn(params, ctx, deps);
+}
 function resolveKey(namespace, params, crawlOptions) {
   const withParams = params === void 0 ? namespace : [...namespace, params];
   if (!crawlOptions) return withParams;
@@ -29,22 +32,22 @@ function buildChildKey(parentKey, ownSegments, params, crawlOptions, infinite) {
   const withInfinite = infinite ? [...withOwn, "infinite"] : withOwn;
   return defined ? [...withInfinite, defined] : withInfinite;
 }
-function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, select) {
+function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, select, deps) {
   return (lastPage, allPages, lastPageParam, allPageParams) => {
-    const combined = select ? select(lastPage) : lastPage;
+    const combined = select ? select(lastPage, deps) : lastPage;
     if (!shouldFetchNextPage(combined, crawlOptions)) return void 0;
     return getNextPageParam(lastPage, allPages, lastPageParam, allPageParams);
   };
 }
 function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shouldFetchNextPage, reduce) {
-  return async (params, crawlOptions, context) => {
+  return async (params, crawlOptions, deps, context) => {
     var _a, _b, _c;
     if ((_a = context.signal) == null ? void 0 : _a.aborted) {
       if (reduce) throw new DOMException("Aborted", "AbortError");
       return [];
     }
     const ctx = { ...context, pageParam: initialPageParam };
-    const initialResult = queryFn(params, ctx);
+    const initialResult = invokeQueryFn(queryFn, params, ctx, deps);
     if (isAsyncIterable(initialResult)) {
       const pages2 = [];
       let acc2 = void 0;
@@ -76,7 +79,12 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
       if (nextParam == null) break;
       currentParam = nextParam;
       ctx.pageParam = currentParam;
-      page = await queryFn(params, ctx);
+      page = await invokeQueryFn(
+        queryFn,
+        params,
+        ctx,
+        deps
+      );
     }
     if (reduce) {
       if (acc === void 0) throw new DOMException("Aborted", "AbortError");
@@ -85,13 +93,28 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
     return pages;
   };
 }
+function buildAutoConsumeQueryFn(queryFn, reduce) {
+  return async (params, deps, context) => {
+    var _a;
+    const result = await invokeQueryFn(queryFn, params, context, deps);
+    if (!isAsyncIterable(result)) return result;
+    const pages = [];
+    let acc = void 0;
+    for await (const page of result) {
+      if ((_a = context.signal) == null ? void 0 : _a.aborted) break;
+      pages.push(page);
+      if (reduce) acc = reduce(acc, page);
+    }
+    return reduce ? acc !== void 0 ? acc : pages : pages;
+  };
+}
 function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNextPage, reduce) {
-  return async (params, crawlOptions, context) => {
+  return async (params, crawlOptions, deps, context) => {
     var _a, _b, _c;
     if ((_a = context.signal) == null ? void 0 : _a.aborted)
       throw new DOMException("Aborted", "AbortError");
     const ctx = { ...context, pageParam: context.pageParam };
-    const initialResult = queryFn(params, ctx);
+    const initialResult = invokeQueryFn(queryFn, params, ctx, deps);
     if (isAsyncIterable(initialResult)) {
       const pages2 = [];
       const startParam = context.pageParam;
@@ -128,7 +151,12 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
       if (!shouldFetchNextPage(acc, crawlOptions)) break;
       currentParam = nextParam;
       ctx.pageParam = currentParam;
-      page = await queryFn(params, ctx);
+      page = await invokeQueryFn(
+        queryFn,
+        params,
+        ctx,
+        deps
+      );
     }
     if (acc === void 0) throw new DOMException("Aborted", "AbortError");
     return { data: acc, nextPageParam: nextBatchParam };
@@ -158,62 +186,76 @@ function buildFactory(cfg) {
     shouldFetchNextPage,
     reduce
   ) : void 0;
+  const autoConsumeFn = !hasCrawling && rawQueryFn !== void 0 ? buildAutoConsumeQueryFn(rawQueryFn, reduce) : void 0;
   const infiniteCrawlingFn = hasInfiniteCrawling ? buildInfiniteCrawlingQueryFn(
     rawQueryFn,
     getNextPageParam,
     shouldFetchNextPage,
     reduce
   ) : void 0;
-  const envelopeSelect = infiniteCrawlingFn ? (data) => ({
-    ...data,
-    pages: data.pages.map((e) => select ? select(e.data) : e.data)
-  }) : void 0;
-  const infiniteSelect = !infiniteCrawlingFn && select ? (data) => ({
-    ...data,
-    pages: data.pages.map(select)
-  }) : void 0;
+  const bindSelect = (deps) => select === void 0 ? void 0 : deps === void 0 ? select : (data) => select(data, deps);
   const factory = function(params, crawlOptions = {}) {
     const queryKey = parentKey !== void 0 ? buildChildKey(parentKey, ownSegments, params, crawlOptions) : resolveKey(namespace, params, crawlOptions);
-    const resolvedQueryFn = crawlingFn ? (ctx) => crawlingFn(params, crawlOptions, ctx) : rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
-    return {
-      ...standardOptions,
-      queryKey,
-      ...resolvedQueryFn !== void 0 && { queryFn: resolvedQueryFn },
-      ...select !== void 0 && { select },
-      [FACTORY_CONFIG]: cfg
+    const make = (deps) => {
+      const resolvedQueryFn = crawlingFn ? (ctx) => crawlingFn(params, crawlOptions, deps, ctx) : autoConsumeFn ? (ctx) => autoConsumeFn(params, deps, ctx) : void 0;
+      const boundSelect = bindSelect(deps);
+      return {
+        ...standardOptions,
+        queryKey,
+        ...resolvedQueryFn !== void 0 && { queryFn: resolvedQueryFn },
+        ...boundSelect !== void 0 && { select: boundSelect },
+        inject: (injected) => make(injected),
+        [FACTORY_CONFIG]: cfg
+      };
     };
+    return make(void 0);
   };
   factory.infinite = function(params, crawlOptions = {}) {
     const queryKey = parentKey !== void 0 ? buildChildKey(parentKey, ownSegments, params, crawlOptions, true) : resolveKey(infiniteNamespace, params, crawlOptions);
-    if (infiniteCrawlingFn) {
+    const make = (deps) => {
+      if (infiniteCrawlingFn) {
+        return {
+          ...standardOptions,
+          queryKey,
+          queryFn: (ctx) => infiniteCrawlingFn(params, crawlOptions, deps, ctx),
+          getNextPageParam: getEnvelopeNextPageParam,
+          initialPageParam,
+          select: (data) => ({
+            ...data,
+            pages: data.pages.map(
+              (e) => select ? select(e.data, deps) : e.data
+            )
+          }),
+          ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
+          inject: (injected) => make(injected),
+          [FACTORY_CONFIG]: cfg
+        };
+      }
+      const boundQueryFn = rawQueryFn ? (ctx) => invokeQueryFn(rawQueryFn, params, ctx, deps) : void 0;
+      const infiniteSelect = select ? (data) => ({
+        ...data,
+        pages: data.pages.map((p) => select(p, deps))
+      }) : void 0;
+      const infiniteGetNextPageParam = getNextPageParam && shouldFetchNextPage ? wrapGetNextPageParam(
+        getNextPageParam,
+        shouldFetchNextPage,
+        crawlOptions,
+        select,
+        deps
+      ) : getNextPageParam != null ? getNextPageParam : noNextPage;
       return {
         ...standardOptions,
         queryKey,
-        queryFn: (ctx) => infiniteCrawlingFn(params, crawlOptions, ctx),
-        getNextPageParam: getEnvelopeNextPageParam,
-        initialPageParam,
-        select: envelopeSelect,
+        ...boundQueryFn !== void 0 && { queryFn: boundQueryFn },
+        ...infiniteSelect !== void 0 && { select: infiniteSelect },
+        getNextPageParam: infiniteGetNextPageParam,
         ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
+        ...initialPageParam !== void 0 && { initialPageParam },
+        inject: (injected) => make(injected),
         [FACTORY_CONFIG]: cfg
       };
-    }
-    const boundQueryFn = rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
-    const infiniteGetNextPageParam = getNextPageParam && shouldFetchNextPage ? wrapGetNextPageParam(
-      getNextPageParam,
-      shouldFetchNextPage,
-      crawlOptions,
-      select
-    ) : getNextPageParam != null ? getNextPageParam : noNextPage;
-    return {
-      ...standardOptions,
-      queryKey,
-      ...boundQueryFn !== void 0 && { queryFn: boundQueryFn },
-      ...infiniteSelect !== void 0 && { select: infiniteSelect },
-      getNextPageParam: infiniteGetNextPageParam,
-      ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
-      ...initialPageParam !== void 0 && { initialPageParam },
-      [FACTORY_CONFIG]: cfg
     };
+    return make(void 0);
   };
   return factory;
 }
@@ -239,7 +281,7 @@ function queryFactory(configOrParent, childConfig) {
     } else if (childConfig.select && parentCfg.select) {
       const p = parentCfg.select;
       const c = childConfig.select;
-      resolvedSelect = (data) => c(p(data));
+      resolvedSelect = (data, deps) => c(p(data, deps), deps);
     } else {
       resolvedSelect = (_a = childConfig.select) != null ? _a : parentCfg.select;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robohall/react-query-factory",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "A factory abstraction for TanStack Query (React Query) with composable keys, crawling support, and automatic infinite query generation",
   "author": "Robert Hall",
   "license": "MIT",