bubus 1.8.1 → 2.2.1

package/dist/esm/base_event.js

@@ -0,0 +1,825 @@
+import { z } from "zod";
+import { v7 as uuidv7 } from "uuid";
+import { EventResult } from "./event_result.js";
+import { EventHandler, EventHandlerAbortedError, EventHandlerCancelledError, EventHandlerTimeoutError } from "./event_handler.js";
+import {
+  AsyncLock,
+  EVENT_CONCURRENCY_MODES,
+  EVENT_HANDLER_CONCURRENCY_MODES,
+  EVENT_HANDLER_COMPLETION_MODES,
+  withResolvers
+} from "./lock_manager.js";
+import { _runWithTimeout } from "./timing.js";
+import { extractZodShape, normalizeEventResultType, toJsonSchema } from "./types.js";
+import { monotonicDatetime } from "./helpers.js";
+const RESERVED_USER_EVENT_FIELDS = /* @__PURE__ */ new Set(["bus", "first", "toString", "toJSON", "fromJSON"]);
+function assertNoReservedUserEventFields(data, context) {
+  for (const field_name of RESERVED_USER_EVENT_FIELDS) {
+    if (Object.prototype.hasOwnProperty.call(data, field_name)) {
+      throw new Error(`${context} field "${field_name}" is reserved for EventBus runtime context and cannot be set in event payload`);
+    }
+  }
+}
+function assertNoUnknownEventPrefixedFields(data, context) {
+  for (const field_name of Object.keys(data)) {
+    if (field_name.startsWith("event_") && !KNOWN_BASE_EVENT_FIELDS.has(field_name)) {
+      throw new Error(`${context} field "${field_name}" starts with "event_" but is not a recognized BaseEvent field`);
+    }
+  }
+}
+function assertNoModelPrefixedFields(data, context) {
+  for (const field_name of Object.keys(data)) {
+    if (field_name.startsWith("model_")) {
+      throw new Error(`${context} field "${field_name}" starts with "model_" and is reserved for model internals`);
+    }
+  }
+}
+function compareIsoDatetime(left, right) {
+  const left_value = left ?? "";
+  const right_value = right ?? "";
+  if (left_value === right_value) {
+    return 0;
+  }
+  return left_value < right_value ? -1 : 1;
+}
+const BaseEventSchema = z.object({
+  event_id: z.string().uuid(),
+  event_created_at: z.string().datetime(),
+  event_type: z.string(),
+  event_version: z.string().default("0.0.1"),
+  event_timeout: z.number().positive().nullable(),
+  event_slow_timeout: z.number().positive().nullable().optional(),
+  event_handler_timeout: z.number().positive().nullable().optional(),
+  event_handler_slow_timeout: z.number().positive().nullable().optional(),
+  event_parent_id: z.string().uuid().nullable().optional(),
+  event_path: z.array(z.string()).optional(),
+  event_result_type: z.unknown().optional(),
+  event_emitted_by_handler_id: z.string().uuid().nullable().optional(),
+  event_pending_bus_count: z.number().nonnegative().optional(),
+  event_status: z.enum(["pending", "started", "completed"]).optional(),
+  event_started_at: z.string().datetime().nullable().optional(),
+  event_completed_at: z.string().datetime().nullable().optional(),
+  event_results: z.array(z.unknown()).optional(),
+  event_concurrency: z.enum(EVENT_CONCURRENCY_MODES).nullable().optional(),
+  event_handler_concurrency: z.enum(EVENT_HANDLER_CONCURRENCY_MODES).nullable().optional(),
+  event_handler_completion: z.enum(EVENT_HANDLER_COMPLETION_MODES).nullable().optional()
+}).loose();
+const KNOWN_BASE_EVENT_FIELDS = new Set(Object.keys(BaseEventSchema.shape));
+const EVENT_CLASS_DEFAULTS = /* @__PURE__ */ new WeakMap();
+const ROOT_EVENTBUS_ID = "00000000-0000-0000-0000-000000000000";
+class BaseEvent {
+  // event metadata fields
+  event_id;
+  // unique uuidv7 identifier for the event
+  event_created_at;
+  event_type;
+  // should match the class name of the event, e.g. BaseEvent.extend("MyEvent").event_type === "MyEvent"
+  event_version;
+  // event schema/version tag managed by callers for migration-friendly payload handling
+  event_timeout;
+  // maximum time in seconds that the event is allowed to run before it is aborted
+  event_slow_timeout;
+  // optional per-event slow warning threshold in seconds
+  event_handler_timeout;
+  // optional per-event handler timeout override in seconds
+  event_handler_slow_timeout;
+  // optional per-event slow handler warning threshold in seconds
+  event_parent_id;
+  // id of the parent event that triggered this event, if this event was emitted during handling of another event, else null
+  event_path;
+  // list of bus labels (name#id) that the event has been dispatched to, including the current bus
+  event_result_type;
+  // optional zod schema to enforce the shape of return values from handlers
+  event_results;
+  // map of handler ids to EventResult objects for the event
+  event_emitted_by_handler_id;
+  // if event was emitted inside a handler while it was running, this is set to the enclosing handler's handler id, else null
+  event_pending_bus_count;
+  // number of buses that have accepted this event and not yet finished processing or removed it from their queues (for queue-jump processing)
+  event_status;
+  // processing status of the event as a whole, no separate 'error' state because events can not error, only individual handlers can
+  event_started_at;
+  event_completed_at;
+  event_concurrency;
+  // concurrency mode for the event as a whole in relation to other events
+  event_handler_concurrency;
+  // concurrency mode for the handlers within the event
+  event_handler_completion;
+  // completion strategy: 'all' (default) waits for every handler, 'first' returns earliest non-undefined result and cancels the rest
+  static event_type;
+  // class name of the event, e.g. BaseEvent.extend("MyEvent").event_type === "MyEvent"
+  static event_version = "0.0.1";
+  static schema = BaseEventSchema;
+  // zod schema for the event data fields, used to parse and validate event data when creating a new event
+  // internal runtime state
+  bus;
+  // shortcut to the bus that dispatched this event, for event.bus.emit(event) auto-child tracking via proxy wrapping
+  _event_original;
+  // underlying event object that was dispatched, if this is a bus-scoped proxy wrapping it
+  _event_dispatch_context;
+  // captured AsyncLocalStorage context at dispatch site, used to restore that context when running handlers
+  _event_completed_signal;
+  _lock_for_event_handler;
+  get event_bus() {
+    return this.bus;
+  }
+  constructor(data = {}) {
+    assertNoReservedUserEventFields(data, "BaseEvent");
+    assertNoUnknownEventPrefixedFields(data, "BaseEvent");
+    assertNoModelPrefixedFields(data, "BaseEvent");
+    const ctor = this.constructor;
+    const ctor_defaults = EVENT_CLASS_DEFAULTS.get(ctor) ?? {};
+    const merged_data = {
+      ...ctor_defaults,
+      ...data
+    };
+    const event_type = merged_data.event_type ?? ctor.event_type ?? ctor.name;
+    const event_version = merged_data.event_version ?? ctor.event_version ?? "0.0.1";
+    const raw_event_result_type = merged_data.event_result_type ?? ctor.event_result_type;
+    const event_result_type = normalizeEventResultType(raw_event_result_type);
+    const event_id = merged_data.event_id ?? uuidv7();
+    const event_created_at = monotonicDatetime(merged_data.event_created_at);
+    const event_timeout = merged_data.event_timeout ?? null;
+    const base_data = {
+      ...merged_data,
+      event_id,
+      event_created_at,
+      event_type,
+      event_version,
+      event_timeout,
+      event_result_type
+    };
+    const schema = ctor.schema ?? BaseEventSchema;
+    const parsed = schema.parse(base_data);
+    Object.assign(this, parsed);
+    const parsed_path = parsed.event_path;
+    this.event_path = Array.isArray(parsed_path) ? [...parsed_path] : [];
+    this.event_results = hydrateEventResults(this, parsed.event_results);
+    this.event_pending_bus_count = typeof parsed.event_pending_bus_count === "number" ? Math.max(0, Number(parsed.event_pending_bus_count)) : 0;
+    const parsed_status = parsed.event_status;
+    this.event_status = parsed_status === "pending" || parsed_status === "started" || parsed_status === "completed" ? parsed_status : "pending";
+    this.event_started_at = parsed.event_started_at === null || parsed.event_started_at === void 0 ? null : monotonicDatetime(parsed.event_started_at);
+    this.event_completed_at = parsed.event_completed_at === null || parsed.event_completed_at === void 0 ? null : monotonicDatetime(parsed.event_completed_at);
+    this.event_parent_id = typeof parsed.event_parent_id === "string" ? parsed.event_parent_id : null;
+    this.event_emitted_by_handler_id = typeof parsed.event_emitted_by_handler_id === "string" ? parsed.event_emitted_by_handler_id : null;
+    this.event_result_type = event_result_type;
+    this._event_completed_signal = null;
+    this._lock_for_event_handler = null;
+    this._event_dispatch_context = void 0;
+  }
+  // "MyEvent#a48f"
+  toString() {
+    return `${this.event_type}#${this.event_id.slice(-4)}`;
+  }
+  static extend(event_type, shape = {}) {
+    const raw_shape = shape;
+    assertNoReservedUserEventFields(raw_shape, `BaseEvent.extend(${event_type})`);
+    assertNoUnknownEventPrefixedFields(raw_shape, `BaseEvent.extend(${event_type})`);
+    assertNoModelPrefixedFields(raw_shape, `BaseEvent.extend(${event_type})`);
+    const raw_event_result_type = raw_shape.event_result_type;
+    const event_result_type = normalizeEventResultType(raw_event_result_type);
+    const event_version = typeof raw_shape.event_version === "string" ? raw_shape.event_version : void 0;
+    const event_defaults = Object.fromEntries(
+      Object.entries(raw_shape).filter(
+        ([key, value]) => key !== "event_result_type" && key !== "event_version" && !(value instanceof z.ZodType)
+      )
+    );
+    const zod_shape = extractZodShape(raw_shape);
+    const full_schema = BaseEventSchema.extend(zod_shape);
+    class ExtendedEvent extends BaseEvent {
+      static schema = full_schema;
+      static event_type = event_type;
+      static event_version = event_version ?? BaseEvent.event_version;
+      static event_result_type = event_result_type;
+      constructor(data) {
+        super(data);
+      }
+    }
+    function EventFactory(data) {
+      return new ExtendedEvent(data);
+    }
+    EventFactory.schema = full_schema;
+    EventFactory.event_type = event_type;
+    EventFactory.event_version = event_version ?? BaseEvent.event_version;
+    EventFactory.event_result_type = event_result_type;
+    EventFactory.class = ExtendedEvent;
+    EventFactory.fromJSON = (data) => ExtendedEvent.fromJSON(data);
+    EventFactory.prototype = ExtendedEvent.prototype;
+    EVENT_CLASS_DEFAULTS.set(ExtendedEvent, event_defaults);
+    return EventFactory;
+  }
+  static fromJSON(data) {
+    if (!data || typeof data !== "object") {
+      const schema = this.schema ?? BaseEventSchema;
+      const parsed = schema.parse(data);
+      return new this(parsed);
+    }
+    const record = { ...data };
+    if (record.event_result_type !== void 0 && record.event_result_type !== null) {
+      record.event_result_type = normalizeEventResultType(record.event_result_type);
+    }
+    return new this(record);
+  }
+  static toJSONArray(events) {
+    return Array.from(events, (event) => {
+      const original = event._event_original ?? event;
+      return original.toJSON();
+    });
+  }
+  static fromJSONArray(data) {
+    if (!Array.isArray(data)) {
+      return [];
+    }
+    return data.map((item) => BaseEvent.fromJSON(item));
+  }
+  toJSON() {
+    const record = {};
+    for (const [key, value] of Object.entries(this)) {
+      if (key.startsWith("_") || key === "bus" || key === "event_results") continue;
+      if (value === void 0 || typeof value === "function") continue;
+      record[key] = value;
+    }
+    const event_results = Array.from(this.event_results.values()).map((result) => result.toJSON());
+    return {
+      ...record,
+      event_id: this.event_id,
+      event_type: this.event_type,
+      event_version: this.event_version,
+      event_result_type: this.event_result_type ? toJsonSchema(this.event_result_type) : this.event_result_type,
+      // static configuration options
+      event_timeout: this.event_timeout,
+      event_slow_timeout: this.event_slow_timeout,
+      event_concurrency: this.event_concurrency,
+      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_timeout: this.event_handler_timeout,
+      // mutable parent/child/bus tracking runtime state
+      event_parent_id: this.event_parent_id,
+      event_path: this.event_path,
+      event_emitted_by_handler_id: this.event_emitted_by_handler_id,
+      event_pending_bus_count: this.event_pending_bus_count,
+      // mutable runtime status and timestamps
+      event_status: this.event_status,
+      event_created_at: this.event_created_at,
+      event_started_at: this.event_started_at ?? null,
+      event_completed_at: this.event_completed_at ?? null,
+      // mutable result state
+      ...event_results.length > 0 ? { event_results } : {}
+    };
+  }
+  _createSlowEventWarningTimer() {
+    const event_slow_timeout = this.event_slow_timeout ?? this.bus?.event_slow_timeout ?? null;
+    const event_warn_ms = event_slow_timeout === null ? null : event_slow_timeout * 1e3;
+    if (event_warn_ms === null) {
+      return null;
+    }
+    const name = this.bus?.name ?? "EventBus";
+    return setTimeout(() => {
+      if (this.event_status === "completed") {
+        return;
+      }
+      const running_handler_count = [...this.event_results.values()].filter((result) => result.status === "started").length;
+      const started_at = this.event_started_at ?? this.event_created_at;
+      const elapsed_ms = Math.max(0, Date.now() - Date.parse(started_at));
+      const elapsed_seconds = (elapsed_ms / 1e3).toFixed(2);
+      console.warn(
+        `[bubus] Slow event processing: ${name}.on(${this.event_type}#${this.event_id.slice(-4)}, ${running_handler_count} handlers) still running after ${elapsed_seconds}s`
+      );
+    }, event_warn_ms);
+  }
+  eventResultUpdate(handler, options = {}) {
+    const original_event = this._event_original ?? this;
+    let resolved_eventbus = options.eventbus;
+    let handler_entry;
+    if (handler instanceof EventHandler) {
+      handler_entry = handler;
+      if (!resolved_eventbus && handler_entry.eventbus_id !== ROOT_EVENTBUS_ID && original_event.bus) {
+        resolved_eventbus = original_event.bus.all_instances.findBusById(handler_entry.eventbus_id) ?? (original_event.bus.id === handler_entry.eventbus_id ? original_event.bus : void 0);
+      }
+    } else {
+      handler_entry = EventHandler.fromCallable({
+        handler,
+        event_pattern: original_event.event_type,
+        eventbus_name: resolved_eventbus?.name ?? "EventBus",
+        eventbus_id: resolved_eventbus?.id ?? ROOT_EVENTBUS_ID
+      });
+    }
+    const scoped_event = resolved_eventbus ? resolved_eventbus._getEventProxyScopedToThisBus(original_event) : original_event;
+    const handler_id = handler_entry.id;
+    const existing = original_event.event_results.get(handler_id);
+    const event_result = existing ?? new EventResult({ event: scoped_event, handler: handler_entry });
+    if (!existing) {
+      original_event.event_results.set(handler_id, event_result);
+    } else {
+      if (existing.event !== scoped_event) {
+        existing.event = scoped_event;
+      }
+      if (existing.handler.id !== handler_entry.id) {
+        existing.handler = handler_entry;
+      }
+    }
+    if (options.status !== void 0 || options.result !== void 0 || options.error !== void 0) {
+      const update_params = {};
+      if (options.status !== void 0) update_params.status = options.status;
+      if (options.result !== void 0) update_params.result = options.result;
+      if (options.error !== void 0) update_params.error = options.error;
+      event_result.update(update_params);
+      if (event_result.status === "started" && event_result.started_at !== null) {
+        original_event._markStarted(event_result.started_at, false);
+      }
+      if (options.status === "pending" || options.status === "started") {
+        original_event.event_completed_at = null;
+      }
+    }
+    return event_result;
+  }
+  _createPendingHandlerResults(bus) {
+    const original_event = this._event_original ?? this;
+    const scoped_event = bus._getEventProxyScopedToThisBus(original_event);
+    const handlers = bus._getHandlersForEvent(original_event);
+    return handlers.map((entry) => {
+      const handler_id = entry.id;
+      const existing = original_event.event_results.get(handler_id);
+      const result = existing ?? new EventResult({ event: scoped_event, handler: entry });
+      if (!existing) {
+        original_event.event_results.set(handler_id, result);
+      } else if (existing.event !== scoped_event) {
+        existing.event = scoped_event;
+      }
+      return { handler: entry, result };
+    });
+  }
+  _collectPendingResults(original, pending_entries) {
+    if (pending_entries) {
+      return pending_entries.map((entry) => entry.result);
+    }
+    if (!this.bus?.id) {
+      return Array.from(original.event_results.values());
+    }
+    return Array.from(original.event_results.values()).filter((result) => result.eventbus_id === this.bus.id);
+  }
+  _isFirstModeWinningResult(entry) {
+    return entry.status === "completed" && entry.result !== void 0 && entry.result !== null && !(entry.result instanceof BaseEvent);
+  }
+  _markFirstModeWinnerIfNeeded(original, entry, first_state) {
+    if (first_state.found || !this._isFirstModeWinningResult(entry)) {
+      return;
+    }
+    first_state.found = true;
+    original._markRemainingFirstModeResultCancelled(entry);
+  }
+  async _runHandlerWithLock(original, entry) {
+    if (!this.bus) {
+      throw new Error("event has no bus attached");
+    }
+    await this.bus.locks._runWithHandlerLock(original, this.bus.event_handler_concurrency, async (handler_lock) => {
+      await entry.runHandler(handler_lock);
+    });
+  }
+  // Run all pending handler results for the current bus context.
+  async _runHandlers(pending_entries) {
+    const original = this._event_original ?? this;
+    const pending_results = this._collectPendingResults(original, pending_entries);
+    if (pending_results.length === 0) {
+      return;
+    }
+    const resolved_completion = original.event_handler_completion ?? this.bus?.event_handler_completion ?? "all";
+    if (resolved_completion === "first") {
+      if (original._getHandlerLock(this.bus?.event_handler_concurrency) !== null) {
+        for (const entry of pending_results) {
+          await this._runHandlerWithLock(original, entry);
+          if (!this._isFirstModeWinningResult(entry)) {
+            continue;
+          }
+          original._markRemainingFirstModeResultCancelled(entry);
+          break;
+        }
+        return;
+      }
+      const first_state = { found: false };
+      const handler_promises = pending_results.map((entry) => this._runHandlerWithLock(original, entry));
+      const monitored = pending_results.map(
+        (entry, index) => handler_promises[index].then(() => {
+          this._markFirstModeWinnerIfNeeded(original, entry, first_state);
+        })
+      );
+      await Promise.all(monitored);
+      return;
+    } else {
+      const handler_promises = pending_results.map((entry) => this._runHandlerWithLock(original, entry));
+      await Promise.all(handler_promises);
+    }
+  }
+  _getHandlerLock(default_concurrency) {
+    const original = this._event_original ?? this;
+    const resolved = original.event_handler_concurrency ?? default_concurrency ?? original.bus?.event_handler_concurrency ?? "serial";
+    if (resolved === "parallel") {
+      return null;
+    }
+    if (!original._lock_for_event_handler) {
+      original._lock_for_event_handler = new AsyncLock(1);
+    }
+    return original._lock_for_event_handler;
+  }
+  _setHandlerLock(lock) {
+    const original = this._event_original ?? this;
+    original._lock_for_event_handler = lock;
+  }
+  _getDispatchContext() {
+    const original = this._event_original ?? this;
+    return original._event_dispatch_context;
+  }
+  _setDispatchContext(dispatch_context) {
+    const original = this._event_original ?? this;
+    original._event_dispatch_context = dispatch_context;
+  }
+  // Get parent event object from event_parent_id (checks across all buses)
+  get event_parent() {
+    const original = this._event_original ?? this;
+    const parent_id = original.event_parent_id;
+    if (!parent_id) {
+      return void 0;
+    }
+    return original.bus?.findEventById(parent_id) ?? void 0;
+  }
+  // get all direct children of this event
+  get event_children() {
+    const children = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const result of this.event_results.values()) {
+      for (const child of result.event_children) {
+        if (!seen.has(child.event_id)) {
+          seen.add(child.event_id);
+          children.push(child);
+        }
+      }
+    }
+    return children;
+  }
+  // get all children grandchildren etc. recursively
+  get event_descendants() {
+    const descendants = [];
+    const visited = /* @__PURE__ */ new Set();
+    const root_id = this.event_id;
+    const stack = [...this.event_children];
+    while (stack.length > 0) {
+      const child = stack.pop();
+      if (!child) {
+        continue;
+      }
+      const child_id = child.event_id;
+      if (child_id === root_id) {
+        continue;
+      }
+      if (visited.has(child_id)) {
+        continue;
+      }
+      visited.add(child_id);
+      descendants.push(child);
+      if (child.event_children.length > 0) {
+        stack.push(...child.event_children);
+      }
+    }
+    return descendants;
+  }
+  // force-abort processing of all pending descendants of an event regardless of whether they have already started
+  _cancelPendingChildProcessing(reason) {
+    const original = this._event_original ?? this;
+    const cancellation_cause = reason instanceof EventHandlerTimeoutError ? reason : reason instanceof EventHandlerCancelledError || reason instanceof EventHandlerAbortedError ? reason.cause instanceof Error ? reason.cause : reason : reason instanceof Error ? reason : new Error(String(reason));
+    const visited = /* @__PURE__ */ new Set();
+    const cancelChildEvent = (child) => {
+      const original_child = child._event_original ?? child;
+      if (visited.has(original_child.event_id)) {
+        return;
+      }
+      visited.add(original_child.event_id);
+      for (const grandchild of original_child.event_children) {
+        cancelChildEvent(grandchild);
+      }
+      original_child._markCancelled(cancellation_cause);
+      if (original_child.event_status !== "completed") {
+        original_child._markCompleted();
+      }
+    };
+    for (const child of original.event_children) {
+      cancelChildEvent(child);
+    }
+  }
+  // Cancel all handler results for an event except the winner, used by first() mode.
+  // Cancels pending handlers immediately, aborts started handlers via _signalAbort(),
+  // and cancels any child events emitted by the losing handlers.
+  _markRemainingFirstModeResultCancelled(winner) {
+    const cause = new Error("first() resolved: another handler returned a result first");
+    const bus_id = winner.eventbus_id;
+    for (const result of this.event_results.values()) {
+      if (result === winner) continue;
+      if (result.eventbus_id !== bus_id) continue;
+      if (result.status === "pending") {
+        result._markError(
+          new EventHandlerCancelledError(`Cancelled: first() resolved`, {
+            event_result: result,
+            cause
+          })
+        );
+      } else if (result.status === "started") {
+        for (const child of result.event_children) {
+          const original_child = child._event_original ?? child;
+          original_child._cancelPendingChildProcessing(cause);
+          original_child._markCancelled(cause);
+        }
+        result._lock?.exitHandlerRun();
+        const aborted_error = new EventHandlerAbortedError(`Aborted: first() resolved`, {
+          event_result: result,
+          cause
+        });
+        result._markError(aborted_error);
+        result._signalAbort(aborted_error);
+      }
+    }
+  }
+  // force-abort processing of this event regardless of whether it is pending or has already started
+  _markCancelled(cause) {
+    const original = this._event_original ?? this;
+    if (!this.bus) {
+      if (original.event_status !== "completed") {
+        original._markCompleted();
+      }
+      return;
+    }
+    const path = Array.isArray(original.event_path) ? original.event_path : [];
+    const buses_to_cancel = new Set(path);
+    for (const bus of this.bus.all_instances) {
+      if (!buses_to_cancel.has(bus.label)) {
+        continue;
+      }
+      const handler_entries = original._createPendingHandlerResults(bus);
+      let updated = false;
+      for (const entry of handler_entries) {
+        if (entry.result.status === "pending") {
+          const cancelled_error = new EventHandlerCancelledError(`Cancelled pending handler due to parent error: ${cause.message}`, {
+            event_result: entry.result,
+            cause
+          });
+          entry.result._markError(cancelled_error);
+          updated = true;
+        } else if (entry.result.status === "started") {
+          entry.result._lock?.exitHandlerRun();
+          const aborted_error = new EventHandlerAbortedError(`Aborted running handler due to parent error: ${cause.message}`, {
+            event_result: entry.result,
+            cause
+          });
+          entry.result._markError(aborted_error);
+          entry.result._signalAbort(aborted_error);
+          updated = true;
+        }
+      }
+      const removed = bus.removeEventFromPendingQueue(original);
+      if (removed > 0 && !bus.isEventInFlightOrQueued(original.event_id)) {
+        original.event_pending_bus_count = Math.max(0, original.event_pending_bus_count - 1);
+      }
+      if (updated || removed > 0) {
+        original._markCompleted(false);
+      }
+    }
+    if (original.event_status !== "completed") {
+      original._markCompleted();
+    }
+  }
+  _notifyEventParentsOfCompletion() {
+    const original = this._event_original ?? this;
+    if (!this.bus) {
+      return;
+    }
+    const visited = /* @__PURE__ */ new Set();
+    let parent_id = original.event_parent_id;
+    while (parent_id && !visited.has(parent_id)) {
+      visited.add(parent_id);
+      const parent = this.bus.findEventById(parent_id);
+      if (!parent) {
+        break;
+      }
+      parent._markCompleted(false, false);
+      if (parent.event_status !== "completed") {
+        break;
+      }
+      parent_id = parent.event_parent_id;
+    }
+  }
+  // awaitable that triggers immediate (queue-jump) processing of the event on all buses where it is queued
+  // use eventCompleted() to wait for normal queue-order completion without queue-jumping.
+  done() {
+    if (!this.bus) {
+      return Promise.reject(new Error("event has no bus attached"));
+    }
+    if (this.event_status === "completed") {
+      return Promise.resolve(this);
+    }
+    return this.bus._processEventImmediately(this);
+  }
+  // returns the first non-undefined handler result value, cancelling remaining handlers
+  // when any handler completes. Works with all event_handler_concurrency modes:
+  //   parallel: races all handlers, returns first non-undefined, aborts the rest
+  //   serial: runs handlers sequentially, returns first non-undefined, skips remaining
+  first() {
+    if (!this.bus) {
+      return Promise.reject(new Error("event has no bus attached"));
+    }
+    const original = this._event_original ?? this;
+    original.event_handler_completion = "first";
+    return this.done().then((completed_event) => {
+      const orig = completed_event._event_original ?? completed_event;
+      return Array.from(orig.event_results.values()).filter(
+        (result) => result.status === "completed" && result.result !== void 0 && result.result !== null && !(result.result instanceof BaseEvent)
+      ).sort((a, b) => compareIsoDatetime(a.completed_at, b.completed_at)).map((result) => result.result).at(0);
+    });
+  }
+  async eventResultsList(include_or_options, maybe_options) {
+    const default_include = (_result, event_result) => event_result.status === "completed" && event_result.result !== void 0 && event_result.result !== null && !(event_result.result instanceof Error) && !(event_result.result instanceof BaseEvent) && event_result.error === void 0;
+    let options;
+    let include;
+    if (typeof include_or_options === "function") {
+      options = maybe_options ?? {};
+      include = include_or_options;
+    } else {
+      options = include_or_options ?? {};
+      include = options.include ?? default_include;
+    }
+    const raise_if_any = options.raise_if_any ?? true;
+    const raise_if_none = options.raise_if_none ?? true;
+    const original = this._event_original ?? this;
+    const resolved_timeout_seconds = options.timeout ?? original.event_timeout ?? this.bus?.event_timeout ?? null;
+    let completed_event;
+    if (resolved_timeout_seconds === null) {
+      completed_event = await this.done();
+    } else {
+      completed_event = await _runWithTimeout(
+        resolved_timeout_seconds,
+        () => new Error(`Timed out waiting for ${original.event_type} results after ${resolved_timeout_seconds}s`),
+        () => this.done()
+      );
+    }
+    const all_results = Array.from(completed_event.event_results.values());
+    const error_results = all_results.filter((event_result) => event_result.error !== void 0 || event_result.result instanceof Error);
+    if (raise_if_any && error_results.length > 0) {
+      if (error_results.length === 1) {
+        const first_error = error_results[0];
+        if (first_error.error instanceof Error) {
+          throw first_error.error;
+        }
+        if (first_error.result instanceof Error) {
+          throw first_error.result;
+        }
+        throw new Error(String(first_error.error ?? first_error.result));
+      }
+      const errors = error_results.map((event_result) => {
+        if (event_result.error instanceof Error) {
+          return event_result.error;
+        }
+        if (event_result.result instanceof Error) {
+          return event_result.result;
+        }
+        return new Error(String(event_result.error ?? event_result.result));
+      });
+      throw new AggregateError(
+        errors,
+        `Event ${completed_event.event_type}#${completed_event.event_id.slice(-4)} had ${errors.length} handler error(s)`
+      );
+    }
+    const included_results = all_results.filter((event_result) => include(event_result.result, event_result));
+    if (raise_if_none && included_results.length === 0) {
+      throw new Error(
+        `Expected at least one handler to return a non-null result, but none did: ${completed_event.event_type}#${completed_event.event_id.slice(-4)}`
+      );
+    }
+    return included_results.map((event_result) => event_result.result);
+  }
+  // awaitable that waits for the event to be processed in normal queue order by the _runloop
+  eventCompleted() {
+    if (this.event_status === "completed") {
+      return Promise.resolve(this);
+    }
+    this._notifyDoneListeners();
+    return this._event_completed_signal.promise;
+  }
+  _markPending() {
+    const original = this._event_original ?? this;
+    original.event_status = "pending";
+    original.event_started_at = null;
+    original.event_completed_at = null;
+    original.event_results.clear();
+    original.event_pending_bus_count = 0;
+    original._setDispatchContext(void 0);
+    original._event_completed_signal = null;
+    original._lock_for_event_handler = null;
+    original.bus = void 0;
+    return this;
+  }
+  eventReset() {
+    const original = this._event_original ?? this;
+    const ctor = original.constructor;
+    const fresh_event = ctor.fromJSON(original.toJSON());
+    fresh_event.event_id = uuidv7();
+    return fresh_event._markPending();
+  }
+  _markStarted(started_at = null, notify_hook = true) {
+    const original = this._event_original ?? this;
+    if (original.event_status !== "pending") {
+      return;
+    }
+    original.event_status = "started";
+    original.event_started_at = started_at === null ? monotonicDatetime() : monotonicDatetime(started_at);
+    if (notify_hook && original.bus) {
+      const bus_for_hook = original.bus;
+      const event_for_bus = bus_for_hook._getEventProxyScopedToThisBus(original);
+      void bus_for_hook.onEventChange(event_for_bus, "started");
+    }
+  }
+  _markCompleted(force = true, notify_parents = true) {
+    const original = this._event_original ?? this;
+    if (original.event_status === "completed") {
+      return;
+    }
+    if (!force) {
+      if (original.event_pending_bus_count > 0) {
+        return;
+      }
+      if (!original._areAllChildrenComplete()) {
+        return;
+      }
+    }
+    original.event_status = "completed";
+    original.event_completed_at = monotonicDatetime();
+    if (original.bus) {
+      const bus_for_hook = original.bus;
+      const event_for_bus = bus_for_hook._getEventProxyScopedToThisBus(original);
+      void bus_for_hook.onEventChange(event_for_bus, "completed");
+    }
+    original._setDispatchContext(null);
+    original._notifyDoneListeners();
+    original._event_completed_signal.resolve(original);
+    original._event_completed_signal = null;
+    original.dropFromZeroHistoryBuses();
+    if (notify_parents && original.bus) {
+      original._notifyEventParentsOfCompletion();
+    }
+  }
+  dropFromZeroHistoryBuses() {
+    if (!this.bus) {
+      return;
+    }
+    const original = this._event_original ?? this;
+    for (const bus of this.bus.all_instances) {
+      if (bus.event_history.max_history_size !== 0) {
+        continue;
+      }
+      bus.removeEventFromHistory(original.event_id);
+    }
+  }
+  get event_errors() {
+    return Array.from(this.event_results.values()).filter((event_result) => event_result.error !== void 0 && event_result.completed_at !== null).sort((event_result_a, event_result_b) => compareIsoDatetime(event_result_a.completed_at, event_result_b.completed_at)).map((event_result) => event_result.error);
+  }
+  // Returns the first non-undefined completed handler result, sorted by completion time.
+  // Useful after first() or done() to get the winning result value.
+  get event_result() {
+    return Array.from(this.event_results.values()).filter((event_result) => event_result.completed_at !== null && event_result.result !== void 0).sort((event_result_a, event_result_b) => compareIsoDatetime(event_result_a.completed_at, event_result_b.completed_at)).map((event_result) => event_result.result).at(0);
+  }
+  _areAllChildrenComplete() {
+    return this.event_descendants.every((descendant) => descendant.event_status === "completed");
+  }
+  _notifyDoneListeners() {
+    if (this._event_completed_signal) {
+      return;
+    }
+    this._event_completed_signal = withResolvers();
+  }
+  // Break internal reference chains so a completed event can be GC'd when
+  // Evicted from event_history. Called by EventHistory.trimEventHistory().
+  _gc() {
+    this._event_completed_signal = null;
+    this._setDispatchContext(null);
+    this.bus = void 0;
+    this._lock_for_event_handler = null;
+    for (const result of this.event_results.values()) {
+      result.event_children = [];
+    }
+    this.event_results.clear();
+  }
+}
+const hydrateEventResults = (event, raw_event_results) => {
+  const event_results = /* @__PURE__ */ new Map();
+  if (!Array.isArray(raw_event_results)) {
+    return event_results;
+  }
+  for (const item of raw_event_results) {
+    const result = EventResult.fromJSON(event, item);
+    const map_key = typeof result.handler_id === "string" && result.handler_id.length > 0 ? result.handler_id : result.id;
+    event_results.set(map_key, result);
+  }
+  return event_results;
+};
+export {
+  BaseEvent,
+  BaseEventSchema
+};
+//# sourceMappingURL=base_event.js.map