@mark1russell7/collections 0.9.3 → 0.9.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Collections with no dependencies: lists, maps, queues, a summary tree, channels, lazy operations and dependency graphs.",
   "keywords": [
     "collections",
@@ -77,6 +77,7 @@
     "@mark1russell7/rigor-statistics": "^0.1.8",
     "@mark1russell7/rigor-testkit": "^0.1.0",
     "@types/node": "^26.6.5",
+    "@vitest/coverage-v8": "^5.1.0",
     "esbuild": "^0.28.2",
     "fast-check": "^4.10.2",
     "tsdown": "^0.23.1",

package/src/async/semaphore.ts

@@ -0,0 +1,88 @@
+/**
+ * semaphore - A bound on the tasks that run at the same time.
+ *
+ * @example
+ * const writes = semaphore(4);
+ * // At most 4 writes run at once. The others wait in the order that they came.
+ * await Promise.all(items.map((item) => writes.run(() => store.set(item.id, item))));
+ */
+
+/** A semaphore: a count of permits, and a queue of the callers that wait for one. */
+export interface Semaphore {
+  /** The permits of the semaphore. */
+  readonly permits: number;
+  /** The permits that no caller holds. */
+  readonly available: number;
+  /** The callers that wait for a permit. */
+  readonly waiting: number;
+  /**
+   * This method gives a permit. It waits while all permits are held. The waiting callers get the permits in the order
+   * that they came. The result is the release of the permit. A second call of the release does nothing.
+   */
+  acquire(): Promise<() => void>;
+  /** This method starts a task with a permit. The permit goes back when the task ends, also when it throws. */
+  run<R>(task: () => R | PromiseLike<R>): Promise<R>;
+}
+
+/**
+ * This function makes a semaphore with `permits` permits. The value is a whole number of 1 or more, or `Infinity`
+ * for no bound. Another value throws a `RangeError`.
+ */
+export function semaphore(permits: number): Semaphore {
+  if (!(permits === Infinity || (Number.isInteger(permits) && permits >= 1))) {
+    throw new RangeError(`A semaphore needs a whole number of permits of 1 or more, or Infinity: ${permits}`);
+  }
+  let held = 0;
+  // The waiting callers, in the order that they came. A release gives its permit to the first.
+  const queue: Array<() => void> = [];
+  let head = 0;
+
+  const releaseOnce = (): (() => void) => {
+    let done = false;
+    return () => {
+      if (done) return;
+      done = true;
+      if (head < queue.length) {
+        const next = queue[head]!;
+        head += 1;
+        // The permit goes from the releaser to the next caller, so `held` does not change
+        if (head > 64 && head * 2 > queue.length) {
+          queue.splice(0, head);
+          head = 0;
+        }
+        next();
+      } else {
+        held -= 1;
+      }
+    };
+  };
+
+  const acquire = (): Promise<() => void> => {
+    if (held < permits) {
+      held += 1;
+      return Promise.resolve(releaseOnce());
+    }
+    return new Promise((resolve) => {
+      queue.push(() => resolve(releaseOnce()));
+    });
+  };
+
+  return {
+    permits,
+    get available() {
+      return permits - held;
+    },
+    get waiting() {
+      return queue.length - head;
+    },
+    acquire,
+    async run<R>(task: () => R | PromiseLike<R>): Promise<R> {
+      const release = await acquire();
+      try {
+        return await task();
+      } finally {
+        release();
+      }
+    },
+  };
+}

package/src/index.ts

@@ -93,6 +93,7 @@ export * from "./behaviors/ttl.js";
 export * from "./async/async-queue.js";
 export * from "./async/channels.js";
 export * from "./async/settled.js";
+export * from "./async/semaphore.js";
 
 // ============================================================================
 // Functional Operations
@@ -135,6 +136,7 @@ export { ttlMap, ttlCache, TTLCache, ttlCollection } from "./behaviors/ttl.js";
 // Async/Concurrent
 export { asyncQueue, AsyncQueue } from "./async/async-queue.js";
 export { asSettled, type Settled } from "./async/settled.js";
+export { semaphore, type Semaphore } from "./async/semaphore.js";
 export {
   channel,
   Channel,