Skip to content

Events API Reference ​

Everything on this page is imported from @holo-js/events.

Available methods ​

Every function, method, and option you can use in app code, grouped by task. Each item links to its own entry below.

Define

Listener options

Dispatch

Pending dispatch

Registry lookups

Results and types

Errors and CLI

Define ​

defineEvent() ​

ts
defineEvent<TPayload, TName extends string | undefined = string | undefined>(
  event: { name?: TName },
): DefinedEventDefinition<TPayload, TName>

Defines an event. TPayload is the payload type. TName is optional; pass the event name as a literal to get event.name narrowing in multi-event listeners.

ts
import { defineEvent } from '@holo-js/events'

export default defineEvent<{ userId: string, email: string }, 'user.registered'>({
  name: 'user.registered',
})

The only option is name, a string. It's recommended. If you leave it out, Holo derives the name from the file path under server/events.

defineListener() ​

ts
defineListener(listener: ListenerDefinitionInput): ListenerDefinition

Defines a listener for one or more events. The options are listed under Listener options.

ts
import { defineListener } from '@holo-js/events'
import UserRegistered from '../../events/user/registered'

export default defineListener({
  listensTo: [UserRegistered],
  queue: true,
  queueName: 'emails',
  afterCommit: true,
  async handle(event) {
    console.log(event.payload.email)
  },
})

definition.dispatch() ​

Every event from defineEvent() has a dispatch(payload) method. It returns a pending dispatch and requires the event to have an explicit name.

ts
import UserRegistered from '../events/user/registered'

await UserRegistered.dispatch({ userId: 'user_1', email: '[email protected]' })

Listener options ​

Pass these to defineListener(). Options marked "requires queue: true" throw an error on a sync listener.

listensTo ​

Required. The event, or array of events, this listener handles. Each item is an event definition or an event name string. It must have at least one entry.

handle() ​

Required. handle(event) runs for each matching event. It receives an EventEnvelope and can be async.

name ​

Optional string. The listener's ID. getRegisteredListener() looks it up by this value. If you leave it out, Holo derives an ID from the file path under server/listeners, joined with dots.

queue ​

Optional boolean. When true, the listener runs in a queue worker instead of inline during the dispatch. The payload must be JSON-safe. See Queued listeners.

connection ​

Optional string. The queue connection for this listener. Requires queue: true. A .onConnection() call on a dispatch overrides it.

queueName ​

Optional string. The queue name for this listener. Requires queue: true. A .onQueue() call on a dispatch overrides it.

delay ​

Optional. Seconds to wait before the queued listener runs, as a number of zero or more, or a Date to run at. Requires queue: true. A .delay() call on a dispatch overrides it.

afterCommit ​

Optional boolean. When true, the listener runs after the current database transaction commits. See After-commit events.

Dispatch ​

dispatchEvent() ​

ts
dispatchEvent(event: EventDefinition | string, payload): EventPendingDispatch

Dispatches an event by definition or by name. With a registered name, the payload is typed from Holo's generated event types.

ts
import { dispatchEvent } from '@holo-js/events'

await dispatchEvent('user.registered', { userId: 'user_1', email: '[email protected]' })

Event.dispatch() ​

Event is an object with one method, dispatch(). It is the same function as dispatchEvent().

ts
import { Event } from '@holo-js/events'
import UserRegistered from '../events/user/registered'

await Event.dispatch(UserRegistered, { userId: 'user_1', email: '[email protected]' })

Pending dispatch ​

Every dispatch form returns an EventPendingDispatch. Nothing runs until you await it or call .dispatch(), .then(), .catch(), or .finally(). It runs at most once. Chain methods return a new pending dispatch, so they can be combined in any order.

.afterCommit() ​

Defers every listener for this dispatch, sync and queued, until the current transaction commits. See After-commit events.

.onConnection(name) ​

Sends the queued listeners of this dispatch to another queue connection. It overrides each listener's connection. Sync listeners are not affected.

.onQueue(name) ​

Sends the queued listeners of this dispatch to another queue name. It overrides each listener's queueName.

.delay(value) ​

Delays the queued listeners of this dispatch, in seconds or until a Date. It overrides each listener's delay. An invalid value throws when you call .delay().

.dispatch() ​

Runs the dispatch and returns a promise of EventDispatchResult.

.then(), .catch(), .finally() ​

The standard promise methods. await and these methods all start the dispatch.

Registry lookups ​

These read the events and listeners that Holo discovered. They are read-only.

getRegisteredEvent() ​

ts
getRegisteredEvent(name: string): RegisteredEvent | undefined

Returns the registered event with this name, or undefined.

listRegisteredEvents() ​

ts
listRegisteredEvents(): readonly RegisteredEvent[]

Returns every registered event, sorted by name.

getRegisteredListener() ​

ts
getRegisteredListener(id: string): RegisteredListener | undefined

Returns the registered listener with this ID, or undefined.

listRegisteredListeners() ​

ts
listRegisteredListeners(): readonly RegisteredListener[]

Returns every registered listener, sorted by ID.

listRegisteredListenersForEvent() ​

ts
listRegisteredListenersForEvent(eventName: string): readonly RegisteredListener[]

Returns the listeners for one event, in the order they were registered. A dispatch runs them in this order.

Results and types ​

EventDispatchResult ​

The value a dispatch resolves to.

FieldTypeDescription
eventNamestringThe dispatched event name.
occurredAtnumberDispatch time in milliseconds since the Unix epoch.
deferredbooleantrue if any listener is waiting for a commit.
syncListenersnumberNumber of sync listeners for this dispatch.
queuedListenersnumberNumber of queued listeners for this dispatch.

EventEnvelope ​

The object passed to a listener's handle().

FieldTypeDescription
namestring (or the literal name)The event name.
payloadTPayloadThe dispatched payload.
occurredAtnumberDispatch time in milliseconds since the Unix epoch.

Useful types ​

TypeDescription
EventPayloadFor<'user.registered'>The payload type of a registered event, by name.
ListenerHandledEvent<typeof UserRegistered>The event argument type for a listener of that event.
EventDelayValuenumber | Date.
ts
import { type EventPayloadFor } from '@holo-js/events'

type RegisteredPayload = EventPayloadFor<'user.registered'>

Common errors ​

MessageCause
Event "<name>" is not registered.The event file isn't in server/events, or discovery hasn't run since you added it.
Dispatching an event definition requires an explicit event name.The event has no name. Add one.
Listener queue metadata requires queue: true.connection, queueName, or delay set on a sync listener.
Listeners must listen to at least one event.listensTo is an empty array.
Event payload at "<path>" must be JSON-serializable for queued listeners.A queued listener exists and the payload contains a non-JSON value.
Queued listeners require @holo-js/queue to be installed.A listener has queue: true but queue support isn't installed.

CLI commands ​

CommandDescription
npx holo install eventsAdd events to an existing project.
npx holo make:event <name>Create an event in server/events. user/registered creates user.registered.
npx holo make:listener <name> --event <event-name>Create a listener. Repeat --event, or separate names with commas, to listen to several events.
npx holo prepareRefresh discovered events, listeners, and generated types.

Released under the MIT License.