basalt / events/src / OutboxPluginOptions
Interface: OutboxPluginOptions
Defined in: events/src/outbox.ts:553
Extends
Properties
backoff?
> optional backoff?: false | OutboxBackoff
Defined in: events/src/outbox.ts:233
Retry backoff for failed entries. Tracked per relay process (no store/schema change): after a failure the entry is skipped by this process's flushes until its delay elapses. A restart forgets the backoff — worst case one immediate retry, still at-least-once. Pass false to retry on every flush (old behavior).
Inherited from
batchSize?
> optional batchSize?: number
Defined in: events/src/outbox.ts:561
captureEvents?
> optional captureEvents?: string[]
Defined in: events/src/outbox.ts:558
Capture these event patterns into the outbox automatically (needs @basaltkit/events).
claimLeaseMs?
> optional claimLeaseMs?: number
Defined in: events/src/outbox.ts:269
How long a relay's claim on an entry lasts (stores implementing claim). While claimed no other relay dispatches it; if the relay dies mid-dispatch the claim expires and another relay takes the entry over (at-least-once). Must exceed your slowest dispatch. Default 300_000 (5 minutes).
Inherited from
concurrency?
> optional concurrency?: number
Defined in: events/src/outbox.ts:246
Entries of one batch dispatched in parallel. Default 8, so one slow or hanging downstream (e.g. one tenant's webhook endpoint) cannot serialize the whole batch behind it. Dispatch starts in createdAt order; set 1 for strictly sequential delivery.
Inherited from
dispatch
> dispatch: OutboxDispatch
Defined in: events/src/outbox.ts:556
Delivers a committed entry to the outside world (webhooks, Kafka, …).
dispatchTimeoutMs?
> optional dispatchTimeoutMs?: number | false
Defined in: events/src/outbox.ts:262
How long a flush waits on one dispatch before it stops waiting and moves on (default 10_000 ms; false waits indefinitely). The dispatch is NOT cancelled or failed: it keeps running "detached", its outcome is recorded when it settles, and the entry is not re-dispatched while it runs — so no duplicate and no lost result. This bounds how long one hanging downstream can hold a flush (and with it every other tenant's next tick).
Inherited from
OutboxOptions.dispatchTimeoutMs
intervalMs?
> optional intervalMs?: number
Defined in: events/src/outbox.ts:560
Poll interval in ms to flush the outbox. Omit to flush manually via OUTBOX.
maxAttempts?
> optional maxAttempts?: number
Defined in: events/src/outbox.ts:226
Attempts before an entry is left as dead (excluded from future flushes). Default 10.
Inherited from
now?
> optional now?: () => number
Defined in: events/src/outbox.ts:270
Returns
number
Inherited from
onDead?
> optional onDead?: (entry, error) => void
Defined in: events/src/outbox.ts:239
Called once when an entry exhausts maxAttempts and will no longer be flushed (it stays in the store with its lastError for inspection). Default: console.error — dead events should never be silent.
Parameters
entry
error
unknown
Returns
void
Inherited from
onFlushError?
> optional onFlushError?: (error) => void
Defined in: events/src/outbox.ts:567
A timer/shutdown flush failed at the store level (e.g. pending() threw). Per-entry dispatch failures are NOT this — they are marked on the entry. Default: console.error. Must never throw.
Parameters
error
unknown
Returns
void
store?
> optional store?: OutboxStore
Defined in: events/src/outbox.ts:554
tenantConcurrency?
> optional tenantConcurrency?: number
Defined in: events/src/outbox.ts:253
Most dispatches ONE tenant may have in flight at once — across flushes, counting detached ones (see dispatchTimeoutMs). Entries recorded without a tenant share one "global" slot budget. Default ceil(concurrency / 2), so a tenant whose downstream hangs can never hold every worker.