Transport Contract Matrix
This matrix pins every first-party transport to its public entry points, source files, and contract tests. It is meant to make reliability claims auditable: raw wire transports must surface delivery failures, production-grade delivery must be explicit about wrappers or queues, and lifecycle behavior must have a named test path.
pnpm verify:transport-contracts checks this page against package exports and the repository file tree. When a transport source file or public transport subpath is added, update this matrix in the same change.
Contract Rules
- Raw HTTP/vendor transports propagate non-2xx responses and rejected
fetchcalls; they do not silently retry unless wrapped. - Production delivery for raw wire sinks requires
batchTransport(),retryTransport(),fallbackTransport(), or a transport that documents its own queue/retry behavior. - Runtime-dependent transports must document the platform surface they depend on and test unavailable or failing dependencies.
- Durable paths must expose
flush()or persistence/replay behavior in tests. - Test-only and display-only transports must say so instead of implying delivery durability.
Matrix
| ID | Public entry | Export(s) | Source | Delivery contract | Failure and lifecycle contract | Contract tests |
|---|---|---|---|---|---|---|
core-batch | @loggerjs/core/transport-batch | batchTransport | packages/core/src/transports/batch.ts | Bounded queue, byte budget, timed flush, concurrency, retry, circuit breaker, and drop accounting around any inner transport. | Failed batches are retried or re-queued according to policy; flush() drains; close() stops timers and flushes pending work. | packages/core/test/batch-transport.test.ts packages/core/test/batch-coverage.test.ts |
core-retry | @loggerjs/core/transport-reliability | retryTransport, fallbackTransport | packages/core/src/transports/reliability.ts | Immediate retry/fallback wrapper for transports that already own batching or need per-call retry. | Retries use bounded backoff; circuit breaker and fallback behavior are observable; flush()/close() delegate to wrapped transports. | packages/core/test/reliability-transport.test.ts packages/core/test/reliability-coverage.test.ts |
core-console | @loggerjs/core/transport-console | consoleTransport | packages/core/src/transports/console.ts | Runtime-neutral local console sink. | Uses unpatched console functions to avoid capture recursion; filters console-origin events by default. | packages/core/test/console-transport.test.ts |
core-memory | Root export | memoryTransport | packages/core/src/transports/memory.ts | Bounded in-memory diagnostics ring buffer; not durable. | Drops oldest entries beyond capacity; snapshots are synchronous and process-local. | packages/core/test/logger.test.ts packages/core/test/integration-api.test.ts |
core-test | @loggerjs/core/transport-test | testTransport | packages/core/src/transports/test.ts | Assertion-only in-memory sink with wait and snapshot helpers. | Injectable failures and wait timeouts are part of the test contract; not a production sink. | packages/core/test/test-transport.test.ts |
browser-http | @loggerjs/browser/transport-http | browserHttpTransport | packages/browser/src/http-transport.ts | Browser fetch delivery with batching, retry options, optional offline queue, payload transforms, and page-exit beacon mode. | Non-2xx and rejected fetch attempts are failures; page-exit beacon is best effort and size/runtime dependent. | packages/browser/test/http-transport.test.ts tests/e2e/browser-production.spec.ts |
browser-indexeddb-queue | @loggerjs/browser/offline-indexeddb, @loggerjs/browser/transport-indexeddb | indexedDbBrowserHttpOfflineQueue, indexedDbTransport | packages/browser/src/indexeddb-offline-queue.ts packages/browser/src/indexeddb-transport.ts | Persistent browser queue/store for reload-surviving replay and local export. | IndexedDB unavailability, quota, private mode, blocked upgrades, TTL, and pruning are runtime-dependent and tested. | packages/browser/test/indexeddb-offline-queue.test.ts packages/browser/test/indexeddb-transport.test.ts tests/e2e/browser-production.spec.ts |
browser-offline-first | @loggerjs/browser/offline-first-transport | offlineFirstTransport | packages/browser/src/offline-first-transport.ts | Remote-first delivery with queued replay after offline or remote failure. | Remote rejection queues payloads; flush() replays queued records when storage and network are available. | packages/browser/test/offline-first-transport.test.ts |
browser-page-exit | @loggerjs/browser/transport-http, @loggerjs/browser/integration-page-lifecycle | browserHttpTransport page lifecycle flush | packages/browser/src/http-transport.ts packages/browser/src/page-lifecycle.ts | Last-chance pagehide/visibilitychange delivery for browser HTTP. | sendBeacon is best effort; unsupported or failed beacon falls back to configured HTTP behavior where possible. | packages/browser/test/http-transport.test.ts packages/browser/test/page-lifecycle.test.ts tests/e2e/browser-production.spec.ts |
browser-service-worker | @loggerjs/browser/transport-service-worker | browserServiceWorkerTransport | packages/browser/src/service-worker-transport.ts | Queue until a configured or ready service worker controller is available, then post messages. | Registration/controller availability is runtime-dependent; ready() and flush() expose acceptance boundaries. | packages/browser/test/service-worker-transport.test.ts tests/e2e/browser-production.spec.ts |
browser-websocket | @loggerjs/browser/transport-websocket | browserWebSocketTransport | packages/browser/src/websocket-transport.ts | Live WebSocket sink with bounded queue while connecting or closed. | Reconnection is caller-owned; queue bounds and close/error behavior are explicit. | packages/browser/test/websocket-transport.test.ts |
browser-broadcast | @loggerjs/browser/transport-broadcast-channel | browserBroadcastChannelTransport | packages/browser/src/broadcast-channel-transport.ts | Same-origin tab fan-out via BroadcastChannel. | Receiver presence is not guaranteed; missing API and close semantics are tested. | packages/browser/test/broadcast-channel-transport.test.ts |
node-http | @loggerjs/node/transport-http | nodeHttpTransport | packages/node/src/http-transport.ts | Node fetch delivery self-wrapped in batchTransport. | Non-2xx/rejected fetch attempts are retried by the wrapper; flush() drains batched HTTP work. | packages/node/test/http-transport.test.ts |
node-file | @loggerjs/node/transport-file, @loggerjs/node/transport-rotating-file | fileTransport, rotatingFileTransport | packages/node/src/file-transport.ts packages/node/src/rotating-file-transport.ts | Local NDJSON file durability, optional synchronous writes, buffering, and size rotation. | flush() drains normal writes; flushSync() is the crash-path contract where supported; rotation is single-writer. | packages/node/test/file-transport.test.ts packages/node/test/rotating-file-transport.test.ts |
node-stdout | @loggerjs/node/transport-stdout | stdoutTransport, stderrTransport | packages/node/src/stdout-transport.ts | NDJSON stream sink for stdout/stderr with optional buffering. | Backpressure is drain-aware; EPIPE is treated as clean shutdown by default; flush() drains buffered writes. | packages/node/test/stdout-transport.test.ts |
node-syslog | @loggerjs/node/transport-syslog | nodeSyslogTransport | packages/node/src/syslog-transport.ts | RFC-style syslog formatting over UDP or TCP. | UDP is lossy; TCP depends on socket lifecycle; format, send, close, and error behavior are tested. | packages/node/test/syslog-transport.test.ts |
node-worker | @loggerjs/node/transport-worker | workerTransport | packages/node/src/worker-transport.ts | Worker-thread offload with codec transfer and optional ready/ack handshake. | Startup, ack timeout, fallback, close, and auto-end behavior define the acceptance boundary. | packages/node/test/worker-transport.test.ts |
database | @loggerjs/database/transport, @loggerjs/database/sqlite, @loggerjs/database/postgres | databaseTransport, sqliteTransport, postgresTransport | packages/database/src/transport.ts packages/database/src/sqlite.ts packages/database/src/postgres.ts | Batched row mapping to an application-provided adapter, SQLite driver, or Postgres client. | Adapter/driver failures surface through batch/retry and internal error reporting; transaction semantics are driver-owned. | packages/database/test/database-transport.test.ts |
datadog | @loggerjs/datadog/transport | datadogLogsTransport | packages/datadog/src/index.ts | Raw Datadog Logs HTTP payload sink. | Missing fetch, non-2xx, and rejected fetch fail the raw transport; production durability requires batchTransport() or retryTransport(). | packages/datadog/test/datadog-transport.test.ts |
elastic | @loggerjs/elastic/transport | elasticTransport | packages/elastic/src/index.ts | Raw Elastic bulk HTTP payload sink. | Missing fetch, non-2xx, and rejected fetch fail the raw transport; production durability requires batchTransport() or retryTransport(). | packages/elastic/test/elastic-transport.test.ts |
loki | @loggerjs/loki/transport | lokiTransport | packages/loki/src/index.ts | Raw Loki push HTTP payload sink. | Missing fetch, non-2xx, and rejected fetch fail the raw transport; production durability requires batchTransport() or retryTransport(). | packages/loki/test/loki-transport.test.ts |
cloudwatch | @loggerjs/cloudwatch/transport | cloudWatchLogsTransport | packages/cloudwatch/src/index.ts | Raw CloudWatch Logs API payload sink. | Missing fetch, non-2xx, and rejected fetch fail the raw transport; sequence-token progression remains caller/service dependent. | packages/cloudwatch/test/cloudwatch-transport.test.ts |
sentry | @loggerjs/sentry/transport | sentryTransport | packages/sentry/src/index.ts | Adapter to an application-provided Sentry SDK object. | SDK throws fail the raw transport and are observable by wrappers; capture-level mapping and disabled SDK methods are tested. | packages/sentry/test/sentry-transport.test.ts |
otel-otlp | @loggerjs/otel/transport-http, @loggerjs/otel/codec-otlp-json | otlpHttpTransport, otlpJsonCodec | packages/otel/src/transport.ts packages/otel/src/otlp-json.ts | OTLP/HTTP JSON delivery self-wrapped in batchTransport; codec maps LoggerJS events to OTLP logs. | Non-2xx/rejected fetch attempts are retried by the wrapper; codec shape and metadata mapping are pinned. | packages/otel/test/otlp-json.test.ts |
pretty-console | @loggerjs/pretty/transport-console | prettyConsoleTransport | packages/pretty/src/console-transport.ts | Human-readable browser/console display sink. | Display-only; avoids console capture loops and preserves raw arguments for DevTools. | packages/pretty/test/console-transport.test.ts |
pretty-stream | @loggerjs/pretty/transport-stream | prettyStreamTransport, prettyStdoutTransport, prettyStderrTransport | packages/pretty/src/stream-transport.ts | Human-readable stream sink for Node terminals or stream-like targets. | Backpressure and stream errors are visible; flush() waits for drain where supported. | packages/pretty/test/stream-transport.test.ts |