@robohall/react-query-factory 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Hall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# react-query-factory
+
+TanStack Query is very good at caching. It is less good at deciding what your query keys should be, or at fetching every page of a cursor-paginated endpoint before your component has to think about it.
+
+This library wraps query definitions in a small factory function that handles composable key namespacing, automatic multi-page crawling, and `useInfiniteQuery` generation — so the part of your codebase that knows *what* to fetch stays separate from the part that knows *how React renders it*.
+
+It has zero runtime dependencies — all TanStack Query imports are type-only and erased at compile time.
+
+---
+
+## Installation
+
+```bash
+npm install react-query-factory
+# peer dependency: @tanstack/react-query >= 5.0.0
+```
+
+---
+
+## Quick start
+
+Define a factory once, call it in any component:
+
+```typescript
+import {
+  EC2Client,
+  DescribeInstancesCommand,
+  type DescribeInstancesCommandInput,
+} from '@aws-sdk/client-ec2';
+import { queryFactory } from 'react-query-factory';
+import { useQuery } from '@tanstack/react-query';
+
+const ec2 = new EC2Client({ region: 'us-east-1' });
+
+const describeInstances = queryFactory({
+  queryKey: ['ec2:DescribeInstances'],
+  queryFn: (params: DescribeInstancesCommandInput, ctx) =>
+    ec2.send(new DescribeInstancesCommand(params), { abortSignal: ctx.signal }),
+  staleTime: 30_000,
+});
+
+function InstanceList() {
+  const { data } = useQuery(
+    describeInstances({ Filters: [{ Name: 'instance-state-name', Values: ['running'] }] })
+  );
+  // query key:  ['ec2:DescribeInstances', { Filters: [...] }]
+  // staleTime:  30 000 ms, no repetition required
+}
+```
+
+`describeInstances({ ... })` returns a plain object — `{ queryKey, queryFn, staleTime, … }` — that you spread or pass directly to `useQuery`. The factory does not touch your query client.
+
+---
+
+## 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.
+
+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:
+
+```typescript
+import type { Instance, DescribeInstancesCommandInput } from '@aws-sdk/client-ec2';
+
+const describeInstances = queryFactory({
+  queryKey: ['ec2:DescribeInstances'],
+  queryFn: (params: DescribeInstancesCommandInput, ctx) =>
+    ec2.send(
+      new DescribeInstancesCommand({ ...params, NextToken: ctx.pageParam }),
+      { abortSignal: ctx.signal },
+    ),
+  getNextPageParam: response => response.NextToken,
+  initialPageParam: undefined as string | undefined,
+  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 }));
+}
+```
+
+**`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:
+
+```typescript
+const describeInstances = queryFactory({
+  // ...
+  shouldFetchNextPage: (instances, opts: { minResults?: number }) =>
+    opts.minResults != null && (instances?.length ?? 0) < opts.minResults,
+});
+
+// stop after accumulating at least 50 instances
+const { data } = useQuery(
+  describeInstances({ MaxResults: 1000 }, { minResults: 50 })
+);
+```
+
+`crawlOptions` is appended to the query key, so `describeInstances({}, { minResults: 50 })` and `describeInstances({}, { minResults: 200 })` are separate cache entries — they crawl independently and never collide.
+
+---
+
+## Factory composition
+
+A factory can inherit from another factory. The child's query key is appended to the parent's, standard options are shallow-merged, and the `queryFn` and crawling config can be inherited or replaced.
+
+**Inherit the queryFn, add a `select` transform:**
+
+```typescript
+const runningInstances = queryFactory(describeInstances, {
+  select: instances => instances.filter(i => i.State?.Name === 'running'),
+});
+
+// query key:  ['ec2:DescribeInstances', { MaxResults: 1000 }]  (same cache entry as parent)
+// data:       Instance[] filtered to State.Name === 'running'
+const { data } = useQuery(runningInstances({ MaxResults: 1000 }));
+```
+
+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.
+
+**Add a new queryFn under the parent's namespace:**
+
+```typescript
+const findInstance = queryFactory(describeInstances, {
+  queryKey: ['find'],
+  // queryFn, getNextPageParam, initialPageParam, and reduce are all inherited
+  shouldFetchNextPage: (instances, opts: { instanceId?: string }) =>
+    opts.instanceId != null &&
+    !instances?.some(i => i.InstanceId === opts.instanceId),
+});
+
+// query key: ['ec2:DescribeInstances', 'find', { MaxResults: 100 }, { instanceId: 'i-0abc123' }]
+// crawls pages until the target instance appears, then stops
+const { data } = useQuery(
+  findInstance({ MaxResults: 100 }, { instanceId: 'i-0abc123def456' })
+);
+```
+
+Because `findInstance`'s key is nested under `['ec2:DescribeInstances']`, a single invalidation call busts the parent and all children:
+
+```typescript
+// after a runInstances/terminateInstances mutation — invalidates everything in the namespace.
+// Calling the factory with no args produces just the namespace key; TanStack prefix-matches it
+// against all entries, so describeInstances, runningInstances, and findInstance are all busted.
+await queryClient.invalidateQueries(describeInstances());
+```
+
+---
+
+## Infinite queries
+
+Every factory exposes a `.infinite()` method that returns `useInfiniteQuery`-compatible options. If the factory has `reduce` configured, each virtual page is itself a crawl — TanStack loads pages one at a time, but each "page load" makes multiple API calls and reduces them before handing the result back:
+
+```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 })
+);
+
+// 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 }]`
+
+---
+
+## Public API
+
+### `queryFactory(config)`
+
+Creates a standalone factory.
+
+```typescript
+queryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions>(
+  config: QueryFactoryConfig<...>
+): QueryFactory<...>
+```
+
+### `queryFactory(parent, config)`
+
+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.
+
+### `QueryFactoryConfig`
+
+All fields except `reduce` and `shouldFetchNextPage` are the standard TanStack Query API — the same types and semantics you'd pass to `useQuery` or `useInfiniteQuery`. The factory doesn't reinvent them; it just requires certain combinations to be present in order to activate crawling.
+
+| Field | Type | Notes |
+|---|---|---|
+| `queryKey` | `QueryKey` | Namespace segments. Params are appended at call time. |
+| `queryFn` | `(params: TParams, ctx: QueryFunctionContext) => TData \| Promise<TData>` | 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. |
+| `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. |
+
+### `QueryFactory<TParams, TData, TError, TSelected, TPageParam, TCrawlOptions>`
+
+The callable factory returned by `queryFactory()`.
+
+```typescript
+factory(params: TParams, crawlOptions?: TCrawlOptions): ResolvedQueryOptions  // → useQuery()
+factory.infinite(params, crawlOptions?)                : ResolvedInfiniteOptions // → useInfiniteQuery()
+```
+
+### `ResolvedQueryOptions`
+
+Return type of `factory(params)`. Pass directly to `useQuery()`. Contains an `initialPageParam?: never` field that prevents accidental use with `useInfiniteQuery`.
+
+### `ResolvedInfiniteOptions`
+
+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`.
+
+---
+
+## Running the sandbox
+
+The sandbox contains five interactive demos using a mock paginated API: basic single-page fetch, full crawl, factory composition, infinite query with per-page crawling, and a target-search that stops the crawl early.
+
+```bash
+npm run sandbox
+```
+
+This starts a Vite dev server. Navigate to the URL it prints (typically `http://localhost:5173`).

package/dist/index.d.mts

@@ -0,0 +1,149 @@
+import { QueryKey, NotifyOnChangeProps, QueryMeta, 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;
+}
+/**
+ * Configuration passed to `queryFactory()`.
+ *
+ * - Set only `queryKey` + `queryFn` for a basic single-page query.
+ * - Add `getNextPageParam`, `initialPageParam`, and `reduce` to enable automatic
+ *   pagination: the generated `queryFn` crawls all pages and reduces them to a
+ *   single `TSelected` value.
+ * - Call `factory.infinite(params)` to get a `useInfiniteQuery`-compatible config
+ *   where each virtual page is itself a crawl.
+ */
+interface QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> extends StandardQueryOptions<TError> {
+    /** 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>;
+    select?: (data: TData) => TSelected;
+    /** TanStack v5 generic order: GetNextPageParamFunction<TPageParam, TData> */
+    getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
+    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;
+}
+/**
+ * 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> & {
+    queryKey: QueryKey;
+    queryFn?: (context: QueryFunctionContext) => TData | Promise<TData>;
+    select?: (data: TData) => TSelected;
+    /** Structural guard: makes this type incompatible with useInfiniteQuery, which requires initialPageParam. */
+    initialPageParam?: never;
+};
+/**
+ * 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`.
+ */
+type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown> = StandardQueryOptions<TError> & {
+    queryKey: QueryKey;
+    queryFn?: (context: QueryFunctionContext<QueryKey, TPageParam>) => TData | Promise<TData>;
+    /** Structural guard: the InfiniteData parameter type makes this incompatible with useQuery,
+     *  whose select expects (data: TData) rather than (data: InfiniteData<TData, TPageParam>). */
+    select?: (data: InfiniteData<TData, TPageParam>) => any;
+    /** Required so this type satisfies useInfiniteQuery, which requires getNextPageParam. */
+    getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
+    getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
+    /** Required so this type satisfies useInfiniteQuery, which requires initialPageParam. */
+    initialPageParam: TPageParam;
+};
+/**
+ * A callable factory produced by `queryFactory()`.
+ *
+ * - `factory(params)` → `ResolvedQueryOptions` for `useQuery()`
+ * - `factory.infinite(params)` → `ResolvedInfiniteOptions` for `useInfiniteQuery()`
+ *
+ * Both signatures accept an optional `crawlOptions` object that is appended to
+ * the query key and passed to `shouldFetchNextPage` so different call sites can
+ * control crawl behavior independently.
+ *
+ * `params` is always optional. Calling with no arguments produces just the
+ * 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>> {
+    (params?: TParams, crawlOptions?: TCrawlOptions): ResolvedQueryOptions<TData, TError, TSelected>;
+    infinite(params?: TParams, crawlOptions?: TCrawlOptions): ResolvedInfiniteOptions<TData, TError, TPageParam>;
+}
+/**
+ * Creates a standalone query factory from a config object.
+ *
+ * @example
+ * const usersFactory = queryFactory({
+ *   queryKey: ['users'],
+ *   queryFn: (params: { page: number }, ctx) => fetchUsers(params, ctx.signal),
+ * });
+ * // 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>;
+/**
+ * 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
+ * the parent's, and standard options are shallow-merged (child wins).
+ *
+ * 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'> & {
+    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>;
+/**
+ * Creates a child factory that reuses the parent's `queryFn` and pagination
+ * config. Useful for adding a `select` transform, narrowing params, or
+ * overriding `shouldFetchNextPage` with a different crawl-options shape —
+ * 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'> & {
+    queryKey?: QueryKey;
+    queryFn?: never;
+    select?: (data: TParentSelected) => TChildSelected;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions>;
+
+export { type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+import { QueryKey, NotifyOnChangeProps, QueryMeta, 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;
+}
+/**
+ * Configuration passed to `queryFactory()`.
+ *
+ * - Set only `queryKey` + `queryFn` for a basic single-page query.
+ * - Add `getNextPageParam`, `initialPageParam`, and `reduce` to enable automatic
+ *   pagination: the generated `queryFn` crawls all pages and reduces them to a
+ *   single `TSelected` value.
+ * - Call `factory.infinite(params)` to get a `useInfiniteQuery`-compatible config
+ *   where each virtual page is itself a crawl.
+ */
+interface QueryFactoryConfig<TParams = void, TData = unknown, TError = Error, TSelected = TData, TPageParam = unknown, TCrawlOptions extends Record<string, unknown> = Record<string, unknown>> extends StandardQueryOptions<TError> {
+    /** 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>;
+    select?: (data: TData) => TSelected;
+    /** TanStack v5 generic order: GetNextPageParamFunction<TPageParam, TData> */
+    getNextPageParam?: GetNextPageParamFunction<TPageParam, TData>;
+    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;
+}
+/**
+ * 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> & {
+    queryKey: QueryKey;
+    queryFn?: (context: QueryFunctionContext) => TData | Promise<TData>;
+    select?: (data: TData) => TSelected;
+    /** Structural guard: makes this type incompatible with useInfiniteQuery, which requires initialPageParam. */
+    initialPageParam?: never;
+};
+/**
+ * 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`.
+ */
+type ResolvedInfiniteOptions<TData = unknown, TError = Error, TPageParam = unknown> = StandardQueryOptions<TError> & {
+    queryKey: QueryKey;
+    queryFn?: (context: QueryFunctionContext<QueryKey, TPageParam>) => TData | Promise<TData>;
+    /** Structural guard: the InfiniteData parameter type makes this incompatible with useQuery,
+     *  whose select expects (data: TData) rather than (data: InfiniteData<TData, TPageParam>). */
+    select?: (data: InfiniteData<TData, TPageParam>) => any;
+    /** Required so this type satisfies useInfiniteQuery, which requires getNextPageParam. */
+    getNextPageParam: GetNextPageParamFunction<TPageParam, TData>;
+    getPreviousPageParam?: GetPreviousPageParamFunction<TPageParam, TData>;
+    /** Required so this type satisfies useInfiniteQuery, which requires initialPageParam. */
+    initialPageParam: TPageParam;
+};
+/**
+ * A callable factory produced by `queryFactory()`.
+ *
+ * - `factory(params)` → `ResolvedQueryOptions` for `useQuery()`
+ * - `factory.infinite(params)` → `ResolvedInfiniteOptions` for `useInfiniteQuery()`
+ *
+ * Both signatures accept an optional `crawlOptions` object that is appended to
+ * the query key and passed to `shouldFetchNextPage` so different call sites can
+ * control crawl behavior independently.
+ *
+ * `params` is always optional. Calling with no arguments produces just the
+ * 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>> {
+    (params?: TParams, crawlOptions?: TCrawlOptions): ResolvedQueryOptions<TData, TError, TSelected>;
+    infinite(params?: TParams, crawlOptions?: TCrawlOptions): ResolvedInfiniteOptions<TData, TError, TPageParam>;
+}
+/**
+ * Creates a standalone query factory from a config object.
+ *
+ * @example
+ * const usersFactory = queryFactory({
+ *   queryKey: ['users'],
+ *   queryFn: (params: { page: number }, ctx) => fetchUsers(params, ctx.signal),
+ * });
+ * // 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>;
+/**
+ * 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
+ * the parent's, and standard options are shallow-merged (child wins).
+ *
+ * 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'> & {
+    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>;
+/**
+ * Creates a child factory that reuses the parent's `queryFn` and pagination
+ * config. Useful for adding a `select` transform, narrowing params, or
+ * overriding `shouldFetchNextPage` with a different crawl-options shape —
+ * 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'> & {
+    queryKey?: QueryKey;
+    queryFn?: never;
+    select?: (data: TParentSelected) => TChildSelected;
+}): QueryFactory<TChildParams, TData, TError, TChildSelected, TPageParam, TChildCrawlOptions>;
+
+export { type QueryFactory, type QueryFactoryConfig, type ResolvedInfiniteOptions, type ResolvedQueryOptions, type StandardQueryOptions, queryFactory };

package/dist/index.js

@@ -0,0 +1,244 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  queryFactory: () => queryFactory
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/queryFactory.ts
+var FACTORY_CONFIG = /* @__PURE__ */ Symbol("factoryConfig");
+function resolveKey(namespace, params, crawlOptions) {
+  const base = Array.isArray(namespace) ? namespace : [namespace];
+  const withParams = params === void 0 ? base : [...base, params];
+  if (!crawlOptions) return withParams;
+  const defined = Object.fromEntries(Object.entries(crawlOptions).filter(([, v]) => v !== void 0));
+  return Object.keys(defined).length > 0 ? [...withParams, defined] : withParams;
+}
+function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, reduce) {
+  return (lastPage, allPages, lastPageParam, allPageParams) => {
+    const combined = reduce ? allPages.reduce((acc, page) => reduce(acc, page), void 0) : lastPage;
+    if (!shouldFetchNextPage(combined, crawlOptions)) return void 0;
+    return getNextPageParam(lastPage, allPages, lastPageParam, allPageParams);
+  };
+}
+function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shouldFetchNextPage, reduce, crawlOptions) {
+  return async (context) => {
+    var _a, _b;
+    const pages = [];
+    const pageParams = [];
+    let currentParam = initialPageParam;
+    let acc = void 0;
+    while (true) {
+      if ((_a = context.signal) == null ? void 0 : _a.aborted) break;
+      const page = await queryFn({ ...context, pageParam: currentParam });
+      pages.push(page);
+      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;
+      const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
+      if (nextParam == null) break;
+      currentParam = nextParam;
+    }
+    if (reduce) {
+      if (acc === void 0) throw new DOMException("Aborted", "AbortError");
+      return acc;
+    }
+    return pages;
+  };
+}
+function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNextPage, reduce, crawlOptions) {
+  return async (context) => {
+    var _a, _b;
+    const pages = [];
+    const pageParams = [];
+    let currentParam = context.pageParam;
+    let acc = void 0;
+    let nextBatchParam = null;
+    while (true) {
+      if ((_a = context.signal) == null ? void 0 : _a.aborted) break;
+      const page = await queryFn({ ...context, pageParam: currentParam });
+      pages.push(page);
+      pageParams.push(currentParam);
+      acc = reduce(acc, page);
+      if ((_b = context.signal) == null ? void 0 : _b.aborted) break;
+      const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
+      nextBatchParam = nextParam != null ? nextParam : null;
+      if (nextParam == null) break;
+      if (shouldFetchNextPage && !shouldFetchNextPage(acc, crawlOptions)) break;
+      currentParam = nextParam;
+    }
+    if (acc === void 0) throw new DOMException("Aborted", "AbortError");
+    return { data: acc, nextPageParam: nextBatchParam };
+  };
+}
+function buildFactory(cfg) {
+  const {
+    queryKey: namespace,
+    queryFn: rawQueryFn,
+    select,
+    getNextPageParam,
+    getPreviousPageParam,
+    initialPageParam,
+    shouldFetchNextPage,
+    reduce,
+    standardOptions
+  } = cfg;
+  const hasCrawling = rawQueryFn !== void 0 && getNextPageParam !== void 0;
+  const hasInfiniteCrawling = hasCrawling && reduce !== void 0;
+  const factory = function(params, crawlOptions = {}) {
+    const queryKey = resolveKey(namespace, params, crawlOptions);
+    const boundQueryFn = rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
+    const resolvedQueryFn = hasCrawling ? buildCrawlingQueryFn(boundQueryFn, getNextPageParam, initialPageParam, shouldFetchNextPage, reduce, crawlOptions) : boundQueryFn;
+    return {
+      ...standardOptions,
+      queryKey,
+      ...resolvedQueryFn !== void 0 && { queryFn: resolvedQueryFn },
+      ...select !== void 0 && { select },
+      [FACTORY_CONFIG]: cfg
+    };
+  };
+  factory.infinite = function(params, crawlOptions = {}) {
+    const queryKey = resolveKey([...resolveKey(namespace, void 0), "infinite"], params, crawlOptions);
+    const boundQueryFn = rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
+    if (hasInfiniteCrawling) {
+      const crawlingQueryFn = buildInfiniteCrawlingQueryFn(
+        boundQueryFn,
+        getNextPageParam,
+        shouldFetchNextPage,
+        reduce,
+        crawlOptions
+      );
+      const envelopeGetNextPageParam = (envelope) => envelope.nextPageParam;
+      const envelopeSelect = (data) => ({
+        ...data,
+        pages: data.pages.map((e) => select ? select(e.data) : e.data)
+      });
+      return {
+        ...standardOptions,
+        queryKey,
+        queryFn: crawlingQueryFn,
+        getNextPageParam: envelopeGetNextPageParam,
+        initialPageParam,
+        select: envelopeSelect,
+        ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
+        [FACTORY_CONFIG]: cfg
+      };
+    }
+    const infiniteGetNextPageParam = getNextPageParam && shouldFetchNextPage ? wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, reduce) : getNextPageParam != null ? getNextPageParam : (() => void 0);
+    const infiniteSelect = select ? (data) => ({
+      ...data,
+      pages: data.pages.map(select)
+    }) : void 0;
+    return {
+      ...standardOptions,
+      queryKey,
+      ...boundQueryFn !== void 0 && { queryFn: boundQueryFn },
+      ...infiniteSelect !== void 0 && { select: infiniteSelect },
+      getNextPageParam: infiniteGetNextPageParam,
+      ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
+      ...initialPageParam !== void 0 && { initialPageParam },
+      [FACTORY_CONFIG]: cfg
+    };
+  };
+  return factory;
+}
+function queryFactory(configOrParent, childConfig) {
+  var _a, _b, _c, _d, _e;
+  if (childConfig !== void 0 && typeof configOrParent === "function") {
+    const result = configOrParent();
+    const parentCfg = result == null ? void 0 : result[FACTORY_CONFIG];
+    if (!parentCfg) {
+      throw new Error("queryFactory: first argument must be a factory created by queryFactory()");
+    }
+    const hasNewQueryFn = childConfig.queryFn !== void 0;
+    const childNamespace = childConfig.queryKey ? Array.isArray(childConfig.queryKey) ? childConfig.queryKey : [childConfig.queryKey] : [];
+    const composedNamespace = [...parentCfg.queryKey, ...childNamespace];
+    let resolvedSelect;
+    if (hasNewQueryFn) {
+      resolvedSelect = childConfig.select;
+    } else if (childConfig.select && parentCfg.select) {
+      const p = parentCfg.select;
+      const c = childConfig.select;
+      resolvedSelect = (data) => c(p(data));
+    } else {
+      resolvedSelect = (_a = childConfig.select) != null ? _a : parentCfg.select;
+    }
+    const crawling = hasNewQueryFn ? {
+      getNextPageParam: childConfig.getNextPageParam,
+      getPreviousPageParam: childConfig.getPreviousPageParam,
+      initialPageParam: childConfig.initialPageParam,
+      shouldFetchNextPage: childConfig.shouldFetchNextPage,
+      reduce: childConfig.reduce
+    } : {
+      getNextPageParam: (_b = childConfig.getNextPageParam) != null ? _b : parentCfg.getNextPageParam,
+      getPreviousPageParam: (_c = childConfig.getPreviousPageParam) != null ? _c : parentCfg.getPreviousPageParam,
+      initialPageParam: childConfig.initialPageParam !== void 0 ? childConfig.initialPageParam : parentCfg.initialPageParam,
+      shouldFetchNextPage: (_d = childConfig.shouldFetchNextPage) != null ? _d : parentCfg.shouldFetchNextPage,
+      reduce: (_e = childConfig.reduce) != null ? _e : parentCfg.reduce
+    };
+    const {
+      queryKey: _k,
+      queryFn: _f,
+      select: _s,
+      getNextPageParam: _g,
+      getPreviousPageParam: _gp,
+      initialPageParam: _ip,
+      shouldFetchNextPage: _sfnp,
+      reduce: _c2,
+      ...childStandardOptions
+    } = childConfig;
+    return buildFactory({
+      queryKey: composedNamespace,
+      queryFn: hasNewQueryFn ? childConfig.queryFn : parentCfg.queryFn,
+      select: resolvedSelect,
+      ...crawling,
+      standardOptions: { ...parentCfg.standardOptions, ...childStandardOptions }
+    });
+  }
+  const {
+    queryKey,
+    queryFn,
+    select,
+    getNextPageParam,
+    getPreviousPageParam,
+    initialPageParam,
+    shouldFetchNextPage,
+    reduce,
+    ...standardOptions
+  } = configOrParent;
+  return buildFactory({
+    queryKey,
+    queryFn,
+    select,
+    getNextPageParam,
+    getPreviousPageParam,
+    initialPageParam,
+    shouldFetchNextPage,
+    reduce,
+    standardOptions
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  queryFactory
+});

package/dist/index.mjs

@@ -0,0 +1,217 @@
+// src/queryFactory.ts
+var FACTORY_CONFIG = /* @__PURE__ */ Symbol("factoryConfig");
+function resolveKey(namespace, params, crawlOptions) {
+  const base = Array.isArray(namespace) ? namespace : [namespace];
+  const withParams = params === void 0 ? base : [...base, params];
+  if (!crawlOptions) return withParams;
+  const defined = Object.fromEntries(Object.entries(crawlOptions).filter(([, v]) => v !== void 0));
+  return Object.keys(defined).length > 0 ? [...withParams, defined] : withParams;
+}
+function wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, reduce) {
+  return (lastPage, allPages, lastPageParam, allPageParams) => {
+    const combined = reduce ? allPages.reduce((acc, page) => reduce(acc, page), void 0) : lastPage;
+    if (!shouldFetchNextPage(combined, crawlOptions)) return void 0;
+    return getNextPageParam(lastPage, allPages, lastPageParam, allPageParams);
+  };
+}
+function buildCrawlingQueryFn(queryFn, getNextPageParam, initialPageParam, shouldFetchNextPage, reduce, crawlOptions) {
+  return async (context) => {
+    var _a, _b;
+    const pages = [];
+    const pageParams = [];
+    let currentParam = initialPageParam;
+    let acc = void 0;
+    while (true) {
+      if ((_a = context.signal) == null ? void 0 : _a.aborted) break;
+      const page = await queryFn({ ...context, pageParam: currentParam });
+      pages.push(page);
+      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;
+      const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
+      if (nextParam == null) break;
+      currentParam = nextParam;
+    }
+    if (reduce) {
+      if (acc === void 0) throw new DOMException("Aborted", "AbortError");
+      return acc;
+    }
+    return pages;
+  };
+}
+function buildInfiniteCrawlingQueryFn(queryFn, getNextPageParam, shouldFetchNextPage, reduce, crawlOptions) {
+  return async (context) => {
+    var _a, _b;
+    const pages = [];
+    const pageParams = [];
+    let currentParam = context.pageParam;
+    let acc = void 0;
+    let nextBatchParam = null;
+    while (true) {
+      if ((_a = context.signal) == null ? void 0 : _a.aborted) break;
+      const page = await queryFn({ ...context, pageParam: currentParam });
+      pages.push(page);
+      pageParams.push(currentParam);
+      acc = reduce(acc, page);
+      if ((_b = context.signal) == null ? void 0 : _b.aborted) break;
+      const nextParam = getNextPageParam(page, pages, currentParam, pageParams);
+      nextBatchParam = nextParam != null ? nextParam : null;
+      if (nextParam == null) break;
+      if (shouldFetchNextPage && !shouldFetchNextPage(acc, crawlOptions)) break;
+      currentParam = nextParam;
+    }
+    if (acc === void 0) throw new DOMException("Aborted", "AbortError");
+    return { data: acc, nextPageParam: nextBatchParam };
+  };
+}
+function buildFactory(cfg) {
+  const {
+    queryKey: namespace,
+    queryFn: rawQueryFn,
+    select,
+    getNextPageParam,
+    getPreviousPageParam,
+    initialPageParam,
+    shouldFetchNextPage,
+    reduce,
+    standardOptions
+  } = cfg;
+  const hasCrawling = rawQueryFn !== void 0 && getNextPageParam !== void 0;
+  const hasInfiniteCrawling = hasCrawling && reduce !== void 0;
+  const factory = function(params, crawlOptions = {}) {
+    const queryKey = resolveKey(namespace, params, crawlOptions);
+    const boundQueryFn = rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
+    const resolvedQueryFn = hasCrawling ? buildCrawlingQueryFn(boundQueryFn, getNextPageParam, initialPageParam, shouldFetchNextPage, reduce, crawlOptions) : boundQueryFn;
+    return {
+      ...standardOptions,
+      queryKey,
+      ...resolvedQueryFn !== void 0 && { queryFn: resolvedQueryFn },
+      ...select !== void 0 && { select },
+      [FACTORY_CONFIG]: cfg
+    };
+  };
+  factory.infinite = function(params, crawlOptions = {}) {
+    const queryKey = resolveKey([...resolveKey(namespace, void 0), "infinite"], params, crawlOptions);
+    const boundQueryFn = rawQueryFn ? (ctx) => rawQueryFn(params, ctx) : void 0;
+    if (hasInfiniteCrawling) {
+      const crawlingQueryFn = buildInfiniteCrawlingQueryFn(
+        boundQueryFn,
+        getNextPageParam,
+        shouldFetchNextPage,
+        reduce,
+        crawlOptions
+      );
+      const envelopeGetNextPageParam = (envelope) => envelope.nextPageParam;
+      const envelopeSelect = (data) => ({
+        ...data,
+        pages: data.pages.map((e) => select ? select(e.data) : e.data)
+      });
+      return {
+        ...standardOptions,
+        queryKey,
+        queryFn: crawlingQueryFn,
+        getNextPageParam: envelopeGetNextPageParam,
+        initialPageParam,
+        select: envelopeSelect,
+        ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
+        [FACTORY_CONFIG]: cfg
+      };
+    }
+    const infiniteGetNextPageParam = getNextPageParam && shouldFetchNextPage ? wrapGetNextPageParam(getNextPageParam, shouldFetchNextPage, crawlOptions, reduce) : getNextPageParam != null ? getNextPageParam : (() => void 0);
+    const infiniteSelect = select ? (data) => ({
+      ...data,
+      pages: data.pages.map(select)
+    }) : void 0;
+    return {
+      ...standardOptions,
+      queryKey,
+      ...boundQueryFn !== void 0 && { queryFn: boundQueryFn },
+      ...infiniteSelect !== void 0 && { select: infiniteSelect },
+      getNextPageParam: infiniteGetNextPageParam,
+      ...getPreviousPageParam !== void 0 && { getPreviousPageParam },
+      ...initialPageParam !== void 0 && { initialPageParam },
+      [FACTORY_CONFIG]: cfg
+    };
+  };
+  return factory;
+}
+function queryFactory(configOrParent, childConfig) {
+  var _a, _b, _c, _d, _e;
+  if (childConfig !== void 0 && typeof configOrParent === "function") {
+    const result = configOrParent();
+    const parentCfg = result == null ? void 0 : result[FACTORY_CONFIG];
+    if (!parentCfg) {
+      throw new Error("queryFactory: first argument must be a factory created by queryFactory()");
+    }
+    const hasNewQueryFn = childConfig.queryFn !== void 0;
+    const childNamespace = childConfig.queryKey ? Array.isArray(childConfig.queryKey) ? childConfig.queryKey : [childConfig.queryKey] : [];
+    const composedNamespace = [...parentCfg.queryKey, ...childNamespace];
+    let resolvedSelect;
+    if (hasNewQueryFn) {
+      resolvedSelect = childConfig.select;
+    } else if (childConfig.select && parentCfg.select) {
+      const p = parentCfg.select;
+      const c = childConfig.select;
+      resolvedSelect = (data) => c(p(data));
+    } else {
+      resolvedSelect = (_a = childConfig.select) != null ? _a : parentCfg.select;
+    }
+    const crawling = hasNewQueryFn ? {
+      getNextPageParam: childConfig.getNextPageParam,
+      getPreviousPageParam: childConfig.getPreviousPageParam,
+      initialPageParam: childConfig.initialPageParam,
+      shouldFetchNextPage: childConfig.shouldFetchNextPage,
+      reduce: childConfig.reduce
+    } : {
+      getNextPageParam: (_b = childConfig.getNextPageParam) != null ? _b : parentCfg.getNextPageParam,
+      getPreviousPageParam: (_c = childConfig.getPreviousPageParam) != null ? _c : parentCfg.getPreviousPageParam,
+      initialPageParam: childConfig.initialPageParam !== void 0 ? childConfig.initialPageParam : parentCfg.initialPageParam,
+      shouldFetchNextPage: (_d = childConfig.shouldFetchNextPage) != null ? _d : parentCfg.shouldFetchNextPage,
+      reduce: (_e = childConfig.reduce) != null ? _e : parentCfg.reduce
+    };
+    const {
+      queryKey: _k,
+      queryFn: _f,
+      select: _s,
+      getNextPageParam: _g,
+      getPreviousPageParam: _gp,
+      initialPageParam: _ip,
+      shouldFetchNextPage: _sfnp,
+      reduce: _c2,
+      ...childStandardOptions
+    } = childConfig;
+    return buildFactory({
+      queryKey: composedNamespace,
+      queryFn: hasNewQueryFn ? childConfig.queryFn : parentCfg.queryFn,
+      select: resolvedSelect,
+      ...crawling,
+      standardOptions: { ...parentCfg.standardOptions, ...childStandardOptions }
+    });
+  }
+  const {
+    queryKey,
+    queryFn,
+    select,
+    getNextPageParam,
+    getPreviousPageParam,
+    initialPageParam,
+    shouldFetchNextPage,
+    reduce,
+    ...standardOptions
+  } = configOrParent;
+  return buildFactory({
+    queryKey,
+    queryFn,
+    select,
+    getNextPageParam,
+    getPreviousPageParam,
+    initialPageParam,
+    shouldFetchNextPage,
+    reduce,
+    standardOptions
+  });
+}
+export {
+  queryFactory
+};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@robohall/react-query-factory",
+  "version": "1.0.0",
+  "description": "A factory abstraction for TanStack Query (React Query) with composable keys, crawling support, and automatic infinite query generation",
+  "author": "Robert Hall",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/roberth26/react-query-factory.git"
+  },
+  "bugs": "https://github.com/roberth26/react-query-factory/issues",
+  "homepage": "https://github.com/roberth26/react-query-factory#readme",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test",
+    "sandbox": "cd sandbox && npm run dev"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "react-query",
+    "tanstack-query",
+    "query-factory",
+    "typescript"
+  ]
+}