@robohall/react-query-factory 1.0.2 → 1.0.4

package/README.md

@@ -85,13 +85,14 @@ function InstanceList() {
 }
 ```
 
-**`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:
+**`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:
 
 ```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 ?? 0) < opts.minResults,
+    opts.minResults != null && instances.length < opts.minResults,  // instances: Instance[], not Instance[] | undefined
 });
 
 // stop after accumulating at least 50 instances
@@ -201,8 +202,8 @@ All fields except `reduce` and `shouldFetchNextPage` are the standard TanStack Q
 | `initialPageParam` | `TPageParam` | Exact TanStack API. Required alongside `getNextPageParam` to enable crawling. |
 | `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 \| undefined, crawlOptions: TCrawlOptions) => boolean` | Library addition. Return `false` to stop the crawl early based on accumulated results. |
-| + all `StandardQueryOptions` fields | | `staleTime`, `gcTime`, `retry`, `enabled`, `refetchOnWindowFocus`, etc. |
+| `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. |
+| + 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

@@ -1,27 +1,14 @@
-import { QueryKey, NotifyOnChangeProps, QueryMeta, QueryFunctionContext, InfiniteData, GetNextPageParamFunction, GetPreviousPageParamFunction } from '@tanstack/react-query';
+import { QueryObserverOptions, QueryKey, QueryFunctionContext, InfiniteData, GetNextPageParamFunction, GetPreviousPageParamFunction } from '@tanstack/react-query';
 
-/** Subset of TanStack Query options that apply to both regular and infinite queries. */
-interface StandardQueryOptions<TError = Error> {
-    enabled?: boolean;
-    staleTime?: number | ((query: {
-        queryKey: QueryKey;
-    }) => number);
-    gcTime?: number;
-    retry?: boolean | number | ((failureCount: number, error: TError) => boolean);
-    retryDelay?: number | ((retryAttempt: number, error: TError) => number);
-    refetchOnWindowFocus?: boolean | 'always';
-    refetchOnReconnect?: boolean | 'always';
-    refetchOnMount?: boolean | 'always';
-    refetchInterval?: number | false | ((query: {
-        queryKey: QueryKey;
-    }) => number | false);
-    refetchIntervalInBackground?: boolean;
-    networkMode?: 'online' | 'always' | 'offlineFirst';
-    notifyOnChangeProps?: NotifyOnChangeProps;
-    throwOnError?: boolean | ((error: TError) => boolean);
-    meta?: QueryMeta;
-    structuralSharing?: boolean;
-}
+/**
+ * All TanStack Query options that apply to both regular and infinite queries,
+ * derived directly from `QueryObserverOptions` so it stays in sync with TanStack.
+ *
+ * Fields owned by the factory (`queryKey`, `queryFn`, `select`) and internal
+ * implementation details (`behavior`, `_defaulted`, `_type`, `_optimisticResults`,
+ * `queryHash`) are omitted.
+ */
+type StandardQueryOptions<TError = Error, TData = unknown> = Omit<QueryObserverOptions<TData, TError, TData, TData, QueryKey>, 'queryKey' | 'queryFn' | 'select' | 'behavior' | '_defaulted' | '_type' | '_optimisticResults' | 'queryHash'>;
 /**
  * Configuration passed to `queryFactory()`.
  *
@@ -31,32 +18,45 @@ interface StandardQueryOptions<TError = Error> {
  *   single `TSelected` value.
  * - Call `factory.infinite(params)` to get a `useInfiniteQuery`-compatible config
  *   where each virtual page is itself a crawl.
+ *
+ * When `getNextPageParam` is provided, `initialPageParam` is required. This
+ * mirrors TanStack's own API and ensures `TPageParam` is inferred from the
+ * concrete initial value (so `ctx.pageParam` in `queryFn` is typed correctly).
  */
-interface QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> extends StandardQueryOptions<TError> {
+type QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> = 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;
-    queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, TPageParam>) => TData | Promise<TData>;
+    queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, [unknown] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
     select?: (data: TData) => TSelected;
+} & ({
     /** TanStack v5 generic order: GetNextPageParamFunction<TPageParam, TData> */
-    getNextPageParam?: 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;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
-    initialPageParam?: TPageParam;
-    /** Called after each page to decide whether to keep crawling.
-     *  Receives the current combined result and the crawl options from the call site. */
-    shouldFetchNextPage?: (combined: TSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
     /** 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. */
     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. */
+    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()`.
  *
  * The `initialPageParam?: never` field is a structural guard that makes this
  * type incompatible with `useInfiniteQuery`, preventing accidental misuse.
  */
-type ResolvedQueryOptions<TData = unknown, TError = Error, TSelected = TData> = StandardQueryOptions<TError> & {
+type ResolvedQueryOptions<TData = unknown, TError = Error, TSelected = TData> = StandardQueryOptions<TError, TData> & {
     queryKey: QueryKey;
     queryFn?: (context: QueryFunctionContext) => TData | Promise<TData>;
     select?: (data: TData) => TSelected;
@@ -69,7 +69,7 @@ type ResolvedQueryOptions<TData = unknown, TError = Error, TSelected = TData> =
  * The `select` field expects `InfiniteData<TData, TPageParam>`, which is a structural
  * guard making this type incompatible with `useQuery`.
  */
-type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown> = StandardQueryOptions<TError> & {
+type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown> = 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,
@@ -99,6 +99,21 @@ 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>;
 }
+/**
+ * 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> & {
+    queryKey: QueryKey;
+    queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, [unknown] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
+    select?: (data: TData) => 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>;
 /**
  * Creates a standalone query factory from a config object.
  *
@@ -140,10 +155,15 @@ 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: Omit<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions>, 'queryKey' | 'queryFn' | 'select'> & {
+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> & {
     queryKey?: QueryKey;
     queryFn?: never;
     select?: (data: TParentSelected) => TChildSelected;
+    getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
+    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>;
 
 export { type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };

package/dist/index.d.ts

@@ -1,27 +1,14 @@
-import { QueryKey, NotifyOnChangeProps, QueryMeta, QueryFunctionContext, InfiniteData, GetNextPageParamFunction, GetPreviousPageParamFunction } from '@tanstack/react-query';
+import { QueryObserverOptions, QueryKey, QueryFunctionContext, InfiniteData, GetNextPageParamFunction, GetPreviousPageParamFunction } from '@tanstack/react-query';
 
-/** Subset of TanStack Query options that apply to both regular and infinite queries. */
-interface StandardQueryOptions<TError = Error> {
-    enabled?: boolean;
-    staleTime?: number | ((query: {
-        queryKey: QueryKey;
-    }) => number);
-    gcTime?: number;
-    retry?: boolean | number | ((failureCount: number, error: TError) => boolean);
-    retryDelay?: number | ((retryAttempt: number, error: TError) => number);
-    refetchOnWindowFocus?: boolean | 'always';
-    refetchOnReconnect?: boolean | 'always';
-    refetchOnMount?: boolean | 'always';
-    refetchInterval?: number | false | ((query: {
-        queryKey: QueryKey;
-    }) => number | false);
-    refetchIntervalInBackground?: boolean;
-    networkMode?: 'online' | 'always' | 'offlineFirst';
-    notifyOnChangeProps?: NotifyOnChangeProps;
-    throwOnError?: boolean | ((error: TError) => boolean);
-    meta?: QueryMeta;
-    structuralSharing?: boolean;
-}
+/**
+ * All TanStack Query options that apply to both regular and infinite queries,
+ * derived directly from `QueryObserverOptions` so it stays in sync with TanStack.
+ *
+ * Fields owned by the factory (`queryKey`, `queryFn`, `select`) and internal
+ * implementation details (`behavior`, `_defaulted`, `_type`, `_optimisticResults`,
+ * `queryHash`) are omitted.
+ */
+type StandardQueryOptions<TError = Error, TData = unknown> = Omit<QueryObserverOptions<TData, TError, TData, TData, QueryKey>, 'queryKey' | 'queryFn' | 'select' | 'behavior' | '_defaulted' | '_type' | '_optimisticResults' | 'queryHash'>;
 /**
  * Configuration passed to `queryFactory()`.
  *
@@ -31,32 +18,45 @@ interface StandardQueryOptions<TError = Error> {
  *   single `TSelected` value.
  * - Call `factory.infinite(params)` to get a `useInfiniteQuery`-compatible config
  *   where each virtual page is itself a crawl.
+ *
+ * When `getNextPageParam` is provided, `initialPageParam` is required. This
+ * mirrors TanStack's own API and ensures `TPageParam` is inferred from the
+ * concrete initial value (so `ctx.pageParam` in `queryFn` is typed correctly).
  */
-interface QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> extends StandardQueryOptions<TError> {
+type QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> = 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;
-    queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, TPageParam>) => TData | Promise<TData>;
+    queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, [unknown] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
     select?: (data: TData) => TSelected;
+} & ({
     /** TanStack v5 generic order: GetNextPageParamFunction<TPageParam, TData> */
-    getNextPageParam?: 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;
     getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
-    initialPageParam?: TPageParam;
-    /** Called after each page to decide whether to keep crawling.
-     *  Receives the current combined result and the crawl options from the call site. */
-    shouldFetchNextPage?: (combined: TSelected | undefined, crawlOptions: TCrawlOptions) => boolean;
     /** 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. */
     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. */
+    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()`.
  *
  * The `initialPageParam?: never` field is a structural guard that makes this
  * type incompatible with `useInfiniteQuery`, preventing accidental misuse.
  */
-type ResolvedQueryOptions<TData = unknown, TError = Error, TSelected = TData> = StandardQueryOptions<TError> & {
+type ResolvedQueryOptions<TData = unknown, TError = Error, TSelected = TData> = StandardQueryOptions<TError, TData> & {
     queryKey: QueryKey;
     queryFn?: (context: QueryFunctionContext) => TData | Promise<TData>;
     select?: (data: TData) => TSelected;
@@ -69,7 +69,7 @@ type ResolvedQueryOptions<TData = unknown, TError = Error, TSelected = TData> =
  * The `select` field expects `InfiniteData<TData, TPageParam>`, which is a structural
  * guard making this type incompatible with `useQuery`.
  */
-type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown> = StandardQueryOptions<TError> & {
+type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown> = 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,
@@ -99,6 +99,21 @@ 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>;
 }
+/**
+ * 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> & {
+    queryKey: QueryKey;
+    queryFn?: (params: TParams, context: QueryFunctionContext<QueryKey, [unknown] extends [TPageParam] ? never : TPageParam>) => TData | Promise<TData>;
+    select?: (data: TData) => 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>;
 /**
  * Creates a standalone query factory from a config object.
  *
@@ -140,10 +155,15 @@ 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: Omit<QueryFactoryConfig<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions>, 'queryKey' | 'queryFn' | 'select'> & {
+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> & {
     queryKey?: QueryKey;
     queryFn?: never;
     select?: (data: TParentSelected) => TChildSelected;
+    getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
+    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>;
 
 export { type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };

package/package.json

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