@dmop/puru 0.1.11 → 0.1.13

package/dist/index.d.cts

@@ -9,9 +9,9 @@ type StructuredCloneValue = void | null | undefined | string | number | boolean
 type ChannelValue = Exclude<StructuredCloneValue, null>;
 interface PuruConfig {
     maxThreads: number;
-    strategy: 'fifo' | 'work-stealing';
+    strategy: "fifo" | "work-stealing";
     idleTimeout: number;
-    adapter: 'auto' | 'node' | 'bun' | 'inline';
+    adapter: "auto" | "node" | "bun" | "inline";
     concurrency: number;
 }
 interface SpawnResult<T> {
@@ -213,7 +213,7 @@ declare function withValue<T = unknown>(parent: Context, key: symbol | string, v
  * }, { 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';
+    priority?: "low" | "normal" | "high";
     concurrent?: boolean;
     channels?: TChannels;
     ctx?: Context;
@@ -418,6 +418,77 @@ declare class RWMutex {
     private wakeWriter;
 }
 
+/**
+ * Weighted counting semaphore. Limits concurrent access to a resource where
+ * each acquisition can have a different cost. Modeled after Go's
+ * `golang.org/x/sync/semaphore.Weighted`.
+ *
+ * A `Mutex` is equivalent to `new Semaphore(1)` — one holder at a time.
+ * A `Semaphore` generalizes this to N units, with variable-weight acquisitions.
+ *
+ * Like `Mutex`, this operates on the main thread only. For cross-thread
+ * coordination, use channels instead.
+ *
+ * @example
+ * // Limit to 10 concurrent DB connections
+ * const sem = new Semaphore(10)
+ *
+ * await sem.acquire()     // take 1 slot
+ * try {
+ *   await db.query(...)
+ * } finally {
+ *   sem.release()
+ * }
+ *
+ * @example
+ * // Weighted: heavy queries cost more
+ * const sem = new Semaphore(10)
+ *
+ * await sem.acquire(5)    // heavy query takes 5 slots
+ * sem.release(5)
+ *
+ * @example
+ * // withAcquire — recommended (auto-releases on error)
+ * const result = await sem.withAcquire(async () => {
+ *   return await fetch(url)
+ * })
+ *
+ * @example
+ * // Non-blocking check
+ * if (sem.tryAcquire(3)) {
+ *   try { ... } finally { sem.release(3) }
+ * }
+ */
+declare class Semaphore {
+    private max;
+    private cur;
+    private queue;
+    constructor(n: number);
+    /**
+     * Acquire `n` permits, waiting if necessary until they are available.
+     * Acquires are served in FIFO order.
+     */
+    acquire(n?: number): Promise<void>;
+    /**
+     * Try to acquire `n` permits without blocking.
+     * Returns `true` if successful, `false` if not enough permits are available.
+     */
+    tryAcquire(n?: number): boolean;
+    /**
+     * Release `n` permits, potentially waking queued acquirers.
+     */
+    release(n?: number): void;
+    /**
+     * Acquire `n` permits, run `fn`, then release automatically — even if `fn` throws.
+     */
+    withAcquire<T>(fn: () => T | Promise<T>, n?: number): Promise<T>;
+    /** Number of permits currently available. */
+    get available(): number;
+    /** Total capacity of the semaphore. */
+    get capacity(): number;
+    private wake;
+}
+
 /**
  * Condition variable for async coordination. Modeled after Go's `sync.Cond`.
  *
@@ -763,9 +834,9 @@ declare function resize(maxThreads: number): void;
  */
 declare function shutdown(): Promise<void>;
 
-type Runtime = 'node' | 'deno' | 'bun' | 'browser';
-type Capability = 'full-threads' | 'single-thread';
+type Runtime = "node" | "deno" | "bun" | "browser";
+type Capability = "full-threads" | "single-thread";
 declare function detectRuntime(): Runtime;
 declare function detectCapability(): Capability;
 
-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 };
+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, Semaphore, type SendOnly, type SpawnResult, Ticker, Timer, WaitGroup, after, background, chan, configure, detectCapability, detectRuntime, resize, select, shutdown, spawn, stats, task, ticker, withCancel, withDeadline, withTimeout, withValue };

package/dist/index.d.ts

@@ -9,9 +9,9 @@ type StructuredCloneValue = void | null | undefined | string | number | boolean
 type ChannelValue = Exclude<StructuredCloneValue, null>;
 interface PuruConfig {
     maxThreads: number;
-    strategy: 'fifo' | 'work-stealing';
+    strategy: "fifo" | "work-stealing";
     idleTimeout: number;
-    adapter: 'auto' | 'node' | 'bun' | 'inline';
+    adapter: "auto" | "node" | "bun" | "inline";
     concurrency: number;
 }
 interface SpawnResult<T> {
@@ -213,7 +213,7 @@ declare function withValue<T = unknown>(parent: Context, key: symbol | string, v
  * }, { 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';
+    priority?: "low" | "normal" | "high";
     concurrent?: boolean;
     channels?: TChannels;
     ctx?: Context;
@@ -418,6 +418,77 @@ declare class RWMutex {
     private wakeWriter;
 }
 
+/**
+ * Weighted counting semaphore. Limits concurrent access to a resource where
+ * each acquisition can have a different cost. Modeled after Go's
+ * `golang.org/x/sync/semaphore.Weighted`.
+ *
+ * A `Mutex` is equivalent to `new Semaphore(1)` — one holder at a time.
+ * A `Semaphore` generalizes this to N units, with variable-weight acquisitions.
+ *
+ * Like `Mutex`, this operates on the main thread only. For cross-thread
+ * coordination, use channels instead.
+ *
+ * @example
+ * // Limit to 10 concurrent DB connections
+ * const sem = new Semaphore(10)
+ *
+ * await sem.acquire()     // take 1 slot
+ * try {
+ *   await db.query(...)
+ * } finally {
+ *   sem.release()
+ * }
+ *
+ * @example
+ * // Weighted: heavy queries cost more
+ * const sem = new Semaphore(10)
+ *
+ * await sem.acquire(5)    // heavy query takes 5 slots
+ * sem.release(5)
+ *
+ * @example
+ * // withAcquire — recommended (auto-releases on error)
+ * const result = await sem.withAcquire(async () => {
+ *   return await fetch(url)
+ * })
+ *
+ * @example
+ * // Non-blocking check
+ * if (sem.tryAcquire(3)) {
+ *   try { ... } finally { sem.release(3) }
+ * }
+ */
+declare class Semaphore {
+    private max;
+    private cur;
+    private queue;
+    constructor(n: number);
+    /**
+     * Acquire `n` permits, waiting if necessary until they are available.
+     * Acquires are served in FIFO order.
+     */
+    acquire(n?: number): Promise<void>;
+    /**
+     * Try to acquire `n` permits without blocking.
+     * Returns `true` if successful, `false` if not enough permits are available.
+     */
+    tryAcquire(n?: number): boolean;
+    /**
+     * Release `n` permits, potentially waking queued acquirers.
+     */
+    release(n?: number): void;
+    /**
+     * Acquire `n` permits, run `fn`, then release automatically — even if `fn` throws.
+     */
+    withAcquire<T>(fn: () => T | Promise<T>, n?: number): Promise<T>;
+    /** Number of permits currently available. */
+    get available(): number;
+    /** Total capacity of the semaphore. */
+    get capacity(): number;
+    private wake;
+}
+
 /**
  * Condition variable for async coordination. Modeled after Go's `sync.Cond`.
  *
@@ -763,9 +834,9 @@ declare function resize(maxThreads: number): void;
  */
 declare function shutdown(): Promise<void>;
 
-type Runtime = 'node' | 'deno' | 'bun' | 'browser';
-type Capability = 'full-threads' | 'single-thread';
+type Runtime = "node" | "deno" | "bun" | "browser";
+type Capability = "full-threads" | "single-thread";
 declare function detectRuntime(): Runtime;
 declare function detectCapability(): Capability;
 
-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 };
+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, Semaphore, type SendOnly, type SpawnResult, Ticker, Timer, WaitGroup, after, background, chan, configure, detectCapability, detectRuntime, resize, select, shutdown, spawn, stats, task, ticker, withCancel, withDeadline, withTimeout, withValue };