@spoosh/react 0.10.1 → 0.11.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ReadClient, TagMode, SpooshResponse, SpooshPlugin, PluginTypeConfig, MergePluginResults, WriteSelectorClient, SpooshBody, StateManager, EventEmitter, PluginExecutor, PluginArray, ResolveTypes, MergePluginOptions, ResolverContext, ResolveResultTypes, MergePluginInstanceApi, SpooshOptions } from '@spoosh/core';
+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';
 
 type SuccessResponse<T> = Extract<T, {
     data: unknown;
@@ -81,28 +81,28 @@ type ResponseInputFields<TQuery, TBody, TParamNames extends string> = [
 ] extends [never, never, never] ? object : {
     input: ReadInputFields<TQuery, TBody, TParamNames>;
 };
-type TriggerAwaitedReturn$1<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse$1<T> = T extends {
+type TriggerAwaitedReturn$2<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse$2<T> = T extends {
     input: infer I;
 } ? I : never;
-type ExtractTriggerQuery$1<I> = I extends {
+type ExtractTriggerQuery$2<I> = I extends {
     query: infer Q;
 } ? {
     query?: Q;
 } : unknown;
-type ExtractTriggerBody$1<I> = I extends {
+type ExtractTriggerBody$2<I> = I extends {
     body: infer B;
 } ? {
     body?: B;
 } : unknown;
-type ExtractTriggerParams$1<I> = I extends {
+type ExtractTriggerParams$2<I> = I extends {
     params: infer P;
 } ? {
     params?: P;
 } : unknown;
-type TriggerOptions<T> = ExtractInputFromResponse$1<TriggerAwaitedReturn$1<T>> extends infer I ? [I] extends [never] ? {
+type TriggerOptions<T> = ExtractInputFromResponse$2<TriggerAwaitedReturn$2<T>> extends infer I ? [I] extends [never] ? {
     force?: boolean;
-} : ExtractTriggerQuery$1<I> & ExtractTriggerBody$1<I> & ExtractTriggerParams$1<I> & {
+} : ExtractTriggerQuery$2<I> & ExtractTriggerBody$2<I> & ExtractTriggerParams$2<I> & {
     /** Force refetch even if data is cached */
     force?: boolean;
 } : {
@@ -160,30 +160,30 @@ 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<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 {
+type ExtractTriggerQuery$1<I> = I extends {
     query: infer Q;
 } ? undefined extends Q ? {
     query?: Exclude<Q, undefined>;
 } : {
     query: Q;
 } : unknown;
-type ExtractTriggerBody<I> = I extends {
+type ExtractTriggerBody$1<I> = I extends {
     body: infer B;
 } ? undefined extends B ? {
     body?: Exclude<B, undefined> | SpooshBody<Exclude<B, undefined>>;
 } : {
     body: B | SpooshBody<B>;
 } : unknown;
-type ExtractTriggerParams<I> = I extends {
+type ExtractTriggerParams$1<I> = I extends {
     params: infer P;
 } ? {
     params: P;
 } : unknown;
-type WriteTriggerInput<T> = ExtractInputFromResponse<TriggerAwaitedReturn<T>> extends infer I ? [I] extends [never] ? object : ExtractTriggerQuery<I> & ExtractTriggerBody<I> & ExtractTriggerParams<I> : object;
+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;
 /**
  * Result returned by `useWrite` hook.
  *
@@ -209,6 +209,73 @@ 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 {
+    input: infer I;
+} ? I : never;
+type ExtractTriggerQuery<I> = I extends {
+    query: infer Q;
+} ? undefined extends Q ? {
+    query?: Exclude<Q, undefined>;
+} : {
+    query: Q;
+} : unknown;
+type ExtractTriggerBody<I> = I extends {
+    body: infer B;
+} ? undefined extends B ? {
+    body?: Exclude<B, undefined> | SpooshBody<Exclude<B, undefined>>;
+} : {
+    body: B | SpooshBody<B>;
+} : unknown;
+type ExtractTriggerParams<I> = I extends {
+    params: infer P;
+} ? {
+    params: P;
+} : unknown;
+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;
+/**
+ * Options for useQueue hook.
+ */
+interface UseQueueOptions {
+    /** Maximum concurrent operations. Defaults to 3. */
+    concurrency?: number;
+}
+/**
+ * Result returned by useQueue hook.
+ *
+ * @template TData - The response data type
+ * @template TError - The error type
+ * @template TTriggerInput - The trigger input type
+ * @template TMeta - Plugin-contributed metadata on queue items
+ */
+type UseQueueResult<TData, TError, TTriggerInput, TMeta = object> = {
+    /** Add item to queue and execute. Returns promise for this item. */
+    trigger: (input?: TTriggerInput) => Promise<SpooshResponse<TData, TError>>;
+    /** All tasks in queue with their current status */
+    tasks: QueueItem<TData, TError, TMeta>[];
+    /** Queue statistics (pending/loading/settled/success/failed/total/percentage) */
+    stats: QueueStats;
+    /** Abort task by ID, or all tasks if no ID */
+    abort: (id?: string) => void;
+    /** Retry failed task by ID, or all failed if no ID */
+    retry: (id?: string) => Promise<void>;
+    /** Remove specific task by ID (aborts if active) */
+    remove: (id: string) => void;
+    /** Remove all settled tasks (success, error, aborted). Keeps pending/running. */
+    removeSettled: () => void;
+    /** Abort all and clear queue */
+    clear: () => void;
+};
+/**
+ * API client type for queue selector.
+ * Supports all HTTP methods (GET, POST, PUT, PATCH, DELETE).
+ */
+type QueueApiClient<TSchema, TDefaultError> = QueueSelectorClient<TSchema, TDefaultError>;
+
 type TagModeInArray = "all" | "self";
 type AnyInfiniteRequestOptions = {
     query?: Record<string, unknown>;
@@ -311,6 +378,9 @@ 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>>;
 type ResolvedWriteOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["write"], WriteResolverContext<TSchema, TMethod, TDefaultError>>;
 type ResolvedWriteTriggerOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["writeTrigger"], WriteResolverContext<TSchema, TMethod, TDefaultError>>;
+type QueueResolverContext<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>>;
+type ResolvedQueueOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["queue"], QueueResolverContext<TSchema, TMethod, TDefaultError>>;
+type ResolvedQueueTriggerOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["queueTrigger"], QueueResolverContext<TSchema, TMethod, TDefaultError>>;
 type UseReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     <TReadFn extends (api: ReadApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>, TReadOpts>(readFn: TReadFn, readOptions: TReadOpts & BaseReadOptions & ResolveTypes<MergePluginOptions<TPlugins>["read"], ResolverContext<TSchema, ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseParamNames<TReadFn> extends never ? never : Record<ExtractResponseParamNames<TReadFn>, string | number>>>): BaseReadResult<ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, ResolveResultTypes<MergePluginResults<TPlugins>["read"], TReadOpts>, TriggerOptions<TReadFn>> & ResponseInputFields<ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseParamNames<TReadFn>>;
     <TReadFn extends (api: ReadApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>>(readFn: TReadFn): BaseReadResult<ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, MergePluginResults<TPlugins>["read"], TriggerOptions<TReadFn>> & ResponseInputFields<ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseParamNames<TReadFn>>;
@@ -318,6 +388,9 @@ type UseReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
 type UseWriteFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     <TWriteFn extends (api: WriteApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>, TWriteOpts extends ResolvedWriteOptions<TSchema, TPlugins, TWriteFn, TDefaultError> = ResolvedWriteOptions<TSchema, TPlugins, TWriteFn, TDefaultError>>(writeFn: TWriteFn, writeOptions?: TWriteOpts): BaseWriteResult<ExtractMethodData<TWriteFn>, InferError<ExtractMethodError<TWriteFn>, TDefaultError>, WriteTriggerInput<TWriteFn> & ResolvedWriteTriggerOptions<TSchema, TPlugins, TWriteFn, TDefaultError>, ResolveResultTypes<MergePluginResults<TPlugins>["write"], TWriteOpts>> & WriteResponseInputFields<ExtractMethodQuery<TWriteFn>, ExtractMethodBody<TWriteFn>, ExtractResponseParamNames<TWriteFn>>;
 };
+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 {
@@ -390,6 +463,26 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      * ```
      */
     useInfiniteRead: UseInfiniteReadFn<TDefaultError, TSchema, TPlugins>;
+    /**
+     * React hook for queued operations with concurrency control.
+     *
+     * @param queueFn - Function that selects the API endpoint
+     * @param queueOptions - Optional configuration including `concurrency`
+     * @returns Object containing `trigger`, `queue`, `progress`, `abort`, `retry`, `remove`, `clear`
+     *
+     * @example
+     * ```tsx
+     * const { trigger, queue, progress } = useQueue(
+     *   (api) => api("uploads").POST(),
+     *   { concurrency: 2 }
+     * );
+     *
+     * for (const file of files) {
+     *   trigger({ body: form({ file }) });
+     * }
+     * ```
+     */
+    useQueue: UseQueueFn<TDefaultError, TSchema, TPlugins>;
 } & MergePluginInstanceApi<TPlugins, TSchema>;
 /**
  * Shape of a Spoosh instance required for creating React hooks.
@@ -439,4 +532,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 ReadApiClient, type ResponseInputFields, type SpooshReactHooks, type TriggerOptions, type UseInfiniteReadResult, type UseReadResult, type UseWriteResult, type WriteApiClient, type WriteResponseInputFields, create };
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ReadClient, TagMode, SpooshResponse, SpooshPlugin, PluginTypeConfig, MergePluginResults, WriteSelectorClient, SpooshBody, StateManager, EventEmitter, PluginExecutor, PluginArray, ResolveTypes, MergePluginOptions, ResolverContext, ResolveResultTypes, MergePluginInstanceApi, SpooshOptions } from '@spoosh/core';
+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';
 
 type SuccessResponse<T> = Extract<T, {
     data: unknown;
@@ -81,28 +81,28 @@ type ResponseInputFields<TQuery, TBody, TParamNames extends string> = [
 ] extends [never, never, never] ? object : {
     input: ReadInputFields<TQuery, TBody, TParamNames>;
 };
-type TriggerAwaitedReturn$1<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse$1<T> = T extends {
+type TriggerAwaitedReturn$2<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse$2<T> = T extends {
     input: infer I;
 } ? I : never;
-type ExtractTriggerQuery$1<I> = I extends {
+type ExtractTriggerQuery$2<I> = I extends {
     query: infer Q;
 } ? {
     query?: Q;
 } : unknown;
-type ExtractTriggerBody$1<I> = I extends {
+type ExtractTriggerBody$2<I> = I extends {
     body: infer B;
 } ? {
     body?: B;
 } : unknown;
-type ExtractTriggerParams$1<I> = I extends {
+type ExtractTriggerParams$2<I> = I extends {
     params: infer P;
 } ? {
     params?: P;
 } : unknown;
-type TriggerOptions<T> = ExtractInputFromResponse$1<TriggerAwaitedReturn$1<T>> extends infer I ? [I] extends [never] ? {
+type TriggerOptions<T> = ExtractInputFromResponse$2<TriggerAwaitedReturn$2<T>> extends infer I ? [I] extends [never] ? {
     force?: boolean;
-} : ExtractTriggerQuery$1<I> & ExtractTriggerBody$1<I> & ExtractTriggerParams$1<I> & {
+} : ExtractTriggerQuery$2<I> & ExtractTriggerBody$2<I> & ExtractTriggerParams$2<I> & {
     /** Force refetch even if data is cached */
     force?: boolean;
 } : {
@@ -160,30 +160,30 @@ 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<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 {
+type ExtractTriggerQuery$1<I> = I extends {
     query: infer Q;
 } ? undefined extends Q ? {
     query?: Exclude<Q, undefined>;
 } : {
     query: Q;
 } : unknown;
-type ExtractTriggerBody<I> = I extends {
+type ExtractTriggerBody$1<I> = I extends {
     body: infer B;
 } ? undefined extends B ? {
     body?: Exclude<B, undefined> | SpooshBody<Exclude<B, undefined>>;
 } : {
     body: B | SpooshBody<B>;
 } : unknown;
-type ExtractTriggerParams<I> = I extends {
+type ExtractTriggerParams$1<I> = I extends {
     params: infer P;
 } ? {
     params: P;
 } : unknown;
-type WriteTriggerInput<T> = ExtractInputFromResponse<TriggerAwaitedReturn<T>> extends infer I ? [I] extends [never] ? object : ExtractTriggerQuery<I> & ExtractTriggerBody<I> & ExtractTriggerParams<I> : object;
+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;
 /**
  * Result returned by `useWrite` hook.
  *
@@ -209,6 +209,73 @@ 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 {
+    input: infer I;
+} ? I : never;
+type ExtractTriggerQuery<I> = I extends {
+    query: infer Q;
+} ? undefined extends Q ? {
+    query?: Exclude<Q, undefined>;
+} : {
+    query: Q;
+} : unknown;
+type ExtractTriggerBody<I> = I extends {
+    body: infer B;
+} ? undefined extends B ? {
+    body?: Exclude<B, undefined> | SpooshBody<Exclude<B, undefined>>;
+} : {
+    body: B | SpooshBody<B>;
+} : unknown;
+type ExtractTriggerParams<I> = I extends {
+    params: infer P;
+} ? {
+    params: P;
+} : unknown;
+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;
+/**
+ * Options for useQueue hook.
+ */
+interface UseQueueOptions {
+    /** Maximum concurrent operations. Defaults to 3. */
+    concurrency?: number;
+}
+/**
+ * Result returned by useQueue hook.
+ *
+ * @template TData - The response data type
+ * @template TError - The error type
+ * @template TTriggerInput - The trigger input type
+ * @template TMeta - Plugin-contributed metadata on queue items
+ */
+type UseQueueResult<TData, TError, TTriggerInput, TMeta = object> = {
+    /** Add item to queue and execute. Returns promise for this item. */
+    trigger: (input?: TTriggerInput) => Promise<SpooshResponse<TData, TError>>;
+    /** All tasks in queue with their current status */
+    tasks: QueueItem<TData, TError, TMeta>[];
+    /** Queue statistics (pending/loading/settled/success/failed/total/percentage) */
+    stats: QueueStats;
+    /** Abort task by ID, or all tasks if no ID */
+    abort: (id?: string) => void;
+    /** Retry failed task by ID, or all failed if no ID */
+    retry: (id?: string) => Promise<void>;
+    /** Remove specific task by ID (aborts if active) */
+    remove: (id: string) => void;
+    /** Remove all settled tasks (success, error, aborted). Keeps pending/running. */
+    removeSettled: () => void;
+    /** Abort all and clear queue */
+    clear: () => void;
+};
+/**
+ * API client type for queue selector.
+ * Supports all HTTP methods (GET, POST, PUT, PATCH, DELETE).
+ */
+type QueueApiClient<TSchema, TDefaultError> = QueueSelectorClient<TSchema, TDefaultError>;
+
 type TagModeInArray = "all" | "self";
 type AnyInfiniteRequestOptions = {
     query?: Record<string, unknown>;
@@ -311,6 +378,9 @@ 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>>;
 type ResolvedWriteOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["write"], WriteResolverContext<TSchema, TMethod, TDefaultError>>;
 type ResolvedWriteTriggerOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["writeTrigger"], WriteResolverContext<TSchema, TMethod, TDefaultError>>;
+type QueueResolverContext<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>>;
+type ResolvedQueueOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["queue"], QueueResolverContext<TSchema, TMethod, TDefaultError>>;
+type ResolvedQueueTriggerOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["queueTrigger"], QueueResolverContext<TSchema, TMethod, TDefaultError>>;
 type UseReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     <TReadFn extends (api: ReadApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>, TReadOpts>(readFn: TReadFn, readOptions: TReadOpts & BaseReadOptions & ResolveTypes<MergePluginOptions<TPlugins>["read"], ResolverContext<TSchema, ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseParamNames<TReadFn> extends never ? never : Record<ExtractResponseParamNames<TReadFn>, string | number>>>): BaseReadResult<ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, ResolveResultTypes<MergePluginResults<TPlugins>["read"], TReadOpts>, TriggerOptions<TReadFn>> & ResponseInputFields<ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseParamNames<TReadFn>>;
     <TReadFn extends (api: ReadApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>>(readFn: TReadFn): BaseReadResult<ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, MergePluginResults<TPlugins>["read"], TriggerOptions<TReadFn>> & ResponseInputFields<ExtractResponseQuery<TReadFn>, ExtractResponseBody<TReadFn>, ExtractResponseParamNames<TReadFn>>;
@@ -318,6 +388,9 @@ type UseReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
 type UseWriteFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     <TWriteFn extends (api: WriteApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>, TWriteOpts extends ResolvedWriteOptions<TSchema, TPlugins, TWriteFn, TDefaultError> = ResolvedWriteOptions<TSchema, TPlugins, TWriteFn, TDefaultError>>(writeFn: TWriteFn, writeOptions?: TWriteOpts): BaseWriteResult<ExtractMethodData<TWriteFn>, InferError<ExtractMethodError<TWriteFn>, TDefaultError>, WriteTriggerInput<TWriteFn> & ResolvedWriteTriggerOptions<TSchema, TPlugins, TWriteFn, TDefaultError>, ResolveResultTypes<MergePluginResults<TPlugins>["write"], TWriteOpts>> & WriteResponseInputFields<ExtractMethodQuery<TWriteFn>, ExtractMethodBody<TWriteFn>, ExtractResponseParamNames<TWriteFn>>;
 };
+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 {
@@ -390,6 +463,26 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      * ```
      */
     useInfiniteRead: UseInfiniteReadFn<TDefaultError, TSchema, TPlugins>;
+    /**
+     * React hook for queued operations with concurrency control.
+     *
+     * @param queueFn - Function that selects the API endpoint
+     * @param queueOptions - Optional configuration including `concurrency`
+     * @returns Object containing `trigger`, `queue`, `progress`, `abort`, `retry`, `remove`, `clear`
+     *
+     * @example
+     * ```tsx
+     * const { trigger, queue, progress } = useQueue(
+     *   (api) => api("uploads").POST(),
+     *   { concurrency: 2 }
+     * );
+     *
+     * for (const file of files) {
+     *   trigger({ body: form({ file }) });
+     * }
+     * ```
+     */
+    useQueue: UseQueueFn<TDefaultError, TSchema, TPlugins>;
 } & MergePluginInstanceApi<TPlugins, TSchema>;
 /**
  * Shape of a Spoosh instance required for creating React hooks.
@@ -439,4 +532,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 ReadApiClient, type ResponseInputFields, type SpooshReactHooks, type TriggerOptions, type UseInfiniteReadResult, type UseReadResult, type UseWriteResult, type WriteApiClient, type WriteResponseInputFields, create };
+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 };

package/dist/index.js

@@ -588,6 +588,72 @@ function createUseInfiniteRead(options) {
   };
 }
 
+// src/useQueue/index.ts
+var import_react4 = require("react");
+var import_core4 = require("@spoosh/core");
+function createUseQueue(options) {
+  const { api, stateManager, pluginExecutor, eventEmitter } = options;
+  function useQueue(queueFn, queueOptions) {
+    (0, import_react4.useId)();
+    const selectorResultRef = (0, import_react4.useRef)({
+      call: null,
+      selector: null
+    });
+    const selectorProxy = (0, import_core4.createSelectorProxy)((result) => {
+      selectorResultRef.current = result;
+    });
+    queueFn(selectorProxy);
+    const capturedCall = selectorResultRef.current.call;
+    const capturedSelector = selectorResultRef.current.selector;
+    const captured = capturedCall ?? capturedSelector;
+    if (!captured) {
+      throw new Error(
+        'useQueue requires selecting an HTTP method. Example: useQueue((api) => api("uploads").POST())'
+      );
+    }
+    const { concurrency, ...hookOptions } = queueOptions ?? {};
+    const controllerRef = (0, import_react4.useRef)(null);
+    if (!controllerRef.current) {
+      const config = {
+        path: captured.path,
+        method: captured.method,
+        concurrency,
+        operationType: "queue",
+        hookOptions
+      };
+      controllerRef.current = (0, import_core4.createQueueController)(config, {
+        api,
+        stateManager,
+        eventEmitter,
+        pluginExecutor
+      });
+    }
+    const controller = controllerRef.current;
+    (0, import_react4.useEffect)(() => {
+      if (concurrency !== void 0) {
+        controller.setConcurrency(concurrency);
+      }
+    }, [concurrency, controller]);
+    const tasks = (0, import_react4.useSyncExternalStore)(
+      controller.subscribe,
+      controller.getQueue,
+      controller.getQueue
+    );
+    return {
+      trigger: (input) => controller.trigger(input ?? {}),
+      tasks,
+      stats: controller.getStats(),
+      abort: controller.abort,
+      retry: controller.retry,
+      remove: controller.remove,
+      removeSettled: controller.removeSettled,
+      clear: controller.clear
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+  }
+  return useQueue;
+}
+
 // src/create/index.ts
 function create(instance) {
   const { api, stateManager, eventEmitter, pluginExecutor } = instance;
@@ -609,6 +675,12 @@ function create(instance) {
     eventEmitter,
     pluginExecutor
   });
+  const useQueue = createUseQueue({
+    api,
+    stateManager,
+    eventEmitter,
+    pluginExecutor
+  });
   const plugins = pluginExecutor.getPlugins();
   const setupContext = {
     stateManager,
@@ -637,6 +709,7 @@ function create(instance) {
     useRead,
     useWrite,
     useInfiniteRead,
+    useQueue,
     ...instanceApis
   };
 }

package/dist/index.mjs

@@ -597,6 +597,75 @@ function createUseInfiniteRead(options) {
   };
 }
 
+// src/useQueue/index.ts
+import { useSyncExternalStore as useSyncExternalStore4, useRef as useRef4, useId as useId4, useEffect as useEffect3 } from "react";
+import {
+  createSelectorProxy as createSelectorProxy4,
+  createQueueController
+} from "@spoosh/core";
+function createUseQueue(options) {
+  const { api, stateManager, pluginExecutor, eventEmitter } = options;
+  function useQueue(queueFn, queueOptions) {
+    useId4();
+    const selectorResultRef = useRef4({
+      call: null,
+      selector: null
+    });
+    const selectorProxy = createSelectorProxy4((result) => {
+      selectorResultRef.current = result;
+    });
+    queueFn(selectorProxy);
+    const capturedCall = selectorResultRef.current.call;
+    const capturedSelector = selectorResultRef.current.selector;
+    const captured = capturedCall ?? capturedSelector;
+    if (!captured) {
+      throw new Error(
+        'useQueue requires selecting an HTTP method. Example: useQueue((api) => api("uploads").POST())'
+      );
+    }
+    const { concurrency, ...hookOptions } = queueOptions ?? {};
+    const controllerRef = useRef4(null);
+    if (!controllerRef.current) {
+      const config = {
+        path: captured.path,
+        method: captured.method,
+        concurrency,
+        operationType: "queue",
+        hookOptions
+      };
+      controllerRef.current = createQueueController(config, {
+        api,
+        stateManager,
+        eventEmitter,
+        pluginExecutor
+      });
+    }
+    const controller = controllerRef.current;
+    useEffect3(() => {
+      if (concurrency !== void 0) {
+        controller.setConcurrency(concurrency);
+      }
+    }, [concurrency, controller]);
+    const tasks = useSyncExternalStore4(
+      controller.subscribe,
+      controller.getQueue,
+      controller.getQueue
+    );
+    return {
+      trigger: (input) => controller.trigger(input ?? {}),
+      tasks,
+      stats: controller.getStats(),
+      abort: controller.abort,
+      retry: controller.retry,
+      remove: controller.remove,
+      removeSettled: controller.removeSettled,
+      clear: controller.clear
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    };
+  }
+  return useQueue;
+}
+
 // src/create/index.ts
 function create(instance) {
   const { api, stateManager, eventEmitter, pluginExecutor } = instance;
@@ -618,6 +687,12 @@ function create(instance) {
     eventEmitter,
     pluginExecutor
   });
+  const useQueue = createUseQueue({
+    api,
+    stateManager,
+    eventEmitter,
+    pluginExecutor
+  });
   const plugins = pluginExecutor.getPlugins();
   const setupContext = {
     stateManager,
@@ -646,6 +721,7 @@ function create(instance) {
     useRead,
     useWrite,
     useInfiniteRead,
+    useQueue,
     ...instanceApis
   };
 }

package/package.json

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