@ariestools/sdk 7.0.7 → 7.0.8

package/dist/neutral/creatable.mjs

@@ -1 +1,1270 @@
-export * from '../_pkg/creatable/neutral/index.mjs'
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/modules/creatable/AbstractCreatable.ts
+import { Mutex } from "async-mutex";
+
+// src/modules/assert/assertEx.ts
+function assertEx(expr, func) {
+  if (expr !== void 0 && expr !== null && expr !== false && expr !== 0 && expr !== "" && expr !== 0n) return expr;
+  if (typeof func === "function") {
+    const errorOrMessage = func(expr);
+    throw typeof errorOrMessage === "string" ? new Error(errorOrMessage) : errorOrMessage;
+  }
+  if (func !== void 0) {
+    throw new Error("Invalid assertEx usage: second argument must be a function or undefined");
+  }
+  throw new Error("Assertion failed");
+}
+
+// src/modules/base/Base.ts
+var DEFAULT_HISTORY_INTERVAL = 1e3 * 5;
+var DEFAULT_HISTORY_TIME = 60 * 60 * 1e3;
+var MAX_GC_FREQUENCY = 1e3 * 60;
+var MIN_GC_FREQUENCY = 1e3;
+var MIN_HISTORY_INTERVAL = 1e3;
+var Base = class _Base {
+  static defaultLogger;
+  static globalInstances = {};
+  static globalInstancesCountHistory = {};
+  static _historyInterval = DEFAULT_HISTORY_INTERVAL;
+  static _historyTime = DEFAULT_HISTORY_TIME;
+  static _historyTimeout;
+  static _lastGC = 0;
+  static _maxGcFrequency = MAX_GC_FREQUENCY;
+  _params;
+  constructor(params) {
+    this._params = params;
+    params?.logger?.debug(`Base constructed [${this.constructor.name}]`);
+    this.recordInstance();
+  }
+  static get historyInterval() {
+    return this._historyInterval;
+  }
+  static set historyInterval(value) {
+    assertEx(value <= this.historyTime, () => `historyInterval [${value}] must be less than or equal to historyTime [${this.historyTime}]`);
+    this._historyInterval = Math.max(value, MIN_HISTORY_INTERVAL);
+  }
+  static get historyTime() {
+    return this._historyTime;
+  }
+  static set historyTime(value) {
+    assertEx(value >= this.historyInterval, () => `historyTime [${value}] must be greater than or equal to historyInterval [${this.historyInterval}]`);
+    this._historyInterval = value;
+  }
+  static get maxGcFrequency() {
+    return this._maxGcFrequency;
+  }
+  static set maxGcFrequency(value) {
+    this._maxGcFrequency = Math.max(value, MIN_GC_FREQUENCY);
+  }
+  static get maxHistoryDepth() {
+    return Math.floor(this.historyTime / this.historyInterval);
+  }
+  get logger() {
+    return this.params?.logger ?? _Base.defaultLogger;
+  }
+  get meter() {
+    return this.params?.meterProvider?.getMeter(this.constructor.name);
+  }
+  get params() {
+    return this._params;
+  }
+  get tracer() {
+    return this.params?.traceProvider?.getTracer(this.constructor.name);
+  }
+  static gc(classNameOrForce = false) {
+    if (typeof classNameOrForce === "string") {
+      this.gcClass(classNameOrForce);
+    } else {
+      if (classNameOrForce || Date.now() - this._lastGC > this._maxGcFrequency) {
+        this.gcAll();
+      }
+    }
+  }
+  static instanceCount(className) {
+    return this.globalInstances[className]?.length ?? 0;
+  }
+  static instanceCounts() {
+    this.gc();
+    const result = {};
+    for (const [className, instances] of Object.entries(this.globalInstances)) result[className] = instances.length;
+    return result;
+  }
+  static startHistory() {
+    if (this._historyTimeout !== void 0) {
+      this.stopHistory();
+    }
+    const timeoutHandler = () => {
+      if (this._historyTimeout === void 0) {
+        return;
+      }
+      this.addToHistory();
+      this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval);
+    };
+    this._historyTimeout = setTimeout(timeoutHandler, this.historyInterval);
+  }
+  static stopHistory() {
+    if (this._historyTimeout === void 0) {
+      return;
+    }
+    clearTimeout(this._historyTimeout);
+    this._historyTimeout = void 0;
+  }
+  static addToHistory() {
+    const counts = this.instanceCounts();
+    for (const className of Object.keys(this.globalInstances)) {
+      this.globalInstancesCountHistory[className] = this.globalInstancesCountHistory[className]?.slice(-this.maxHistoryDepth) ?? [];
+      this.globalInstancesCountHistory[className].push(counts[className]);
+    }
+  }
+  static gcAll() {
+    for (const className of Object.keys(this.globalInstances)) {
+      this.gcClass(className);
+    }
+  }
+  static gcClass(className) {
+    this.globalInstances[className] = this.globalInstances[className]?.filter((ref) => ref.deref() !== null) ?? [];
+  }
+  recordInstance() {
+    const baseClassName = this.constructor.name;
+    const instanceArray = _Base.globalInstances[baseClassName] ?? [];
+    instanceArray.push(new WeakRef(this));
+    _Base.globalInstances[baseClassName] = instanceArray;
+  }
+};
+
+// src/modules/typeof/is.ts
+function isUndefined(value) {
+  return value === void 0;
+}
+function isDefined(value) {
+  return !isUndefined(value);
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function isNumber(value) {
+  return typeof value === "number";
+}
+function isError(value) {
+  return value instanceof Error;
+}
+function isPromise(value) {
+  return value instanceof Promise;
+}
+
+// src/modules/error/handleError.ts
+var handleError = (error, handler) => {
+  if (isError(error)) {
+    return handler(error);
+  }
+  throw error;
+};
+
+// src/modules/forget/ForgetConfig.ts
+var defaultForgetConfig = { timeout: 3e4 };
+
+// src/modules/forget/ForgetNodeConfig.ts
+var defaultForgetNodeConfig = {
+  ...defaultForgetConfig,
+  terminateOnTimeout: false,
+  terminateOnException: false
+};
+
+// src/modules/timer/setTimeoutEx.ts
+var TimerScheduler = class {
+  currentTimeout;
+  interval = -1;
+  timeouts = [];
+  /**
+   * Cancels a timeout previously created with setTimeoutEx.
+   * @param id - The timeout ID returned by setTimeoutEx.
+   */
+  clearTimeoutEx(id) {
+    this.timeouts = this.timeouts.filter((timeout) => timeout.id !== id);
+    this.update(this.timeouts);
+  }
+  /** Clears all scheduled timeouts and resets internal state. */
+  reset() {
+    this.interval = -1;
+    clearTimeout(this.currentTimeout);
+    this.currentTimeout = void 0;
+    this.timeouts = [];
+  }
+  /**
+   * Sets a timeout using an optimized internal timer that coalesces multiple timeouts into a single native timer.
+   * @param func - The function to call after the delay.
+   * @param delay - The delay in milliseconds (must be >= 0).
+   * @returns A unique string ID that can be used with clearTimeoutEx to cancel the timeout.
+   */
+  setTimeoutEx(func, delay2) {
+    assertEx(delay2 >= 0, () => "delay must be >= 0");
+    const id = `${Date.now()}|${Math.random() * 9999999999}`;
+    this.timeouts.push({
+      delay: delay2,
+      func,
+      id
+    });
+    this.update();
+    return id;
+  }
+  timerFunc() {
+    const notFiring = this.timeouts.filter((timeout) => timeout.delay > this.interval);
+    const firing = this.timeouts.filter((timeout) => timeout.delay <= this.interval);
+    this.update(notFiring, this.interval);
+    for (const timeout of firing) {
+      timeout.func();
+    }
+  }
+  update(newTimeouts = this.timeouts, delayPassed = 0) {
+    if (newTimeouts.length === 0) {
+      this.reset();
+    } else {
+      const newInterval = Math.min(...newTimeouts.map((timeout) => timeout.delay));
+      if (newInterval === this.interval && this.currentTimeout !== void 0) {
+        return;
+      }
+      clearTimeout(this.currentTimeout);
+      this.timeouts = newTimeouts.map((timeout) => ({
+        delay: timeout.delay - delayPassed,
+        func: timeout.func,
+        id: timeout.id
+      }));
+      this.interval = newInterval;
+      this.currentTimeout = setTimeout(() => this.timerFunc(), this.interval);
+    }
+  }
+};
+var defaultTimerScheduler = new TimerScheduler();
+var setTimeoutEx = (func, delay2) => defaultTimerScheduler.setTimeoutEx(func, delay2);
+
+// src/modules/delay/delay.ts
+var delay = (ms) => {
+  return new Promise((resolve) => setTimeoutEx(() => resolve(), ms));
+};
+
+// src/modules/forget/ForgetPromise.ts
+var ForgetPromise = class {
+  /**
+   * Number of forgotten promises still running (not yet settled).
+   * Decremented only when the underlying promise fulfills or rejects — not when a timeout fires.
+   */
+  static activeForgets = 0;
+  /** Number of forgotten promises that threw exceptions. */
+  static exceptedForgets = 0;
+  /** Logger instance used for error and warning output. */
+  static logger = console;
+  /** Whether any forgotten promises are still running, including any that have exceeded their timeout. */
+  static get active() {
+    return this.activeForgets > 0;
+  }
+  /**
+   * Waits until all forgotten promises have settled.
+   * @param interval - Polling interval in milliseconds.
+   * @param timeout - Optional maximum wait time in milliseconds.
+   * @returns `0` when every forgotten promise has settled; otherwise the number still running.
+   * A non-zero return after `timeout` elapses can include promises whose timeout callback already
+   * ran but whose work is still in flight.
+   */
+  static async awaitInactive(interval = 100, timeout) {
+    let timeoutRemaining = timeout;
+    while (this.active) {
+      await delay(interval);
+      if (timeoutRemaining !== void 0) {
+        timeoutRemaining -= interval;
+        if (timeoutRemaining <= 0) {
+          return this.activeForgets;
+        }
+      }
+    }
+    return 0;
+  }
+  /** Handles exceptions from forgotten promises by logging error details. */
+  static exceptionHandler(error, { name }, externalStackTrace) {
+    this.logger.error(`forget promise handler excepted [${name}]: ${error.message}`, error);
+    if (externalStackTrace !== void 0) {
+      this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace);
+    }
+  }
+  /**
+   * Used to explicitly launch an async function (or Promise) with awaiting it
+   * @param promise The promise to forget
+   * @param config Configuration of forget settings
+   */
+  static forget(promise, config) {
+    const stackError = new Error("Stack");
+    const externalStackTrace = stackError.stack;
+    const resolvedConfig = {
+      ...defaultForgetConfig,
+      ...globalThis.xy?.forget?.config,
+      ...config
+    };
+    const resolvedPromise2 = typeof promise === "function" ? promise() : promise;
+    if (isPromise(resolvedPromise2)) {
+      try {
+        let isCompleted = false;
+        this.activeForgets++;
+        const promiseWrapper = async () => {
+          try {
+            const result = await resolvedPromise2;
+            this.activeForgets--;
+            isCompleted = true;
+            resolvedConfig?.onComplete?.([result, void 0]);
+          } catch (error) {
+            const caughtError = error instanceof Error ? error : new Error(String(error));
+            this.activeForgets--;
+            isCompleted = true;
+            this.logger.error(`forgotten promise excepted [${config?.name ?? "unknown"}]: ${caughtError.message}`, caughtError);
+            resolvedConfig?.onComplete?.([void 0, caughtError]);
+          }
+        };
+        const promises = [promiseWrapper()];
+        const timeout = resolvedConfig.timeout ?? defaultForgetConfig.timeout;
+        if (isNumber(timeout)) {
+          const timeoutFunc = async () => {
+            await delay(timeout);
+            if (!isCompleted) {
+              resolvedConfig.onCancel?.();
+              this.timeoutHandler(timeout, resolvedConfig, externalStackTrace);
+            }
+          };
+          promises.push(timeoutFunc());
+        }
+        const race = Promise.race(promises);
+        void race.catch(() => {
+        });
+      } catch (ex) {
+        this.exceptedForgets += 1;
+        resolvedConfig?.onException?.(ex);
+        this.exceptionHandler(ex, resolvedConfig, externalStackTrace);
+      }
+    } else {
+      return;
+    }
+  }
+  /**
+   * Handles timeout events for forgotten promises by logging timeout details.
+   * Does not terminate the underlying promise; it may continue running after this is called.
+   */
+  static timeoutHandler(time, { name = "unknown" }, externalStackTrace) {
+    this.logger.error(`forget promise timed out after ${time}ms [still running] [${name}]`);
+    if (externalStackTrace !== void 0) {
+      this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace);
+    }
+  }
+};
+
+// src/modules/forget/ForgetPromiseNode.ts
+var ForgetPromiseNode = class extends ForgetPromise {
+  /** Handles exceptions, optionally terminating the process based on config. */
+  static exceptionHandler(error, config, externalStackTrace) {
+    super.exceptionHandler(error, config, externalStackTrace);
+    if (config?.terminateOnException === true) {
+      this.logger.error(`Attempting to terminate process [${config?.name ?? "unknown"}]...`);
+      process.exit(1);
+    }
+  }
+  /** Forgets a promise using Node.js-specific configuration with process termination support. */
+  static forget(promise, config) {
+    const resolvedConfig = {
+      ...defaultForgetNodeConfig,
+      ...globalThis.xy?.forget?.config,
+      ...config
+    };
+    super.forget(promise, resolvedConfig);
+  }
+  /** Handles timeouts, optionally terminating the process based on config. */
+  static timeoutHandler(time, config, externalStackTrace) {
+    super.timeoutHandler(time, config, externalStackTrace);
+    if (config?.terminateOnTimeout === true) {
+      this.logger.error(`Attempting to terminate process [${config?.name ?? "unknown"}]...`);
+      process.exit(2);
+    }
+  }
+};
+
+// src/modules/forget/forgetNode.ts
+var forgetNode = (promise, config) => {
+  ForgetPromiseNode.forget(promise, config);
+};
+
+// src/modules/events/Events/Events.ts
+var NO_META_EVENT_ERROR_MESSAGE = "`eventName` cannot be meta event `listenerAdded` or `listenerRemoved`";
+var processGlobal = globalThis;
+var resolvedPromise = Promise.resolve();
+var isMetaEvent = (eventName) => eventName === "listenerAdded" || eventName === "listenerRemoved";
+var Events = class _Events extends Base {
+  static anyMap = /* @__PURE__ */ new WeakMap();
+  static eventsMap = /* @__PURE__ */ new WeakMap();
+  static isGlobalDebugEnabled = false;
+  // this is here to be able to query the type, not use
+  eventData = {};
+  _canEmitMetaEvents = false;
+  constructor(params = {}) {
+    const mutatedParams = { ...params };
+    if (mutatedParams.debug) {
+      mutatedParams.debug.logger ??= (type, debugName, eventName, eventData) => {
+        let eventDataString;
+        try {
+          eventDataString = JSON.stringify(eventData);
+        } catch {
+          eventDataString = `Object with the following keys failed to stringify: ${Object.keys(eventData ?? {}).join(",")}`;
+        }
+        const eventNameString = typeof eventName === "symbol" || typeof eventName === "number" ? eventName.toString() : eventName;
+        const currentTime = /* @__PURE__ */ new Date();
+        const logTime = `${currentTime.getHours()}:${currentTime.getMinutes()}:${currentTime.getSeconds()}.${currentTime.getMilliseconds()}`;
+        this.logger?.log(`[${logTime}][events:${type}][${debugName}] Event Name: ${eventNameString}
+	data: ${eventDataString}`);
+      };
+    }
+    super(mutatedParams);
+    _Events.anyMap.set(this, /* @__PURE__ */ new Set());
+    _Events.eventsMap.set(this, /* @__PURE__ */ new Map());
+  }
+  /** Whether debug mode is enabled globally or via the DEBUG environment variable. */
+  static get isDebugEnabled() {
+    if (typeof processGlobal.process?.env !== "object") {
+      return this.isGlobalDebugEnabled;
+    }
+    const env = processGlobal.process?.env;
+    return env?.DEBUG === "events" || env?.DEBUG === "*" || this.isGlobalDebugEnabled;
+  }
+  static set isDebugEnabled(newValue) {
+    this.isGlobalDebugEnabled = newValue;
+  }
+  /** The debug configuration for this instance, if provided. */
+  get debug() {
+    return this.params.debug;
+  }
+  /**
+   * Removes all listeners for the specified event name(s).
+   * @param eventNames - One or more event names to clear listeners for.
+   */
+  clearListeners(eventNames) {
+    const eventNamesArray = Array.isArray(eventNames) ? eventNames : [eventNames];
+    for (const eventName of eventNamesArray) {
+      this.logIfDebugEnabled("clear", eventName);
+      if (typeof eventName === "string" || typeof eventName === "symbol" || typeof eventName === "number") {
+        const set = this.getListeners(eventName);
+        if (set) {
+          set.clear();
+        }
+      } else {
+        _Events.anyMap.get(this)?.clear();
+        const eventEntries = assertEx(_Events.eventsMap.get(this));
+        for (const [eventName2, listeners] of eventEntries) {
+          listeners.clear();
+          _Events.eventsMap.get(this)?.delete(eventName2);
+        }
+      }
+    }
+  }
+  /**
+   * Emits an event, invoking all registered listeners concurrently.
+   * @param eventName - The event to emit.
+   * @param eventArgs - The data to pass to listeners.
+   */
+  async emit(eventName, eventArgs) {
+    return await this.emitInternal(eventName, eventArgs);
+  }
+  /**
+   * Emits an internal meta event (listenerAdded or listenerRemoved).
+   * @param eventName - The meta event name.
+   * @param eventArgs - The meta event data containing listener and event information.
+   * @returns True if the meta event was emitted successfully.
+   */
+  async emitMetaEvent(eventName, eventArgs) {
+    if (isMetaEvent(eventName)) {
+      try {
+        this._canEmitMetaEvents = true;
+        await this.emitMetaEventInternal(eventName, eventArgs);
+        return true;
+      } finally {
+        this._canEmitMetaEvents = false;
+      }
+    }
+  }
+  /**
+   * Emits an event, invoking all registered listeners sequentially in order.
+   * @param eventName - The event to emit.
+   * @param eventArgs - The data to pass to listeners.
+   */
+  async emitSerial(eventName, eventArgs) {
+    if (isMetaEvent(eventName) && !this._canEmitMetaEvents) {
+      throw new TypeError(NO_META_EVENT_ERROR_MESSAGE);
+    }
+    const filterMatch = (args, filter) => {
+      switch (typeof filter) {
+        case "object": {
+          if (filter === null || args === null || typeof args !== "object") return args === filter;
+          return Object.entries(args).reduce((prev, [key, value]) => filter[key] === value ? true : prev, false);
+        }
+        default: {
+          return args === filter;
+        }
+      }
+    };
+    this.logIfDebugEnabled("emitSerial", eventName, eventArgs);
+    const listeners = this.getListeners(eventName) ?? /* @__PURE__ */ new Set();
+    const filteredListeners = [...listeners].filter((value) => isDefined(value.filter) ? filterMatch(eventArgs, value.filter) : true).map((info) => info.listener);
+    const anyListeners = assertEx(_Events.anyMap.get(this));
+    const staticListeners = [...filteredListeners];
+    const staticAnyListeners = [...anyListeners];
+    await resolvedPromise;
+    for (const listener of staticListeners) {
+      await this.safeCallListener(eventName, eventArgs, listener);
+    }
+    for (const listener of staticAnyListeners) {
+      await this.safeCallAnyListener(eventName, eventArgs, listener);
+    }
+  }
+  /**
+   * Returns the total number of listeners registered for the specified event name(s).
+   * @param eventNames - One or more event names to count listeners for.
+   * @returns The total listener count.
+   */
+  // TODO: Make test for this
+  listenerCount(eventNames) {
+    const eventNamesArray = Array.isArray(eventNames) ? eventNames : [eventNames];
+    let count = 0;
+    for (const eventName of eventNamesArray) {
+      if (typeof eventName === "string") {
+        count += assertEx(_Events.anyMap.get(this)).size + (this.getListeners(eventName)?.size ?? 0);
+        continue;
+      }
+      count += assertEx(_Events.anyMap.get(this)).size;
+      const eventListeners = assertEx(_Events.eventsMap.get(this)).values();
+      for (const value of eventListeners) {
+        count += value.size;
+      }
+    }
+    return count;
+  }
+  /**
+   * Logs debug information if debug mode is enabled.
+   * @param type - The type of operation being logged.
+   * @param eventName - The event name, if applicable.
+   * @param eventArgs - The event data, if applicable.
+   */
+  logIfDebugEnabled(type, eventName, eventArgs) {
+    if (_Events.isDebugEnabled || this.debug?.enabled === true) {
+      this.debug?.logger?.(type, this.debug.name, eventName, eventArgs);
+    }
+  }
+  /**
+   * Removes a specific listener from the specified event name(s).
+   * @param eventNames - One or more event names to unsubscribe from.
+   * @param listener - The listener to remove.
+   */
+  off(eventNames, listener) {
+    const eventNamesArray = Array.isArray(eventNames) ? eventNames : [eventNames];
+    for (const eventName of eventNamesArray) {
+      const set = this.getListeners(eventName);
+      if (set) {
+        set.delete(listener);
+        if (set.size === 0) {
+          const events = _Events.eventsMap.get(this);
+          events?.delete(eventName);
+        }
+      }
+      this.logIfDebugEnabled("unsubscribe", eventName);
+      if (!isMetaEvent(eventName)) {
+        forgetNode(this.emitMetaEvent("listenerRemoved", { eventName, listener }));
+      }
+    }
+  }
+  /**
+   * Removes a wildcard listener that was receiving all events.
+   * @param listener - The wildcard listener to remove.
+   */
+  offAny(listener) {
+    this.logIfDebugEnabled("unsubscribeAny");
+    const typedMap = _Events.anyMap.get(this);
+    typedMap?.delete(listener);
+    forgetNode(this.emitMetaEvent("listenerRemoved", { listener }));
+  }
+  /**
+   * Subscribes a listener to the specified event name(s).
+   * @param eventNames - One or more event names to listen for.
+   * @param listener - The callback to invoke when the event fires.
+   * @param filter - Optional filter to selectively invoke the listener based on event data.
+   * @returns An unsubscribe function.
+   */
+  on(eventNames, listener, filter) {
+    const eventNamesArray = Array.isArray(eventNames) ? eventNames : [eventNames];
+    for (const eventName of eventNamesArray) {
+      let set = this.getListeners(eventName);
+      if (!set) {
+        set = /* @__PURE__ */ new Set();
+        const events = _Events.eventsMap.get(this);
+        events?.set(eventName, set);
+      }
+      set.add({ filter, listener });
+      this.logIfDebugEnabled("subscribe", eventName);
+      if (!isMetaEvent(eventName)) {
+        forgetNode(this.emitMetaEvent("listenerAdded", { eventName, listener }));
+      }
+    }
+    return this.off.bind(this, eventNames, listener);
+  }
+  /**
+   * Subscribes a wildcard listener that receives all events.
+   * @param listener - The callback to invoke for any event.
+   * @returns An unsubscribe function.
+   */
+  onAny(listener) {
+    this.logIfDebugEnabled("subscribeAny");
+    _Events.anyMap.get(this)?.add(listener);
+    forgetNode(this.emitMetaEvent("listenerAdded", { listener }));
+    return this.offAny.bind(this, listener);
+  }
+  /**
+   * Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
+   * @param eventName - The event to listen for.
+   * @param listener - The callback to invoke once.
+   * @returns An unsubscribe function.
+   */
+  once(eventName, listener) {
+    const subListener = async (args) => {
+      this.off(eventName, subListener);
+      await this.safeCallListener(eventName, args, listener);
+    };
+    this.on(eventName, subListener);
+    return this.off.bind(this, eventName, subListener);
+  }
+  async emitInternal(eventName, eventArgs, filter) {
+    if (isMetaEvent(eventName) && !this._canEmitMetaEvents) {
+      throw new TypeError(NO_META_EVENT_ERROR_MESSAGE);
+    }
+    this.logIfDebugEnabled("emit", eventName, eventArgs);
+    const listeners = this.getListeners(eventName) ?? /* @__PURE__ */ new Set();
+    const filteredListeners = [...listeners].filter((value) => isDefined(filter) ? isDefined(value.listener) : true).map((info) => info.listener);
+    const anyListeners = assertEx(_Events.anyMap.get(this));
+    const staticListeners = [...filteredListeners];
+    const staticAnyListeners = isMetaEvent(eventName) ? [] : [...anyListeners];
+    await resolvedPromise;
+    await Promise.all([
+      ...staticListeners.map(async (listener) => {
+        await this.safeCallListener(eventName, eventArgs, listener);
+      }),
+      ...staticAnyListeners.map(async (listener) => {
+        if (anyListeners.has(listener)) {
+          await this.safeCallAnyListener(eventName, eventArgs, listener);
+        }
+      })
+    ]);
+  }
+  async emitMetaEventInternal(eventName, eventArgs) {
+    if (isMetaEvent(eventName) && !this._canEmitMetaEvents) {
+      throw new TypeError("`eventName` cannot be meta event `listenerAdded` or `listenerRemoved`");
+    }
+    this.logIfDebugEnabled("emit", eventName, eventArgs);
+    const listeners = this.getListeners(eventName) ?? /* @__PURE__ */ new Set();
+    const filteredListeners = [...listeners].map((info) => info.listener);
+    const anyListeners = assertEx(_Events.anyMap.get(this));
+    const staticListeners = [...filteredListeners];
+    const staticAnyListeners = isMetaEvent(eventName) ? [] : [...anyListeners];
+    await resolvedPromise;
+    await Promise.all([
+      ...staticListeners.map(async (listener) => {
+        await this.safeCallListener(eventName, eventArgs, listener);
+      }),
+      /* v8 ignore start -- race condition guard */
+      ...staticAnyListeners.map(async (listener) => {
+        if (anyListeners.has(listener)) {
+          await this.safeCallAnyListener(eventName, eventArgs, listener);
+        }
+      })
+      /* v8 ignore stop */
+    ]);
+    return true;
+  }
+  getListeners(eventName) {
+    const events = assertEx(_Events.eventsMap.get(this));
+    if (!events.has(eventName)) {
+      return;
+    }
+    return events.get(eventName);
+  }
+  async safeCallAnyListener(eventName, eventArgs, listener) {
+    try {
+      return await listener(eventName, eventArgs);
+    } catch (ex) {
+      handleError(ex, (error) => {
+        this.logger?.error(`Listener[${String(eventName)}] Excepted: ${error.message}`);
+      });
+    }
+  }
+  async safeCallListener(eventName, eventArgs, listener) {
+    try {
+      return await listener(eventArgs);
+    } catch (ex) {
+      handleError(ex, (error) => {
+        this.logger?.error(`Listener[${String(eventName)}] Excepted: ${error.message}`);
+      });
+    }
+  }
+};
+
+// src/modules/events/BaseEmitter.ts
+var BaseEmitter = class extends Base {
+  // just here to query types
+  eventData = {};
+  events;
+  constructor(params) {
+    super(params);
+    this.events = new Events();
+  }
+  /**
+   * Removes all listeners for the specified event name(s).
+   * @param eventNames - One or more event names to clear listeners for.
+   * @returns This instance for chaining.
+   */
+  clearListeners(eventNames) {
+    this.events.clearListeners(eventNames);
+    return this;
+  }
+  /**
+   * Emits an event, invoking all registered listeners concurrently.
+   * @param eventName - The event to emit.
+   * @param eventArgs - The data to pass to listeners.
+   */
+  emit(eventName, eventArgs) {
+    return this.events.emit(eventName, eventArgs);
+  }
+  /**
+   * Emits an event, invoking all registered listeners sequentially in order.
+   * @param eventName - The event to emit.
+   * @param eventArgs - The data to pass to listeners.
+   */
+  emitSerial(eventName, eventArgs) {
+    return this.events.emitSerial(eventName, eventArgs);
+  }
+  /**
+   * Returns the total number of listeners registered for the specified event name(s).
+   * @param eventNames - One or more event names to count listeners for.
+   * @returns The total listener count.
+   */
+  listenerCount(eventNames) {
+    return this.events.listenerCount(eventNames);
+  }
+  /**
+   * Removes a specific listener from the specified event name(s).
+   * @param eventNames - One or more event names to unsubscribe from.
+   * @param listener - The listener to remove.
+   */
+  off(eventNames, listener) {
+    return this.events.off(eventNames, listener);
+  }
+  /**
+   * Removes a wildcard listener that was receiving all events.
+   * @param listener - The wildcard listener to remove.
+   */
+  offAny(listener) {
+    return this.events.offAny(listener);
+  }
+  /**
+   * Subscribes a listener to the specified event name(s).
+   * @param eventNames - One or more event names to listen for.
+   * @param listener - The callback to invoke when the event fires.
+   * @returns An unsubscribe function.
+   */
+  on(eventNames, listener) {
+    return this.events.on(eventNames, listener);
+  }
+  /**
+   * Subscribes a wildcard listener that receives all events.
+   * @param listener - The callback to invoke for any event.
+   * @returns An unsubscribe function.
+   */
+  onAny(listener) {
+    return this.events.onAny(listener);
+  }
+  /**
+   * Subscribes a listener that will be invoked only once for the specified event, then automatically removed.
+   * @param eventName - The event to listen for.
+   * @param listener - The callback to invoke once.
+   * @returns An unsubscribe function.
+   */
+  once(eventName, listener) {
+    return this.events.once(eventName, listener);
+  }
+};
+
+// src/modules/telemetry/span.ts
+import {
+  context,
+  propagation,
+  ROOT_CONTEXT,
+  SpanStatusCode,
+  trace as TRACE_API
+} from "@opentelemetry/api";
+
+// src/modules/telemetry/timeBudget.ts
+async function timeBudget(name, logger, func, budget, status = false) {
+  const start = Date.now();
+  const timer = status ? setInterval(() => {
+    const duration2 = Date.now() - start;
+    if (budget > 0 && duration2 > budget) {
+      logger?.warn(`Function [${name}] execution is exceeding budget: ${duration2}ms > ${budget}ms`);
+    }
+  }, Math.max(100, budget)) : void 0;
+  const result = await func();
+  const duration = Date.now() - start;
+  if (timer === void 0 && budget > 0 && duration > budget) {
+    logger?.warn(`Function [${name}] execution exceeded budget: ${duration}ms > ${budget}ms`);
+  }
+  if (timer !== void 0) {
+    clearInterval(timer);
+  }
+  return result;
+}
+
+// src/modules/telemetry/span.ts
+function cloneContextWithoutSpan(activeCtx, configKeys = []) {
+  let newCtx = ROOT_CONTEXT;
+  const baggage = propagation.getBaggage(activeCtx);
+  if (baggage) {
+    newCtx = propagation.setBaggage(newCtx, baggage);
+  }
+  for (const key of configKeys) {
+    const value = activeCtx.getValue(key);
+    if (value !== void 0) {
+      newCtx = newCtx.setValue(key, value);
+    }
+  }
+  return newCtx;
+}
+function spanRoot(name, fn, tracer) {
+  const activeTracer = tracer ?? TRACE_API.getTracer(name);
+  if (isDefined(activeTracer)) {
+    const activeContext = context.active();
+    const noSpanContext = cloneContextWithoutSpan(activeContext);
+    const span = activeTracer.startSpan(name, {}, noSpanContext);
+    return context.with(TRACE_API.setSpan(noSpanContext, span), () => {
+      try {
+        const result = fn();
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (ex) {
+        const error = ex;
+        span.recordException(error);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        throw ex;
+      } finally {
+        span.end();
+      }
+    });
+  }
+  return fn();
+}
+async function spanRootAsync(name, fn, {
+  timeBudgetLimit,
+  logger,
+  tracer
+} = {}) {
+  const funcToRun = isDefined(timeBudgetLimit) ? () => timeBudget(name, logger ?? console, fn, timeBudgetLimit) : fn;
+  const activeTracer = tracer ?? TRACE_API.getTracer(name);
+  if (isDefined(activeTracer)) {
+    const activeContext = context.active();
+    const noSpanContext = cloneContextWithoutSpan(activeContext);
+    const span = activeTracer.startSpan(name, {}, noSpanContext);
+    return await context.with(TRACE_API.setSpan(noSpanContext, span), async () => {
+      try {
+        const result = await funcToRun();
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (ex) {
+        const error = ex;
+        span.recordException(error);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+        throw ex;
+      } finally {
+        span.end();
+      }
+    });
+  }
+  return await funcToRun();
+}
+
+// src/modules/creatable/Creatable.ts
+function creatable() {
+  return (constructor) => {
+    constructor;
+  };
+}
+function creatableFactory() {
+  return (constructor) => {
+    constructor;
+  };
+}
+
+// src/modules/creatable/Factory.ts
+var Factory = class _Factory {
+  /** The Creatable class this factory delegates creation to. */
+  creatable;
+  /** Default parameters merged into every `create` call. */
+  defaultParams;
+  /** Labels identifying resources created by this factory. */
+  labels;
+  constructor(creatable2, params, labels = {}) {
+    this.creatable = creatable2;
+    this.defaultParams = params;
+    this.labels = Object.assign({}, creatable2.labels ?? {}, labels ?? {});
+  }
+  /**
+   * Creates a new Factory instance with the given default params and labels.
+   * @param creatableModule - The Creatable class to wrap
+   * @param params - Default parameters for new instances
+   * @param labels - Labels to assign to created instances
+   */
+  static withParams(creatableModule, params, labels = {}) {
+    return new _Factory(creatableModule, params, labels);
+  }
+  /**
+   * Creates a new instance, merging the provided params over the factory defaults.
+   * @param params - Optional parameters to override the factory defaults
+   */
+  create(params) {
+    const mergedParams = {
+      ...this.defaultParams,
+      ...params
+    };
+    return this.creatable.create(mergedParams);
+  }
+};
+
+// src/modules/creatable/lib/getFunctionName.ts
+function getFunctionName(depth = 2) {
+  const error = new Error("Stack");
+  let newIndex;
+  const stackParts = error.stack?.split("\n")[depth]?.split(" ");
+  const funcName = stackParts?.find((item, index) => {
+    if (!(item.length > 0 && item !== "at")) {
+      return;
+    }
+    if (item === "new") {
+      newIndex = index;
+    }
+    return true;
+  }) ?? "<unknown>";
+  return isNumber(newIndex) ? `${funcName} ${stackParts?.[newIndex + 1]}` : funcName;
+}
+
+// src/modules/creatable/lib/getRootFunction.ts
+var getPrototype = (value) => {
+  const prototype = Object.getPrototypeOf(value);
+  return typeof prototype === "object" ? prototype : null;
+};
+function getRootFunction(obj, funcName) {
+  if (obj === null || typeof obj !== "object") return void 0;
+  let current = obj;
+  let prototype = getPrototype(current);
+  while (prototype !== null && prototype[funcName] !== void 0) {
+    current = prototype;
+    prototype = getPrototype(current);
+  }
+  return current[funcName];
+}
+
+// src/modules/creatable/AbstractCreatable.ts
+var AbstractCreatableConstructorKey = /* @__PURE__ */ Symbol.for("AbstractCreatableConstructor");
+var CREATABLE_NOT_STARTED = "Creatable not Started";
+var AbstractCreatable = class extends BaseEmitter {
+  /** Optional default logger for this instance. */
+  defaultLogger;
+  _startPromise;
+  _status = null;
+  _statusMutex = new Mutex();
+  _validatedParams;
+  constructor(key, params) {
+    assertEx(key === AbstractCreatableConstructorKey, () => "AbstractCreatable should not be instantiated directly, use the static create method instead");
+    super(params);
+  }
+  /** The name identifier for this creatable instance. */
+  get name() {
+    return this.params.name;
+  }
+  /** The validated and merged parameters for this instance. */
+  get params() {
+    this._validatedParams ??= this.paramsValidator(super.params);
+    return this._validatedParams;
+  }
+  /** Whether this instance can be started (must be in 'created' or 'stopped' status). */
+  get startable() {
+    return this.status === "created" || this.status === "stopped";
+  }
+  /** The current lifecycle status of this instance, or null if not yet initialized. */
+  get status() {
+    return this._status;
+  }
+  /** The status reporter used to broadcast lifecycle changes. */
+  get statusReporter() {
+    return this.params.statusReporter;
+  }
+  /**
+   * Asynchronously creates a new instance by processing params, constructing,
+   * and running both static and instance createHandlers.
+   * @param inParams - Optional partial parameters to configure the instance
+   * @returns The fully initialized instance
+   */
+  static async create(inParams = {}) {
+    const params = await this.paramsHandler(inParams);
+    const name = params.name ?? this.name;
+    try {
+      const [Constructor] = [this];
+      const instance = new Constructor(AbstractCreatableConstructorKey, params);
+      instance.setStatus("creating");
+      const initializedInstance = await this.createHandler(instance);
+      await instance.createHandler();
+      instance.setStatus("created");
+      return initializedInstance;
+    } catch (ex) {
+      params.statusReporter?.report(name, "error", isError(ex) ? ex : new Error(`Error creating: ${name}`));
+      params.logger?.error(`Error creating creatable [${name}]: ${isError(ex) ? `${ex.message} ${ex.stack}` : String(ex)}`);
+      throw isError(ex) ? ex : new Error(`Error creating: ${name}`);
+    }
+  }
+  /**
+   * Static hook called during creation to perform additional initialization.
+   * Override in subclasses to customize post-construction setup.
+   * @param instance - The newly constructed instance
+   * @returns The instance, potentially modified
+   */
+  static createHandler(instance) {
+    return instance;
+  }
+  /**
+   * Static hook called during creation to validate and transform params.
+   * Override in subclasses to add default values or validation.
+   * @param params - The raw partial params provided to `create`
+   * @returns The processed params ready for construction
+   */
+  static paramsHandler(params = {}) {
+    return { ...params };
+  }
+  /** Instance-level creation hook. Override in subclasses to perform setup after construction. */
+  createHandler() {
+    assertEx(this._status === "creating", () => `createHandler can not be called [status = ${this.status}]`);
+  }
+  /**
+   * Validates and returns the merged params, ensuring required fields are present.
+   * Override in subclasses to add custom validation logic.
+   * @param params - The raw partial params to validate
+   * @returns The validated params
+   */
+  paramsValidator(params) {
+    return { ...params, name: params.name };
+  }
+  /**
+   * Executes a function within a telemetry span.
+   * @param name - The span name
+   * @param fn - The function to execute within the span
+   */
+  span(name, fn) {
+    return spanRoot(name, fn, this.tracer);
+  }
+  /**
+   * Executes an async function within a telemetry span.
+   * @param name - The span name
+   * @param fn - The async function to execute within the span
+   * @param config - Optional span configuration
+   */
+  async spanAsync(name, fn, config = {}) {
+    return await spanRootAsync(name, fn, {
+      ...config,
+      tracer: config.tracer ?? this.tracer,
+      logger: config.logger ?? this.defaultLogger
+    });
+  }
+  /**
+   * Starts the instance, transitioning through 'starting' to 'started' status.
+   * Thread-safe via mutex. Returns true if already started or started successfully.
+   */
+  async start() {
+    this._noOverride("start");
+    if (this.status === "started") {
+      return true;
+    }
+    return await this._statusMutex.runExclusive(async () => {
+      try {
+        if (this.status === "started") {
+          return true;
+        }
+        assertEx(this.startable, () => `Creatable [${this.name}] is not startable in status [${this.status}]`);
+        this.setStatus("starting");
+        await this.startHandler();
+        this.setStatus("started");
+        return true;
+      } catch (ex) {
+        this.setStatus("error", isError(ex) ? ex : new Error(`Error starting: ${String(ex)}`));
+        this.logger?.error(`Error starting creatable [${this.name}]: ${isError(ex) ? `${ex.message} ${ex.stack}` : String(ex)}`);
+        return false;
+      }
+    });
+  }
+  /**
+   * Checks whether this instance is currently started.
+   * Takes an action if not started, based on the notStartedAction parameter.
+   * @param notStartedAction - What to do if not started: 'error'/'throw' throws, 'warn'/'log' logs, 'none' is silent
+   * @returns True if started, false otherwise
+   */
+  started(notStartedAction = "log") {
+    if (isString(this.status) && this.status === "started") {
+      return true;
+    }
+    const message = () => `${CREATABLE_NOT_STARTED} [${this.name}] current state: ${this.status}`;
+    switch (notStartedAction) {
+      case "error": {
+        throw new Error(message());
+      }
+      case "throw": {
+        throw new Error(message());
+      }
+      case "warn": {
+        this.logger?.warn(message());
+        break;
+      }
+      case "log": {
+        this.logger?.log(message());
+        break;
+      }
+      case "none": {
+        break;
+      }
+      default: {
+        throw new Error(`Unknown notStartedAction: ${notStartedAction}`);
+      }
+    }
+    return false;
+  }
+  /**
+   * Async version of `started` that can optionally auto-start the instance.
+   * @param notStartedAction - What to do if not started and auto-start is disabled
+   * @param tryStart - If true, attempts to start the instance automatically
+   * @returns True if the instance is or becomes started
+   */
+  async startedAsync(notStartedAction = "log", tryStart = true) {
+    if (isString(this.status) && this.status === "started") {
+      return true;
+    }
+    if (this.status !== null && ["created", "stopped", "starting"].includes(this.status)) {
+      this._startPromise ??= (async () => {
+        if (tryStart) {
+          try {
+            return await this.start();
+          } finally {
+            this._startPromise = void 0;
+          }
+        }
+        return this.started(notStartedAction);
+      })();
+    } else {
+      const message = `${CREATABLE_NOT_STARTED} [${this.name}] current state: ${this.status}`;
+      throw new Error(message);
+    }
+    if (isUndefined(this._startPromise)) {
+      throw new Error(`Failed to create start promise: ${this.status}`);
+    }
+    return await this._startPromise;
+  }
+  /**
+   * Stops the instance, transitioning through 'stopping' to 'stopped' status.
+   * Thread-safe via mutex. Returns true if already stopped or stopped successfully.
+   */
+  async stop() {
+    this._noOverride("stop");
+    if (this.status === "stopped") {
+      return true;
+    }
+    return await this._statusMutex.runExclusive(async () => {
+      try {
+        if (this.status === "stopped") {
+          return true;
+        }
+        assertEx(this.status === "started", () => `Creatable [${this.name}] is not stoppable in status [${this.status}]`);
+        this.setStatus("stopping");
+        await this.stopHandler();
+        this.setStatus("stopped");
+        return true;
+      } catch (ex) {
+        this.setStatus("error", isError(ex) ? ex : new Error(`Error stopping: ${String(ex)}`));
+        return false;
+      }
+    });
+  }
+  /**
+   * Asserts that the given function has not been overridden in a subclass.
+   * Used to enforce the handler pattern (override `startHandler` not `start`).
+   */
+  _noOverride(functionName = getFunctionName(3)) {
+    const thisFunc = this[functionName];
+    const rootFunc = getRootFunction(this, functionName);
+    assertEx(thisFunc === rootFunc, () => `Override not allowed for [${functionName}] - override ${functionName}Handler instead`);
+  }
+  setStatus(value, progressOrError) {
+    this._status = value;
+    if (value !== null) {
+      if (value === "error") {
+        if (isError(progressOrError)) {
+          this.statusReporter?.report(this.name, value, progressOrError);
+          return;
+        }
+      } else {
+        if (isNumber(progressOrError)) {
+          this.statusReporter?.report(this.name, value, progressOrError);
+          return;
+        }
+      }
+      this.statusReporter?.report(this.name, value);
+    }
+  }
+  /** Override in subclasses to define start behavior. Throw an error on failure. */
+  startHandler() {
+  }
+  /** Override in subclasses to define stop behavior. Throw an error on failure. */
+  stopHandler() {
+  }
+};
+AbstractCreatable = __decorateClass([
+  creatable()
+], AbstractCreatable);
+var AbstractCreatableWithFactory = class extends AbstractCreatable {
+  /**
+   * Creates a factory that produces instances of this class with pre-configured params and labels.
+   * @param params - Default parameters for instances created by the factory
+   * @param labels - Labels to assign to created instances
+   */
+  static factory(params, labels) {
+    return Factory.withParams(this, params, labels);
+  }
+};
+AbstractCreatableWithFactory = __decorateClass([
+  creatable()
+], AbstractCreatableWithFactory);
+
+// src/modules/creatable/model/Labels.ts
+var hasAllLabels = (source, required) => {
+  if (!required) return true;
+  return Object.entries(required).every(([key, value]) => {
+    return Object.hasOwn(source ?? {}, key) && source?.[key] === value;
+  });
+};
+export {
+  AbstractCreatable,
+  AbstractCreatableWithFactory,
+  Factory,
+  creatable,
+  creatableFactory,
+  hasAllLabels
+};
+//# sourceMappingURL=creatable.mjs.map