abxbus 2.4.1

package/dist/types/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/types/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;
+}

package/dist/types/event_result.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import { BaseEvent } from './base_event.js';
+import type { EventBus } from './event_bus.js';
+import { EventHandler } from './event_handler.js';
+import { type HandlerLock } from './lock_manager.js';
+import type { Deferred } from './lock_manager.js';
+import type { EventResultType } from './types.js';
+export type EventResultStatus = 'pending' | 'started' | 'completed' | 'error';
+export declare const EventResultJSONSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        started: "started";
+        completed: "completed";
+        error: "error";
+    }>;
+    event_id: z.ZodString;
+    handler_id: z.ZodString;
+    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.ZodOptional<z.ZodString>;
+    handler_event_pattern: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"*">]>>;
+    eventbus_name: z.ZodString;
+    eventbus_id: z.ZodString;
+    started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    completed_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodUnknown>;
+    event_children: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type EventResultJSON = z.infer<typeof EventResultJSONSchema>;
+export declare class EventResult<TEvent extends BaseEvent = BaseEvent> {
+    id: string;
+    status: EventResultStatus;
+    event: TEvent;
+    handler: EventHandler;
+    started_at: string | null;
+    completed_at: string | null;
+    result?: EventResultType<TEvent>;
+    error?: unknown;
+    event_children: BaseEvent[];
+    _abort: Deferred<never> | null;
+    _lock: HandlerLock | null;
+    _queue_jump_pause_releases: Map<EventBus, () => void> | null;
+    constructor(params: {
+        event: TEvent;
+        handler: EventHandler;
+    });
+    toString(): string;
+    get event_id(): string;
+    get bus(): EventBus;
+    get handler_id(): string;
+    get handler_name(): string;
+    get handler_file_path(): string | null;
+    get eventbus_name(): string;
+    get eventbus_id(): string;
+    get eventbus_label(): string;
+    private getHookBus;
+    private _notifyStatusHook;
+    get value(): EventResultType<TEvent> | undefined;
+    get result_type(): TEvent['event_result_type'];
+    _linkEmittedChildEvent(child_event: BaseEvent): void;
+    get raw_value(): EventResultType<TEvent> | undefined;
+    get handler_timeout(): number | null;
+    get handler_slow_timeout(): number | null;
+    _createSlowHandlerWarningTimer(effective_timeout: number | null): ReturnType<typeof setTimeout> | null;
+    _ensureQueueJumpPause(bus: EventBus): void;
+    _releaseQueueJumpPauses(): void;
+    update(params: {
+        status?: EventResultStatus;
+        result?: EventResultType<TEvent> | BaseEvent | undefined;
+        error?: unknown;
+    }): this;
+    private _createHandlerTimeoutError;
+    private _handleHandlerError;
+    private _onHandlerExit;
+    runHandler(handler_lock: HandlerLock | null): Promise<void>;
+    _signalAbort(error: Error): void;
+    _markStarted(notify_hook?: boolean): Promise<never>;
+    _markCompleted(result: EventResultType<TEvent> | BaseEvent | undefined, notify_hook?: boolean): void;
+    _markError(error: unknown, notify_hook?: boolean): void;
+    toJSON(): EventResultJSON;
+    static fromJSON<TEvent extends BaseEvent>(event: TEvent, data: unknown): EventResult<TEvent>;
+}

package/dist/types/events_suck.d.ts

@@ -0,0 +1,40 @@
+import { EventBus } from './event_bus.js';
+import { BaseEvent } from './base_event.js';
+import type { EventClass, EventResultType } from './types.js';
+type EventMap = Record<string, EventClass<BaseEvent>>;
+type AnyFn = (...args: any[]) => any;
+type FunctionMap = Record<string, AnyFn>;
+type ExtraDict = Record<string, unknown>;
+type EventFieldsFromFn<TFunc extends AnyFn> = Parameters<TFunc> extends [infer TArg] ? (TArg extends Record<string, unknown> ? TArg : ExtraDict) : ExtraDict;
+type GeneratedEvent<TFunc extends AnyFn> = {
+    (data: EventFieldsFromFn<TFunc> & ExtraDict): BaseEvent & EventFieldsFromFn<TFunc> & {
+        __event_result_type__?: Awaited<ReturnType<TFunc>>;
+    };
+    new (data: EventFieldsFromFn<TFunc> & ExtraDict): BaseEvent & EventFieldsFromFn<TFunc> & {
+        __event_result_type__?: Awaited<ReturnType<TFunc>>;
+    };
+    event_type?: string;
+};
+export type GeneratedEvents<TEvents extends FunctionMap> = {
+    by_name: {
+        [K in keyof TEvents]: GeneratedEvent<TEvents[K]>;
+    };
+} & {
+    [K in keyof TEvents]: GeneratedEvent<TEvents[K]>;
+};
+type EventInit<TEventClass extends EventClass<BaseEvent>> = ConstructorParameters<TEventClass> extends [infer TInit, ...unknown[]] ? TInit : never;
+type EventMethodArgs<TEventClass extends EventClass<BaseEvent>> = {} extends EventInit<TEventClass> ? [init?: EventInit<TEventClass>, extra?: Record<string, unknown>] : [init: EventInit<TEventClass>, extra?: Record<string, unknown>];
+type EventMethodResult<TEventClass extends EventClass<BaseEvent>> = EventResultType<InstanceType<TEventClass>> | undefined;
+export type EventsSuckClient<TEvents extends EventMap> = {
+    bus: EventBus;
+} & {
+    [K in keyof TEvents]: (...args: EventMethodArgs<TEvents[K]>) => Promise<EventMethodResult<TEvents[K]>>;
+};
+export type EventsSuckClientClass<TEvents extends EventMap> = new (bus?: EventBus) => EventsSuckClient<TEvents>;
+export declare const make_events: <TEvents extends FunctionMap>(events: TEvents) => GeneratedEvents<TEvents>;
+export declare const wrap: <TEvents extends EventMap>(class_name: string, methods: TEvents) => EventsSuckClientClass<TEvents>;
+export declare const events_suck: {
+    readonly make_events: <TEvents extends FunctionMap>(events: TEvents) => GeneratedEvents<TEvents>;
+    readonly wrap: <TEvents extends EventMap>(class_name: string, methods: TEvents) => EventsSuckClientClass<TEvents>;
+};
+export {};

package/dist/types/helpers.d.ts

@@ -0,0 +1 @@
+export declare function monotonicDatetime(isostring?: string): string;

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+export { BaseEvent, BaseEventSchema } from './base_event.js';
+export { EventHistory } from './event_history.js';
+export type { EventHistoryFindOptions, EventHistoryTrimOptions } from './event_history.js';
+export { EventResult } from './event_result.js';
+export { EventBus } from './event_bus.js';
+export type { EventBusJSON, EventBusOptions } from './event_bus.js';
+export { monotonicDatetime } from './helpers.js';
+export type { EventBusMiddleware, EventBusMiddlewareCtor, EventBusMiddlewareInput } from './middlewares.js';
+export { EventHandlerTimeoutError, EventHandlerCancelledError, EventHandlerAbortedError, EventHandlerResultSchemaError, } from './event_handler.js';
+export type { EventConcurrencyMode, EventHandlerConcurrencyMode, EventHandlerCompletionMode, EventBusInterfaceForLockManager, } from './lock_manager.js';
+export type { EventClass, EventHandlerCallable as EventHandler, EventPattern, EventStatus, FindOptions, FindWindow } from './types.js';
+export { retry, clearSemaphoreRegistry, RetryTimeoutError, SemaphoreTimeoutError } from './retry.js';
+export type { RetryOptions } from './retry.js';
+export { HTTPEventBridge, SocketEventBridge, NATSEventBridge, RedisEventBridge, PostgresEventBridge, JSONLEventBridge, SQLiteEventBridge, } from './bridges.js';
+export type { HTTPEventBridgeOptions } from './bridges.js';
+export { events_suck } from './events_suck.js';
+export type { EventsSuckClient, EventsSuckClientClass, GeneratedEvents } from './events_suck.js';

package/dist/types/lock_manager.d.ts

@@ -0,0 +1,70 @@
+import type { BaseEvent } from './base_event.js';
+import type { EventResult } from './event_result.js';
+export type Deferred<T> = {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+};
+export declare const withResolvers: <T>() => Deferred<T>;
+export declare const EVENT_CONCURRENCY_MODES: readonly ["global-serial", "bus-serial", "parallel"];
+export type EventConcurrencyMode = (typeof EVENT_CONCURRENCY_MODES)[number];
+export declare const EVENT_HANDLER_CONCURRENCY_MODES: readonly ["serial", "parallel"];
+export type EventHandlerConcurrencyMode = (typeof EVENT_HANDLER_CONCURRENCY_MODES)[number];
+export declare const EVENT_HANDLER_COMPLETION_MODES: readonly ["all", "first"];
+export type EventHandlerCompletionMode = (typeof EVENT_HANDLER_COMPLETION_MODES)[number];
+export declare class AsyncLock {
+    size: number;
+    in_use: number;
+    waiters: Array<() => void>;
+    constructor(size: number);
+    acquire(): Promise<void>;
+    release(): void;
+}
+export declare const runWithLock: <T>(lock: AsyncLock | null, fn: () => Promise<T>) => Promise<T>;
+export type HandlerExecutionState = 'held' | 'yielded' | 'closed';
+export declare class HandlerLock {
+    private lock;
+    private state;
+    constructor(lock: AsyncLock | null);
+    yieldHandlerLockForChildRun(): boolean;
+    reclaimHandlerLockIfRunning(): Promise<boolean>;
+    exitHandlerRun(): void;
+    runQueueJump<T>(fn: () => Promise<T>): Promise<T>;
+}
+export type EventBusInterfaceForLockManager = {
+    isIdleAndQueueEmpty: () => boolean;
+    event_concurrency: EventConcurrencyMode;
+    _lock_for_event_global_serial: AsyncLock;
+};
+export type LockManagerOptions = {
+    auto_schedule_idle_checks?: boolean;
+};
+export declare class LockManager {
+    private bus;
+    private auto_schedule_idle_checks;
+    readonly bus_event_lock: AsyncLock;
+    private pause_depth;
+    private pause_waiters;
+    private active_handler_results;
+    private idle_waiters;
+    private idle_check_pending;
+    private idle_check_streak;
+    constructor(bus: EventBusInterfaceForLockManager, options?: LockManagerOptions);
+    _requestRunloopPause(): () => void;
+    _waitUntilRunloopResumed(): Promise<void>;
+    _isPaused(): boolean;
+    _runWithHandlerDispatchContext<T>(result: EventResult, fn: () => Promise<T>): Promise<T>;
+    _getActiveHandlerResult(): EventResult | undefined;
+    _getActiveHandlerResults(): EventResult[];
+    _isAnyHandlerActive(): boolean;
+    waitForIdle(timeout_seconds?: number | null): Promise<boolean>;
+    _notifyIdleListeners(): void;
+    getLockForEvent(event: BaseEvent): AsyncLock | null;
+    _runWithEventLock<T>(event: BaseEvent, fn: () => Promise<T>, options?: {
+        bypass_event_locks?: boolean;
+        pre_acquired_lock?: AsyncLock | null;
+    }): Promise<T>;
+    _runWithHandlerLock<T>(event: BaseEvent, default_handler_concurrency: EventHandlerConcurrencyMode | undefined, fn: (lock: HandlerLock | null) => Promise<T>): Promise<T>;
+    private scheduleIdleCheck;
+    clear(): void;
+}

package/dist/types/logging.d.ts

@@ -0,0 +1,16 @@
+import { BaseEvent } from './base_event.js';
+import { EventResult } from './event_result.js';
+type LogTreeBus = {
+    name: string;
+    event_history: {
+        values(): IterableIterator<BaseEvent>;
+        has(event_id: string): boolean;
+    };
+    toString?: () => string;
+};
+export declare const logTree: (bus: LogTreeBus) => string;
+export declare const buildTreeLine: (event: BaseEvent, indent: string, is_last: boolean, parent_to_children: Map<string, BaseEvent[]>, visited: Set<string>) => string;
+export declare const buildResultLine: (result: EventResult, indent: string, is_last: boolean, parent_to_children: Map<string, BaseEvent[]>, visited: Set<string>) => string;
+export declare const formatTimestamp: (value?: string) => string;
+export declare const formatResultValue: (value: unknown) => string;
+export {};

package/dist/types/middlewares.d.ts

@@ -0,0 +1,13 @@
+import type { BaseEvent } from './base_event.js';
+import type { EventBus } from './event_bus.js';
+import type { EventHandler } from './event_handler.js';
+import type { EventResult } from './event_result.js';
+import type { EventStatus } from './types.js';
+export type { EventStatus } from './types.js';
+export interface EventBusMiddleware {
+    onEventChange?(eventbus: EventBus, event: BaseEvent, status: EventStatus): void | Promise<void>;
+    onEventResultChange?(eventbus: EventBus, event: BaseEvent, event_result: EventResult, status: EventStatus): void | Promise<void>;
+    onBusHandlersChange?(eventbus: EventBus, handler: EventHandler, registered: boolean): void | Promise<void>;
+}
+export type EventBusMiddlewareCtor = new () => EventBusMiddleware;
+export type EventBusMiddlewareInput = EventBusMiddleware | EventBusMiddlewareCtor;

package/dist/types/optional_deps.d.ts

@@ -0,0 +1,3 @@
+export declare const isNodeRuntime: () => boolean;
+export declare const assertOptionalDependencyAvailable: (bridge_name: string, package_name: string) => void;
+export declare const importOptionalDependency: (bridge_name: string, package_name: string) => Promise<any>;

package/dist/types/retry.d.ts

@@ -0,0 +1,52 @@
+export interface RetryOptions {
+    /** Total number of attempts including the initial call (1 = no retry, 3 = up to 2 retries). Default: 1 */
+    max_attempts?: number;
+    /** Seconds to wait between retries. Default: 0 */
+    retry_after?: number;
+    /** Multiplier applied to retry_after after each attempt for exponential backoff. Default: 1.0 (constant delay) */
+    retry_backoff_factor?: number;
+    /** Only retry when the thrown error matches one of these matchers. Accepts error class constructors,
+     *  string error names (matched against error.name), or RegExp patterns (tested against String(error)).
+     *  Default: undefined (retry on any error) */
+    retry_on_errors?: Array<(new (...args: any[]) => Error) | string | RegExp>;
+    /** Per-attempt timeout in seconds. Default: undefined (no per-attempt timeout) */
+    timeout?: number | null;
+    /** Maximum concurrent executions sharing this semaphore. Default: undefined (no concurrency limit) */
+    semaphore_limit?: number | null;
+    /** Semaphore identifier. Functions with the same name share the same concurrency slot pool. Default: function name.
+     *  If a function is provided, it receives the same arguments as the wrapped function. */
+    semaphore_name?: string | ((...args: any[]) => string) | null;
+    /** If true, proceed without concurrency limit when semaphore acquisition times out. Default: true */
+    semaphore_lax?: boolean;
+    /** Semaphore scoping strategy. Default: 'global'
+     *  - 'global': all calls share one semaphore (keyed by semaphore_name)
+     *  - 'class': all instances of the same class share one semaphore (keyed by className.semaphore_name)
+     *  - 'instance': each object instance gets its own semaphore (keyed by instanceId.semaphore_name)
+     *  'class' and 'instance' require `this` to be an object; they fall back to 'global' for standalone calls. */
+    semaphore_scope?: 'global' | 'class' | 'instance';
+    /** Maximum seconds to wait for semaphore acquisition. Default: undefined → timeout * max(1, limit - 1) */
+    semaphore_timeout?: number | null;
+}
+/** Thrown when a single attempt exceeds the per-attempt timeout. */
+export declare class RetryTimeoutError extends Error {
+    timeout_seconds: number;
+    attempt: number;
+    constructor(message: string, params: {
+        timeout_seconds: number;
+        attempt: number;
+    });
+}
+/** Thrown (when semaphore_lax=false) if the semaphore cannot be acquired within the timeout. */
+export declare class SemaphoreTimeoutError extends Error {
+    semaphore_name: string;
+    semaphore_limit: number;
+    timeout_seconds: number;
+    constructor(message: string, params: {
+        semaphore_name: string;
+        semaphore_limit: number;
+        timeout_seconds: number;
+    });
+}
+/** Reset the global semaphore registry. Useful in tests. */
+export declare function clearSemaphoreRegistry(): void;
+export declare function retry(options?: RetryOptions): <T extends (...args: any[]) => any>(target: T, _context?: ClassMethodDecoratorContext) => T;

package/dist/types/timing.d.ts

@@ -0,0 +1,3 @@
+export declare function _runWithTimeout<T>(timeout_seconds: number | null, on_timeout: () => Error, fn: () => Promise<T>): Promise<T>;
+export declare function _runWithSlowMonitor<T>(slow_timer: ReturnType<typeof setTimeout> | null, fn: () => Promise<T>): Promise<T>;
+export declare function _runWithAbortMonitor<T>(fn: () => T | Promise<T>, abort_signal: Promise<never>): Promise<T>;

package/dist/types/type_inference.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/types.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import type { BaseEvent } from './base_event.js';
+export type EventStatus = 'pending' | 'started' | 'completed';
+export type EventClass<T extends BaseEvent = BaseEvent> = {
+    event_type?: string;
+} & (new (...args: any[]) => T);
+export type EventPattern<T extends BaseEvent = BaseEvent> = string | EventClass<T>;
+export type EventWithResultSchema<TResult> = BaseEvent & {
+    __event_result_type__?: TResult;
+};
+export type EventResultType<TEvent extends BaseEvent> = TEvent extends {
+    __event_result_type__?: infer TResult;
+} ? TResult : unknown;
+export type EventResultTypeConstructor = StringConstructor | NumberConstructor | BooleanConstructor | ArrayConstructor | ObjectConstructor;
+export type EventResultTypeInput = z.ZodTypeAny | EventResultTypeConstructor | unknown;
+export type EventHandlerReturn<T extends BaseEvent = BaseEvent> = EventResultType<T> | BaseEvent | null | void;
+export type EventHandlerCallable<T extends BaseEvent = BaseEvent> = (event: T) => EventHandlerReturn<T> | Promise<EventHandlerReturn<T>>;
+export type UntypedEventHandlerFunction<T extends BaseEvent = BaseEvent> = (event: T) => EventHandlerReturn<T> | unknown | Promise<EventHandlerReturn<T> | unknown>;
+export type FindWindow = boolean | number;
+type FindReservedOptionKeys = 'past' | 'future' | 'child_of';
+type EventFilterFields<T extends BaseEvent> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : symbol extends K ? never : K extends FindReservedOptionKeys ? never : T[K] extends (...args: any[]) => any ? never : K]?: T[K];
+};
+export type FindOptions<T extends BaseEvent = BaseEvent> = {
+    past?: FindWindow;
+    future?: FindWindow;
+    child_of?: BaseEvent | null;
+} & EventFilterFields<T> & Record<string, unknown>;
+export declare const normalizeEventPattern: (event_pattern: EventPattern | "*") => string | "*";
+export declare const isZodSchema: (value: unknown) => value is z.ZodTypeAny;
+export declare const eventResultTypeFromConstructor: (value: unknown) => z.ZodTypeAny | undefined;
+export declare const extractZodShape: (raw: Record<string, unknown>) => z.ZodRawShape;
+export declare const toJsonSchema: (schema: unknown) => unknown;
+export declare const fromJsonSchema: (schema: unknown) => z.ZodTypeAny;
+export declare const normalizeEventResultType: (value: EventResultTypeInput) => z.ZodTypeAny | undefined;
+export {};

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "abxbus",
+  "version": "2.4.1",
+  "description": "Event bus library for browsers and ESM Node.js",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "default": "./dist/esm/index.js"
+    },
+    "./*": {
+      "types": "./dist/types/*.d.ts",
+      "import": "./dist/esm/*.js",
+      "require": "./dist/cjs/*.js",
+      "default": "./dist/esm/*.js"
+    }
+  },
+  "files": [
+    "dist/cjs",
+    "dist/esm",
+    "dist/types"
+  ],
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "uuid": "^13.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.55.0",
+    "@typescript-eslint/parser": "^8.55.0",
+    "esbuild": "^0.27.3",
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.1",
+    "tsc-files": "^1.1.4",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ArchiveBox/abx-bus.git",
+    "directory": "abxbus-ts"
+  },
+  "bugs": {
+    "url": "https://github.com/ArchiveBox/abx-bus/issues"
+  },
+  "homepage": "https://abxbus.archivebox.io",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "optionalDependencies": {
+    "ioredis": "^5.9.3",
+    "nats": "^2.29.3",
+    "pg": "^8.18.0"
+  },
+  "scripts": {
+    "build": "pnpm run build:esm && pnpm run build:cjs && pnpm run build:types && pnpm run build:cjs:types",
+    "build:esm": "node ./scripts/build_esm.mjs",
+    "build:cjs": "node ./scripts/build_cjs.mjs",
+    "build:cjs:types": "node ./scripts/copy_types_to_cjs.mjs",
+    "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "prettier": "prettier --write .",
+    "eslint": "eslint .",
+    "lint": "pnpm run prettier && pnpm run eslint && pnpm run typecheck",
+    "test": "NODE_OPTIONS='--expose-gc' node --expose-gc --test --import tsx \"tests/**/*.test.ts\"",
+    "perf": "pnpm run perf:node && pnpm run perf:bun && pnpm run perf:deno && pnpm run perf:browser",
+    "debug:node": "NODE_OPTIONS='--expose-gc' node --expose-gc --import tsx",
+    "debug:bun": "bun --expose-gc run",
+    "debug:deno": "deno run --sloppy-imports --v8-flags=--expose-gc",
+    "perf:node": "pnpm run build && pnpm run debug:node -- tests/performance.runtime.ts --scenario 50k-events && pnpm run debug:node -- tests/performance.runtime.ts --scenario 500-buses-x-100-events && pnpm run debug:node -- tests/performance.runtime.ts --scenario 1-event-x-50k-parallel-handlers && pnpm run debug:node -- tests/performance.runtime.ts --scenario 50k-one-off-handlers && pnpm run debug:node -- tests/performance.runtime.ts --scenario worst-case-forwarding-timeouts && pnpm run debug:node -- tests/performance.runtime.ts --scenario cleanup-equivalence",
+    "perf:bun": "pnpm run build && pnpm run debug:bun -- tests/performance.runtime.ts --scenario 50k-events && pnpm run debug:bun -- tests/performance.runtime.ts --scenario 500-buses-x-100-events && pnpm run debug:bun -- tests/performance.runtime.ts --scenario 1-event-x-50k-parallel-handlers && pnpm run debug:bun -- tests/performance.runtime.ts --scenario 50k-one-off-handlers && pnpm run debug:bun -- tests/performance.runtime.ts --scenario worst-case-forwarding-timeouts && pnpm run debug:bun -- tests/performance.runtime.ts --scenario cleanup-equivalence",
+    "perf:deno": "pnpm run build && pnpm run debug:deno -- tests/performance.runtime.ts --scenario 50k-events && pnpm run debug:deno -- tests/performance.runtime.ts --scenario 500-buses-x-100-events && pnpm run debug:deno -- tests/performance.runtime.ts --scenario 1-event-x-50k-parallel-handlers && pnpm run debug:deno -- tests/performance.runtime.ts --scenario 50k-one-off-handlers && pnpm run debug:deno -- tests/performance.runtime.ts --scenario worst-case-forwarding-timeouts && pnpm run debug:deno -- tests/performance.runtime.ts --scenario cleanup-equivalence",
+    "perf:browser": "pnpm run build && bash ./scripts/run_browser_perf.sh",
+    "release:dry-run": "pnpm publish --access public --dry-run --no-git-checks",
+    "release:check": "pnpm run typecheck && pnpm test && pnpm run build"
+  }
+}