@robohall/react-query-factory 2.1.5 → 2.2.0

package/README.md

@@ -218,6 +218,23 @@ queryClient.invalidateQueries(describeInstances({ MaxResults: 20 }));
 
 ---
 
+## Which pattern?
+
+| Pattern                   | Use when                                                                                         |
+| ------------------------- | ------------------------------------------------------------------------------------------------ |
+| Basic                     | API returns a single, non-paginated response                                                     |
+| Async iterator            | `queryFn` returns an `AsyncIterable` (e.g. an AWS SDK v3 paginator) — no cursor wiring required  |
+| Crawl-then-render         | Paginated API; UI needs all data before it's useful (dropdowns, counts, totals)                  |
+| Render-while-crawling     | Paginated API; UI can show partial results as pages arrive                                       |
+| On-demand (`.infinite()`) | Paginated API; user clicks "load more" or navigates pages                                        |
+| Client-side search        | Paginated API; find a subset without server-side filtering — stop crawling when condition is met |
+
+**Async iterator** is a `queryFn` style, not a display pattern — combine it with any crawl pattern above when your SDK provides a paginator function.
+
+**Composition** and **Invalidation** apply alongside any pattern: use composition when multiple views share one cache entry, invalidation after a mutation changes server state.
+
+---
+
 ## Installation
 
 ```bash
@@ -247,11 +264,25 @@ const { data: partial } = useQuery(
 );
 ```
 
+### Error behavior
+
+If any page fetch throws, the error propagates immediately — there is no per-page retry or partial-result fallback. TanStack Query receives the error exactly as it would from a single-page `queryFn` and applies its normal `retry`, `throwOnError`, and error-state semantics.
+
+When TanStack retries, the crawl starts over from `initialPageParam`. There is no resume-from-page-N.
+
+The crawl also respects the abort signal between pages. When the signal fires (component unmounts, query superseded by a newer one), the loop exits after the current in-flight page completes. TanStack does not commit the partial result.
+
 ---
 
 ## Async iterator queryFns
 
-When `queryFn` returns an `AsyncIterable`, the library detects it automatically and drives the crawl with `for await...of` instead of the cursor loop. This means `getNextPageParam` and `initialPageParam` are not required — the iterator manages its own cursor. AWS SDK v3 paginator functions (`paginateDescribeInstances`, etc.) are a common source of async iterables:
+When `queryFn` returns an `AsyncIterable`, the library walks it with `for await...of` instead of calling `queryFn` repeatedly with successive `pageParam` values. The cursor lives inside the iterator rather than in `getNextPageParam` — that's the only meaningful difference from a cursor-based factory. `shouldFetchNextPage`, `reduce`, `crawlOptions`, and `.infinite()` all work identically.
+
+One caveat for `.infinite()`: `getNextPageParam` is still required, but its role shifts — instead of wiring each individual API page, it records where the next batch should start when the user loads more.
+
+Without `shouldFetchNextPage`, the library exhausts the iterator on every call — every page, every time.
+
+Any source of `AsyncIterable<TPage>` works:
 
 ```typescript
 import { paginateDescribeInstances } from '@aws-sdk/client-ec2';
@@ -273,9 +304,7 @@ const describeInstances = queryFactory({
 });
 ```
 
-`shouldFetchNextPage` still controls early stopping — the library calls `next()` on the iterator only when it returns `true`. Any source of `AsyncIterable<TPage>` works, not just AWS SDK paginators.
-
-For `.infinite()` mode, `getNextPageParam` is required to capture the next virtual page's starting cursor from the last yielded item. AWS SDK v3 paginators accept a `startingToken` to resume from a specific position — wire `ctx.pageParam` to it:
+For `.infinite()`, wire `ctx.pageParam` to the iterator's resume parameter so each batch starts from the right position:
 
 ```typescript
 const describeInstances = queryFactory({
@@ -388,6 +417,24 @@ The `.infinite()` key includes an `'infinite'` segment to keep it separate from
 
 ---
 
+## 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:
+
+```typescript
+const describeInstances = queryFactory({
+  queryKey: ['ec2:DescribeInstances'],
+  staleTime: 60_000, // re-crawl at most once per minute
+  // ...
+});
+```
+
+Child factories inherit `staleTime` and all other standard options from the parent, so setting it once on the root factory covers every derived view.
+
+When freshness requirements allow it, `refetchOnWindowFocus` and `refetchOnMount` can be set to `false` on the factory for the same reason — each is a potential full re-crawl.
+
+---
+
 ## Public API
 
 ### `queryFactory(config)`
@@ -440,6 +487,26 @@ Return type of `factory(params)`. Pass directly to `useQuery()`. Contains an `in
 
 Return type of `factory.infinite(params)`. Pass directly to `useInfiniteQuery()`. The `select` field is typed to `InfiniteData<TData, TPageParam>`, which prevents accidental use with `useQuery`.
 
+### `FactoryParams<F>`
+
+Extracts the params type from a factory — the first argument of a factory call. Useful for typing component props that accept factory params.
+
+```typescript
+import type { FactoryParams } from '@robohall/react-query-factory';
+
+type Params = FactoryParams<typeof describeInstances>; // → DescribeInstancesRequest
+```
+
+### `FactoryCrawlOptions<F>`
+
+Extracts the crawl options type from a factory — the second argument of a factory call. Useful for typing helpers or components that accept crawl options.
+
+```typescript
+import type { FactoryCrawlOptions } from '@robohall/react-query-factory';
+
+type CrawlOpts = FactoryCrawlOptions<typeof describeInstances>; // → { minResults?: number }
+```
+
 ---
 
 ## Running the sandbox

package/dist/index.d.mts

@@ -100,6 +100,10 @@ interface QueryFactory<TParams = void, TData = unknown, TError = Error, TSelecte
     (params?: TParams, crawlOptions?: TCrawlOptions): ResolvedQueryOptions<TData, TError, TSelected>;
     infinite(params?: TParams, crawlOptions?: TCrawlOptions): 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;
 /**
  * Creates a standalone query factory with pagination and reduce. When `reduce` is
  * present, `shouldFetchNextPage` receives `TSelected` (never undefined) because
@@ -208,4 +212,4 @@ declare function queryFactory<TParams = void, TData = unknown, TError = Error, T
     shouldFetchNextPage: (combined: TSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
 }): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false>;
 
-export { type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };
+export { type FactoryCrawlOptions, type FactoryParams, type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };

package/dist/index.d.ts

@@ -100,6 +100,10 @@ interface QueryFactory<TParams = void, TData = unknown, TError = Error, TSelecte
     (params?: TParams, crawlOptions?: TCrawlOptions): ResolvedQueryOptions<TData, TError, TSelected>;
     infinite(params?: TParams, crawlOptions?: TCrawlOptions): 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;
 /**
  * Creates a standalone query factory with pagination and reduce. When `reduce` is
  * present, `shouldFetchNextPage` receives `TSelected` (never undefined) because
@@ -208,4 +212,4 @@ declare function queryFactory<TParams = void, TData = unknown, TError = Error, T
     shouldFetchNextPage: (combined: TSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
 }): QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions, false>;
 
-export { type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };
+export { type FactoryCrawlOptions, type FactoryParams, type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };

package/dist/index.js

@@ -64,7 +64,7 @@ function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOption
 }
 function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shouldFetchNextPage, reduce) {
   return async (params, crawlOptions, context) => {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     if ((_a = context.signal) == null ? void 0 : _a.aborted) {
       if (reduce) throw new DOMException("Aborted", "AbortError");
       return [];
@@ -74,10 +74,10 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
     if (isAsyncIterable(initialResult)) {
       const pages2 = [];
       let acc2 = void 0;
-      for await (const page of initialResult) {
+      for await (const page2 of initialResult) {
         if ((_b = context.signal) == null ? void 0 : _b.aborted) break;
-        pages2.push(page);
-        if (reduce) acc2 = reduce(acc2, page);
+        pages2.push(page2);
+        if (reduce) acc2 = reduce(acc2, page2);
         if (!shouldFetchNextPage(acc2, crawlOptions)) break;
       }
       if (reduce) {
@@ -90,9 +90,8 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
     const pageParams = [];
     let currentParam = initialPageParam;
     let acc = void 0;
-    let nextResult = initialResult;
+    let page = await initialResult;
     while (true) {
-      const page = await nextResult;
       pages.push(page);
       pageParams.push(currentParam);
       if (reduce) acc = reduce(acc, page);
@@ -102,9 +101,8 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
       const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
       if (nextParam == null) break;
       currentParam = nextParam;
-      if ((_d = context.signal) == null ? void 0 : _d.aborted) break;
       ctx.pageParam = currentParam;
-      nextResult = queryFn(params, ctx);
+      page = await queryFn(params, ctx);
     }
     if (reduce) {
       if (acc === void 0) throw new DOMException("Aborted", "AbortError");
@@ -115,7 +113,7 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
 }
 function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNextPage, reduce) {
   return async (params, crawlOptions, context) => {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     if ((_a = context.signal) == null ? void 0 : _a.aborted)
       throw new DOMException("Aborted", "AbortError");
     const ctx = { ...context, pageParam: context.pageParam };
@@ -125,11 +123,11 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
       const startParam = context.pageParam;
       let acc2 = void 0;
       let nextBatchParam2 = null;
-      for await (const page of initialResult) {
+      for await (const page2 of initialResult) {
         if ((_b = context.signal) == null ? void 0 : _b.aborted) break;
-        pages2.push(page);
-        acc2 = reduce(acc2, page);
-        const nextParam = getNextPageParam(page, pages2, startParam, [
+        pages2.push(page2);
+        acc2 = reduce(acc2, page2);
+        const nextParam = getNextPageParam(page2, pages2, startParam, [
           startParam
         ]);
         nextBatchParam2 = nextParam != null ? nextParam : null;
@@ -144,9 +142,8 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
     let currentParam = context.pageParam;
     let acc = void 0;
     let nextBatchParam = null;
-    let nextResult = initialResult;
+    let page = await initialResult;
     while (true) {
-      const page = await nextResult;
       pages.push(page);
       pageParams.push(currentParam);
       acc = reduce(acc, page);
@@ -156,9 +153,8 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
       if (nextParam == null) break;
       if (!shouldFetchNextPage(acc, crawlOptions)) break;
       currentParam = nextParam;
-      if ((_d = context.signal) == null ? void 0 : _d.aborted) break;
       ctx.pageParam = currentParam;
-      nextResult = queryFn(params, ctx);
+      page = await queryFn(params, ctx);
     }
     if (acc === void 0) throw new DOMException("Aborted", "AbortError");
     return { data: acc, nextPageParam: nextBatchParam };

package/dist/index.mjs

@@ -38,7 +38,7 @@ function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOption
 }
 function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shouldFetchNextPage, reduce) {
   return async (params, crawlOptions, context) => {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     if ((_a = context.signal) == null ? void 0 : _a.aborted) {
       if (reduce) throw new DOMException("Aborted", "AbortError");
       return [];
@@ -48,10 +48,10 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
     if (isAsyncIterable(initialResult)) {
       const pages2 = [];
       let acc2 = void 0;
-      for await (const page of initialResult) {
+      for await (const page2 of initialResult) {
         if ((_b = context.signal) == null ? void 0 : _b.aborted) break;
-        pages2.push(page);
-        if (reduce) acc2 = reduce(acc2, page);
+        pages2.push(page2);
+        if (reduce) acc2 = reduce(acc2, page2);
         if (!shouldFetchNextPage(acc2, crawlOptions)) break;
       }
       if (reduce) {
@@ -64,9 +64,8 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
     const pageParams = [];
     let currentParam = initialPageParam;
     let acc = void 0;
-    let nextResult = initialResult;
+    let page = await initialResult;
     while (true) {
-      const page = await nextResult;
       pages.push(page);
       pageParams.push(currentParam);
       if (reduce) acc = reduce(acc, page);
@@ -76,9 +75,8 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
       const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
       if (nextParam == null) break;
       currentParam = nextParam;
-      if ((_d = context.signal) == null ? void 0 : _d.aborted) break;
       ctx.pageParam = currentParam;
-      nextResult = queryFn(params, ctx);
+      page = await queryFn(params, ctx);
     }
     if (reduce) {
       if (acc === void 0) throw new DOMException("Aborted", "AbortError");
@@ -89,7 +87,7 @@ function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shoul
 }
 function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNextPage, reduce) {
   return async (params, crawlOptions, context) => {
-    var _a, _b, _c, _d;
+    var _a, _b, _c;
     if ((_a = context.signal) == null ? void 0 : _a.aborted)
       throw new DOMException("Aborted", "AbortError");
     const ctx = { ...context, pageParam: context.pageParam };
@@ -99,11 +97,11 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
       const startParam = context.pageParam;
       let acc2 = void 0;
       let nextBatchParam2 = null;
-      for await (const page of initialResult) {
+      for await (const page2 of initialResult) {
         if ((_b = context.signal) == null ? void 0 : _b.aborted) break;
-        pages2.push(page);
-        acc2 = reduce(acc2, page);
-        const nextParam = getNextPageParam(page, pages2, startParam, [
+        pages2.push(page2);
+        acc2 = reduce(acc2, page2);
+        const nextParam = getNextPageParam(page2, pages2, startParam, [
           startParam
         ]);
         nextBatchParam2 = nextParam != null ? nextParam : null;
@@ -118,9 +116,8 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
     let currentParam = context.pageParam;
     let acc = void 0;
     let nextBatchParam = null;
-    let nextResult = initialResult;
+    let page = await initialResult;
     while (true) {
-      const page = await nextResult;
       pages.push(page);
       pageParams.push(currentParam);
       acc = reduce(acc, page);
@@ -130,9 +127,8 @@ function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNext
       if (nextParam == null) break;
       if (!shouldFetchNextPage(acc, crawlOptions)) break;
       currentParam = nextParam;
-      if ((_d = context.signal) == null ? void 0 : _d.aborted) break;
       ctx.pageParam = currentParam;
-      nextResult = queryFn(params, ctx);
+      page = await queryFn(params, ctx);
     }
     if (acc === void 0) throw new DOMException("Aborted", "AbortError");
     return { data: acc, nextPageParam: nextBatchParam };

package/package.json

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