abxbus 2.4.1 → 2.4.15

package/dist/esm/base_event.js

@@ -12,7 +12,7 @@ import {
 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"]);
+const RESERVED_USER_EVENT_FIELDS = /* @__PURE__ */ new Set(["bus", "emit", "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)) {
@@ -51,6 +51,7 @@ const BaseEventSchema = z.object({
   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_blocks_parent_completion: z.boolean().optional(),
   event_parent_id: z.string().uuid().nullable().optional(),
   event_path: z.array(z.string()).optional(),
   event_result_type: z.unknown().optional(),
@@ -84,6 +85,8 @@ class BaseEvent {
   // optional per-event handler timeout override in seconds
   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()
   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;
@@ -112,17 +115,14 @@ class BaseEvent {
   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_bus;
+  // bus that dispatched this event, also used by event.emit(child)
   _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");
@@ -140,6 +140,7 @@ class BaseEvent {
     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 base_data = {
       ...merged_data,
       event_id,
@@ -147,6 +148,7 @@ class BaseEvent {
       event_type,
       event_version,
       event_timeout,
+      event_blocks_parent_completion,
       event_result_type
     };
     const schema = ctor.schema ?? BaseEventSchema;
@@ -235,7 +237,7 @@ class BaseEvent {
   toJSON() {
     const record = {};
     for (const [key, value] of Object.entries(this)) {
-      if (key.startsWith("_") || key === "bus" || key === "event_results") continue;
+      if (key.startsWith("_") || key === "bus" || key === "event_bus" || key === "event_results") continue;
       if (value === void 0 || typeof value === "function") continue;
       record[key] = value;
     }
@@ -254,6 +256,7 @@ class BaseEvent {
       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,
@@ -269,12 +272,12 @@ class BaseEvent {
     };
   }
   _createSlowEventWarningTimer() {
-    const event_slow_timeout = this.event_slow_timeout ?? this.bus?.event_slow_timeout ?? null;
+    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;
     if (event_warn_ms === null) {
       return null;
     }
-    const name = this.bus?.name ?? "EventBus";
+    const name = this.event_bus?.name ?? "EventBus";
     return setTimeout(() => {
       if (this.event_status === "completed") {
         return;
@@ -294,8 +297,8 @@ class BaseEvent {
     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);
+      if (!resolved_eventbus && handler_entry.eventbus_id !== ROOT_EVENTBUS_ID && original_event.event_bus) {
+        resolved_eventbus = original_event.event_bus.all_instances.findBusById(handler_entry.eventbus_id) ?? (original_event.event_bus.id === handler_entry.eventbus_id ? original_event.event_bus : void 0);
       }
     } else {
       handler_entry = EventHandler.fromCallable({
@@ -354,10 +357,10 @@ class BaseEvent {
     if (pending_entries) {
       return pending_entries.map((entry) => entry.result);
     }
-    if (!this.bus?.id) {
+    if (!this.event_bus?.id) {
       return Array.from(original.event_results.values());
     }
-    return Array.from(original.event_results.values()).filter((result) => result.eventbus_id === this.bus.id);
+    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);
@@ -370,10 +373,10 @@ class BaseEvent {
     original._markRemainingFirstModeResultCancelled(entry);
   }
   async _runHandlerWithLock(original, entry) {
-    if (!this.bus) {
+    if (!this.event_bus) {
       throw new Error("event has no bus attached");
     }
-    await this.bus.locks._runWithHandlerLock(original, this.bus.event_handler_concurrency, async (handler_lock) => {
+    await this.event_bus.locks._runWithHandlerLock(original, this.event_bus.event_handler_concurrency, async (handler_lock) => {
       await entry.runHandler(handler_lock);
     });
   }
@@ -384,9 +387,9 @@ class BaseEvent {
     if (pending_results.length === 0) {
       return;
     }
-    const resolved_completion = original.event_handler_completion ?? this.bus?.event_handler_completion ?? "all";
+    const resolved_completion = original.event_handler_completion ?? this.event_bus?.event_handler_completion ?? "all";
     if (resolved_completion === "first") {
-      if (original._getHandlerLock(this.bus?.event_handler_concurrency) !== null) {
+      if (original._getHandlerLock(this.event_bus?.event_handler_concurrency) !== null) {
         for (const entry of pending_results) {
           await this._runHandlerWithLock(original, entry);
           if (!this._isFirstModeWinningResult(entry)) {
@@ -413,7 +416,7 @@ class BaseEvent {
   }
   _getHandlerLock(default_concurrency) {
     const original = this._event_original ?? this;
-    const resolved = original.event_handler_concurrency ?? default_concurrency ?? original.bus?.event_handler_concurrency ?? "serial";
+    const resolved = original.event_handler_concurrency ?? default_concurrency ?? original.event_bus?.event_handler_concurrency ?? "serial";
     if (resolved === "parallel") {
       return null;
     }
@@ -441,7 +444,7 @@ class BaseEvent {
     if (!parent_id) {
       return void 0;
     }
-    return original.bus?.findEventById(parent_id) ?? void 0;
+    return original.event_bus?.findEventById(parent_id) ?? void 0;
   }
   // get all direct children of this event
   get event_children() {
@@ -483,6 +486,17 @@ class BaseEvent {
     }
     return descendants;
   }
+  emit(event) {
+    const original_parent = this._event_original ?? this;
+    const original_child = event._event_original ?? event;
+    if (!original_child.event_parent_id && original_child.event_id !== original_parent.event_id) {
+      original_child.event_parent_id = original_parent.event_id;
+    }
+    if (!this.event_bus) {
+      throw new Error("event has no bus attached");
+    }
+    return this.event_bus.emit(original_child);
+  }
   // 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;
@@ -495,6 +509,10 @@ class BaseEvent {
       }
       visited.add(original_child.event_id);
       for (const grandchild of original_child.event_children) {
+        const original_grandchild = grandchild._event_original ?? grandchild;
+        if (!original_grandchild.event_blocks_parent_completion) {
+          continue;
+        }
         cancelChildEvent(grandchild);
       }
       original_child._markCancelled(cancellation_cause);
@@ -503,6 +521,10 @@ class BaseEvent {
       }
     };
     for (const child of original.event_children) {
+      const original_child = child._event_original ?? child;
+      if (!original_child.event_blocks_parent_completion) {
+        continue;
+      }
       cancelChildEvent(child);
     }
   }
@@ -525,6 +547,9 @@ class BaseEvent {
       } else if (result.status === "started") {
         for (const child of result.event_children) {
           const original_child = child._event_original ?? child;
+          if (!original_child.event_blocks_parent_completion) {
+            continue;
+          }
           original_child._cancelPendingChildProcessing(cause);
           original_child._markCancelled(cause);
         }
@@ -541,7 +566,7 @@ class BaseEvent {
   // 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 (!this.event_bus) {
       if (original.event_status !== "completed") {
         original._markCompleted();
       }
@@ -549,7 +574,7 @@ class BaseEvent {
     }
     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) {
+    for (const bus of this.event_bus.all_instances) {
       if (!buses_to_cancel.has(bus.label)) {
         continue;
       }
@@ -588,14 +613,14 @@ class BaseEvent {
   }
   _notifyEventParentsOfCompletion() {
     const original = this._event_original ?? this;
-    if (!this.bus) {
+    if (!this.event_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);
+      const parent = this.event_bus.findEventById(parent_id);
       if (!parent) {
         break;
       }
@@ -609,12 +634,13 @@ class BaseEvent {
   // 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.bus) {
+    if (!this.event_bus) {
       return Promise.reject(new Error("event has no bus attached"));
     }
     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.bus._processEventImmediately(this);
+    const completion_promise = this.event_status === "completed" ? Promise.resolve(original) : this.event_bus._processEventImmediately(this);
     if (!raise_if_any) {
       return completion_promise;
     }
@@ -634,7 +660,7 @@ class BaseEvent {
   //   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) {
+    if (!this.event_bus) {
       return Promise.reject(new Error("event has no bus attached"));
     }
     const original = this._event_original ?? this;
@@ -667,7 +693,7 @@ class BaseEvent {
     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;
+    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 });
@@ -715,12 +741,29 @@ class BaseEvent {
   }
   // awaitable that waits for the event to be processed in normal queue order by the _runloop
   eventCompleted() {
+    const original = this._event_original ?? this;
+    original._markBlocksParentCompletionIfAwaitedFromEmittingHandler();
     if (this.event_status === "completed") {
       return Promise.resolve(this);
     }
     this._notifyDoneListeners();
     return this._event_completed_signal.promise;
   }
+  _markBlocksParentCompletionIfAwaitedFromEmittingHandler() {
+    const original = this._event_original ?? this;
+    if (original.event_blocks_parent_completion || !original.event_bus) {
+      return;
+    }
+    const active_result = original.event_bus.locks._getActiveHandlerResultForCurrentAsyncContext();
+    if (!active_result || active_result.status !== "started") {
+      return;
+    }
+    const active_parent = active_result.event._event_original ?? active_result.event;
+    const is_child_of_active_handler = original.event_parent_id === active_parent.event_id && original.event_emitted_by_handler_id === active_result.handler_id && active_result.event_children.some((child) => (child._event_original ?? child).event_id === original.event_id);
+    if (is_child_of_active_handler) {
+      original.event_blocks_parent_completion = true;
+    }
+  }
   _markPending() {
     const original = this._event_original ?? this;
     original.event_status = "pending";
@@ -731,7 +774,7 @@ class BaseEvent {
     original._setDispatchContext(void 0);
     original._event_completed_signal = null;
     original._lock_for_event_handler = null;
-    original.bus = void 0;
+    original.event_bus = void 0;
     return this;
   }
   eventReset() {
@@ -748,8 +791,8 @@ class BaseEvent {
     }
     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;
+    if (notify_hook && original.event_bus) {
+      const bus_for_hook = original.event_bus;
       const event_for_bus = bus_for_hook._getEventProxyScopedToThisBus(original);
       void bus_for_hook.onEventChange(event_for_bus, "started");
     }
@@ -769,8 +812,8 @@ class BaseEvent {
     }
     original.event_status = "completed";
     original.event_completed_at = monotonicDatetime();
-    if (original.bus) {
-      const bus_for_hook = original.bus;
+    if (original.event_bus) {
+      const bus_for_hook = original.event_bus;
       const event_for_bus = bus_for_hook._getEventProxyScopedToThisBus(original);
       void bus_for_hook.onEventChange(event_for_bus, "completed");
     }
@@ -779,16 +822,16 @@ class BaseEvent {
     original._event_completed_signal.resolve(original);
     original._event_completed_signal = null;
     original.dropFromZeroHistoryBuses();
-    if (notify_parents && original.bus) {
+    if (notify_parents && original.event_bus) {
       original._notifyEventParentsOfCompletion();
     }
   }
   dropFromZeroHistoryBuses() {
-    if (!this.bus) {
+    if (!this.event_bus) {
       return;
     }
     const original = this._event_original ?? this;
-    for (const bus of this.bus.all_instances) {
+    for (const bus of this.event_bus.all_instances) {
       if (bus.event_history.max_history_size !== 0) {
         continue;
       }
@@ -816,8 +859,25 @@ class BaseEvent {
   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");
+  _areAllChildrenComplete(visited = /* @__PURE__ */ new Set()) {
+    const original = this._event_original ?? this;
+    if (visited.has(original.event_id)) {
+      return true;
+    }
+    visited.add(original.event_id);
+    for (const child of original.event_children) {
+      const original_child = child._event_original ?? child;
+      if (!original_child.event_blocks_parent_completion) {
+        continue;
+      }
+      if (original_child.event_status !== "completed") {
+        return false;
+      }
+      if (!original_child._areAllChildrenComplete(visited)) {
+        return false;
+      }
+    }
+    return true;
   }
   _notifyDoneListeners() {
     if (this._event_completed_signal) {
@@ -830,7 +890,7 @@ class BaseEvent {
   _gc() {
     this._event_completed_signal = null;
     this._setDispatchContext(null);
-    this.bus = void 0;
+    this.event_bus = void 0;
     this._lock_for_event_handler = null;
     for (const result of this.event_results.values()) {
       result.event_children = [];