@seriousme/opifex 1.11.0 → 1.11.2

package/server/test/handleConnect.test.ts

@@ -1,12 +1,15 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { makeDummyQueueSockConn } from "../../dev_utils/mod.ts";
+import {
+  makeDummyQueueSockConn,
+  resolveNextTick,
+} from "../../dev_utils/mod.ts";
 import {
   type AnyPacket,
   AuthenticationResult,
   PacketType,
 } from "../../mqttPacket/mod.ts";
-import { AsyncQueue, nextTick } from "../../utils/mod.ts";
+import { BufferedAsyncIterable } from "../../utils/mod.ts";
 import { MqttConn, MQTTLevel } from "../deps.ts";
 import { MqttServer } from "../mod.ts";
 import { handlers } from "./test-handlers.ts";
@@ -34,11 +37,11 @@ const disconnectPacket: AnyPacket = {
 const mqttServer = new MqttServer({ handlers });
 
 function startServer(): {
-  reader: AsyncIterableIterator<AnyPacket>;
+  reader: AsyncIterator<AnyPacket>;
   mqttConn: MqttConn;
 } {
-  const reader = new AsyncQueue<Uint8Array>();
-  const writer = new AsyncQueue<Uint8Array>();
+  const reader = new BufferedAsyncIterable<Uint8Array>();
+  const writer = new BufferedAsyncIterable<Uint8Array>();
 
   const outputConn = makeDummyQueueSockConn(writer, reader);
   const mqttConn = new MqttConn({ conn: outputConn });
@@ -66,7 +69,7 @@ test("Authentication with valid username and password works", async () => {
     );
   }
   mqttConn.send(disconnectPacket);
-  await nextTick();
+  await resolveNextTick();
   assert.deepStrictEqual(
     mqttConn.isClosed,
     true,
@@ -92,7 +95,7 @@ test("Authentication with invalid username fails", async () => {
       "Expected badUsernameOrPassword",
     );
   }
-  await nextTick();
+  await resolveNextTick();
   assert.deepStrictEqual(
     mqttConn.isClosed,
     true,
@@ -118,7 +121,7 @@ test("Authentication with invalid password fails", async () => {
       "Expected badUsernameOrPassword",
     );
   }
-  await nextTick();
+  await resolveNextTick();
   assert.deepStrictEqual(
     mqttConn.isClosed,
     true,

package/utils/BufferedAsyncIterable.ts

@@ -0,0 +1,76 @@
+import { Deferred } from "./deferred.ts";
+import { ArrayQueue } from "./queue.ts";
+
+/**
+ * An Async Queue is a queue that can be used to push items to it and then wait
+ * for them to be consumed.
+ *
+ * @example
+ * ```ts
+ * const queue = new AsyncQueue<string>();
+ * queue.push("hello");
+ * for await (const item of queue) {
+ *   console.log(item); // "hello"
+ * }
+ * ```
+ */
+export class BufferedAsyncIterable<T> implements AsyncIterable<T> {
+  private buffer: ArrayQueue<T>;
+  private bufferSize: number;
+
+  private done = false;
+
+  #next?: Deferred<T>;
+
+  constructor(bufferSize: number = 2048) {
+    this.buffer = new ArrayQueue();
+    this.bufferSize = bufferSize;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<Awaited<T>, void, unknown> {
+    while (!this.done) {
+      yield this.next();
+    }
+  }
+
+  next(): T | Promise<T> {
+    // await nextTick();
+    if (this.buffer.size() > 0) {
+      return this.buffer.dequeue()!;
+    } else if (this.done) {
+      throw new Error("Closed");
+    } else if (!this.#next) {
+      this.#next = new Deferred<T>();
+    }
+    return this.#next.promise;
+  }
+
+  close(reason = "closed"): void {
+    this.done = true;
+    if (this.#next) {
+      this.#next.reject(new Error(reason));
+    }
+  }
+
+  readonly push = (item: T): void | Promise<void> => {
+    if (this.#next) {
+      this.#next.resolve(item);
+      this.#next = undefined;
+      return;
+    }
+    this.buffer.enqueue(item);
+    if (this.buffer.size() > this.bufferSize) {
+      // If our current buffer has grown greater than the allowed size we adaptively
+      // wait for an amount of milliseconds proportional to the size of the buffer.
+      // This ensures backpressure is applied to the producer that is pushing items
+      // into the queue. Note that this might be an exceedingly simple heuristic,
+      // a PID (Proportional-Integral-Derivative) controller could be used to improve
+      // the responsiveness of the system.
+      return new Promise((resolve) => setTimeout(resolve, this.buffer.size()));
+    }
+  };
+
+  get isDone(): boolean {
+    return this.done;
+  }
+}

package/utils/mod.ts

@@ -5,5 +5,4 @@
 export { assert } from "./assert.ts";
 export { Deferred } from "./deferred.ts";
 export { Logger, logger, LogLevel } from "./logger.ts";
-export { AsyncQueue } from "./asyncQueue.ts";
-export { nextTick } from "./nextTick.ts";
+export { BufferedAsyncIterable } from "./BufferedAsyncIterable.ts";

package/utils/queue.ts

@@ -0,0 +1,66 @@
+/**
+ * A simple queue implementation using an array.
+ * This implementation optimizes for O(1) enqueue and dequeue operations
+ * by avoiding array shifts, which are O(n).
+ *
+ * Usage:
+ * ```ts
+ * const queue = new ArrayQueue<number>();
+ * queue.enqueue(1);
+ * queue.enqueue(2);
+ * console.log(queue.dequeue()); // 1
+ * console.log(queue.size()); // 1
+ * console.log(queue.isEmpty()); // false
+ * queue.dequeue();
+ * console.log(queue.isEmpty()); // true
+ * ```
+ */
+
+export class ArrayQueue<T> {
+  private items: T[] = [];
+  private headIndex: number = 0; // Tracks the front of the queue
+
+  /**
+   * size is the difference between the actual array length and the index offset
+   * @returns the number of items in the queue
+   */
+  public size(): number {
+    return this.items.length - this.headIndex;
+  }
+  /**
+   * isEmpty checks if the queue has no items
+   * @returns true if the queue is empty
+   */
+  public isEmpty(): boolean {
+    return this.size() === 0;
+  }
+  /**
+   * enqueue adds an item to the end of the queue
+   *  O(1) - Push to the end is highly optimized in V8.
+   */
+  public enqueue(data: T): void {
+    this.items.push(data);
+  }
+  /**
+   * dequeue removes and returns the item at the front of the queue
+   * O(1) - Avoids array shifting by incrementing the index.
+   * @returns the item at the front of the queue or undefined if the queue is empty
+   */
+  public dequeue(): T | undefined {
+    if (this.isEmpty()) {
+      return undefined;
+    }
+
+    const item = this.items[this.headIndex];
+    this.headIndex++; // Move the "front" marker forward
+
+    // Optimization: Periodically "clean up" the dead space
+    // when the empty space (headIndex) exceeds a threshold.
+    // This amortizes the cost, keeping average time closer to O(1).
+    if (this.headIndex > 2000 && this.headIndex > this.items.length / 4) {
+      this.items = this.items.slice(this.headIndex);
+      this.headIndex = 0;
+    }
+    return item;
+  }
+}

package/dist/utils/asyncQueue.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"asyncQueue.d.ts","sourceRoot":"","sources":["../../utils/asyncQueue.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,qBAAa,UAAU,CAAC,CAAC;;IACvB,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,cAAc,CAAY;IAElC,OAAO,CAAC,IAAI,CAAS;gBAIT,cAAc,CAAC,EAAE,MAAM;IAM7B,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC;IAYxB,KAAK,CAAC,MAAM,SAAW,GAAG,IAAI;IAOvB,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC;IAM1E,IAAI,CAAC,IAAI,EAAE,CAAC;IAYZ,IAAI,MAAM,IAAI,OAAO,CAEpB;CACF"}

package/dist/utils/asyncQueue.js

@@ -1,65 +0,0 @@
-import { Deferred } from "./deferred.js";
-import { nextTick } from "./nextTick.js";
-/**
- * An Async Queue is a queue that can be used to push items to it and then wait
- * for them to be consumed.
- *
- * @example
- * ```ts
- * const queue = new AsyncQueue<string>();
- * queue.push("hello");
- * for await (const item of queue) {
- *   console.log(item); // "hello"
- * }
- * ```
- */
-export class AsyncQueue {
-    queue = [];
-    maxQueueLength = Infinity;
-    done = false;
-    #next;
-    constructor(maxQueueLength) {
-        if (maxQueueLength) {
-            this.maxQueueLength = maxQueueLength;
-        }
-    }
-    async next() {
-        await nextTick();
-        if (this.queue.length) {
-            return Promise.resolve(this.queue.shift());
-        }
-        else if (this.done) {
-            return Promise.reject("Closed");
-        }
-        else if (!this.#next) {
-            this.#next = new Deferred();
-        }
-        return this.#next.promise;
-    }
-    close(reason = "closed") {
-        this.done = true;
-        if (this.#next) {
-            this.#next.reject(new Error(reason));
-        }
-    }
-    async *[Symbol.asyncIterator]() {
-        while (true) {
-            yield await this.next();
-        }
-    }
-    push(item) {
-        if (this.#next) {
-            this.#next.resolve(item);
-            this.#next = undefined;
-            return;
-        }
-        if (this.queue.length > this.maxQueueLength) {
-            this.queue.shift();
-        }
-        this.queue.push(item);
-    }
-    get isDone() {
-        return this.done;
-    }
-}
-//# sourceMappingURL=asyncQueue.js.map

package/dist/utils/asyncQueue.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"asyncQueue.js","sourceRoot":"","sources":["../../utils/asyncQueue.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC;;;;;;;;;;;;GAYG;AAEH,MAAM,OAAO,UAAU;IACb,KAAK,GAAQ,EAAE,CAAC;IAChB,cAAc,GAAG,QAAQ,CAAC;IAE1B,IAAI,GAAG,KAAK,CAAC;IAErB,KAAK,CAAe;IAEpB,YAAY,cAAuB;QACjC,IAAI,cAAc,EAAE,CAAC;YACnB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACvC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,QAAQ,EAAE,CAAC;QACjB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YACtB,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAG,CAAC,CAAC;QAC9C,CAAC;aAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACrB,OAAO,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClC,CAAC;aAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YACvB,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,EAAK,CAAC;QACjC,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,MAAM,GAAG,QAAQ;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC3B,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,IAAI,CAAC,IAAO;QACV,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;YACvB,OAAO;QACT,CAAC;QACD,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;YAC5C,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/utils/nextTick.d.ts

@@ -1,17 +0,0 @@
-/**
- * Returns a promise that resolves on the next tick of the Node.js event loop.
- * This is useful for deferring execution of code until after the current call stack is cleared.
- *
- * @example
- * ```ts
- * async function example() {
- *   console.log('Before nextTick');
- *   await nextTick();
- *   console.log('After nextTick');
- * }
- * ```
- *
- * @returns {Promise<void>} A promise that resolves on the next tick of the event loop
- */
-export declare function nextTick(): Promise<void>;
-//# sourceMappingURL=nextTick.d.ts.map

package/dist/utils/nextTick.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"nextTick.d.ts","sourceRoot":"","sources":["../../utils/nextTick.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAExC"}

package/dist/utils/nextTick.js

@@ -1,19 +0,0 @@
-/**
- * Returns a promise that resolves on the next tick of the Node.js event loop.
- * This is useful for deferring execution of code until after the current call stack is cleared.
- *
- * @example
- * ```ts
- * async function example() {
- *   console.log('Before nextTick');
- *   await nextTick();
- *   console.log('After nextTick');
- * }
- * ```
- *
- * @returns {Promise<void>} A promise that resolves on the next tick of the event loop
- */
-export function nextTick() {
-    return new Promise((resolve) => setTimeout(resolve, 0));
-}
-//# sourceMappingURL=nextTick.js.map

package/dist/utils/nextTick.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"nextTick.js","sourceRoot":"","sources":["../../utils/nextTick.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/utils/asyncQueue.ts

@@ -1,71 +0,0 @@
-import { Deferred } from "./deferred.ts";
-import { nextTick } from "./nextTick.ts";
-/**
- * An Async Queue is a queue that can be used to push items to it and then wait
- * for them to be consumed.
- *
- * @example
- * ```ts
- * const queue = new AsyncQueue<string>();
- * queue.push("hello");
- * for await (const item of queue) {
- *   console.log(item); // "hello"
- * }
- * ```
- */
-
-export class AsyncQueue<T> {
-  private queue: T[] = [];
-  private maxQueueLength = Infinity;
-
-  private done = false;
-
-  #next?: Deferred<T>;
-
-  constructor(maxQueueLength?: number) {
-    if (maxQueueLength) {
-      this.maxQueueLength = maxQueueLength;
-    }
-  }
-
-  async next(): Promise<T> {
-    await nextTick();
-    if (this.queue.length) {
-      return Promise.resolve(this.queue.shift()!);
-    } else if (this.done) {
-      return Promise.reject("Closed");
-    } else if (!this.#next) {
-      this.#next = new Deferred<T>();
-    }
-    return this.#next.promise;
-  }
-
-  close(reason = "closed"): void {
-    this.done = true;
-    if (this.#next) {
-      this.#next.reject(new Error(reason));
-    }
-  }
-
-  async *[Symbol.asyncIterator](): AsyncGenerator<Awaited<T>, void, unknown> {
-    while (true) {
-      yield await this.next();
-    }
-  }
-
-  push(item: T) {
-    if (this.#next) {
-      this.#next.resolve(item);
-      this.#next = undefined;
-      return;
-    }
-    if (this.queue.length > this.maxQueueLength) {
-      this.queue.shift();
-    }
-    this.queue.push(item);
-  }
-
-  get isDone(): boolean {
-    return this.done;
-  }
-}

package/utils/nextTick.ts

@@ -1,18 +0,0 @@
-/**
- * Returns a promise that resolves on the next tick of the Node.js event loop.
- * This is useful for deferring execution of code until after the current call stack is cleared.
- *
- * @example
- * ```ts
- * async function example() {
- *   console.log('Before nextTick');
- *   await nextTick();
- *   console.log('After nextTick');
- * }
- * ```
- *
- * @returns {Promise<void>} A promise that resolves on the next tick of the event loop
- */
-export function nextTick(): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, 0));
-}