@dmop/puru 0.1.4 → 0.1.10

package/dist/index.d.cts

@@ -1,3 +1,12 @@
+interface JsonObject {
+    [key: string]: JsonValue;
+}
+type JsonValue = null | string | number | boolean | JsonValue[] | JsonObject;
+interface StructuredCloneObject {
+    [key: string]: StructuredCloneValue;
+}
+type StructuredCloneValue = void | null | undefined | string | number | boolean | bigint | Date | RegExp | Error | ArrayBuffer | ArrayBufferView | StructuredCloneValue[] | Map<StructuredCloneValue, StructuredCloneValue> | Set<StructuredCloneValue> | StructuredCloneObject;
+type ChannelValue = Exclude<StructuredCloneValue, null>;
 interface PuruConfig {
     maxThreads: number;
     strategy: 'fifo' | 'work-stealing';
@@ -10,46 +19,248 @@ interface SpawnResult<T> {
     cancel: () => void;
 }
 
-interface Channel<T> {
+/**
+ * A Go-style channel for communicating between async tasks and across worker threads.
+ *
+ * Use `chan<T>(capacity?)` to create a channel. Values must be structured-cloneable
+ * (no functions, symbols, or WeakRefs). `null` cannot be sent — `recv()` returns
+ * `null` only when the channel is closed.
+ *
+ * @example
+ * const ch = chan<number>(10)
+ * await ch.send(42)
+ * const value = await ch.recv() // 42
+ * ch.close()
+ * await ch.recv() // null — channel closed
+ *
+ * @example
+ * // Async iteration ends automatically when the channel is closed
+ * for await (const item of ch) {
+ *   process(item)
+ * }
+ */
+interface Channel<T extends ChannelValue> {
     send(value: T): Promise<void>;
+    /** Resolves with the next value, or `null` if the channel is closed. */
     recv(): Promise<T | null>;
     close(): void;
     [Symbol.asyncIterator](): AsyncIterator<T>;
 }
-declare function chan<T>(capacity?: number): Channel<T>;
+/**
+ * Create a Go-style channel for communicating between tasks and across worker threads.
+ *
+ * Provides backpressure: `send()` blocks when the buffer is full,
+ * `recv()` blocks when the buffer is empty. Channel values must be structured-cloneable
+ * (no functions, symbols, or WeakRefs). `null` cannot be sent — it signals closure.
+ *
+ * @param capacity Buffer size. `0` (default) = unbuffered: each `send()` blocks until a `recv()` is ready.
+ *
+ * @example
+ * const ch = chan<string>(5) // buffered channel, capacity 5
+ * await ch.send('hello')
+ * const msg = await ch.recv() // 'hello'
+ * ch.close()
+ *
+ * @example
+ * // Fan-out: multiple workers pulling from the same channel
+ * const input = chan<Job>(50)
+ * const output = chan<Result>(50)
+ *
+ * for (let i = 0; i < 4; i++) {
+ *   spawn(async ({ input, output }) => {
+ *     for await (const job of input) {
+ *       await output.send(processJob(job))
+ *     }
+ *   }, { channels: { input, output } })
+ * }
+ */
+declare function chan<T extends ChannelValue>(capacity?: number): Channel<T>;
 
-declare function spawn<T>(fn: (() => T | Promise<T>) | ((channels: Record<string, Channel<unknown>>) => T | Promise<T>), opts?: {
+/**
+ * Run a function in a worker thread. Returns a handle with the result promise and a cancel function.
+ *
+ * **Functions must be self-contained** — they are serialized via `.toString()` and sent to a
+ * worker thread, so they cannot capture variables from the enclosing scope. Define everything
+ * you need inside the function body, or use `task()` to pass arguments.
+ *
+ * **Two modes:**
+ * - Default (exclusive): the function gets a dedicated thread. Best for CPU-bound work (> 5ms).
+ * - `{ concurrent: true }`: many tasks share a thread's event loop. Best for async/I/O work.
+ *
+ * @example
+ * // CPU-bound work — define helpers inside the function body
+ * const { result } = spawn(() => {
+ *   function fibonacci(n: number): number {
+ *     if (n <= 1) return n
+ *     return fibonacci(n - 1) + fibonacci(n - 2)
+ *   }
+ *   return fibonacci(40)
+ * })
+ * console.log(await result)
+ *
+ * @example
+ * // I/O-bound work — concurrent mode shares threads efficiently
+ * const { result } = spawn(() => fetch('https://api.example.com').then(r => r.json()), {
+ *   concurrent: true,
+ * })
+ *
+ * @example
+ * // Cancel a long-running task
+ * const { result, cancel } = spawn(() => longRunningTask())
+ * setTimeout(cancel, 5000)
+ *
+ * @example
+ * // Cross-thread channels — pass channels via opts.channels
+ * const ch = chan<number>(10)
+ * spawn(async ({ ch }) => {
+ *   for (let i = 0; i < 100; i++) await ch.send(i)
+ *   ch.close()
+ * }, { channels: { ch } })
+ */
+declare function spawn<T extends StructuredCloneValue, TChannels extends Record<string, Channel<ChannelValue>> = Record<never, never>>(fn: (() => T | Promise<T>) | ((channels: TChannels) => T | Promise<T>), opts?: {
     priority?: 'low' | 'normal' | 'high';
     concurrent?: boolean;
-    channels?: Record<string, Channel<unknown>>;
+    channels?: TChannels;
 }): SpawnResult<T>;
 
-declare class WaitGroup {
+type SpawnChannels$1 = Record<string, Channel<ChannelValue>>;
+/**
+ * Structured concurrency: spawn multiple tasks and wait for all to complete.
+ *
+ * Like `Promise.all`, but tasks run in worker threads across CPU cores. Results are
+ * returned in the order tasks were spawned. A shared `AbortSignal` lets long-running
+ * tasks observe cooperative cancellation via `cancel()`.
+ *
+ * For fail-fast behavior (cancel all on first error), use `ErrGroup` instead.
+ *
+ * @example
+ * // CPU-bound parallel work
+ * const wg = new WaitGroup()
+ * wg.spawn(() => { /* define helpers inside — no closure captures *\/ })
+ * wg.spawn(() => { /* another CPU task *\/ })
+ * const [r1, r2] = await wg.wait()
+ *
+ * @example
+ * // Mixed CPU + I/O
+ * wg.spawn(() => crunchNumbers(), )
+ * wg.spawn(() => fetch('https://api.example.com').then(r => r.json()), { concurrent: true })
+ * const results = await wg.wait()
+ *
+ * @example
+ * // Tolerate partial failures with waitSettled
+ * const settled = await wg.waitSettled()
+ * for (const r of settled) {
+ *   if (r.status === 'fulfilled') use(r.value)
+ *   else console.error(r.reason)
+ * }
+ */
+declare class WaitGroup<T extends StructuredCloneValue = StructuredCloneValue> {
     private tasks;
     private controller;
+    /**
+     * An `AbortSignal` shared across all tasks in this group.
+     * Pass it into spawned functions so they can stop early when `cancel()` is called.
+     */
     get signal(): AbortSignal;
-    spawn(fn: (() => unknown) | ((channels: Record<string, Channel<unknown>>) => unknown), opts?: {
+    /**
+     * Spawns a function on a worker thread and adds it to the group.
+     *
+     * @throws If the group has already been cancelled.
+     */
+    spawn<TChannels extends SpawnChannels$1 = Record<never, never>>(fn: (() => T | Promise<T>) | ((channels: TChannels) => T | Promise<T>), opts?: {
         concurrent?: boolean;
-        channels?: Record<string, Channel<unknown>>;
+        channels?: TChannels;
     }): void;
-    wait(): Promise<unknown[]>;
-    waitSettled(): Promise<PromiseSettledResult<unknown>[]>;
+    /**
+     * Waits for all tasks to complete successfully.
+     * Rejects as soon as any task throws.
+     */
+    wait(): Promise<T[]>;
+    /**
+     * Waits for all tasks to settle (fulfilled or rejected) and returns each outcome.
+     * Never rejects — inspect each `PromiseSettledResult` to handle failures individually.
+     */
+    waitSettled(): Promise<PromiseSettledResult<T>[]>;
+    /**
+     * Cancels all tasks in the group and signals the shared `AbortSignal`.
+     * Already-settled tasks are unaffected.
+     */
     cancel(): void;
 }
 
-declare class ErrGroup {
+type SpawnChannels = Record<string, Channel<ChannelValue>>;
+/**
+ * Like `WaitGroup`, but cancels all remaining tasks on the first error.
+ *
+ * Modeled after Go's `golang.org/x/sync/errgroup`. Use when partial results are useless —
+ * if any task fails, there is no point waiting for the rest. Benchmarks show ~3.7x faster
+ * failure handling than waiting for all tasks to settle.
+ *
+ * For "wait for everything regardless of failures", use `WaitGroup` with `waitSettled()`.
+ *
+ * @example
+ * const eg = new ErrGroup()
+ * eg.spawn(() => run('fetchUser', userId))
+ * eg.spawn(() => run('fetchOrders', userId))
+ * eg.spawn(() => run('fetchAnalytics', userId))
+ *
+ * try {
+ *   const [user, orders, analytics] = await eg.wait()
+ * } catch (err) {
+ *   // First failure cancelled the rest — no partial data to clean up
+ * }
+ *
+ * @example
+ * // Observe cancellation inside a task via the shared signal
+ * const eg = new ErrGroup()
+ * eg.spawn(() => {
+ *   // eg.signal is not directly available inside the worker —
+ *   // use task() with register() and check a channel or AbortSignal instead
+ * })
+ */
+declare class ErrGroup<T extends StructuredCloneValue = StructuredCloneValue> {
     private tasks;
     private controller;
     private firstError;
     private hasError;
     get signal(): AbortSignal;
-    spawn(fn: () => unknown, opts?: {
+    spawn<TChannels extends SpawnChannels = Record<never, never>>(fn: (() => T | Promise<T>) | ((channels: TChannels) => T | Promise<T>), opts?: {
         concurrent?: boolean;
+        channels?: TChannels;
     }): void;
-    wait(): Promise<unknown[]>;
+    wait(): Promise<T[]>;
     cancel(): void;
 }
 
+/**
+ * Async mutual exclusion. Serializes access to shared state under concurrency.
+ *
+ * Prefer `withLock()` over manual `lock()`/`unlock()` — it automatically releases
+ * the lock even if the callback throws.
+ *
+ * Note: `Mutex` operates on the main thread (or whichever thread creates it).
+ * Worker threads do not share memory, so this is not useful for cross-thread locking.
+ * For cross-thread coordination, use channels instead.
+ *
+ * @example
+ * const mu = new Mutex()
+ *
+ * // withLock — recommended (auto-unlocks on error)
+ * const result = await mu.withLock(async () => {
+ *   const current = await db.get('counter')
+ *   await db.set('counter', current + 1)
+ *   return current + 1
+ * })
+ *
+ * @example
+ * // Manual lock/unlock (use withLock instead when possible)
+ * await mu.lock()
+ * try {
+ *   // critical section
+ * } finally {
+ *   mu.unlock()
+ * }
+ */
 declare class Mutex {
     private queue;
     private locked;
@@ -59,6 +270,30 @@ declare class Mutex {
     get isLocked(): boolean;
 }
 
+/**
+ * Run a function exactly once, even if called concurrently.
+ * All callers await the same promise and receive the same result.
+ *
+ * Use for lazy, one-time initialization of expensive resources (DB pools, ML models,
+ * config, etc.) that must be initialized at most once regardless of concurrent demand.
+ *
+ * @example
+ * const initDB = new Once<DBPool>()
+ *
+ * async function getDB() {
+ *   return initDB.do(() => createPool({ max: 10 }))
+ * }
+ *
+ * // Safe under concurrent load — pool is created exactly once
+ * const [db1, db2] = await Promise.all([getDB(), getDB()])
+ * // db1 === db2 (same pool instance)
+ *
+ * @example
+ * // Check if initialization has already run
+ * if (!initDB.done) {
+ *   console.log('not yet initialized')
+ * }
+ */
 declare class Once<T = void> {
     private promise;
     private called;
@@ -67,14 +302,99 @@ declare class Once<T = void> {
     reset(): void;
 }
 
-type SelectCase<T = unknown> = [Promise<T>, (value: T) => void];
+type SelectCase<T = StructuredCloneValue> = [Promise<T>, (value: T) => void];
+/**
+ * Options for `select()`.
+ *
+ * `default` makes the call non-blocking: if no case is immediately ready,
+ * the default handler runs instead of waiting. This mirrors Go's `select { default: ... }`.
+ */
 interface SelectOptions {
     default?: () => void;
 }
+/**
+ * Wait for the first of multiple promises to resolve, like Go's `select`.
+ *
+ * Each case is a `[promise, handler]` tuple. The handler for the first settled
+ * promise is called with its value. All other handlers are ignored.
+ *
+ * If `opts.default` is provided, `select` becomes non-blocking: if no promise
+ * is already resolved, the default runs immediately (Go's `select { default: ... }`).
+ *
+ * Commonly used with `ch.recv()`, `after()`, and `spawn().result`.
+ *
+ * @example
+ * // Block until a channel message arrives or timeout after 5s
+ * await select([
+ *   [ch.recv(), (value) => console.log('received', value)],
+ *   [after(5000), () => console.log('timed out')],
+ * ])
+ *
+ * @example
+ * // Non-blocking: check a channel without waiting
+ * await select(
+ *   [[ch.recv(), (value) => process(value)]],
+ *   { default: () => console.log('channel empty — doing other work') },
+ * )
+ *
+ * @example
+ * // Race two worker results against a deadline
+ * const { result: fast } = spawn(() => quickSearch(query))
+ * const { result: deep } = spawn(() => deepSearch(query))
+ *
+ * let response: Result
+ * await select([
+ *   [fast, (r) => { response = r }],
+ *   [after(200), () => { response = { partial: true } }],
+ * ])
+ */
 declare function select(cases: SelectCase[], opts?: SelectOptions): Promise<void>;
 
+/**
+ * Returns a promise that resolves after `ms` milliseconds.
+ *
+ * Designed for use with `select()` to add timeouts to channel operations or
+ * race a deadline against worker results. Also works as a simple async delay.
+ *
+ * @example
+ * // Timeout a channel receive after 2 seconds
+ * await select([
+ *   [ch.recv(), (value) => handle(value)],
+ *   [after(2000), () => handleTimeout()],
+ * ])
+ *
+ * @example
+ * // Simple delay
+ * await after(500)
+ * console.log('500ms later')
+ */
 declare function after(ms: number): Promise<void>;
 
+/**
+ * A repeating timer that ticks at a fixed interval.
+ *
+ * Implements `AsyncIterable<void>` — use `for await...of` to run work on each tick.
+ * Call `stop()` to cancel the ticker and end the iteration.
+ *
+ * Create with the `ticker(ms)` factory function.
+ *
+ * @example
+ * const t = ticker(1000) // tick every second
+ * for await (const _ of t) {
+ *   await doWork()
+ *   if (shouldStop) t.stop() // ends the for-await loop
+ * }
+ *
+ * @example
+ * // Use with select() to process work on each tick with a timeout
+ * const t = ticker(5000)
+ * for await (const _ of t) {
+ *   await select([
+ *     [spawn(() => checkHealth()).result, (ok) => report(ok)],
+ *     [after(4000), () => report('timeout')],
+ *   ])
+ * }
+ */
 declare class Ticker {
     private interval;
     private resolve;
@@ -85,12 +405,59 @@ declare class Ticker {
     stop(): void;
     [Symbol.asyncIterator](): AsyncIterator<void>;
 }
+/**
+ * Create a `Ticker` that fires every `ms` milliseconds.
+ *
+ * @example
+ * const t = ticker(500)
+ * for await (const _ of t) {
+ *   console.log('tick')
+ *   if (done) t.stop()
+ * }
+ */
 declare function ticker(ms: number): Ticker;
 
-type TaskFn = (...args: unknown[]) => unknown;
-declare function register(name: string, fn: TaskFn): void;
-declare function run<T = unknown>(name: string, ...args: unknown[]): Promise<T>;
+/**
+ * Define a reusable task that runs in a worker thread.
+ *
+ * Returns a typed async function — call it like a regular async function,
+ * and it dispatches to the thread pool each time.
+ *
+ * Use task() when you have the same function to call many times with
+ * different arguments. For one-off work, use spawn() instead.
+ *
+ * Arguments must be JSON-serializable (no functions, symbols, undefined, or BigInt).
+ * The function itself must be self-contained — it cannot capture enclosing scope variables.
+ *
+ * @example
+ * const resizeImage = task((src: string, width: number, height: number) => {
+ *   // runs in a worker thread
+ *   return processPixels(src, width, height)
+ * })
+ *
+ * const result = await resizeImage('photo.jpg', 800, 600)
+ * const [a, b] = await Promise.all([resizeImage('a.jpg', 400, 300), resizeImage('b.jpg', 800, 600)])
+ */
+declare function task<TArgs extends JsonValue[], TReturn extends StructuredCloneValue>(fn: (...args: TArgs) => TReturn | Promise<TReturn>): (...args: TArgs) => Promise<TReturn>;
 
+/**
+ * Configure the global thread pool. **Must be called before the first `spawn()`.**
+ *
+ * After the pool is initialized, calling `configure()` throws. Call it once at
+ * application startup or in test setup.
+ *
+ * @example
+ * configure({
+ *   maxThreads: 4,          // default: os.availableParallelism()
+ *   concurrency: 64,        // max concurrent tasks per shared worker (default: 64)
+ *   idleTimeout: 30_000,    // kill idle workers after 30s (default: 30_000)
+ *   adapter: 'auto',        // 'auto' | 'node' | 'bun' | 'inline' (default: 'auto')
+ * })
+ *
+ * @example
+ * // In tests: run tasks on the main thread with no real workers
+ * configure({ adapter: 'inline' })
+ */
 declare function configure(opts: Partial<PuruConfig>): void;
 
 interface PoolStats {
@@ -119,10 +486,24 @@ interface PoolStats {
 }
 declare function stats(): PoolStats;
 declare function resize(maxThreads: number): void;
+/**
+ * Gracefully shut down the thread pool.
+ *
+ * Rejects all queued tasks, waits for all workers to terminate, then clears
+ * the pool. Safe to call at process exit or at the end of a test suite.
+ *
+ * ```ts
+ * process.on('SIGTERM', async () => {
+ *   await shutdown()
+ *   process.exit(0)
+ * })
+ * ```
+ */
+declare function shutdown(): Promise<void>;
 
 type Runtime = 'node' | 'deno' | 'bun' | 'browser';
 type Capability = 'full-threads' | 'single-thread';
 declare function detectRuntime(): Runtime;
 declare function detectCapability(): Capability;
 
-export { type Capability, type Channel, ErrGroup, Mutex, Once, type PoolStats, type PuruConfig, type Runtime, type SelectOptions, type SpawnResult, Ticker, WaitGroup, after, chan, configure, detectCapability, detectRuntime, register, resize, run, select, spawn, stats, ticker };
+export { type Capability, type Channel, ErrGroup, Mutex, Once, type PoolStats, type PuruConfig, type Runtime, type SelectOptions, type SpawnResult, Ticker, WaitGroup, after, chan, configure, detectCapability, detectRuntime, resize, select, shutdown, spawn, stats, task, ticker };