@dmop/puru 0.1.5 → 0.1.11

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';
@@ -30,11 +39,33 @@ interface SpawnResult<T> {
  *   process(item)
  * }
  */
-interface Channel<T> {
+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;
+    /** Number of values currently buffered. Like Go's `len(ch)`. */
+    readonly len: number;
+    /** Buffer capacity. Like Go's `cap(ch)`. */
+    readonly cap: number;
+    /** Returns a send-only view of this channel. Like Go's `chan<- T`. */
+    sendOnly(): SendOnly<T>;
+    /** Returns a receive-only view of this channel. Like Go's `<-chan T`. */
+    recvOnly(): RecvOnly<T>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+/** Send-only view of a channel. Like Go's `chan<- T`. */
+interface SendOnly<T extends ChannelValue> {
+    send(value: T): Promise<void>;
+    close(): void;
+    readonly len: number;
+    readonly cap: number;
+}
+/** Receive-only view of a channel. Like Go's `<-chan T`. */
+interface RecvOnly<T extends ChannelValue> {
+    recv(): Promise<T | null>;
+    readonly len: number;
+    readonly cap: number;
     [Symbol.asyncIterator](): AsyncIterator<T>;
 }
 /**
@@ -65,7 +96,80 @@ interface Channel<T> {
  *   }, { channels: { input, output } })
  * }
  */
-declare function chan<T extends NonNullable<unknown>>(capacity?: number): Channel<T>;
+declare function chan<T extends ChannelValue>(capacity?: number): Channel<T>;
+
+/**
+ * Hierarchical cancellation, deadlines, and request-scoped values — modeled after Go's `context` package.
+ *
+ * Context is the glue that makes cancellation and timeouts composable. Derive child
+ * contexts from a parent: when the parent is cancelled, all children cancel automatically.
+ *
+ * @example
+ * // Timeout a group of tasks
+ * const [ctx, cancel] = withTimeout(background(), 5000)
+ * const wg = new WaitGroup()
+ * wg.spawn(() => longRunningWork())
+ * ctx.done().then(() => wg.cancel())
+ *
+ * @example
+ * // Nested deadlines
+ * const [parent, cancelParent] = withCancel(background())
+ * const [child, _] = withTimeout(parent, 1000)
+ * // child cancels after 1s OR when cancelParent() is called — whichever comes first
+ *
+ * @example
+ * // Request-scoped values
+ * const reqCtx = withValue(background(), 'requestId', 'abc-123')
+ * reqCtx.value('requestId') // 'abc-123'
+ */
+/** Returned by `ctx.err` when the context was explicitly cancelled. */
+declare class CancelledError extends Error {
+    constructor(message?: string);
+}
+/** Returned by `ctx.err` when the context's deadline has passed. */
+declare class DeadlineExceededError extends Error {
+    constructor();
+}
+type ContextError = CancelledError | DeadlineExceededError;
+interface Context {
+    /** AbortSignal that fires when this context is cancelled or its deadline expires. */
+    readonly signal: AbortSignal;
+    /** The deadline for this context, or `null` if none was set. */
+    readonly deadline: Date | null;
+    /** The cancellation error, or `null` if the context is still active. */
+    readonly err: ContextError | null;
+    /** Retrieves a value stored in this context or any of its ancestors. */
+    value<T = unknown>(key: symbol | string): T | undefined;
+    /** Returns a promise that resolves when the context is cancelled. */
+    done(): Promise<void>;
+}
+type CancelFunc = (reason?: string) => void;
+/**
+ * Returns the root context. It is never cancelled, has no deadline, and carries no values.
+ * All other contexts should derive from this.
+ */
+declare function background(): Context;
+/**
+ * Returns a child context and a cancel function. Calling `cancel()` cancels the child
+ * and all contexts derived from it. The child also cancels when the parent does.
+ */
+declare function withCancel(parent: Context): [Context, CancelFunc];
+/**
+ * Returns a child context that automatically cancels at the given `deadline`.
+ * If the parent has an earlier deadline, that deadline is inherited.
+ * The returned cancel function can cancel early and clears the timer.
+ */
+declare function withDeadline(parent: Context, deadline: Date): [Context, CancelFunc];
+/**
+ * Returns a child context that automatically cancels after `ms` milliseconds.
+ * Equivalent to `withDeadline(parent, new Date(Date.now() + ms))`.
+ */
+declare function withTimeout(parent: Context, ms: number): [Context, CancelFunc];
+/**
+ * Returns a child context carrying a key-value pair.
+ * Values are retrieved with `ctx.value(key)` and looked up through the ancestor chain.
+ */
+declare function withValue<T = unknown>(parent: Context, key: symbol | string, value: T): Context;
 
 /**
  * Run a function in a worker thread. Returns a handle with the result promise and a cancel function.
@@ -108,12 +212,14 @@ declare function chan<T extends NonNullable<unknown>>(capacity?: number): Channe
  *   ch.close()
  * }, { channels: { ch } })
  */
-declare function spawn<T>(fn: (() => T | Promise<T>) | ((channels: Record<string, Channel<unknown>>) => T | Promise<T>), opts?: {
+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;
+    ctx?: Context;
 }): SpawnResult<T>;
 
+type SpawnChannels$1 = Record<string, Channel<ChannelValue>>;
 /**
  * Structured concurrency: spawn multiple tasks and wait for all to complete.
  *
@@ -144,9 +250,11 @@ declare function spawn<T>(fn: (() => T | Promise<T>) | ((channels: Record<string
  *   else console.error(r.reason)
  * }
  */
-declare class WaitGroup {
+declare class WaitGroup<T extends StructuredCloneValue = StructuredCloneValue> {
     private tasks;
     private controller;
+    private ctx?;
+    constructor(ctx?: Context);
     /**
      * An `AbortSignal` shared across all tasks in this group.
      * Pass it into spawned functions so they can stop early when `cancel()` is called.
@@ -157,20 +265,20 @@ declare class WaitGroup {
      *
      * @throws If the group has already been cancelled.
      */
-    spawn(fn: (() => unknown) | ((channels: Record<string, Channel<unknown>>) => unknown), opts?: {
+    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;
     /**
      * Waits for all tasks to complete successfully.
      * Rejects as soon as any task throws.
      */
-    wait(): Promise<unknown[]>;
+    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<unknown>[]>;
+    waitSettled(): Promise<PromiseSettledResult<T>[]>;
     /**
      * Cancels all tasks in the group and signals the shared `AbortSignal`.
      * Already-settled tasks are unaffected.
@@ -178,6 +286,7 @@ declare class WaitGroup {
     cancel(): void;
 }
 
+type SpawnChannels = Record<string, Channel<ChannelValue>>;
 /**
  * Like `WaitGroup`, but cancels all remaining tasks on the first error.
  *
@@ -207,17 +316,29 @@ declare class WaitGroup {
  *   // use task() with register() and check a channel or AbortSignal instead
  * })
  */
-declare class ErrGroup {
+declare class ErrGroup<T extends StructuredCloneValue = StructuredCloneValue> {
     private tasks;
     private controller;
     private firstError;
     private hasError;
+    private ctx?;
+    private limit;
+    private inFlight;
+    private waiting;
+    constructor(ctx?: Context);
     get signal(): AbortSignal;
-    spawn(fn: (() => unknown) | ((channels: Record<string, Channel<unknown>>) => unknown), opts?: {
+    /**
+     * Set the maximum number of tasks that can run concurrently.
+     * Like Go's `errgroup.SetLimit()`. Must be called before any `spawn()`.
+     * A value of 0 (default) means unlimited.
+     */
+    setLimit(n: number): void;
+    spawn<TChannels extends SpawnChannels = 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[]>;
+    private doSpawn;
+    wait(): Promise<T[]>;
     cancel(): void;
 }
 
@@ -258,6 +379,98 @@ declare class Mutex {
     withLock<T>(fn: () => T | Promise<T>): Promise<T>;
     get isLocked(): boolean;
 }
+/**
+ * Async read-write mutex. Multiple readers can hold the lock simultaneously,
+ * but writers get exclusive access. Modeled after Go's `sync.RWMutex`.
+ *
+ * Use this instead of `Mutex` when reads vastly outnumber writes — concurrent
+ * readers improve throughput without sacrificing write safety.
+ *
+ * Like `Mutex`, this operates on the main thread only. For cross-thread
+ * coordination, use channels instead.
+ *
+ * @example
+ * const rw = new RWMutex()
+ *
+ * // Multiple readers can run concurrently
+ * const data = await rw.withRLock(async () => {
+ *   return await db.get('config')
+ * })
+ *
+ * // Writers get exclusive access
+ * await rw.withLock(async () => {
+ *   await db.set('config', newValue)
+ * })
+ */
+declare class RWMutex {
+    private readers;
+    private writing;
+    private readQueue;
+    private writeQueue;
+    rLock(): Promise<void>;
+    rUnlock(): void;
+    lock(): Promise<void>;
+    unlock(): void;
+    withRLock<T>(fn: () => T | Promise<T>): Promise<T>;
+    withLock<T>(fn: () => T | Promise<T>): Promise<T>;
+    get isLocked(): boolean;
+    private wakeReaders;
+    private wakeWriter;
+}
+
+/**
+ * Condition variable for async coordination. Modeled after Go's `sync.Cond`.
+ *
+ * A `Cond` is associated with a `Mutex`. Goroutines (async tasks) can:
+ * - `wait()` — atomically release the lock and suspend until signaled, then re-acquire the lock
+ * - `signal()` — wake one waiting task
+ * - `broadcast()` — wake all waiting tasks
+ *
+ * Always check the condition in a loop — spurious wakeups are possible if
+ * multiple waiters compete for the lock after `broadcast()`.
+ *
+ * @example
+ * const mu = new Mutex()
+ * const cond = new Cond(mu)
+ * let ready = false
+ *
+ * // Waiter
+ * await mu.lock()
+ * while (!ready) {
+ *   await cond.wait()
+ * }
+ * console.log('ready!')
+ * mu.unlock()
+ *
+ * // Signaler (from another async context)
+ * await mu.lock()
+ * ready = true
+ * cond.signal()
+ * mu.unlock()
+ *
+ * @example
+ * // Broadcast to wake all waiters
+ * await mu.lock()
+ * ready = true
+ * cond.broadcast()
+ * mu.unlock()
+ */
+declare class Cond {
+    private mu;
+    private waiters;
+    constructor(mu: Mutex);
+    /**
+     * Atomically releases the mutex, suspends the caller until `signal()` or `broadcast()`
+     * is called, then re-acquires the mutex before returning.
+     *
+     * Must be called while holding the mutex.
+     */
+    wait(): Promise<void>;
+    /** Wake one waiting task (if any). */
+    signal(): void;
+    /** Wake all waiting tasks. */
+    broadcast(): void;
+}
 
 /**
  * Run a function exactly once, even if called concurrently.
@@ -291,7 +504,9 @@ declare class Once<T = void> {
     reset(): void;
 }
 
-type SelectCase<T = unknown> = [Promise<T>, (value: T) => void];
+type RecvCase<T = StructuredCloneValue> = [Promise<T>, (value: T) => void];
+type SendCase = [Promise<void>, () => void];
+type SelectCase<T = StructuredCloneValue> = RecvCase<T> | SendCase;
 /**
  * Options for `select()`.
  *
@@ -307,10 +522,13 @@ interface SelectOptions {
  * Each case is a `[promise, handler]` tuple. The handler for the first settled
  * promise is called with its value. All other handlers are ignored.
  *
+ * **Recv cases:** `[ch.recv(), (value) => ...]` — handler receives the value.
+ * **Send cases:** `[ch.send(value), () => ...]` — handler is called when the send completes.
+ *
  * 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`.
+ * Commonly used with `ch.recv()`, `ch.send()`, `after()`, and `spawn().result`.
  *
  * @example
  * // Block until a channel message arrives or timeout after 5s
@@ -327,6 +545,13 @@ interface SelectOptions {
  * )
  *
  * @example
+ * // Select with send case — try to send or timeout
+ * await select([
+ *   [ch.send(value), () => console.log('sent!')],
+ *   [after(1000), () => console.log('send timed out')],
+ * ])
+ *
+ * @example
  * // Race two worker results against a deadline
  * const { result: fast } = spawn(() => quickSearch(query))
  * const { result: deep } = spawn(() => deepSearch(query))
@@ -406,6 +631,54 @@ declare class Ticker {
  */
 declare function ticker(ms: number): Ticker;
 
+/**
+ * A one-shot timer that can be stopped and reset. Like Go's `time.Timer`.
+ *
+ * Unlike `after()` which is fire-and-forget, `Timer` gives you control:
+ * - `stop()` cancels a pending timer
+ * - `reset(ms)` reschedules without allocating a new object
+ *
+ * The `channel` property is a promise that resolves when the timer fires.
+ * After `stop()`, the promise never resolves. After `reset()`, a new `channel`
+ * promise is created.
+ *
+ * @example
+ * // Basic timeout with ability to cancel
+ * const t = new Timer(5000)
+ * await select([
+ *   [ch.recv(), (v) => { t.stop(); handle(v) }],
+ *   [t.channel, () => console.log('timed out')],
+ * ])
+ *
+ * @example
+ * // Reset a timer (e.g., debounce pattern)
+ * const t = new Timer(300)
+ * onInput(() => t.reset(300))
+ * await t.channel // fires 300ms after last input
+ */
+declare class Timer {
+    private timer;
+    private _stopped;
+    /** Promise that resolves when the timer fires. Replaced on `reset()`. */
+    channel: Promise<void>;
+    constructor(ms: number);
+    private schedule;
+    /**
+     * Stop the timer. Returns `true` if the timer was pending (stopped before firing),
+     * `false` if it had already fired or was already stopped.
+     *
+     * After stopping, the current `channel` promise will never resolve.
+     */
+    stop(): boolean;
+    /**
+     * Reset the timer to fire after `ms` milliseconds.
+     * If the timer was pending, it is stopped first. Creates a new `channel` promise.
+     */
+    reset(ms: number): void;
+    /** Whether the timer has fired or been stopped. */
+    get stopped(): boolean;
+}
+
 /**
  * Define a reusable task that runs in a worker thread.
  *
@@ -427,7 +700,7 @@ declare function ticker(ms: number): Ticker;
  * 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 unknown[], TReturn>(fn: (...args: TArgs) => TReturn | Promise<TReturn>): (...args: TArgs) => Promise<TReturn>;
+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()`.**
@@ -495,4 +768,4 @@ 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, resize, select, shutdown, spawn, stats, task, ticker };
+export { type CancelFunc, CancelledError, type Capability, type Channel, Cond, type Context, type ContextError, DeadlineExceededError, ErrGroup, Mutex, Once, type PoolStats, type PuruConfig, RWMutex, type RecvOnly, type Runtime, type SelectOptions, type SendOnly, type SpawnResult, Ticker, Timer, WaitGroup, after, background, chan, configure, detectCapability, detectRuntime, resize, select, shutdown, spawn, stats, task, ticker, withCancel, withDeadline, withTimeout, withValue };