abxbus 2.5.1 → 2.5.3

package/dist/cjs/base_event.d.ts

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+import { EventBus } from './event_bus.js';
+import { EventResult } from './event_result.js';
+import { EventHandler } from './event_handler.js';
+import type { EventConcurrencyMode, EventHandlerConcurrencyMode, EventHandlerCompletionMode, Deferred } from './lock_manager.js';
+import { AsyncLock } from './lock_manager.js';
+import type { EventHandlerCallable, EventResultType } from './types.js';
+export declare const BaseEventSchema: z.ZodObject<{
+    event_id: z.ZodString;
+    event_created_at: z.ZodString;
+    event_type: z.ZodString;
+    event_version: z.ZodDefault<z.ZodString>;
+    event_timeout: z.ZodNullable<z.ZodNumber>;
+    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>;
+    event_emitted_by_handler_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event_pending_bus_count: z.ZodOptional<z.ZodNumber>;
+    event_status: z.ZodOptional<z.ZodEnum<{
+        pending: "pending";
+        started: "started";
+        completed: "completed";
+    }>>;
+    event_started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event_completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    event_results: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    event_concurrency: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        "global-serial": "global-serial";
+        "bus-serial": "bus-serial";
+        parallel: "parallel";
+    }>>>;
+    event_handler_concurrency: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        parallel: "parallel";
+        serial: "serial";
+    }>>>;
+    event_handler_completion: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        all: "all";
+        first: "first";
+    }>>>;
+}, 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_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>;
+type EventPayload<TShape extends z.ZodRawShape> = TShape extends Record<string, never> ? {} : z.infer<z.ZodObject<TShape>>;
+type EventInput<TShape extends z.ZodRawShape> = z.input<EventSchema<TShape>>;
+export type EventInit<TShape extends z.ZodRawShape> = Omit<EventInput<TShape>, keyof BaseEventFields> & Partial<BaseEventFields>;
+type EventWithResultSchema<TResult> = BaseEvent & {
+    __event_result_type__?: TResult;
+};
+type ResultTypeFromEventResultTypeInput<TInput> = TInput extends z.ZodTypeAny ? z.infer<TInput> : TInput extends StringConstructor ? string : TInput extends NumberConstructor ? number : TInput extends BooleanConstructor ? boolean : TInput extends ArrayConstructor ? unknown[] : TInput extends ObjectConstructor ? Record<string, unknown> : unknown;
+type ResultSchemaFromShape<TShape> = TShape extends {
+    event_result_type: infer S;
+} ? ResultTypeFromEventResultTypeInput<S> : unknown;
+type EventResultsListInclude<TEvent extends BaseEvent> = (result: EventResultType<TEvent> | undefined, event_result: EventResult<TEvent>) => boolean;
+type EventResultsListOptions<TEvent extends BaseEvent> = {
+    timeout?: number | null;
+    include?: EventResultsListInclude<TEvent>;
+    raise_if_any?: boolean;
+    raise_if_none?: boolean;
+};
+type EventDoneOptions = {
+    raise_if_any?: boolean;
+};
+type EventResultUpdateOptions<TEvent extends BaseEvent> = {
+    eventbus?: EventBus;
+    status?: 'pending' | 'started' | 'completed' | 'error';
+    result?: EventResultType<TEvent> | BaseEvent | undefined;
+    error?: unknown;
+};
+export type EventFactory<TShape extends z.ZodRawShape, TResult = unknown> = {
+    (data: EventInit<TShape>): EventWithResultSchema<TResult> & EventPayload<TShape>;
+    new (data: EventInit<TShape>): EventWithResultSchema<TResult> & EventPayload<TShape>;
+    schema: EventSchema<TShape>;
+    class?: new (data: EventInit<TShape>) => EventWithResultSchema<TResult> & EventPayload<TShape>;
+    event_type?: string;
+    event_version?: string;
+    event_result_type?: z.ZodTypeAny;
+    fromJSON?: (data: unknown) => EventWithResultSchema<TResult> & EventPayload<TShape>;
+};
+type ZodShapeFrom<TShape extends Record<string, unknown>> = {
+    [K in keyof TShape as K extends 'event_result_type' ? never : TShape[K] extends z.ZodTypeAny ? K : never]: Extract<TShape[K], z.ZodTypeAny>;
+};
+export declare class BaseEvent {
+    event_id: string;
+    event_created_at: string;
+    event_type: string;
+    event_version: string;
+    event_timeout: number | null;
+    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;
+    event_results: Map<string, EventResult<this>>;
+    event_emitted_by_handler_id: string | null;
+    event_pending_bus_count: number;
+    event_status: 'pending' | 'started' | 'completed';
+    event_started_at: string | null;
+    event_completed_at: string | null;
+    event_concurrency?: EventConcurrencyMode | null;
+    event_handler_concurrency?: EventHandlerConcurrencyMode | null;
+    event_handler_completion?: EventHandlerCompletionMode | null;
+    static event_type?: string;
+    static event_version: string;
+    static schema: z.ZodObject<{
+        event_id: z.ZodString;
+        event_created_at: z.ZodString;
+        event_type: z.ZodString;
+        event_version: z.ZodDefault<z.ZodString>;
+        event_timeout: z.ZodNullable<z.ZodNumber>;
+        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>;
+        event_emitted_by_handler_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        event_pending_bus_count: z.ZodOptional<z.ZodNumber>;
+        event_status: z.ZodOptional<z.ZodEnum<{
+            pending: "pending";
+            started: "started";
+            completed: "completed";
+        }>>;
+        event_started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        event_completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        event_results: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        event_concurrency: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            "global-serial": "global-serial";
+            "bus-serial": "bus-serial";
+            parallel: "parallel";
+        }>>>;
+        event_handler_concurrency: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            parallel: "parallel";
+            serial: "serial";
+        }>>>;
+        event_handler_completion: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            all: "all";
+            first: "first";
+        }>>>;
+    }, z.core.$loose>;
+    event_bus?: EventBus;
+    _event_original?: BaseEvent;
+    _event_dispatch_context?: unknown | null;
+    _event_completed_signal: Deferred<this> | null;
+    _lock_for_event_handler: AsyncLock | null;
+    constructor(data?: BaseEventInit<Record<string, unknown>>);
+    toString(): string;
+    static extend<TShape extends z.ZodRawShape>(event_type: string, shape?: TShape): EventFactory<TShape, ResultSchemaFromShape<TShape>>;
+    static extend<TShape extends Record<string, unknown>>(event_type: string, shape?: TShape): EventFactory<ZodShapeFrom<TShape>, ResultSchemaFromShape<TShape>>;
+    static fromJSON<T extends typeof BaseEvent>(this: T, data: unknown): InstanceType<T>;
+    static toJSONArray(events: Iterable<BaseEvent>): BaseEventJSON[];
+    static fromJSONArray(data: unknown): BaseEvent[];
+    toJSON(): BaseEventJSON;
+    _createSlowEventWarningTimer(): ReturnType<typeof setTimeout> | null;
+    eventResultUpdate(handler: EventHandler | EventHandlerCallable<this>, options?: EventResultUpdateOptions<this>): EventResult<this>;
+    _createPendingHandlerResults(bus: EventBus): Array<{
+        handler: EventHandler;
+        result: EventResult;
+    }>;
+    private _collectPendingResults;
+    private _isFirstModeWinningResult;
+    private _markFirstModeWinnerIfNeeded;
+    private _runHandlerWithLock;
+    _runHandlers(pending_entries?: Array<{
+        handler: EventHandler;
+        result: EventResult;
+    }>): Promise<void>;
+    _getHandlerLock(default_concurrency?: EventHandlerConcurrencyMode): AsyncLock | null;
+    _setHandlerLock(lock: AsyncLock | null): void;
+    _getDispatchContext(): unknown | null | undefined;
+    _setDispatchContext(dispatch_context: unknown | null | undefined): void;
+    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;
+    _notifyEventParentsOfCompletion(): void;
+    done(options?: EventDoneOptions): Promise<this>;
+    first(): Promise<EventResultType<this> | undefined>;
+    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;
+    _markCompleted(force?: boolean, notify_parents?: boolean): void;
+    private dropFromZeroHistoryBuses;
+    get event_errors(): unknown[];
+    private _isFirstModeControlError;
+    _firstProcessingError(options?: {
+        ignore_first_mode_control_errors?: boolean;
+    }): unknown | undefined;
+    get event_result(): EventResultType<this> | undefined;
+    _areAllChildrenComplete(visited?: Set<string>): boolean;
+    private _notifyDoneListeners;
+    _gc(): void;
+}
+export {};

package/dist/cjs/bridge_jsonl.d.ts

@@ -0,0 +1,26 @@
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class JSONLEventBridge {
+    readonly path: string;
+    readonly poll_interval: number;
+    readonly name: string;
+    private readonly inbound_bus;
+    private running;
+    private byte_offset;
+    private pending_line;
+    private listener_task;
+    constructor(path: string, poll_interval?: number, name?: string);
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void;
+    emit<T extends BaseEvent>(event: T): Promise<void>;
+    dispatch<T extends BaseEvent>(event: T): Promise<void>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private listenLoop;
+    private pollNewLines;
+    private dispatchInboundPayload;
+    private readAppended;
+    private dirname;
+    private loadFs;
+}

package/dist/cjs/bridge_nats.d.ts

@@ -0,0 +1,20 @@
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class NATSEventBridge {
+    readonly server: string;
+    readonly subject: string;
+    readonly name: string;
+    private readonly inbound_bus;
+    private running;
+    private nc;
+    private sub_task;
+    constructor(server: string, subject: string, name?: string);
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void;
+    emit<T extends BaseEvent>(event: T): Promise<void>;
+    dispatch<T extends BaseEvent>(event: T): Promise<void>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private dispatchInboundPayload;
+}

package/dist/cjs/bridge_postgres.d.ts

@@ -0,0 +1,31 @@
+/**
+ * PostgreSQL LISTEN/NOTIFY + flat-table bridge for forwarding events.
+ */
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class PostgresEventBridge {
+    readonly table_url: string;
+    readonly dsn: string;
+    readonly table: string;
+    readonly channel: string;
+    readonly name: string;
+    private readonly inbound_bus;
+    private running;
+    private client;
+    private table_columns;
+    private notification_handler;
+    constructor(table_url: string, channel?: string, name?: string);
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void;
+    emit<T extends BaseEvent>(event: T): Promise<void>;
+    dispatch<T extends BaseEvent>(event: T): Promise<void>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private dispatchByEventId;
+    private dispatchInboundPayload;
+    private ensureTableExists;
+    private ensureBaseIndexes;
+    private refreshColumnCache;
+    private ensureColumns;
+}

package/dist/cjs/bridge_redis.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Redis pub/sub bridge for forwarding events between runtimes.
+ *
+ * Usage:
+ *   // channel from URL path
+ *   const bridge = new RedisEventBridge('redis://user:pass@localhost:6379/1/my_channel')
+ *
+ *   // explicit channel override
+ *   const bridge2 = new RedisEventBridge('redis://user:pass@localhost:6379/1', 'my_channel')
+ *
+ * URL format:
+ *   redis://user:pass@host:6379/<db>/<optional_channel>
+ */
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class RedisEventBridge {
+    readonly url: string;
+    readonly channel: string;
+    readonly name: string;
+    private readonly inbound_bus;
+    private running;
+    private start_promise;
+    private redis_pub;
+    private redis_sub;
+    constructor(redis_url: string, channel?: string, name?: string);
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void;
+    emit<T extends BaseEvent>(event: T): Promise<void>;
+    dispatch<T extends BaseEvent>(event: T): Promise<void>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private dispatchInboundPayload;
+}

package/dist/cjs/bridge_sqlite.d.ts

@@ -0,0 +1,30 @@
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class SQLiteEventBridge {
+    readonly path: string;
+    readonly table: string;
+    readonly poll_interval: number;
+    readonly name: string;
+    private readonly inbound_bus;
+    private running;
+    private last_seen_event_created_at;
+    private last_seen_event_id;
+    private listener_task;
+    private start_task;
+    private db;
+    private table_columns;
+    constructor(path: string, table?: string, poll_interval?: number, name?: string);
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>): void;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>): void;
+    emit<T extends BaseEvent>(event: T): Promise<void>;
+    dispatch<T extends BaseEvent>(event: T): Promise<void>;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    private ensureStarted;
+    private listenLoop;
+    private dispatchInboundPayload;
+    private refreshColumnCache;
+    private ensureColumns;
+    private ensureBaseIndexes;
+    private setCursorToLatestRow;
+}

package/dist/cjs/event_bus.d.ts

@@ -0,0 +1,125 @@
+import { BaseEvent, type BaseEventJSON } from './base_event.js';
+import { EventHistory } from './event_history.js';
+import { EventResult } from './event_result.js';
+import { AsyncLock, type EventConcurrencyMode, type EventHandlerConcurrencyMode, type EventHandlerCompletionMode, LockManager } from './lock_manager.js';
+import { EventHandler, type EphemeralFindEventHandler, type EventHandlerJSON } from './event_handler.js';
+import type { EventBusMiddleware, EventBusMiddlewareInput } from './middlewares.js';
+import type { EventClass, EventHandlerCallable, EventPattern, FindOptions, UntypedEventHandlerFunction } from './types.js';
+export type EventBusOptions = {
+    id?: string;
+    max_history_size?: number | null;
+    max_history_drop?: boolean;
+    event_concurrency?: EventConcurrencyMode | null;
+    event_timeout?: number | null;
+    event_slow_timeout?: number | null;
+    event_handler_concurrency?: EventHandlerConcurrencyMode | null;
+    event_handler_completion?: EventHandlerCompletionMode;
+    event_handler_slow_timeout?: number | null;
+    event_handler_detect_file_paths?: boolean;
+    middlewares?: EventBusMiddlewareInput[];
+};
+export type EventBusJSON = {
+    id: string;
+    name: string;
+    max_history_size: number | null;
+    max_history_drop: boolean;
+    event_concurrency: EventConcurrencyMode;
+    event_timeout: number | null;
+    event_slow_timeout: number | null;
+    event_handler_concurrency: EventHandlerConcurrencyMode;
+    event_handler_completion: EventHandlerCompletionMode;
+    event_handler_slow_timeout: number | null;
+    event_handler_detect_file_paths: boolean;
+    handlers: Record<string, EventHandlerJSON>;
+    handlers_by_key: Record<string, string[]>;
+    event_history: Record<string, BaseEventJSON>;
+    pending_event_queue: string[];
+};
+export declare class GlobalEventBusRegistry {
+    private _bus_refs;
+    add(bus: EventBus): void;
+    discard(bus: EventBus): void;
+    has(bus: EventBus): boolean;
+    get size(): number;
+    [Symbol.iterator](): IterableIterator<EventBus>;
+    findBusById(bus_id: string): EventBus | undefined;
+    findEventById(event_id: string): BaseEvent | null;
+}
+export declare class EventBus {
+    private static _registry_by_constructor;
+    private static _global_event_lock_by_constructor;
+    private static getRegistryForConstructor;
+    private static getGlobalEventLockForConstructor;
+    static get all_instances(): GlobalEventBusRegistry;
+    get all_instances(): GlobalEventBusRegistry;
+    get _lock_for_event_global_serial(): AsyncLock;
+    id: string;
+    name: string;
+    event_timeout: number | null;
+    event_concurrency: EventConcurrencyMode;
+    event_handler_concurrency: EventHandlerConcurrencyMode;
+    event_handler_completion: EventHandlerCompletionMode;
+    event_handler_detect_file_paths: boolean;
+    event_handler_slow_timeout: number | null;
+    event_slow_timeout: number | null;
+    handlers: Map<string, EventHandler>;
+    handlers_by_key: Map<string, string[]>;
+    event_history: EventHistory<BaseEvent>;
+    pending_event_queue: BaseEvent[];
+    in_flight_event_ids: Set<string>;
+    runloop_running: boolean;
+    locks: LockManager;
+    find_waiters: Set<EphemeralFindEventHandler>;
+    middlewares: EventBusMiddleware[];
+    private static normalizeMiddlewares;
+    constructor(name?: string, options?: EventBusOptions);
+    toString(): string;
+    scheduleMicrotask(fn: () => void): void;
+    private _runMiddlewareHook;
+    onEventChange(event: BaseEvent, status: 'pending' | 'started' | 'completed'): Promise<void>;
+    onEventResultChange(event: BaseEvent, result: EventResult, status: 'pending' | 'started' | 'completed'): Promise<void>;
+    private _onEventChange;
+    private _onEventResultChange;
+    private _onBusHandlersChange;
+    private _finalizeEventTimeout;
+    private _createEventTimeoutError;
+    private _runHandlersWithTimeout;
+    private _markEventCompletedIfNeeded;
+    toJSON(): EventBusJSON;
+    private static _stubHandlerFn;
+    private static _upsertHandlerIndex;
+    private static _linkEventResultHandlers;
+    static fromJSON(data: unknown): EventBus;
+    get label(): string;
+    removeEventFromPendingQueue(event: BaseEvent): number;
+    isEventInFlightOrQueued(event_id: string): boolean;
+    removeEventFromHistory(event_id: string): boolean;
+    destroy(): void;
+    on<T extends BaseEvent>(event_pattern: EventClass<T>, handler: EventHandlerCallable<T>, options?: Partial<EventHandler>): EventHandler;
+    on<T extends BaseEvent>(event_pattern: string | '*', handler: UntypedEventHandlerFunction<T>, options?: Partial<EventHandler>): EventHandler;
+    off<T extends BaseEvent>(event_pattern: EventPattern<T> | '*', handler?: EventHandlerCallable<T> | string | EventHandler): void;
+    emit<T extends BaseEvent>(event: T): T;
+    dispatch<T extends BaseEvent>(event: T): T;
+    find(event_pattern: '*', options?: FindOptions<BaseEvent>): Promise<BaseEvent | null>;
+    find(event_pattern: '*', where: (event: BaseEvent) => boolean, options?: FindOptions<BaseEvent>): Promise<BaseEvent | null>;
+    find<T extends BaseEvent>(event_pattern: EventPattern<T>, options?: FindOptions<T>): Promise<T | null>;
+    find<T extends BaseEvent>(event_pattern: EventPattern<T>, where: (event: T) => boolean, options?: FindOptions<T>): Promise<T | null>;
+    private _waitForFutureMatch;
+    waitUntilIdle(timeout?: number | null): Promise<boolean>;
+    isIdle(): boolean;
+    isIdleAndQueueEmpty(): boolean;
+    eventIsChildOf(child_event: BaseEvent, parent_event: BaseEvent): boolean;
+    eventIsParentOf(parent_event: BaseEvent, child_event: BaseEvent): boolean;
+    logTree(): string;
+    findEventById(event_id: string): BaseEvent | null;
+    private _startRunloop;
+    private _processEvent;
+    _processEventImmediately<T extends BaseEvent>(event: T, handler_result?: EventResult): Promise<T>;
+    private _processEventImmediatelyAcrossBuses;
+    private _runloop;
+    _hasProcessedEvent(event: BaseEvent): boolean;
+    _getEventProxyScopedToThisBus<T extends BaseEvent>(event: T, handler_result?: EventResult): T;
+    private _resolveFindWaiters;
+    _getHandlersForEvent(event: BaseEvent): EventHandler[];
+    private _removeIndexedHandler;
+}

package/dist/cjs/event_handler.d.ts

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+import { type EventHandlerCallable, type EventPattern } from './types.js';
+import { BaseEvent } from './base_event.js';
+import type { EventResult } from './event_result.js';
+export type EphemeralFindEventHandler = {
+    event_pattern: string | '*';
+    matches: (event: BaseEvent) => boolean;
+    resolve: (event: BaseEvent) => void;
+    timeout_id?: ReturnType<typeof setTimeout>;
+};
+export declare const FindWaiterJSONSchema: z.ZodObject<{
+    event_pattern: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"*">]>;
+    has_timeout: z.ZodBoolean;
+}, z.core.$strict>;
+export type FindWaiterJSON = z.infer<typeof FindWaiterJSONSchema>;
+export declare class FindWaiter {
+    static toJSON(waiter: EphemeralFindEventHandler): FindWaiterJSON;
+    static fromJSON(data: unknown, overrides?: {
+        matches?: (event: BaseEvent) => boolean;
+        resolve?: (event: BaseEvent) => void;
+    }): EphemeralFindEventHandler;
+    static toJSONArray(waiters: Iterable<EphemeralFindEventHandler>): FindWaiterJSON[];
+    static fromJSONArray(data: unknown, overrides?: {
+        matches?: (event: BaseEvent) => boolean;
+        resolve?: (event: BaseEvent) => void;
+    }): EphemeralFindEventHandler[];
+}
+export declare const EventHandlerJSONSchema: z.ZodObject<{
+    id: z.ZodString;
+    eventbus_name: z.ZodString;
+    eventbus_id: z.ZodString;
+    event_pattern: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"*">]>;
+    handler_name: z.ZodString;
+    handler_file_path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    handler_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    handler_slow_timeout: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    handler_registered_at: z.ZodString;
+}, z.core.$strict>;
+export type EventHandlerJSON = z.infer<typeof EventHandlerJSONSchema>;
+export declare class EventHandler {
+    id: string;
+    handler: EventHandlerCallable;
+    handler_name: string;
+    handler_file_path: string | null;
+    handler_timeout?: number | null;
+    handler_slow_timeout?: number | null;
+    handler_registered_at: string;
+    event_pattern: string | '*';
+    eventbus_name: string;
+    eventbus_id: string;
+    constructor(params: {
+        id?: string;
+        handler: EventHandlerCallable;
+        handler_name: string;
+        handler_file_path?: string | null;
+        handler_timeout?: number | null;
+        handler_slow_timeout?: number | null;
+        handler_registered_at: string;
+        event_pattern: string | '*';
+        eventbus_name: string;
+        eventbus_id: string;
+    });
+    get _handler_async(): EventHandlerCallable;
+    static computeHandlerId(params: {
+        eventbus_id: string;
+        handler_name: string;
+        handler_file_path?: string | null;
+        handler_registered_at: string;
+        event_pattern: string | '*';
+    }): string;
+    static fromCallable<TEvent extends BaseEvent = BaseEvent>(params: {
+        handler: EventHandlerCallable<TEvent>;
+        event_pattern: EventPattern | '*';
+        eventbus_name: string;
+        eventbus_id: string;
+        detect_handler_file_path?: boolean;
+        id?: string;
+        handler_file_path?: string | null;
+        handler_timeout?: number | null;
+        handler_slow_timeout?: number | null;
+        handler_registered_at?: string;
+    }): EventHandler;
+    toString(): string;
+    _detectHandlerFilePath(): void;
+    toJSON(): EventHandlerJSON;
+    static fromJSON(data: unknown, handler?: EventHandlerCallable): EventHandler;
+    static toJSONArray(handlers: Iterable<EventHandler>): EventHandlerJSON[];
+    static fromJSONArray(data: unknown, handler?: EventHandlerCallable): EventHandler[];
+    get eventbus_label(): string;
+}
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+export declare class EventHandlerError extends Error {
+    event_result: EventResult;
+    timeout_seconds: number | null;
+    cause: Error;
+    constructor(message: string, params: {
+        event_result: EventResult;
+        timeout_seconds?: number | null;
+        cause: Error;
+    });
+    get event(): BaseEvent;
+    get event_type(): string;
+    get handler_name(): string;
+    get handler_id(): string;
+    get event_timeout(): number | null;
+}
+export declare class EventHandlerTimeoutError extends EventHandlerError {
+    constructor(message: string, params: {
+        event_result: EventResult;
+        timeout_seconds?: number | null;
+        cause?: Error;
+    });
+}
+export declare class EventHandlerCancelledError extends EventHandlerError {
+    constructor(message: string, params: {
+        event_result: EventResult;
+        timeout_seconds?: number | null;
+        cause: Error;
+    });
+}
+export declare class EventHandlerAbortedError extends EventHandlerError {
+    constructor(message: string, params: {
+        event_result: EventResult;
+        timeout_seconds?: number | null;
+        cause: Error;
+    });
+}
+export declare class EventHandlerResultSchemaError extends EventHandlerError {
+    raw_value: unknown;
+    constructor(message: string, params: {
+        event_result: EventResult;
+        timeout_seconds?: number | null;
+        cause: Error;
+        raw_value: unknown;
+    });
+    get expected_schema(): any;
+}

package/dist/cjs/event_history.d.ts

@@ -0,0 +1,45 @@
+import { BaseEvent } from './base_event.js';
+import type { EventPattern, FindWindow } from './types.js';
+export type EventHistoryFindOptions = {
+    past?: FindWindow;
+    future?: FindWindow;
+    child_of?: BaseEvent | null;
+    event_is_child_of?: (event: BaseEvent, ancestor: BaseEvent) => boolean;
+    wait_for_future_match?: (event_pattern: string | '*', matches: (event: BaseEvent) => boolean, future: FindWindow) => Promise<BaseEvent | null>;
+} & Record<string, unknown>;
+export type EventHistoryTrimOptions<TEvent extends BaseEvent = BaseEvent> = {
+    is_event_complete?: (event: TEvent) => boolean;
+    on_remove?: (event: TEvent) => void;
+    owner_label?: string;
+    max_history_size?: number | null;
+    max_history_drop?: boolean;
+};
+export declare class EventHistory<TEvent extends BaseEvent = BaseEvent> implements Iterable<[string, TEvent]> {
+    max_history_size: number | null;
+    max_history_drop: boolean;
+    private _events;
+    private _warned_about_dropping_uncompleted_events;
+    constructor(options?: {
+        max_history_size?: number | null;
+        max_history_drop?: boolean;
+    });
+    get size(): number;
+    [Symbol.iterator](): Iterator<[string, TEvent]>;
+    entries(): IterableIterator<[string, TEvent]>;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<TEvent>;
+    clear(): void;
+    get(event_id: string): TEvent | undefined;
+    set(event_id: string, event: TEvent): this;
+    has(event_id: string): boolean;
+    delete(event_id: string): boolean;
+    addEvent(event: TEvent): void;
+    getEvent(event_id: string): TEvent | undefined;
+    removeEvent(event_id: string): boolean;
+    hasEvent(event_id: string): boolean;
+    static normalizeEventPattern(event_pattern: EventPattern | '*'): string | '*';
+    find(event_pattern: '*', where?: (event: TEvent) => boolean, options?: EventHistoryFindOptions): Promise<TEvent | null>;
+    find<TMatch extends TEvent>(event_pattern: EventPattern<TMatch>, where?: (event: TMatch) => boolean, options?: EventHistoryFindOptions): Promise<TMatch | null>;
+    trimEventHistory(options?: EventHistoryTrimOptions<TEvent>): number;
+    private eventIsChildOf;
+}