Interface IOutboxStore

The outbox store port.

Every method returns a promise that REJECTS on failure and never throws synchronously. Every transition atomically requires the expected status and kind equal to OUTBOX_RECORD_KIND. Claims compare and increment the read version; settlement compares the held version. Every read requires that discriminator. A custom store must honour these rules.

Since

0.9.0

interface IOutboxStore {
    append(scope: IOutboxWriteScope, record: OutboxRecord): Promise<void>;
    claim(
        id: string,
        update: { claimVersion: number; leaseUntil: number },
    ): Promise<OutboxTransition>;
    failedKeys(limit: number): Promise<readonly OutboxKey[]>;
    markFailure(
        id: string,
        update: {
            attempts: number;
            availableAt: number;
            claimVersion: number;
            lastError: string;
            status: "failed" | "pending";
        },
    ): Promise<OutboxTransition>;
    markInvalid(id: string, now: number): Promise<OutboxTransition>;
    markSent(
        id: string,
        update: {
            claimVersion: number;
            deleteNow: boolean;
            sentBy: string;
            settledAt: number;
        },
    ): Promise<OutboxTransition>;
    purge(before: number, limit: number): Promise<number>;
    release(
        id: string,
        action: "retry" | "discard",
        now: number,
    ): Promise<OutboxTransition>;
    scanPending(
        after: string | undefined,
        limit: number,
    ): Promise<readonly OutboxRecord[]>;
    stats(): Promise<OutboxStoreStats>;
    verify(): Promise<void>;
}

Index

Methods

append claim failedKeys markFailure markInvalid markSent purge release scanPending stats verify

Methods

append

append(scope: IOutboxWriteScope, record: OutboxRecord): Promise<void>
Writes a row inside the caller's transaction.
Parameters
- scope: IOutboxWriteScope
  The caller's unit of work
- record: OutboxRecord
  The row to write
Returns Promise<void>
A promise that rejects with the adapter's DuplicateKeyError for a duplicate id
- Defined in packages/common/src/services/outbox.ts:222

claim

claim(
id: string,
update: { claimVersion: number; leaseUntil: number },
): Promise<OutboxTransition>
Claims a pending row at the read version, incrementing that version by one.
Parameters
- id: string
  The row id
- update: { claimVersion: number; leaseUntil: number }
  The read version and the new lease expiry
  - ReadonlyclaimVersion: number
    
    Version read by the caller, in [0, Number.MAX_SAFE_INTEGER - 1].
    
    Since
    0.9.0
  - ReadonlyleaseUntil: number
    
    New claim expiry in epoch milliseconds.
    
    Since
    0.9.0
Returns Promise<OutboxTransition>
applied, missing, not-pending, or claim-lost

Since
0.9.0
- Defined in packages/common/src/services/outbox.ts:252

failedKeys

failedKeys(limit: number): Promise<readonly OutboxKey[]>
Reads the keys of failed rows, never their envelopes.
Parameters
- limit: number
  Maximum keys returned
Returns Promise<readonly OutboxKey[]>
The failed rows' tenant and ordering keys
- Defined in packages/common/src/services/outbox.ts:242

markFailure

markFailure(
    id: string,
    update: {
        attempts: number;
        availableAt: number;
        claimVersion: number;
        lastError: string;
        status: "failed" | "pending";
    },
): Promise<OutboxTransition>
Records a publish failure on a pending row at the held version, clearing its lease.
Parameters
- id: string
  The row id
- update: {
      attempts: number;
      availableAt: number;
      claimVersion: number;
      lastError: string;
      status: "failed" | "pending";
  }
  The held version, attempt count, error line, retry time and status
  - Readonlyattempts: number
  - ReadonlyavailableAt: number
  - ReadonlyclaimVersion: number
    
    Version held by the publishing relay.
    
    Since
    0.9.0
  - ReadonlylastError: string
  - Readonlystatus: "failed" | "pending"
Returns Promise<OutboxTransition>
applied, or why nothing was written
- Defined in packages/common/src/services/outbox.ts:301

markInvalid

markInvalid(id: string, now: number): Promise<OutboxTransition>
Poisons an invalid pending row without a claim, preserving its attempts. Writes failed, invalid-row, availableAt: now, and leaseUntil: 0.
Parameters
- id: string
  The row id
- now: number
  Epoch milliseconds
Returns Promise<OutboxTransition>
applied, missing, or not-pending

Since
0.9.0
- Defined in packages/common/src/services/outbox.ts:271

markSent

markSent(
    id: string,
    update: {
        claimVersion: number;
        deleteNow: boolean;
        sentBy: string;
        settledAt: number;
    },
): Promise<OutboxTransition>
Marks a pending row as sent (or deletes it when deleteNow is set).
Parameters
- id: string
  The row id
- update: { claimVersion: number; deleteNow: boolean; sentBy: string; settledAt: number }
  The held version, settlement time, sending sweep and deletion policy
  - ReadonlyclaimVersion: number
    
    Version held by the sending relay.
    
    Since
    0.9.0
  - ReadonlydeleteNow: boolean
    
    Delete immediately instead of retaining the sent row.
    
    Since
    0.9.0
  - ReadonlysentBy: string
    
    Sending instance and sweep origin, for operator diagnostics.
    
    Since
    0.9.0
  - ReadonlysettledAt: number
    
    Settlement time in epoch milliseconds.
    
    Since
    0.9.0
Returns Promise<OutboxTransition>
applied, or why nothing was written
- Defined in packages/common/src/services/outbox.ts:280

purge

purge(before: number, limit: number): Promise<number>
Deletes sent, then discarded, rows settled before before.
Parameters
- before: number
  Epoch milliseconds; rows with settledAt < before are deleted
- limit: number
  Maximum rows deleted per status
Returns Promise<number>
The number of rows deleted (a row already gone counts zero)
- Defined in packages/common/src/services/outbox.ts:340

release

release(
    id: string,
    action: "retry" | "discard",
    now: number,
): Promise<OutboxTransition>
Releases a failed row: retry returns it to pending with attempts: 0, availableAt: now, leaseUntil: 0 and no lastError, keeping its version; discard makes it discarded with settledAt: now.
Parameters
- id: string
  The row id
- action: "retry" | "discard"
  retry or discard
- now: number
  Epoch milliseconds
Returns Promise<OutboxTransition>
applied, missing, or not-failed
- Defined in packages/common/src/services/outbox.ts:324

scanPending

scanPending(
after: string | undefined,
limit: number,
): Promise<readonly OutboxRecord[]>
Reads pending rows in ascending position order.

Applies NO availableAt filter: the relay decides what a row's backoff means for its key.
Parameters
- after: string | undefined
  Exclusive lower bound on position; undefined reads from the start
- limit: number
  Maximum rows returned
Returns Promise<readonly OutboxRecord[]>
The rows, in position order
- Defined in packages/common/src/services/outbox.ts:234

stats

stats(): Promise<OutboxStoreStats>
Counts pending and failed rows and reads the oldest pending row's age.

Returns Promise<OutboxStoreStats>
The counts
- Defined in packages/common/src/services/outbox.ts:331

verify

verify(): Promise<void>
Refuses, at startup, a backend that cannot serve the outbox.

Returns Promise<void>
A promise that rejects naming why the store cannot serve
- Defined in packages/common/src/services/outbox.ts:347

Interface IOutboxStore

Since

Index

Methods

Methods

append

Parameters

Returns Promise<void>

claim

Parameters

ReadonlyclaimVersion: number

Since

ReadonlyleaseUntil: number

Since

Returns Promise<OutboxTransition>

Since

failedKeys

Parameters

Returns Promise<readonly OutboxKey[]>

markFailure

Parameters

Readonlyattempts: number

ReadonlyavailableAt: number

ReadonlyclaimVersion: number

Since

ReadonlylastError: string

Readonlystatus: "failed" | "pending"

Returns Promise<OutboxTransition>

markInvalid

Parameters

Returns Promise<OutboxTransition>

Since

markSent

Parameters

ReadonlyclaimVersion: number

Since

ReadonlydeleteNow: boolean

Since

ReadonlysentBy: string

Since

ReadonlysettledAt: number

Since

Returns Promise<OutboxTransition>

purge

Parameters

Returns Promise<number>

release

Parameters

Returns Promise<OutboxTransition>

scanPending

Parameters

Returns Promise<readonly OutboxRecord[]>

stats

Returns Promise<OutboxStoreStats>

verify

Returns Promise<void>

Settings

On This Page

`Readonly`claimVersion: number

`Readonly`leaseUntil: number

`Readonly`attempts: number

`Readonly`availableAt: number

`Readonly`claimVersion: number

`Readonly`lastError: string

`Readonly`status: "failed" | "pending"

`Readonly`claimVersion: number

`Readonly`deleteNow: boolean

`Readonly`sentBy: string

`Readonly`settledAt: number