@robohall/react-query-factory 1.1.0 → 1.2.0

package/README.md

@@ -54,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` and `shouldFetchNextPage` to activate crawling — those two are the only required pieces. `initialPageParam` types `ctx.pageParam` in your `queryFn` (without it, `ctx.pageParam` is `never`). `reduce` folds crawled pages into a single value; without it the result is the last fetched page. **`shouldFetchNextPage`** is called after each page — return `true` to keep fetching, `false` to stop. Use `() => true` to walk every page:
+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';
@@ -79,7 +79,7 @@ const describeInstances = queryFactory({
 
 function InstanceList() {
   // one useQuery call; data is Instance[], not DescribeInstancesResponse[]
-  const { data } = useQuery(describeInstances({ MaxResults: 1000 }));
+  const { data } = useQuery(describeInstances({ MaxResults: 20 }));
 }
 ```
 
@@ -94,11 +94,11 @@ const describeInstances = queryFactory({
 });
 
 // fetch all pages
-const { data: all } = useQuery(describeInstances({ MaxResults: 1000 }));
+const { data: all } = useQuery(describeInstances({ MaxResults: 20 }));
 
-// stop after accumulating at least 50 instances
+// stop after accumulating at least 50 instances (≥ 3 API calls)
 const { data: partial } = useQuery(
-  describeInstances({ MaxResults: 1000 }, { minResults: 50 })
+  describeInstances({ MaxResults: 20 }, { minResults: 50 })
 );
 ```
 
@@ -117,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.
@@ -135,10 +135,10 @@ const findInstance = queryFactory(describeInstances, {
     !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' })
 );
 ```
 
@@ -160,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 }]`
 
 ---
 
@@ -188,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`
 
@@ -200,10 +200,10 @@ All fields except `reduce` and `shouldFetchNextPage` are the standard TanStack Q
 | `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. Required (with `shouldFetchNextPage`) to activate crawling. Required (with `initialPageParam`) for `.infinite()`. |
-| `initialPageParam` | `TPageParam` | Exact TanStack API. Drives `TPageParam` inference — without it `ctx.pageParam` is typed `never`. Required for `.infinite()` to work at runtime. |
+| `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()`. |
 | `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 the last fetched page (`TSelected = TData`). |
+| `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

@@ -62,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>;
@@ -93,7 +98,7 @@ type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unkno
  */
 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

package/dist/index.d.ts

@@ -62,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>;
@@ -93,7 +98,7 @@ type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unkno
  */
 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

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);
   };
@@ -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);
   };
@@ -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.1.0",
+  "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",