abxbus 2.4.32 → 2.5.0

package/dist/esm/BaseEvent.js

@@ -10,9 +10,20 @@ import {
   withResolvers
 } from "./LockManager.js";
 import { _runWithTimeout } from "./timing.js";
-import { extractZodShape, normalizeEventResultType, toJsonSchema } from "./types.js";
+import { isZodSchema, normalizeEventResultType, toJsonSchema } from "./types.js";
 import { monotonicDatetime } from "./helpers.js";
-const RESERVED_USER_EVENT_FIELDS = /* @__PURE__ */ new Set(["bus", "emit", "first", "toString", "toJSON", "fromJSON"]);
+const RESERVED_USER_EVENT_FIELDS = /* @__PURE__ */ new Set([
+  "bus",
+  "emit",
+  "wait",
+  "now",
+  "eventResult",
+  "eventResultsList",
+  "toString",
+  "toJSON",
+  "fromJSON"
+]);
+const EVENT_TYPE_REGISTRY = /* @__PURE__ */ new Map();
 function assertNoReservedUserEventFields(data, context) {
   for (const field_name of RESERVED_USER_EVENT_FIELDS) {
     if (Object.prototype.hasOwnProperty.call(data, field_name)) {
@@ -34,6 +45,12 @@ function assertNoModelPrefixedFields(data, context) {
     }
   }
 }
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isZodObjectSchema(value) {
+  return isZodSchema(value) && typeof value.safeExtend === "function" && isRecord(value.shape);
+}
 function compareIsoDatetime(left, right) {
   const left_value = left ?? "";
   const right_value = right ?? "";
@@ -47,10 +64,10 @@ const BaseEventSchema = z.object({
   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_timeout: z.number().nonnegative().nullable(),
+  event_slow_timeout: z.number().nonnegative().nullable().optional(),
+  event_handler_timeout: z.number().nonnegative().nullable().optional(),
+  event_handler_slow_timeout: z.number().nonnegative().nullable().optional(),
   event_blocks_parent_completion: z.boolean().optional(),
   event_parent_id: z.string().uuid().nullable().optional(),
   event_path: z.array(z.string()).optional(),
@@ -66,8 +83,110 @@ const BaseEventSchema = z.object({
   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";
+function baseEventDefaultShape(event_type) {
+  return {
+    event_id: z.string().uuid(),
+    event_created_at: z.string().datetime(),
+    event_type: z.string().default(event_type),
+    event_version: z.string().default("0.0.1"),
+    event_timeout: z.number().nonnegative().nullable().default(null),
+    event_slow_timeout: z.number().nonnegative().nullable().optional(),
+    event_handler_timeout: z.number().nonnegative().nullable().optional(),
+    event_handler_slow_timeout: z.number().nonnegative().nullable().optional(),
+    event_blocks_parent_completion: z.boolean().default(false),
+    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.record(z.string(), 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()
+  };
+}
+function missingBaseFields(event_type, user_shape) {
+  return Object.fromEntries(Object.entries(baseEventDefaultShape(event_type)).filter(([key]) => !(key in user_shape)));
+}
+function shortcutDefaultSchema(base_field_schema, value) {
+  if (!base_field_schema) {
+    return z.unknown().optional().default(value);
+  }
+  return base_field_schema.prefault(base_field_schema.parse(value));
+}
+function schemaDefaultsForShortcut(event_type, raw_shape) {
+  const defaults = {};
+  const base_shape = baseEventDefaultShape(event_type);
+  for (const [key, value] of Object.entries(raw_shape)) {
+    if (key === "event_result_type") continue;
+    if (!isZodSchema(value)) {
+      defaults[key] = shortcutDefaultSchema(base_shape[key], value);
+    }
+  }
+  return defaults;
+}
+function zodFieldsForShortcut(raw_shape) {
+  const fields = {};
+  for (const [key, value] of Object.entries(raw_shape)) {
+    if (key === "event_result_type") continue;
+    if (isZodSchema(value)) {
+      fields[key] = value;
+    }
+  }
+  return fields;
+}
+function eventResultTypeFromObjectSchema(schema) {
+  const raw_event_result_type = schema.shape.event_result_type;
+  return raw_event_result_type === void 0 ? void 0 : normalizeEventResultType(raw_event_result_type);
+}
+function buildFullEventSchema(event_type, spec) {
+  if (isZodObjectSchema(spec)) {
+    const user_shape = spec.shape;
+    assertNoReservedUserEventFields(user_shape, `BaseEvent.extend(${event_type})`);
+    assertNoUnknownEventPrefixedFields(user_shape, `BaseEvent.extend(${event_type})`);
+    assertNoModelPrefixedFields(user_shape, `BaseEvent.extend(${event_type})`);
+    const full_schema2 = spec.safeExtend({
+      event_result_type: z.unknown().optional(),
+      ...missingBaseFields(event_type, user_shape)
+    });
+    return {
+      event_schema: full_schema2,
+      event_result_type: eventResultTypeFromObjectSchema(spec)
+    };
+  }
+  const raw_shape = isRecord(spec) ? spec : {};
+  assertNoReservedUserEventFields(raw_shape, `BaseEvent.extend(${event_type})`);
+  assertNoUnknownEventPrefixedFields(raw_shape, `BaseEvent.extend(${event_type})`);
+  assertNoModelPrefixedFields(raw_shape, `BaseEvent.extend(${event_type})`);
+  const shortcut_shape = {
+    ...schemaDefaultsForShortcut(event_type, raw_shape),
+    ...zodFieldsForShortcut(raw_shape)
+  };
+  const full_schema = z.object(shortcut_shape).safeExtend(missingBaseFields(event_type, shortcut_shape)).loose();
+  return {
+    event_schema: full_schema,
+    event_result_type: normalizeEventResultType(raw_shape.event_result_type),
+    event_version: typeof raw_shape.event_version === "string" ? raw_shape.event_version : void 0
+  };
+}
+function decodeEventSchema(schema, input) {
+  const decoded = z.decode(schema, input);
+  if (!isRecord(decoded)) {
+    throw new Error("BaseEvent schema must decode to an object");
+  }
+  return decoded;
+}
+function encodeEventSchema(schema, input) {
+  const encoded = z.encode(schema, input);
+  if (!isRecord(encoded)) {
+    throw new Error("BaseEvent schema must encode to an object");
+  }
+  return encoded;
+}
 class BaseEvent {
   // event metadata fields
   event_id;
@@ -86,7 +205,7 @@ class BaseEvent {
   event_handler_slow_timeout;
   // optional per-event slow handler warning threshold in seconds
   event_blocks_parent_completion;
-  // true only for children explicitly awaited via done()/eventCompleted()
+  // true only for children explicitly awaited via now()
   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;
@@ -109,11 +228,13 @@ class BaseEvent {
   // 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
+  event_schema;
   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
+  static event_result_type;
+  static event_schema = BaseEventSchema;
+  // generated Zod schema for local TS event data validation; never sent over the wire
   // internal runtime state
   event_bus;
   // bus that dispatched this event, also used by event.emit(child)
@@ -121,6 +242,7 @@ class BaseEvent {
   // 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_fields_set;
   _event_completed_signal;
   _lock_for_event_handler;
   constructor(data = {}) {
@@ -128,34 +250,42 @@ class 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 explicit_event_fields = new Set(Object.keys(data ?? {}));
+    const merged_data = { ...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 event_blocks_parent_completion = merged_data.event_blocks_parent_completion ?? false;
+    const event_schema = ctor.event_schema ?? BaseEventSchema;
     const base_data = {
       ...merged_data,
-      event_id,
-      event_created_at,
+      event_id: merged_data.event_id ?? uuidv7(),
+      event_created_at: merged_data.event_created_at ?? monotonicDatetime(),
       event_type,
       event_version,
-      event_timeout,
-      event_blocks_parent_completion,
       event_result_type
     };
-    const schema = ctor.schema ?? BaseEventSchema;
-    const parsed = schema.parse(base_data);
+    if (event_schema === BaseEventSchema) {
+      base_data.event_timeout ??= null;
+      base_data.event_blocks_parent_completion ??= false;
+    }
+    const parsed = decodeEventSchema(event_schema, base_data);
     Object.assign(this, parsed);
+    Object.defineProperty(this, "event_schema", {
+      value: event_schema,
+      writable: true,
+      enumerable: false,
+      configurable: true
+    });
+    Object.defineProperty(this, "_event_fields_set", {
+      value: explicit_event_fields,
+      writable: true,
+      enumerable: false,
+      configurable: true
+    });
     const parsed_path = parsed.event_path;
     this.event_path = Array.isArray(parsed_path) ? [...parsed_path] : [];
+    this.event_created_at = monotonicDatetime(parsed.event_created_at);
     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;
@@ -164,7 +294,7 @@ class BaseEvent {
     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_result_type = normalizeEventResultType(parsed.event_result_type ?? event_result_type);
     this._event_completed_signal = null;
     this._lock_for_event_handler = null;
     this._event_dispatch_context = void 0;
@@ -173,23 +303,13 @@ class BaseEvent {
   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);
+  static extend(event_type, shape) {
+    const built = buildFullEventSchema(event_type, shape ?? {});
+    const full_schema = built.event_schema;
+    const event_result_type = built.event_result_type;
+    const event_version = built.event_version;
     class ExtendedEvent extends BaseEvent {
-      static schema = full_schema;
+      static event_schema = full_schema;
       static event_type = event_type;
       static event_version = event_version ?? BaseEvent.event_version;
       static event_result_type = event_result_type;
@@ -200,23 +320,36 @@ class BaseEvent {
     function EventFactory(data) {
       return new ExtendedEvent(data);
     }
-    EventFactory.schema = full_schema;
+    EventFactory.event_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);
+    EVENT_TYPE_REGISTRY.set(event_type, ExtendedEvent);
     return EventFactory;
   }
   static fromJSON(data) {
     if (!data || typeof data !== "object") {
-      const schema = this.schema ?? BaseEventSchema;
-      const parsed = schema.parse(data);
+      const event_schema = this.event_schema ?? BaseEventSchema;
+      const parsed = decodeEventSchema(event_schema, data);
       return new this(parsed);
     }
     const record = { ...data };
+    if (this === BaseEvent) {
+      const event_type = record.event_type;
+      if (typeof event_type === "string") {
+        const KnownEvent = EVENT_TYPE_REGISTRY.get(event_type);
+        if (KnownEvent) {
+          return KnownEvent.fromJSON(record);
+        }
+      }
+    }
+    const ctor = this;
+    if (this !== BaseEvent && ctor.event_result_type && record.event_result_type !== void 0) {
+      delete record.event_result_type;
+    }
     if (record.event_result_type !== void 0 && record.event_result_type !== null) {
       record.event_result_type = normalizeEventResultType(record.event_result_type);
     }
@@ -237,18 +370,47 @@ class BaseEvent {
   toJSON() {
     const record = {};
     for (const [key, value] of Object.entries(this)) {
-      if (key.startsWith("_") || key === "bus" || key === "event_bus" || key === "event_results") continue;
+      if (key.startsWith("_") || key === "bus" || key === "event_bus" || key === "event_schema" || key === "event_results") continue;
       if (value === void 0 || typeof value === "function") continue;
       record[key] = value;
     }
     const event_results = Object.fromEntries(
       Array.from(this.event_results.entries()).map(([handler_id, result]) => [handler_id, result.toJSON()])
     );
-    return {
+    const event_schema = this.constructor.event_schema ?? this.event_schema ?? BaseEventSchema;
+    const encoded = encodeEventSchema(event_schema, {
       ...record,
       event_id: this.event_id,
       event_type: this.event_type,
       event_version: this.event_version,
+      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,
+      event_blocks_parent_completion: this.event_blocks_parent_completion,
+      // 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,
+      ...Object.keys(event_results).length > 0 ? { event_results } : {}
+    });
+    delete encoded.event_schema;
+    return {
+      ...encoded,
+      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,
@@ -273,13 +435,12 @@ class BaseEvent {
       ...Object.keys(event_results).length > 0 ? { event_results } : {}
     };
   }
-  _createSlowEventWarningTimer() {
-    const event_slow_timeout = this.event_slow_timeout ?? this.event_bus?.event_slow_timeout ?? null;
-    const event_warn_ms = event_slow_timeout === null ? null : event_slow_timeout * 1e3;
+  _createSlowEventWarningTimer(event_slow_timeout = this.event_slow_timeout ?? null, bus_name) {
+    const event_warn_ms = event_slow_timeout === null || event_slow_timeout <= 0 ? null : event_slow_timeout * 1e3;
     if (event_warn_ms === null) {
       return null;
     }
-    const name = this.event_bus?.name ?? "EventBus";
+    const name = bus_name ?? this.event_bus?.name ?? "EventBus";
     return setTimeout(() => {
       if (this.event_status === "completed") {
         return;
@@ -365,7 +526,13 @@ class BaseEvent {
     return Array.from(original.event_results.values()).filter((result) => result.eventbus_id === this.event_bus.id);
   }
   _isFirstModeWinningResult(entry) {
-    return entry.status === "completed" && entry.result !== void 0 && entry.result !== null && !(entry.result instanceof BaseEvent);
+    return BaseEvent._defaultResultInclude(entry.result, entry);
+  }
+  static _defaultResultInclude(result, event_result) {
+    return event_result.status === "completed" && result !== void 0 && result !== null && !(result instanceof Error) && !(result instanceof BaseEvent) && event_result.error === void 0;
+  }
+  static _includeEventResult(include, event_result) {
+    return include(event_result.result, event_result);
   }
   _markFirstModeWinnerIfNeeded(original, entry, first_state) {
     if (first_state.found || !this._isFirstModeWinningResult(entry)) {
@@ -378,9 +545,13 @@ class BaseEvent {
     if (!this.event_bus) {
       throw new Error("event has no bus attached");
     }
-    await this.event_bus.locks._runWithHandlerLock(original, this.event_bus.event_handler_concurrency, async (handler_lock) => {
-      await entry.runHandler(handler_lock);
-    });
+    await this.event_bus.locks._runWithHandlerLock(
+      original,
+      original.event_handler_concurrency ?? this.event_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) {
@@ -391,7 +562,7 @@ class BaseEvent {
     }
     const resolved_completion = original.event_handler_completion ?? this.event_bus?.event_handler_completion ?? "all";
     if (resolved_completion === "first") {
-      if (original._getHandlerLock(this.event_bus?.event_handler_concurrency) !== null) {
+      if (original._getHandlerLock(original.event_handler_concurrency ?? this.event_bus?.event_handler_concurrency ?? "serial") !== null) {
         for (const entry of pending_results) {
           await this._runHandlerWithLock(original, entry);
           if (!this._isFirstModeWinningResult(entry)) {
@@ -418,7 +589,7 @@ class BaseEvent {
   }
   _getHandlerLock(default_concurrency) {
     const original = this._event_original ?? this;
-    const resolved = original.event_handler_concurrency ?? default_concurrency ?? original.event_bus?.event_handler_concurrency ?? "serial";
+    const resolved = original.event_handler_concurrency ?? default_concurrency ?? "serial";
     if (resolved === "parallel") {
       return null;
     }
@@ -530,18 +701,18 @@ class BaseEvent {
       cancelChildEvent(child);
     }
   }
-  // Cancel all handler results for an event except the winner, used by first() mode.
+  // Cancel all handler results for an event except the winner, used by event_handler_completion='first'.
   // 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 cause = new Error("event_handler_completion='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`, {
+          new EventHandlerCancelledError(`Cancelled: event_handler_completion='first' resolved`, {
             event_result: result,
             cause
           })
@@ -556,7 +727,7 @@ class BaseEvent {
           original_child._markCancelled(cause);
         }
         result._lock?.exitHandlerRun();
-        const aborted_error = new EventHandlerAbortedError(`Aborted: first() resolved`, {
+        const aborted_error = new EventHandlerAbortedError(`Aborted: event_handler_completion='first' resolved`, {
           event_result: result,
           cause
         });
@@ -633,92 +804,41 @@ class BaseEvent {
       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(options = {}) {
-    if (!this.event_bus) {
-      return Promise.reject(new Error("event has no bus attached"));
-    }
+  _withEventResultMethods(promise) {
+    const chainable = promise;
+    chainable.eventResult = async (options) => {
+      const event = await promise;
+      return event.eventResult(options);
+    };
+    chainable.eventResultsList = async (options) => {
+      const event = await promise;
+      return event.eventResultsList(options);
+    };
+    return chainable;
+  }
+  _timeoutPromise(timeout, message, fn) {
+    return timeout === null || timeout <= 0 ? fn() : _runWithTimeout(timeout, () => new Error(message()), fn);
+  }
+  _orderedEventResults() {
     const original = this._event_original ?? this;
-    original._markBlocksParentCompletionIfAwaitedFromEmittingHandler();
-    const raise_if_any = options.raise_if_any ?? true;
-    const completion_promise = this.event_status === "completed" ? Promise.resolve(original) : this.event_bus._processEventImmediately(this);
-    if (!raise_if_any) {
-      return completion_promise;
-    }
-    return completion_promise.then((completed_event) => {
-      const first_error = completed_event._firstProcessingError();
-      if (first_error !== void 0) {
-        if (first_error instanceof Error) {
-          throw first_error;
-        }
-        throw new Error(String(first_error));
-      }
-      return completed_event;
-    });
+    return Array.from(original.event_results.values()).sort(
+      (a, b) => compareIsoDatetime(a.completed_at, b.completed_at)
+    );
   }
-  // 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.event_bus) {
-      return Promise.reject(new Error("event has no bus attached"));
-    }
+  _orderedEventResultsByRegistration() {
     const original = this._event_original ?? this;
-    original.event_handler_completion = "first";
-    return this.done({ raise_if_any: false }).then((completed_event) => {
-      const first_error = completed_event._firstProcessingError({ ignore_first_mode_control_errors: true });
-      if (first_error !== void 0) {
-        if (first_error instanceof Error) {
-          throw first_error;
-        }
-        throw new Error(String(first_error));
-      }
-      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);
-    });
+    return Array.from(original.event_results.values()).sort(
+      (a, b) => compareIsoDatetime(a.handler.handler_registered_at, b.handler.handler_registered_at) || compareIsoDatetime(a.started_at, b.started_at) || a.handler_id.localeCompare(b.handler_id)
+    );
   }
-  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;
-    }
+  _collectResultValues(options = {}, order = "completion") {
+    const include = options.include ?? BaseEvent._defaultResultInclude;
     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.event_bus?.event_timeout ?? null;
-    let completed_event;
-    if (resolved_timeout_seconds === null) {
-      completed_event = await this.done({ raise_if_any: false });
-    } 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({ raise_if_any: false })
-      );
-    }
-    const all_results = Array.from(completed_event.event_results.values());
+    const raise_if_none = options.raise_if_none ?? false;
+    const all_results = order === "registration" ? this._orderedEventResultsByRegistration() : this._orderedEventResults();
     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 included_results = all_results.filter((event_result) => BaseEvent._includeEventResult(include, event_result));
+    if (error_results.length > 0 && raise_if_any) {
       const errors = error_results.map((event_result) => {
         if (event_result.error instanceof Error) {
           return event_result.error;
@@ -728,28 +848,104 @@ class BaseEvent {
         }
         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)`
-      );
+      if (errors.length === 1) {
+        throw errors[0];
+      }
+      throw new AggregateError(errors, `Event ${this.event_type}#${this.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)}`
+        `Expected at least one handler to return a non-null result, but none did: ${this.event_type}#${this.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() {
+  _hasIncludedResult(options = {}) {
+    const include = options.include ?? BaseEvent._defaultResultInclude;
+    return this._orderedEventResults().some((event_result) => BaseEvent._includeEventResult(include, event_result));
+  }
+  async _waitForFirstResultOrCompletion(options = {}) {
     const original = this._event_original ?? this;
+    if (options.timeout !== void 0 && options.timeout !== null && options.timeout < 0) {
+      throw new Error("timeout must be >= 0 or null");
+    }
+    if (!this.event_bus && original.event_status !== "completed") {
+      throw new Error("event has no bus attached");
+    }
+    if (original.event_status === "completed" || this._hasIncludedResult(options)) {
+      return this;
+    }
+    const waitForResult = async () => {
+      for (; ; ) {
+        if (original.event_status === "completed" || this._hasIncludedResult(options)) {
+          return this;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1));
+      }
+    };
+    const timeout = options.timeout ?? null;
+    return this._timeoutPromise(timeout, () => `Timed out waiting for ${original.event_type} result after ${timeout}s`, waitForResult);
+  }
+  // Active awaitable that triggers immediate (queue-jump) processing of the event on all buses where it is queued.
+  now(options = {}) {
+    const original = this._event_original ?? this;
+    if (options.timeout !== void 0 && options.timeout !== null && options.timeout < 0) {
+      return this._withEventResultMethods(Promise.reject(new Error("timeout must be >= 0 or null")));
+    }
+    if (!this.event_bus && original.event_status !== "completed") {
+      return this._withEventResultMethods(Promise.reject(new Error("event has no bus attached")));
+    }
     original._markBlocksParentCompletionIfAwaitedFromEmittingHandler();
-    if (this.event_status === "completed") {
-      return Promise.resolve(this);
+    const resolved_timeout_seconds = options.timeout ?? null;
+    const processing = original.event_status === "completed" ? Promise.resolve(this) : this._timeoutPromise(
+      resolved_timeout_seconds,
+      () => `Timed out waiting for ${original.event_type} completion after ${resolved_timeout_seconds}s`,
+      () => this.event_bus._processEventImmediately(this)
+    );
+    if (options.first_result) {
+      void processing.catch(() => void 0);
+      return this._withEventResultMethods(this._waitForFirstResultOrCompletion(options));
+    }
+    return this._withEventResultMethods(processing);
+  }
+  // Passive awaitable that waits for normal queue-order processing without forcing execution.
+  wait(options = {}) {
+    const original = this._event_original ?? this;
+    if (options.timeout !== void 0 && options.timeout !== null && options.timeout < 0) {
+      return this._withEventResultMethods(Promise.reject(new Error("timeout must be >= 0 or null")));
+    }
+    if (!this.event_bus && original.event_status !== "completed") {
+      return this._withEventResultMethods(Promise.reject(new Error("event has no bus attached")));
+    }
+    if (options.first_result) {
+      return this._withEventResultMethods(this._waitForFirstResultOrCompletion(options));
+    }
+    if (original.event_status === "completed") {
+      return this._withEventResultMethods(Promise.resolve(this));
     }
     this._notifyDoneListeners();
-    return this._event_completed_signal.promise;
+    const timeout = options.timeout ?? null;
+    return this._withEventResultMethods(
+      this._timeoutPromise(
+        timeout,
+        () => `Timed out waiting for ${original.event_type} completion after ${timeout}s`,
+        () => this._event_completed_signal.promise.then(() => this)
+      )
+    );
+  }
+  async eventResult(options = {}) {
+    const original = this._event_original ?? this;
+    if (original.event_status === "pending" && original.event_results.size === 0) {
+      await this.now({ first_result: true });
+    }
+    return this._collectResultValues(options, "registration").at(0);
+  }
+  async eventResultsList(options = {}) {
+    const original = this._event_original ?? this;
+    if (original.event_status === "pending" && original.event_results.size === 0) {
+      await this.now({ first_result: false });
+    }
+    return this._collectResultValues(options, "registration");
   }
   _markBlocksParentCompletionIfAwaitedFromEmittingHandler() {
     const original = this._event_original ?? this;
@@ -843,23 +1039,8 @@ class BaseEvent {
   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);
   }
-  _isFirstModeControlError(error) {
-    if (!(error instanceof EventHandlerCancelledError || error instanceof EventHandlerAbortedError)) {
-      return false;
-    }
-    if (error.message.includes("first() resolved")) {
-      return true;
-    }
-    return error.cause instanceof Error && error.cause.message.includes("first() resolved");
-  }
-  _firstProcessingError(options = {}) {
-    const ignore_first_mode_control_errors = options.ignore_first_mode_control_errors ?? false;
-    return Array.from(this.event_results.values()).filter((event_result) => event_result.error !== void 0 && event_result.completed_at !== null).filter((event_result) => ignore_first_mode_control_errors ? !this._isFirstModeControlError(event_result.error) : true).sort((event_result_a, event_result_b) => compareIsoDatetime(event_result_a.completed_at, event_result_b.completed_at)).map((event_result) => event_result.error).at(0);
-  }
-  // 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);
+  _firstProcessingError() {
+    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).at(0);
   }
   _areAllChildrenComplete(visited = /* @__PURE__ */ new Set()) {
     const original = this._event_original ?? this;