@seriousme/opifex 1.11.3 → 2.1.0

package/trie/trie.test.ts

@@ -141,7 +141,15 @@ test("Removal of object values works", () => {
   assert.ok(includesAll(root.match("foo/bar"), [c1, c2]), "two items found");
   root.remove("foo/bar", c2);
   assert.ok(includesAll(root.match("foo/bar"), [c1]), "one item found");
-  root.remove("foo/bar", { a: 1, b: 2, c: 3 });
+  // partial filter
+  root.remove("foo/bar", { a: 1 });
   assert.ok(includesAll(root.match("foo/bar"), []), "empty array");
   assert.deepStrictEqual(root.match("foo/bar").length, 0, "matches left");
 });
+
+test("Overlapping topics with empty levels works", () => {
+  const root = new Trie<number>();
+  root.add("foo/bar", 2);
+  root.add("foo/bar/#", 3);
+  assert.ok(includesAll(root.match("foo/bar"), [2, 3]), "two items found");
+});

package/trie/trie.ts

@@ -3,7 +3,7 @@
  * @description A Trie data structure implementation that supports wildcard matching
  * @template T The type of values stored in the trie
  */
-type Parts = string[];
+export type Parts = string[];
 
 /**
  * Trie class for storing and matching hierarchical key-value pairs with wildcard support
@@ -58,14 +58,11 @@ export class Trie<T> {
    * @returns Array of matched values
    */
   private _matchPrefix(parts: Parts): Array<T> {
-    if (parts.length === 0) {
-      return this.#value ? this.#value : [];
-    }
     const [first, ...rest] = parts;
-    if (first !== undefined) {
-      return this.matchChild(first, rest);
-    }
-    return [];
+    if (first === undefined) return [];
+
+    // Direct lookup on the reserved topic node without evaluating top-level + or #
+    return this.matchChild(first, rest);
   }
 
   /**
@@ -74,18 +71,31 @@ export class Trie<T> {
    * @returns Array of matched values
    */
   private _match(parts: Parts): Array<T> {
+    let results: Array<T> = [];
+
+    // 1. Check if there is a multi-level wildcard ('#') at this level.
+    // In MQTT, 'a/#' matches 'a', 'a/b', 'a/b/c', etc.
+    const subtreeNode = this.#children.get(this.wildcardSubtree);
+    if (subtreeNode) {
+      results = results.concat(subtreeNode.#value);
+    }
+
+    // 2. Base case: we reached the end of the topic parts.
     if (parts.length === 0) {
-      return this.#value ? this.#value : [];
+      return results.concat(this.#value);
     }
+
     const [first, ...rest] = parts;
-    if (first !== undefined) {
-      const exact = this.matchChild(first, rest);
-      const single = this.matchChild(this.wildcardOne, rest);
-      const subtree = this.matchChild(this.wildcardSubtree, []);
-      const results = exact.concat(single, subtree);
-      return results;
-    }
-    return [];
+    // deno-coverage-ignore
+    if (first === undefined) return [];
+
+    // 3. Exact matching child node
+    const exact = this.matchChild(first, rest);
+
+    // 4. Single-level wildcard ('+') matching child node
+    const single = this.matchChild(this.wildcardOne, rest);
+
+    return results.concat(exact, single);
   }
 
   /**
@@ -102,23 +112,22 @@ export class Trie<T> {
    * @param parts Parts of the key to add at
    * @param value The value to add
    */
-  private _add(parts: Parts, value: T) {
+  private _add(parts: Parts, value: T): void {
     if (parts.length === 0) {
       this.#value = this.#value.concat(value);
       return;
     }
     const [first, ...rest] = parts;
-    if (first !== undefined) {
-      const child = this.#children.get(first);
-      if (child instanceof Trie) {
-        child._add(rest, value);
-      } else {
-        const node = new Trie<T>(this.looseCompare);
-        this.#children.set(first, node);
-        node._add(rest, value);
-      }
+    // deno-coverage-ignore
+    if (first === undefined) return;
+    const child = this.#children.get(first);
+    if (child instanceof Trie) {
+      child._add(rest, value);
+    } else {
+      const node = new Trie<T>(this.looseCompare);
+      this.#children.set(first, node);
+      node._add(rest, value);
     }
-    return;
   }
 
   /**
@@ -126,7 +135,12 @@ export class Trie<T> {
    * @param key The key to remove the value from
    * @param value The value to remove
    */
-  remove(key: string, value: T): void {
+  /**
+   * Removes a value from the trie at the specified key
+   * @param key The key to remove the value from
+   * @param value The value (or partial object) to remove
+   */
+  remove(key: string, value: Partial<T> | T): void {
     return this._remove(key.split(this.separator), value);
   }
 
@@ -135,40 +149,51 @@ export class Trie<T> {
    * @param parts Parts of the key to remove from
    * @param value The value to remove
    */
-  private _remove(parts: Parts, value: T): void {
+  private _remove(parts: Parts, value: Partial<T> | T): void {
     if (parts.length === 0) {
-      const arr = this.#value || [];
+      const arr = this.#value;
       this.#value = arr.filter(this.filter(value));
       return;
     }
     const [first, ...rest] = parts;
-    if (first !== undefined) {
-      const node = this.#children.get(first);
-      if (node) {
-        node._remove(rest, value);
-        if (node.#value.length === 0 && this.#children.size === 0) {
-          this.#children.delete(first);
-        }
+    // deno-coverage-ignore
+    if (first === undefined) return;
+    const node = this.#children.get(first);
+    if (node) {
+      node._remove(rest, value);
+      if (node.#value.length === 0 && node.#children.size === 0) {
+        this.#children.delete(first);
       }
     }
   }
 
   /**
    * Creates a filter function for removing values
-   * @param value The value to filter against
-   * @returns Filter function
+   * Supports partial object matching when looseCompare is enabled or when matching objects.
+   * @param value The value (or partial value) to filter against
+   * @returns Filter function (returns true to KEEP the item, false to REMOVE it)
    */
-  private filter(value: T): (value: T, index: number, array: T[]) => boolean {
-    if (this.looseCompare && typeof value === "object") {
+  private filter(value: Partial<T> | T): (item: T) => boolean {
+    if (typeof value === "object" && value !== null) {
       return (item) => {
+        if (typeof item !== "object" || item === null) {
+          return true; // Keep if the stored item isn't an object but we are filtering by one
+        }
+
+        // Check if every key-value pair in our filter object matches the stored item
         for (const key in value) {
-          if (value[key] !== item[key]) {
-            return true;
+          if (Object.prototype.hasOwnProperty.call(value, key)) {
+            // If the stored item has a different value (or doesn't have the key), it's not a match
+            if (item[key] !== value[key]) {
+              return true; // Keep the item (no match)
+            }
           }
         }
-        return false;
+        return false; // Remove the item (it matches all criteria in the partial object)
       };
     }
+
+    // Fallback for primitives
     return (item) => item !== value;
   }
 }

package/utils/bufferedAsyncIterable.test.ts

@@ -0,0 +1,92 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { BufferedAsyncIterable } from "./bufferedAsyncIterable.ts";
+
+test("should initialize with correct default state", () => {
+  const iterable = new BufferedAsyncIterable<number>();
+  assert.strictEqual(iterable.isDone, false);
+});
+
+test("should handle immediate push and pull via next()", () => {
+  const iterable = new BufferedAsyncIterable<string>();
+
+  iterable.push("hello");
+  const result = iterable.next();
+
+  assert.strictEqual(result, "hello");
+});
+
+test("should resolve a pending next() call when data is pushed later", async () => {
+  const iterable = new BufferedAsyncIterable<number>();
+
+  const pendingPromise = iterable.next() as Promise<number>;
+
+  // The promise should resolve once we push data
+  iterable.push(42);
+
+  const result = await pendingPromise;
+  assert.strictEqual(result, 42);
+});
+
+test("should work correctly with for-await-of loop", async () => {
+  const iterable = new BufferedAsyncIterable<number>();
+  const items: number[] = [];
+
+  iterable.push(1);
+  iterable.push(2);
+
+  // Read items asynchronously
+  const consumer = async () => {
+    try {
+      for await (const item of iterable) {
+        items.push(item);
+      }
+    } catch (err) {
+      // Expecting a 'Closed' error to break the loop when close() is called
+      assert.match((err as Error).message, /closed/i);
+    }
+  };
+
+  const consumerPromise = consumer();
+
+  // Allow the event loop to process the items, then close the iterable
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  iterable.close();
+
+  await consumerPromise;
+
+  assert.deepStrictEqual(items, [1, 2]);
+});
+
+test("should reject pending promises and throw when closed", async () => {
+  const iterable = new BufferedAsyncIterable<number>();
+
+  const pendingPromise = iterable.next() as Promise<number>;
+
+  iterable.close("custom close reason");
+
+  // The outstanding promise should now reject
+  await assert.rejects(pendingPromise, /custom close reason/);
+
+  // Subsequent calls to next() should instantly throw
+  assert.throws(() => iterable.next(), /Closed/);
+});
+
+test("should apply backpressure when buffer size is exceeded", async () => {
+  // Set a very small buffer size of 1 to easily trigger backpressure
+  const iterable = new BufferedAsyncIterable<number>(1);
+
+  // First item fills the queue size to 1 (equal to bufferSize, no backpressure yet)
+  iterable.push(1);
+
+  // Second item exceeds bufferSize (size becomes 2), returning a backpressure promise
+  const backpressurePromise = iterable.push(2);
+
+  assert.ok(
+    backpressurePromise instanceof Promise,
+    "Should return a promise due to backpressure",
+  );
+
+  // Wait for the backpressure timeout to resolve (proportional to buffer size, 2ms)
+  await backpressurePromise;
+});

package/utils/deferred.test.ts

@@ -0,0 +1,36 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import { Deferred } from "./deferred.ts"; // Note the .js extension if you are using ESM
+
+test("should initialize with a pending promise", async () => {
+  const deferred = new Deferred<string>();
+
+  assert.ok(deferred.promise instanceof Promise);
+
+  // Verify it is indeed pending by racing it against a fast timeout
+  const timeout = new Promise((_, reject) =>
+    setTimeout(() => reject(new Error("Timeout")), 10)
+  );
+  await assert.rejects(Promise.race([deferred.promise, timeout]), /Timeout/);
+});
+
+test("should resolve the promise when resolve() is called", async () => {
+  const deferred = new Deferred<number>();
+
+  deferred.resolve(123);
+
+  const result = await deferred.promise;
+  assert.strictEqual(result, 123);
+});
+
+test("should reject the promise when reject() is called", async () => {
+  const deferred = new Deferred<void>();
+  const testError = new Error("Something went wrong");
+
+  deferred.reject(testError);
+
+  await assert.rejects(deferred.promise, (err: Error) => {
+    assert.strictEqual(err.message, "Something went wrong");
+    return true;
+  });
+});

package/utils/deferred.ts

@@ -1,7 +1,6 @@
 /**
  * Create a promise that can be resolved/rejected later
  */
-
 export class Deferred<T> {
   promise: Promise<T>;
   resolve!: (val: T) => void;

package/utils/getOrInsertPolyFill.ts

@@ -0,0 +1,12 @@
+/*
+ Node 26 has getOrInsert by default.
+ This is a polyfill for older versions
+ */
+
+export function getOrInsert<K, V>(map: Map<K, V>, key: K, defaultValue: V): V {
+  if (map.has(key)) {
+    return map.get(key)!;
+  }
+  map.set(key, defaultValue);
+  return defaultValue;
+}

package/utils/logger.test.ts

@@ -0,0 +1,189 @@
+import { mock, test } from "node:test";
+import assert from "node:assert";
+import { Logger, logger, LogLevel } from "./logger.ts";
+
+// Helper to check if a function is the 'noop' function
+// deno-lint-ignore ban-types
+const isNoop = (fn: Function) =>
+  fn.name === "noop" || fn.toString().includes("noop");
+
+test("default initialization", () => {
+  const testLogger = new Logger();
+
+  // By default, error, warn, and info should be active, while verbose/debug should be noop
+  assert.strictEqual(typeof testLogger.error, "function");
+  assert.strictEqual(typeof testLogger.warn, "function");
+  assert.strictEqual(typeof testLogger.info, "function");
+
+  assert.strictEqual(
+    isNoop(testLogger.verbose),
+    true,
+    "Verbose should be noop by default",
+  );
+  assert.strictEqual(
+    isNoop(testLogger.debug),
+    true,
+    "Debug should be noop by default",
+  );
+});
+
+test("level(LogLevel.error) activates only error", () => {
+  const testLogger = new Logger();
+  testLogger.level(LogLevel.error);
+
+  assert.strictEqual(
+    isNoop(testLogger.warn),
+    true,
+    "Warn should be noop at error level",
+  );
+  assert.strictEqual(
+    isNoop(testLogger.info),
+    true,
+    "Info should be noop at error level",
+  );
+  assert.strictEqual(
+    isNoop(testLogger.verbose),
+    true,
+    "Verbose should be noop at error level",
+  );
+  assert.strictEqual(
+    isNoop(testLogger.debug),
+    true,
+    "Debug should be noop at error level",
+  );
+});
+
+test("level(LogLevel.info) activates warn and info", () => {
+  const testLogger = new Logger();
+  testLogger.level(LogLevel.info);
+
+  assert.strictEqual(
+    isNoop(testLogger.warn),
+    false,
+    "Warn should be active at info level",
+  );
+  assert.strictEqual(
+    isNoop(testLogger.info),
+    false,
+    "Info should be active at info level",
+  );
+  assert.strictEqual(
+    isNoop(testLogger.verbose),
+    true,
+    "Verbose should be noop at info level",
+  );
+  assert.strictEqual(
+    isNoop(testLogger.debug),
+    true,
+    "Debug should be noop at info level",
+  );
+});
+
+test("level(LogLevel.debug) activates all loggers", () => {
+  const testLogger = new Logger();
+  testLogger.level(LogLevel.debug);
+
+  assert.strictEqual(isNoop(testLogger.warn), false);
+  assert.strictEqual(isNoop(testLogger.info), false);
+  assert.strictEqual(isNoop(testLogger.verbose), false);
+  assert.strictEqual(isNoop(testLogger.debug), false);
+});
+
+test("verify that log functions actually execute logging", () => {
+  const testLogger = new Logger();
+
+  // deno-lint-ignore no-explicit-any
+  const debugSpy = mock.method(testLogger as any, "defaultDebug");
+  // set the level, this will connect the spy
+  testLogger.level(LogLevel.debug);
+
+  testLogger.debug("Test debug message");
+
+  // check if the spy was called
+  assert.strictEqual(
+    debugSpy.mock.calls.length,
+    1,
+    "The log method should be called exactly once",
+  );
+
+  // and if the parameters were passed correcty
+  assert.deepStrictEqual(debugSpy.mock.calls[0].arguments, [
+    "Test debug message",
+  ]);
+
+  // cleaunup the mock and restore state to normal
+  mock.restoreAll();
+});
+
+test("verify that the exported logger is an instance", () => {
+  assert.strictEqual(
+    logger instanceof Logger,
+    true,
+    "The exported logger must be a Logger instance",
+  );
+});
+
+test("should always return the exact same instance (Reference Check)", () => {
+  const firstImport = logger;
+  const secondImport = logger;
+
+  // Verify both references point to the exact same object in memory
+  assert.strictEqual(
+    firstImport,
+    secondImport,
+    "The exported logger must be a strict singleton reference",
+  );
+});
+
+test("should share state across the application (State Check)", () => {
+  // 1. Change the log level to Error
+  logger.level(LogLevel.error);
+
+  // 2. Verify the state change is reflected globally (debug should now be noop)
+  assert.strictEqual(
+    isNoop(logger.debug),
+    true,
+    "State changes should reflect globally",
+  );
+
+  // 3. Change it back to Debug and verify again
+  logger.level(LogLevel.debug);
+  assert.strictEqual(
+    isNoop(logger.debug),
+    false,
+    "State changes should reflect globally",
+  );
+});
+
+test("should not be the same as a newly instantiated Logger", () => {
+  const newInstance = new Logger();
+
+  // The singleton instance must be completely unique from manually created instances
+  assert.notStrictEqual(
+    logger,
+    newInstance,
+    "The singleton instance must be unique from new Logger() instances",
+  );
+});
+
+test("should perform lazy evaluation of log arguments", () => {
+  const testLogger = new Logger();
+  testLogger.level(LogLevel.debug);
+
+  let evaluationCount = 0;
+
+  const lazyArg = () => {
+    evaluationCount++;
+    return "Lazy evaluated message";
+  };
+
+  // Call debug with a lazy argument
+  testLogger.debug(lazyArg);
+
+  // The lazy argument should have been evaluated exactly once
+  assert.strictEqual(
+    evaluationCount,
+    1,
+    "The lazy argument should be evaluated exactly once",
+  );
+});

package/utils/logger.ts

@@ -1,20 +1,32 @@
 import { noop } from "./utils.ts";
 
 /**
- * The available log levels
+ * The available log levels used to filter messages.
  */
 export const LogLevel = {
+  /** Crucial application errors or failures. */
   error: 0,
+  /** Non-fatal warnings that indicate unexpected behavior. */
   warn: 1,
+  /** Informational statements highlighting general operational flow. */
   info: 2,
+  /** Detailed tracing and comprehensive runtime statements. */
   verbose: 3,
+  /** High-density internal troubleshooting logs. */
   debug: 4,
 } as const;
 
-export type TLogLevel = typeof LogLevel[keyof typeof LogLevel];
+/**
+ * Union type representing the permitted numeric log level indices.
+ */
+export type LogLevel = typeof LogLevel[keyof typeof LogLevel];
+
+type LogArgument = unknown | (() => unknown);
 
 /**
- * Simple logger class
+ * Simple logger class providing level-configurable output routing.
+ * @class Logger
+ *
  * @example
  * ```ts
  * const logger = new Logger();
@@ -27,30 +39,73 @@ export type TLogLevel = typeof LogLevel[keyof typeof LogLevel];
  * ```
  */
 export class Logger {
+  /** Native console reference used to output critical errors. */
   private defaultError = console.error;
+  /** Native console reference used to output warning flags. */
   private defaultWarn = console.warn;
+  /** Native console reference used to output standard runtime indicators. */
   private defaultInfo = console.info;
+  /** Native console reference used to track granular metrics and details. */
   private defaultVerbose = console.log;
+  /** Native console reference used to step through highly specific operations. */
   private defaultDebug = console.log;
 
+  /** Flag indicating if error messages should be logged. */
+  isError = true;
+  /** Flag indicating if warning messages should be logged. */
+  isWarn = true;
+  /** Flag indicating if informational messages should be logged. */
+  isInfo = true;
+  /** Flag indicating if verbose messages should be logged. */
+  isVerbose = false;
+  /** Flag indicating if debug messages should be logged. */
+  isDebug = false;
+
+  /** Log an error message to the standard error stream. */
   error: typeof console.log = this.defaultError;
+  /** Log a warning message if the active log level permits. */
   warn: typeof console.log = this.defaultWarn;
+  /** Log an informational status update if the active log level permits. */
   info: typeof console.log = this.defaultInfo;
+  /** Log extended telemetry notes if the active log level permits. */
   verbose: typeof console.log = noop;
+  /** Log debug parameters and objects if the active log level permits. */
   debug: typeof console.log = noop;
 
+  /** Creates a wrapper function that evaluates lazy log arguments before invoking the target logging function. */
+  // deno-lint-ignore no-explicit-any
+  private createLogFn(targetFn: (...args: any[]) => void) {
+    return (...args: LogArgument[]) => {
+      const evaluated = args.map((
+        arg,
+      ) => (typeof arg === "function" ? arg() : arg));
+      targetFn(...evaluated);
+    };
+  }
+
+  /** Create a new Logger instance. */
   constructor() {}
 
-  level(logLevel: TLogLevel) {
-    this.warn = logLevel > 0 ? this.defaultWarn : noop;
-    this.info = logLevel > 1 ? this.defaultInfo : noop;
-    this.verbose = logLevel > 2 ? this.defaultVerbose : noop;
-    this.debug = logLevel > 3 ? this.defaultDebug : noop;
+  /**
+   * Adjusts the current verbosity threshold, enabling or masking specific log outputs.
+   * @param {LogLevel} logLevel - The minimum numeric severity level threshold to output.
+   */
+  level(logLevel: LogLevel) {
+    this.isWarn = logLevel >= LogLevel.warn;
+    this.isInfo = logLevel >= LogLevel.info;
+    this.isVerbose = logLevel >= LogLevel.verbose;
+    this.isDebug = logLevel >= LogLevel.debug;
+    this.warn = this.isWarn ? this.createLogFn(this.defaultWarn) : noop;
+    this.info = this.isInfo ? this.createLogFn(this.defaultInfo) : noop;
+    this.verbose = this.isVerbose
+      ? this.createLogFn(this.defaultVerbose)
+      : noop;
+    this.debug = this.isDebug ? this.createLogFn(this.defaultDebug) : noop;
   }
 }
 
 /**
- * logger provides a singleton logger instance
+ * Provides a single pre-configured global logger instance.
  * @example
  * ```ts
  * import { logger } from "./utils/logger.ts";

package/utils/mod.ts

@@ -5,4 +5,18 @@
 export { assert } from "./assert.ts";
 export { Deferred } from "./deferred.ts";
 export { Logger, logger, LogLevel } from "./logger.ts";
-export { BufferedAsyncIterable } from "./BufferedAsyncIterable.ts";
+export { BufferedAsyncIterable } from "./bufferedAsyncIterable.ts";
+export {
+  joinTopicFilter,
+  parseTopicFilter,
+  topicFilterToRegExp,
+} from "./topicFilter.ts";
+export { OutboundTopicAliasManager } from "./outboundTopicAliasManager.ts";
+export type { OutboundTopicAlias } from "./outboundTopicAliasManager.ts";
+export {
+  hasWildcards,
+  invalidmaxTopicLevels,
+  invalidTopic,
+  invalidTopicFilter,
+} from "./validators.ts";
+export { delay, noop } from "./utils.ts";