Documentation Index
Fetch the complete documentation index at: https://abxbus.archivebox.io/llms.txt
Use this file to discover all available pages before exploring further.
find(...) is the unified lookup API: search history, wait for future events, or combine both.
Interface
await bus.find(
event_type, # Event class, event type string, or '*'
where: Callable[[BaseEvent], bool] | None = None,
child_of: BaseEvent | None = None,
past: bool | float | timedelta = True,
future: bool | float = False,
**event_fields, # equality filters (event_status='completed', request_id='abc', ...)
)
await bus.find(event_pattern, options?)
await bus.find(event_pattern, where, options?)
// options:
{
past?: boolean | number // seconds when number
future?: boolean | number // seconds when number
child_of?: BaseEvent | null
[event_field: string]: unknown // equality filters, e.g. event_status: 'completed'
}
Option semantics
past
true: search all history (default)false: skip historynumber (or timedelta in Python): search recent history window
future
false: do not wait (default)true: wait indefinitelynumber: wait up to N seconds
where: predicate filterchild_of: match only descendants of the given parent eventevent_fields: strict equality filters on event fields/metadata
Default behavior when omitted is history-only lookup (past=True, future=False).
Common use cases
1) History lookup only (non-blocking)
existing = await bus.find(ResponseEvent)
const existing = await bus.find(ResponseEvent)
2) Wait only for future events
future = await bus.find(ResponseEvent, past=False, future=5)
const future = await bus.find(ResponseEvent, { past: false, future: 5 })
3) Check recent history, then keep waiting briefly
match = await bus.find(ResponseEvent, past=5, future=5)
const match = await bus.find(ResponseEvent, { past: 5, future: 5 })
4) Filter by fields + predicate
match = await bus.find(
ResponseEvent,
where=lambda e: e.request_id == my_id,
event_status='completed',
future=5,
)
const match = await bus.find(
ResponseEvent,
(event) => event.request_id === myId,
{ event_status: 'completed', future: 5 }
)
5) Wildcard lookup across all event types
any_completed = await bus.find(
'*',
where=lambda e: e.event_type.endswith('ResultEvent'),
event_status='completed',
future=5,
)
const anyCompleted = await bus.find(
'*',
(event) => event.event_type.endsWith('ResultEvent'),
{ event_status: 'completed', future: 5 }
)
6) Find descendants of a specific parent event
parent_event = await bus.emit(NavigateToUrlEvent(url='https://example.com'))
child = await bus.find(TabCreatedEvent, child_of=parent_event, past=5)
const parentEvent = await bus.emit(NavigateToUrlEvent({ url: 'https://example.com' })).done()
const child = await bus.find(TabCreatedEvent, { child_of: parentEvent, past: 5 })
7) Debounce expensive work
event = (
await bus.find(ScreenshotEvent, past=10, future=False)
or await bus.find(ScreenshotEvent, past=False, future=5)
or bus.emit(ScreenshotEvent())
)
await event
const event =
(await bus.find(ScreenshotEvent, { past: 10, future: false })) ??
(await bus.find(ScreenshotEvent, { past: false, future: 5 })) ??
bus.emit(ScreenshotEvent({}))
await event.done()
Important behavior
find() resolves when an event is emitted, not when handlers finish.- To wait for handler completion, await the returned event (
await event in Python, await event.done() in TypeScript).
- If no match is found (or
future times out), find() returns None / null.
- If both
past and future are false, it returns immediately with no match.