bubus 1.7.3 → 2.2.1

package/dist/esm/event_bus.js

@@ -0,0 +1,1046 @@
+import { BaseEvent } from "./base_event.js";
+import { EventHistory } from "./event_history.js";
+import { captureAsyncContext } from "./async_context.js";
+import { _runWithSlowMonitor, _runWithTimeout } from "./timing.js";
+import {
+  AsyncLock,
+  LockManager
+} from "./lock_manager.js";
+import {
+  EventHandler,
+  EventHandlerAbortedError,
+  EventHandlerCancelledError,
+  EventHandlerTimeoutError
+} from "./event_handler.js";
+import { logTree } from "./logging.js";
+import { v7 as uuidv7 } from "uuid";
+import { monotonicDatetime } from "./helpers.js";
+import { normalizeEventPattern } from "./types.js";
+class GlobalEventBusRegistry {
+  _bus_refs = /* @__PURE__ */ new Set();
+  add(bus) {
+    this._bus_refs.add(new WeakRef(bus));
+  }
+  discard(bus) {
+    for (const ref of this._bus_refs) {
+      const current = ref.deref();
+      if (!current || current === bus) {
+        this._bus_refs.delete(ref);
+      }
+    }
+  }
+  has(bus) {
+    for (const ref of this._bus_refs) {
+      const current = ref.deref();
+      if (!current) {
+        this._bus_refs.delete(ref);
+        continue;
+      }
+      if (current === bus) {
+        return true;
+      }
+    }
+    return false;
+  }
+  get size() {
+    let count = 0;
+    for (const ref of this._bus_refs) {
+      if (ref.deref()) {
+        count += 1;
+      } else {
+        this._bus_refs.delete(ref);
+      }
+    }
+    return count;
+  }
+  *[Symbol.iterator]() {
+    for (const ref of this._bus_refs) {
+      const bus = ref.deref();
+      if (bus) {
+        yield bus;
+      } else {
+        this._bus_refs.delete(ref);
+      }
+    }
+  }
+  findBusById(bus_id) {
+    for (const bus of this) {
+      if (bus.id === bus_id) {
+        return bus;
+      }
+    }
+    return void 0;
+  }
+  findEventById(event_id) {
+    for (const bus of this) {
+      const event = bus.event_history.getEvent(event_id);
+      if (event) {
+        return event;
+      }
+    }
+    return null;
+  }
+}
+class EventBus {
+  static _registry_by_constructor = /* @__PURE__ */ new WeakMap();
+  static _global_event_lock_by_constructor = /* @__PURE__ */ new WeakMap();
+  static getRegistryForConstructor(constructor_fn) {
+    const existing_registry = EventBus._registry_by_constructor.get(constructor_fn);
+    if (existing_registry) {
+      return existing_registry;
+    }
+    const created_registry = new GlobalEventBusRegistry();
+    EventBus._registry_by_constructor.set(constructor_fn, created_registry);
+    return created_registry;
+  }
+  static getGlobalEventLockForConstructor(constructor_fn) {
+    const existing_lock = EventBus._global_event_lock_by_constructor.get(constructor_fn);
+    if (existing_lock) {
+      return existing_lock;
+    }
+    const created_lock = new AsyncLock(1);
+    EventBus._global_event_lock_by_constructor.set(constructor_fn, created_lock);
+    return created_lock;
+  }
+  static get all_instances() {
+    return EventBus.getRegistryForConstructor(this);
+  }
+  get all_instances() {
+    return EventBus.getRegistryForConstructor(this.constructor);
+  }
+  get _lock_for_event_global_serial() {
+    return EventBus.getGlobalEventLockForConstructor(this.constructor);
+  }
+  id;
+  // unique uuidv7 identifier for the event bus
+  name;
+  // name of the event bus, recommended to include the word "Bus" in the name for clarity in logs
+  // configuration options
+  event_timeout;
+  event_concurrency;
+  event_handler_concurrency;
+  event_handler_completion;
+  event_handler_detect_file_paths;
+  // slow processing warning timeout settings
+  event_handler_slow_timeout;
+  event_slow_timeout;
+  // public runtime state
+  handlers;
+  // map of handler uuidv5 ids to EventHandler objects
+  handlers_by_key;
+  // map of normalized event_pattern to ordered handler ids
+  event_history;
+  // map of event uuidv7 ids to processed BaseEvent objects
+  // internal runtime state
+  pending_event_queue;
+  // queue of events that have been emitted to the bus but not yet processed
+  in_flight_event_ids;
+  // set of event ids that are currently being processed by the bus
+  runloop_running;
+  locks;
+  find_waiters;
+  // set of EphemeralFindEventHandler objects that are waiting for a matching future event
+  middlewares;
+  static normalizeMiddlewares(middlewares) {
+    const normalized = [];
+    for (const middleware of middlewares ?? []) {
+      if (!middleware) {
+        continue;
+      }
+      if (typeof middleware === "function") {
+        normalized.push(new middleware());
+      } else {
+        normalized.push(middleware);
+      }
+    }
+    return normalized;
+  }
+  constructor(name = "EventBus", options = {}) {
+    this.id = options.id ?? uuidv7();
+    this.name = name;
+    this.event_concurrency = options.event_concurrency ?? "bus-serial";
+    this.event_handler_concurrency = options.event_handler_concurrency ?? "serial";
+    this.event_handler_completion = options.event_handler_completion ?? "all";
+    this.event_handler_detect_file_paths = options.event_handler_detect_file_paths ?? true;
+    this.event_timeout = options.event_timeout === void 0 ? 60 : options.event_timeout;
+    this.event_handler_slow_timeout = options.event_handler_slow_timeout === void 0 ? 30 : options.event_handler_slow_timeout;
+    this.event_slow_timeout = options.event_slow_timeout === void 0 ? 300 : options.event_slow_timeout;
+    this.runloop_running = false;
+    this.handlers = /* @__PURE__ */ new Map();
+    this.handlers_by_key = /* @__PURE__ */ new Map();
+    this.find_waiters = /* @__PURE__ */ new Set();
+    this.event_history = new EventHistory({
+      max_history_size: options.max_history_size === void 0 ? 100 : options.max_history_size,
+      max_history_drop: options.max_history_drop ?? false
+    });
+    this.pending_event_queue = [];
+    this.in_flight_event_ids = /* @__PURE__ */ new Set();
+    this.locks = new LockManager(this);
+    this.middlewares = EventBus.normalizeMiddlewares(options.middlewares);
+    this.all_instances.add(this);
+    this.dispatch = this.dispatch.bind(this);
+    this.emit = this.emit.bind(this);
+  }
+  toString() {
+    return `${this.name}#${this.id.slice(-4)}`;
+  }
+  scheduleMicrotask(fn) {
+    if (typeof queueMicrotask === "function") {
+      queueMicrotask(fn);
+      return;
+    }
+    void Promise.resolve().then(fn);
+  }
+  async _runMiddlewareHook(hook, args) {
+    if (this.middlewares.length === 0) {
+      return;
+    }
+    for (const middleware of this.middlewares) {
+      const callback = middleware[hook];
+      if (!callback) {
+        continue;
+      }
+      await callback.apply(middleware, args);
+    }
+  }
+  async onEventChange(event, status) {
+    await this._onEventChange(event, status);
+  }
+  async onEventResultChange(event, result, status) {
+    await this._onEventResultChange(event, result, status);
+  }
+  async _onEventChange(event, status) {
+    await this._runMiddlewareHook("onEventChange", [this, event, status]);
+  }
+  async _onEventResultChange(event, result, status) {
+    await this._runMiddlewareHook("onEventResultChange", [this, event, result, status]);
+  }
+  async _onBusHandlersChange(handler, registered) {
+    await this._runMiddlewareHook("onBusHandlersChange", [this, handler, registered]);
+  }
+  _finalizeEventTimeout(event, pending_entries, timeout_error) {
+    const timeout_seconds = timeout_error.timeout_seconds ?? event.event_timeout ?? null;
+    event._cancelPendingChildProcessing(timeout_error);
+    for (const entry of pending_entries) {
+      const result = entry.result;
+      if (result.status === "completed") {
+        continue;
+      }
+      if (result.status === "error") {
+        continue;
+      }
+      if (result.status === "started") {
+        result._lock?.exitHandlerRun();
+        result._releaseQueueJumpPauses();
+        const aborted_error = new EventHandlerAbortedError(`Aborted running handler due to event timeout`, {
+          event_result: result,
+          timeout_seconds,
+          cause: timeout_error
+        });
+        result._markError(aborted_error);
+        result._signalAbort(aborted_error);
+        continue;
+      }
+      const cancelled_error = new EventHandlerCancelledError(`Cancelled pending handler due to event timeout`, {
+        event_result: result,
+        timeout_seconds,
+        cause: timeout_error
+      });
+      result._markError(cancelled_error);
+    }
+    event.event_pending_bus_count = Math.max(0, event.event_pending_bus_count - 1);
+    event._markCompleted();
+  }
+  _createEventTimeoutError(event, pending_entries, timeout_seconds) {
+    const timeout_anchor = pending_entries.find((entry) => entry.result.status === "started") ?? pending_entries.find((entry) => entry.result.status === "pending") ?? pending_entries[0];
+    return new EventHandlerTimeoutError(
+      `${this.toString()}.on(${event.toString()}, ${timeout_anchor.result.handler.toString()}) timed out after ${timeout_seconds}s`,
+      {
+        event_result: timeout_anchor.result,
+        timeout_seconds
+      }
+    );
+  }
+  async _runHandlersWithTimeout(event, pending_entries, event_timeout, fn) {
+    try {
+      if (event_timeout === null || pending_entries.length === 0) {
+        await fn();
+      } else {
+        await _runWithTimeout(event_timeout, () => this._createEventTimeoutError(event, pending_entries, event_timeout), fn);
+      }
+    } catch (error) {
+      if (error instanceof EventHandlerTimeoutError) {
+        this._finalizeEventTimeout(event, pending_entries, error);
+        return;
+      }
+      throw error;
+    }
+  }
+  _markEventCompletedIfNeeded(event) {
+    if (event.event_status !== "completed") {
+      event.event_pending_bus_count = Math.max(0, event.event_pending_bus_count - 1);
+      event._markCompleted(false);
+    }
+    if (this.event_history.max_history_size !== null && this.event_history.max_history_size > 0 && this.event_history.size > this.event_history.max_history_size) {
+      this.event_history.trimEventHistory({
+        is_event_complete: (candidate_event) => candidate_event.event_status === "completed",
+        on_remove: (candidate_event) => candidate_event._gc(),
+        owner_label: this.toString(),
+        max_history_size: this.event_history.max_history_size,
+        max_history_drop: this.event_history.max_history_drop
+      });
+    }
+  }
+  toJSON() {
+    const handlers = {};
+    for (const [handler_id, handler] of this.handlers.entries()) {
+      handlers[handler_id] = handler.toJSON();
+    }
+    const handlers_by_key = {};
+    for (const [key, ids] of this.handlers_by_key.entries()) {
+      handlers_by_key[key] = [...ids];
+    }
+    const event_history = {};
+    for (const [event_id, event] of this.event_history.entries()) {
+      event_history[event_id] = event.toJSON();
+    }
+    const pending_event_queue = [];
+    for (const event of this.pending_event_queue) {
+      const event_id = event.event_id;
+      if (!event_history[event_id]) {
+        event_history[event_id] = event.toJSON();
+      }
+      pending_event_queue.push(event_id);
+    }
+    return {
+      id: this.id,
+      name: this.name,
+      max_history_size: this.event_history.max_history_size,
+      max_history_drop: this.event_history.max_history_drop,
+      event_concurrency: this.event_concurrency,
+      event_timeout: this.event_timeout,
+      event_slow_timeout: this.event_slow_timeout,
+      event_handler_concurrency: this.event_handler_concurrency,
+      event_handler_completion: this.event_handler_completion,
+      event_handler_slow_timeout: this.event_handler_slow_timeout,
+      event_handler_detect_file_paths: this.event_handler_detect_file_paths,
+      handlers,
+      handlers_by_key,
+      event_history,
+      pending_event_queue
+    };
+  }
+  static _stubHandlerFn() {
+    return (() => void 0);
+  }
+  static _upsertHandlerIndex(bus, event_pattern, handler_id) {
+    const ids = bus.handlers_by_key.get(event_pattern);
+    if (ids) {
+      if (!ids.includes(handler_id)) {
+        ids.push(handler_id);
+      }
+      return;
+    }
+    bus.handlers_by_key.set(event_pattern, [handler_id]);
+  }
+  static _linkEventResultHandlers(event, bus) {
+    for (const [map_key, result] of Array.from(event.event_results.entries())) {
+      const handler_id = result.handler_id;
+      const existing_handler = bus.handlers.get(handler_id);
+      if (existing_handler) {
+        result.handler = existing_handler;
+      } else {
+        const source = result.handler;
+        const handler_entry = EventHandler.fromJSON(
+          {
+            ...source.toJSON(),
+            id: handler_id,
+            event_pattern: source.event_pattern || event.event_type,
+            eventbus_name: source.eventbus_name || bus.name,
+            eventbus_id: source.eventbus_id || bus.id
+          },
+          EventBus._stubHandlerFn()
+        );
+        bus.handlers.set(handler_entry.id, handler_entry);
+        EventBus._upsertHandlerIndex(bus, handler_entry.event_pattern, handler_entry.id);
+        result.handler = handler_entry;
+      }
+      if (map_key !== handler_id) {
+        event.event_results.delete(map_key);
+        event.event_results.set(handler_id, result);
+      }
+    }
+  }
+  static fromJSON(data) {
+    if (!data || typeof data !== "object") {
+      throw new Error("EventBus.fromJSON(data) requires an object");
+    }
+    const record = data;
+    const name = typeof record.name === "string" ? record.name : "EventBus";
+    const options = {};
+    if (typeof record.id === "string") options.id = record.id;
+    if (typeof record.max_history_size === "number" || record.max_history_size === null) options.max_history_size = record.max_history_size;
+    if (typeof record.max_history_drop === "boolean") options.max_history_drop = record.max_history_drop;
+    if (record.event_concurrency === "global-serial" || record.event_concurrency === "bus-serial" || record.event_concurrency === "parallel") {
+      options.event_concurrency = record.event_concurrency;
+    }
+    if (typeof record.event_timeout === "number" || record.event_timeout === null) options.event_timeout = record.event_timeout;
+    if (typeof record.event_slow_timeout === "number" || record.event_slow_timeout === null)
+      options.event_slow_timeout = record.event_slow_timeout;
+    if (record.event_handler_concurrency === "serial" || record.event_handler_concurrency === "parallel") {
+      options.event_handler_concurrency = record.event_handler_concurrency;
+    }
+    if (record.event_handler_completion === "all" || record.event_handler_completion === "first") {
+      options.event_handler_completion = record.event_handler_completion;
+    }
+    if (typeof record.event_handler_slow_timeout === "number" || record.event_handler_slow_timeout === null) {
+      options.event_handler_slow_timeout = record.event_handler_slow_timeout;
+    }
+    if (typeof record.event_handler_detect_file_paths === "boolean") {
+      options.event_handler_detect_file_paths = record.event_handler_detect_file_paths;
+    }
+    const bus = new EventBus(name, options);
+    if (!record.handlers || typeof record.handlers !== "object" || Array.isArray(record.handlers)) {
+      throw new Error("EventBus.fromJSON(data) requires handlers as an id-keyed object");
+    }
+    for (const [handler_id, payload] of Object.entries(record.handlers)) {
+      if (!payload || typeof payload !== "object") {
+        continue;
+      }
+      const parsed = EventHandler.fromJSON(
+        {
+          ...payload,
+          id: typeof payload.id === "string" ? payload.id : handler_id
+        },
+        EventBus._stubHandlerFn()
+      );
+      bus.handlers.set(parsed.id, parsed);
+    }
+    if (!record.handlers_by_key || typeof record.handlers_by_key !== "object" || Array.isArray(record.handlers_by_key)) {
+      throw new Error("EventBus.fromJSON(data) requires handlers_by_key as an object");
+    }
+    bus.handlers_by_key.clear();
+    for (const [raw_key, raw_ids] of Object.entries(record.handlers_by_key)) {
+      if (!Array.isArray(raw_ids)) {
+        continue;
+      }
+      const ids = raw_ids.filter((id) => typeof id === "string");
+      bus.handlers_by_key.set(raw_key, ids);
+    }
+    if (!record.event_history || typeof record.event_history !== "object" || Array.isArray(record.event_history)) {
+      throw new Error("EventBus.fromJSON(data) requires event_history as an id-keyed object");
+    }
+    for (const [event_id, payload] of Object.entries(record.event_history)) {
+      if (!payload || typeof payload !== "object") {
+        continue;
+      }
+      const event = BaseEvent.fromJSON({
+        ...payload,
+        event_id: typeof payload.event_id === "string" ? payload.event_id : event_id
+      });
+      event.bus = bus;
+      bus.event_history.set(event.event_id, event);
+    }
+    if (!Array.isArray(record.pending_event_queue)) {
+      throw new Error("EventBus.fromJSON(data) requires pending_event_queue as an array of event ids");
+    }
+    const raw_pending_event_queue = record.pending_event_queue;
+    const pending_event_ids = [];
+    for (const item of raw_pending_event_queue) {
+      if (typeof item === "string") {
+        pending_event_ids.push(item);
+      }
+    }
+    bus.pending_event_queue = pending_event_ids.map((event_id) => bus.event_history.get(event_id)).filter((event) => Boolean(event));
+    for (const event of bus.event_history.values()) {
+      EventBus._linkEventResultHandlers(event, bus);
+    }
+    bus.in_flight_event_ids.clear();
+    bus.runloop_running = false;
+    bus.locks.clear();
+    bus.find_waiters.clear();
+    return bus;
+  }
+  get label() {
+    return `${this.name}#${this.id.slice(-4)}`;
+  }
+  removeEventFromPendingQueue(event) {
+    const original_event = event._event_original ?? event;
+    let removed_count = 0;
+    for (let index = this.pending_event_queue.length - 1; index >= 0; index -= 1) {
+      const queued_event = this.pending_event_queue[index];
+      const queued_original = queued_event._event_original ?? queued_event;
+      if (queued_original.event_id !== original_event.event_id) {
+        continue;
+      }
+      this.pending_event_queue.splice(index, 1);
+      removed_count += 1;
+    }
+    return removed_count;
+  }
+  isEventInFlightOrQueued(event_id) {
+    if (this.in_flight_event_ids.has(event_id)) {
+      return true;
+    }
+    for (const queued_event of this.pending_event_queue) {
+      const queued_original = queued_event._event_original ?? queued_event;
+      if (queued_original.event_id === event_id) {
+        return true;
+      }
+    }
+    return false;
+  }
+  removeEventFromHistory(event_id) {
+    return this.event_history.delete(event_id);
+  }
+  // destroy the event bus and all its state to allow for garbage collection
+  destroy() {
+    this.all_instances.discard(this);
+    this.handlers.clear();
+    this.handlers_by_key.clear();
+    for (const event of this.event_history.values()) {
+      event._gc();
+    }
+    this.event_history.clear();
+    this.pending_event_queue.length = 0;
+    this.in_flight_event_ids.clear();
+    this.find_waiters.clear();
+    this.locks.clear();
+  }
+  on(event_pattern, handler, options = {}) {
+    const normalized_key = normalizeEventPattern(event_pattern);
+    const handler_name = handler.name || "anonymous";
+    const handler_entry = new EventHandler({
+      handler,
+      handler_name,
+      handler_registered_at: monotonicDatetime(),
+      event_pattern: normalized_key,
+      eventbus_name: this.name,
+      eventbus_id: this.id,
+      ...options
+    });
+    if (this.event_handler_detect_file_paths) {
+      handler_entry._detectHandlerFilePath();
+    }
+    this.handlers.set(handler_entry.id, handler_entry);
+    const ids = this.handlers_by_key.get(handler_entry.event_pattern);
+    if (ids) ids.push(handler_entry.id);
+    else this.handlers_by_key.set(handler_entry.event_pattern, [handler_entry.id]);
+    this.scheduleMicrotask(() => {
+      void this._onBusHandlersChange(handler_entry, true);
+    });
+    return handler_entry;
+  }
+  off(event_pattern, handler) {
+    const normalized_key = normalizeEventPattern(event_pattern);
+    if (typeof handler === "object" && handler instanceof EventHandler && handler.id !== void 0) {
+      handler = handler.id;
+    }
+    const match_by_id = typeof handler === "string";
+    for (const entry of this.handlers.values()) {
+      if (entry.event_pattern !== normalized_key) {
+        continue;
+      }
+      const handler_id = entry.id;
+      if (handler === void 0 || (match_by_id ? handler_id === handler : entry.handler === handler)) {
+        this.handlers.delete(handler_id);
+        this._removeIndexedHandler(entry.event_pattern, handler_id);
+        this.scheduleMicrotask(() => {
+          void this._onBusHandlersChange(entry, false);
+        });
+      }
+    }
+  }
+  emit(event) {
+    const original_event = event._event_original ?? event;
+    if (!original_event.bus) {
+      original_event.bus = this;
+    }
+    if (!Array.isArray(original_event.event_path)) {
+      original_event.event_path = [];
+    }
+    if (original_event._getDispatchContext() === void 0) {
+      original_event._setDispatchContext(captureAsyncContext());
+    }
+    if (original_event.event_path.includes(this.label) || this._hasProcessedEvent(original_event)) {
+      return this._getEventProxyScopedToThisBus(original_event);
+    }
+    if (!original_event.event_path.includes(this.label)) {
+      original_event.event_path.push(this.label);
+    }
+    if (!original_event.event_parent_id && !original_event.event_emitted_by_handler_id) {
+      this._resolveImplicitParentHandlerResult()?._linkEmittedChildEvent(original_event);
+    }
+    if (original_event.event_parent_id && original_event.event_emitted_by_handler_id) {
+      const parent_result = original_event.event_parent?.event_results.get(original_event.event_emitted_by_handler_id);
+      if (parent_result) {
+        parent_result._linkEmittedChildEvent(original_event);
+      }
+    }
+    if (this.event_history.max_history_size !== null && this.event_history.max_history_size > 0 && !this.event_history.max_history_drop && this.event_history.size >= this.event_history.max_history_size) {
+      throw new Error(
+        `${this.toString()}.emit(${original_event.event_type}) rejected: history limit reached (${this.event_history.size}/${this.event_history.max_history_size}); set event_history.max_history_drop=true to drop old history instead.`
+      );
+    }
+    this.event_history.addEvent(original_event);
+    this.event_history.trimEventHistory({
+      is_event_complete: (candidate_event) => candidate_event.event_status === "completed",
+      on_remove: (candidate_event) => candidate_event._gc(),
+      owner_label: this.toString(),
+      max_history_size: this.event_history.max_history_size,
+      max_history_drop: this.event_history.max_history_drop
+    });
+    this._resolveFindWaiters(original_event);
+    original_event.event_pending_bus_count += 1;
+    this.pending_event_queue.push(original_event);
+    this._startRunloop();
+    return this._getEventProxyScopedToThisBus(original_event);
+  }
+  // alias for emit
+  dispatch(event) {
+    return this.emit(event);
+  }
+  async find(event_pattern, where_or_options = {}, maybe_options = {}) {
+    const where = typeof where_or_options === "function" ? where_or_options : () => true;
+    const options = typeof where_or_options === "function" ? maybe_options : where_or_options;
+    const match = await this.event_history.find(event_pattern, where, {
+      ...options,
+      event_is_child_of: (event, ancestor) => this.eventIsChildOf(event, ancestor),
+      wait_for_future_match: (normalized_event_pattern, matches, future) => this._waitForFutureMatch(normalized_event_pattern, matches, future)
+    });
+    if (!match) {
+      return null;
+    }
+    return this._getEventProxyScopedToThisBus(match);
+  }
+  async _waitForFutureMatch(event_pattern, matches, future) {
+    if (future === false) {
+      return null;
+    }
+    return await new Promise((resolve) => {
+      const waiter = {
+        event_pattern,
+        matches,
+        resolve: (event) => resolve(event)
+      };
+      if (future !== true) {
+        const timeout_ms = Math.max(0, Number(future)) * 1e3;
+        waiter.timeout_id = setTimeout(() => {
+          this.find_waiters.delete(waiter);
+          resolve(null);
+        }, timeout_ms);
+      }
+      this.find_waiters.add(waiter);
+    });
+  }
+  async waitUntilIdle(timeout = null) {
+    return await this.locks.waitForIdle(timeout);
+  }
+  // Weak idle check: only checks if handlers are idle, doesnt check that the queue is empty
+  isIdle() {
+    for (const event of this.event_history.values()) {
+      for (const result of event.event_results.values()) {
+        if (result.eventbus_id !== this.id) {
+          continue;
+        }
+        if (result.status === "pending" || result.status === "started") {
+          return false;
+        }
+      }
+    }
+    return true;
+  }
+  // Stronger idle check: no queued work, no in-flight processing, _runloop not
+  // active, and no handlers pending/running for this bus.
+  isIdleAndQueueEmpty() {
+    return this.pending_event_queue.length === 0 && this.in_flight_event_ids.size === 0 && this.isIdle() && !this.runloop_running;
+  }
+  eventIsChildOf(child_event, parent_event) {
+    if (child_event.event_id === parent_event.event_id) {
+      return false;
+    }
+    let current_parent_id = child_event.event_parent_id;
+    while (current_parent_id) {
+      if (current_parent_id === parent_event.event_id) {
+        return true;
+      }
+      const parent = this.event_history.get(current_parent_id);
+      if (!parent) {
+        return false;
+      }
+      current_parent_id = parent.event_parent_id;
+    }
+    return false;
+  }
+  eventIsParentOf(parent_event, child_event) {
+    return this.eventIsChildOf(child_event, parent_event);
+  }
+  // return a full detailed tree diagram of all events and results on this bus
+  logTree() {
+    return logTree(this);
+  }
+  // Resolve an event id from this bus first, then across all known buses.
+  findEventById(event_id) {
+    return this.event_history.get(event_id) ?? this.all_instances.findEventById(event_id);
+  }
+  // Walk up the parent event chain to find an in-flight ancestor handler result.
+  // Returns the result if found, null otherwise. Used by _processEventImmediately to detect
+  // cross-bus queue-jump scenarios where the calling handler is on a different bus.
+  _getParentEventResultAcrossAllBuses(event) {
+    const original = event._event_original ?? event;
+    let current_parent_id = original.event_parent_id;
+    let current_handler_id = original.event_emitted_by_handler_id;
+    while (current_handler_id && current_parent_id) {
+      const parent = this.all_instances.findEventById(current_parent_id);
+      if (!parent) break;
+      const handler_result = parent.event_results.get(current_handler_id);
+      if (handler_result && handler_result.status === "started") return handler_result;
+      current_parent_id = parent.event_parent_id;
+      current_handler_id = parent.event_emitted_by_handler_id;
+    }
+    return null;
+  }
+  _startRunloop() {
+    if (this.runloop_running) {
+      return;
+    }
+    this.runloop_running = true;
+    this.scheduleMicrotask(() => {
+      void this._runloop();
+    });
+  }
+  // schedule the processing of an event on the event bus by its normal _runloop
+  // optionally using a pre-acquired lock if we're inside handling of a parent event
+  async _processEvent(event, options = {}) {
+    let pending_entries = [];
+    try {
+      if (this._hasProcessedEvent(event)) {
+        return;
+      }
+      const scoped_event = this._getEventProxyScopedToThisBus(event);
+      await this._onEventChange(scoped_event, "pending");
+      event._markStarted();
+      pending_entries = event._createPendingHandlerResults(this);
+      const resolved_event_timeout = event.event_timeout ?? this.event_timeout;
+      if (this.middlewares.length > 0) {
+        for (const entry of pending_entries) {
+          await this._onEventResultChange(scoped_event, entry.result, "pending");
+        }
+      }
+      await this.locks._runWithEventLock(
+        event,
+        () => this._runHandlersWithTimeout(
+          event,
+          pending_entries,
+          resolved_event_timeout,
+          () => _runWithSlowMonitor(event._createSlowEventWarningTimer(), () => scoped_event._runHandlers(pending_entries))
+        ),
+        options
+      );
+      this._markEventCompletedIfNeeded(event);
+    } finally {
+      if (options.pre_acquired_lock) {
+        options.pre_acquired_lock.release();
+      }
+      this.in_flight_event_ids.delete(event.event_id);
+      this.locks._notifyIdleListeners();
+    }
+  }
+  // Called when a handler does `await child.done()` — processes the child event
+  // immediately ("queue-jump") instead of waiting for the _runloop to pick it up.
+  //
+  // Yield-and-reacquire: if the calling handler holds a handler concurrency lock,
+  // we temporarily release it so child handlers on the same bus can acquire it
+  // (preventing deadlock for serial handler mode). We re-acquire after
+  // the child completes so the parent handler can continue with the lock held.
+  async _processEventImmediately(event, handler_result) {
+    const original_event = event._event_original ?? event;
+    const proxy_result = handler_result?.status === "started" ? handler_result : void 0;
+    const currently_active_event_result = proxy_result ?? this.locks._getActiveHandlerResult() ?? this._getParentEventResultAcrossAllBuses(original_event) ?? void 0;
+    if (!currently_active_event_result) {
+      const queue_index = this.pending_event_queue.indexOf(original_event);
+      const can_process_now = queue_index === 0 && !this.locks._isPaused() && !this.in_flight_event_ids.has(original_event.event_id) && !this._hasProcessedEvent(original_event);
+      if (can_process_now) {
+        const event_lock = this.locks.getLockForEvent(original_event);
+        let pre_acquired_lock = null;
+        if (event_lock) {
+          await event_lock.acquire();
+          pre_acquired_lock = event_lock;
+        }
+        const queue_head = this.pending_event_queue[0];
+        const queue_head_original = queue_head?._event_original ?? queue_head;
+        const still_can_process_now = queue_head_original === original_event && !this.locks._isPaused() && !this.in_flight_event_ids.has(original_event.event_id) && !this._hasProcessedEvent(original_event);
+        if (still_can_process_now) {
+          this.pending_event_queue.shift();
+          this.in_flight_event_ids.add(original_event.event_id);
+          await this._processEvent(original_event, {
+            bypass_event_locks: true,
+            pre_acquired_lock
+          });
+          if (original_event.event_status !== "completed") {
+            await original_event.eventCompleted();
+          }
+          return event;
+        }
+        if (pre_acquired_lock) {
+          pre_acquired_lock.release();
+        }
+      }
+      await original_event.eventCompleted();
+      return event;
+    }
+    currently_active_event_result._ensureQueueJumpPause(this);
+    if (original_event.event_status === "completed") {
+      return event;
+    }
+    if (currently_active_event_result._lock) {
+      await currently_active_event_result._lock.runQueueJump(this._processEventImmediatelyAcrossBuses.bind(this, original_event));
+      return event;
+    }
+    await this._processEventImmediatelyAcrossBuses(original_event);
+    return event;
+  }
+  // Processes a queue-jumped event across all buses that have it emitted.
+  // Called from _processEventImmediately after the parent handler's lock has been yielded.
+  async _processEventImmediatelyAcrossBuses(event) {
+    const ordered = [];
+    const seen = /* @__PURE__ */ new Set();
+    const event_path = Array.isArray(event.event_path) ? event.event_path : [];
+    for (const label of event_path) {
+      for (const bus of this.all_instances) {
+        if (bus.label !== label) {
+          continue;
+        }
+        if (!bus.event_history.has(event.event_id)) {
+          continue;
+        }
+        if (bus._hasProcessedEvent(event)) {
+          continue;
+        }
+        if (!seen.has(bus)) {
+          ordered.push(bus);
+          seen.add(bus);
+        }
+      }
+    }
+    if (!seen.has(this) && this.event_history.has(event.event_id)) {
+      ordered.push(this);
+    }
+    if (ordered.length === 0) {
+      await event.eventCompleted();
+      return;
+    }
+    const initiating_event_lock = this.locks.getLockForEvent(event);
+    const pause_releases = [];
+    try {
+      for (const bus of ordered) {
+        if (bus !== this) {
+          pause_releases.push(bus.locks._requestRunloopPause());
+        }
+      }
+      for (const bus of ordered) {
+        const index = bus.pending_event_queue.indexOf(event);
+        if (index >= 0) {
+          bus.pending_event_queue.splice(index, 1);
+        }
+        if (bus._hasProcessedEvent(event)) {
+          continue;
+        }
+        if (bus.in_flight_event_ids.has(event.event_id)) {
+          continue;
+        }
+        bus.in_flight_event_ids.add(event.event_id);
+        const bus_event_lock = bus.locks.getLockForEvent(event);
+        const should_bypass_event_lock = bus === this || initiating_event_lock !== null && bus_event_lock === initiating_event_lock;
+        await bus._processEvent(event, {
+          bypass_event_locks: should_bypass_event_lock
+        });
+      }
+      if (event.event_status !== "completed") {
+        await event.eventCompleted();
+      }
+    } finally {
+      for (const release of pause_releases) {
+        release();
+      }
+    }
+  }
+  async _runloop() {
+    for (; ; ) {
+      while (this.pending_event_queue.length > 0) {
+        await Promise.resolve();
+        if (this.locks._isPaused()) {
+          await this.locks._waitUntilRunloopResumed();
+          continue;
+        }
+        const next_event = this.pending_event_queue[0];
+        if (!next_event) {
+          continue;
+        }
+        const original_event = next_event._event_original ?? next_event;
+        if (this._hasProcessedEvent(original_event)) {
+          this.pending_event_queue.shift();
+          continue;
+        }
+        let pre_acquired_lock = null;
+        const event_lock = this.locks.getLockForEvent(original_event);
+        if (event_lock) {
+          await event_lock.acquire();
+          pre_acquired_lock = event_lock;
+        }
+        const current_head = this.pending_event_queue[0];
+        const current_head_original = current_head?._event_original ?? current_head;
+        if (current_head_original !== original_event) {
+          if (pre_acquired_lock) {
+            pre_acquired_lock.release();
+          }
+          continue;
+        }
+        this.pending_event_queue.shift();
+        if (this.in_flight_event_ids.has(original_event.event_id)) {
+          if (pre_acquired_lock) {
+            pre_acquired_lock.release();
+          }
+          continue;
+        }
+        this.in_flight_event_ids.add(original_event.event_id);
+        void this._processEvent(original_event, {
+          bypass_event_locks: true,
+          pre_acquired_lock
+        });
+        await Promise.resolve();
+      }
+      this.runloop_running = false;
+      if (this.pending_event_queue.length > 0) {
+        this._startRunloop();
+        return;
+      }
+      this.locks._notifyIdleListeners();
+      return;
+    }
+  }
+  // check if an event has been processed (and completed) by this bus
+  _hasProcessedEvent(event) {
+    const results = Array.from(event.event_results.values()).filter((result) => result.eventbus_id === this.id);
+    if (results.length === 0) {
+      return false;
+    }
+    return results.every((result) => result.status === "completed" || result.status === "error");
+  }
+  _resolveImplicitParentHandlerResult() {
+    const active_on_target_bus = this.locks._getActiveHandlerResults().filter((result) => result.status === "started");
+    if (active_on_target_bus.length === 1) {
+      return active_on_target_bus[0];
+    }
+    const active_globally = [];
+    for (const bus of this.all_instances) {
+      for (const result of bus.locks._getActiveHandlerResults()) {
+        if (result.status === "started") {
+          active_globally.push(result);
+        }
+      }
+    }
+    if (active_globally.length === 1) {
+      return active_globally[0];
+    }
+    return null;
+  }
+  // get a proxy wrapper around an Event that will automatically link emitted child events to this bus and handler
+  // proxy is what gets passed into the handler, if handler does event.bus.emit(...) to dispatch child events,
+  // the proxy auto-sets event.parent_event_id and event.event_emitted_by_handler_id
+  _getEventProxyScopedToThisBus(event, handler_result) {
+    const original_event = event._event_original ?? event;
+    const bus = this;
+    const parent_event_id = original_event.event_id;
+    const bus_proxy = new Proxy(bus, {
+      get(target, prop, receiver) {
+        if (prop === "_processEventImmediately") {
+          const runner = Reflect.get(target, prop, receiver);
+          const process_event_immediately = (child_event) => {
+            return runner.call(target, child_event, handler_result);
+          };
+          return process_event_immediately;
+        }
+        if (prop === "dispatch" || prop === "emit") {
+          const emit_child_event = (child_event) => {
+            const original_child = child_event._event_original ?? child_event;
+            if (handler_result) {
+              handler_result._linkEmittedChildEvent(original_child);
+            } else if (!original_child.event_parent_id && original_child.event_id !== parent_event_id) {
+              original_child.event_parent_id = parent_event_id;
+            }
+            const dispatcher = Reflect.get(target, prop, receiver);
+            const dispatched = dispatcher.call(target, original_child);
+            return target._getEventProxyScopedToThisBus(dispatched, handler_result);
+          };
+          return emit_child_event;
+        }
+        return Reflect.get(target, prop, receiver);
+      }
+    });
+    const scoped = new Proxy(original_event, {
+      get(target, prop, receiver) {
+        if (prop === "bus") {
+          return bus_proxy;
+        }
+        if (prop === "_event_original") {
+          return target;
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+      set(target, prop, value) {
+        if (prop === "bus") {
+          return true;
+        }
+        return Reflect.set(target, prop, value, target);
+      },
+      has(target, prop) {
+        if (prop === "bus") {
+          return true;
+        }
+        if (prop === "_event_original") {
+          return true;
+        }
+        return Reflect.has(target, prop);
+      }
+    });
+    return scoped;
+  }
+  _resolveFindWaiters(event) {
+    for (const waiter of Array.from(this.find_waiters)) {
+      if (waiter.event_pattern !== "*" && event.event_type !== waiter.event_pattern || !waiter.matches(event)) {
+        continue;
+      }
+      if (waiter.timeout_id) {
+        clearTimeout(waiter.timeout_id);
+      }
+      this.find_waiters.delete(waiter);
+      waiter.resolve(event);
+    }
+  }
+  _getHandlersForEvent(event) {
+    const handlers = [];
+    for (const key of [event.event_type, "*"]) {
+      const ids = this.handlers_by_key.get(key);
+      if (!ids) continue;
+      for (const id of ids) {
+        const entry = this.handlers.get(id);
+        if (entry) handlers.push(entry);
+      }
+    }
+    return handlers;
+  }
+  _removeIndexedHandler(event_pattern, handler_id) {
+    const ids = this.handlers_by_key.get(event_pattern);
+    if (!ids) return;
+    const idx = ids.indexOf(handler_id);
+    if (idx < 0) return;
+    ids.splice(idx, 1);
+    if (ids.length === 0) this.handlers_by_key.delete(event_pattern);
+  }
+}
+export {
+  EventBus,
+  GlobalEventBusRegistry
+};
+//# sourceMappingURL=event_bus.js.map