@mark1russell7/collections 0.0.0-stage → 0.2.0

package/build/testing/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The checks of the contract suite. The suite does not import a test framework, so a runtime
+ * entry of this package does not load one. A failed check throws `ContractViolation`.
+ */
+/** The error of a failed check of the contract suite. */
+export declare class ContractViolation extends Error {
+  override readonly name = "ContractViolation";
+}
+/** This function gives the text of a value for a message: JSON, with a `Map` as its entries. */
+export declare function show(value: unknown): string;
+/**
+ * This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps
+ * are equal when they have the same keys with equal values, in any order.
+ */
+export declare function deepEqual(actual: unknown, expected: unknown): boolean;
+/** This function throws `ContractViolation` when the two values are not deeply equal. */
+export declare function same(actual: unknown, expected: unknown, what: string): void;
+/** This function throws `ContractViolation` when the condition is false. */
+export declare function holds(condition: boolean, what: string): void;
+/**
+ * This function starts an operation that must fail with a rejected promise, and gives the error.
+ * A synchronous throw breaks the contract too: each method of a storage gives a promise.
+ */
+export declare function rejects(start: () => Promise<unknown>, what: string): Promise<unknown>;
+//# sourceMappingURL=index.d.ts.map

package/build/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/testing/check.ts"],"mappings":";;;;;qBAMa,0BAA0B;oBACnB;;;wBAIJ,KAAK;;;;;wBAmBL,UAAU,iBAAiB;;wBAqB3B,KAAK,iBAAiB,mBAAmB;;wBAOzC,MAAM,oBAAoB;;;;;wBAQpB,QAAQ,aAAa,kBAAkB,eAAe"}

package/build/testing/index.js

@@ -0,0 +1,72 @@
+// src/testing/check.ts
+/**
+* The checks of the contract suite. The suite does not import a test framework, so a runtime
+* entry of this package does not load one. A failed check throws `ContractViolation`.
+*/
+/** The error of a failed check of the contract suite. */
+var ContractViolation = class extends Error {
+	name = "ContractViolation";
+};
+/** This function gives the text of a value for a message: JSON, with a `Map` as its entries. */
+function show(value) {
+	if (value === void 0) return "undefined";
+	try {
+		return JSON.stringify(value, (_key, item) => item instanceof Map ? { Map: [...item.entries()] } : item === void 0 ? "<undefined>" : item);
+	} catch {
+		return String(value);
+	}
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+/**
+* This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps
+* are equal when they have the same keys with equal values, in any order.
+*/
+function deepEqual(actual, expected) {
+	if (Object.is(actual, expected)) return true;
+	if (actual instanceof Map && expected instanceof Map) {
+		if (actual.size !== expected.size) return false;
+		for (const [key, value] of actual) if (!expected.has(key) || !deepEqual(value, expected.get(key))) return false;
+		return true;
+	}
+	if (Array.isArray(actual) && Array.isArray(expected)) return actual.length === expected.length && actual.every((item, index) => deepEqual(item, expected[index]));
+	if (isPlainObject(actual) && isPlainObject(expected)) {
+		const keys = Object.keys(actual);
+		if (keys.length !== Object.keys(expected).length) return false;
+		return keys.every((key) => Object.prototype.hasOwnProperty.call(expected, key) && deepEqual(actual[key], expected[key]));
+	}
+	return false;
+}
+/** This function throws `ContractViolation` when the two values are not deeply equal. */
+function same(actual, expected, what) {
+	if (!deepEqual(actual, expected)) throw new ContractViolation(`${what}: expected ${show(expected)}, got ${show(actual)}`);
+}
+/** This function throws `ContractViolation` when the condition is false. */
+function holds(condition, what) {
+	if (!condition) throw new ContractViolation(what);
+}
+/**
+* This function starts an operation that must fail with a rejected promise, and gives the error.
+* A synchronous throw breaks the contract too: each method of a storage gives a promise.
+*/
+async function rejects(start, what) {
+	let promise;
+	try {
+		promise = start();
+	} catch (error) {
+		throw new ContractViolation(`${what}: the method threw at once (${show(error instanceof Error ? error.message : error)}), and did not give a rejected promise`);
+	}
+	holds(typeof promise?.then === "function", `${what}: the method did not give a promise`);
+	try {
+		await promise;
+	} catch (error) {
+		return error;
+	}
+	throw new ContractViolation(`${what}: the promise did not reject`);
+}
+export { ContractViolation, deepEqual, holds, rejects, same, show };
+
+//# sourceMappingURL=index.js.map

package/build/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/testing/check.ts"],"sourcesContent":["/**\n * The checks of the contract suite. The suite does not import a test framework, so a runtime\n * entry of this package does not load one. A failed check throws `ContractViolation`.\n */\n\n/** The error of a failed check of the contract suite. */\nexport class ContractViolation extends Error {\n  override readonly name = \"ContractViolation\";\n}\n\n/** This function gives the text of a value for a message: JSON, with a `Map` as its entries. */\nexport function show(value: unknown): string {\n  if (value === undefined) return \"undefined\";\n  try {\n    return JSON.stringify(value, (_key, item: unknown) => (item instanceof Map ? { Map: [...item.entries()] } : item === undefined ? \"<undefined>\" : item));\n  } catch {\n    return String(value);\n  }\n}\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  if (typeof value !== \"object\" || value === null) return false;\n  const prototype = Object.getPrototypeOf(value) as unknown;\n  return prototype === Object.prototype || prototype === null;\n}\n\n/**\n * This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps\n * are equal when they have the same keys with equal values, in any order.\n */\nexport function deepEqual(actual: unknown, expected: unknown): boolean {\n  if (Object.is(actual, expected)) return true;\n  if (actual instanceof Map && expected instanceof Map) {\n    if (actual.size !== expected.size) return false;\n    for (const [key, value] of actual) {\n      if (!expected.has(key) || !deepEqual(value, expected.get(key))) return false;\n    }\n    return true;\n  }\n  if (Array.isArray(actual) && Array.isArray(expected)) {\n    return actual.length === expected.length && actual.every((item, index) => deepEqual(item, expected[index]));\n  }\n  if (isPlainObject(actual) && isPlainObject(expected)) {\n    const keys = Object.keys(actual);\n    if (keys.length !== Object.keys(expected).length) return false;\n    return keys.every((key) => Object.prototype.hasOwnProperty.call(expected, key) && deepEqual(actual[key], expected[key]));\n  }\n  return false;\n}\n\n/** This function throws `ContractViolation` when the two values are not deeply equal. */\nexport function same(actual: unknown, expected: unknown, what: string): void {\n  if (!deepEqual(actual, expected)) {\n    throw new ContractViolation(`${what}: expected ${show(expected)}, got ${show(actual)}`);\n  }\n}\n\n/** This function throws `ContractViolation` when the condition is false. */\nexport function holds(condition: boolean, what: string): void {\n  if (!condition) throw new ContractViolation(what);\n}\n\n/**\n * This function starts an operation that must fail with a rejected promise, and gives the error.\n * A synchronous throw breaks the contract too: each method of a storage gives a promise.\n */\nexport async function rejects(start: () => Promise<unknown>, what: string): Promise<unknown> {\n  let promise: Promise<unknown>;\n  try {\n    promise = start();\n  } catch (error) {\n    throw new ContractViolation(`${what}: the method threw at once (${show(error instanceof Error ? error.message : error)}), and did not give a rejected promise`);\n  }\n  holds(typeof promise?.then === \"function\", `${what}: the method did not give a promise`);\n  try {\n    await promise;\n  } catch (error) {\n    return error;\n  }\n  throw new ContractViolation(`${what}: the promise did not reject`);\n}\n"],"mappings":";;;;;;AAMA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,OAAyB;AAC3B;;AAGA,SAAgB,KAAK,OAAwB;CAC3C,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,IAAI;EACF,OAAO,KAAK,UAAU,QAAQ,MAAM,SAAmB,gBAAgB,MAAM,EAAE,KAAK,CAAC,GAAG,KAAK,QAAQ,CAAC,EAAE,IAAI,SAAS,KAAA,IAAY,gBAAgB,IAAK;CACxJ,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF;AAEA,SAAS,cAAc,OAAkD;CACvE,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO;CACxD,MAAM,YAAY,OAAO,eAAe,KAAK;CAC7C,OAAO,cAAc,OAAO,aAAa,cAAc;AACzD;;;;;AAMA,SAAgB,UAAU,QAAiB,UAA4B;CACrE,IAAI,OAAO,GAAG,QAAQ,QAAQ,GAAG,OAAO;CACxC,IAAI,kBAAkB,OAAO,oBAAoB,KAAK;EACpD,IAAI,OAAO,SAAS,SAAS,MAAM,OAAO;EAC1C,KAAK,MAAM,CAAC,KAAK,UAAU,QACzB,IAAI,CAAC,SAAS,IAAI,GAAG,KAAK,CAAC,UAAU,OAAO,SAAS,IAAI,GAAG,CAAC,GAAG,OAAO;EAEzE,OAAO;CACT;CACA,IAAI,MAAM,QAAQ,MAAM,KAAK,MAAM,QAAQ,QAAQ,GACjD,OAAO,OAAO,WAAW,SAAS,UAAU,OAAO,OAAO,MAAM,UAAU,UAAU,MAAM,SAAS,MAAM,CAAC;CAE5G,IAAI,cAAc,MAAM,KAAK,cAAc,QAAQ,GAAG;EACpD,MAAM,OAAO,OAAO,KAAK,MAAM;EAC/B,IAAI,KAAK,WAAW,OAAO,KAAK,QAAQ,CAAC,CAAC,QAAQ,OAAO;EACzD,OAAO,KAAK,OAAO,QAAQ,OAAO,UAAU,eAAe,KAAK,UAAU,GAAG,KAAK,UAAU,OAAO,MAAM,SAAS,IAAI,CAAC;CACzH;CACA,OAAO;AACT;;AAGA,SAAgB,KAAK,QAAiB,UAAmB,MAAoB;CAC3E,IAAI,CAAC,UAAU,QAAQ,QAAQ,GAC7B,MAAM,IAAI,kBAAkB,GAAG,KAAK,aAAa,KAAK,QAAQ,EAAE,QAAQ,KAAK,MAAM,GAAG;AAE1F;;AAGA,SAAgB,MAAM,WAAoB,MAAoB;CAC5D,IAAI,CAAC,WAAW,MAAM,IAAI,kBAAkB,IAAI;AAClD;;;;;AAMA,eAAsB,QAAQ,OAA+B,MAAgC;CAC3F,IAAI;CACJ,IAAI;EACF,UAAU,MAAM;CAClB,SAAS,OAAO;EACd,MAAM,IAAI,kBAAkB,GAAG,KAAK,8BAA8B,KAAK,iBAAiB,QAAQ,MAAM,UAAU,KAAK,EAAE,uCAAuC;CAChK;CACA,MAAM,OAAO,SAAS,SAAS,YAAY,GAAG,KAAK,oCAAoC;CACvF,IAAI;EACF,MAAM;CACR,SAAS,OAAO;EACd,OAAO;CACT;CACA,MAAM,IAAI,kBAAkB,GAAG,KAAK,6BAA6B;AACnE"}

package/package.json

@@ -1,6 +1,80 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/collections",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Collections with no dependencies: lists, maps, queues, a summary tree, channels, lazy operations and dependency graphs.",
+  "keywords": [
+    "collections",
+    "data-structures",
+    "tree-map",
+    "priority-queue",
+    "lru",
+    "summary-tree",
+    "channels",
+    "dag",
+    "topological-sort",
+    "typescript"
+  ],
+  "homepage": "https://mark1russell7.github.io/collections/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/collections/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/collections.git",
+    "directory": "packages/collections"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./build/index.js",
+  "types": "./build/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/index.d.ts",
+      "default": "./build/index.js"
+    },
+    "./dag": {
+      "types": "./build/dag/index.d.ts",
+      "default": "./build/dag/index.js"
+    },
+    "./graph": {
+      "types": "./build/graph/index.d.ts",
+      "default": "./build/graph/index.js"
+    },
+    "./testing": {
+      "types": "./build/testing/index.d.ts",
+      "default": "./build/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "build",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/contracts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "devDependencies": {
+    "@mark1russell7/cue": "^2.0.0",
+    "@types/node": "^26.6.5",
+    "esbuild": "^0.28.2",
+    "fast-check": "^4.10.2",
+    "tsdown": "^0.23.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json"
+  }
 }

package/src/async/async-queue.ts

@@ -0,0 +1,481 @@
+/**
+ * AsyncQueue - An async iterable queue with backpressure support.
+ *
+ * The queue is for producer-consumer patterns where producers can wait when
+ * the queue is full and consumers can wait when the queue is empty.
+ * This module implements AsyncIterable for use with for-await-of loops.
+ *
+ * @example
+ * const queue = asyncQueue<number>({ capacity: 10 })
+ *
+ * // Producer
+ * await queue.put(42) // Waits if queue is full
+ *
+ * // Consumer
+ * const value = await queue.take() // Waits if queue is empty
+ *
+ * // Async iteration
+ * for await (const value of queue) {
+ *   console.log(value)
+ * }
+ */
+
+import type { AsyncQueue as IAsyncQueue } from "../interfaces/queue.js";
+
+/**
+ * Options for making an AsyncQueue.
+ */
+export interface AsyncQueueOptions {
+  /**
+   * Maximum capacity. Infinity for unbounded queue.
+   * @default Infinity
+   */
+  capacity?: number;
+
+  /**
+   * Timeout for put/take operations in milliseconds.
+   * @default undefined (no timeout)
+   */
+  timeout?: number;
+}
+
+/**
+ * Resolver for waiting operations.
+ */
+interface Resolver<T> {
+  resolve: (value: T) => void;
+  reject: (reason: any) => void;
+  timeoutId?: ReturnType<typeof setTimeout>;
+}
+
+/** A waiting put: it keeps its element until the queue takes it. */
+interface Putter<T> extends Resolver<void> {
+  element: T;
+}
+
+/**
+ * AsyncQueue<T> - Thread-safe async queue with backpressure.
+ *
+ * Features:
+ * - Blocking put() when full (backpressure)
+ * - Blocking take() when empty
+ * - AsyncIterable support
+ * - Graceful closing
+ * - Timeouts
+ *
+ * Perfect for:
+ * - Producer-consumer patterns
+ * - Rate limiting
+ * - Task queues
+ * - Stream processing
+ */
+export class AsyncQueue<T> implements IAsyncQueue<T> {
+  private buffer: T[] = [];
+  private putters: Putter<T>[] = [];
+  private takers: Resolver<T>[] = [];
+  /** The calls of `peek` that wait: they see the next element, but they do not take it. */
+  private peekers: Resolver<T>[] = [];
+  private _isClosed = false;
+  private readonly capacity: number;
+  private readonly defaultTimeout?: number;
+
+  constructor(options: AsyncQueueOptions = {}) {
+    this.capacity = options.capacity ?? Infinity;
+    if (options.timeout !== undefined) {
+      this.defaultTimeout = options.timeout;
+    }
+  }
+
+  // ========================================================================
+  // Size and state
+  // ========================================================================
+
+  get size(): number {
+    return this.buffer.length;
+  }
+
+  get isEmpty(): boolean {
+    return this.buffer.length === 0;
+  }
+
+  get isFull(): boolean {
+    return this.buffer.length >= this.capacity;
+  }
+
+  get isClosed(): boolean {
+    return this._isClosed;
+  }
+
+  get remainingCapacity(): number {
+    return this.capacity === Infinity ? Infinity : this.capacity - this.buffer.length;
+  }
+
+  // ========================================================================
+  // Blocking operations
+  // ========================================================================
+
+  /**
+   * This method adds an element to the queue.
+   * If the queue is full, waits until space is available. With a capacity of 0, it waits until
+   * a taker takes the element (a rendezvous).
+   *
+   * @throws Error if queue is closed
+   * @throws Error if timeout expires
+   */
+  async put(element: T, timeout?: number): Promise<void> {
+    if (this._isClosed) {
+      throw new Error("Queue is closed");
+    }
+    if (this.tryPutNow(element)) {
+      return;
+    }
+
+    // A waiting peek sees the element of a waiting put (a capacity of 0)
+    this.wakePeekers(element);
+
+    // Queue is full: wait with the element. (Before, a waiting putter kept only its resolve
+    // function, so its element was dropped when space came: BUGS-2026-07 C11.)
+    return new Promise<void>((resolve, reject) => {
+      const putter: Putter<T> = { element, resolve, reject };
+      const timeoutMs = timeout ?? this.defaultTimeout;
+      if (timeoutMs !== undefined) {
+        putter.timeoutId = setTimeout(() => {
+          const index = this.putters.indexOf(putter);
+          if (index !== -1) {
+            this.putters.splice(index, 1);
+          }
+          reject(new Error(`Put timeout after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+      this.putters.push(putter);
+    });
+  }
+
+  /**
+   * Removes and gives an element from the queue.
+   * If the queue is empty, waits until an element is available.
+   *
+   * @throws Error if queue is closed and empty
+   * @throws Error if timeout expires
+   */
+  async take(timeout?: number): Promise<T> {
+    const next = this.takeNow();
+    if (next.found) {
+      return next.element;
+    }
+
+    // If closed and empty, throw
+    if (this._isClosed) {
+      throw new Error("Queue is closed and empty");
+    }
+
+    // Wait for an element
+    return new Promise<T>((resolve, reject) => {
+      const taker: Resolver<T> = { resolve, reject };
+      const timeoutMs = timeout ?? this.defaultTimeout;
+      if (timeoutMs !== undefined) {
+        taker.timeoutId = setTimeout(() => {
+          const index = this.takers.indexOf(taker);
+          if (index !== -1) {
+            this.takers.splice(index, 1);
+          }
+          reject(new Error(`Take timeout after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+      this.takers.push(taker);
+    });
+  }
+
+  /**
+   * This method waits for the next element, as `take` does, but it gives the element to
+   * `onElement` and the closure of the queue to `onClosed`. These calls are synchronous: they
+   * occur in the call that adds the element or closes the queue. The method has no timeout.
+   *
+   * The function that it gives withdraws the wait. A withdrawn wait gets no element, so no
+   * element goes to a taker that left. `select` races its cases with this method.
+   *
+   * @returns A function that withdraws the wait. It gives true when the wait had no element yet.
+   */
+  waitTake(onElement: (element: T) => void, onClosed: (error: Error) => void): () => boolean {
+    const next = this.takeNow();
+    if (next.found) {
+      onElement(next.element);
+      return () => false;
+    }
+    if (this._isClosed) {
+      onClosed(new Error("Queue is closed and empty"));
+      return () => false;
+    }
+    const taker: Resolver<T> = { resolve: onElement, reject: onClosed };
+    this.takers.push(taker);
+    return () => {
+      const index = this.takers.indexOf(taker);
+      if (index === -1) return false;
+      this.takers.splice(index, 1);
+      return true;
+    };
+  }
+
+  // ========================================================================
+  // Non-blocking operations
+  // ========================================================================
+
+  /**
+   * This method tries to add an element without waiting.
+   * This method gives false if queue is full (with a capacity of 0: if no taker waits).
+   */
+  tryPut(element: T): boolean {
+    if (this._isClosed) {
+      return false;
+    }
+    return this.tryPutNow(element);
+  }
+
+  /**
+   * This method tries to remove an element without waiting.
+   * This method gives undefined if queue is empty.
+   */
+  tryTake(): T | undefined {
+    const next = this.takeNow();
+    return next.found ? next.element : undefined;
+  }
+
+  /** This method gives the element to a waiting taker, or puts it in the buffer when there is space. */
+  private tryPutNow(element: T): boolean {
+    // A waiting taker gets the element directly (the buffer is empty when a taker waits)
+    const taker = this.takers.shift();
+    if (taker) {
+      this.wakePeekers(element);
+      this.clearTimeout(taker);
+      taker.resolve(element);
+      return true;
+    }
+    if (this.buffer.length < this.capacity) {
+      this.buffer.push(element);
+      this.wakePeekers(element);
+      return true;
+    }
+    return false;
+  }
+
+  /** Each waiting peek gets the element, which stays where it is. */
+  private wakePeekers(element: T): void {
+    const peekers = this.peekers;
+    this.peekers = [];
+    for (const peeker of peekers) {
+      this.clearTimeout(peeker);
+      peeker.resolve(element);
+    }
+  }
+
+  /**
+   * This method takes the next element: from the buffer (then a waiting putter moves its element into the
+   * buffer), or directly from a waiting putter (a capacity of 0). (Before, the direct path
+   * released the putter but did not give its element to the taker, so the taker waited forever:
+   * BUGS-2026-07 C11.)
+   */
+  private takeNow(): { found: true; element: T } | { found: false } {
+    if (this.buffer.length > 0) {
+      const element = this.buffer.shift()!;
+      this.admitPutter();
+      return { found: true, element };
+    }
+    const putter = this.putters.shift();
+    if (putter) {
+      this.clearTimeout(putter);
+      putter.resolve();
+      return { found: true, element: putter.element };
+    }
+    return { found: false };
+  }
+
+  // ========================================================================
+  // Peeking
+  // ========================================================================
+
+  /**
+   * This method gives the next element without removing it.
+   * Waits if queue is empty.
+   */
+  async peek(): Promise<T> {
+    if (this.buffer.length > 0) {
+      return this.buffer[0]!;
+    }
+    if (this.putters.length > 0) {
+      return this.putters[0]!.element;
+    }
+
+    if (this._isClosed) {
+      throw new Error("Queue is closed and empty");
+    }
+
+    // Wait for the next element without a take. (Before, peek took the element and put it back
+    // at the front: a take that waited after it kept waiting, and the order changed: audit pass 2.)
+    return new Promise<T>((resolve, reject) => {
+      const peeker: Resolver<T> = { resolve, reject };
+      const timeoutMs = this.defaultTimeout;
+      if (timeoutMs !== undefined) {
+        peeker.timeoutId = setTimeout(() => {
+          const index = this.peekers.indexOf(peeker);
+          if (index !== -1) {
+            this.peekers.splice(index, 1);
+          }
+          reject(new Error(`Peek timeout after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }
+      this.peekers.push(peeker);
+    });
+  }
+
+  /**
+   * This method gives the next element without waiting.
+   * This method gives undefined if queue is empty.
+   */
+  tryPeek(): T | undefined {
+    return this.buffer.length > 0 ? this.buffer[0] : this.putters[0]?.element;
+  }
+
+  // ========================================================================
+  // Closing and draining
+  // ========================================================================
+
+  /**
+   * This method closes the queue. No more elements can be added.
+   * Existing elements can still be consumed.
+   */
+  close(): void {
+    this._isClosed = true;
+
+    // Reject all waiting putters
+    for (const putter of this.putters) {
+      this.clearTimeout(putter);
+      putter.reject(new Error("Queue closed"));
+    }
+    this.putters = [];
+
+    // Wake up takers if queue is empty
+    if (this.buffer.length === 0) {
+      for (const taker of this.takers) {
+        this.clearTimeout(taker);
+        taker.reject(new Error("Queue closed and empty"));
+      }
+      this.takers = [];
+      for (const peeker of this.peekers) {
+        this.clearTimeout(peeker);
+        peeker.reject(new Error("Queue closed and empty"));
+      }
+      this.peekers = [];
+    }
+  }
+
+  /**
+   * This method drains all elements into an array.
+   * This method gives immediately with current elements.
+   */
+  drain(): T[] {
+    // The buffer, then the elements of the waiting putters, in order. (Before, the waiting
+    // putters were released but their elements were dropped.)
+    const elements = this.buffer.slice();
+    this.buffer = [];
+    for (const putter of this.putters.splice(0)) {
+      this.clearTimeout(putter);
+      putter.resolve();
+      elements.push(putter.element);
+    }
+    return elements;
+  }
+
+  // ========================================================================
+  // Async iteration
+  // ========================================================================
+
+  /**
+   * Async iterator that yields elements as they become available.
+   * Stops when queue is closed and empty.
+   */
+  async *[Symbol.asyncIterator](): AsyncIterator<T> {
+    while (true) {
+      const next = this.takeNow();
+      if (next.found) {
+        yield next.element;
+      } else if (this._isClosed) {
+        break;
+      } else {
+        let element: T;
+        try {
+          element = await this.take();
+        } catch (error) {
+          // The queue was closed while the iterator waited
+          if (this._isClosed) break;
+          throw error;
+        }
+        yield element;
+      }
+    }
+  }
+
+  // ========================================================================
+  // Private helpers
+  // ========================================================================
+
+  /** When the buffer has space, the first waiting putter moves its element into it. */
+  private admitPutter(): void {
+    if (this.putters.length > 0 && this.buffer.length < this.capacity) {
+      const putter = this.putters.shift()!;
+      this.clearTimeout(putter);
+      this.buffer.push(putter.element);
+      putter.resolve();
+    }
+  }
+
+  private clearTimeout(resolver: Resolver<any>): void {
+    if (resolver.timeoutId) {
+      clearTimeout(resolver.timeoutId);
+    }
+  }
+
+  // ========================================================================
+  // Utility methods
+  // ========================================================================
+
+  /**
+   * This method gives statistics about the queue.
+   */
+  getStats() : {
+    size: number;
+    capacity: number;
+    isEmpty: boolean;
+    isFull: boolean;
+    isClosed: boolean;
+    waitingPutters: number;
+    waitingTakers: number;
+    remainingCapacity: number;
+  } {
+    return {
+      size: this.size,
+      capacity: this.capacity,
+      isEmpty: this.isEmpty,
+      isFull: this.isFull,
+      isClosed: this._isClosed,
+      waitingPutters: this.putters.length,
+      waitingTakers: this.takers.length,
+      remainingCapacity: this.remainingCapacity,
+    };
+  }
+
+  toString(): string {
+    return `AsyncQueue[size=${this.size}, capacity=${this.capacity}, closed=${this._isClosed}]`;
+  }
+}
+
+/**
+ * Factory function to make an AsyncQueue.
+ *
+ * @example
+ * const queue = asyncQueue<number>({ capacity: 100 })
+ * await queue.put(42)
+ * const value = await queue.take()
+ */
+export function asyncQueue<T>(options?: AsyncQueueOptions): AsyncQueue<T> {
+  return new AsyncQueue<T>(options);
+}