abxbus 2.4.28 → 2.4.30

package/dist/types/EventBus.d.ts

@@ -4,7 +4,7 @@ import { EventResult } from './EventResult.js';
 import { AsyncLock, type EventConcurrencyMode, type EventHandlerConcurrencyMode, type EventHandlerCompletionMode, LockManager } from './LockManager.js';
 import { EventHandler, type EphemeralFindEventHandler, type EventHandlerJSON } from './EventHandler.js';
 import type { EventBusMiddleware, EventBusMiddlewareInput } from './EventBusMiddleware.js';
-import type { EventClass, EventHandlerCallable, EventPattern, FindOptions, UntypedEventHandlerFunction } from './types.js';
+import type { EventClass, EventHandlerCallable, EventPattern, FilterOptions, FindOptions, UntypedEventHandlerFunction } from './types.js';
 export type EventBusOptions = {
     id?: string;
     max_history_size?: number | null;
@@ -104,6 +104,10 @@ export declare class EventBus {
     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>;
+    filter(event_pattern: '*', options?: FilterOptions<BaseEvent>): Promise<BaseEvent[]>;
+    filter(event_pattern: '*', where: (event: BaseEvent) => boolean, options?: FilterOptions<BaseEvent>): Promise<BaseEvent[]>;
+    filter<T extends BaseEvent>(event_pattern: EventPattern<T>, options?: FilterOptions<T>): Promise<T[]>;
+    filter<T extends BaseEvent>(event_pattern: EventPattern<T>, where: (event: T) => boolean, options?: FilterOptions<T>): Promise<T[]>;
     private _waitForFutureMatch;
     waitUntilIdle(timeout?: number | null): Promise<boolean>;
     isIdle(): boolean;

package/dist/types/EventHistory.d.ts

@@ -7,6 +7,9 @@ export type EventHistoryFindOptions = {
     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 EventHistoryFilterOptions = EventHistoryFindOptions & {
+    limit?: number | null;
+};
 export type EventHistoryTrimOptions<TEvent extends BaseEvent = BaseEvent> = {
     is_event_complete?: (event: TEvent) => boolean;
     on_remove?: (event: TEvent) => void;
@@ -40,6 +43,8 @@ export declare class EventHistory<TEvent extends BaseEvent = BaseEvent> implemen
     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>;
+    filter(event_pattern: '*', where?: (event: TEvent) => boolean, options?: EventHistoryFilterOptions): Promise<TEvent[]>;
+    filter<TMatch extends TEvent>(event_pattern: EventPattern<TMatch>, where?: (event: TMatch) => boolean, options?: EventHistoryFilterOptions): Promise<TMatch[]>;
     trimEventHistory(options?: EventHistoryTrimOptions<TEvent>): number;
     private eventIsChildOf;
 }

package/dist/types/TachyonEventBridge.d.ts

@@ -0,0 +1,25 @@
+import { BaseEvent } from './BaseEvent.js';
+import type { EventClass, EventHandlerCallable, UntypedEventHandlerFunction } from './types.js';
+export declare class TachyonEventBridge {
+    readonly path: string;
+    readonly capacity: number;
+    readonly name: string;
+    private readonly inbound_bus;
+    private listener_worker;
+    private acted_as_listener;
+    private listener_startup_error;
+    private sender_worker;
+    private sender_ready_promise;
+    private send_seq;
+    private pending_sends;
+    private closed;
+    constructor(path: string, capacity?: 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 ensureListenerStarted;
+    private ensureSenderConnected;
+}

package/dist/types/bridges.d.ts

@@ -7,3 +7,4 @@ export { SQLiteEventBridge } from './SQLiteEventBridge.js';
 export { NATSEventBridge } from './NATSEventBridge.js';
 export { RedisEventBridge } from './RedisEventBridge.js';
 export { PostgresEventBridge } from './PostgresEventBridge.js';
+export { TachyonEventBridge } from './TachyonEventBridge.js';

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 export { BaseEvent, BaseEventSchema } from './BaseEvent.js';
 export { EventHistory } from './EventHistory.js';
-export type { EventHistoryFindOptions, EventHistoryTrimOptions } from './EventHistory.js';
+export type { EventHistoryFilterOptions, EventHistoryFindOptions, EventHistoryTrimOptions } from './EventHistory.js';
 export { EventResult } from './EventResult.js';
 export { EventBus } from './EventBus.js';
 export type { EventBusJSON, EventBusOptions } from './EventBus.js';
@@ -14,7 +14,7 @@ export type { EventBusMiddleware, EventBusMiddlewareCtor, EventBusMiddlewareInpu
 export { monotonicDatetime } from './helpers.js';
 export { EventHandlerTimeoutError, EventHandlerCancelledError, EventHandlerAbortedError, EventHandlerResultSchemaError, } from './EventHandler.js';
 export type { EventConcurrencyMode, EventHandlerConcurrencyMode, EventHandlerCompletionMode, EventBusInterfaceForLockManager, } from './LockManager.js';
-export type { EventClass, EventHandlerCallable as EventHandler, EventPattern, EventStatus, FindOptions, FindWindow } from './types.js';
+export type { EventClass, EventHandlerCallable as EventHandler, EventPattern, EventStatus, FilterOptions, FindOptions, FindWindow, } from './types.js';
 export { retry, clearSemaphoreRegistry, RetryTimeoutError, SemaphoreTimeoutError } from './retry.js';
 export type { RetryOptions } from './retry.js';
 export { events_suck } from './events_suck.js';

package/dist/types/types.d.ts

@@ -26,6 +26,9 @@ export type FindOptions<T extends BaseEvent = BaseEvent> = {
     future?: FindWindow;
     child_of?: BaseEvent | null;
 } & EventFilterFields<T> & Record<string, unknown>;
+export type FilterOptions<T extends BaseEvent = BaseEvent> = FindOptions<T> & {
+    limit?: number | null;
+};
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "abxbus",
-  "version": "2.4.28",
+  "version": "2.4.30",
   "description": "Event bus library for browsers and ESM Node.js",
   "type": "module",
   "sideEffects": false,
@@ -46,35 +46,38 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "uuid": "^13.0.0",
-    "zod": "^4.3.6"
+    "uuid": "^14.0.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
-    "@opentelemetry/resources": "^2.7.0",
-    "@opentelemetry/sdk-trace-base": "^2.7.0",
-    "@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",
-    "ioredis": "^5.9.3",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.217.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@tachyon-ipc/core": "^0.5.0",
+    "@types/node": "^25.6.1",
+    "@typescript-eslint/eslint-plugin": "^8.59.2",
+    "@typescript-eslint/parser": "^8.59.2",
+    "cmake-js": "^8.0.0",
+    "esbuild": "^0.28.0",
+    "eslint": "^10.3.0",
+    "ioredis": "^5.10.1",
     "nats": "^2.29.3",
-    "pg": "^8.18.0",
-    "prettier": "^3.8.1",
+    "pg": "^8.20.0",
+    "prettier": "^3.8.3",
     "tsc-files": "^1.1.4",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/exporter-trace-otlp-http": "^0.215.0",
-    "@opentelemetry/resources": "^2.7.0",
-    "@opentelemetry/sdk-trace-base": "^2.7.0",
-    "ioredis": "^5.9.3",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.217.0",
+    "@opentelemetry/resources": "^2.7.1",
+    "@opentelemetry/sdk-trace-base": "^2.7.1",
+    "@tachyon-ipc/core": "^0.5.0",
+    "ioredis": "^5.10.1",
     "nats": "^2.29.3",
-    "pg": "^8.18.0"
+    "pg": "^8.20.0"
   },
   "peerDependenciesMeta": {
     "@opentelemetry/api": {
@@ -89,6 +92,9 @@
     "@opentelemetry/sdk-trace-base": {
       "optional": true
     },
+    "@tachyon-ipc/core": {
+      "optional": true
+    },
     "ioredis": {
       "optional": true
     },

package/src/EventBus.ts

@@ -24,7 +24,7 @@ import { v7 as uuidv7 } from 'uuid'
 import { monotonicDatetime } from './helpers.js'
 
 import { normalizeEventPattern } from './types.js'
-import type { EventClass, EventHandlerCallable, EventPattern, FindOptions, UntypedEventHandlerFunction } from './types.js'
+import type { EventClass, EventHandlerCallable, EventPattern, FilterOptions, FindOptions, UntypedEventHandlerFunction } from './types.js'
 
 export type EventBusOptions = {
   id?: string
@@ -782,16 +782,39 @@ export class EventBus {
   ): Promise<T | null> {
     const where = typeof where_or_options === 'function' ? where_or_options : () => true
     const options = typeof where_or_options === 'function' ? maybe_options : where_or_options
-    const match = await this.event_history.find(event_pattern as EventPattern<T> | '*', where, {
+    // `limit` field-equality filter would collide with filter()'s cap arg; route it through `where`.
+    let effective_where = where
+    let effective_options: FindOptions<T> = options
+    if (Object.prototype.hasOwnProperty.call(options, 'limit')) {
+      const { limit: limit_field_value, ...rest } = options as FindOptions<T> & { limit: unknown }
+      const inner_where = where
+      effective_where = (event: T) => (event as unknown as Record<string, unknown>).limit === limit_field_value && inner_where(event)
+      effective_options = rest as unknown as FindOptions<T>
+    }
+    const results = await this.filter(event_pattern as EventPattern<T> | '*', effective_where, { ...effective_options, limit: 1 })
+    return results.length > 0 ? results[0] : null
+  }
+
+  // same as find() but returns the list of all matching events (newest to oldest)
+  // optional `limit` arg caps the number of results returned
+  filter(event_pattern: '*', options?: FilterOptions<BaseEvent>): Promise<BaseEvent[]>
+  filter(event_pattern: '*', where: (event: BaseEvent) => boolean, options?: FilterOptions<BaseEvent>): Promise<BaseEvent[]>
+  filter<T extends BaseEvent>(event_pattern: EventPattern<T>, options?: FilterOptions<T>): Promise<T[]>
+  filter<T extends BaseEvent>(event_pattern: EventPattern<T>, where: (event: T) => boolean, options?: FilterOptions<T>): Promise<T[]>
+  async filter<T extends BaseEvent>(
+    event_pattern: EventPattern<T> | '*',
+    where_or_options: ((event: T) => boolean) | FilterOptions<T> = {},
+    maybe_options: FilterOptions<T> = {}
+  ): Promise<T[]> {
+    const where = typeof where_or_options === 'function' ? where_or_options : () => true
+    const options = typeof where_or_options === 'function' ? maybe_options : where_or_options
+    const matches = await this.event_history.filter(event_pattern as EventPattern<T> | '*', where, {
       ...options,
       event_is_child_of: (event, ancestor) => this.eventIsChildOf(event, ancestor),
-      wait_for_future_match: (normalized_event_pattern, matches, future) =>
-        this._waitForFutureMatch(normalized_event_pattern, matches, future),
+      wait_for_future_match: (normalized_event_pattern, matches_fn, future) =>
+        this._waitForFutureMatch(normalized_event_pattern, matches_fn, future),
     })
-    if (!match) {
-      return null
-    }
-    return this._getEventProxyScopedToThisBus(match) as T
+    return matches.map((match) => this._getEventProxyScopedToThisBus(match) as T)
   }
 
   private async _waitForFutureMatch(
@@ -1000,8 +1023,13 @@ export class EventBus {
       original_event.event_blocks_parent_completion = true
     }
 
-    // ensure a pause request is set so the bus _runloop pauses and (will resume when the handler exits)
-    currently_active_event_result._ensureQueueJumpPause(this)
+    // Serial event modes need the runloop paused while the queue-jumped child
+    // runs so queued siblings cannot overshoot the suspended parent handler.
+    // Parallel events have no event lock, so pausing here would incorrectly
+    // block later parallel work emitted by the same parent.
+    if (this.locks.getLockForEvent(original_event) !== null) {
+      currently_active_event_result._ensureQueueJumpPause(this)
+    }
     if (original_event.event_status === 'completed') {
       return event
     }

package/src/EventHistory.ts

@@ -15,6 +15,8 @@ export type EventHistoryFindOptions = {
   ) => Promise<BaseEvent | null>
 } & Record<string, unknown>
 
+export type EventHistoryFilterOptions = EventHistoryFindOptions & { limit?: number | null }
+
 export type EventHistoryTrimOptions<TEvent extends BaseEvent = BaseEvent> = {
   is_event_complete?: (event: TEvent) => boolean
   on_remove?: (event: TEvent) => void
@@ -109,13 +111,45 @@ export class EventHistory<TEvent extends BaseEvent = BaseEvent> implements Itera
     where: (event: TEvent) => boolean = () => true,
     options: EventHistoryFindOptions = {}
   ): Promise<TEvent | null> {
+    // `limit` field-equality filter would collide with filter()'s cap arg; route it through `where`.
+    let effective_where = where
+    let effective_options: EventHistoryFindOptions = options
+    if (Object.prototype.hasOwnProperty.call(options, 'limit')) {
+      const { limit: limit_field_value, ...rest } = options as EventHistoryFindOptions & { limit: unknown }
+      const inner_where = where
+      effective_where = (event: TEvent) => (event as unknown as Record<string, unknown>).limit === limit_field_value && inner_where(event)
+      effective_options = rest as EventHistoryFindOptions
+    }
+    const results = await this.filter(event_pattern as EventPattern<TEvent> | '*', effective_where, {
+      ...effective_options,
+      limit: 1,
+    })
+    return results.length > 0 ? results[0] : null
+  }
+
+  filter(event_pattern: '*', where?: (event: TEvent) => boolean, options?: EventHistoryFilterOptions): Promise<TEvent[]>
+  filter<TMatch extends TEvent>(
+    event_pattern: EventPattern<TMatch>,
+    where?: (event: TMatch) => boolean,
+    options?: EventHistoryFilterOptions
+  ): Promise<TMatch[]>
+  async filter(
+    event_pattern: EventPattern<TEvent> | '*',
+    where: (event: TEvent) => boolean = () => true,
+    options: EventHistoryFilterOptions = {}
+  ): Promise<TEvent[]> {
     const past = options.past ?? true
     const future = options.future ?? false
     const child_of = options.child_of ?? null
     const eventIsChildOf = options.event_is_child_of ?? ((event: BaseEvent, ancestor: BaseEvent) => this.eventIsChildOf(event, ancestor))
     const waitForFutureMatch = options.wait_for_future_match
+    const limit = options.limit ?? null
     if (past === false && future === false) {
-      return null
+      return []
+    }
+
+    if (limit !== null && limit <= 0) {
+      return []
     }
 
     const event_key = EventHistory.normalizeEventPattern(event_pattern)
@@ -128,6 +162,7 @@ export class EventHistory<TEvent extends BaseEvent = BaseEvent> implements Itera
         key !== 'child_of' &&
         key !== 'event_is_child_of' &&
         key !== 'wait_for_future_match' &&
+        key !== 'limit' &&
         value !== undefined
     )
 
@@ -137,6 +172,7 @@ export class EventHistory<TEvent extends BaseEvent = BaseEvent> implements Itera
       event_field_filters.every(([field_name, expected]) => (event as unknown as Record<string, unknown>)[field_name] === expected) &&
       where(event as TEvent)
 
+    const results: TEvent[] = []
     if (past !== false) {
       const history_values = Array.from(this._events.values())
       for (let i = history_values.length - 1; i >= 0; i -= 1) {
@@ -145,16 +181,23 @@ export class EventHistory<TEvent extends BaseEvent = BaseEvent> implements Itera
           continue
         }
         if (matches(event)) {
-          return event
+          results.push(event)
+          if (limit !== null && results.length >= limit) {
+            return results
+          }
         }
       }
     }
 
     if (future === false || !waitForFutureMatch) {
-      return null
+      return results
     }
 
-    return (await waitForFutureMatch(event_key, matches, future)) as TEvent | null
+    const future_match = (await waitForFutureMatch(event_key, matches, future)) as TEvent | null
+    if (future_match !== null) {
+      results.push(future_match)
+    }
+    return results
   }
 
   trimEventHistory(options: EventHistoryTrimOptions<TEvent> = {}): number {