@spoosh/core 0.14.1 → 0.15.1

package/dist/index.d.mts

@@ -215,7 +215,6 @@ type CacheEntryWithKey<TData = unknown, TError = unknown> = {
     key: string;
     entry: CacheEntry<TData, TError>;
 };
-declare function createInitialState<TData, TError>(): OperationState<TData, TError>;
 type StateManager = {
     createQueryKey: (params: {
         path: string;
@@ -249,8 +248,11 @@ type StateManager = {
     onDataChange: (callback: DataChangeCallback) => () => void;
     clear: () => void;
 };
+
 declare function createStateManager(): StateManager;
 
+declare function createInitialState<TData, TError>(): OperationState<TData, TError>;
+
 /**
  * Devtool-related types for tracing and debugging.
  * These types are used by the devtool plugin and plugins that emit trace events.
@@ -435,7 +437,7 @@ interface EventTracer {
     emit(msg: string, options?: EventOptions): void;
 }
 
-type OperationType = "read" | "write" | "infiniteRead" | "queue";
+type OperationType = "read" | "write" | "pages" | "queue";
 type LifecyclePhase = "onMount" | "onUnmount" | "onUpdate";
 type OperationState<TData = unknown, TError = unknown> = {
     data: TData | undefined;
@@ -492,7 +494,7 @@ type PluginContextBase = {
     eventEmitter: EventEmitter;
     /** Access other plugins' exported APIs */
     plugins: PluginAccessor;
-    /** Plugin-specific options passed from hooks (useRead/useWrite/useInfiniteRead) */
+    /** Plugin-specific options passed from hooks (useRead/useWrite/usePages) */
     pluginOptions?: unknown;
     /** Force a network request even if cached data exists. Used by plugins to communicate intent. */
     forceRefetch?: boolean;
@@ -598,7 +600,7 @@ type PluginLifecycle = {
 type PluginTypeConfig = {
     readOptions?: object;
     writeOptions?: object;
-    infiniteReadOptions?: object;
+    pagesOptions?: object;
     writeTriggerOptions?: object;
     queueOptions?: object;
     queueTriggerOptions?: object;
@@ -1027,8 +1029,8 @@ type ExtractReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends
 type ExtractWriteOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     writeOptions: infer W;
 } ? W : object : object;
-type ExtractInfiniteReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
-    infiniteReadOptions: infer I;
+type ExtractPagesOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    pagesOptions: infer I;
 } ? I : object : object;
 type ExtractWriteTriggerOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     writeTriggerOptions: infer W;
@@ -1051,21 +1053,21 @@ type ExtractWriteResult<T> = T extends SpooshPlugin<infer Types> ? Types extends
 type ExtractInstanceApi<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     instanceApi: infer A;
 } ? A : object : object;
-type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type UnionToIntersection$1<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 type MergePluginOptions<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
-    read: UnionToIntersection<ExtractReadOptions<TPlugins[number]>>;
-    write: UnionToIntersection<ExtractWriteOptions<TPlugins[number]>>;
-    infiniteRead: UnionToIntersection<ExtractInfiniteReadOptions<TPlugins[number]>>;
-    writeTrigger: UnionToIntersection<ExtractWriteTriggerOptions<TPlugins[number]>>;
-    queue: UnionToIntersection<ExtractQueueOptions<TPlugins[number]>>;
-    queueTrigger: UnionToIntersection<ExtractQueueTriggerOptions<TPlugins[number]>>;
+    read: UnionToIntersection$1<ExtractReadOptions<TPlugins[number]>>;
+    write: UnionToIntersection$1<ExtractWriteOptions<TPlugins[number]>>;
+    pages: UnionToIntersection$1<ExtractPagesOptions<TPlugins[number]>>;
+    writeTrigger: UnionToIntersection$1<ExtractWriteTriggerOptions<TPlugins[number]>>;
+    queue: UnionToIntersection$1<ExtractQueueOptions<TPlugins[number]>>;
+    queueTrigger: UnionToIntersection$1<ExtractQueueTriggerOptions<TPlugins[number]>>;
 };
 type MergePluginResults<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
-    read: UnionToIntersection<ExtractReadResult<TPlugins[number]>>;
-    write: UnionToIntersection<ExtractWriteResult<TPlugins[number]>>;
-    queue: UnionToIntersection<ExtractQueueResult<TPlugins[number]>>;
+    read: UnionToIntersection$1<ExtractReadResult<TPlugins[number]>>;
+    write: UnionToIntersection$1<ExtractWriteResult<TPlugins[number]>>;
+    queue: UnionToIntersection$1<ExtractQueueResult<TPlugins[number]>>;
 };
-type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
+type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection$1<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
 type PluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]> = {
     plugins: TPlugins;
     _options: MergePluginOptions<TPlugins>;
@@ -1309,12 +1311,103 @@ type WritePathMethods$1<TSchema, TPath extends string> = FindMatchingKey<TSchema
  */
 type WriteSchemaHelper<TSchema> = <TPath extends WritePaths<TSchema> | (string & {})>(path: TPath) => HasWriteMethod<TSchema, TPath> extends true ? WritePathMethods$1<TSchema, TPath> : never;
 
+/**
+ * Check for exact type equality using function type assignability.
+ * Two types are equal if functions returning them are mutually assignable.
+ */
+type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+/**
+ * Convert bare `object` type to `never` to exclude it from the union.
+ * Preserves all other types including interfaces and types with actual properties.
+ */
+type FilterObjectType<T> = Equals<T, object> extends true ? never : T;
+/**
+ * Convert a union type to an intersection type.
+ * This merges all properties from all types in the union.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+/**
+ * Extract all option types from plugin configuration and create a union, then intersect.
+ * This allows middleware to access all properties from all option types.
+ * object types are converted to unknown which doesn't affect the intersection.
+ */
+type ExtractPluginOptionsUnion<T extends PluginTypeConfig> = UnionToIntersection<FilterObjectType<T extends {
+    readOptions: infer R;
+} ? R : never> | FilterObjectType<T extends {
+    writeOptions: infer W;
+} ? W : never> | FilterObjectType<T extends {
+    writeTriggerOptions: infer WT;
+} ? WT : never> | FilterObjectType<T extends {
+    queueTriggerOptions: infer QT;
+} ? QT : never> | FilterObjectType<T extends {
+    pagesOptions: infer P;
+} ? P : never> | FilterObjectType<T extends {
+    queueOptions: infer Q;
+} ? Q : never>>;
+/**
+ * Plugin context with typed pluginOptions based on plugin configuration.
+ */
+type TypedPluginContext<T extends PluginTypeConfig> = Omit<PluginContext, "pluginOptions"> & {
+    pluginOptions?: ExtractPluginOptionsUnion<T>;
+};
+/**
+ * Plugin definition with typed context for middleware and handlers.
+ */
+type TypedPluginDefinition<T extends PluginTypeConfig> = Omit<SpooshPlugin<T>, "middleware" | "afterResponse" | "lifecycle"> & {
+    middleware?: (context: TypedPluginContext<T>, next: () => Promise<any>) => Promise<any>;
+    afterResponse?: (context: TypedPluginContext<T>, response: any) => any;
+    lifecycle?: {
+        onMount?: (context: TypedPluginContext<T>) => void | Promise<void>;
+        onUpdate?: (context: TypedPluginContext<T>, previousContext: TypedPluginContext<T>) => void | Promise<void>;
+        onUnmount?: (context: TypedPluginContext<T>) => void | Promise<void>;
+    };
+};
+/**
+ * Helper to create a Spoosh plugin with automatic type inference for plugin options.
+ *
+ * This eliminates the need for manual type assertions in middleware by automatically
+ * intersecting all option types, making all properties accessible:
+ *
+ * ```ts
+ * // Before:
+ * const pluginOptions = context.pluginOptions as CacheReadOptions | undefined;
+ * const staleTime = pluginOptions?.staleTime ?? defaultStaleTime;
+ *
+ * // After (with createSpooshPlugin):
+ * const staleTime = context.pluginOptions?.staleTime ?? defaultStaleTime;
+ * ```
+ *
+ * @typeParam T - Plugin type configuration (readOptions, writeOptions, etc.)
+ * @param definition - Plugin definition with typed context
+ * @returns Typed Spoosh plugin
+ *
+ * @example
+ * ```ts
+ * export const cachePlugin = (config: CachePluginConfig = {}) =>
+ *   createSpooshPlugin<{
+ *     readOptions: CacheReadOptions;
+ *     writeOptions: CacheWriteOptions;
+ *     pagesOptions: CachePagesOptions;
+ *   }>({
+ *     name: "spoosh:cache",
+ *     operations: ["read", "write", "pages"],
+ *     middleware: async (context, next) => {
+ *       // context.pluginOptions is automatically typed as an intersection:
+ *       // CacheReadOptions & CachePagesOptions (CacheWriteOptions filtered as it's just 'object')
+ *       // All properties from all option types are accessible:
+ *       const staleTime = context.pluginOptions?.staleTime ?? defaultStaleTime;
+ *       return next();
+ *     },
+ *   });
+ * ```
+ */
+declare function createSpooshPlugin<T extends PluginTypeConfig>(definition: TypedPluginDefinition<T>): SpooshPlugin<T>;
+
 /**
  * Base request options available on all methods.
  */
 type BaseRequestOptions = {
     headers?: HeadersInitOrGetter;
-    cache?: RequestCache;
     signal?: AbortSignal;
 };
 /**
@@ -1490,6 +1583,22 @@ type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends
     };
 };
 
+type ExtractTriggerQuery<I> = I extends {
+    query: infer Q;
+} ? {
+    query?: Q;
+} : unknown;
+type ExtractTriggerBody<I> = I extends {
+    body: infer B;
+} ? {
+    body?: B;
+} : unknown;
+type ExtractTriggerParams<I> = I extends {
+    params: infer P;
+} ? {
+    params?: P;
+} : unknown;
+
 /**
  * Class-based builder for creating Spoosh instances with type-safe plugin inference.
  *
@@ -2001,6 +2110,7 @@ type CreateOperationOptions<TData, TError> = {
     /** Unique identifier for the hook instance. Persists across queryKey changes. */
     instanceId?: string;
 };
+
 declare function createOperationController<TData, TError>(options: CreateOperationOptions<TData, TError>): OperationController<TData, TError>;
 
 type InfiniteRequestOptions = {
@@ -2008,27 +2118,43 @@ type InfiniteRequestOptions = {
     params?: Record<string, string | number>;
     body?: unknown;
 };
-type PageContext<TData, TRequest = InfiniteRequestOptions> = {
-    response: TData | undefined;
-    allResponses: TData[];
+type InfinitePageStatus = "pending" | "loading" | "success" | "error" | "stale";
+interface InfinitePage<TData, TError, TMeta> {
+    status: InfinitePageStatus;
+    data?: TData;
+    error?: TError;
+    meta?: TMeta;
+    input?: InfiniteRequestOptions;
+}
+type InfiniteNextContext<TData, TError, TRequest, TMeta> = {
+    lastPage: InfinitePage<TData, TError, TMeta> | undefined;
+    pages: InfinitePage<TData, TError, TMeta>[];
+    request: TRequest;
+};
+type InfinitePrevContext<TData, TError, TRequest, TMeta> = {
+    firstPage: InfinitePage<TData, TError, TMeta> | undefined;
+    pages: InfinitePage<TData, TError, TMeta>[];
     request: TRequest;
 };
 type FetchDirection = "next" | "prev";
-type InfiniteReadState<TData, TItem, TError> = {
+type InfiniteTriggerOptions = Partial<InfiniteRequestOptions> & {
+    /** Bypass cache and force refetch. Default: true */
+    force?: boolean;
+};
+type InfiniteReadState<TData, TItem, TError, TMeta = Record<string, unknown>> = {
     data: TItem[] | undefined;
-    allResponses: TData[] | undefined;
-    allRequests: InfiniteRequestOptions[] | undefined;
+    pages: InfinitePage<TData, TError, TMeta>[];
     canFetchNext: boolean;
     canFetchPrev: boolean;
     error: TError | undefined;
 };
-type InfiniteReadController<TData, TItem, TError> = {
-    getState: () => InfiniteReadState<TData, TItem, TError>;
+type InfiniteReadController<TData, TItem, TError, TMeta = Record<string, unknown>> = {
+    getState: () => InfiniteReadState<TData, TItem, TError, TMeta>;
     getFetchingDirection: () => FetchDirection | null;
     subscribe: (callback: () => void) => () => void;
     fetchNext: () => Promise<void>;
     fetchPrev: () => Promise<void>;
-    refetch: () => Promise<void>;
+    trigger: (options?: InfiniteTriggerOptions) => Promise<void>;
     abort: () => void;
     mount: () => void;
     unmount: () => void;
@@ -2036,17 +2162,16 @@ type InfiniteReadController<TData, TItem, TError> = {
     getContext: () => PluginContext;
     setPluginOptions: (options: unknown) => void;
 };
-type CreateInfiniteReadOptions<TData, TItem, TError, TRequest> = {
+type CreateInfiniteReadOptions<TData, TItem, TError, TRequest, TMeta = Record<string, unknown>> = {
     path: string;
     method: HttpMethod;
     tags: string[];
     initialRequest: InfiniteRequestOptions;
-    baseOptionsForKey: object;
-    canFetchNext: (ctx: PageContext<TData, TRequest>) => boolean;
-    canFetchPrev?: (ctx: PageContext<TData, TRequest>) => boolean;
-    nextPageRequest: (ctx: PageContext<TData, TRequest>) => Partial<TRequest>;
-    prevPageRequest?: (ctx: PageContext<TData, TRequest>) => Partial<TRequest>;
-    merger: (responses: TData[]) => TItem[];
+    canFetchNext?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => boolean;
+    canFetchPrev?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => boolean;
+    nextPageRequest?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
+    prevPageRequest?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
+    merger: (pages: InfinitePage<TData, TError, TMeta>[]) => TItem[];
     stateManager: StateManager;
     eventEmitter: EventEmitter;
     pluginExecutor: PluginExecutor;
@@ -2054,7 +2179,8 @@ type CreateInfiniteReadOptions<TData, TItem, TError, TRequest> = {
     /** Unique identifier for the hook instance. Persists across queryKey changes. */
     instanceId?: string;
 };
-declare function createInfiniteReadController<TData, TItem, TError, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions>(options: CreateInfiniteReadOptions<TData, TItem, TError, TRequest>): InfiniteReadController<TData, TItem, TError>;
+
+declare function createInfiniteReadController<TData, TItem, TError, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions, TMeta = Record<string, unknown>>(options: CreateInfiniteReadOptions<TData, TItem, TError, TRequest, TMeta>): InfiniteReadController<TData, TItem, TError, TMeta>;
 
 /**
  * Status of an item in the queue.
@@ -2177,4 +2303,4 @@ declare class Semaphore {
     getWaitingCount(): number;
 }
 
-export { type AnyRequestOptions, type ApiSchema, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type DevtoolEvents, type EventEmitter, type EventListener, type EventOptions, type EventTracer, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HasReadMethod, type HasWriteMethod, type HeadersInitOrGetter, type HttpMethod, type HttpMethodKey, type InfiniteReadController, type InfiniteReadState, type InfiniteRequestOptions, type InstanceApiContext, type InstanceApiResolvers, type InstancePluginExecutor, type LifecyclePhase, type MergePluginInstanceApi, type MergePluginOptions, type MergePluginResults, type MethodOptionsMap, type OperationController, type OperationState, type OperationType, type PageContext, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextBase, type PluginContextExtensions, type PluginContextInput, type PluginExecutor, type PluginExportsRegistry, type PluginFactory, type PluginHandler, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginRequestOptions, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type QueueController, type QueueControllerConfig, type QueueControllerContext, type QueueItem, type QueueItemStatus, type QueueSelectorClient, type QueueStats, type QueueTriggerInput, type ReadClient, type ReadPaths, type ReadSchemaHelper, type RefetchEvent, type RequestCompleteEvent, type RequestOptions$1 as RequestOptions, type RequestTracer, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, Semaphore, type SetupContext, type Simplify, Spoosh, type SpooshBody, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshOptions, type SpooshOptionsInput, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StandaloneEvent, type StateManager, type StripPrefix, type TagMode, type TagOptions, type Trace, type TraceColor, type TraceEvent, type TraceInfo, type TraceListener, type TraceOptions, type TraceStage, type Transport, type TransportOption, type TransportOptionsMap, type TransportResponse, type WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, type WriteSelectorClient, __DEV__, buildUrl, clone, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createQueueController, createSelectorProxy, createStateManager, createTracer, executeFetch, extractMethodFromSelector, extractPathFromSelector, fetchTransport, form, generateTags, getContentType, isAbortError, isJsonBody, isNetworkError, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, removeHeaderKeys, resolveHeadersToRecord, resolvePath, resolvePathString, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded, xhrTransport };
+export { type AnyRequestOptions, type ApiSchema, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type DataChangeCallback, type DevtoolEvents, type EventEmitter, type EventListener, type EventOptions, type EventTracer, type ExecuteOptions, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type ExtractTriggerBody, type ExtractTriggerParams, type ExtractTriggerQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HasReadMethod, type HasWriteMethod, type HeadersInitOrGetter, type HttpMethod, type HttpMethodKey, type InfiniteNextContext, type InfinitePage, type InfinitePageStatus, type InfinitePrevContext, type InfiniteReadController, type InfiniteReadState, type InfiniteRequestOptions, type InfiniteTriggerOptions, type InstanceApiContext, type InstanceApiResolvers, type InstancePluginExecutor, type LifecyclePhase, type MergePluginInstanceApi, type MergePluginOptions, type MergePluginResults, type MethodOptionsMap, type OperationController, type OperationState, type OperationType, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextBase, type PluginContextExtensions, type PluginContextInput, type PluginExecutor, type PluginExportsRegistry, type PluginFactory, type PluginHandler, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginRequestOptions, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type QueueController, type QueueControllerConfig, type QueueControllerContext, type QueueItem, type QueueItemStatus, type QueueSelectorClient, type QueueStats, type QueueTriggerInput, type ReadClient, type ReadPaths, type ReadSchemaHelper, type RefetchEvent, type RequestCompleteEvent, type RequestOptions$1 as RequestOptions, type RequestTracer, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, Semaphore, type SetupContext, type Simplify, Spoosh, type SpooshBody, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshOptions, type SpooshOptionsInput, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StandaloneEvent, type StateManager, type StripPrefix, type Subscriber, type TagMode, type TagOptions, type Trace, type TraceColor, type TraceEvent, type TraceInfo, type TraceListener, type TraceOptions, type TraceStage, type Transport, type TransportOption, type TransportOptionsMap, type TransportResponse, type TypedPluginContext, type TypedPluginDefinition, type WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, type WriteSelectorClient, __DEV__, buildUrl, clone, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createQueueController, createSelectorProxy, createSpooshPlugin, createStateManager, createTracer, executeFetch, extractMethodFromSelector, extractPathFromSelector, fetchTransport, form, generateTags, getContentType, isAbortError, isJsonBody, isNetworkError, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, removeHeaderKeys, resolveHeadersToRecord, resolvePath, resolvePathString, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded, xhrTransport };

package/dist/index.d.ts

@@ -215,7 +215,6 @@ type CacheEntryWithKey<TData = unknown, TError = unknown> = {
     key: string;
     entry: CacheEntry<TData, TError>;
 };
-declare function createInitialState<TData, TError>(): OperationState<TData, TError>;
 type StateManager = {
     createQueryKey: (params: {
         path: string;
@@ -249,8 +248,11 @@ type StateManager = {
     onDataChange: (callback: DataChangeCallback) => () => void;
     clear: () => void;
 };
+
 declare function createStateManager(): StateManager;
 
+declare function createInitialState<TData, TError>(): OperationState<TData, TError>;
+
 /**
  * Devtool-related types for tracing and debugging.
  * These types are used by the devtool plugin and plugins that emit trace events.
@@ -435,7 +437,7 @@ interface EventTracer {
     emit(msg: string, options?: EventOptions): void;
 }
 
-type OperationType = "read" | "write" | "infiniteRead" | "queue";
+type OperationType = "read" | "write" | "pages" | "queue";
 type LifecyclePhase = "onMount" | "onUnmount" | "onUpdate";
 type OperationState<TData = unknown, TError = unknown> = {
     data: TData | undefined;
@@ -492,7 +494,7 @@ type PluginContextBase = {
     eventEmitter: EventEmitter;
     /** Access other plugins' exported APIs */
     plugins: PluginAccessor;
-    /** Plugin-specific options passed from hooks (useRead/useWrite/useInfiniteRead) */
+    /** Plugin-specific options passed from hooks (useRead/useWrite/usePages) */
     pluginOptions?: unknown;
     /** Force a network request even if cached data exists. Used by plugins to communicate intent. */
     forceRefetch?: boolean;
@@ -598,7 +600,7 @@ type PluginLifecycle = {
 type PluginTypeConfig = {
     readOptions?: object;
     writeOptions?: object;
-    infiniteReadOptions?: object;
+    pagesOptions?: object;
     writeTriggerOptions?: object;
     queueOptions?: object;
     queueTriggerOptions?: object;
@@ -1027,8 +1029,8 @@ type ExtractReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends
 type ExtractWriteOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     writeOptions: infer W;
 } ? W : object : object;
-type ExtractInfiniteReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
-    infiniteReadOptions: infer I;
+type ExtractPagesOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    pagesOptions: infer I;
 } ? I : object : object;
 type ExtractWriteTriggerOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     writeTriggerOptions: infer W;
@@ -1051,21 +1053,21 @@ type ExtractWriteResult<T> = T extends SpooshPlugin<infer Types> ? Types extends
 type ExtractInstanceApi<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     instanceApi: infer A;
 } ? A : object : object;
-type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type UnionToIntersection$1<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 type MergePluginOptions<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
-    read: UnionToIntersection<ExtractReadOptions<TPlugins[number]>>;
-    write: UnionToIntersection<ExtractWriteOptions<TPlugins[number]>>;
-    infiniteRead: UnionToIntersection<ExtractInfiniteReadOptions<TPlugins[number]>>;
-    writeTrigger: UnionToIntersection<ExtractWriteTriggerOptions<TPlugins[number]>>;
-    queue: UnionToIntersection<ExtractQueueOptions<TPlugins[number]>>;
-    queueTrigger: UnionToIntersection<ExtractQueueTriggerOptions<TPlugins[number]>>;
+    read: UnionToIntersection$1<ExtractReadOptions<TPlugins[number]>>;
+    write: UnionToIntersection$1<ExtractWriteOptions<TPlugins[number]>>;
+    pages: UnionToIntersection$1<ExtractPagesOptions<TPlugins[number]>>;
+    writeTrigger: UnionToIntersection$1<ExtractWriteTriggerOptions<TPlugins[number]>>;
+    queue: UnionToIntersection$1<ExtractQueueOptions<TPlugins[number]>>;
+    queueTrigger: UnionToIntersection$1<ExtractQueueTriggerOptions<TPlugins[number]>>;
 };
 type MergePluginResults<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
-    read: UnionToIntersection<ExtractReadResult<TPlugins[number]>>;
-    write: UnionToIntersection<ExtractWriteResult<TPlugins[number]>>;
-    queue: UnionToIntersection<ExtractQueueResult<TPlugins[number]>>;
+    read: UnionToIntersection$1<ExtractReadResult<TPlugins[number]>>;
+    write: UnionToIntersection$1<ExtractWriteResult<TPlugins[number]>>;
+    queue: UnionToIntersection$1<ExtractQueueResult<TPlugins[number]>>;
 };
-type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
+type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection$1<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
 type PluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]> = {
     plugins: TPlugins;
     _options: MergePluginOptions<TPlugins>;
@@ -1309,12 +1311,103 @@ type WritePathMethods$1<TSchema, TPath extends string> = FindMatchingKey<TSchema
  */
 type WriteSchemaHelper<TSchema> = <TPath extends WritePaths<TSchema> | (string & {})>(path: TPath) => HasWriteMethod<TSchema, TPath> extends true ? WritePathMethods$1<TSchema, TPath> : never;
 
+/**
+ * Check for exact type equality using function type assignability.
+ * Two types are equal if functions returning them are mutually assignable.
+ */
+type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+/**
+ * Convert bare `object` type to `never` to exclude it from the union.
+ * Preserves all other types including interfaces and types with actual properties.
+ */
+type FilterObjectType<T> = Equals<T, object> extends true ? never : T;
+/**
+ * Convert a union type to an intersection type.
+ * This merges all properties from all types in the union.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+/**
+ * Extract all option types from plugin configuration and create a union, then intersect.
+ * This allows middleware to access all properties from all option types.
+ * object types are converted to unknown which doesn't affect the intersection.
+ */
+type ExtractPluginOptionsUnion<T extends PluginTypeConfig> = UnionToIntersection<FilterObjectType<T extends {
+    readOptions: infer R;
+} ? R : never> | FilterObjectType<T extends {
+    writeOptions: infer W;
+} ? W : never> | FilterObjectType<T extends {
+    writeTriggerOptions: infer WT;
+} ? WT : never> | FilterObjectType<T extends {
+    queueTriggerOptions: infer QT;
+} ? QT : never> | FilterObjectType<T extends {
+    pagesOptions: infer P;
+} ? P : never> | FilterObjectType<T extends {
+    queueOptions: infer Q;
+} ? Q : never>>;
+/**
+ * Plugin context with typed pluginOptions based on plugin configuration.
+ */
+type TypedPluginContext<T extends PluginTypeConfig> = Omit<PluginContext, "pluginOptions"> & {
+    pluginOptions?: ExtractPluginOptionsUnion<T>;
+};
+/**
+ * Plugin definition with typed context for middleware and handlers.
+ */
+type TypedPluginDefinition<T extends PluginTypeConfig> = Omit<SpooshPlugin<T>, "middleware" | "afterResponse" | "lifecycle"> & {
+    middleware?: (context: TypedPluginContext<T>, next: () => Promise<any>) => Promise<any>;
+    afterResponse?: (context: TypedPluginContext<T>, response: any) => any;
+    lifecycle?: {
+        onMount?: (context: TypedPluginContext<T>) => void | Promise<void>;
+        onUpdate?: (context: TypedPluginContext<T>, previousContext: TypedPluginContext<T>) => void | Promise<void>;
+        onUnmount?: (context: TypedPluginContext<T>) => void | Promise<void>;
+    };
+};
+/**
+ * Helper to create a Spoosh plugin with automatic type inference for plugin options.
+ *
+ * This eliminates the need for manual type assertions in middleware by automatically
+ * intersecting all option types, making all properties accessible:
+ *
+ * ```ts
+ * // Before:
+ * const pluginOptions = context.pluginOptions as CacheReadOptions | undefined;
+ * const staleTime = pluginOptions?.staleTime ?? defaultStaleTime;
+ *
+ * // After (with createSpooshPlugin):
+ * const staleTime = context.pluginOptions?.staleTime ?? defaultStaleTime;
+ * ```
+ *
+ * @typeParam T - Plugin type configuration (readOptions, writeOptions, etc.)
+ * @param definition - Plugin definition with typed context
+ * @returns Typed Spoosh plugin
+ *
+ * @example
+ * ```ts
+ * export const cachePlugin = (config: CachePluginConfig = {}) =>
+ *   createSpooshPlugin<{
+ *     readOptions: CacheReadOptions;
+ *     writeOptions: CacheWriteOptions;
+ *     pagesOptions: CachePagesOptions;
+ *   }>({
+ *     name: "spoosh:cache",
+ *     operations: ["read", "write", "pages"],
+ *     middleware: async (context, next) => {
+ *       // context.pluginOptions is automatically typed as an intersection:
+ *       // CacheReadOptions & CachePagesOptions (CacheWriteOptions filtered as it's just 'object')
+ *       // All properties from all option types are accessible:
+ *       const staleTime = context.pluginOptions?.staleTime ?? defaultStaleTime;
+ *       return next();
+ *     },
+ *   });
+ * ```
+ */
+declare function createSpooshPlugin<T extends PluginTypeConfig>(definition: TypedPluginDefinition<T>): SpooshPlugin<T>;
+
 /**
  * Base request options available on all methods.
  */
 type BaseRequestOptions = {
     headers?: HeadersInitOrGetter;
-    cache?: RequestCache;
     signal?: AbortSignal;
 };
 /**
@@ -1490,6 +1583,22 @@ type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends
     };
 };
 
+type ExtractTriggerQuery<I> = I extends {
+    query: infer Q;
+} ? {
+    query?: Q;
+} : unknown;
+type ExtractTriggerBody<I> = I extends {
+    body: infer B;
+} ? {
+    body?: B;
+} : unknown;
+type ExtractTriggerParams<I> = I extends {
+    params: infer P;
+} ? {
+    params?: P;
+} : unknown;
+
 /**
  * Class-based builder for creating Spoosh instances with type-safe plugin inference.
  *
@@ -2001,6 +2110,7 @@ type CreateOperationOptions<TData, TError> = {
     /** Unique identifier for the hook instance. Persists across queryKey changes. */
     instanceId?: string;
 };
+
 declare function createOperationController<TData, TError>(options: CreateOperationOptions<TData, TError>): OperationController<TData, TError>;
 
 type InfiniteRequestOptions = {
@@ -2008,27 +2118,43 @@ type InfiniteRequestOptions = {
     params?: Record<string, string | number>;
     body?: unknown;
 };
-type PageContext<TData, TRequest = InfiniteRequestOptions> = {
-    response: TData | undefined;
-    allResponses: TData[];
+type InfinitePageStatus = "pending" | "loading" | "success" | "error" | "stale";
+interface InfinitePage<TData, TError, TMeta> {
+    status: InfinitePageStatus;
+    data?: TData;
+    error?: TError;
+    meta?: TMeta;
+    input?: InfiniteRequestOptions;
+}
+type InfiniteNextContext<TData, TError, TRequest, TMeta> = {
+    lastPage: InfinitePage<TData, TError, TMeta> | undefined;
+    pages: InfinitePage<TData, TError, TMeta>[];
+    request: TRequest;
+};
+type InfinitePrevContext<TData, TError, TRequest, TMeta> = {
+    firstPage: InfinitePage<TData, TError, TMeta> | undefined;
+    pages: InfinitePage<TData, TError, TMeta>[];
     request: TRequest;
 };
 type FetchDirection = "next" | "prev";
-type InfiniteReadState<TData, TItem, TError> = {
+type InfiniteTriggerOptions = Partial<InfiniteRequestOptions> & {
+    /** Bypass cache and force refetch. Default: true */
+    force?: boolean;
+};
+type InfiniteReadState<TData, TItem, TError, TMeta = Record<string, unknown>> = {
     data: TItem[] | undefined;
-    allResponses: TData[] | undefined;
-    allRequests: InfiniteRequestOptions[] | undefined;
+    pages: InfinitePage<TData, TError, TMeta>[];
     canFetchNext: boolean;
     canFetchPrev: boolean;
     error: TError | undefined;
 };
-type InfiniteReadController<TData, TItem, TError> = {
-    getState: () => InfiniteReadState<TData, TItem, TError>;
+type InfiniteReadController<TData, TItem, TError, TMeta = Record<string, unknown>> = {
+    getState: () => InfiniteReadState<TData, TItem, TError, TMeta>;
     getFetchingDirection: () => FetchDirection | null;
     subscribe: (callback: () => void) => () => void;
     fetchNext: () => Promise<void>;
     fetchPrev: () => Promise<void>;
-    refetch: () => Promise<void>;
+    trigger: (options?: InfiniteTriggerOptions) => Promise<void>;
     abort: () => void;
     mount: () => void;
     unmount: () => void;
@@ -2036,17 +2162,16 @@ type InfiniteReadController<TData, TItem, TError> = {
     getContext: () => PluginContext;
     setPluginOptions: (options: unknown) => void;
 };
-type CreateInfiniteReadOptions<TData, TItem, TError, TRequest> = {
+type CreateInfiniteReadOptions<TData, TItem, TError, TRequest, TMeta = Record<string, unknown>> = {
     path: string;
     method: HttpMethod;
     tags: string[];
     initialRequest: InfiniteRequestOptions;
-    baseOptionsForKey: object;
-    canFetchNext: (ctx: PageContext<TData, TRequest>) => boolean;
-    canFetchPrev?: (ctx: PageContext<TData, TRequest>) => boolean;
-    nextPageRequest: (ctx: PageContext<TData, TRequest>) => Partial<TRequest>;
-    prevPageRequest?: (ctx: PageContext<TData, TRequest>) => Partial<TRequest>;
-    merger: (responses: TData[]) => TItem[];
+    canFetchNext?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => boolean;
+    canFetchPrev?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => boolean;
+    nextPageRequest?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
+    prevPageRequest?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
+    merger: (pages: InfinitePage<TData, TError, TMeta>[]) => TItem[];
     stateManager: StateManager;
     eventEmitter: EventEmitter;
     pluginExecutor: PluginExecutor;
@@ -2054,7 +2179,8 @@ type CreateInfiniteReadOptions<TData, TItem, TError, TRequest> = {
     /** Unique identifier for the hook instance. Persists across queryKey changes. */
     instanceId?: string;
 };
-declare function createInfiniteReadController<TData, TItem, TError, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions>(options: CreateInfiniteReadOptions<TData, TItem, TError, TRequest>): InfiniteReadController<TData, TItem, TError>;
+
+declare function createInfiniteReadController<TData, TItem, TError, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions, TMeta = Record<string, unknown>>(options: CreateInfiniteReadOptions<TData, TItem, TError, TRequest, TMeta>): InfiniteReadController<TData, TItem, TError, TMeta>;
 
 /**
  * Status of an item in the queue.
@@ -2177,4 +2303,4 @@ declare class Semaphore {
     getWaitingCount(): number;
 }
 
-export { type AnyRequestOptions, type ApiSchema, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type DevtoolEvents, type EventEmitter, type EventListener, type EventOptions, type EventTracer, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HasReadMethod, type HasWriteMethod, type HeadersInitOrGetter, type HttpMethod, type HttpMethodKey, type InfiniteReadController, type InfiniteReadState, type InfiniteRequestOptions, type InstanceApiContext, type InstanceApiResolvers, type InstancePluginExecutor, type LifecyclePhase, type MergePluginInstanceApi, type MergePluginOptions, type MergePluginResults, type MethodOptionsMap, type OperationController, type OperationState, type OperationType, type PageContext, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextBase, type PluginContextExtensions, type PluginContextInput, type PluginExecutor, type PluginExportsRegistry, type PluginFactory, type PluginHandler, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginRequestOptions, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type QueueController, type QueueControllerConfig, type QueueControllerContext, type QueueItem, type QueueItemStatus, type QueueSelectorClient, type QueueStats, type QueueTriggerInput, type ReadClient, type ReadPaths, type ReadSchemaHelper, type RefetchEvent, type RequestCompleteEvent, type RequestOptions$1 as RequestOptions, type RequestTracer, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, Semaphore, type SetupContext, type Simplify, Spoosh, type SpooshBody, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshOptions, type SpooshOptionsInput, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StandaloneEvent, type StateManager, type StripPrefix, type TagMode, type TagOptions, type Trace, type TraceColor, type TraceEvent, type TraceInfo, type TraceListener, type TraceOptions, type TraceStage, type Transport, type TransportOption, type TransportOptionsMap, type TransportResponse, type WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, type WriteSelectorClient, __DEV__, buildUrl, clone, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createQueueController, createSelectorProxy, createStateManager, createTracer, executeFetch, extractMethodFromSelector, extractPathFromSelector, fetchTransport, form, generateTags, getContentType, isAbortError, isJsonBody, isNetworkError, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, removeHeaderKeys, resolveHeadersToRecord, resolvePath, resolvePathString, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded, xhrTransport };
+export { type AnyRequestOptions, type ApiSchema, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type DataChangeCallback, type DevtoolEvents, type EventEmitter, type EventListener, type EventOptions, type EventTracer, type ExecuteOptions, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type ExtractTriggerBody, type ExtractTriggerParams, type ExtractTriggerQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HasReadMethod, type HasWriteMethod, type HeadersInitOrGetter, type HttpMethod, type HttpMethodKey, type InfiniteNextContext, type InfinitePage, type InfinitePageStatus, type InfinitePrevContext, type InfiniteReadController, type InfiniteReadState, type InfiniteRequestOptions, type InfiniteTriggerOptions, type InstanceApiContext, type InstanceApiResolvers, type InstancePluginExecutor, type LifecyclePhase, type MergePluginInstanceApi, type MergePluginOptions, type MergePluginResults, type MethodOptionsMap, type OperationController, type OperationState, type OperationType, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextBase, type PluginContextExtensions, type PluginContextInput, type PluginExecutor, type PluginExportsRegistry, type PluginFactory, type PluginHandler, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginRequestOptions, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type QueueController, type QueueControllerConfig, type QueueControllerContext, type QueueItem, type QueueItemStatus, type QueueSelectorClient, type QueueStats, type QueueTriggerInput, type ReadClient, type ReadPaths, type ReadSchemaHelper, type RefetchEvent, type RequestCompleteEvent, type RequestOptions$1 as RequestOptions, type RequestTracer, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, Semaphore, type SetupContext, type Simplify, Spoosh, type SpooshBody, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshOptions, type SpooshOptionsInput, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StandaloneEvent, type StateManager, type StripPrefix, type Subscriber, type TagMode, type TagOptions, type Trace, type TraceColor, type TraceEvent, type TraceInfo, type TraceListener, type TraceOptions, type TraceStage, type Transport, type TransportOption, type TransportOptionsMap, type TransportResponse, type TypedPluginContext, type TypedPluginDefinition, type WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, type WriteSelectorClient, __DEV__, buildUrl, clone, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createQueueController, createSelectorProxy, createSpooshPlugin, createStateManager, createTracer, executeFetch, extractMethodFromSelector, extractPathFromSelector, fetchTransport, form, generateTags, getContentType, isAbortError, isJsonBody, isNetworkError, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, removeHeaderKeys, resolveHeadersToRecord, resolvePath, resolvePathString, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded, xhrTransport };