@robohall/react-query-factory 1.0.5 → 1.2.0

package/README.md

@@ -38,7 +38,6 @@ const describeInstances = queryFactory({
   queryKey: ['ec2:DescribeInstances'],
   queryFn: (params: DescribeInstancesCommandInput, ctx) =>
     ec2.send(new DescribeInstancesCommand(params), { abortSignal: ctx.signal }),
-  staleTime: 30_000,
 });
 
 function InstanceList() {
@@ -46,7 +45,6 @@ function InstanceList() {
     describeInstances({ Filters: [{ Name: 'instance-state-name', Values: ['running'] }] })
   );
   // query key:  ['ec2:DescribeInstances', { Filters: [...] }]
-  // staleTime:  30 000 ms, no repetition required
 }
 ```
 
@@ -56,9 +54,9 @@ function InstanceList() {
 
 ## Crawling
 
-`DescribeInstances` is paginated. If you have more than 1000 instances, one call won't get them all. The standard approach — chaining `fetchNextPage` calls, accumulating results, checking `NextToken` — is correct but tedious to repeat everywhere.
+`DescribeInstances` is paginated. If you have more than 20 instances, one call won't get them all. The standard approach — chaining `fetchNextPage` calls, accumulating results, checking `NextToken` — is correct but tedious to repeat everywhere.
 
-Add `getNextPageParam`, `initialPageParam`, and `reduce` to your factory config, and the generated `queryFn` will walk every page automatically, reducing them into a single flat array:
+Add `getNextPageParam` and `shouldFetchNextPage` to activate crawling — those two are the only required pieces. `initialPageParam` types `ctx.pageParam` in your `queryFn` (without it and without a `getNextPageParam` that provides inference, `ctx.pageParam` is `never`). `reduce` folds crawled pages into a single value; without it the result is an array of all fetched raw pages (`TData[]`). **`shouldFetchNextPage`** is called after each page — return `true` to keep fetching, `false` to stop. Use `() => true` to walk every page:
 
 ```typescript
 import type { Instance, DescribeInstancesCommandInput } from '@aws-sdk/client-ec2';
@@ -72,32 +70,35 @@ const describeInstances = queryFactory({
     ),
   getNextPageParam: response => response.NextToken,
   initialPageParam: undefined as string | undefined,
+  shouldFetchNextPage: () => true,
   reduce: (acc, page): Instance[] => [
     ...(acc ?? []),
     ...(page.Reservations?.flatMap(r => r.Instances ?? []) ?? []),
   ],
-  staleTime: 30_000,
 });
 
 function InstanceList() {
   // one useQuery call; data is Instance[], not DescribeInstancesResponse[]
-  const { data } = useQuery(describeInstances({ MaxResults: 1000 }));
+  const { data } = useQuery(describeInstances({ MaxResults: 20 }));
 }
 ```
 
-**`shouldFetchNextPage`** lets a call site stop the crawl early based on what has been accumulated so far. The arguments are the current reduced value and a `crawlOptions` object passed at call time. When `reduce` is present, `combined` is typed as `TSelected` (never undefined) because `reduce` always runs before this callback:
+`shouldFetchNextPage` also accepts a `crawlOptions` object passed at call time, letting each call site control the crawl independently:
 
 ```typescript
 const describeInstances = queryFactory({
   // ...
   reduce: (acc, page): Instance[] => [...(acc ?? []), ...page.Reservations.flatMap(r => r.Instances)],
   shouldFetchNextPage: (instances, opts: { minResults?: number }) =>
-    opts.minResults != null && instances.length < opts.minResults,
+    opts.minResults == null || instances.length < opts.minResults,
 });
 
-// stop after accumulating at least 50 instances
-const { data } = useQuery(
-  describeInstances({ MaxResults: 1000 }, { minResults: 50 })
+// fetch all pages
+const { data: all } = useQuery(describeInstances({ MaxResults: 20 }));
+
+// stop after accumulating at least 50 instances (≥ 3 API calls)
+const { data: partial } = useQuery(
+  describeInstances({ MaxResults: 20 }, { minResults: 50 })
 );
 ```
 
@@ -116,9 +117,9 @@ const runningInstances = queryFactory(describeInstances, {
   select: instances => instances.filter(i => i.State?.Name === 'running'),
 });
 
-// query key:  ['ec2:DescribeInstances', { MaxResults: 1000 }]  (same cache entry as parent)
+// query key:  ['ec2:DescribeInstances', { MaxResults: 20 }]  (same cache entry as parent)
 // data:       Instance[] filtered to State.Name === 'running'
-const { data } = useQuery(runningInstances({ MaxResults: 1000 }));
+const { data } = useQuery(runningInstances({ MaxResults: 20 }));
 ```
 
 Parent and child `select` functions compose automatically — if the parent already has a `select`, the child's `select` receives the parent's output, not the raw API response.
@@ -131,13 +132,13 @@ const findInstance = queryFactory(describeInstances, {
   // queryFn, getNextPageParam, initialPageParam, and reduce are all inherited
   shouldFetchNextPage: (instances, opts: { instanceId?: string }) =>
     opts.instanceId != null &&
-    !instances?.some(i => i.InstanceId === opts.instanceId),
+    !instances.some(i => i.InstanceId === opts.instanceId),
 });
 
-// query key: ['ec2:DescribeInstances', 'find', { MaxResults: 100 }, { instanceId: 'i-0abc123' }]
+// query key: ['ec2:DescribeInstances', 'find', { MaxResults: 20 }, { instanceId: 'i-0abc123def456' }]
 // crawls pages until the target instance appears, then stops
 const { data } = useQuery(
-  findInstance({ MaxResults: 100 }, { instanceId: 'i-0abc123def456' })
+  findInstance({ MaxResults: 20 }, { instanceId: 'i-0abc123def456' })
 );
 ```
 
@@ -159,15 +160,15 @@ Every factory exposes a `.infinite()` method that returns `useInfiniteQuery`-com
 ```typescript
 const { data, fetchNextPage, hasNextPage } = useInfiniteQuery(
   // load 50 instances per UI page, each backed by up to 5 DescribeInstances calls
-  describeInstances.infinite({ MaxResults: 10 }, { minResults: 50 })
+  describeInstances.infinite({ MaxResults: 20 }, { minResults: 50 })
 );
 
 // data.pages is Instance[][], one array per virtual page
 ```
 
 The `.infinite()` key includes an `'infinite'` segment to keep it separate from the regular `useQuery` cache entry:
-- `describeInstances({ MaxResults: 10 })` → `['ec2:DescribeInstances', { MaxResults: 10 }]`
-- `describeInstances.infinite({ MaxResults: 10 })` → `['ec2:DescribeInstances', 'infinite', { MaxResults: 10 }]`
+- `describeInstances({ MaxResults: 20 })` → `['ec2:DescribeInstances', { MaxResults: 20 }]`
+- `describeInstances.infinite({ MaxResults: 20 })` → `['ec2:DescribeInstances', 'infinite', { MaxResults: 20 }]`
 
 ---
 
@@ -187,7 +188,7 @@ queryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions>(
 
 Creates a child factory. Two overloads:
 - **With a new `queryFn`** — inherits key namespace and standard options; crawling config must be re-declared if needed.
-- **Without a `queryFn`** — inherits everything; accepts only `queryKey`, `select`, and standard options. `select` is composed with the parent's.
+- **Without a `queryFn`** — inherits everything; accepts `queryKey`, `select`, standard options, and any crawling fields (`shouldFetchNextPage`, `reduce`, `getNextPageParam`, `getPreviousPageParam`, `initialPageParam`) to override the parent's. `select` is composed with the parent's.
 
 ### `QueryFactoryConfig`
 
@@ -198,11 +199,11 @@ All fields except `reduce` and `shouldFetchNextPage` are the standard TanStack Q
 | `queryKey` | `QueryKey` | Namespace segments. Params are appended at call time. |
 | `queryFn` | `(params: TParams, ctx: QueryFunctionContext) => TData \| Promise<TData>` | Same as TanStack, with an extra leading `params` argument. |
 | `select` | `(data: TData) => TSelected` | Exact TanStack API. Composed automatically on child factories. |
-| `getNextPageParam` | `GetNextPageParamFunction<TPageParam, TData>` | Exact TanStack API. Providing this together with `initialPageParam` and `reduce` activates crawling. |
-| `initialPageParam` | `TPageParam` | Exact TanStack API. Required alongside `getNextPageParam` to enable crawling. |
+| `getNextPageParam` | `GetNextPageParamFunction<TPageParam, TData>` | Exact TanStack API. Required (with `shouldFetchNextPage`) to activate crawling. Required (with `initialPageParam`) for `.infinite()`. |
+| `initialPageParam` | `TPageParam` | Exact TanStack API. Drives `TPageParam` inference — without it and without a `getNextPageParam` that provides inference, `ctx.pageParam` is typed `never`. Required for `.infinite()` to work at runtime. |
 | `getPreviousPageParam` | `GetPreviousPageParamFunction<TPageParam, TData>` | Exact TanStack API. Passed through on `.infinite()`. |
-| `reduce` | `(acc: TSelected \| undefined, page: TData) => TSelected` | Library addition. Folds crawled pages into a single value; required for crawling and `.infinite()` crawling. |
-| `shouldFetchNextPage` | `(combined: TSelected, crawlOptions: TCrawlOptions) => boolean` when `reduce` is present; `(combined: TSelected \| undefined, ...) => boolean` otherwise | Library addition. Return `false` to stop the crawl early based on accumulated results. |
+| `shouldFetchNextPage` | `(combined: TSelected \| undefined, crawlOptions: TCrawlOptions) => boolean` | Library addition. **Required (with `getNextPageParam`) 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 | | All options accepted by TanStack's `useQuery` / `useInfiniteQuery` except `queryKey`, `queryFn`, and `select` (which the factory owns). Includes `staleTime`, `gcTime`, `retry`, `retryOnMount`, `enabled`, `refetchOnWindowFocus`, `refetchOnReconnect`, `refetchOnMount`, `refetchInterval`, `refetchIntervalInBackground`, `networkMode`, `notifyOnChangeProps`, `throwOnError`, `structuralSharing`, `initialData`, `initialDataUpdatedAt`, `placeholderData`, `queryKeyHashFn`, `persister`, `meta`, `maxPages`, `experimental_prefetchInRender`. Function-form callbacks (e.g. `enabled: (query) => boolean`) are supported wherever TanStack accepts them. |
 
 ### `QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions>`

package/dist/index.d.mts

@@ -31,27 +31,21 @@ type QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelect
         unknown
     ] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
     select?: (data: TData) => TSelected;
-} & ({
     /** TanStack v5 generic order: GetNextPageParamFunction<TPageParam, TData> */
-    getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
-    /** Required alongside getNextPageParam — drives TPageParam inference so
-     *  ctx.pageParam in queryFn is typed as TPageParam, not unknown. */
-    initialPageParam: TPageParam;
+    getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
+    /** Drives TPageParam inference so ctx.pageParam in queryFn is typed as TPageParam.
+     *  When omitted TPageParam stays unknown and ctx.pageParam is typed as never.
+     *  Required for .infinite() to work correctly at runtime. */
+    initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     /** Reduces crawled pages incrementally into the final query result.
      *  Called once per page; accumulator is undefined on the first call.
-     *  When set, enables crawling on both the regular and .infinite variants. */
+     *  When omitted, the crawl result is the last fetched page (TSelected = TData). */
     reduce?: (accumulator: TSelected | undefined, page: TData) => TSelected;
     /** Called after each page to decide whether to keep crawling.
-     *  `combined` may be undefined when reduce is absent. */
+     *  Required (along with getNextPageParam) to activate crawling. */
     shouldFetchNextPage?: (combined: TSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
-} | {
-    getNextPageParam?: never;
-    initialPageParam?: never;
-    getPreviousPageParam?: never;
-    shouldFetchNextPage?: never;
-    reduce?: never;
-});
+};
 /**
  * What `factory(params)` returns — pass directly to `useQuery()`.
  *
@@ -68,15 +62,20 @@ type ResolvedQueryOptions<TData = unknown, TError = Error, TSelected = TData> =
 /**
  * What `factory.infinite(params)` returns — pass directly to `useInfiniteQuery()`.
  *
- * The `select` field expects `InfiniteData<TData, TPageParam>`, which is a structural
- * guard making this type incompatible with `useQuery`.
+ * The `select` field input type (`InfiniteData<TData, TPageParam>`) is a structural
+ * guard making this type incompatible with `useQuery`, whose select expects `(data: TData)`.
+ *
+ * `TResult` is the concrete type that `useInfiniteQuery` will use as its `TData` — i.e.
+ * what `select` returns (or `InfiniteData<TData, TPageParam>` when no select is set).
+ * Carrying it explicitly avoids returning `any`, which would poison TResult inference
+ * in TypeScript 6 when callers spread this type and add their own `select`.
  */
-type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown> = Omit<StandardQueryOptions<TError, any>, 'persister'> & {
+type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown, TResult = InfiniteData<TData, TPageParam>> = Omit<StandardQueryOptions<TError, any>, 'persister'> & {
     queryKey: QueryKey;
     queryFn?: (context: QueryFunctionContext<QueryKey, TPageParam>) => TData | Promise<TData>;
-    /** Structural guard: the InfiniteData parameter type makes this incompatible with useQuery,
+    /** Structural guard: the InfiniteData input type makes this incompatible with useQuery,
      *  whose select expects (data: TData) rather than (data: InfiniteData<TData, TPageParam>). */
-    select?: (data: InfiniteData<TData, TPageParam>) => any;
+    select?: (data: InfiniteData<TData, TPageParam>) => TResult;
     /** Required so this type satisfies useInfiniteQuery, which requires getNextPageParam. */
     getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
@@ -97,9 +96,9 @@ type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unkno
  * namespace key, which is useful for broad cache invalidation:
  * `queryClient.invalidateQueries(factory())`
  */
-interface QueryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> {
+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>;
+    infinite(params?: TParams, crawlOptions?: TCrawlOptions): ResolvedInfiniteOptions<TData, TError, TPageParam, InfiniteData<TSelected, TPageParam>>;
 }
 /**
  * Creates a standalone query factory with pagination and reduce. When `reduce` is
@@ -112,12 +111,12 @@ declare function queryFactory<TParams = void, TData = unknown, TError = Error, T
         unknown
     ] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
     select?: (data: TData) => TSelected;
-    getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
-    initialPageParam: TPageParam;
+    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>;
+}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true>;
 /**
  * Creates a standalone query factory from a config object.
  *
@@ -128,7 +127,7 @@ 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>;
+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>;
 /**
  * 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
@@ -136,22 +135,10 @@ declare function queryFactory<TParams = void, TData = unknown, TError = Error, T
  *
  * 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>, config: Omit<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions>, 'queryKey' | 'getNextPageParam' | 'getPreviousPageParam' | 'initialPageParam' | 'shouldFetchNextPage' | 'reduce'> & {
+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'> & {
     queryKey?: QueryKey;
     queryFn: NonNullable<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam>['queryFn']>;
-} & ({
-    getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
-    initialPageParam: TPageParam;
-    getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
-    shouldFetchNextPage?: (combined: TChildSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
-    reduce?: (accumulator: TChildSelected | undefined, page: TData) => TChildSelected;
-} | {
-    getNextPageParam?: never;
-    initialPageParam?: never;
-    getPreviousPageParam?: never;
-    shouldFetchNextPage?: never;
-    reduce?: never;
-})): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions>;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean>;
 /**
  * Creates a child factory that reuses the parent's `queryFn` and pagination
  * config. Useful for adding a `select` transform, narrowing params, or
@@ -159,7 +146,7 @@ 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>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, TParentCrawlOptions>, 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>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, TParentCrawlOptions, TParentHasReduce>, config: StandardQueryOptions<TError, TData> & {
     queryKey?: QueryKey;
     queryFn?: never;
     select?: (data: TParentSelected) => TChildSelected;
@@ -167,7 +154,7 @@ declare function queryFactory<TChildParams extends TParentParams, TData = unknow
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce?: (accumulator: TChildSelected | undefined, page: TData) => TChildSelected;
-    shouldFetchNextPage?: (combined: TChildSelected | undefined, crawlOptions: TChildCrawlOptions) => boolean;
-}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions>;
+    shouldFetchNextPage?: (combined: TParentHasReduce extends true ? TChildSelected : TChildSelected | undefined, crawlOptions: TChildCrawlOptions) => boolean;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions, TParentHasReduce>;
 
 export { type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };

package/dist/index.d.ts

@@ -31,27 +31,21 @@ type QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelect
         unknown
     ] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
     select?: (data: TData) => TSelected;
-} & ({
     /** TanStack v5 generic order: GetNextPageParamFunction<TPageParam, TData> */
-    getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
-    /** Required alongside getNextPageParam — drives TPageParam inference so
-     *  ctx.pageParam in queryFn is typed as TPageParam, not unknown. */
-    initialPageParam: TPageParam;
+    getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
+    /** Drives TPageParam inference so ctx.pageParam in queryFn is typed as TPageParam.
+     *  When omitted TPageParam stays unknown and ctx.pageParam is typed as never.
+     *  Required for .infinite() to work correctly at runtime. */
+    initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     /** Reduces crawled pages incrementally into the final query result.
      *  Called once per page; accumulator is undefined on the first call.
-     *  When set, enables crawling on both the regular and .infinite variants. */
+     *  When omitted, the crawl result is the last fetched page (TSelected = TData). */
     reduce?: (accumulator: TSelected | undefined, page: TData) => TSelected;
     /** Called after each page to decide whether to keep crawling.
-     *  `combined` may be undefined when reduce is absent. */
+     *  Required (along with getNextPageParam) to activate crawling. */
     shouldFetchNextPage?: (combined: TSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
-} | {
-    getNextPageParam?: never;
-    initialPageParam?: never;
-    getPreviousPageParam?: never;
-    shouldFetchNextPage?: never;
-    reduce?: never;
-});
+};
 /**
  * What `factory(params)` returns — pass directly to `useQuery()`.
  *
@@ -68,15 +62,20 @@ type ResolvedQueryOptions<TData = unknown, TError = Error, TSelected = TData> =
 /**
  * What `factory.infinite(params)` returns — pass directly to `useInfiniteQuery()`.
  *
- * The `select` field expects `InfiniteData<TData, TPageParam>`, which is a structural
- * guard making this type incompatible with `useQuery`.
+ * The `select` field input type (`InfiniteData<TData, TPageParam>`) is a structural
+ * guard making this type incompatible with `useQuery`, whose select expects `(data: TData)`.
+ *
+ * `TResult` is the concrete type that `useInfiniteQuery` will use as its `TData` — i.e.
+ * what `select` returns (or `InfiniteData<TData, TPageParam>` when no select is set).
+ * Carrying it explicitly avoids returning `any`, which would poison TResult inference
+ * in TypeScript 6 when callers spread this type and add their own `select`.
  */
-type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown> = Omit<StandardQueryOptions<TError, any>, 'persister'> & {
+type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown, TResult = InfiniteData<TData, TPageParam>> = Omit<StandardQueryOptions<TError, any>, 'persister'> & {
     queryKey: QueryKey;
     queryFn?: (context: QueryFunctionContext<QueryKey, TPageParam>) => TData | Promise<TData>;
-    /** Structural guard: the InfiniteData parameter type makes this incompatible with useQuery,
+    /** Structural guard: the InfiniteData input type makes this incompatible with useQuery,
      *  whose select expects (data: TData) rather than (data: InfiniteData<TData, TPageParam>). */
-    select?: (data: InfiniteData<TData, TPageParam>) => any;
+    select?: (data: InfiniteData<TData, TPageParam>) => TResult;
     /** Required so this type satisfies useInfiniteQuery, which requires getNextPageParam. */
     getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
@@ -97,9 +96,9 @@ type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unkno
  * namespace key, which is useful for broad cache invalidation:
  * `queryClient.invalidateQueries(factory())`
  */
-interface QueryFactory<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> {
+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>;
+    infinite(params?: TParams, crawlOptions?: TCrawlOptions): ResolvedInfiniteOptions<TData, TError, TPageParam, InfiniteData<TSelected, TPageParam>>;
 }
 /**
  * Creates a standalone query factory with pagination and reduce. When `reduce` is
@@ -112,12 +111,12 @@ declare function queryFactory<TParams = void, TData = unknown, TError = Error, T
         unknown
     ] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
     select?: (data: TData) => TSelected;
-    getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
-    initialPageParam: TPageParam;
+    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>;
+}): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, true>;
 /**
  * Creates a standalone query factory from a config object.
  *
@@ -128,7 +127,7 @@ 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>;
+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>;
 /**
  * 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
@@ -136,22 +135,10 @@ declare function queryFactory<TParams = void, TData = unknown, TError = Error, T
  *
  * 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>, config: Omit<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions>, 'queryKey' | 'getNextPageParam' | 'getPreviousPageParam' | 'initialPageParam' | 'shouldFetchNextPage' | 'reduce'> & {
+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'> & {
     queryKey?: QueryKey;
     queryFn: NonNullable<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam>['queryFn']>;
-} & ({
-    getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
-    initialPageParam: TPageParam;
-    getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
-    shouldFetchNextPage?: (combined: TChildSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
-    reduce?: (accumulator: TChildSelected | undefined, page: TData) => TChildSelected;
-} | {
-    getNextPageParam?: never;
-    initialPageParam?: never;
-    getPreviousPageParam?: never;
-    shouldFetchNextPage?: never;
-    reduce?: never;
-})): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions>;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TCrawlOptions, boolean>;
 /**
  * Creates a child factory that reuses the parent's `queryFn` and pagination
  * config. Useful for adding a `select` transform, narrowing params, or
@@ -159,7 +146,7 @@ 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>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, TParentCrawlOptions>, 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>(parent: QueryFactory<TParentParams, TData, any, TParentSelected, TPageParam, TParentCrawlOptions, TParentHasReduce>, config: StandardQueryOptions<TError, TData> & {
     queryKey?: QueryKey;
     queryFn?: never;
     select?: (data: TParentSelected) => TChildSelected;
@@ -167,7 +154,7 @@ declare function queryFactory<TChildParams extends TParentParams, TData = unknow
     initialPageParam?: TPageParam;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
     reduce?: (accumulator: TChildSelected | undefined, page: TData) => TChildSelected;
-    shouldFetchNextPage?: (combined: TChildSelected | undefined, crawlOptions: TChildCrawlOptions) => boolean;
-}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions>;
+    shouldFetchNextPage?: (combined: TParentHasReduce extends true ? TChildSelected : TChildSelected | undefined, crawlOptions: TChildCrawlOptions) => boolean;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions, TParentHasReduce>;
 
 export { type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };

package/dist/index.js

@@ -40,9 +40,10 @@ function resolveKey(namespace, params, crawlOptions) {
   }
   return defined ? [...withParams, defined] : withParams;
 }
-function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions) {
+function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, select) {
   return (lastPage, allPages, lastPageParam, allPageParams) => {
-    if (!shouldFetchNextPage(lastPage, crawlOptions))
+    const combined = select ? select(lastPage) : lastPage;
+    if (!shouldFetchNextPage(combined, crawlOptions))
       return void 0;
     return getNextPageParam(lastPage, allPages, lastPageParam, allPageParams);
   };
@@ -63,7 +64,7 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
       pageParams.push(currentParam);
       if (reduce) acc = reduce(acc, page);
       if ((_b = context.signal) == null ? void 0 : _b.aborted) break;
-      if (shouldFetchNextPage && !shouldFetchNextPage(acc, crawlOptions)) break;
+      if (!shouldFetchNextPage(acc, crawlOptions)) break;
       const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
       if (nextParam == null) break;
       currentParam = nextParam;
@@ -95,7 +96,7 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
       const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
       nextBatchParam = nextParam != null ? nextParam : null;
       if (nextParam == null) break;
-      if (shouldFetchNextPage && !shouldFetchNextPage(acc, crawlOptions)) break;
+      if (!shouldFetchNextPage(acc, crawlOptions)) break;
       currentParam = nextParam;
     }
     if (acc === void 0) throw new DOMException("Aborted", "AbortError");
@@ -114,7 +115,7 @@ function buildFactory(cfg) {
     reduce,
     standardOptions
   } = cfg;
-  const hasCrawling = rawQueryFn !== void 0 && getNextPageParam !== void 0;
+  const hasCrawling = rawQueryFn !== void 0 && getNextPageParam !== void 0 && shouldFetchNextPage !== void 0;
   const hasInfiniteCrawling = hasCrawling && reduce !== void 0;
   const crawlingFn = hasCrawling ? buildCrawlingQueryFn(
     rawQueryFn,
@@ -167,7 +168,8 @@ function buildFactory(cfg) {
     const infiniteGetNextPageParam = getNextPageParam && shouldFetchNextPage ? wrapGetNextPageParam(
       getNextPageParam,
       shouldFetchNextPage,
-      crawlOptions
+      crawlOptions,
+      select
     ) : getNextPageParam != null ? getNextPageParam : noNextPage;
     return {
       ...standardOptions,

package/dist/index.mjs

@@ -14,9 +14,10 @@ function resolveKey(namespace, params, crawlOptions) {
   }
   return defined ? [...withParams, defined] : withParams;
 }
-function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions) {
+function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, select) {
   return (lastPage, allPages, lastPageParam, allPageParams) => {
-    if (!shouldFetchNextPage(lastPage, crawlOptions))
+    const combined = select ? select(lastPage) : lastPage;
+    if (!shouldFetchNextPage(combined, crawlOptions))
       return void 0;
     return getNextPageParam(lastPage, allPages, lastPageParam, allPageParams);
   };
@@ -37,7 +38,7 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
       pageParams.push(currentParam);
       if (reduce) acc = reduce(acc, page);
       if ((_b = context.signal) == null ? void 0 : _b.aborted) break;
-      if (shouldFetchNextPage && !shouldFetchNextPage(acc, crawlOptions)) break;
+      if (!shouldFetchNextPage(acc, crawlOptions)) break;
       const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
       if (nextParam == null) break;
       currentParam = nextParam;
@@ -69,7 +70,7 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
       const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
       nextBatchParam = nextParam != null ? nextParam : null;
       if (nextParam == null) break;
-      if (shouldFetchNextPage && !shouldFetchNextPage(acc, crawlOptions)) break;
+      if (!shouldFetchNextPage(acc, crawlOptions)) break;
       currentParam = nextParam;
     }
     if (acc === void 0) throw new DOMException("Aborted", "AbortError");
@@ -88,7 +89,7 @@ function buildFactory(cfg) {
     reduce,
     standardOptions
   } = cfg;
-  const hasCrawling = rawQueryFn !== void 0 && getNextPageParam !== void 0;
+  const hasCrawling = rawQueryFn !== void 0 && getNextPageParam !== void 0 && shouldFetchNextPage !== void 0;
   const hasInfiniteCrawling = hasCrawling && reduce !== void 0;
   const crawlingFn = hasCrawling ? buildCrawlingQueryFn(
     rawQueryFn,
@@ -141,7 +142,8 @@ function buildFactory(cfg) {
     const infiniteGetNextPageParam = getNextPageParam && shouldFetchNextPage ? wrapGetNextPageParam(
       getNextPageParam,
       shouldFetchNextPage,
-      crawlOptions
+      crawlOptions,
+      select
     ) : getNextPageParam != null ? getNextPageParam : noNextPage;
     return {
       ...standardOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robohall/react-query-factory",
-  "version": "1.0.5",
+  "version": "1.2.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",