@bquery/bquery 1.9.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bquery/bquery",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "The jQuery for the Modern Web Platform - Zero build, TypeScript-first library with reactivity, components, and motion",
   "type": "module",
   "main": "./dist/full.umd.js",
@@ -27,6 +27,10 @@
       "import": "./dist/reactive.es.mjs",
       "types": "./dist/reactive/index.d.ts"
     },
+    "./concurrency": {
+      "import": "./dist/concurrency.es.mjs",
+      "types": "./dist/concurrency/index.d.ts"
+    },
     "./component": {
       "import": "./dist/component.es.mjs",
       "types": "./dist/component/index.d.ts"
@@ -94,6 +98,10 @@
     "./ssr": {
       "import": "./dist/ssr.es.mjs",
       "types": "./dist/ssr/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server.es.mjs",
+      "types": "./dist/server/index.d.ts"
     }
   },
   "files": [
@@ -113,6 +121,7 @@
     "build:lib": "vite build",
     "build:umd": "vite build --config vite.umd.config.ts",
     "build:types": "tsc --emitDeclarationOnly --outDir dist",
+    "check:ai-guidance": "bun scripts/check-ai-guidance.mjs",
     "test": "bun test",
     "test:types": "tsc -p tsconfig.component-test.json --noEmit",
     "test:watch": "bun test --watch",
@@ -155,24 +164,24 @@
   },
   "engines": {
     "node": ">=24.0.0",
-    "bun": ">=1.3.11"
+    "bun": ">=1.3.13"
   },
   "devDependencies": {
-    "@storybook/addon-docs": "^10.3.4",
-    "@storybook/web-components-vite": "^10.3.4",
-    "@typescript-eslint/eslint-plugin": "^8.58.0",
-    "@typescript-eslint/parser": "^8.58.0",
-    "bun-types": "^1.3.11",
-    "eslint": "^10.2.0",
+    "@storybook/addon-docs": "^10.3.6",
+    "@storybook/web-components-vite": "^10.3.6",
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
+    "bun-types": "^1.3.13",
+    "eslint": "^10.2.1",
     "eslint-config-prettier": "^10.1.8",
-    "globals": "^17.4.0",
-    "happy-dom": "^20.8.9",
-    "prettier": "^3.8.1",
+    "globals": "^17.5.0",
+    "happy-dom": "^20.9.0",
+    "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
-    "storybook": "^10.3.4",
-    "typedoc": "^0.28.18",
-    "typescript": "^5.9.3",
-    "vite": "^8.0.3",
+    "storybook": "^10.3.6",
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10",
     "vitepress": "^1.6.4"
   }
 }

package/src/concurrency/errors.ts

@@ -0,0 +1,57 @@
+/**
+ * Error types for the concurrency module.
+ *
+ * @module bquery/concurrency
+ */
+
+import type { TaskWorkerErrorCode } from './types';
+
+/** Base error for concurrency task failures. */
+export class TaskWorkerError extends Error {
+  /** Stable error code for programmatic handling. */
+  code: TaskWorkerErrorCode;
+
+  constructor(message: string, code: TaskWorkerErrorCode, cause?: unknown) {
+    super(message);
+    this.name = 'TaskWorkerError';
+    this.code = code;
+    if (cause !== undefined) {
+      (this as Error & { cause?: unknown }).cause = cause;
+    }
+  }
+}
+
+/** Thrown when the environment cannot create inline Web Workers. */
+export class TaskWorkerUnsupportedError extends TaskWorkerError {
+  constructor(
+    message = 'Concurrency tasks are not supported in this environment.',
+    cause?: unknown
+  ) {
+    super(message, 'UNSUPPORTED', cause);
+    this.name = 'TaskWorkerUnsupportedError';
+  }
+}
+
+/** Thrown when the task handler or payload cannot be serialized safely. */
+export class TaskWorkerSerializationError extends TaskWorkerError {
+  constructor(message: string, cause?: unknown) {
+    super(message, 'SERIALIZATION', cause);
+    this.name = 'TaskWorkerSerializationError';
+  }
+}
+
+/** Thrown when a task exceeds its configured timeout. */
+export class TaskWorkerTimeoutError extends TaskWorkerError {
+  constructor(message: string, cause?: unknown) {
+    super(message, 'TIMEOUT', cause);
+    this.name = 'TaskWorkerTimeoutError';
+  }
+}
+
+/** Thrown when a task is aborted via `AbortSignal`. */
+export class TaskWorkerAbortError extends TaskWorkerError {
+  constructor(message = 'The worker task was aborted.', cause?: unknown) {
+    super(message, 'ABORT', cause);
+    this.name = 'TaskWorkerAbortError';
+  }
+}

package/src/concurrency/high-level.ts

@@ -0,0 +1,387 @@
+/**
+ * Thin high-level helpers layered on top of the explicit worker primitives.
+ *
+ * @module bquery/concurrency
+ */
+
+import { createTaskPool } from './pool';
+import { runTask } from './task';
+import { validateTaskHandler } from './internal';
+import type {
+  ParallelCollectionOptions,
+  ParallelMapHandler,
+  ParallelMapOptions,
+  ParallelOptions,
+  ParallelPredicateHandler,
+  ParallelReduceHandler,
+  ParallelResults,
+  ParallelTask,
+  TaskPool,
+  TaskRunOptions,
+  WorkerTaskHandler,
+} from './types';
+
+interface SerializedParallelTask {
+  handlerSource: string;
+  input: unknown;
+}
+
+interface SerializedChunk<TInput = unknown> {
+  items: Array<{
+    index: number;
+    value: TInput;
+  }>;
+  handlerSource: string;
+}
+
+interface IndexedMapResult<TResult> {
+  index: number;
+  value: TResult;
+}
+
+const executeSerializedTask = async (job: SerializedParallelTask): Promise<unknown> => {
+  const revive = new Function(`return (${job.handlerSource});`);
+  const handler = revive() as ((input: unknown) => unknown | Promise<unknown>) | undefined;
+
+  if (typeof handler !== 'function') {
+    throw new TypeError('The serialized task handler did not revive as a function.');
+  }
+
+  return await handler(job.input);
+};
+
+interface SerializedReduceJob<TInput = unknown, TAccumulator = unknown> {
+  initialValue: TAccumulator;
+  reducerSource: string;
+  values: readonly TInput[];
+}
+
+const executeSerializedChunk = async (
+  job: SerializedChunk
+): Promise<Array<IndexedMapResult<unknown>>> => {
+  const revive = new Function(`return (${job.handlerSource});`);
+  const handler = revive() as
+    | ((value: unknown, index: number) => unknown | Promise<unknown>)
+    | undefined;
+
+  if (typeof handler !== 'function') {
+    throw new TypeError('The serialized collection handler did not revive as a function.');
+  }
+
+  const results: Array<IndexedMapResult<unknown>> = [];
+  for (const item of job.items) {
+    results.push({
+      index: item.index,
+      value: await handler(item.value, item.index),
+    });
+  }
+
+  return results;
+};
+
+const executeSerializedReduce = async (job: SerializedReduceJob): Promise<unknown> => {
+  const revive = new Function(`return (${job.reducerSource});`);
+  const reducer = revive() as
+    | ((accumulator: unknown, value: unknown, index: number) => unknown | Promise<unknown>)
+    | undefined;
+
+  if (typeof reducer !== 'function') {
+    throw new TypeError('The serialized reducer did not revive as a function.');
+  }
+
+  let accumulator = job.initialValue;
+  for (let index = 0; index < job.values.length; index++) {
+    accumulator = await reducer(accumulator, job.values[index], index);
+  }
+
+  return accumulator;
+};
+
+const normalizeBatchSize = (batchSize: number | undefined, label: string): number => {
+  if (batchSize === undefined) {
+    return 1;
+  }
+
+  if (!Number.isInteger(batchSize) || batchSize < 1) {
+    throw new RangeError(`${label} batchSize must be a positive integer.`);
+  }
+
+  return batchSize;
+};
+
+const createSerializedTaskPool = (
+  options: ParallelOptions
+): TaskPool<SerializedParallelTask, unknown> => {
+  return createTaskPool(executeSerializedTask, options);
+};
+
+const serializeTask = <TInput, TResult>(
+  task: ParallelTask<TInput, TResult>
+): SerializedParallelTask => ({
+  handlerSource: validateTaskHandler(task.handler),
+  input: task.input,
+});
+
+const runChunkedHandler = async <TInput, TResult>(
+  values: readonly TInput[],
+  handler: (value: TInput, index: number) => TResult | Promise<TResult>,
+  options: ParallelCollectionOptions = {},
+  label: string
+): Promise<TResult[]> => {
+  if (values.length === 0) {
+    return [];
+  }
+
+  const handlerSource = validateTaskHandler(
+    handler as unknown as WorkerTaskHandler<TInput, TResult>
+  );
+  const { batchSize, signal, ...poolOptions } = options;
+  const normalizedBatchSize = normalizeBatchSize(batchSize, label);
+  const pool = createTaskPool(executeSerializedChunk, poolOptions);
+  const chunks: Array<SerializedChunk<TInput>> = [];
+
+  for (let index = 0; index < values.length; index += normalizedBatchSize) {
+    const end = Math.min(index + normalizedBatchSize, values.length);
+    const items: SerializedChunk<TInput>['items'] = [];
+
+    for (let itemIndex = index; itemIndex < end; itemIndex += 1) {
+      items.push({
+        index: itemIndex,
+        value: values[itemIndex],
+      });
+    }
+
+    chunks.push({ items, handlerSource });
+  }
+
+  try {
+    const chunkResults = await Promise.all(
+      chunks.map((chunk) => pool.run(chunk, signal ? { signal } : undefined))
+    );
+    const mapped = new Array<TResult>(values.length);
+
+    for (const chunk of chunkResults) {
+      for (const item of chunk) {
+        mapped[item.index] = item.value as TResult;
+      }
+    }
+
+    return mapped;
+  } finally {
+    pool.terminate();
+  }
+};
+
+/**
+ * Executes multiple standalone tasks in parallel using a bounded worker pool.
+ *
+ * @example
+ * ```ts
+ * import { parallel } from '@bquery/bquery/concurrency';
+ *
+ * const results = await parallel([
+ *   { handler: (value: number) => value * 2, input: 5 },
+ *   { handler: ({ a, b }: { a: number; b: number }) => a + b, input: { a: 1, b: 2 } },
+ * ]);
+ * ```
+ */
+export async function parallel<TTasks extends readonly ParallelTask[]>(
+  tasks: TTasks,
+  options: ParallelOptions = {}
+): Promise<ParallelResults<TTasks>> {
+  if (tasks.length === 0) {
+    return [] as unknown as ParallelResults<TTasks>;
+  }
+
+  const pool = createSerializedTaskPool(options);
+
+  try {
+    const results = await Promise.all(
+      tasks.map((task) => pool.run(serializeTask(task), task.options))
+    );
+    return results as ParallelResults<TTasks>;
+  } finally {
+    pool.terminate();
+  }
+}
+
+/**
+ * Executes tasks in sequential batches while each batch still uses parallel workers.
+ *
+ * This adapts `threadts-universal`'s batch helper to bQuery without colliding
+ * with the reactive module's existing `batch()` export.
+ *
+ * @example
+ * ```ts
+ * import { batchTasks } from '@bquery/bquery/concurrency';
+ *
+ * const results = await batchTasks(
+ *   [
+ *     { handler: (value: number) => value * 2, input: 1 },
+ *     { handler: (value: number) => value * 2, input: 2 },
+ *     { handler: (value: number) => value * 2, input: 3 },
+ *   ],
+ *   2
+ * );
+ * ```
+ */
+export async function batchTasks<TTasks extends readonly ParallelTask[]>(
+  tasks: TTasks,
+  batchSize?: number,
+  options: ParallelOptions = {}
+): Promise<ParallelResults<TTasks>> {
+  if (tasks.length === 0) {
+    return [] as unknown as ParallelResults<TTasks>;
+  }
+
+  const normalizedBatchSize = normalizeBatchSize(batchSize, 'batchTasks');
+  const pool = createSerializedTaskPool(options);
+  const results: unknown[] = [];
+
+  try {
+    for (let index = 0; index < tasks.length; index += normalizedBatchSize) {
+      const batch = tasks.slice(index, index + normalizedBatchSize);
+      const batchResults = await Promise.all(
+        batch.map((task) => pool.run(serializeTask(task), task.options))
+      );
+      results.push(...batchResults);
+    }
+
+    return results as ParallelResults<TTasks>;
+  } finally {
+    pool.terminate();
+  }
+}
+
+/**
+ * Maps an array in parallel using optional chunking on top of `createTaskPool()`.
+ *
+ * @example
+ * ```ts
+ * import { map } from '@bquery/bquery/concurrency';
+ *
+ * const results = await map([1, 2, 3], (value, index) => value + index, {
+ *   batchSize: 2,
+ *   concurrency: 2,
+ * });
+ * ```
+ */
+export async function map<TInput, TResult>(
+  values: readonly TInput[],
+  mapper: ParallelMapHandler<TInput, TResult>,
+  options: ParallelMapOptions = {}
+): Promise<TResult[]> {
+  return runChunkedHandler(values, mapper, options, 'map');
+}
+
+/**
+ * Filters an array in parallel using a standalone predicate with optional chunking.
+ */
+export async function filter<TInput>(
+  values: readonly TInput[],
+  predicate: ParallelPredicateHandler<TInput>,
+  options: ParallelCollectionOptions = {}
+): Promise<TInput[]> {
+  const matches = await runChunkedHandler(values, predicate, options, 'filter');
+  const filtered: TInput[] = [];
+
+  for (let index = 0; index < values.length; index += 1) {
+    if (!matches[index]) {
+      continue;
+    }
+
+    if (index in values) {
+      filtered.push(values[index] as TInput);
+    } else {
+      filtered.length += 1;
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Returns whether at least one array item matches a standalone predicate.
+ *
+ * The current implementation evaluates predicate chunks explicitly and reduces
+ * the final boolean result on the main thread instead of using hidden globals
+ * or speculative worker cancellation.
+ */
+export async function some<TInput>(
+  values: readonly TInput[],
+  predicate: ParallelPredicateHandler<TInput>,
+  options: ParallelCollectionOptions = {}
+): Promise<boolean> {
+  if (values.length === 0) {
+    return false;
+  }
+
+  const matches = await runChunkedHandler(values, predicate, options, 'some');
+  return matches.some(Boolean);
+}
+
+/**
+ * Returns whether every array item matches a standalone predicate.
+ *
+ * The current implementation evaluates predicate chunks explicitly and reduces
+ * the final boolean result on the main thread instead of using hidden globals
+ * or speculative worker cancellation.
+ */
+export async function every<TInput>(
+  values: readonly TInput[],
+  predicate: ParallelPredicateHandler<TInput>,
+  options: ParallelCollectionOptions = {}
+): Promise<boolean> {
+  if (values.length === 0) {
+    return true;
+  }
+
+  const matches = await runChunkedHandler(values, predicate, options, 'every');
+  return matches.every(Boolean);
+}
+
+/**
+ * Finds the first array item that matches a standalone predicate.
+ */
+export async function find<TInput>(
+  values: readonly TInput[],
+  predicate: ParallelPredicateHandler<TInput>,
+  options: ParallelCollectionOptions = {}
+): Promise<TInput | undefined> {
+  if (values.length === 0) {
+    return undefined;
+  }
+
+  const matches = await runChunkedHandler(values, predicate, options, 'find');
+  const index = matches.findIndex(Boolean);
+  return index === -1 ? undefined : values[index];
+}
+
+/**
+ * Reduces an array inside one isolated worker while preserving standard
+ * left-to-right accumulator semantics.
+ */
+export async function reduce<TInput, TAccumulator>(
+  values: readonly TInput[],
+  reducer: ParallelReduceHandler<TAccumulator, TInput>,
+  initialValue: TAccumulator,
+  options: TaskRunOptions = {}
+): Promise<TAccumulator> {
+  if (values.length === 0) {
+    return initialValue;
+  }
+
+  const reducerSource = validateTaskHandler(
+    reducer as unknown as WorkerTaskHandler<unknown, unknown>
+  );
+
+  return runTask(
+    executeSerializedReduce,
+    {
+      initialValue,
+      reducerSource,
+      values,
+    },
+    options
+  ) as Promise<TAccumulator>;
+}

package/src/concurrency/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Optional concurrency helpers built on zero-build Web Workers.
+ *
+ * The concurrency surface intentionally stays browser-first and explicit:
+ * worker tasks, RPC helpers, bounded pools, and thin high-level helpers
+ * without decorators, hidden global runtimes, or build-time worker glue.
+ *
+ * @module bquery/concurrency
+ */
+
+export {
+  TaskWorkerAbortError,
+  TaskWorkerError,
+  TaskWorkerSerializationError,
+  TaskWorkerTimeoutError,
+  TaskWorkerUnsupportedError,
+} from './errors';
+export { batchTasks, every, filter, find, map, parallel, reduce, some } from './high-level';
+export { pipeline } from './pipeline';
+export { createRpcPool, createTaskPool } from './pool';
+export {
+  createReactiveRpcPool,
+  createReactiveRpcWorker,
+  createReactiveTaskPool,
+  createReactiveTaskWorker,
+} from './reactive';
+export { callWorkerMethod, createRpcWorker } from './rpc';
+export { getConcurrencySupport, isConcurrencySupported } from './support';
+export { createTaskWorker, runTask } from './task';
+
+export type {
+  CallWorkerMethodOptions,
+  ConcurrencyPipeline,
+  ConcurrencyPipelineOptions,
+  ConcurrencySupport,
+  CreateRpcPoolOptions,
+  CreateRpcWorkerOptions,
+  CreateTaskPoolOptions,
+  CreateTaskWorkerOptions,
+  ParallelCollectionOptions,
+  ParallelMapHandler,
+  ParallelMapOptions,
+  ParallelOptions,
+  ParallelPredicateHandler,
+  ParallelReduceHandler,
+  ParallelResults,
+  ParallelTask,
+  ReactiveRpcPool,
+  ReactiveRpcWorker,
+  ReactiveTaskPool,
+  ReactiveTaskWorker,
+  RpcPool,
+  RpcWorker,
+  RunTaskOptions,
+  TaskPool,
+  TaskRunOptions,
+  TaskWorker,
+  TaskWorkerErrorCode,
+  TaskWorkerState,
+  WorkerRpcHandler,
+  WorkerRpcHandlers,
+  WorkerTaskHandler,
+} from './types';

package/src/concurrency/internal.ts

@@ -0,0 +1,100 @@
+/**
+ * Internal helpers shared across concurrency implementations.
+ *
+ * @internal
+ */
+
+import { TaskWorkerError, TaskWorkerSerializationError, TaskWorkerTimeoutError } from './errors';
+import type { TaskWorkerErrorCode, WorkerTaskHandler } from './types';
+
+/** @internal */
+export interface SerializedWorkerError {
+  /** Untrusted serialized worker payload; validate against TaskWorkerErrorCode before use. */
+  code?: string;
+  message?: string;
+  name?: string;
+  stack?: string;
+}
+
+const TASK_WORKER_ERROR_CODES = new Set<TaskWorkerErrorCode>([
+  'ABORT',
+  'BUSY',
+  'METHOD_NOT_FOUND',
+  'QUEUE_CLEARED',
+  'QUEUE_FULL',
+  'SERIALIZATION',
+  'TERMINATED',
+  'TIMEOUT',
+  'UNSUPPORTED',
+  'WORKER',
+]);
+
+const NATIVE_FUNCTION_SOURCE_RE = /\{\s*\[native code\]\s*\}$/u;
+
+/** @internal */
+export const isTaskWorkerErrorCode = (code: string | undefined): code is TaskWorkerErrorCode => {
+  return typeof code === 'string' && TASK_WORKER_ERROR_CODES.has(code as TaskWorkerErrorCode);
+};
+
+/** @internal */
+export const normalizeTimeout = (timeout?: number): number | undefined => {
+  if (typeof timeout !== 'number' || !Number.isFinite(timeout) || timeout <= 0) {
+    return undefined;
+  }
+
+  return timeout;
+};
+
+/** @internal */
+export const validateTaskHandler = <TInput, TResult>(
+  handler: WorkerTaskHandler<TInput, TResult>
+): string => {
+  const source = Function.prototype.toString.call(handler).trim();
+
+  if (!source || NATIVE_FUNCTION_SOURCE_RE.test(source)) {
+    throw new TaskWorkerSerializationError(
+      'Task handlers must be standalone user-defined functions or arrow functions.'
+    );
+  }
+
+  try {
+    const revived = new Function(`return (${source});`)() as unknown;
+    if (typeof revived !== 'function') {
+      throw new TypeError('Task handler did not revive as a function.');
+    }
+  } catch (error) {
+    throw new TaskWorkerSerializationError(
+      'Task handlers must be standalone functions that can be reconstructed in a worker context.',
+      error
+    );
+  }
+
+  return source;
+};
+
+/** @internal */
+export const createWorkerInstance = (scriptSource: string, name?: string): Worker => {
+  const blob = new Blob([scriptSource], { type: 'text/javascript' });
+  const scriptUrl = URL.createObjectURL(blob);
+
+  try {
+    return new Worker(scriptUrl, name ? { name } : undefined);
+  } finally {
+    URL.revokeObjectURL(scriptUrl);
+  }
+};
+
+/** @internal */
+export const restoreWorkerError = (payload: SerializedWorkerError | undefined): TaskWorkerError => {
+  const message = payload?.message || 'Worker task failed.';
+  const code = isTaskWorkerErrorCode(payload?.code) ? payload.code : 'WORKER';
+  const error =
+    code === 'TIMEOUT' ? new TaskWorkerTimeoutError(message) : new TaskWorkerError(message, code);
+
+  error.name = payload?.name || error.name;
+  if (payload?.stack) {
+    error.stack = payload.stack;
+  }
+
+  return error;
+};