On this page
Overview
Persists complete mail reports before delivery and normalizes idempotent enqueue, retry, reconciliation, and invalid-record maintenance.
- Artifact
MailOutbox.mjs· esm - Classification
public first party - Availability
Browser/native WebView or compatible injected host with durable storage, Web Locks, and a delivery function - Normalization
Complete records, idempotency and retry/reconciliation state, full drains/inventory, cancellation, and invalid-record maintenance are normalized; storage, lock, and delivery failures are coded.
Import and lifecycle
import * as module from '/arcane/modules/MailOutbox.mjs';
Construction validates caller-owned DBOPFS-compatible storage, Web Locks, delivery, clock, and online-event adapters. enqueue() persists complete content before delivery; start() owns the online listener; drain() serializes FIFO attempts; stop() detaches the listener and its owned online drain without deleting records.
Application-facing behavior: Protocol/table/window/state constants; MailOutbox, factory/default; read-only lifecycle diagnostics; record inspection and maintenance; enqueue, drain, start, and stop.
Protocol and host implementation
arcane-mail-outbox/1 + injected durable storage + Web Locks + AbortSignal + online EventTarget This detail does not widen the application-facing API or grant authority.
Exports, signatures, parameters, and results
| Binding | Form | Declaration or signature | Parameter syntax |
|---|---|---|---|
MAIL_OUTBOX_PROTOCOL | variable · value | variable MAIL_OUTBOX_PROTOCOL | — |
MAIL_OUTBOX_TABLE | variable · value | variable MAIL_OUTBOX_TABLE | — |
MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS | variable · value | variable MAIL_OUTBOX_IDEMPOTENCY_WINDOW_MS | — |
MAIL_OUTBOX_STATES | variable · value | variable MAIL_OUTBOX_STATES | — |
MailOutbox | class | class MailOutbox | — |
createMailOutbox | function | function createMailOutbox(options) | options |
default | default · class | class MailOutbox | — |
| Member | Kind | Exact public declaration | Parameter syntax |
|---|---|---|---|
MailOutbox.constructor | constructor | constructor({
storage,
deliver,
clock=Date.now,
isOnline=function defaultOnlineStatus(){
return globalThis.navigator?.onLine!==false;
},
lockManager=undefined,
onlineTarget=is.function(globalThis.addEventListener)?globalThis:null,
onRecordCommitted=null,
quarantineTable=QUARANTINE_TABLE,
table=MAIL_OUTBOX_TABLE
}={}) | {
storage,
deliver,
clock=Date.now,
isOnline=function defaultOnlineStatus(){
return globalThis.navigator?.onLine!==false;
},
lockManager=undefined,
onlineTarget=is.function(globalThis.addEventListener)?globalThis:null,
onRecordCommitted=null,
quarantineTable=QUARANTINE_TABLE,
table=MAIL_OUTBOX_TABLE
}={} |
MailOutbox.started | get | get started() | — |
MailOutbox.invalidRecords | get | get invalidRecords() | — |
MailOutbox.lastBackgroundError | get | get lastBackgroundError() | — |
MailOutbox.get | async method | async get(key) | key |
MailOutbox.list | async method | async list() | — |
MailOutbox.audit | async method | async audit() | — |
MailOutbox.deleteInvalid | async method | async deleteInvalid(fileName) | fileName |
MailOutbox.repairInvalid | async method | async repairInvalid(fileName,replacement) | fileName,replacement |
MailOutbox.quarantineInvalid | async method | async quarantineInvalid() | — |
MailOutbox.enqueue | async method | async enqueue({report,reportKey:key}={}, {attempt=true,signal=null}={}) | {report,reportKey:key}={}, {attempt=true,signal=null}={} |
MailOutbox.drain | async method | async drain({reason='manual',signal=null}={}) | {reason='manual',signal=null}={} |
MailOutbox.start | async method | async start({signal=null}={}) | {signal=null}={} |
MailOutbox.stop | method | stop() | — |
Parameter meanings and results
new MailOutbox(options={}); enqueue({report,reportKey},{attempt=true,signal=null}={}); drain({reason='manual',signal=null}={}); get(key); list(); audit(); deleteInvalid(fileName); repairInvalid(fileName,replacement); quarantineInvalid(); start({signal=null}={}); stop(). Accepted delivery results require requestId; providerId and acceptanceAuthority are optional transport metadata, and records and summaries remain complete mutable values. createMailOutbox(options) returns the same validated contract.
Events, side effects, and errors
Source-literal CustomEvent dispatches
No source-literal CustomEvent dispatch is part of this artifact.
Lifecycle and event flow
This artifact has no additional documented lifecycle event flow.
Direct coded failures
This artifact directly assigns no stable coded failure.
Exported Error subclasses
This artifact exports no Error subclass.
Documented failure behavior
- MAIL_OUTBOX_INVALID
- MAIL_OUTBOX_RECORD_INVALID
- MAIL_OUTBOX_DELIVERY_RESULT_INVALID
- MAIL_OUTBOX_STORAGE_UNAVAILABLE
- MAIL_OUTBOX_LOCK_UNAVAILABLE
- MAIL_OUTBOX_STORAGE_FAILED
- MAIL_OUTBOX_IDEMPOTENCY_CONFLICT
- MAIL_OUTBOX_ABORTED
Availability and capabilities
Browser/native WebView or compatible injected host with durable storage, Web Locks, and a delivery function. Complete records, idempotency and retry/reconciliation state, full drains/inventory, cancellation, and invalid-record maintenance are normalized; storage, lock, and delivery failures are coded.
None. Delivery authority belongs to the injected transport or Core adapter. An accepted result requires requestId; providerId and acceptanceAuthority are optional transport metadata, and acceptance is not inbox-delivery proof.
Contract example
import {createMailOutbox} from '/arcane/modules/MailOutbox.mjs';
const outbox=createMailOutbox({storage,lockManager,deliver});
await outbox.start();
Related reference
No direct Core call is claimed for this artifact. Any injected provider or consuming module retains its own documented authority.