@bquery/bquery 1.9.0 → 1.11.0

package/src/concurrency/reactive.ts

@@ -0,0 +1,339 @@
+/**
+ * Reactive wrappers around reusable concurrency primitives.
+ *
+ * @module bquery/concurrency
+ */
+
+import { batch } from '../reactive/batch';
+import { signal, type Signal } from '../reactive/core';
+import { readonly } from '../reactive/readonly';
+import { createRpcPool, createTaskPool } from './pool';
+import { createRpcWorker } from './rpc';
+import { createTaskWorker } from './task';
+import type {
+  CreateRpcPoolOptions,
+  CreateRpcWorkerOptions,
+  CreateTaskPoolOptions,
+  CreateTaskWorkerOptions,
+  ReactiveRpcPool,
+  ReactiveRpcWorker,
+  ReactiveTaskPool,
+  ReactiveTaskWorker,
+  TaskPool,
+  TaskRunOptions,
+  TaskWorker,
+  TaskWorkerState,
+  WorkerRpcHandlers,
+  WorkerTaskHandler,
+} from './types';
+
+interface WorkerSignalMirror {
+  busy: Signal<boolean>;
+  state: Signal<TaskWorkerState>;
+}
+
+interface PoolSignalMirror extends WorkerSignalMirror {
+  concurrency: Signal<number>;
+  pending: Signal<number>;
+  size: Signal<number>;
+}
+
+type WorkerStateSource = Pick<TaskWorker<unknown, unknown>, 'busy' | 'state'>;
+type PoolStateSource = Pick<
+  TaskPool<unknown, unknown>,
+  'busy' | 'concurrency' | 'pending' | 'size' | 'state'
+>;
+
+const syncWorkerSignals = (source: WorkerStateSource, mirror: WorkerSignalMirror): void => {
+  batch(() => {
+    mirror.state.value = source.state;
+    mirror.busy.value = source.busy;
+  });
+};
+
+const syncPoolSignals = (source: PoolStateSource, mirror: PoolSignalMirror): void => {
+  batch(() => {
+    mirror.state.value = source.state;
+    mirror.busy.value = source.busy;
+    mirror.concurrency.value = source.concurrency;
+    mirror.pending.value = source.pending;
+    mirror.size.value = source.size;
+  });
+};
+
+const createWorkerSignalMirror = (source: WorkerStateSource): WorkerSignalMirror => {
+  return {
+    busy: signal(source.busy),
+    state: signal(source.state),
+  };
+};
+
+const createPoolSignalMirror = (source: PoolStateSource): PoolSignalMirror => {
+  return {
+    busy: signal(source.busy),
+    concurrency: signal(source.concurrency),
+    pending: signal(source.pending),
+    size: signal(source.size),
+    state: signal(source.state),
+  };
+};
+
+const attachRunSync = <TResult>(run: Promise<TResult>, sync: () => void): Promise<TResult> => {
+  sync();
+  return run.finally(() => {
+    sync();
+    queueMicrotask(sync);
+  });
+};
+
+/**
+ * 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 function createReactiveTaskWorker<TInput = void, TResult = unknown>(
+  handler: WorkerTaskHandler<TInput, TResult>,
+  options: CreateTaskWorkerOptions = {}
+): ReactiveTaskWorker<TInput, TResult> {
+  const worker = createTaskWorker(handler, options);
+  const mirror = createWorkerSignalMirror(worker as WorkerStateSource);
+  const sync = (): void => {
+    syncWorkerSignals(worker as WorkerStateSource, mirror);
+  };
+
+  return {
+    get busy(): boolean {
+      return worker.busy;
+    },
+    get state(): TaskWorkerState {
+      return worker.state;
+    },
+    busy$: readonly(mirror.busy),
+    state$: readonly(mirror.state),
+    run(input: TInput, runOptions: TaskRunOptions = {}): Promise<TResult> {
+      return attachRunSync(worker.run(input, runOptions), sync);
+    },
+    terminate(): void {
+      worker.terminate();
+      sync();
+    },
+  };
+}
+
+/**
+ * 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 function createReactiveRpcWorker<TRoutes extends WorkerRpcHandlers>(
+  handlers: TRoutes,
+  options: CreateRpcWorkerOptions = {}
+): ReactiveRpcWorker<TRoutes> {
+  const worker = createRpcWorker(handlers, options);
+  const mirror = createWorkerSignalMirror(worker as WorkerStateSource);
+  const sync = (): void => {
+    syncWorkerSignals(worker as WorkerStateSource, mirror);
+  };
+
+  return {
+    get busy(): boolean {
+      return worker.busy;
+    },
+    get state(): TaskWorkerState {
+      return worker.state;
+    },
+    busy$: readonly(mirror.busy),
+    state$: readonly(mirror.state),
+    call<TMethod extends keyof TRoutes & string>(
+      method: TMethod,
+      input: Parameters<TRoutes[TMethod]>[0],
+      runOptions: TaskRunOptions = {}
+    ): Promise<Awaited<ReturnType<TRoutes[TMethod]>>> {
+      return attachRunSync(worker.call(method, input, runOptions), sync);
+    },
+    terminate(): void {
+      worker.terminate();
+      sync();
+    },
+  };
+}
+
+/**
+ * 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 function createReactiveTaskPool<TInput = void, TResult = unknown>(
+  handler: WorkerTaskHandler<TInput, TResult>,
+  options: CreateTaskPoolOptions = {}
+): ReactiveTaskPool<TInput, TResult> {
+  const pool = createTaskPool(handler, options);
+  const mirror = createPoolSignalMirror(pool as PoolStateSource);
+  const sync = (): void => {
+    syncPoolSignals(pool as PoolStateSource, mirror);
+  };
+
+  return {
+    get busy(): boolean {
+      return pool.busy;
+    },
+    get concurrency(): number {
+      return pool.concurrency;
+    },
+    get pending(): number {
+      return pool.pending;
+    },
+    get size(): number {
+      return pool.size;
+    },
+    get state(): TaskWorkerState {
+      return pool.state;
+    },
+    busy$: readonly(mirror.busy),
+    concurrency$: readonly(mirror.concurrency),
+    pending$: readonly(mirror.pending),
+    size$: readonly(mirror.size),
+    state$: readonly(mirror.state),
+    run(input: TInput, runOptions: TaskRunOptions = {}): Promise<TResult> {
+      return attachRunSync(pool.run(input, runOptions), sync);
+    },
+    clear(): void {
+      pool.clear();
+      sync();
+    },
+    terminate(): void {
+      pool.terminate();
+      sync();
+    },
+  };
+}
+
+/**
+ * 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 function createReactiveRpcPool<TRoutes extends WorkerRpcHandlers>(
+  handlers: TRoutes,
+  options: CreateRpcPoolOptions = {}
+): ReactiveRpcPool<TRoutes> {
+  const pool = createRpcPool(handlers, options);
+  const mirror = createPoolSignalMirror(pool as PoolStateSource);
+  const sync = (): void => {
+    syncPoolSignals(pool as PoolStateSource, mirror);
+  };
+
+  return {
+    get busy(): boolean {
+      return pool.busy;
+    },
+    get concurrency(): number {
+      return pool.concurrency;
+    },
+    get pending(): number {
+      return pool.pending;
+    },
+    get size(): number {
+      return pool.size;
+    },
+    get state(): TaskWorkerState {
+      return pool.state;
+    },
+    busy$: readonly(mirror.busy),
+    concurrency$: readonly(mirror.concurrency),
+    pending$: readonly(mirror.pending),
+    size$: readonly(mirror.size),
+    state$: readonly(mirror.state),
+    call<TMethod extends keyof TRoutes & string>(
+      method: TMethod,
+      input: Parameters<TRoutes[TMethod]>[0],
+      runOptions: TaskRunOptions = {}
+    ): Promise<Awaited<ReturnType<TRoutes[TMethod]>>> {
+      return attachRunSync(pool.call(method, input, runOptions), sync);
+    },
+    clear(): void {
+      pool.clear();
+      sync();
+    },
+    terminate(): void {
+      pool.terminate();
+      sync();
+    },
+  };
+}

package/src/concurrency/rpc.ts

@@ -0,0 +1,380 @@
+/**
+ * RPC-style worker communication helpers.
+ *
+ * @module bquery/concurrency
+ */
+
+import {
+  TaskWorkerAbortError,
+  TaskWorkerError,
+  TaskWorkerSerializationError,
+  TaskWorkerTimeoutError,
+  TaskWorkerUnsupportedError,
+} from './errors';
+import {
+  createWorkerInstance,
+  normalizeTimeout,
+  restoreWorkerError,
+  validateTaskHandler,
+  type SerializedWorkerError,
+} from './internal';
+import { isConcurrencySupported } from './support';
+import type {
+  CallWorkerMethodOptions,
+  CreateRpcWorkerOptions,
+  RpcWorker,
+  TaskRunOptions,
+  TaskWorkerState,
+  WorkerRpcHandlers,
+} from './types';
+
+interface WorkerSuccessMessage<TResult> {
+  id: number;
+  result: TResult;
+  type: 'bq:result';
+}
+
+interface WorkerErrorMessage {
+  error: SerializedWorkerError;
+  id: number;
+  type: 'bq:error';
+}
+
+type WorkerResponse<TResult> = WorkerSuccessMessage<TResult> | WorkerErrorMessage;
+
+interface PendingRun<TResult> {
+  abortHandler?: () => void;
+  id: number;
+  reject: (reason?: unknown) => void;
+  resolve: (value: TResult | PromiseLike<TResult>) => void;
+  timeoutId?: ReturnType<typeof setTimeout>;
+}
+
+const WORKER_RPC_MESSAGE = 'bq:rpc';
+
+const validateRpcHandlers = <TRoutes extends WorkerRpcHandlers>(
+  handlers: TRoutes
+): Array<[keyof TRoutes & string, string]> => {
+  const methodNames = Object.keys(handlers) as Array<keyof TRoutes & string>;
+
+  if (methodNames.length === 0) {
+    throw new TaskWorkerSerializationError(
+      'RPC workers require at least one standalone method handler.'
+    );
+  }
+
+  return methodNames.map((method) => {
+    const handler = handlers[method];
+    if (typeof handler !== 'function') {
+      throw new TaskWorkerSerializationError(
+        `RPC handler "${method}" must be a standalone function.`
+      );
+    }
+
+    return [method, validateTaskHandler(handler)];
+  });
+};
+
+const createRpcWorkerScript = (handlerSources: Array<[string, string]>): string => {
+  const assignments = handlerSources
+    .map(([method, source]) => `handlers[${JSON.stringify(method)}] = (${source});`)
+    .join('\n');
+
+  return `'use strict';
+const serializeError = (error) => {
+  if (error && typeof error === 'object') {
+    return {
+      code: typeof error.code === 'string' ? error.code : undefined,
+      message: typeof error.message === 'string' ? error.message : 'Worker RPC call failed.',
+      name: typeof error.name === 'string' ? error.name : 'Error',
+      stack: typeof error.stack === 'string' ? error.stack : undefined,
+    };
+  }
+
+  return {
+    message: typeof error === 'string' ? error : 'Worker RPC call failed.',
+    name: 'Error',
+  };
+};
+
+const handlers = Object.create(null);
+${assignments}
+
+const hasOwn = Object.prototype.hasOwnProperty;
+
+self.onmessage = async (event) => {
+  const message = event.data;
+  if (!message || message.type !== '${WORKER_RPC_MESSAGE}') {
+    return;
+  }
+
+  const method = typeof message.method === 'string' ? message.method : '';
+  if (!hasOwn.call(handlers, method)) {
+    self.postMessage({
+      error: {
+        code: 'METHOD_NOT_FOUND',
+        message: 'Unknown RPC method "' + String(method) + '".',
+        name: 'TaskWorkerError',
+      },
+      id: message.id,
+      type: 'bq:error',
+    });
+    return;
+  }
+
+  try {
+    const result = await handlers[method](message.payload);
+    self.postMessage({ id: message.id, result, type: 'bq:result' });
+  } catch (error) {
+    self.postMessage({ error: serializeError(error), id: message.id, type: 'bq:error' });
+  }
+};`;
+};
+
+/**
+ * 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 function createRpcWorker<TRoutes extends WorkerRpcHandlers>(
+  handlers: TRoutes,
+  options: CreateRpcWorkerOptions = {}
+): RpcWorker<TRoutes> {
+  if (!isConcurrencySupported()) {
+    throw new TaskWorkerUnsupportedError();
+  }
+
+  const handlerSources = validateRpcHandlers(handlers);
+  const scriptSource = createRpcWorkerScript(handlerSources);
+  const defaultTimeout = normalizeTimeout(options.timeout);
+  let disposed = false;
+  let worker: Worker | null = null;
+  let pending: PendingRun<unknown> | null = null;
+  let nextRunId = 0;
+  let pendingAbortSignal: AbortSignal | undefined;
+
+  const cleanupPending = (): void => {
+    if (!pending) {
+      return;
+    }
+
+    if (pending.timeoutId !== undefined) {
+      clearTimeout(pending.timeoutId);
+    }
+
+    if (pending.abortHandler) {
+      pendingAbortSignal?.removeEventListener('abort', pending.abortHandler);
+    }
+
+    pending = null;
+    pendingAbortSignal = undefined;
+  };
+
+  const detachWorker = (): void => {
+    if (!worker) {
+      return;
+    }
+
+    worker.onmessage = null;
+    worker.onerror = null;
+    worker.terminate();
+    worker = null;
+  };
+
+  const rejectPending = (error: Error): void => {
+    if (!pending) {
+      return;
+    }
+
+    const current = pending;
+    cleanupPending();
+    current.reject(error);
+  };
+
+  const ensureWorker = (): Worker => {
+    if (disposed) {
+      throw new TaskWorkerError('The RPC worker has already been terminated.', 'TERMINATED');
+    }
+
+    if (worker) {
+      return worker;
+    }
+
+    const instance = createWorkerInstance(scriptSource, options.name);
+    instance.onmessage = (event: MessageEvent<WorkerResponse<unknown>>) => {
+      const current = pending;
+      if (!current) {
+        return;
+      }
+
+      const message = event.data;
+      if (!message || message.id !== current.id) {
+        return;
+      }
+
+      cleanupPending();
+
+      if (message.type === 'bq:error') {
+        current.reject(restoreWorkerError(message.error));
+        return;
+      }
+
+      current.resolve(message.result);
+    };
+
+    instance.onerror = (event: ErrorEvent) => {
+      const error = new TaskWorkerError(event.message || 'Worker RPC execution failed.', 'WORKER');
+      detachWorker();
+      rejectPending(error);
+    };
+
+    worker = instance;
+    return instance;
+  };
+
+  const resetAfterInterruptedRun = (error: Error): void => {
+    detachWorker();
+    rejectPending(error);
+  };
+
+  return {
+    get busy(): boolean {
+      return pending !== null;
+    },
+    get state(): TaskWorkerState {
+      if (disposed) {
+        return 'terminated';
+      }
+
+      return pending ? 'running' : 'idle';
+    },
+    call<TMethod extends keyof TRoutes & string>(
+      method: TMethod,
+      input: Parameters<TRoutes[TMethod]>[0],
+      runOptions: TaskRunOptions = {}
+    ): Promise<Awaited<ReturnType<TRoutes[TMethod]>>> {
+      if (disposed) {
+        return Promise.reject(
+          new TaskWorkerError('The RPC worker has already been terminated.', 'TERMINATED')
+        );
+      }
+
+      if (pending) {
+        return Promise.reject(
+          new TaskWorkerError(
+            'This RPC worker is already processing a request. Wait for the current call to finish or create another worker.',
+            'BUSY'
+          )
+        );
+      }
+
+      if (runOptions.signal?.aborted) {
+        return Promise.reject(new TaskWorkerAbortError());
+      }
+
+      const activeWorker = ensureWorker();
+      const timeout = normalizeTimeout(runOptions.timeout) ?? defaultTimeout;
+      const runId = nextRunId++;
+
+      return new Promise<Awaited<ReturnType<TRoutes[TMethod]>>>((resolve, reject) => {
+        const current: PendingRun<Awaited<ReturnType<TRoutes[TMethod]>>> = {
+          id: runId,
+          reject,
+          resolve,
+        };
+
+        if (runOptions.signal) {
+          current.abortHandler = () => {
+            resetAfterInterruptedRun(new TaskWorkerAbortError());
+          };
+          pendingAbortSignal = runOptions.signal;
+          runOptions.signal.addEventListener('abort', current.abortHandler, { once: true });
+        }
+
+        if (timeout !== undefined) {
+          current.timeoutId = setTimeout(() => {
+            resetAfterInterruptedRun(
+              new TaskWorkerTimeoutError(`Worker RPC call exceeded the timeout of ${timeout}ms.`)
+            );
+          }, timeout);
+        }
+
+        pending = current as PendingRun<unknown>;
+
+        try {
+          activeWorker.postMessage(
+            { id: runId, method, payload: input, type: WORKER_RPC_MESSAGE },
+            runOptions.transfer ?? []
+          );
+        } catch (error) {
+          detachWorker();
+          rejectPending(
+            new TaskWorkerSerializationError(
+              'Failed to serialize the RPC payload or transfer list for worker execution.',
+              error
+            )
+          );
+        }
+      });
+    },
+    terminate(): void {
+      if (disposed) {
+        return;
+      }
+
+      disposed = true;
+      detachWorker();
+      rejectPending(new TaskWorkerError('The RPC worker was terminated.', 'TERMINATED'));
+    },
+  };
+}
+
+/**
+ * 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 async 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]>>> {
+  const worker = createRpcWorker(handlers, options);
+
+  try {
+    return await worker.call(method, input, options);
+  } finally {
+    worker.terminate();
+  }
+}