abxbus 2.4.1 → 2.4.15

package/README.md

@@ -2,9 +2,9 @@
 
 <img width="200" alt="image" src="https://github.com/user-attachments/assets/b3525c24-51ba-496c-b327-ccdfe46a7362" align="right" />
 
-[![DeepWiki: Python](https://img.shields.io/badge/DeepWiki-abxbus%2FPython-yellow.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/ArchiveBox/abx-bus) [![PyPI - Version](https://img.shields.io/pypi/v/abx-bus)](https://pypi.org/project/abx-bus/) [![GitHub License](https://img.shields.io/github/license/ArchiveBox/abx-bus)](https://github.com/ArchiveBox/abx-bus) ![GitHub last commit](https://img.shields.io/github/last-commit/ArchiveBox/abx-bus)
+[![DeepWiki: Python](https://img.shields.io/badge/DeepWiki-abxbus%2FPython-yellow.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/ArchiveBox/abxbus) [![PyPI - Version](https://img.shields.io/pypi/v/abxbus)](https://pypi.org/project/abxbus/) [![GitHub License](https://img.shields.io/github/license/ArchiveBox/abxbus)](https://github.com/ArchiveBox/abxbus) ![GitHub last commit](https://img.shields.io/github/last-commit/ArchiveBox/abxbus)
 
-[![DeepWiki: TS](https://img.shields.io/badge/DeepWiki-abxbus%2FTypescript-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/ArchiveBox/abx-bus/3-typescript-implementation) [![NPM Version](https://img.shields.io/npm/v/abxbus)](https://www.npmjs.com/package/abxbus)
+[![DeepWiki: TS](https://img.shields.io/badge/DeepWiki-abxbus%2FTypescript-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/ArchiveBox/abxbus/3-typescript-implementation) [![NPM Version](https://img.shields.io/npm/v/abxbus)](https://www.npmjs.com/package/abxbus)
 
 AbxBus is an in-memory event bus library for async Python and TS (node/bun/deno/browser).
 
@@ -27,17 +27,17 @@ It's async native, has proper automatic nested event tracking, and powerful conc
 
 ♾️ It's inspired by the simplicity of async and events in `JS` but with baked-in features that allow to eliminate most of the tedious repetitive complexity in event-driven codebases:
 
-- correct timeout enforcement across multiple levels of events, if a parent times out it correctly aborts all child event processing
+- correct timeout enforcement across multiple levels of events, including cancellation of awaited/blocking child work when a parent times out
 - ability to strongly type hint and enforce the return type of event handlers at compile-time
 - ability to queue events on the bus, or inline await them for immediate execution like a normal function call
 - handles ~5,000 events/sec/core in both languages, with ~2kb/event RAM consumed per event during active processing
 
 ## 🔗 Links
 
-- Issue Tracker: https://github.com/ArchiveBox/abx-bus/issues
+- Issue Tracker: https://github.com/ArchiveBox/abxbus/issues
 - Documentation: https://abxbus.archivebox.io
-- DeepWiki: https://deepwiki.com/ArchiveBox/abx-bus
-- PyPI: https://pypi.org/project/abx-bus/
+- DeepWiki: https://deepwiki.com/ArchiveBox/abxbus
+- PyPI: https://pypi.org/project/abxbus/
 - NPM: https://www.npmjs.com/package/abxbus
 
 <br/>
@@ -294,6 +294,17 @@ await bus.waitUntilIdle()   // this resolves once all three events have finished
 await bus.waitUntilIdle(5)  // wait up to 5 seconds, then continue even if work is still in-flight
 ```
 
+#### Emit styles from handlers
+
+Most handler code should use `await event.emit(ChildEvent({})).done()`. That creates a linked child and marks it as blocking parent completion.
+
+| Style | `event_parent_id` | `event_blocks_parent_completion` | Blocks current handler? | Effect |
+| --- | --- | --- | --- | --- |
+| `await event.emit(ChildEvent({})).done()` | Parent event id | `true` | Yes | Linked child work; parent completion waits too. |
+| `event.emit(ChildEvent({}))` without awaiting | Parent event id | `false` | No | Linked background child; visible in ancestry but parent completion does not wait. |
+| `await bus.emit(TopLevelEvent({})).done()` | `null` | `false` | Yes | Detached top-level event; the handler waits naturally because it is awaited. |
+| `bus.emit(TopLevelEvent({}))` without awaiting | `null` | `false` | No | True detached background event with no retained parent relationship. |
+
 #### Parent/child/event lookup helpers
 
 ```ts
@@ -389,6 +400,7 @@ Special configuration fields you can set on each event to control processing:
 - `event_path: string[]` (bus labels like `BusName#ab12`)
 - `event_parent_id: string | null`
 - `event_emitted_by_handler_id: string | null`
+- `event_blocks_parent_completion: boolean`
 - `event_status: 'pending' | 'started' | 'completed'`
 - `event_results: Map<string, EventResult>`
 - `event_pending_bus_count: number`
@@ -634,7 +646,7 @@ Notes:
 ## 👾 Development
 
 ```bash
-git clone https://github.com/ArchiveBox/abx-bus abxbus && cd abxbus
+git clone https://github.com/ArchiveBox/abxbus abxbus && cd abxbus
 
 cd ./abxbus-ts
 pnpm install

package/dist/cjs/base_event.d.ts

@@ -14,6 +14,7 @@ export declare const BaseEventSchema: z.ZodObject<{
     event_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     event_handler_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     event_handler_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    event_blocks_parent_completion: z.ZodOptional<z.ZodBoolean>;
     event_parent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     event_path: z.ZodOptional<z.ZodArray<z.ZodString>>;
     event_result_type: z.ZodOptional<z.ZodUnknown>;
@@ -43,7 +44,7 @@ export declare const BaseEventSchema: z.ZodObject<{
 }, z.core.$loose>;
 export type BaseEventData = z.infer<typeof BaseEventSchema>;
 export type BaseEventJSON = BaseEventData & Record<string, unknown>;
-type BaseEventFields = Pick<BaseEventData, 'event_id' | 'event_created_at' | 'event_type' | 'event_version' | 'event_timeout' | 'event_slow_timeout' | 'event_handler_timeout' | 'event_handler_slow_timeout' | 'event_parent_id' | 'event_path' | 'event_result_type' | 'event_emitted_by_handler_id' | 'event_pending_bus_count' | 'event_status' | 'event_started_at' | 'event_completed_at' | 'event_results' | 'event_concurrency' | 'event_handler_concurrency' | 'event_handler_completion'>;
+type BaseEventFields = Pick<BaseEventData, 'event_id' | 'event_created_at' | 'event_type' | 'event_version' | 'event_timeout' | 'event_slow_timeout' | 'event_handler_timeout' | 'event_handler_slow_timeout' | 'event_blocks_parent_completion' | 'event_parent_id' | 'event_path' | 'event_result_type' | 'event_emitted_by_handler_id' | 'event_pending_bus_count' | 'event_status' | 'event_started_at' | 'event_completed_at' | 'event_results' | 'event_concurrency' | 'event_handler_concurrency' | 'event_handler_completion'>;
 export type BaseEventInit<TFields extends Record<string, unknown>> = TFields & Partial<BaseEventFields>;
 type BaseEventSchemaShape = typeof BaseEventSchema.shape;
 export type EventSchema<TShape extends z.ZodRawShape> = z.ZodObject<BaseEventSchemaShape & TShape>;
@@ -95,6 +96,7 @@ export declare class BaseEvent {
     event_slow_timeout?: number | null;
     event_handler_timeout?: number | null;
     event_handler_slow_timeout?: number | null;
+    event_blocks_parent_completion: boolean;
     event_parent_id: string | null;
     event_path: string[];
     event_result_type?: z.ZodTypeAny;
@@ -118,6 +120,7 @@ export declare class BaseEvent {
         event_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         event_handler_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         event_handler_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        event_blocks_parent_completion: z.ZodOptional<z.ZodBoolean>;
         event_parent_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         event_path: z.ZodOptional<z.ZodArray<z.ZodString>>;
         event_result_type: z.ZodOptional<z.ZodUnknown>;
@@ -145,12 +148,11 @@ export declare class BaseEvent {
             first: "first";
         }>>>;
     }, z.core.$loose>;
-    bus?: EventBus;
+    event_bus?: EventBus;
     _event_original?: BaseEvent;
     _event_dispatch_context?: unknown | null;
     _event_completed_signal: Deferred<this> | null;
     _lock_for_event_handler: AsyncLock | null;
-    get event_bus(): EventBus;
     constructor(data?: BaseEventInit<Record<string, unknown>>);
     toString(): string;
     static extend<TShape extends z.ZodRawShape>(event_type: string, shape?: TShape): EventFactory<TShape, ResultSchemaFromShape<TShape>>;
@@ -180,6 +182,7 @@ export declare class BaseEvent {
     get event_parent(): BaseEvent | undefined;
     get event_children(): BaseEvent[];
     get event_descendants(): BaseEvent[];
+    emit<T extends BaseEvent>(event: T): T;
     _cancelPendingChildProcessing(reason: unknown): void;
     _markRemainingFirstModeResultCancelled(winner: EventResult): void;
     _markCancelled(cause: Error): void;
@@ -189,6 +192,7 @@ export declare class BaseEvent {
     eventResultsList(include: EventResultsListInclude<this>, options?: EventResultsListOptions<this>): Promise<Array<EventResultType<this> | undefined>>;
     eventResultsList(options?: EventResultsListOptions<this>): Promise<Array<EventResultType<this> | undefined>>;
     eventCompleted(): Promise<this>;
+    _markBlocksParentCompletionIfAwaitedFromEmittingHandler(): void;
     _markPending(): this;
     eventReset(): this;
     _markStarted(started_at?: string | null, notify_hook?: boolean): void;
@@ -200,7 +204,7 @@ export declare class BaseEvent {
         ignore_first_mode_control_errors?: boolean;
     }): unknown | undefined;
     get event_result(): EventResultType<this> | undefined;
-    _areAllChildrenComplete(): boolean;
+    _areAllChildrenComplete(visited?: Set<string>): boolean;
     private _notifyDoneListeners;
     _gc(): void;
 }

package/dist/cjs/base_event.js

@@ -30,7 +30,7 @@ var import_lock_manager = require("./lock_manager.js");
 var import_timing = require("./timing.js");
 var import_types = require("./types.js");
 var import_helpers = require("./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)) {
@@ -69,6 +69,7 @@ const BaseEventSchema = import_zod.z.object({
   event_slow_timeout: import_zod.z.number().positive().nullable().optional(),
   event_handler_timeout: import_zod.z.number().positive().nullable().optional(),
   event_handler_slow_timeout: import_zod.z.number().positive().nullable().optional(),
+  event_blocks_parent_completion: import_zod.z.boolean().optional(),
   event_parent_id: import_zod.z.string().uuid().nullable().optional(),
   event_path: import_zod.z.array(import_zod.z.string()).optional(),
   event_result_type: import_zod.z.unknown().optional(),
@@ -102,6 +103,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;
@@ -130,17 +133,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");
@@ -158,6 +158,7 @@ class BaseEvent {
     const event_id = merged_data.event_id ?? (0, import_uuid.v7)();
     const event_created_at = (0, import_helpers.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,
@@ -165,6 +166,7 @@ class BaseEvent {
       event_type,
       event_version,
       event_timeout,
+      event_blocks_parent_completion,
       event_result_type
     };
     const schema = ctor.schema ?? BaseEventSchema;
@@ -253,7 +255,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;
     }
@@ -272,6 +274,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,
@@ -287,12 +290,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;
@@ -312,8 +315,8 @@ class BaseEvent {
     let handler_entry;
     if (handler instanceof import_event_handler.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 = import_event_handler.EventHandler.fromCallable({
@@ -372,10 +375,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);
@@ -388,10 +391,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);
     });
   }
@@ -402,9 +405,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)) {
@@ -431,7 +434,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;
     }
@@ -459,7 +462,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() {
@@ -501,6 +504,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;
@@ -513,6 +527,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);
@@ -521,6 +539,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);
     }
   }
@@ -543,6 +565,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);
         }
@@ -559,7 +584,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();
       }
@@ -567,7 +592,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;
       }
@@ -606,14 +631,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;
       }
@@ -627,12 +652,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;
     }
@@ -652,7 +678,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;
@@ -685,7 +711,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 });
@@ -733,12 +759,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";
@@ -749,7 +792,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() {
@@ -766,8 +809,8 @@ class BaseEvent {
     }
     original.event_status = "started";
     original.event_started_at = started_at === null ? (0, import_helpers.monotonicDatetime)() : (0, import_helpers.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");
     }
@@ -787,8 +830,8 @@ class BaseEvent {
     }
     original.event_status = "completed";
     original.event_completed_at = (0, import_helpers.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");
     }
@@ -797,16 +840,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;
       }
@@ -834,8 +877,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) {
@@ -848,7 +908,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 = [];