@bquery/bquery 1.9.0 → 1.10.0

package/dist/concurrency/reactive.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Reactive wrappers around reusable concurrency primitives.
+ *
+ * @module bquery/concurrency
+ */
+import type { CreateRpcPoolOptions, CreateRpcWorkerOptions, CreateTaskPoolOptions, CreateTaskWorkerOptions, ReactiveRpcPool, ReactiveRpcWorker, ReactiveTaskPool, ReactiveTaskWorker, WorkerRpcHandlers, WorkerTaskHandler } from './types';
+/**
+ * Creates a reactive wrapper around a reusable task worker.
+ *
+ * The returned wrapper preserves the standard `run()` / `terminate()` API and
+ * adds readonly signals such as `state$` and `busy$` for UI bindings.
+ *
+ * @example
+ * ```ts
+ * import { createReactiveTaskWorker } from '@bquery/bquery/concurrency';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const worker = createReactiveTaskWorker((value: number) => value * 2);
+ *
+ * effect(() => {
+ *   console.log(worker.state$.value, worker.busy$.value);
+ * });
+ *
+ * await worker.run(21);
+ * worker.terminate();
+ * ```
+ */
+export declare function createReactiveTaskWorker<TInput = void, TResult = unknown>(handler: WorkerTaskHandler<TInput, TResult>, options?: CreateTaskWorkerOptions): ReactiveTaskWorker<TInput, TResult>;
+/**
+ * Creates a reactive wrapper around a reusable RPC worker.
+ *
+ * The returned wrapper preserves the standard `call()` / `terminate()` API and
+ * adds readonly signals such as `state$` and `busy$` for UI bindings.
+ *
+ * @example
+ * ```ts
+ * import { createReactiveRpcWorker } from '@bquery/bquery/concurrency';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const rpc = createReactiveRpcWorker({
+ *   sum: ({ values }: { values: number[] }) => values.reduce((total, value) => total + value, 0),
+ * });
+ *
+ * effect(() => {
+ *   console.log(rpc.state$.value, rpc.busy$.value);
+ * });
+ *
+ * await rpc.call('sum', { values: [1, 2, 3] });
+ * rpc.terminate();
+ * ```
+ */
+export declare function createReactiveRpcWorker<TRoutes extends WorkerRpcHandlers>(handlers: TRoutes, options?: CreateRpcWorkerOptions): ReactiveRpcWorker<TRoutes>;
+/**
+ * Creates a reactive wrapper around a reusable task pool.
+ *
+ * The returned wrapper preserves the standard `run()` / `clear()` /
+ * `terminate()` API and adds readonly signals for pool state and queue load.
+ *
+ * @example
+ * ```ts
+ * import { createReactiveTaskPool } from '@bquery/bquery/concurrency';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const pool = createReactiveTaskPool((value: number) => value * 2, { concurrency: 2 });
+ *
+ * effect(() => {
+ *   console.log(pool.pending$.value, pool.size$.value, pool.state$.value);
+ * });
+ *
+ * await Promise.all([pool.run(1), pool.run(2), pool.run(3)]);
+ * pool.terminate();
+ * ```
+ */
+export declare function createReactiveTaskPool<TInput = void, TResult = unknown>(handler: WorkerTaskHandler<TInput, TResult>, options?: CreateTaskPoolOptions): ReactiveTaskPool<TInput, TResult>;
+/**
+ * Creates a reactive wrapper around a reusable RPC pool.
+ *
+ * The returned wrapper preserves the standard `call()` / `clear()` /
+ * `terminate()` API and adds readonly signals for pool state and queue load.
+ *
+ * @example
+ * ```ts
+ * import { createReactiveRpcPool } from '@bquery/bquery/concurrency';
+ * import { effect } from '@bquery/bquery/reactive';
+ *
+ * const pool = createReactiveRpcPool(
+ *   {
+ *     sum: ({ values }: { values: number[] }) => values.reduce((total, value) => total + value, 0),
+ *   },
+ *   { concurrency: 2 }
+ * );
+ *
+ * effect(() => {
+ *   console.log(pool.pending$.value, pool.size$.value, pool.state$.value);
+ * });
+ *
+ * await Promise.all([
+ *   pool.call('sum', { values: [1, 2] }),
+ *   pool.call('sum', { values: [3, 4] }),
+ *   pool.call('sum', { values: [5, 6] }),
+ * ]);
+ *
+ * pool.terminate();
+ * ```
+ */
+export declare function createReactiveRpcPool<TRoutes extends WorkerRpcHandlers>(handlers: TRoutes, options?: CreateRpcPoolOptions): ReactiveRpcPool<TRoutes>;
+//# sourceMappingURL=reactive.d.ts.map

package/dist/concurrency/reactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../../src/concurrency/reactive.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EACV,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAKlB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AA6DjB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,GAAG,IAAI,EAAE,OAAO,GAAG,OAAO,EACvE,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,OAAO,GAAE,uBAA4B,GACpC,kBAAkB,CAAC,MAAM,EAAE,OAAO,CAAC,CAwBrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,SAAS,iBAAiB,EACvE,QAAQ,EAAE,OAAO,EACjB,OAAO,GAAE,sBAA2B,GACnC,iBAAiB,CAAC,OAAO,CAAC,CA4B5B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,GAAG,IAAI,EAAE,OAAO,GAAG,OAAO,EACrE,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,OAAO,GAAE,qBAA0B,GAClC,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAwCnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,SAAS,iBAAiB,EACrE,QAAQ,EAAE,OAAO,EACjB,OAAO,GAAE,oBAAyB,GACjC,eAAe,CAAC,OAAO,CAAC,CA4C1B"}

package/dist/concurrency/rpc.d.ts

@@ -0,0 +1,46 @@
+/**
+ * RPC-style worker communication helpers.
+ *
+ * @module bquery/concurrency
+ */
+import type { CallWorkerMethodOptions, CreateRpcWorkerOptions, RpcWorker, WorkerRpcHandlers } from './types';
+/**
+ * Creates a reusable RPC-style worker with explicit named method dispatch.
+ *
+ * The worker processes one request at a time to keep lifecycle, timeout, abort,
+ * and cleanup semantics aligned with the minimal Milestone 1 task API.
+ *
+ * @example
+ * ```ts
+ * import { createRpcWorker } from '@bquery/bquery/concurrency';
+ *
+ * const rpc = createRpcWorker({
+ *   sum: ({ values }: { values: number[] }) => values.reduce((total, value) => total + value, 0),
+ *   double: (value: number) => value * 2,
+ * });
+ *
+ * const total = await rpc.call('sum', { values: [1, 2, 3] });
+ * rpc.terminate();
+ * ```
+ */
+export declare function createRpcWorker<TRoutes extends WorkerRpcHandlers>(handlers: TRoutes, options?: CreateRpcWorkerOptions): RpcWorker<TRoutes>;
+/**
+ * Executes a single named RPC method in a fresh worker and tears it down after
+ * the response is received.
+ *
+ * @example
+ * ```ts
+ * import { callWorkerMethod } from '@bquery/bquery/concurrency';
+ *
+ * const total = await callWorkerMethod(
+ *   {
+ *     sum: ({ values }: { values: number[] }) =>
+ *       values.reduce((result, value) => result + value, 0),
+ *   },
+ *   'sum',
+ *   { values: [1, 2, 3] }
+ * );
+ * ```
+ */
+export declare function callWorkerMethod<TRoutes extends WorkerRpcHandlers, TMethod extends keyof TRoutes & string>(handlers: TRoutes, method: TMethod, input: Parameters<TRoutes[TMethod]>[0], options?: CallWorkerMethodOptions): Promise<Awaited<ReturnType<TRoutes[TMethod]>>>;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/concurrency/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../../src/concurrency/rpc.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,SAAS,EAGT,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAyGjB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,OAAO,SAAS,iBAAiB,EAC/D,QAAQ,EAAE,OAAO,EACjB,OAAO,GAAE,sBAA2B,GACnC,SAAS,CAAC,OAAO,CAAC,CA4LpB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,SAAS,iBAAiB,EACjC,OAAO,SAAS,MAAM,OAAO,GAAG,MAAM,EAEtC,QAAQ,EAAE,OAAO,EACjB,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,EACtC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAQhD"}

package/dist/concurrency/support.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Runtime support checks for the concurrency module.
+ *
+ * @module bquery/concurrency
+ */
+import type { ConcurrencySupport } from './types';
+/**
+ * Returns a feature snapshot for zero-build inline worker execution.
+ *
+ * @example
+ * ```ts
+ * if (!isConcurrencySupported()) {
+ *   console.warn('Worker tasks are unavailable in this environment.');
+ * }
+ * ```
+ */
+export declare function getConcurrencySupport(): ConcurrencySupport;
+/**
+ * Returns `true` when bQuery can create inline worker tasks in the current
+ * environment.
+ */
+export declare function isConcurrencySupported(): boolean;
+//# sourceMappingURL=support.d.ts.map

package/dist/concurrency/support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"support.d.ts","sourceRoot":"","sources":["../../src/concurrency/support.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,CAiB1D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD"}

package/dist/concurrency/task.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Zero-build worker task helpers.
+ *
+ * @module bquery/concurrency
+ */
+import type { CreateTaskWorkerOptions, RunTaskOptions, TaskWorker, WorkerTaskHandler } from './types';
+/**
+ * Creates a reusable worker task handle around a standalone function.
+ *
+ * @example
+ * ```ts
+ * import { createTaskWorker } from '@bquery/bquery/concurrency';
+ *
+ * const worker = createTaskWorker((value: number) => value * value, { name: 'square-worker' });
+ * const result = await worker.run(12);
+ * worker.terminate();
+ * ```
+ */
+export declare function createTaskWorker<TInput = void, TResult = unknown>(handler: WorkerTaskHandler<TInput, TResult>, options?: CreateTaskWorkerOptions): TaskWorker<TInput, TResult>;
+/**
+ * Executes a single task in a fresh worker and tears it down afterwards.
+ *
+ * @example
+ * ```ts
+ * import { runTask } from '@bquery/bquery/concurrency';
+ *
+ * const result = await runTask((value: number) => value * 2, 21);
+ * ```
+ */
+export declare function runTask<TInput = void, TResult = unknown>(handler: WorkerTaskHandler<TInput, TResult>, input: TInput, options?: RunTaskOptions): Promise<TResult>;
+//# sourceMappingURL=task.d.ts.map

package/dist/concurrency/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/concurrency/task.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH,OAAO,KAAK,EACV,uBAAuB,EACvB,cAAc,EAEd,UAAU,EAEV,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAiEjB;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,GAAG,IAAI,EAAE,OAAO,GAAG,OAAO,EAC/D,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,OAAO,GAAE,uBAA4B,GACpC,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAyL7B;AAED;;;;;;;;;GASG;AACH,wBAAsB,OAAO,CAAC,MAAM,GAAG,IAAI,EAAE,OAAO,GAAG,OAAO,EAC5D,OAAO,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAQlB"}

package/dist/concurrency/types.d.ts

@@ -0,0 +1,343 @@
+/**
+ * Public types for the concurrency module.
+ *
+ * @module bquery/concurrency
+ */
+import type { ReadonlySignalHandle } from '../reactive/index';
+/**
+ * Standalone task handler executed inside a Web Worker.
+ *
+ * The function must be self-contained because it is stringified and evaluated
+ * in the worker context without access to outer closures.
+ *
+ * The bivariance wrapper is intentional: TypeScript checks plain function
+ * parameter types contravariantly under `strictFunctionTypes`, but method
+ * signatures remain bivariant. Modeling the public handler as a method-shaped
+ * signature keeps object-literal task and RPC handlers ergonomic in strict
+ * typechecks, including the repository's dedicated test typecheck. In practice
+ * this allows narrower inline handler parameter annotations in object literals;
+ * the trade-off is that assignability here is intentionally a little less strict
+ * than a plain function-type alias would be.
+ *
+ * @example
+ * ```ts
+ * const square = (value: number) => value * value;
+ * ```
+ */
+export type WorkerTaskHandler<TInput = void, TResult = unknown> = {
+    bivarianceHack(input: TInput): TResult | Promise<TResult>;
+}['bivarianceHack'];
+/** Lifecycle state of a reusable task worker. */
+export type TaskWorkerState = 'idle' | 'running' | 'terminated';
+/** Structured error codes emitted by the concurrency module. */
+export type TaskWorkerErrorCode = 'ABORT' | 'BUSY' | 'METHOD_NOT_FOUND' | 'QUEUE_CLEARED' | 'QUEUE_FULL' | 'SERIALIZATION' | 'TERMINATED' | 'TIMEOUT' | 'UNSUPPORTED' | 'WORKER';
+/** Per-run options for worker task execution. */
+export interface TaskRunOptions {
+    /**
+     * AbortSignal used to cancel the current run.
+     * Cancellation terminates the active worker run so later runs start cleanly.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional timeout in milliseconds.
+     * Non-finite or non-positive values disable timeout handling.
+     */
+    timeout?: number;
+    /**
+     * Transferable values passed together with the task payload.
+     * Use this for large `ArrayBuffer`-backed payloads when appropriate.
+     */
+    transfer?: Transferable[];
+}
+/** Options for creating a reusable task worker. */
+export interface CreateTaskWorkerOptions {
+    /** Optional worker name shown in browser tooling where supported. */
+    name?: string;
+    /**
+     * Default timeout applied to `run()` calls when the run itself does not
+     * override it.
+     */
+    timeout?: number;
+}
+/** Options accepted by the one-off `runTask()` helper. */
+export interface RunTaskOptions extends CreateTaskWorkerOptions, TaskRunOptions {
+}
+/** Options for creating a reusable RPC worker. */
+export type CreateRpcWorkerOptions = CreateTaskWorkerOptions;
+/** Options accepted by the one-off RPC method helper. */
+export interface CallWorkerMethodOptions extends CreateRpcWorkerOptions, TaskRunOptions {
+}
+/** Options for creating a reusable task worker pool. */
+export interface CreateTaskPoolOptions extends CreateTaskWorkerOptions {
+    /** Maximum number of workers executing tasks in parallel (default: 4). */
+    concurrency?: number;
+    /**
+     * Maximum number of not-yet-started tasks kept in the queue.
+     * Use `0` to disable queueing or `Infinity` for an unbounded queue.
+     */
+    maxQueue?: number;
+}
+/** Options for creating a reusable RPC worker pool. */
+export interface CreateRpcPoolOptions extends CreateRpcWorkerOptions {
+    /** Maximum number of workers executing calls in parallel (default: 4). */
+    concurrency?: number;
+    /**
+     * Maximum number of not-yet-started calls kept in the queue.
+     * Use `0` to disable queueing or `Infinity` for an unbounded queue.
+     */
+    maxQueue?: number;
+}
+/** Standalone task descriptor for `parallel()` / `batchTasks()`. */
+export interface ParallelTask<TInput = unknown, TResult = unknown> {
+    /** Standalone handler revived inside a worker context. */
+    handler: WorkerTaskHandler<TInput, TResult>;
+    /** Serializable payload for the handler. */
+    input: TInput;
+    /** Optional per-task timeout, abort, and transfer options. */
+    options?: TaskRunOptions;
+}
+/** Shared pool options for high-level parallel task helpers. */
+export type ParallelOptions = CreateTaskPoolOptions;
+/** Shared options for chunked collection helpers such as `map()` and `filter()`. */
+export interface ParallelCollectionOptions extends CreateTaskPoolOptions {
+    /**
+     * Number of array items grouped into each worker run.
+     * Defaults to `1`.
+     */
+    batchSize?: number;
+    /** AbortSignal shared across all queued or running chunks. */
+    signal?: AbortSignal;
+}
+/** Callback signature used by `map()` for parallel array processing. */
+export type ParallelMapHandler<TInput, TResult> = (value: TInput, index: number) => TResult | Promise<TResult>;
+/** Callback signature used by predicate-style helpers such as `filter()`. */
+export type ParallelPredicateHandler<TInput> = (value: TInput, index: number) => boolean | Promise<boolean>;
+/** Callback signature used by `reduce()` for sequential accumulation inside a worker. */
+export type ParallelReduceHandler<TAccumulator, TInput> = (accumulator: TAccumulator, value: TInput, index: number) => TAccumulator | Promise<TAccumulator>;
+/** Options for `map()` chunking and cancellation behavior. */
+export type ParallelMapOptions = ParallelCollectionOptions;
+/** Shared defaults for the optional fluent concurrency pipeline. */
+export type ConcurrencyPipelineOptions = ParallelCollectionOptions;
+/**
+ * Optional fluent pipeline over the existing explicit collection helpers.
+ *
+ * The pipeline is immutable: each transforming stage returns a new pipeline
+ * instead of mutating the previous one in place.
+ */
+export interface ConcurrencyPipeline<TValue> {
+    /**
+     * Maps the current array value through the existing worker-backed `map()` helper.
+     */
+    map<TResult>(mapper: ParallelMapHandler<TValue, TResult>, options?: ParallelCollectionOptions): ConcurrencyPipeline<TResult>;
+    /**
+     * Filters the current array value through the existing worker-backed `filter()` helper.
+     */
+    filter(predicate: ParallelPredicateHandler<TValue>, options?: ParallelCollectionOptions): ConcurrencyPipeline<TValue>;
+    /**
+     * Resolves the pipeline to a materialized array.
+     */
+    toArray(): Promise<TValue[]>;
+    /**
+     * Evaluates whether at least one item matches via the existing `some()` helper.
+     */
+    some(predicate: ParallelPredicateHandler<TValue>, options?: ParallelCollectionOptions): Promise<boolean>;
+    /**
+     * Evaluates whether every item matches via the existing `every()` helper.
+     */
+    every(predicate: ParallelPredicateHandler<TValue>, options?: ParallelCollectionOptions): Promise<boolean>;
+    /**
+     * Finds the first matching item via the existing `find()` helper.
+     */
+    find(predicate: ParallelPredicateHandler<TValue>, options?: ParallelCollectionOptions): Promise<TValue | undefined>;
+    /**
+     * Reduces the current array value via the existing `reduce()` helper.
+     */
+    reduce<TAccumulator>(reducer: ParallelReduceHandler<TAccumulator, TValue>, initialValue: TAccumulator, options?: TaskRunOptions): Promise<TAccumulator>;
+}
+/** Result tuple inferred from a `parallel()` or `batchTasks()` task list. */
+export type ParallelResults<TTasks extends readonly ParallelTask<unknown, unknown>[]> = {
+    [TIndex in keyof TTasks]: TTasks[TIndex] extends ParallelTask<unknown, infer TResult> ? Awaited<TResult> : never;
+};
+/** Feature-detection snapshot for the browser concurrency runtime. */
+export interface ConcurrencySupport {
+    /** `Worker` constructor availability. */
+    worker: boolean;
+    /** `Blob` availability for zero-build inline worker scripts. */
+    blob: boolean;
+    /** `URL.createObjectURL()` and `URL.revokeObjectURL()` availability. */
+    objectUrl: boolean;
+    /** `AbortController` availability for cancellation ergonomics. */
+    abortController: boolean;
+    /** Whether the minimum browser primitives for this module are present. */
+    supported: boolean;
+}
+/**
+ * Reusable worker-task handle.
+ *
+ * A task worker runs one task at a time. Queueing and pooling live in the
+ * separate `TaskPool` / `RpcPool` APIs so the worker handle itself stays explicit.
+ */
+export interface TaskWorker<TInput = void, TResult = unknown> {
+    /** Current lifecycle state. */
+    readonly state: TaskWorkerState;
+    /** Whether a task is currently running. */
+    readonly busy: boolean;
+    /**
+     * Execute one task in the backing worker.
+     *
+     * @param input - Serializable input passed to the task handler
+     * @param options - Per-run timeout, abort, and transfer options
+     */
+    run(input: TInput, options?: TaskRunOptions): Promise<TResult>;
+    /**
+     * Permanently terminate the backing worker.
+     * Any in-flight task is rejected with a termination error.
+     */
+    terminate(): void;
+}
+/**
+ * Reactive wrapper around a reusable task worker.
+ *
+ * Extends the standard {@link TaskWorker} API with readonly signals so UI code
+ * can observe worker lifecycle changes without polling getters manually.
+ */
+export interface ReactiveTaskWorker<TInput = void, TResult = unknown> extends TaskWorker<TInput, TResult> {
+    /** Reactive mirror of {@link TaskWorker.state}. */
+    readonly state$: ReadonlySignalHandle<TaskWorkerState>;
+    /** Reactive mirror of {@link TaskWorker.busy}. */
+    readonly busy$: ReadonlySignalHandle<boolean>;
+}
+/** Standalone named RPC handler executed inside a Web Worker. */
+export type WorkerRpcHandler<TInput = void, TResult = unknown> = WorkerTaskHandler<TInput, TResult>;
+/** Explicit map of named worker RPC handlers. */
+export type WorkerRpcHandlers = Record<string, WorkerRpcHandler<unknown, unknown>>;
+/** Reusable RPC-style worker handle with named method dispatch. */
+export interface RpcWorker<TRoutes extends WorkerRpcHandlers = WorkerRpcHandlers> {
+    /** Current lifecycle state. */
+    readonly state: TaskWorkerState;
+    /** Whether a method call is currently in progress. */
+    readonly busy: boolean;
+    /**
+     * Call one named RPC method in the backing worker.
+     *
+     * @param method - Method name from the provided RPC handler map
+     * @param input - Serializable payload for the selected method
+     * @param options - Per-call timeout, abort, and transfer options
+     */
+    call<TMethod extends keyof TRoutes & string>(method: TMethod, input: Parameters<TRoutes[TMethod]>[0], options?: TaskRunOptions): Promise<Awaited<ReturnType<TRoutes[TMethod]>>>;
+    /**
+     * Permanently terminate the backing worker.
+     * Any in-flight call is rejected with a termination error.
+     */
+    terminate(): void;
+}
+/**
+ * Reactive wrapper around a reusable RPC worker.
+ *
+ * Extends the standard {@link RpcWorker} API with readonly signals so UI code
+ * can observe worker lifecycle changes without polling getters manually.
+ */
+export interface ReactiveRpcWorker<TRoutes extends WorkerRpcHandlers = WorkerRpcHandlers> extends RpcWorker<TRoutes> {
+    /** Reactive mirror of {@link RpcWorker.state}. */
+    readonly state$: ReadonlySignalHandle<TaskWorkerState>;
+    /** Reactive mirror of {@link RpcWorker.busy}. */
+    readonly busy$: ReadonlySignalHandle<boolean>;
+}
+/** Reusable pool of task workers with bounded concurrency and queueing. */
+export interface TaskPool<TInput = void, TResult = unknown> {
+    /** Current lifecycle state. */
+    readonly state: TaskWorkerState;
+    /** Whether the pool has active or queued tasks. */
+    readonly busy: boolean;
+    /** Maximum number of parallel worker runs. */
+    readonly concurrency: number;
+    /** Number of tasks currently running. */
+    readonly pending: number;
+    /** Number of tasks currently waiting in the queue. */
+    readonly size: number;
+    /**
+     * Queue or immediately execute one task in the pool.
+     *
+     * @param input - Serializable task input
+     * @param options - Per-run timeout, abort, and transfer options
+     */
+    run(input: TInput, options?: TaskRunOptions): Promise<TResult>;
+    /**
+     * Remove queued tasks that have not started yet.
+     * Active tasks continue running.
+     */
+    clear(): void;
+    /**
+     * Permanently terminate the pool and all backing workers.
+     * Active and queued tasks reject with termination errors.
+     */
+    terminate(): void;
+}
+/**
+ * Reactive wrapper around a reusable task pool.
+ *
+ * Extends the standard {@link TaskPool} API with readonly signals for pool
+ * state, queue pressure, and configured concurrency.
+ */
+export interface ReactiveTaskPool<TInput = void, TResult = unknown> extends TaskPool<TInput, TResult> {
+    /** Reactive mirror of {@link TaskPool.state}. */
+    readonly state$: ReadonlySignalHandle<TaskWorkerState>;
+    /** Reactive mirror of {@link TaskPool.busy}. */
+    readonly busy$: ReadonlySignalHandle<boolean>;
+    /** Reactive mirror of {@link TaskPool.concurrency}. */
+    readonly concurrency$: ReadonlySignalHandle<number>;
+    /** Reactive mirror of {@link TaskPool.pending}. */
+    readonly pending$: ReadonlySignalHandle<number>;
+    /** Reactive mirror of {@link TaskPool.size}. */
+    readonly size$: ReadonlySignalHandle<number>;
+}
+/** Reusable pool of RPC workers with bounded concurrency and queueing. */
+export interface RpcPool<TRoutes extends WorkerRpcHandlers = WorkerRpcHandlers> {
+    /** Current lifecycle state. */
+    readonly state: TaskWorkerState;
+    /** Whether the pool has active or queued calls. */
+    readonly busy: boolean;
+    /** Maximum number of parallel worker calls. */
+    readonly concurrency: number;
+    /** Number of calls currently running. */
+    readonly pending: number;
+    /** Number of calls currently waiting in the queue. */
+    readonly size: number;
+    /**
+     * Queue or immediately execute one RPC call in the pool.
+     *
+     * @param method - Method name from the provided RPC handler map
+     * @param input - Serializable payload for the selected method
+     * @param options - Per-call timeout, abort, and transfer options
+     */
+    call<TMethod extends keyof TRoutes & string>(method: TMethod, input: Parameters<TRoutes[TMethod]>[0], options?: TaskRunOptions): Promise<Awaited<ReturnType<TRoutes[TMethod]>>>;
+    /**
+     * Remove queued calls that have not started yet.
+     * Active calls continue running.
+     */
+    clear(): void;
+    /**
+     * Permanently terminate the pool and all backing workers.
+     * Active and queued calls reject with termination errors.
+     */
+    terminate(): void;
+}
+/**
+ * Reactive wrapper around a reusable RPC pool.
+ *
+ * Extends the standard {@link RpcPool} API with readonly signals for pool
+ * state, queue pressure, and configured concurrency.
+ */
+export interface ReactiveRpcPool<TRoutes extends WorkerRpcHandlers = WorkerRpcHandlers> extends RpcPool<TRoutes> {
+    /** Reactive mirror of {@link RpcPool.state}. */
+    readonly state$: ReadonlySignalHandle<TaskWorkerState>;
+    /** Reactive mirror of {@link RpcPool.busy}. */
+    readonly busy$: ReadonlySignalHandle<boolean>;
+    /** Reactive mirror of {@link RpcPool.concurrency}. */
+    readonly concurrency$: ReadonlySignalHandle<number>;
+    /** Reactive mirror of {@link RpcPool.pending}. */
+    readonly pending$: ReadonlySignalHandle<number>;
+    /** Reactive mirror of {@link RpcPool.size}. */
+    readonly size$: ReadonlySignalHandle<number>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/concurrency/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/concurrency/types.ts"],"names":[],"mappings":"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"}