kerium 1.4.4 → 1.5.0

package/dist/locks.d.ts

@@ -49,4 +49,25 @@ export declare class RwLockable {
     get isLocked(): boolean;
     get lockMode(): LockMode | null;
 }
+/** A synchronization primitive that allows up to `max` concurrent holders. */
+export declare class Semaphore {
+    #private;
+    readonly max: number;
+    constructor(max: number);
+    /** Number of slots currently held */
+    get active(): number;
+    /** Number of acquisitions waiting for a slot */
+    get waiting(): number;
+    /** Whether a slot can be acquired synchronously. This value may be invalid after an `await` */
+    get isAvailable(): boolean;
+    /** Acquire a slot, waiting for one to be freed if the semaphore is full */
+    get(): Promise<LockRelease>;
+    /**
+     * Acquire a slot synchronously. Does not support waiting for a slot to be freed.
+     * @throws EAGAIN if all slots are currently held
+     */
+    getSync(): LockRelease;
+    /** Wait until every currently held slot has been released */
+    drain(): Promise<void>;
+}
 export {};

package/dist/locks.js

@@ -156,3 +156,74 @@ let RwLockable = (() => {
     };
 })();
 export { RwLockable };
+/** A synchronization primitive that allows up to `max` concurrent holders. */
+export class Semaphore {
+    max;
+    /** Release promises for every currently held slot */
+    #active = new Set();
+    /** Callbacks that hand a freed slot to the next waiter, in order */
+    #pending = [];
+    constructor(max) {
+        this.max = max;
+        if (!Number.isInteger(max) || max < 1)
+            throw withErrno('EINVAL', 'Semaphore max must be a positive integer');
+    }
+    /** Number of slots currently held */
+    get active() {
+        return this.#active.size;
+    }
+    /** Number of acquisitions waiting for a slot */
+    get waiting() {
+        return this.#pending.length;
+    }
+    /** Whether a slot can be acquired synchronously. This value may be invalid after an `await` */
+    get isAvailable() {
+        return this.#active.size < this.max;
+    }
+    /** Actually take a slot. The caller must have already added `held` to `#active` */
+    #take(held, resolve) {
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            this.#active.delete(held);
+            resolve();
+            this.#pending.shift()?.();
+        };
+        release[Symbol.dispose] = release;
+        return release;
+    }
+    /** Acquire a slot, waiting for one to be freed if the semaphore is full */
+    async get() {
+        const { promise, resolve } = Promise.withResolvers();
+        if (this.#active.size >= this.max) {
+            const grant = Promise.withResolvers();
+            this.#pending.push(() => {
+                this.#active.add(promise);
+                grant.resolve();
+            });
+            await grant.promise;
+        }
+        else {
+            this.#active.add(promise);
+        }
+        return this.#take(promise, resolve);
+    }
+    /**
+     * Acquire a slot synchronously. Does not support waiting for a slot to be freed.
+     * @throws EAGAIN if all slots are currently held
+     */
+    getSync() {
+        if (this.#active.size >= this.max)
+            throw withErrno('EAGAIN');
+        const { promise, resolve } = Promise.withResolvers();
+        this.#active.add(promise);
+        return this.#take(promise, resolve);
+    }
+    /** Wait until every currently held slot has been released */
+    async drain() {
+        while (this.#active.size)
+            await Promise.all(this.#active);
+    }
+}

package/dist/refs.d.ts

@@ -0,0 +1,7 @@
+export declare class RefCounted implements Disposable {
+    #private;
+    get refCount(): number;
+    ref(): this;
+    unref(): void;
+    [Symbol.dispose](): void;
+}

package/dist/refs.js

@@ -0,0 +1,17 @@
+export class RefCounted {
+    #refCount = 0;
+    get refCount() {
+        return this.#refCount;
+    }
+    ref() {
+        this.#refCount++;
+        return this;
+    }
+    unref() {
+        if (this.#refCount > 0)
+            this.#refCount--;
+    }
+    [Symbol.dispose]() {
+        this.unref();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "kerium",
-	"version": "1.4.4",
+	"version": "1.5.0",
 	"description": "POSIX-style errors, logging, and more",
 	"author": "James Prevett <jp@jamespre.dev> (https://jamespre.dev)",
 	"repository": {