@spoosh/react 0.11.0 → 0.12.0

package/README.md

@@ -1,6 +1,6 @@
 # @spoosh/react
 
-React hooks for Spoosh - `useRead`, `useWrite`, and `useInfiniteRead`.
+React hooks for Spoosh - `useRead`, `useWrite`, and `usePages`.
 
 **[Documentation](https://spoosh.dev/docs/react)** · **Requirements:** TypeScript >= 5.0, React >= 18.0
 
@@ -23,7 +23,7 @@ const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
   cachePlugin({ staleTime: 5000 }),
 ]);
 
-export const { useRead, useWrite, useInfiniteRead } = create(spoosh);
+export const { useRead, useWrite, usePages } = create(spoosh);
 ```
 
 ### useRead
@@ -98,7 +98,7 @@ await updateUser.trigger({
 });
 ```
 
-### useInfiniteRead
+### usePages
 
 Bidirectional paginated data fetching with infinite scroll support.
 
@@ -106,7 +106,7 @@ Bidirectional paginated data fetching with infinite scroll support.
 function PostList() {
   const {
     data,
-    allResponses,
+    pages,
     loading,
     canFetchNext,
     canFetchPrev,
@@ -114,26 +114,26 @@ function PostList() {
     fetchPrev,
     fetchingNext,
     fetchingPrev,
-  } = useInfiniteRead(
+  } = usePages(
     (api) => api("posts").GET({ query: { page: 1 } }),
     {
       // Required: Check if next page exists
-      canFetchNext: ({ response }) => response?.meta.hasMore ?? false,
+      canFetchNext: ({ lastPage }) => lastPage?.data?.meta.hasMore ?? false,
 
       // Required: Build request for next page
-      nextPageRequest: ({ response, request }) => ({
-        query: { ...request.query, page: (response?.meta.page ?? 0) + 1 },
+      nextPageRequest: ({ lastPage }) => ({
+        query: { page: (lastPage?.data?.meta.page ?? 0) + 1 },
       }),
 
-      // Required: Merge all responses into items
-      merger: (allResponses) => allResponses.flatMap((r) => r.items),
+      // Required: Merge all pages into items
+      merger: (pages) => pages.flatMap((p) => p.data?.items ?? []),
 
       // Optional: Check if previous page exists
-      canFetchPrev: ({ response }) => (response?.meta.page ?? 1) > 1,
+      canFetchPrev: ({ firstPage }) => (firstPage?.data?.meta.page ?? 1) > 1,
 
       // Optional: Build request for previous page
-      prevPageRequest: ({ response, request }) => ({
-        query: { ...request.query, page: (response?.meta.page ?? 2) - 1 },
+      prevPageRequest: ({ firstPage }) => ({
+        query: { page: (firstPage?.data?.meta.page ?? 2) - 1 },
       }),
     }
   );
@@ -192,41 +192,58 @@ function PostList() {
 | `loading` | `boolean`              | True while mutation is in progress |
 | `abort`   | `() => void`           | Abort current request              |
 
-### useInfiniteRead(readFn, options)
+### usePages(readFn, options)
 
-| Option            | Type                         | Required | Description                     |
-| ----------------- | ---------------------------- | -------- | ------------------------------- |
-| `canFetchNext`    | `(ctx) => boolean`           | Yes      | Check if next page exists       |
-| `nextPageRequest` | `(ctx) => Partial<TRequest>` | Yes      | Build request for next page     |
-| `merger`          | `(allResponses) => TItem[]`  | Yes      | Merge all responses into items  |
-| `canFetchPrev`    | `(ctx) => boolean`           | No       | Check if previous page exists   |
-| `prevPageRequest` | `(ctx) => Partial<TRequest>` | No       | Build request for previous page |
-| `enabled`         | `boolean`                    | No       | Whether to fetch automatically  |
+| Option            | Type                         | Required | Description                                       |
+| ----------------- | ---------------------------- | -------- | ------------------------------------------------- |
+| `merger`          | `(pages) => TItem[]`         | Yes      | Merge all pages into items                        |
+| `canFetchNext`    | `(ctx) => boolean`           | No       | Check if next page exists. Default: `() => false` |
+| `nextPageRequest` | `(ctx) => Partial<TRequest>` | No       | Build request for next page                       |
+| `canFetchPrev`    | `(ctx) => boolean`           | No       | Check if previous page exists                     |
+| `prevPageRequest` | `(ctx) => Partial<TRequest>` | No       | Build request for previous page                   |
+| `enabled`         | `boolean`                    | No       | Whether to fetch automatically                    |
 
 **Context object passed to callbacks:**
 
 ```typescript
-type Context<TData, TRequest> = {
-  response: TData | undefined; // Latest response
-  allResponses: TData[]; // All fetched responses
-  request: TRequest; // Current request options
+// For canFetchNext and nextPageRequest
+type NextContext<TData, TRequest> = {
+  lastPage: InfinitePage<TData> | undefined;
+  pages: InfinitePage<TData>[];
+  request: TRequest;
+};
+
+// For canFetchPrev and prevPageRequest
+type PrevContext<TData, TRequest> = {
+  firstPage: InfinitePage<TData> | undefined;
+  pages: InfinitePage<TData>[];
+  request: TRequest;
+};
+
+// Each page in the pages array
+type InfinitePage<TData> = {
+  status: "pending" | "loading" | "success" | "error" | "stale";
+  data?: TData;
+  error?: TError;
+  meta?: TMeta;
+  input?: { query?; params?; body? };
 };
 ```
 
 **Returns:**
 
-| Property       | Type                   | Description                     |
-| -------------- | ---------------------- | ------------------------------- |
-| `data`         | `TItem[] \| undefined` | Merged items from all responses |
-| `allResponses` | `TData[] \| undefined` | Array of all raw responses      |
-| `loading`      | `boolean`              | True during initial load        |
-| `fetching`     | `boolean`              | True during any fetch           |
-| `fetchingNext` | `boolean`              | True while fetching next page   |
-| `fetchingPrev` | `boolean`              | True while fetching previous    |
-| `canFetchNext` | `boolean`              | Whether next page exists        |
-| `canFetchPrev` | `boolean`              | Whether previous page exists    |
-| `fetchNext`    | `() => Promise<void>`  | Fetch the next page             |
-| `fetchPrev`    | `() => Promise<void>`  | Fetch the previous page         |
-| `refetch`      | `() => Promise<void>`  | Refetch all pages               |
-| `abort`        | `() => void`           | Abort current request           |
-| `error`        | `TError \| undefined`  | Error if request failed         |
+| Property       | Type                          | Description                                     |
+| -------------- | ----------------------------- | ----------------------------------------------- |
+| `data`         | `TItem[] \| undefined`        | Merged items from all pages                     |
+| `pages`        | `InfinitePage<TData>[]`       | Array of all pages with status, data, and meta  |
+| `loading`      | `boolean`                     | True during initial load                        |
+| `fetching`     | `boolean`                     | True during any fetch                           |
+| `fetchingNext` | `boolean`                     | True while fetching next page                   |
+| `fetchingPrev` | `boolean`                     | True while fetching previous                    |
+| `canFetchNext` | `boolean`                     | Whether next page exists                        |
+| `canFetchPrev` | `boolean`                     | Whether previous page exists                    |
+| `fetchNext`    | `() => Promise<void>`         | Fetch the next page                             |
+| `fetchPrev`    | `() => Promise<void>`         | Fetch the previous page                         |
+| `trigger`      | `(options?) => Promise<void>` | Trigger fetch with optional new request options |
+| `abort`        | `() => void`                  | Abort current request                           |
+| `error`        | `TError \| undefined`         | Error if request failed                         |

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ReadClient, TagMode, SpooshResponse, SpooshPlugin, PluginTypeConfig, MergePluginResults, WriteSelectorClient, SpooshBody, QueueSelectorClient, QueueItem, QueueStats, StateManager, EventEmitter, PluginExecutor, PluginArray, ResolveTypes, MergePluginOptions, ResolverContext, ResolveResultTypes, MergePluginInstanceApi, SpooshOptions } from '@spoosh/core';
+import { ReadClient, TagMode, SpooshResponse, ExtractTriggerQuery as ExtractTriggerQuery$2, ExtractTriggerBody as ExtractTriggerBody$2, ExtractTriggerParams as ExtractTriggerParams$2, SpooshPlugin, PluginTypeConfig, MergePluginResults, WriteSelectorClient, SpooshBody, QueueSelectorClient, QueueItem, QueueStats, InfiniteRequestOptions, InfiniteNextContext, InfinitePage, InfinitePrevContext, StateManager, EventEmitter, PluginExecutor, PluginArray, ResolveTypes, MergePluginOptions, ResolverContext, ResolveResultTypes, MergePluginInstanceApi, SpooshOptions } from '@spoosh/core';
 
 type SuccessResponse<T> = Extract<T, {
     data: unknown;
@@ -81,26 +81,11 @@ type ResponseInputFields<TQuery, TBody, TParamNames extends string> = [
 ] extends [never, never, never] ? object : {
     input: ReadInputFields<TQuery, TBody, TParamNames>;
 };
-type TriggerAwaitedReturn$2<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse$2<T> = T extends {
+type TriggerAwaitedReturn$3<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse$3<T> = T extends {
     input: infer I;
 } ? I : never;
-type ExtractTriggerQuery$2<I> = I extends {
-    query: infer Q;
-} ? {
-    query?: Q;
-} : unknown;
-type ExtractTriggerBody$2<I> = I extends {
-    body: infer B;
-} ? {
-    body?: B;
-} : unknown;
-type ExtractTriggerParams$2<I> = I extends {
-    params: infer P;
-} ? {
-    params?: P;
-} : unknown;
-type TriggerOptions<T> = ExtractInputFromResponse$2<TriggerAwaitedReturn$2<T>> extends infer I ? [I] extends [never] ? {
+type TriggerOptions<T> = ExtractInputFromResponse$3<TriggerAwaitedReturn$3<T>> extends infer I ? [I] extends [never] ? {
     force?: boolean;
 } : ExtractTriggerQuery$2<I> & ExtractTriggerBody$2<I> & ExtractTriggerParams$2<I> & {
     /** Force refetch even if data is cached */
@@ -160,8 +145,8 @@ type InputFields<TQuery, TBody, TParamNames extends string> = OptionalQueryField
 type WriteResponseInputFields<TQuery, TBody, TParamNames extends string> = [TQuery, TBody, TParamNames] extends [never, never, never] ? object : {
     input: InputFields<TQuery, TBody, TParamNames> | undefined;
 };
-type TriggerAwaitedReturn$1<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse$1<T> = T extends {
+type TriggerAwaitedReturn$2<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse$2<T> = T extends {
     input: infer I;
 } ? I : never;
 type ExtractTriggerQuery$1<I> = I extends {
@@ -183,7 +168,7 @@ type ExtractTriggerParams$1<I> = I extends {
 } ? {
     params: P;
 } : unknown;
-type WriteTriggerInput<T> = ExtractInputFromResponse$1<TriggerAwaitedReturn$1<T>> extends infer I ? [I] extends [never] ? object : ExtractTriggerQuery$1<I> & ExtractTriggerBody$1<I> & ExtractTriggerParams$1<I> : object;
+type WriteTriggerInput<T> = ExtractInputFromResponse$2<TriggerAwaitedReturn$2<T>> extends infer I ? [I] extends [never] ? object : ExtractTriggerQuery$1<I> & ExtractTriggerBody$1<I> & ExtractTriggerParams$1<I> : object;
 /**
  * Result returned by `useWrite` hook.
  *
@@ -209,8 +194,8 @@ type BaseWriteResult<TData, TError, TOptions, TMeta = Record<string, unknown>> =
 type UseWriteResult<TData, TError, TOptions, TMeta, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = BaseWriteResult<TData, TError, TOptions, TMeta> & MergePluginResults<TPlugins>["write"];
 type WriteApiClient<TSchema, TDefaultError> = WriteSelectorClient<TSchema, TDefaultError>;
 
-type TriggerAwaitedReturn<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse<T> = T extends {
+type TriggerAwaitedReturn$1<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse$1<T> = T extends {
     input: infer I;
 } ? I : never;
 type ExtractTriggerQuery<I> = I extends {
@@ -236,7 +221,7 @@ type QueueTriggerBase = {
     /** Custom ID for this queue item. If not provided, one will be auto-generated. */
     id?: string;
 };
-type QueueTriggerInput<T> = ExtractInputFromResponse<TriggerAwaitedReturn<T>> extends infer I ? [I] extends [never] ? QueueTriggerBase : QueueTriggerBase & ExtractTriggerQuery<I> & ExtractTriggerBody<I> & ExtractTriggerParams<I> : QueueTriggerBase;
+type QueueTriggerInput<T> = ExtractInputFromResponse$1<TriggerAwaitedReturn$1<T>> extends infer I ? [I] extends [never] ? QueueTriggerBase : QueueTriggerBase & ExtractTriggerQuery<I> & ExtractTriggerBody<I> & ExtractTriggerParams<I> : QueueTriggerBase;
 /**
  * Options for useQueue hook.
  */
@@ -277,41 +262,25 @@ type UseQueueResult<TData, TError, TTriggerInput, TMeta = object> = {
 type QueueApiClient<TSchema, TDefaultError> = QueueSelectorClient<TSchema, TDefaultError>;
 
 type TagModeInArray = "all" | "self";
-type AnyInfiniteRequestOptions = {
-    query?: Record<string, unknown>;
-    params?: Record<string, string | number>;
-    body?: unknown;
-};
-/**
- * Context passed to `canFetchNext` and `nextPageRequest` callbacks.
- */
-type InfiniteNextContext<TData, TRequest> = {
-    /** The latest fetched response data */
-    response: TData | undefined;
-    /** All responses fetched so far */
-    allResponses: TData[];
-    /** The current request options (query, params, body) */
-    request: TRequest;
-};
-/**
- * Context passed to `canFetchPrev` and `prevPageRequest` callbacks.
- */
-type InfinitePrevContext<TData, TRequest> = {
-    /** The latest fetched response data */
-    response: TData | undefined;
-    /** All responses fetched so far */
-    allResponses: TData[];
-    /** The current request options (query, params, body) */
-    request: TRequest;
+type TriggerAwaitedReturn<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse<T> = T extends {
+    input: infer I;
+} ? I : never;
+type BaseTriggerOptions = {
+    /** Bypass cache and force refetch. Default: true */
+    force?: boolean;
 };
+type PagesTriggerOptions<TReadFn> = ExtractInputFromResponse<TriggerAwaitedReturn<TReadFn>> extends infer I ? [I] extends [never] ? BaseTriggerOptions : ExtractTriggerQuery$2<I> & ExtractTriggerBody$2<I> & ExtractTriggerParams$2<I> & BaseTriggerOptions : BaseTriggerOptions;
 /**
- * Options for `useInfiniteRead` hook.
+ * Options for `usePages` hook.
  *
  * @template TData - The response data type for each page
  * @template TItem - The item type after merging all responses
+ * @template TError - The error type
  * @template TRequest - The request options type (query, params, body)
+ * @template TMeta - Plugin metadata type
  */
-type BaseInfiniteReadOptions<TData, TItem, TRequest = AnyInfiniteRequestOptions> = {
+type BasePagesOptions<TData, TItem, TError = unknown, TRequest = InfiniteRequestOptions, TMeta = Record<string, unknown>> = {
     /** Whether to fetch automatically on mount. Default: true */
     enabled?: boolean;
     /**
@@ -322,30 +291,66 @@ type BaseInfiniteReadOptions<TData, TItem, TRequest = AnyInfiniteRequestOptions>
      *   - 'none' should only be used as string (use `tags: 'none'` not in array)
      */
     tags?: TagMode | (TagModeInArray | (string & {}))[];
-    /** Callback to determine if there's a next page to fetch */
-    canFetchNext: (ctx: InfiniteNextContext<TData, TRequest>) => boolean;
-    /** Callback to build the request options for the next page */
-    nextPageRequest: (ctx: InfiniteNextContext<TData, TRequest>) => Partial<TRequest>;
-    /** Callback to merge all responses into a single array of items */
-    merger: (allResponses: TData[]) => TItem[];
-    /** Callback to determine if there's a previous page to fetch */
-    canFetchPrev?: (ctx: InfinitePrevContext<TData, TRequest>) => boolean;
-    /** Callback to build the request options for the previous page */
-    prevPageRequest?: (ctx: InfinitePrevContext<TData, TRequest>) => Partial<TRequest>;
+    /**
+     * Callback to determine if there's a next page to fetch.
+     * Receives the last page to check for pagination indicators.
+     * Default: `() => false` (no next page fetching)
+     *
+     * @example
+     * ```ts
+     * canFetchNext: ({ lastPage }) => lastPage?.data?.nextCursor != null
+     * ```
+     */
+    canFetchNext?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => boolean;
+    /**
+     * Callback to build the request options for the next page.
+     * Return only the fields that change - they will be **merged** with the initial request.
+     * Default: `() => ({})` (no changes to request)
+     *
+     * @example
+     * ```ts
+     * // Initial: { query: { cursor: 0, limit: 10 } }
+     * // Only return cursor - limit is preserved automatically
+     * nextPageRequest: ({ lastPage }) => ({
+     *   query: { cursor: lastPage?.data?.nextCursor }
+     * })
+     * ```
+     */
+    nextPageRequest?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
+    /**
+     * Callback to merge all pages into a single array of items.
+     *
+     * @example
+     * ```ts
+     * merger: (pages) => pages.flatMap(p => p.data?.items ?? [])
+     * ```
+     */
+    merger: (pages: InfinitePage<TData, TError, TMeta>[]) => TItem[];
+    /**
+     * Callback to determine if there's a previous page to fetch.
+     * Receives the first page to check for pagination indicators.
+     */
+    canFetchPrev?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => boolean;
+    /**
+     * Callback to build the request options for the previous page.
+     * Return only the fields that change - they will be **merged** with the initial request.
+     */
+    prevPageRequest?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
 };
 /**
- * Result returned by `useInfiniteRead` hook.
+ * Result returned by `usePages` hook.
  *
  * @template TData - The response data type for each page
  * @template TError - The error type
  * @template TItem - The item type after merging all responses
  * @template TPluginResult - Plugin-provided result fields
+ * @template TTriggerOptions - Options that can be passed to trigger()
  */
-type BaseInfiniteReadResult<TData, TError, TItem, TPluginResult = Record<string, unknown>> = {
-    /** Merged items from all fetched responses */
+type BasePagesResult<TData, TError, TItem, TPluginResult = Record<string, unknown>, TTriggerOptions = object> = {
+    /** Merged items from all fetched pages */
     data: TItem[] | undefined;
-    /** Array of all raw response data */
-    allResponses: TData[] | undefined;
+    /** Array of all pages with status, data, error, and meta per page */
+    pages: InfinitePage<TData, TError, TPluginResult>[];
     /** True during the initial load (no data yet) */
     loading: boolean;
     /** True during any fetch operation */
@@ -358,21 +363,19 @@ type BaseInfiniteReadResult<TData, TError, TItem, TPluginResult = Record<string,
     canFetchNext: boolean;
     /** Whether there's a previous page available to fetch */
     canFetchPrev: boolean;
-    /** Plugin-provided metadata */
-    meta: TPluginResult;
     /** Fetch the next page */
     fetchNext: () => Promise<void>;
     /** Fetch the previous page */
     fetchPrev: () => Promise<void>;
-    /** Trigger refetch of all pages from the beginning */
-    trigger: () => Promise<void>;
+    /** Trigger refetch of all pages from the beginning, optionally with new request options */
+    trigger: (options?: TTriggerOptions) => Promise<void>;
     /** Abort the current fetch operation */
     abort: () => void;
     /** Error from the last failed request */
     error: TError | undefined;
 };
-type UseInfiniteReadResult<TData, TError, TItem, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = BaseInfiniteReadResult<TData, TError, TItem> & MergePluginResults<TPlugins>["read"];
-type InfiniteReadApiClient<TSchema, TDefaultError> = ReadClient<TSchema, TDefaultError>;
+type UsePagesResult<TData, TError, TItem, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TTriggerOptions = object> = BasePagesResult<TData, TError, TItem, MergePluginResults<TPlugins>["read"], TTriggerOptions>;
+type PagesApiClient<TSchema, TDefaultError> = ReadClient<TSchema, TDefaultError>;
 
 type InferError<T, TDefaultError> = [T] extends [unknown] ? TDefaultError : T;
 type WriteResolverContext<TSchema, TMethod, TDefaultError> = ResolverContext<TSchema, ExtractMethodData<TMethod>, InferError<ExtractMethodError<TMethod>, TDefaultError>, ExtractMethodQuery<TMethod>, ExtractMethodBody<TMethod>, ExtractResponseParamNames<TMethod> extends never ? never : Record<ExtractResponseParamNames<TMethod>, string | number>>;
@@ -391,17 +394,9 @@ type UseWriteFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
 type UseQueueFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     <TQueueFn extends (api: QueueApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>>(queueFn: TQueueFn, queueOptions?: ResolvedQueueOptions<TSchema, TPlugins, TQueueFn, TDefaultError> & UseQueueOptions): UseQueueResult<ExtractMethodData<TQueueFn>, InferError<ExtractMethodError<TQueueFn>, TDefaultError>, QueueTriggerInput<TQueueFn> & ResolvedQueueTriggerOptions<TSchema, TPlugins, TQueueFn, TDefaultError>, ResolveResultTypes<MergePluginResults<TPlugins>["queue"], ResolvedQueueOptions<TSchema, TPlugins, TQueueFn, TDefaultError> & UseQueueOptions>>;
 };
-type InfiniteReadResolverContext<TSchema, TData, TError, TRequest> = ResolverContext<TSchema, TData, TError, TRequest extends {
-    query: infer Q;
-} ? Q : never, TRequest extends {
-    body: infer B;
-} ? B : never, TRequest extends {
-    params: infer P;
-} ? P : never>;
-type ResolvedInfiniteReadOptions<TSchema, TPlugins extends PluginArray, TData, TError, TRequest> = ResolveTypes<MergePluginOptions<TPlugins>["infiniteRead"], InfiniteReadResolverContext<TSchema, TData, TError, TRequest>>;
-type UseInfiniteReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TData, TItem, TError = TDefaultError, TRequest extends AnyInfiniteRequestOptions = AnyInfiniteRequestOptions>(readFn: (api: InfiniteReadApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<TData, TError>>, readOptions: BaseInfiniteReadOptions<TData, TItem, TRequest> & ResolvedInfiniteReadOptions<TSchema, TPlugins, TData, TError, TRequest>) => BaseInfiniteReadResult<TData, TError, TItem, MergePluginResults<TPlugins>["read"]>;
+type UsePagesFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TReadFn extends (api: PagesApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions, TItem = unknown>(readFn: TReadFn, readOptions: BasePagesOptions<ExtractMethodData<TReadFn>, TItem, InferError<ExtractMethodError<TReadFn>, TDefaultError>, TRequest, MergePluginResults<TPlugins>["read"]> & ResolveTypes<MergePluginOptions<TPlugins>["pages"], ResolverContext<TSchema, ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>>>) => BasePagesResult<ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, TItem, MergePluginResults<TPlugins>["read"], PagesTriggerOptions<TReadFn>>;
 /**
- * Spoosh React hooks interface containing useRead, useWrite, and useInfiniteRead.
+ * Spoosh React hooks interface containing useRead, useWrite, and usePages.
  *
  * @template TDefaultError - The default error type
  * @template TSchema - The API schema type
@@ -448,21 +443,21 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      *
      * @param readFn - Function that selects the API endpoint to call
      * @param readOptions - Configuration including `canFetchNext`, `nextPageRequest`, `merger`, and optional `canFetchPrev`/`prevPageRequest`
-     * @returns Object containing `data`, `allResponses`, `fetchNext`, `fetchPrev`, `canFetchNext`, `canFetchPrev`, `loading`, `fetching`, and pagination states
+     * @returns Object containing `data`, `pages`, `fetchNext`, `fetchPrev`, `canFetchNext`, `canFetchPrev`, `loading`, `fetching`, and pagination states
      *
      * @example
      * ```tsx
-     * const { data, fetchNext, canFetchNext, loading } = useInfiniteRead(
+     * const { data, fetchNext, canFetchNext, loading } = usePages(
      *   (api) => api("posts").GET(),
      *   {
-     *     canFetchNext: ({ response }) => !!response?.nextCursor,
-     *     nextPageRequest: ({ response }) => ({ query: { cursor: response?.nextCursor } }),
-     *     merger: (responses) => responses.flatMap(r => r.items)
+     *     canFetchNext: ({ lastPage }) => !!lastPage?.data?.nextCursor,
+     *     nextPageRequest: ({ lastPage }) => ({ query: { cursor: lastPage?.data?.nextCursor } }),
+     *     merger: (pages) => pages.flatMap(p => p.data?.items ?? [])
      *   }
      * );
      * ```
      */
-    useInfiniteRead: UseInfiniteReadFn<TDefaultError, TSchema, TPlugins>;
+    usePages: UsePagesFn<TDefaultError, TSchema, TPlugins>;
     /**
      * React hook for queued operations with concurrency control.
      *
@@ -505,18 +500,18 @@ type SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins> = {
 };
 
 /**
- * Creates React hooks (useRead, useWrite, useInfiniteRead) from a Spoosh instance.
+ * Creates React hooks (useRead, useWrite, usePages) from a Spoosh instance.
  *
  * @template TSchema - The API schema type
  * @template TDefaultError - The default error type
  * @template TPlugins - The plugins array type
  * @template TApi - The API type
  * @param instance - The Spoosh instance containing api, stateManager, eventEmitter, and pluginExecutor
- * @returns An object containing useRead, useWrite, useInfiniteRead hooks and plugin instance APIs
+ * @returns An object containing useRead, useWrite, usePages hooks and plugin instance APIs
  *
  * @example
  * ```ts
- * const { useRead, useWrite, useInfiniteRead } = create(spooshInstance);
+ * const { useRead, useWrite, usePages } = create(spooshInstance);
  *
  * function MyComponent() {
  *   const { data, loading } = useRead((api) => api("posts").GET());
@@ -532,4 +527,4 @@ type PluginHooksConfig<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[
     plugins: TPlugins;
 };
 
-export { type AnyInfiniteRequestOptions, type BaseInfiniteReadOptions, type BaseInfiniteReadResult, type BaseReadOptions, type BaseReadResult, type BaseWriteResult, type ExtractCoreMethodOptions, type ExtractMethodBody, type ExtractMethodData, type ExtractMethodError, type ExtractMethodOptions, type ExtractMethodQuery, type ExtractResponseBody, type ExtractResponseParamNames, type ExtractResponseQuery, type ExtractResponseRequestOptions, type InfiniteNextContext, type InfinitePrevContext, type InfiniteReadApiClient, type PluginHooksConfig, type QueueApiClient, type QueueTriggerInput, type ReadApiClient, type ResponseInputFields, type SpooshReactHooks, type TriggerOptions, type UseInfiniteReadResult, type UseQueueOptions, type UseQueueResult, type UseReadResult, type UseWriteResult, type WriteApiClient, type WriteResponseInputFields, create };
+export { type BasePagesOptions, type BasePagesResult, type BaseReadOptions, type BaseReadResult, type BaseWriteResult, type ExtractCoreMethodOptions, type ExtractMethodBody, type ExtractMethodData, type ExtractMethodError, type ExtractMethodOptions, type ExtractMethodQuery, type ExtractResponseBody, type ExtractResponseParamNames, type ExtractResponseQuery, type ExtractResponseRequestOptions, type PagesApiClient, type PagesTriggerOptions, type PluginHooksConfig, type QueueApiClient, type QueueTriggerInput, type ReadApiClient, type ResponseInputFields, type SpooshReactHooks, type TriggerOptions, type UsePagesResult, type UseQueueOptions, type UseQueueResult, type UseReadResult, type UseWriteResult, type WriteApiClient, type WriteResponseInputFields, create };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ReadClient, TagMode, SpooshResponse, SpooshPlugin, PluginTypeConfig, MergePluginResults, WriteSelectorClient, SpooshBody, QueueSelectorClient, QueueItem, QueueStats, StateManager, EventEmitter, PluginExecutor, PluginArray, ResolveTypes, MergePluginOptions, ResolverContext, ResolveResultTypes, MergePluginInstanceApi, SpooshOptions } from '@spoosh/core';
+import { ReadClient, TagMode, SpooshResponse, ExtractTriggerQuery as ExtractTriggerQuery$2, ExtractTriggerBody as ExtractTriggerBody$2, ExtractTriggerParams as ExtractTriggerParams$2, SpooshPlugin, PluginTypeConfig, MergePluginResults, WriteSelectorClient, SpooshBody, QueueSelectorClient, QueueItem, QueueStats, InfiniteRequestOptions, InfiniteNextContext, InfinitePage, InfinitePrevContext, StateManager, EventEmitter, PluginExecutor, PluginArray, ResolveTypes, MergePluginOptions, ResolverContext, ResolveResultTypes, MergePluginInstanceApi, SpooshOptions } from '@spoosh/core';
 
 type SuccessResponse<T> = Extract<T, {
     data: unknown;
@@ -81,26 +81,11 @@ type ResponseInputFields<TQuery, TBody, TParamNames extends string> = [
 ] extends [never, never, never] ? object : {
     input: ReadInputFields<TQuery, TBody, TParamNames>;
 };
-type TriggerAwaitedReturn$2<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse$2<T> = T extends {
+type TriggerAwaitedReturn$3<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse$3<T> = T extends {
     input: infer I;
 } ? I : never;
-type ExtractTriggerQuery$2<I> = I extends {
-    query: infer Q;
-} ? {
-    query?: Q;
-} : unknown;
-type ExtractTriggerBody$2<I> = I extends {
-    body: infer B;
-} ? {
-    body?: B;
-} : unknown;
-type ExtractTriggerParams$2<I> = I extends {
-    params: infer P;
-} ? {
-    params?: P;
-} : unknown;
-type TriggerOptions<T> = ExtractInputFromResponse$2<TriggerAwaitedReturn$2<T>> extends infer I ? [I] extends [never] ? {
+type TriggerOptions<T> = ExtractInputFromResponse$3<TriggerAwaitedReturn$3<T>> extends infer I ? [I] extends [never] ? {
     force?: boolean;
 } : ExtractTriggerQuery$2<I> & ExtractTriggerBody$2<I> & ExtractTriggerParams$2<I> & {
     /** Force refetch even if data is cached */
@@ -160,8 +145,8 @@ type InputFields<TQuery, TBody, TParamNames extends string> = OptionalQueryField
 type WriteResponseInputFields<TQuery, TBody, TParamNames extends string> = [TQuery, TBody, TParamNames] extends [never, never, never] ? object : {
     input: InputFields<TQuery, TBody, TParamNames> | undefined;
 };
-type TriggerAwaitedReturn$1<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse$1<T> = T extends {
+type TriggerAwaitedReturn$2<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse$2<T> = T extends {
     input: infer I;
 } ? I : never;
 type ExtractTriggerQuery$1<I> = I extends {
@@ -183,7 +168,7 @@ type ExtractTriggerParams$1<I> = I extends {
 } ? {
     params: P;
 } : unknown;
-type WriteTriggerInput<T> = ExtractInputFromResponse$1<TriggerAwaitedReturn$1<T>> extends infer I ? [I] extends [never] ? object : ExtractTriggerQuery$1<I> & ExtractTriggerBody$1<I> & ExtractTriggerParams$1<I> : object;
+type WriteTriggerInput<T> = ExtractInputFromResponse$2<TriggerAwaitedReturn$2<T>> extends infer I ? [I] extends [never] ? object : ExtractTriggerQuery$1<I> & ExtractTriggerBody$1<I> & ExtractTriggerParams$1<I> : object;
 /**
  * Result returned by `useWrite` hook.
  *
@@ -209,8 +194,8 @@ type BaseWriteResult<TData, TError, TOptions, TMeta = Record<string, unknown>> =
 type UseWriteResult<TData, TError, TOptions, TMeta, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = BaseWriteResult<TData, TError, TOptions, TMeta> & MergePluginResults<TPlugins>["write"];
 type WriteApiClient<TSchema, TDefaultError> = WriteSelectorClient<TSchema, TDefaultError>;
 
-type TriggerAwaitedReturn<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse<T> = T extends {
+type TriggerAwaitedReturn$1<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse$1<T> = T extends {
     input: infer I;
 } ? I : never;
 type ExtractTriggerQuery<I> = I extends {
@@ -236,7 +221,7 @@ type QueueTriggerBase = {
     /** Custom ID for this queue item. If not provided, one will be auto-generated. */
     id?: string;
 };
-type QueueTriggerInput<T> = ExtractInputFromResponse<TriggerAwaitedReturn<T>> extends infer I ? [I] extends [never] ? QueueTriggerBase : QueueTriggerBase & ExtractTriggerQuery<I> & ExtractTriggerBody<I> & ExtractTriggerParams<I> : QueueTriggerBase;
+type QueueTriggerInput<T> = ExtractInputFromResponse$1<TriggerAwaitedReturn$1<T>> extends infer I ? [I] extends [never] ? QueueTriggerBase : QueueTriggerBase & ExtractTriggerQuery<I> & ExtractTriggerBody<I> & ExtractTriggerParams<I> : QueueTriggerBase;
 /**
  * Options for useQueue hook.
  */
@@ -277,41 +262,25 @@ type UseQueueResult<TData, TError, TTriggerInput, TMeta = object> = {
 type QueueApiClient<TSchema, TDefaultError> = QueueSelectorClient<TSchema, TDefaultError>;
 
 type TagModeInArray = "all" | "self";
-type AnyInfiniteRequestOptions = {
-    query?: Record<string, unknown>;
-    params?: Record<string, string | number>;
-    body?: unknown;
-};
-/**
- * Context passed to `canFetchNext` and `nextPageRequest` callbacks.
- */
-type InfiniteNextContext<TData, TRequest> = {
-    /** The latest fetched response data */
-    response: TData | undefined;
-    /** All responses fetched so far */
-    allResponses: TData[];
-    /** The current request options (query, params, body) */
-    request: TRequest;
-};
-/**
- * Context passed to `canFetchPrev` and `prevPageRequest` callbacks.
- */
-type InfinitePrevContext<TData, TRequest> = {
-    /** The latest fetched response data */
-    response: TData | undefined;
-    /** All responses fetched so far */
-    allResponses: TData[];
-    /** The current request options (query, params, body) */
-    request: TRequest;
+type TriggerAwaitedReturn<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse<T> = T extends {
+    input: infer I;
+} ? I : never;
+type BaseTriggerOptions = {
+    /** Bypass cache and force refetch. Default: true */
+    force?: boolean;
 };
+type PagesTriggerOptions<TReadFn> = ExtractInputFromResponse<TriggerAwaitedReturn<TReadFn>> extends infer I ? [I] extends [never] ? BaseTriggerOptions : ExtractTriggerQuery$2<I> & ExtractTriggerBody$2<I> & ExtractTriggerParams$2<I> & BaseTriggerOptions : BaseTriggerOptions;
 /**
- * Options for `useInfiniteRead` hook.
+ * Options for `usePages` hook.
  *
  * @template TData - The response data type for each page
  * @template TItem - The item type after merging all responses
+ * @template TError - The error type
  * @template TRequest - The request options type (query, params, body)
+ * @template TMeta - Plugin metadata type
  */
-type BaseInfiniteReadOptions<TData, TItem, TRequest = AnyInfiniteRequestOptions> = {
+type BasePagesOptions<TData, TItem, TError = unknown, TRequest = InfiniteRequestOptions, TMeta = Record<string, unknown>> = {
     /** Whether to fetch automatically on mount. Default: true */
     enabled?: boolean;
     /**
@@ -322,30 +291,66 @@ type BaseInfiniteReadOptions<TData, TItem, TRequest = AnyInfiniteRequestOptions>
      *   - 'none' should only be used as string (use `tags: 'none'` not in array)
      */
     tags?: TagMode | (TagModeInArray | (string & {}))[];
-    /** Callback to determine if there's a next page to fetch */
-    canFetchNext: (ctx: InfiniteNextContext<TData, TRequest>) => boolean;
-    /** Callback to build the request options for the next page */
-    nextPageRequest: (ctx: InfiniteNextContext<TData, TRequest>) => Partial<TRequest>;
-    /** Callback to merge all responses into a single array of items */
-    merger: (allResponses: TData[]) => TItem[];
-    /** Callback to determine if there's a previous page to fetch */
-    canFetchPrev?: (ctx: InfinitePrevContext<TData, TRequest>) => boolean;
-    /** Callback to build the request options for the previous page */
-    prevPageRequest?: (ctx: InfinitePrevContext<TData, TRequest>) => Partial<TRequest>;
+    /**
+     * Callback to determine if there's a next page to fetch.
+     * Receives the last page to check for pagination indicators.
+     * Default: `() => false` (no next page fetching)
+     *
+     * @example
+     * ```ts
+     * canFetchNext: ({ lastPage }) => lastPage?.data?.nextCursor != null
+     * ```
+     */
+    canFetchNext?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => boolean;
+    /**
+     * Callback to build the request options for the next page.
+     * Return only the fields that change - they will be **merged** with the initial request.
+     * Default: `() => ({})` (no changes to request)
+     *
+     * @example
+     * ```ts
+     * // Initial: { query: { cursor: 0, limit: 10 } }
+     * // Only return cursor - limit is preserved automatically
+     * nextPageRequest: ({ lastPage }) => ({
+     *   query: { cursor: lastPage?.data?.nextCursor }
+     * })
+     * ```
+     */
+    nextPageRequest?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
+    /**
+     * Callback to merge all pages into a single array of items.
+     *
+     * @example
+     * ```ts
+     * merger: (pages) => pages.flatMap(p => p.data?.items ?? [])
+     * ```
+     */
+    merger: (pages: InfinitePage<TData, TError, TMeta>[]) => TItem[];
+    /**
+     * Callback to determine if there's a previous page to fetch.
+     * Receives the first page to check for pagination indicators.
+     */
+    canFetchPrev?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => boolean;
+    /**
+     * Callback to build the request options for the previous page.
+     * Return only the fields that change - they will be **merged** with the initial request.
+     */
+    prevPageRequest?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
 };
 /**
- * Result returned by `useInfiniteRead` hook.
+ * Result returned by `usePages` hook.
  *
  * @template TData - The response data type for each page
  * @template TError - The error type
  * @template TItem - The item type after merging all responses
  * @template TPluginResult - Plugin-provided result fields
+ * @template TTriggerOptions - Options that can be passed to trigger()
  */
-type BaseInfiniteReadResult<TData, TError, TItem, TPluginResult = Record<string, unknown>> = {
-    /** Merged items from all fetched responses */
+type BasePagesResult<TData, TError, TItem, TPluginResult = Record<string, unknown>, TTriggerOptions = object> = {
+    /** Merged items from all fetched pages */
     data: TItem[] | undefined;
-    /** Array of all raw response data */
-    allResponses: TData[] | undefined;
+    /** Array of all pages with status, data, error, and meta per page */
+    pages: InfinitePage<TData, TError, TPluginResult>[];
     /** True during the initial load (no data yet) */
     loading: boolean;
     /** True during any fetch operation */
@@ -358,21 +363,19 @@ type BaseInfiniteReadResult<TData, TError, TItem, TPluginResult = Record<string,
     canFetchNext: boolean;
     /** Whether there's a previous page available to fetch */
     canFetchPrev: boolean;
-    /** Plugin-provided metadata */
-    meta: TPluginResult;
     /** Fetch the next page */
     fetchNext: () => Promise<void>;
     /** Fetch the previous page */
     fetchPrev: () => Promise<void>;
-    /** Trigger refetch of all pages from the beginning */
-    trigger: () => Promise<void>;
+    /** Trigger refetch of all pages from the beginning, optionally with new request options */
+    trigger: (options?: TTriggerOptions) => Promise<void>;
     /** Abort the current fetch operation */
     abort: () => void;
     /** Error from the last failed request */
     error: TError | undefined;
 };
-type UseInfiniteReadResult<TData, TError, TItem, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = BaseInfiniteReadResult<TData, TError, TItem> & MergePluginResults<TPlugins>["read"];
-type InfiniteReadApiClient<TSchema, TDefaultError> = ReadClient<TSchema, TDefaultError>;
+type UsePagesResult<TData, TError, TItem, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TTriggerOptions = object> = BasePagesResult<TData, TError, TItem, MergePluginResults<TPlugins>["read"], TTriggerOptions>;
+type PagesApiClient<TSchema, TDefaultError> = ReadClient<TSchema, TDefaultError>;
 
 type InferError<T, TDefaultError> = [T] extends [unknown] ? TDefaultError : T;
 type WriteResolverContext<TSchema, TMethod, TDefaultError> = ResolverContext<TSchema, ExtractMethodData<TMethod>, InferError<ExtractMethodError<TMethod>, TDefaultError>, ExtractMethodQuery<TMethod>, ExtractMethodBody<TMethod>, ExtractResponseParamNames<TMethod> extends never ? never : Record<ExtractResponseParamNames<TMethod>, string | number>>;
@@ -391,17 +394,9 @@ type UseWriteFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
 type UseQueueFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     <TQueueFn extends (api: QueueApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>>(queueFn: TQueueFn, queueOptions?: ResolvedQueueOptions<TSchema, TPlugins, TQueueFn, TDefaultError> & UseQueueOptions): UseQueueResult<ExtractMethodData<TQueueFn>, InferError<ExtractMethodError<TQueueFn>, TDefaultError>, QueueTriggerInput<TQueueFn> & ResolvedQueueTriggerOptions<TSchema, TPlugins, TQueueFn, TDefaultError>, ResolveResultTypes<MergePluginResults<TPlugins>["queue"], ResolvedQueueOptions<TSchema, TPlugins, TQueueFn, TDefaultError> & UseQueueOptions>>;
 };
-type InfiniteReadResolverContext<TSchema, TData, TError, TRequest> = ResolverContext<TSchema, TData, TError, TRequest extends {
-    query: infer Q;
-} ? Q : never, TRequest extends {
-    body: infer B;
-} ? B : never, TRequest extends {
-    params: infer P;
-} ? P : never>;
-type ResolvedInfiniteReadOptions<TSchema, TPlugins extends PluginArray, TData, TError, TRequest> = ResolveTypes<MergePluginOptions<TPlugins>["infiniteRead"], InfiniteReadResolverContext<TSchema, TData, TError, TRequest>>;
-type UseInfiniteReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TData, TItem, TError = TDefaultError, TRequest extends AnyInfiniteRequestOptions = AnyInfiniteRequestOptions>(readFn: (api: InfiniteReadApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<TData, TError>>, readOptions: BaseInfiniteReadOptions<TData, TItem, TRequest> & ResolvedInfiniteReadOptions<TSchema, TPlugins, TData, TError, TRequest>) => BaseInfiniteReadResult<TData, TError, TItem, MergePluginResults<TPlugins>["read"]>;
+type UsePagesFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TReadFn extends (api: PagesApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions, TItem = unknown>(readFn: TReadFn, readOptions: BasePagesOptions<ExtractMethodData<TReadFn>, TItem, InferError<ExtractMethodError<TReadFn>, TDefaultError>, TRequest, MergePluginResults<TPlugins>["read"]> & ResolveTypes<MergePluginOptions<TPlugins>["pages"], ResolverContext<TSchema, ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>>>) => BasePagesResult<ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, TItem, MergePluginResults<TPlugins>["read"], PagesTriggerOptions<TReadFn>>;
 /**
- * Spoosh React hooks interface containing useRead, useWrite, and useInfiniteRead.
+ * Spoosh React hooks interface containing useRead, useWrite, and usePages.
  *
  * @template TDefaultError - The default error type
  * @template TSchema - The API schema type
@@ -448,21 +443,21 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      *
      * @param readFn - Function that selects the API endpoint to call
      * @param readOptions - Configuration including `canFetchNext`, `nextPageRequest`, `merger`, and optional `canFetchPrev`/`prevPageRequest`
-     * @returns Object containing `data`, `allResponses`, `fetchNext`, `fetchPrev`, `canFetchNext`, `canFetchPrev`, `loading`, `fetching`, and pagination states
+     * @returns Object containing `data`, `pages`, `fetchNext`, `fetchPrev`, `canFetchNext`, `canFetchPrev`, `loading`, `fetching`, and pagination states
      *
      * @example
      * ```tsx
-     * const { data, fetchNext, canFetchNext, loading } = useInfiniteRead(
+     * const { data, fetchNext, canFetchNext, loading } = usePages(
      *   (api) => api("posts").GET(),
      *   {
-     *     canFetchNext: ({ response }) => !!response?.nextCursor,
-     *     nextPageRequest: ({ response }) => ({ query: { cursor: response?.nextCursor } }),
-     *     merger: (responses) => responses.flatMap(r => r.items)
+     *     canFetchNext: ({ lastPage }) => !!lastPage?.data?.nextCursor,
+     *     nextPageRequest: ({ lastPage }) => ({ query: { cursor: lastPage?.data?.nextCursor } }),
+     *     merger: (pages) => pages.flatMap(p => p.data?.items ?? [])
      *   }
      * );
      * ```
      */
-    useInfiniteRead: UseInfiniteReadFn<TDefaultError, TSchema, TPlugins>;
+    usePages: UsePagesFn<TDefaultError, TSchema, TPlugins>;
     /**
      * React hook for queued operations with concurrency control.
      *
@@ -505,18 +500,18 @@ type SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins> = {
 };
 
 /**
- * Creates React hooks (useRead, useWrite, useInfiniteRead) from a Spoosh instance.
+ * Creates React hooks (useRead, useWrite, usePages) from a Spoosh instance.
  *
  * @template TSchema - The API schema type
  * @template TDefaultError - The default error type
  * @template TPlugins - The plugins array type
  * @template TApi - The API type
  * @param instance - The Spoosh instance containing api, stateManager, eventEmitter, and pluginExecutor
- * @returns An object containing useRead, useWrite, useInfiniteRead hooks and plugin instance APIs
+ * @returns An object containing useRead, useWrite, usePages hooks and plugin instance APIs
  *
  * @example
  * ```ts
- * const { useRead, useWrite, useInfiniteRead } = create(spooshInstance);
+ * const { useRead, useWrite, usePages } = create(spooshInstance);
  *
  * function MyComponent() {
  *   const { data, loading } = useRead((api) => api("posts").GET());
@@ -532,4 +527,4 @@ type PluginHooksConfig<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[
     plugins: TPlugins;
 };
 
-export { type AnyInfiniteRequestOptions, type BaseInfiniteReadOptions, type BaseInfiniteReadResult, type BaseReadOptions, type BaseReadResult, type BaseWriteResult, type ExtractCoreMethodOptions, type ExtractMethodBody, type ExtractMethodData, type ExtractMethodError, type ExtractMethodOptions, type ExtractMethodQuery, type ExtractResponseBody, type ExtractResponseParamNames, type ExtractResponseQuery, type ExtractResponseRequestOptions, type InfiniteNextContext, type InfinitePrevContext, type InfiniteReadApiClient, type PluginHooksConfig, type QueueApiClient, type QueueTriggerInput, type ReadApiClient, type ResponseInputFields, type SpooshReactHooks, type TriggerOptions, type UseInfiniteReadResult, type UseQueueOptions, type UseQueueResult, type UseReadResult, type UseWriteResult, type WriteApiClient, type WriteResponseInputFields, create };
+export { type BasePagesOptions, type BasePagesResult, type BaseReadOptions, type BaseReadResult, type BaseWriteResult, type ExtractCoreMethodOptions, type ExtractMethodBody, type ExtractMethodData, type ExtractMethodError, type ExtractMethodOptions, type ExtractMethodQuery, type ExtractResponseBody, type ExtractResponseParamNames, type ExtractResponseQuery, type ExtractResponseRequestOptions, type PagesApiClient, type PagesTriggerOptions, type PluginHooksConfig, type QueueApiClient, type QueueTriggerInput, type ReadApiClient, type ResponseInputFields, type SpooshReactHooks, type TriggerOptions, type UsePagesResult, type UseQueueOptions, type UseQueueResult, type UseReadResult, type UseWriteResult, type WriteApiClient, type WriteResponseInputFields, create };

package/dist/index.js

@@ -404,12 +404,12 @@ function createUseWrite(options) {
   return useWrite;
 }
 
-// src/useInfiniteRead/index.ts
+// src/usePages/index.ts
 var import_react3 = require("react");
 var import_core3 = require("@spoosh/core");
-function createUseInfiniteRead(options) {
+function createUsePages(options) {
   const { api, stateManager, eventEmitter, pluginExecutor } = options;
-  return function useInfiniteRead(readFn, readOptions) {
+  return function usePages(readFn, readOptions) {
     const {
       enabled = true,
       tags,
@@ -432,7 +432,7 @@ function createUseInfiniteRead(options) {
     const capturedCall = selectorResultRef.current.call;
     if (!capturedCall) {
       throw new Error(
-        'useInfiniteRead requires calling an HTTP method (GET). Example: useInfiniteRead((api) => api("posts").GET())'
+        'usePages requires calling an HTTP method (GET). Example: usePages((api) => api("posts").GET())'
       );
     }
     const requestOptions = capturedCall.options;
@@ -442,12 +442,6 @@ function createUseInfiniteRead(options) {
       params: requestOptions?.params,
       body: requestOptions?.body
     };
-    const baseOptionsForKey = {
-      ...capturedCall.options,
-      query: void 0,
-      params: void 0,
-      body: void 0
-    };
     const resolvedPath = (0, import_core3.resolvePath)(pathSegments, requestOptions?.params);
     const resolvedTags = (0, import_core3.resolveTags)({ tags }, resolvedPath);
     const canFetchNextRef = (0, import_react3.useRef)(canFetchNext);
@@ -463,22 +457,31 @@ function createUseInfiniteRead(options) {
     const queryKey = stateManager.createQueryKey({
       path: capturedCall.path,
       method: capturedCall.method,
-      options: baseOptionsForKey
+      options: capturedCall.options
+    });
+    const lifecycleRef = (0, import_react3.useRef)({
+      initialized: false,
+      prevContext: null,
+      lastQueryKey: null
     });
     const controllerRef = (0, import_react3.useRef)(null);
-    if (!controllerRef.current || controllerRef.current.queryKey !== queryKey) {
+    const queryKeyChanged = controllerRef.current !== null && controllerRef.current.queryKey !== queryKey;
+    if (queryKeyChanged) {
+      lifecycleRef.current.prevContext = controllerRef.current.controller.getContext();
+      lifecycleRef.current.initialized = false;
+    }
+    if (!controllerRef.current || queryKeyChanged) {
       controllerRef.current = {
         controller: (0, import_core3.createInfiniteReadController)({
           path: capturedCall.path,
           method: capturedCall.method,
           tags: resolvedTags,
           initialRequest,
-          baseOptionsForKey,
-          canFetchNext: (ctx) => canFetchNextRef.current(ctx),
+          canFetchNext: canFetchNext ? (ctx) => canFetchNextRef.current?.(ctx) ?? false : void 0,
           canFetchPrev: canFetchPrev ? (ctx) => canFetchPrevRef.current?.(ctx) ?? false : void 0,
-          nextPageRequest: (ctx) => nextPageRequestRef.current(ctx),
+          nextPageRequest: nextPageRequest ? (ctx) => nextPageRequestRef.current?.(ctx) ?? {} : void 0,
           prevPageRequest: prevPageRequest ? (ctx) => prevPageRequestRef.current?.(ctx) ?? {} : void 0,
-          merger: (responses) => mergerRef.current(responses),
+          merger: (pages) => mergerRef.current(pages),
           stateManager,
           eventEmitter,
           pluginExecutor,
@@ -488,9 +491,7 @@ function createUseInfiniteRead(options) {
             const method = pathMethods[capturedCall.method];
             const fetchOptions = {
               ...capturedCall.options,
-              query: opts.query,
-              params: opts.params,
-              body: opts.body,
+              ...opts,
               signal
             };
             return method(fetchOptions);
@@ -501,11 +502,12 @@ function createUseInfiniteRead(options) {
     }
     const controller = controllerRef.current.controller;
     controller.setPluginOptions(pluginOpts);
-    const state = (0, import_react3.useSyncExternalStore)(
-      controller.subscribe,
-      controller.getState,
-      controller.getState
+    const subscribe = (0, import_react3.useCallback)(
+      (callback) => controller.subscribe(callback),
+      [controller]
     );
+    const getSnapshot = (0, import_react3.useCallback)(() => controller.getState(), [controller]);
+    const state = (0, import_react3.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
     const [isPending, setIsPending] = (0, import_react3.useState)(() => {
       return enabled && state.data === void 0;
     });
@@ -515,10 +517,6 @@ function createUseInfiniteRead(options) {
     const fetchingPrev = fetchingDirection === "prev";
     const hasData = state.data !== void 0;
     const loading = (isPending || fetching) && !hasData;
-    const lifecycleRef = (0, import_react3.useRef)({
-      initialized: false,
-      prevContext: null
-    });
     const tagsKey = JSON.stringify(tags);
     (0, import_react3.useEffect)(() => {
       return () => {
@@ -527,8 +525,27 @@ function createUseInfiniteRead(options) {
       };
     }, []);
     (0, import_react3.useEffect)(() => {
-      controller.mount();
-      lifecycleRef.current.initialized = true;
+      if (!enabled) return;
+      const { initialized, prevContext, lastQueryKey } = lifecycleRef.current;
+      const isQueryKeyChange = lastQueryKey !== null && lastQueryKey !== queryKey;
+      if (!initialized) {
+        controller.mount();
+        lifecycleRef.current.initialized = true;
+        if (prevContext) {
+          controller.update(prevContext);
+          lifecycleRef.current.prevContext = null;
+        }
+      }
+      lifecycleRef.current.lastQueryKey = queryKey;
+      const currentState = controller.getState();
+      const isFetching = controller.getFetchingDirection() !== null;
+      if (isQueryKeyChange) {
+        setIsPending(true);
+        controller.trigger({ force: false }).finally(() => setIsPending(false));
+      } else if (currentState.data === void 0 && !isFetching) {
+        setIsPending(true);
+        controller.fetchNext().finally(() => setIsPending(false));
+      }
       const unsubInvalidate = eventEmitter.on(
         "invalidate",
         (invalidatedTags) => {
@@ -537,41 +554,32 @@ function createUseInfiniteRead(options) {
           );
           if (hasMatch) {
             setIsPending(true);
-            controller.refetch().finally(() => setIsPending(false));
+            controller.trigger().finally(() => setIsPending(false));
           }
         }
       );
       const unsubRefetchAll = eventEmitter.on("refetchAll", () => {
         setIsPending(true);
-        controller.refetch().finally(() => setIsPending(false));
+        controller.trigger().finally(() => setIsPending(false));
       });
       return () => {
+        controller.unmount();
         unsubInvalidate();
         unsubRefetchAll();
       };
-    }, [tagsKey]);
-    (0, import_react3.useEffect)(() => {
-      if (!lifecycleRef.current.initialized) return;
-      if (enabled) {
-        const currentState = controller.getState();
-        const isFetching = controller.getFetchingDirection() !== null;
-        if (currentState.data === void 0 && !isFetching) {
-          setIsPending(true);
-          controller.fetchNext().finally(() => setIsPending(false));
-        }
-      }
-    }, [enabled]);
+    }, [queryKey, enabled, tagsKey]);
+    const pluginOptsKey = JSON.stringify(pluginOpts);
     (0, import_react3.useEffect)(() => {
       if (!enabled || !lifecycleRef.current.initialized) return;
       const prevContext = controller.getContext();
       controller.update(prevContext);
-    }, [JSON.stringify(pluginOpts)]);
-    const entry = stateManager.getCache(queryKey);
-    const pluginResultData = entry?.meta ? Object.fromEntries(entry.meta) : {};
+    }, [pluginOptsKey]);
+    const trigger = async (options2) => {
+      await controller.trigger(options2);
+    };
     const result = {
-      meta: pluginResultData,
       data: state.data,
-      allResponses: state.allResponses,
+      pages: state.pages,
       loading,
       fetching,
       fetchingNext,
@@ -580,7 +588,7 @@ function createUseInfiniteRead(options) {
       canFetchPrev: state.canFetchPrev,
       fetchNext: controller.fetchNext,
       fetchPrev: controller.fetchPrev,
-      trigger: controller.refetch,
+      trigger,
       abort: controller.abort,
       error: state.error
     };
@@ -669,7 +677,7 @@ function create(instance) {
     eventEmitter,
     pluginExecutor
   });
-  const useInfiniteRead = createUseInfiniteRead({
+  const usePages = createUsePages({
     api,
     stateManager,
     eventEmitter,
@@ -708,7 +716,7 @@ function create(instance) {
   return {
     useRead,
     useWrite,
-    useInfiniteRead,
+    usePages,
     useQueue,
     ...instanceApis
   };

package/dist/index.mjs

@@ -402,13 +402,14 @@ function createUseWrite(options) {
   return useWrite;
 }
 
-// src/useInfiniteRead/index.ts
+// src/usePages/index.ts
 import {
   useRef as useRef3,
   useEffect as useEffect2,
   useSyncExternalStore as useSyncExternalStore3,
   useId as useId3,
-  useState as useState3
+  useState as useState3,
+  useCallback as useCallback3
 } from "react";
 import {
   createInfiniteReadController,
@@ -416,9 +417,9 @@ import {
   resolvePath as resolvePath3,
   resolveTags as resolveTags3
 } from "@spoosh/core";
-function createUseInfiniteRead(options) {
+function createUsePages(options) {
   const { api, stateManager, eventEmitter, pluginExecutor } = options;
-  return function useInfiniteRead(readFn, readOptions) {
+  return function usePages(readFn, readOptions) {
     const {
       enabled = true,
       tags,
@@ -441,7 +442,7 @@ function createUseInfiniteRead(options) {
     const capturedCall = selectorResultRef.current.call;
     if (!capturedCall) {
       throw new Error(
-        'useInfiniteRead requires calling an HTTP method (GET). Example: useInfiniteRead((api) => api("posts").GET())'
+        'usePages requires calling an HTTP method (GET). Example: usePages((api) => api("posts").GET())'
       );
     }
     const requestOptions = capturedCall.options;
@@ -451,12 +452,6 @@ function createUseInfiniteRead(options) {
       params: requestOptions?.params,
       body: requestOptions?.body
     };
-    const baseOptionsForKey = {
-      ...capturedCall.options,
-      query: void 0,
-      params: void 0,
-      body: void 0
-    };
     const resolvedPath = resolvePath3(pathSegments, requestOptions?.params);
     const resolvedTags = resolveTags3({ tags }, resolvedPath);
     const canFetchNextRef = useRef3(canFetchNext);
@@ -472,22 +467,31 @@ function createUseInfiniteRead(options) {
     const queryKey = stateManager.createQueryKey({
       path: capturedCall.path,
       method: capturedCall.method,
-      options: baseOptionsForKey
+      options: capturedCall.options
+    });
+    const lifecycleRef = useRef3({
+      initialized: false,
+      prevContext: null,
+      lastQueryKey: null
     });
     const controllerRef = useRef3(null);
-    if (!controllerRef.current || controllerRef.current.queryKey !== queryKey) {
+    const queryKeyChanged = controllerRef.current !== null && controllerRef.current.queryKey !== queryKey;
+    if (queryKeyChanged) {
+      lifecycleRef.current.prevContext = controllerRef.current.controller.getContext();
+      lifecycleRef.current.initialized = false;
+    }
+    if (!controllerRef.current || queryKeyChanged) {
       controllerRef.current = {
         controller: createInfiniteReadController({
           path: capturedCall.path,
           method: capturedCall.method,
           tags: resolvedTags,
           initialRequest,
-          baseOptionsForKey,
-          canFetchNext: (ctx) => canFetchNextRef.current(ctx),
+          canFetchNext: canFetchNext ? (ctx) => canFetchNextRef.current?.(ctx) ?? false : void 0,
           canFetchPrev: canFetchPrev ? (ctx) => canFetchPrevRef.current?.(ctx) ?? false : void 0,
-          nextPageRequest: (ctx) => nextPageRequestRef.current(ctx),
+          nextPageRequest: nextPageRequest ? (ctx) => nextPageRequestRef.current?.(ctx) ?? {} : void 0,
           prevPageRequest: prevPageRequest ? (ctx) => prevPageRequestRef.current?.(ctx) ?? {} : void 0,
-          merger: (responses) => mergerRef.current(responses),
+          merger: (pages) => mergerRef.current(pages),
           stateManager,
           eventEmitter,
           pluginExecutor,
@@ -497,9 +501,7 @@ function createUseInfiniteRead(options) {
             const method = pathMethods[capturedCall.method];
             const fetchOptions = {
               ...capturedCall.options,
-              query: opts.query,
-              params: opts.params,
-              body: opts.body,
+              ...opts,
               signal
             };
             return method(fetchOptions);
@@ -510,11 +512,12 @@ function createUseInfiniteRead(options) {
     }
     const controller = controllerRef.current.controller;
     controller.setPluginOptions(pluginOpts);
-    const state = useSyncExternalStore3(
-      controller.subscribe,
-      controller.getState,
-      controller.getState
+    const subscribe = useCallback3(
+      (callback) => controller.subscribe(callback),
+      [controller]
     );
+    const getSnapshot = useCallback3(() => controller.getState(), [controller]);
+    const state = useSyncExternalStore3(subscribe, getSnapshot, getSnapshot);
     const [isPending, setIsPending] = useState3(() => {
       return enabled && state.data === void 0;
     });
@@ -524,10 +527,6 @@ function createUseInfiniteRead(options) {
     const fetchingPrev = fetchingDirection === "prev";
     const hasData = state.data !== void 0;
     const loading = (isPending || fetching) && !hasData;
-    const lifecycleRef = useRef3({
-      initialized: false,
-      prevContext: null
-    });
     const tagsKey = JSON.stringify(tags);
     useEffect2(() => {
       return () => {
@@ -536,8 +535,27 @@ function createUseInfiniteRead(options) {
       };
     }, []);
     useEffect2(() => {
-      controller.mount();
-      lifecycleRef.current.initialized = true;
+      if (!enabled) return;
+      const { initialized, prevContext, lastQueryKey } = lifecycleRef.current;
+      const isQueryKeyChange = lastQueryKey !== null && lastQueryKey !== queryKey;
+      if (!initialized) {
+        controller.mount();
+        lifecycleRef.current.initialized = true;
+        if (prevContext) {
+          controller.update(prevContext);
+          lifecycleRef.current.prevContext = null;
+        }
+      }
+      lifecycleRef.current.lastQueryKey = queryKey;
+      const currentState = controller.getState();
+      const isFetching = controller.getFetchingDirection() !== null;
+      if (isQueryKeyChange) {
+        setIsPending(true);
+        controller.trigger({ force: false }).finally(() => setIsPending(false));
+      } else if (currentState.data === void 0 && !isFetching) {
+        setIsPending(true);
+        controller.fetchNext().finally(() => setIsPending(false));
+      }
       const unsubInvalidate = eventEmitter.on(
         "invalidate",
         (invalidatedTags) => {
@@ -546,41 +564,32 @@ function createUseInfiniteRead(options) {
           );
           if (hasMatch) {
             setIsPending(true);
-            controller.refetch().finally(() => setIsPending(false));
+            controller.trigger().finally(() => setIsPending(false));
           }
         }
       );
       const unsubRefetchAll = eventEmitter.on("refetchAll", () => {
         setIsPending(true);
-        controller.refetch().finally(() => setIsPending(false));
+        controller.trigger().finally(() => setIsPending(false));
       });
       return () => {
+        controller.unmount();
         unsubInvalidate();
         unsubRefetchAll();
       };
-    }, [tagsKey]);
-    useEffect2(() => {
-      if (!lifecycleRef.current.initialized) return;
-      if (enabled) {
-        const currentState = controller.getState();
-        const isFetching = controller.getFetchingDirection() !== null;
-        if (currentState.data === void 0 && !isFetching) {
-          setIsPending(true);
-          controller.fetchNext().finally(() => setIsPending(false));
-        }
-      }
-    }, [enabled]);
+    }, [queryKey, enabled, tagsKey]);
+    const pluginOptsKey = JSON.stringify(pluginOpts);
     useEffect2(() => {
       if (!enabled || !lifecycleRef.current.initialized) return;
       const prevContext = controller.getContext();
       controller.update(prevContext);
-    }, [JSON.stringify(pluginOpts)]);
-    const entry = stateManager.getCache(queryKey);
-    const pluginResultData = entry?.meta ? Object.fromEntries(entry.meta) : {};
+    }, [pluginOptsKey]);
+    const trigger = async (options2) => {
+      await controller.trigger(options2);
+    };
     const result = {
-      meta: pluginResultData,
       data: state.data,
-      allResponses: state.allResponses,
+      pages: state.pages,
       loading,
       fetching,
       fetchingNext,
@@ -589,7 +598,7 @@ function createUseInfiniteRead(options) {
       canFetchPrev: state.canFetchPrev,
       fetchNext: controller.fetchNext,
       fetchPrev: controller.fetchPrev,
-      trigger: controller.refetch,
+      trigger,
       abort: controller.abort,
       error: state.error
     };
@@ -681,7 +690,7 @@ function create(instance) {
     eventEmitter,
     pluginExecutor
   });
-  const useInfiniteRead = createUseInfiniteRead({
+  const usePages = createUsePages({
     api,
     stateManager,
     eventEmitter,
@@ -720,7 +729,7 @@ function create(instance) {
   return {
     useRead,
     useWrite,
-    useInfiniteRead,
+    usePages,
     useQueue,
     ...instanceApis
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/react",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "license": "MIT",
   "description": "React hooks for Spoosh API toolkit",
   "keywords": [
@@ -34,14 +34,14 @@
     }
   },
   "peerDependencies": {
-    "@spoosh/core": ">=0.14.0",
+    "@spoosh/core": ">=0.15.0",
     "react": "^18 || ^19"
   },
   "devDependencies": {
     "@testing-library/react": "^16.0.0",
     "jsdom": "^26.0.0",
-    "@spoosh/core": "0.14.0",
-    "@spoosh/test-utils": "0.2.0"
+    "@spoosh/core": "0.15.0",
+    "@spoosh/test-utils": "0.3.0"
   },
   "scripts": {
     "dev": "tsup --watch",