@spoosh/core 0.13.3 → 0.14.1

package/dist/index.d.mts

@@ -210,6 +210,7 @@ type EventEmitter = {
 declare function createEventEmitter(): EventEmitter;
 
 type Subscriber = () => void;
+type DataChangeCallback = (key: string, oldData: unknown, newData: unknown) => void;
 type CacheEntryWithKey<TData = unknown, TError = unknown> = {
     key: string;
     entry: CacheEntry<TData, TError>;
@@ -241,6 +242,11 @@ type StateManager = {
     setPendingPromise: (key: string, promise: Promise<unknown> | undefined) => void;
     /** Get a pending promise for a query key */
     getPendingPromise: (key: string) => Promise<unknown> | undefined;
+    /**
+     * Register a callback to be invoked when cache data changes.
+     * @returns Unsubscribe function
+     */
+    onDataChange: (callback: DataChangeCallback) => () => void;
     clear: () => void;
 };
 declare function createStateManager(): StateManager;
@@ -429,7 +435,7 @@ interface EventTracer {
     emit(msg: string, options?: EventOptions): void;
 }
 
-type OperationType = "read" | "write" | "infiniteRead";
+type OperationType = "read" | "write" | "infiniteRead" | "queue";
 type LifecyclePhase = "onMount" | "onUnmount" | "onUpdate";
 type OperationState<TData = unknown, TError = unknown> = {
     data: TData | undefined;
@@ -594,8 +600,11 @@ type PluginTypeConfig = {
     writeOptions?: object;
     infiniteReadOptions?: object;
     writeTriggerOptions?: object;
+    queueOptions?: object;
+    queueTriggerOptions?: object;
     readResult?: object;
     writeResult?: object;
+    queueResult?: object;
     instanceApi?: object;
 };
 /**
@@ -1024,6 +1033,15 @@ type ExtractInfiniteReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types
 type ExtractWriteTriggerOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     writeTriggerOptions: infer W;
 } ? W : object : object;
+type ExtractQueueOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    queueOptions: infer Q;
+} ? Q : object : object;
+type ExtractQueueTriggerOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    queueTriggerOptions: infer Q;
+} ? Q : object : object;
+type ExtractQueueResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    queueResult: infer Q;
+} ? Q : object : object;
 type ExtractReadResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     readResult: infer R;
 } ? R : object : object;
@@ -1039,10 +1057,13 @@ type MergePluginOptions<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>
     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]>>;
 };
 type MergePluginResults<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
     read: UnionToIntersection<ExtractReadResult<TPlugins[number]>>;
     write: UnionToIntersection<ExtractWriteResult<TPlugins[number]>>;
+    queue: UnionToIntersection<ExtractQueueResult<TPlugins[number]>>;
 };
 type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
 type PluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]> = {
@@ -1430,6 +1451,22 @@ type WriteSelectorPathMethods<TSchema, TPath extends string, TDefaultError> = Fi
  * Used by useWrite for selecting endpoints. All input goes to trigger().
  */
 type WriteSelectorClient<TSchema, TDefaultError = unknown> = <TPath extends WritePaths<TSchema> | (string & {})>(path: TPath) => HasWriteMethod<TSchema, TPath> extends true ? WriteSelectorPathMethods<TSchema, TPath, TDefaultError> : never;
+/**
+ * Method function type for queue selectors - accepts no arguments.
+ * All input (body, query, params) is passed to trigger() instead.
+ */
+type QueueSelectorMethodFn<TMethodConfig, TDefaultError, TUserPath extends string> = () => Promise<MethodResponse<TMethodConfig, TDefaultError, TUserPath>>;
+/**
+ * Queue selector path methods - all HTTP methods, accepting no arguments.
+ */
+type QueueSelectorPathMethods<TSchema, TPath extends string, TDefaultError> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? Simplify<{
+    [M in HttpMethod as M extends keyof TSchema[TKey] ? M : never]: M extends keyof TSchema[TKey] ? QueueSelectorMethodFn<TSchema[TKey][M], TDefaultError, TPath> : never;
+}> : never : never;
+/**
+ * Queue selector client - all HTTP methods, accepting no arguments.
+ * Used by useQueue for selecting endpoints. All input goes to trigger().
+ */
+type QueueSelectorClient<TSchema, TDefaultError = unknown> = <TPath extends SchemaPaths<TSchema> | (string & {})>(path: TPath) => QueueSelectorPathMethods<TSchema, TPath, TDefaultError>;
 
 type PluginArray = readonly SpooshPlugin<PluginTypeConfig>[];
 interface SpooshConfig<TPlugins extends PluginArray = PluginArray> {
@@ -2019,4 +2056,125 @@ type CreateInfiniteReadOptions<TData, TItem, TError, TRequest> = {
 };
 declare function createInfiniteReadController<TData, TItem, TError, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions>(options: CreateInfiniteReadOptions<TData, TItem, TError, TRequest>): InfiniteReadController<TData, TItem, TError>;
 
-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 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, 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, 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 };
+/**
+ * Status of an item in the queue.
+ */
+type QueueItemStatus = "pending" | "running" | "success" | "error" | "aborted";
+/**
+ * Represents a single item in the queue.
+ */
+interface QueueItem<TData = unknown, TError = unknown, TMeta = Record<string, unknown>> {
+    /** Unique identifier for this queue item */
+    id: string;
+    /** Current status of the item */
+    status: QueueItemStatus;
+    /** Response data on success */
+    data?: TData;
+    /** Error on failure */
+    error?: TError;
+    /** Original trigger input */
+    input?: {
+        body?: unknown;
+        query?: unknown;
+        params?: Record<string, string | number>;
+    };
+    /** Plugin-contributed metadata (e.g., progress, transformedData) */
+    meta?: TMeta;
+}
+/**
+ * Statistics information for the queue.
+ */
+interface QueueStats {
+    /** Number of pending items waiting to run */
+    pending: number;
+    /** Number of currently running items */
+    running: number;
+    /** Number of settled items (success, error, or aborted) */
+    settled: number;
+    /** Number of successful items */
+    success: number;
+    /** Number of failed items (error or aborted) */
+    failed: number;
+    /** Total number of items in queue */
+    total: number;
+    /** Completion percentage (0-100) */
+    percentage: number;
+}
+/**
+ * Input type for queue trigger.
+ */
+interface QueueTriggerInput {
+    /** Custom ID for this queue item. If not provided, one will be auto-generated. */
+    id?: string;
+    body?: unknown;
+    query?: unknown;
+    params?: Record<string, string | number>;
+}
+/**
+ * Queue controller instance.
+ * Framework-agnostic - can be used directly in Angular, Vue, etc.
+ */
+interface QueueController<TData = unknown, TError = unknown, TMeta = Record<string, unknown>> {
+    /** Add item to queue and execute. Returns promise that resolves when item completes. */
+    trigger: (input: QueueTriggerInput) => Promise<SpooshResponse<TData, TError>>;
+    /** Get current queue state */
+    getQueue: () => QueueItem<TData, TError, TMeta>[];
+    /** Get queue statistics */
+    getStats: () => QueueStats;
+    /** Subscribe to queue state changes */
+    subscribe: (callback: () => void) => () => void;
+    /** Abort item by ID, or all items if no ID provided */
+    abort: (id?: string) => void;
+    /** Retry failed/aborted item by ID, or all failed items if no ID provided */
+    retry: (id?: string) => Promise<void>;
+    /** Remove specific item by ID (aborts if active) */
+    remove: (id: string) => void;
+    /** Remove all settled items (success, error, aborted). Keeps pending/running. */
+    removeSettled: () => void;
+    /** Abort all and clear entire queue */
+    clear: () => void;
+    /** Update the concurrency limit */
+    setConcurrency: (concurrency: number) => void;
+}
+/**
+ * Configuration for creating a queue controller.
+ */
+interface QueueControllerConfig {
+    /** API path */
+    path: string;
+    /** HTTP method */
+    method: string;
+    /** Maximum concurrent operations. Defaults to 3. */
+    concurrency?: number;
+    /** Operation type for plugin middleware */
+    operationType: "read" | "write" | "queue";
+    /** Hook-level plugin options (e.g., progress, retries) */
+    hookOptions?: Record<string, unknown>;
+}
+
+interface QueueControllerContext {
+    api: unknown;
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    pluginExecutor: InstancePluginExecutor;
+}
+declare function createQueueController<TData, TError, TMeta = Record<string, unknown>>(config: QueueControllerConfig, context: QueueControllerContext): QueueController<TData, TError, TMeta>;
+
+/**
+ * Semaphore for controlling concurrent access.
+ * Used to limit the number of concurrent operations in the queue.
+ */
+declare class Semaphore {
+    private max;
+    private current;
+    private waiting;
+    constructor(max: number);
+    acquire(): Promise<boolean>;
+    release(): void;
+    setConcurrency(max: number): void;
+    reset(): void;
+    getCurrent(): number;
+    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 };

package/dist/index.d.ts

@@ -210,6 +210,7 @@ type EventEmitter = {
 declare function createEventEmitter(): EventEmitter;
 
 type Subscriber = () => void;
+type DataChangeCallback = (key: string, oldData: unknown, newData: unknown) => void;
 type CacheEntryWithKey<TData = unknown, TError = unknown> = {
     key: string;
     entry: CacheEntry<TData, TError>;
@@ -241,6 +242,11 @@ type StateManager = {
     setPendingPromise: (key: string, promise: Promise<unknown> | undefined) => void;
     /** Get a pending promise for a query key */
     getPendingPromise: (key: string) => Promise<unknown> | undefined;
+    /**
+     * Register a callback to be invoked when cache data changes.
+     * @returns Unsubscribe function
+     */
+    onDataChange: (callback: DataChangeCallback) => () => void;
     clear: () => void;
 };
 declare function createStateManager(): StateManager;
@@ -429,7 +435,7 @@ interface EventTracer {
     emit(msg: string, options?: EventOptions): void;
 }
 
-type OperationType = "read" | "write" | "infiniteRead";
+type OperationType = "read" | "write" | "infiniteRead" | "queue";
 type LifecyclePhase = "onMount" | "onUnmount" | "onUpdate";
 type OperationState<TData = unknown, TError = unknown> = {
     data: TData | undefined;
@@ -594,8 +600,11 @@ type PluginTypeConfig = {
     writeOptions?: object;
     infiniteReadOptions?: object;
     writeTriggerOptions?: object;
+    queueOptions?: object;
+    queueTriggerOptions?: object;
     readResult?: object;
     writeResult?: object;
+    queueResult?: object;
     instanceApi?: object;
 };
 /**
@@ -1024,6 +1033,15 @@ type ExtractInfiniteReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types
 type ExtractWriteTriggerOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     writeTriggerOptions: infer W;
 } ? W : object : object;
+type ExtractQueueOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    queueOptions: infer Q;
+} ? Q : object : object;
+type ExtractQueueTriggerOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    queueTriggerOptions: infer Q;
+} ? Q : object : object;
+type ExtractQueueResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    queueResult: infer Q;
+} ? Q : object : object;
 type ExtractReadResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     readResult: infer R;
 } ? R : object : object;
@@ -1039,10 +1057,13 @@ type MergePluginOptions<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>
     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]>>;
 };
 type MergePluginResults<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
     read: UnionToIntersection<ExtractReadResult<TPlugins[number]>>;
     write: UnionToIntersection<ExtractWriteResult<TPlugins[number]>>;
+    queue: UnionToIntersection<ExtractQueueResult<TPlugins[number]>>;
 };
 type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
 type PluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]> = {
@@ -1430,6 +1451,22 @@ type WriteSelectorPathMethods<TSchema, TPath extends string, TDefaultError> = Fi
  * Used by useWrite for selecting endpoints. All input goes to trigger().
  */
 type WriteSelectorClient<TSchema, TDefaultError = unknown> = <TPath extends WritePaths<TSchema> | (string & {})>(path: TPath) => HasWriteMethod<TSchema, TPath> extends true ? WriteSelectorPathMethods<TSchema, TPath, TDefaultError> : never;
+/**
+ * Method function type for queue selectors - accepts no arguments.
+ * All input (body, query, params) is passed to trigger() instead.
+ */
+type QueueSelectorMethodFn<TMethodConfig, TDefaultError, TUserPath extends string> = () => Promise<MethodResponse<TMethodConfig, TDefaultError, TUserPath>>;
+/**
+ * Queue selector path methods - all HTTP methods, accepting no arguments.
+ */
+type QueueSelectorPathMethods<TSchema, TPath extends string, TDefaultError> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? Simplify<{
+    [M in HttpMethod as M extends keyof TSchema[TKey] ? M : never]: M extends keyof TSchema[TKey] ? QueueSelectorMethodFn<TSchema[TKey][M], TDefaultError, TPath> : never;
+}> : never : never;
+/**
+ * Queue selector client - all HTTP methods, accepting no arguments.
+ * Used by useQueue for selecting endpoints. All input goes to trigger().
+ */
+type QueueSelectorClient<TSchema, TDefaultError = unknown> = <TPath extends SchemaPaths<TSchema> | (string & {})>(path: TPath) => QueueSelectorPathMethods<TSchema, TPath, TDefaultError>;
 
 type PluginArray = readonly SpooshPlugin<PluginTypeConfig>[];
 interface SpooshConfig<TPlugins extends PluginArray = PluginArray> {
@@ -2019,4 +2056,125 @@ type CreateInfiniteReadOptions<TData, TItem, TError, TRequest> = {
 };
 declare function createInfiniteReadController<TData, TItem, TError, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions>(options: CreateInfiniteReadOptions<TData, TItem, TError, TRequest>): InfiniteReadController<TData, TItem, TError>;
 
-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 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, 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, 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 };
+/**
+ * Status of an item in the queue.
+ */
+type QueueItemStatus = "pending" | "running" | "success" | "error" | "aborted";
+/**
+ * Represents a single item in the queue.
+ */
+interface QueueItem<TData = unknown, TError = unknown, TMeta = Record<string, unknown>> {
+    /** Unique identifier for this queue item */
+    id: string;
+    /** Current status of the item */
+    status: QueueItemStatus;
+    /** Response data on success */
+    data?: TData;
+    /** Error on failure */
+    error?: TError;
+    /** Original trigger input */
+    input?: {
+        body?: unknown;
+        query?: unknown;
+        params?: Record<string, string | number>;
+    };
+    /** Plugin-contributed metadata (e.g., progress, transformedData) */
+    meta?: TMeta;
+}
+/**
+ * Statistics information for the queue.
+ */
+interface QueueStats {
+    /** Number of pending items waiting to run */
+    pending: number;
+    /** Number of currently running items */
+    running: number;
+    /** Number of settled items (success, error, or aborted) */
+    settled: number;
+    /** Number of successful items */
+    success: number;
+    /** Number of failed items (error or aborted) */
+    failed: number;
+    /** Total number of items in queue */
+    total: number;
+    /** Completion percentage (0-100) */
+    percentage: number;
+}
+/**
+ * Input type for queue trigger.
+ */
+interface QueueTriggerInput {
+    /** Custom ID for this queue item. If not provided, one will be auto-generated. */
+    id?: string;
+    body?: unknown;
+    query?: unknown;
+    params?: Record<string, string | number>;
+}
+/**
+ * Queue controller instance.
+ * Framework-agnostic - can be used directly in Angular, Vue, etc.
+ */
+interface QueueController<TData = unknown, TError = unknown, TMeta = Record<string, unknown>> {
+    /** Add item to queue and execute. Returns promise that resolves when item completes. */
+    trigger: (input: QueueTriggerInput) => Promise<SpooshResponse<TData, TError>>;
+    /** Get current queue state */
+    getQueue: () => QueueItem<TData, TError, TMeta>[];
+    /** Get queue statistics */
+    getStats: () => QueueStats;
+    /** Subscribe to queue state changes */
+    subscribe: (callback: () => void) => () => void;
+    /** Abort item by ID, or all items if no ID provided */
+    abort: (id?: string) => void;
+    /** Retry failed/aborted item by ID, or all failed items if no ID provided */
+    retry: (id?: string) => Promise<void>;
+    /** Remove specific item by ID (aborts if active) */
+    remove: (id: string) => void;
+    /** Remove all settled items (success, error, aborted). Keeps pending/running. */
+    removeSettled: () => void;
+    /** Abort all and clear entire queue */
+    clear: () => void;
+    /** Update the concurrency limit */
+    setConcurrency: (concurrency: number) => void;
+}
+/**
+ * Configuration for creating a queue controller.
+ */
+interface QueueControllerConfig {
+    /** API path */
+    path: string;
+    /** HTTP method */
+    method: string;
+    /** Maximum concurrent operations. Defaults to 3. */
+    concurrency?: number;
+    /** Operation type for plugin middleware */
+    operationType: "read" | "write" | "queue";
+    /** Hook-level plugin options (e.g., progress, retries) */
+    hookOptions?: Record<string, unknown>;
+}
+
+interface QueueControllerContext {
+    api: unknown;
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    pluginExecutor: InstancePluginExecutor;
+}
+declare function createQueueController<TData, TError, TMeta = Record<string, unknown>>(config: QueueControllerConfig, context: QueueControllerContext): QueueController<TData, TError, TMeta>;
+
+/**
+ * Semaphore for controlling concurrent access.
+ * Used to limit the number of concurrent operations in the queue.
+ */
+declare class Semaphore {
+    private max;
+    private current;
+    private waiting;
+    constructor(max: number);
+    acquire(): Promise<boolean>;
+    release(): void;
+    setConcurrency(max: number): void;
+    reset(): void;
+    getCurrent(): number;
+    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 };

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   HTTP_METHODS: () => HTTP_METHODS,
+  Semaphore: () => Semaphore,
   Spoosh: () => Spoosh,
   __DEV__: () => __DEV__,
   buildUrl: () => buildUrl,
@@ -34,6 +35,7 @@ __export(src_exports, {
   createPluginExecutor: () => createPluginExecutor,
   createPluginRegistry: () => createPluginRegistry,
   createProxyHandler: () => createProxyHandler,
+  createQueueController: () => createQueueController,
   createSelectorProxy: () => createSelectorProxy,
   createStateManager: () => createStateManager,
   createTracer: () => createTracer,
@@ -765,6 +767,7 @@ function createStateManager() {
   const cache = /* @__PURE__ */ new Map();
   const subscribers = /* @__PURE__ */ new Map();
   const pendingPromises = /* @__PURE__ */ new Map();
+  const dataChangeCallbacks = /* @__PURE__ */ new Set();
   const notifySubscribers = (key) => {
     const subs = subscribers.get(key);
     subs?.forEach((cb) => cb());
@@ -784,6 +787,7 @@ function createStateManager() {
     },
     setCache(key, entry) {
       const existing = cache.get(key);
+      const oldData = existing?.state.data;
       if (existing) {
         existing.state = { ...existing.state, ...entry.state };
         if (entry.tags) {
@@ -796,6 +800,10 @@ function createStateManager() {
           existing.stale = entry.stale;
         }
         notifySubscribers(key);
+        const newData = existing.state.data;
+        if (oldData !== newData) {
+          dataChangeCallbacks.forEach((cb) => cb(key, oldData, newData));
+        }
       } else {
         const newEntry = {
           state: entry.state ?? createInitialState(),
@@ -807,6 +815,10 @@ function createStateManager() {
         };
         cache.set(key, newEntry);
         notifySubscribers(key);
+        const newData = newEntry.state.data;
+        if (oldData !== newData) {
+          dataChangeCallbacks.forEach((cb) => cb(key, oldData, newData));
+        }
       }
     },
     deleteCache(key) {
@@ -911,10 +923,17 @@ function createStateManager() {
     getPendingPromise(key) {
       return pendingPromises.get(key);
     },
+    onDataChange(callback) {
+      dataChangeCallbacks.add(callback);
+      return () => {
+        dataChangeCallbacks.delete(callback);
+      };
+    },
     clear() {
       cache.clear();
       subscribers.clear();
       pendingPromises.clear();
+      dataChangeCallbacks.clear();
     }
   };
 }
@@ -1829,3 +1848,360 @@ function createInfiniteReadController(options) {
   };
   return controller;
 }
+
+// src/queue/semaphore.ts
+var Semaphore = class {
+  constructor(max) {
+    this.max = max;
+  }
+  current = 0;
+  waiting = [];
+  async acquire() {
+    if (this.current < this.max) {
+      this.current++;
+      return true;
+    }
+    return new Promise((resolve) => this.waiting.push(resolve));
+  }
+  release() {
+    if (this.current > 0) {
+      this.current--;
+    }
+    if (this.waiting.length > 0) {
+      this.current++;
+      this.waiting.shift()(true);
+    }
+  }
+  setConcurrency(max) {
+    const previousMax = this.max;
+    this.max = max;
+    if (max > previousMax) {
+      const slotsToRelease = Math.min(max - previousMax, this.waiting.length);
+      for (let i = 0; i < slotsToRelease; i++) {
+        this.current++;
+        this.waiting.shift()(true);
+      }
+    }
+  }
+  reset() {
+    this.current = 0;
+    while (this.waiting.length > 0) {
+      const resolve = this.waiting.shift();
+      resolve(false);
+    }
+  }
+  getCurrent() {
+    return this.current;
+  }
+  getWaitingCount() {
+    return this.waiting.length;
+  }
+};
+
+// src/queue/controller.ts
+var DEFAULT_CONCURRENCY = 3;
+function createQueueController(config, context) {
+  const { path, method, operationType, hookOptions = {} } = config;
+  const concurrency = config.concurrency ?? DEFAULT_CONCURRENCY;
+  const { api, stateManager, eventEmitter, pluginExecutor } = context;
+  const semaphore = new Semaphore(concurrency);
+  const queue = [];
+  const abortControllers = /* @__PURE__ */ new Map();
+  const subscribers = /* @__PURE__ */ new Set();
+  const itemPromises = /* @__PURE__ */ new Map();
+  let cachedQueueSnapshot = [];
+  const notify = () => {
+    cachedQueueSnapshot = [...queue];
+    subscribers.forEach((cb) => cb());
+  };
+  const generateId = () => `q-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const updateItem = (id, update) => {
+    const item = queue.find((i) => i.id === id);
+    if (item) {
+      Object.assign(item, update);
+    }
+  };
+  const executeItem = async (item) => {
+    const acquired = await semaphore.acquire();
+    if (!acquired || item.status === "aborted") {
+      if (acquired) {
+        semaphore.release();
+      }
+      const response = {
+        error: new Error("Aborted"),
+        aborted: true
+      };
+      itemPromises.get(item.id)?.resolve(response);
+      itemPromises.delete(item.id);
+      return response;
+    }
+    const abortController = new AbortController();
+    abortControllers.set(item.id, abortController);
+    const queryKey = stateManager.createQueryKey({
+      path,
+      method,
+      options: { ...item.input, _queueId: item.id }
+    });
+    const unsubscribeMeta = stateManager.subscribeCache(queryKey, () => {
+      const cacheEntry = stateManager.getCache(queryKey);
+      const meta = cacheEntry?.meta ? Object.fromEntries(cacheEntry.meta) : void 0;
+      if (meta) {
+        updateItem(item.id, { meta });
+        notify();
+      }
+    });
+    try {
+      updateItem(item.id, { status: "running" });
+      notify();
+      const { body, query, params, ...triggerOptions } = item.input ?? {};
+      const pluginContext = pluginExecutor.createContext({
+        operationType,
+        path,
+        method,
+        queryKey,
+        tags: [],
+        requestTimestamp: Date.now(),
+        request: {
+          headers: {},
+          body,
+          query,
+          params,
+          signal: abortController.signal
+        },
+        temp: /* @__PURE__ */ new Map(),
+        pluginOptions: { ...hookOptions, ...triggerOptions },
+        stateManager,
+        eventEmitter
+      });
+      const coreFetch = async () => {
+        const pathMethods = api(
+          path
+        );
+        const methodFn = pathMethods[method];
+        const { transport, transportOptions } = pluginContext.request;
+        return methodFn({
+          body,
+          query,
+          params,
+          signal: abortController.signal,
+          transport,
+          transportOptions
+        });
+      };
+      const response = await pluginExecutor.executeMiddleware(
+        operationType,
+        pluginContext,
+        coreFetch
+      );
+      const cacheEntry = stateManager.getCache(queryKey);
+      const meta = cacheEntry?.meta ? Object.fromEntries(cacheEntry.meta) : void 0;
+      if (response.error) {
+        updateItem(item.id, { status: "error", error: response.error, meta });
+        itemPromises.get(item.id)?.resolve(response);
+      } else {
+        updateItem(item.id, { status: "success", data: response.data, meta });
+        itemPromises.get(item.id)?.resolve(response);
+      }
+      return response;
+    } catch (err) {
+      const isAborted = abortController.signal.aborted;
+      if (isAborted) {
+        updateItem(item.id, { status: "aborted" });
+      } else {
+        updateItem(item.id, { status: "error", error: err });
+      }
+      const errorResponse = {
+        error: err,
+        aborted: isAborted
+      };
+      itemPromises.get(item.id)?.resolve(errorResponse);
+      return errorResponse;
+    } finally {
+      unsubscribeMeta();
+      abortControllers.delete(item.id);
+      itemPromises.delete(item.id);
+      notify();
+      semaphore.release();
+    }
+  };
+  return {
+    trigger(input) {
+      const { id: customId, ...requestInput } = input;
+      const id = customId ?? generateId();
+      const item = {
+        id,
+        status: "pending",
+        input: requestInput
+      };
+      queue.push(item);
+      notify();
+      const promise = new Promise(
+        (resolve, reject) => {
+          itemPromises.set(id, { resolve, reject });
+        }
+      );
+      executeItem(item);
+      return promise;
+    },
+    getQueue: () => cachedQueueSnapshot,
+    getStats: () => {
+      let pending = 0;
+      let running = 0;
+      let success = 0;
+      let failed = 0;
+      for (const item of queue) {
+        if (item.status === "pending") pending++;
+        else if (item.status === "running") running++;
+        else if (item.status === "success") success++;
+        else if (item.status === "error" || item.status === "aborted") failed++;
+      }
+      const settled = success + failed;
+      const total = queue.length;
+      return {
+        pending,
+        running,
+        settled,
+        success,
+        failed,
+        total,
+        percentage: total > 0 ? Math.round(settled / total * 100) : 0
+      };
+    },
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      return () => subscribers.delete(callback);
+    },
+    abort: (id) => {
+      const queryKeysToDiscard = [];
+      const abortedResponse = {
+        error: new Error("Aborted"),
+        aborted: true
+      };
+      if (id) {
+        const item = queue.find((i) => i.id === id);
+        if (item && (item.status === "pending" || item.status === "running")) {
+          const wasPending = item.status === "pending";
+          abortControllers.get(id)?.abort();
+          updateItem(id, { status: "aborted" });
+          if (wasPending) {
+            itemPromises.get(id)?.resolve(abortedResponse);
+            itemPromises.delete(id);
+          }
+          const queryKey = stateManager.createQueryKey({
+            path,
+            method,
+            options: { ...item.input, _queueId: item.id }
+          });
+          queryKeysToDiscard.push(queryKey);
+          notify();
+        }
+      } else {
+        for (const item of queue) {
+          if (item.status === "pending" || item.status === "running") {
+            abortControllers.get(item.id)?.abort();
+            const wasPending = item.status === "pending";
+            updateItem(item.id, { status: "aborted" });
+            if (wasPending) {
+              itemPromises.get(item.id)?.resolve(abortedResponse);
+              itemPromises.delete(item.id);
+            }
+            const queryKey = stateManager.createQueryKey({
+              path,
+              method,
+              options: { ...item.input, _queueId: item.id }
+            });
+            queryKeysToDiscard.push(queryKey);
+          }
+        }
+        notify();
+      }
+      if (queryKeysToDiscard.length > 0) {
+        eventEmitter.emit("spoosh:queue-abort", {
+          queryKeys: queryKeysToDiscard
+        });
+      }
+    },
+    retry: async (id) => {
+      const items = id ? queue.filter(
+        (i) => i.id === id && (i.status === "error" || i.status === "aborted")
+      ) : queue.filter((i) => i.status === "error" || i.status === "aborted");
+      const promises = [];
+      for (const item of items) {
+        updateItem(item.id, { status: "pending", error: void 0 });
+        const promise = new Promise(
+          (resolve) => {
+            itemPromises.set(item.id, { resolve, reject: () => {
+            } });
+          }
+        );
+        promises.push(promise);
+        executeItem(item);
+      }
+      await Promise.all(promises);
+    },
+    remove: (id) => {
+      const abortedResponse = {
+        error: new Error("Removed"),
+        aborted: true
+      };
+      const item = queue.find((i) => i.id === id);
+      if (item) {
+        if (item.status === "pending") {
+          item.status = "aborted";
+          itemPromises.get(id)?.resolve(abortedResponse);
+          itemPromises.delete(id);
+        } else if (item.status === "running") {
+          abortControllers.get(id)?.abort();
+        }
+        const idx = queue.findIndex((i) => i.id === id);
+        if (idx !== -1) {
+          queue.splice(idx, 1);
+        }
+      }
+      notify();
+    },
+    removeSettled: () => {
+      const active = queue.filter(
+        (i) => i.status === "pending" || i.status === "running"
+      );
+      queue.length = 0;
+      queue.push(...active);
+      notify();
+    },
+    clear: () => {
+      const queryKeysToDiscard = [];
+      for (const item of queue) {
+        if (item.status === "pending" || item.status === "running") {
+          abortControllers.get(item.id)?.abort();
+          item.status = "aborted";
+          const abortedResponse = {
+            error: new Error("Aborted"),
+            aborted: true
+          };
+          itemPromises.get(item.id)?.resolve(abortedResponse);
+          itemPromises.delete(item.id);
+          const queryKey = stateManager.createQueryKey({
+            path,
+            method,
+            options: { ...item.input, _queueId: item.id }
+          });
+          queryKeysToDiscard.push(queryKey);
+        }
+      }
+      if (queryKeysToDiscard.length > 0) {
+        eventEmitter.emit("spoosh:queue-clear", {
+          queryKeys: queryKeysToDiscard
+        });
+      }
+      queue.length = 0;
+      semaphore.reset();
+      notify();
+    },
+    setConcurrency: (newConcurrency) => {
+      if (newConcurrency < 1 || !Number.isInteger(newConcurrency)) {
+        return;
+      }
+      semaphore.setConcurrency(newConcurrency);
+    }
+  };
+}

package/dist/index.mjs

@@ -698,6 +698,7 @@ function createStateManager() {
   const cache = /* @__PURE__ */ new Map();
   const subscribers = /* @__PURE__ */ new Map();
   const pendingPromises = /* @__PURE__ */ new Map();
+  const dataChangeCallbacks = /* @__PURE__ */ new Set();
   const notifySubscribers = (key) => {
     const subs = subscribers.get(key);
     subs?.forEach((cb) => cb());
@@ -717,6 +718,7 @@ function createStateManager() {
     },
     setCache(key, entry) {
       const existing = cache.get(key);
+      const oldData = existing?.state.data;
       if (existing) {
         existing.state = { ...existing.state, ...entry.state };
         if (entry.tags) {
@@ -729,6 +731,10 @@ function createStateManager() {
           existing.stale = entry.stale;
         }
         notifySubscribers(key);
+        const newData = existing.state.data;
+        if (oldData !== newData) {
+          dataChangeCallbacks.forEach((cb) => cb(key, oldData, newData));
+        }
       } else {
         const newEntry = {
           state: entry.state ?? createInitialState(),
@@ -740,6 +746,10 @@ function createStateManager() {
         };
         cache.set(key, newEntry);
         notifySubscribers(key);
+        const newData = newEntry.state.data;
+        if (oldData !== newData) {
+          dataChangeCallbacks.forEach((cb) => cb(key, oldData, newData));
+        }
       }
     },
     deleteCache(key) {
@@ -844,10 +854,17 @@ function createStateManager() {
     getPendingPromise(key) {
       return pendingPromises.get(key);
     },
+    onDataChange(callback) {
+      dataChangeCallbacks.add(callback);
+      return () => {
+        dataChangeCallbacks.delete(callback);
+      };
+    },
     clear() {
       cache.clear();
       subscribers.clear();
       pendingPromises.clear();
+      dataChangeCallbacks.clear();
     }
   };
 }
@@ -1762,8 +1779,366 @@ function createInfiniteReadController(options) {
   };
   return controller;
 }
+
+// src/queue/semaphore.ts
+var Semaphore = class {
+  constructor(max) {
+    this.max = max;
+  }
+  current = 0;
+  waiting = [];
+  async acquire() {
+    if (this.current < this.max) {
+      this.current++;
+      return true;
+    }
+    return new Promise((resolve) => this.waiting.push(resolve));
+  }
+  release() {
+    if (this.current > 0) {
+      this.current--;
+    }
+    if (this.waiting.length > 0) {
+      this.current++;
+      this.waiting.shift()(true);
+    }
+  }
+  setConcurrency(max) {
+    const previousMax = this.max;
+    this.max = max;
+    if (max > previousMax) {
+      const slotsToRelease = Math.min(max - previousMax, this.waiting.length);
+      for (let i = 0; i < slotsToRelease; i++) {
+        this.current++;
+        this.waiting.shift()(true);
+      }
+    }
+  }
+  reset() {
+    this.current = 0;
+    while (this.waiting.length > 0) {
+      const resolve = this.waiting.shift();
+      resolve(false);
+    }
+  }
+  getCurrent() {
+    return this.current;
+  }
+  getWaitingCount() {
+    return this.waiting.length;
+  }
+};
+
+// src/queue/controller.ts
+var DEFAULT_CONCURRENCY = 3;
+function createQueueController(config, context) {
+  const { path, method, operationType, hookOptions = {} } = config;
+  const concurrency = config.concurrency ?? DEFAULT_CONCURRENCY;
+  const { api, stateManager, eventEmitter, pluginExecutor } = context;
+  const semaphore = new Semaphore(concurrency);
+  const queue = [];
+  const abortControllers = /* @__PURE__ */ new Map();
+  const subscribers = /* @__PURE__ */ new Set();
+  const itemPromises = /* @__PURE__ */ new Map();
+  let cachedQueueSnapshot = [];
+  const notify = () => {
+    cachedQueueSnapshot = [...queue];
+    subscribers.forEach((cb) => cb());
+  };
+  const generateId = () => `q-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const updateItem = (id, update) => {
+    const item = queue.find((i) => i.id === id);
+    if (item) {
+      Object.assign(item, update);
+    }
+  };
+  const executeItem = async (item) => {
+    const acquired = await semaphore.acquire();
+    if (!acquired || item.status === "aborted") {
+      if (acquired) {
+        semaphore.release();
+      }
+      const response = {
+        error: new Error("Aborted"),
+        aborted: true
+      };
+      itemPromises.get(item.id)?.resolve(response);
+      itemPromises.delete(item.id);
+      return response;
+    }
+    const abortController = new AbortController();
+    abortControllers.set(item.id, abortController);
+    const queryKey = stateManager.createQueryKey({
+      path,
+      method,
+      options: { ...item.input, _queueId: item.id }
+    });
+    const unsubscribeMeta = stateManager.subscribeCache(queryKey, () => {
+      const cacheEntry = stateManager.getCache(queryKey);
+      const meta = cacheEntry?.meta ? Object.fromEntries(cacheEntry.meta) : void 0;
+      if (meta) {
+        updateItem(item.id, { meta });
+        notify();
+      }
+    });
+    try {
+      updateItem(item.id, { status: "running" });
+      notify();
+      const { body, query, params, ...triggerOptions } = item.input ?? {};
+      const pluginContext = pluginExecutor.createContext({
+        operationType,
+        path,
+        method,
+        queryKey,
+        tags: [],
+        requestTimestamp: Date.now(),
+        request: {
+          headers: {},
+          body,
+          query,
+          params,
+          signal: abortController.signal
+        },
+        temp: /* @__PURE__ */ new Map(),
+        pluginOptions: { ...hookOptions, ...triggerOptions },
+        stateManager,
+        eventEmitter
+      });
+      const coreFetch = async () => {
+        const pathMethods = api(
+          path
+        );
+        const methodFn = pathMethods[method];
+        const { transport, transportOptions } = pluginContext.request;
+        return methodFn({
+          body,
+          query,
+          params,
+          signal: abortController.signal,
+          transport,
+          transportOptions
+        });
+      };
+      const response = await pluginExecutor.executeMiddleware(
+        operationType,
+        pluginContext,
+        coreFetch
+      );
+      const cacheEntry = stateManager.getCache(queryKey);
+      const meta = cacheEntry?.meta ? Object.fromEntries(cacheEntry.meta) : void 0;
+      if (response.error) {
+        updateItem(item.id, { status: "error", error: response.error, meta });
+        itemPromises.get(item.id)?.resolve(response);
+      } else {
+        updateItem(item.id, { status: "success", data: response.data, meta });
+        itemPromises.get(item.id)?.resolve(response);
+      }
+      return response;
+    } catch (err) {
+      const isAborted = abortController.signal.aborted;
+      if (isAborted) {
+        updateItem(item.id, { status: "aborted" });
+      } else {
+        updateItem(item.id, { status: "error", error: err });
+      }
+      const errorResponse = {
+        error: err,
+        aborted: isAborted
+      };
+      itemPromises.get(item.id)?.resolve(errorResponse);
+      return errorResponse;
+    } finally {
+      unsubscribeMeta();
+      abortControllers.delete(item.id);
+      itemPromises.delete(item.id);
+      notify();
+      semaphore.release();
+    }
+  };
+  return {
+    trigger(input) {
+      const { id: customId, ...requestInput } = input;
+      const id = customId ?? generateId();
+      const item = {
+        id,
+        status: "pending",
+        input: requestInput
+      };
+      queue.push(item);
+      notify();
+      const promise = new Promise(
+        (resolve, reject) => {
+          itemPromises.set(id, { resolve, reject });
+        }
+      );
+      executeItem(item);
+      return promise;
+    },
+    getQueue: () => cachedQueueSnapshot,
+    getStats: () => {
+      let pending = 0;
+      let running = 0;
+      let success = 0;
+      let failed = 0;
+      for (const item of queue) {
+        if (item.status === "pending") pending++;
+        else if (item.status === "running") running++;
+        else if (item.status === "success") success++;
+        else if (item.status === "error" || item.status === "aborted") failed++;
+      }
+      const settled = success + failed;
+      const total = queue.length;
+      return {
+        pending,
+        running,
+        settled,
+        success,
+        failed,
+        total,
+        percentage: total > 0 ? Math.round(settled / total * 100) : 0
+      };
+    },
+    subscribe: (callback) => {
+      subscribers.add(callback);
+      return () => subscribers.delete(callback);
+    },
+    abort: (id) => {
+      const queryKeysToDiscard = [];
+      const abortedResponse = {
+        error: new Error("Aborted"),
+        aborted: true
+      };
+      if (id) {
+        const item = queue.find((i) => i.id === id);
+        if (item && (item.status === "pending" || item.status === "running")) {
+          const wasPending = item.status === "pending";
+          abortControllers.get(id)?.abort();
+          updateItem(id, { status: "aborted" });
+          if (wasPending) {
+            itemPromises.get(id)?.resolve(abortedResponse);
+            itemPromises.delete(id);
+          }
+          const queryKey = stateManager.createQueryKey({
+            path,
+            method,
+            options: { ...item.input, _queueId: item.id }
+          });
+          queryKeysToDiscard.push(queryKey);
+          notify();
+        }
+      } else {
+        for (const item of queue) {
+          if (item.status === "pending" || item.status === "running") {
+            abortControllers.get(item.id)?.abort();
+            const wasPending = item.status === "pending";
+            updateItem(item.id, { status: "aborted" });
+            if (wasPending) {
+              itemPromises.get(item.id)?.resolve(abortedResponse);
+              itemPromises.delete(item.id);
+            }
+            const queryKey = stateManager.createQueryKey({
+              path,
+              method,
+              options: { ...item.input, _queueId: item.id }
+            });
+            queryKeysToDiscard.push(queryKey);
+          }
+        }
+        notify();
+      }
+      if (queryKeysToDiscard.length > 0) {
+        eventEmitter.emit("spoosh:queue-abort", {
+          queryKeys: queryKeysToDiscard
+        });
+      }
+    },
+    retry: async (id) => {
+      const items = id ? queue.filter(
+        (i) => i.id === id && (i.status === "error" || i.status === "aborted")
+      ) : queue.filter((i) => i.status === "error" || i.status === "aborted");
+      const promises = [];
+      for (const item of items) {
+        updateItem(item.id, { status: "pending", error: void 0 });
+        const promise = new Promise(
+          (resolve) => {
+            itemPromises.set(item.id, { resolve, reject: () => {
+            } });
+          }
+        );
+        promises.push(promise);
+        executeItem(item);
+      }
+      await Promise.all(promises);
+    },
+    remove: (id) => {
+      const abortedResponse = {
+        error: new Error("Removed"),
+        aborted: true
+      };
+      const item = queue.find((i) => i.id === id);
+      if (item) {
+        if (item.status === "pending") {
+          item.status = "aborted";
+          itemPromises.get(id)?.resolve(abortedResponse);
+          itemPromises.delete(id);
+        } else if (item.status === "running") {
+          abortControllers.get(id)?.abort();
+        }
+        const idx = queue.findIndex((i) => i.id === id);
+        if (idx !== -1) {
+          queue.splice(idx, 1);
+        }
+      }
+      notify();
+    },
+    removeSettled: () => {
+      const active = queue.filter(
+        (i) => i.status === "pending" || i.status === "running"
+      );
+      queue.length = 0;
+      queue.push(...active);
+      notify();
+    },
+    clear: () => {
+      const queryKeysToDiscard = [];
+      for (const item of queue) {
+        if (item.status === "pending" || item.status === "running") {
+          abortControllers.get(item.id)?.abort();
+          item.status = "aborted";
+          const abortedResponse = {
+            error: new Error("Aborted"),
+            aborted: true
+          };
+          itemPromises.get(item.id)?.resolve(abortedResponse);
+          itemPromises.delete(item.id);
+          const queryKey = stateManager.createQueryKey({
+            path,
+            method,
+            options: { ...item.input, _queueId: item.id }
+          });
+          queryKeysToDiscard.push(queryKey);
+        }
+      }
+      if (queryKeysToDiscard.length > 0) {
+        eventEmitter.emit("spoosh:queue-clear", {
+          queryKeys: queryKeysToDiscard
+        });
+      }
+      queue.length = 0;
+      semaphore.reset();
+      notify();
+    },
+    setConcurrency: (newConcurrency) => {
+      if (newConcurrency < 1 || !Number.isInteger(newConcurrency)) {
+        return;
+      }
+      semaphore.setConcurrency(newConcurrency);
+    }
+  };
+}
 export {
   HTTP_METHODS,
+  Semaphore,
   Spoosh,
   __DEV__,
   buildUrl,
@@ -1777,6 +2152,7 @@ export {
   createPluginExecutor,
   createPluginRegistry,
   createProxyHandler,
+  createQueueController,
   createSelectorProxy,
   createStateManager,
   createTracer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/core",
-  "version": "0.13.3",
+  "version": "0.14.1",
   "license": "MIT",
   "description": "Type-safe API toolkit with plugin middleware system",
   "keywords": [