@nwire/envelope

Universal message envelope — correlation, causation, tenant, user, version.

What it is

MessageEnvelope is the small bag of identifiers every message in Nwire carries — an HTTP request, a queue job, a scheduled tick, an action dispatched from a CLI. It makes chains of work debuggable, traceable, and tenant-scoped. Zero-dep leaf package: logger, dead-letter, queue, http, store all depend on this.

Install

pnpm add @nwire/envelope

Standalone use

For developers who want a tiny correlation-id / causation-chain primitive in any TS app — no Nwire dependency required.

import { seedEnvelope, deriveEnvelope } from "@nwire/envelope";

// At the edge — seed a new envelope for an incoming request
const root = seedEnvelope({
  source: "http",
  tenant: "acme",
  userId: req.userId,
});

// Inside a handler — derive a child envelope for the next message
const child = deriveEnvelope(root, { source: "queue" });
// child.correlationId === root.correlationId  (same chain)
// child.causationId   === root.messageId      (parent reference)

Within nwire-app

For developers using this package as part of the Nwire stack. Already transitively present in every layer; you usually read ctx.envelope inside a handler. Touch this package directly when writing a custom transport or bus adapter that must construct envelopes.

// inside a handler:
defineAction("recordWash", {
  handler: async ({ input, ctx }) => {
    ctx.logger.info({ stationId: input.stationId }, "wash recorded");
    // ctx.envelope.correlationId, .tenant, .userId all attached automatically
  },
});

API

• MessageEnvelope — shape: messageId, correlationId, causationId, tenant?, userId?, timestamp, version, source?.
• seedEnvelope(input) — start a new chain at a system edge.
• deriveEnvelope(parent, overrides?) — descend one step; carries correlation, advances causation.
• SeedEnvelopeInput — caller-side type.

See also

• Architecture sketch §05 — Foundation tier
• Sibling packages: @nwire/messages, @nwire/logger, @nwire/queue