Class: OutboxService
Defined in: server/checkout/outbox-service.ts:133
The transactional-outbox dispatcher (proposal §Hooks + transactional outbox).
Money / at-least-once code: each deliverPendingEvents pass claims the
per-order head events under a short transaction + lease, delivers them to the
CheckoutHooks outside any transaction (consumer I/O never holds a row
lock), then marks the outcome in a second short transaction. Ordering is
seq, per order; a failing / dead-lettered head blocks its order's later
events while other orders keep flowing. A dispatcher crash self-heals when
the lease expires (redelivery — which is why hooks MUST be idempotent).
The library runs no loop — the consumer schedules deliverPendingEvents
(proposal §Operational checklist).
Constructors
Constructor
new OutboxService(deps: CheckoutFeatureDeps, config?: {
hooks?: CheckoutHooks;
observer?: CheckoutObserver;
}): OutboxService;Defined in: server/checkout/outbox-service.ts:137
Parameters
| Parameter | Type |
|---|---|
deps | CheckoutFeatureDeps |
config | { hooks?: CheckoutHooks; observer?: CheckoutObserver; } |
config.hooks? | CheckoutHooks |
config.observer? | CheckoutObserver |
Returns
OutboxService
Methods
deliverPendingEvents()
deliverPendingEvents(options?: DeliverPendingEventsOptions): Promise<DeliverPendingEventsResult>;Defined in: server/checkout/outbox-service.ts:158
One dispatch pass. Claims up to batchSize per-order heads, delivers each
to its hook, marks the outcome. Returns per-pass counters. Call in a loop /
on a schedule until claimed === 0 to drain the queue.
Parameters
| Parameter | Type |
|---|---|
options | DeliverPendingEventsOptions |
Returns
Promise<DeliverPendingEventsResult>
health()
health(organizationId?: string): Promise<OutboxHealth>;Defined in: server/checkout/outbox-service.ts:395
Operational health (proposal §Operational checklist — wire into monitoring on day one). All four metrics are cheap aggregate reads.
Parameters
| Parameter | Type |
|---|---|
organizationId? | string |
Returns
Promise<OutboxHealth>
listDeadLettered()
listDeadLettered(organizationId: string): Promise<BigIntsAsNumbers<{
attempts: number;
createdAt: Date;
createdBy: string | null;
deadLetteredAt: Date | null;
id: string;
lastError: string | null;
leaseToken: string | null;
nextAttemptAt: Date | null;
orderId: string;
organizationId: string;
payload: JsonValue;
processedAt: Date | null;
seq: bigint;
type: string;
updatedAt: Date;
updatedBy: string | null;
}>[]>;Defined in: server/checkout/outbox-service.ts:353
Dead-lettered events for operator triage (proposal §Operational checklist).
Parameters
| Parameter | Type |
|---|---|
organizationId | string |
Returns
Promise<BigIntsAsNumbers<{
attempts: number;
createdAt: Date;
createdBy: string | null;
deadLetteredAt: Date | null;
id: string;
lastError: string | null;
leaseToken: string | null;
nextAttemptAt: Date | null;
orderId: string;
organizationId: string;
payload: JsonValue;
processedAt: Date | null;
seq: bigint;
type: string;
updatedAt: Date;
updatedBy: string | null;
}>[]>
pruneDelivered()
pruneDelivered(before: Date, organizationId?: string): Promise<number>;Defined in: server/checkout/outbox-service.ts:434
Hard-delete processed events older than before — the module's one
supported hard delete (proposal §Retry + dead-letter; recommended default
90 days). Returns the deleted count. Pending / dead-lettered rows survive.
Parameters
| Parameter | Type |
|---|---|
before | Date |
organizationId? | string |
Returns
Promise<number>
requeueEvent()
requeueEvent(organizationId: string, id: string): Promise<BigIntsAsNumbers<{
attempts: number;
createdAt: Date;
createdBy: string | null;
deadLetteredAt: Date | null;
id: string;
lastError: string | null;
leaseToken: string | null;
nextAttemptAt: Date | null;
orderId: string;
organizationId: string;
payload: JsonValue;
processedAt: Date | null;
seq: bigint;
type: string;
updatedAt: Date;
updatedBy: string | null;
}>>;Defined in: server/checkout/outbox-service.ts:364
Requeue a dead-lettered event: clear the dead-letter mark and reset the retry state so the event — and, since it is its order's blocking head, its order's later events — resume delivery on the next pass.
Parameters
| Parameter | Type |
|---|---|
organizationId | string |
id | string |
Returns
Promise<BigIntsAsNumbers<{
attempts: number;
createdAt: Date;
createdBy: string | null;
deadLetteredAt: Date | null;
id: string;
lastError: string | null;
leaseToken: string | null;
nextAttemptAt: Date | null;
orderId: string;
organizationId: string;
payload: JsonValue;
processedAt: Date | null;
seq: bigint;
type: string;
updatedAt: Date;
updatedBy: string | null;
}>>
skipEvent()
skipEvent(organizationId: string, id: string): Promise<void>;Defined in: server/checkout/outbox-service.ts:382
Skip an event: mark it processed WITHOUT delivering it. Unblocks its order's queue when a dead head can't be delivered (proposal §Retry + dead-letter). The consumer accepts the gap.
Parameters
| Parameter | Type |
|---|---|
organizationId | string |
id | string |
Returns
Promise<void>