@relaybus/core 0.3.1 → 0.4.1

package/dist/internal/index.d.ts

@@ -1,4 +1,4 @@
-import { b as EventHeaders, E as EventEnvelope, h as Clock, L as LeaseReference, d as ErrorInfo, j as ClaimRequest, C as ClaimedDelivery, T as Transport, U as TransportMessageHandler, V as TransportSubscriptionHooks, p as CloseOptions, D as Duration } from '../transport-BlfzIBZD.js';
+import { EventHeaders, EventEnvelope, Clock, LeaseReference, ErrorInfo, ClaimRequest, ClaimedDelivery, Transport, TransportMessageHandler, TransportSubscriptionHooks, CloseOptions, Duration } from '../index.js';
 
 /** Returns `value` when it is an integer of at least 1, else throws a {@link ConfigurationError} naming the option. */
 declare function assertPositiveInteger(value: number, name: string): number;
@@ -82,26 +82,60 @@ type WireField = BodyField | HeaderField;
 type FixedType = {
     readonly fixed: string;
 };
+/**
+ * How `occurredAt` travels: RFC 3339 text (default), or whole epoch milliseconds or seconds, a
+ * number in the body and decimal text in a header. Epoch seconds drop the milliseconds.
+ */
+type TimeFormat = 'rfc3339' | 'epoch-millis' | 'epoch-seconds';
+/** Where the event time lives, and in which format. */
+type TimeField<TField extends WireField> = TField & {
+    readonly format?: TimeFormat;
+};
+/** A JSON value written as it is. */
+type JsonConstant = string | number | boolean | null | readonly JsonConstant[] | {
+    readonly [name: string]: JsonConstant;
+};
+/** A value written with every message: a constant, or derived from the event. */
+type ExtraValue<TValue> = TValue | ((envelope: EventEnvelope) => TValue);
+/** Extra message headers, by name. */
+type ExtraHeaders = Readonly<Record<string, ExtraValue<string>>>;
+/** Extra body values, by dotted path. */
+type ExtraBody = Readonly<Record<string, ExtraValue<JsonConstant>>>;
 type MappingFields<TField extends WireField, TTransportId extends string> = {
     /** Where the event type lives, or the one type of the route. Required. */
     readonly type: TField | FixedType;
     /**
      * Where the event id lives, or the transport's own message identity (see the transport's
      * mapping type). Required, so the inbox dedup key is always a deliberate choice. A message
-     * whose mapped id is missing is malformed.
+     * whose mapped id is missing is malformed, unless `whenMissing` names the transport's own id
+     * to use instead: `{ body: 'id', whenMissing: 'record-position' }`.
      */
-    readonly id: TField | TTransportId;
+    readonly id: TField | TTransportId | (TField & {
+        readonly whenMissing: TTransportId;
+    });
     /** Ordering key. Default: the transport's own (the Kafka record key; none on RabbitMQ). */
     readonly key?: TField;
     /** Producing service. Default: the transport's own (Kafka topic; RabbitMQ `appId`, else the routing key). */
     readonly source?: TField;
-    /** RFC 3339 time. Default: the transport's own (Kafka record timestamp; RabbitMQ `timestamp`, seconds). */
-    readonly occurredAt?: TField;
+    /**
+     * Event time, RFC 3339 unless `format` says otherwise. Default: the transport's own (Kafka
+     * record timestamp; RabbitMQ `timestamp`, seconds).
+     */
+    readonly occurredAt?: TimeField<TField>;
     readonly correlationId?: TField;
     readonly causationId?: TField;
     /** Media type written with the message. Default `application/json`. Not checked on read. */
     readonly contentType?: string;
+    /**
+     * Wire names of event types, for a format whose type values are not relaybus event types or
+     * name them otherwise: `{ 'transfer.auto-dispatched.v1': 'Transfer Auto Dispatched' }`. A listed
+     * type is written as its wire name and read back from it; any other type travels as itself. One
+     * route then carries many types without a `fixed` type per transport. Not with a `fixed` type.
+     */
+    readonly wireTypes?: WireTypes;
 };
+/** Event type to the name the wire uses for it; see `wireTypes` of a jsonEnvelope mapping. */
+type WireTypes = Readonly<Record<string, string>>;
 /**
  * A JSON object that wraps the payload with event metadata, such as
  * `{ "eventName": ..., "messageId": ..., "data": {...}, "meta": {...} }`.
@@ -111,10 +145,37 @@ type BodyEnvelopeMapping<TTransportId extends string> = MappingFields<WireField,
     /** Body path of the payload. Required. */
     readonly payload: BodyField;
     /**
-     * Event headers: a body path holding an object of strings, or `'message-headers'` (default),
-     * every message header that no other field maps.
+     * Event headers: a body path holding an object of strings, `'message-headers'` (default),
+     * every message header that no other field maps, or `'top-level-fields'`, spread over the top
+     * level of the body: every top-level text field that no other value uses is read as one.
+     */
+    readonly headers?: BodyField | 'message-headers' | 'top-level-fields';
+    /**
+     * Values written with every message besides the mapped ones, such as a constant
+     * `provider: 'orders-api'` or a second copy of the time. They are never read; extra headers
+     * are left out of the event headers on read.
+     */
+    readonly extra?: {
+        readonly body?: ExtraBody;
+        readonly headers?: ExtraHeaders;
+    };
+    /**
+     * Top-level body fields to write first, in this order; the others follow in the order they
+     * are written. Only the bytes change, for formats compared byte for byte.
+     */
+    readonly bodyOrder?: readonly string[];
+    /**
+     * Keeps the top-level body fields that no other value uses (and that are not read as event
+     * headers) with every JSON type, in body order, as one object under `payloadField` of the
+     * payload: `{ payloadField: 'wire' }` reads `{ "data": { "a": 1 }, "attempt": 2 }` as the payload
+     * `{ "a": 1, "wire": { "attempt": 2 } }`, so the handler's schema validates them with the payload.
+     * Writing spreads that object back over the top level. Default: such fields are left out on read.
      */
-    readonly headers?: BodyField | 'message-headers';
+    readonly otherFields?: OtherFields;
+};
+/** Where {@link BodyEnvelopeMapping.otherFields} keeps the unused top-level fields. */
+type OtherFields = {
+    readonly payloadField: string;
 };
 /**
  * The body is the payload itself, as a plain JSON producer writes it; every other value lives in
@@ -124,6 +185,10 @@ type PayloadOnlyMapping<TTransportId extends string> = MappingFields<HeaderField
     readonly payload: 'whole-body';
     /** Event headers: every message header that no other field maps. */
     readonly headers?: 'message-headers';
+    /** Message headers written with every message; never read, and left out of the event headers. */
+    readonly extra?: {
+        readonly headers?: ExtraHeaders;
+    };
 };
 /** Where every envelope value lives in a JSON message. `type`, `id` and `payload` are required. */
 type JsonEnvelopeMapping<TTransportId extends string> = BodyEnvelopeMapping<TTransportId> | PayloadOnlyMapping<TTransportId>;
@@ -435,4 +500,5 @@ declare abstract class PositiveInteger {
     static of(value: number, name: string): number;
 }
 
-export { type BodyEnvelopeMapping, type BodyField, BoundedInteger, type CancelTimer, type CloudEventReaders, CompositeKey, type DecodedEventFields, DecodedEventReader, DeliveryLeaseIdentity, ExponentialBackoff, type FixedType, type HandedOutEntry, HandedOutLedger, type HeaderField, type IntegerBounds, type JsonEnvelopeFailures, type JsonEnvelopeFields, type JsonEnvelopeFormat, type JsonEnvelopeMapping, type JsonWireMessage, LaneLeaseTokenFormat, type LaneLeaseTokenLimits, type LaneLeaseTokenParts, type LeaseChange, type LeaseExtension, LeaseSettlement, Milliseconds, NonEmptyText, OwnerSerializedClaims, type PayloadOnlyMapping, PositiveInteger, type ScheduledTask, type SettlementChange, SubscribingTransport, type TextOption, type TransportSubscription, type WireField, assertPositiveInteger, createCloudEventReaders, createJsonEnvelopeFormat, fromHeader, fromPayloadField, isJsonObject, mediaTypeOf, observeRejection, schedule, sleep, writeStructuredCloudEvent };
+export { BoundedInteger, CompositeKey, DecodedEventReader, DeliveryLeaseIdentity, ExponentialBackoff, HandedOutLedger, LaneLeaseTokenFormat, LeaseSettlement, Milliseconds, NonEmptyText, OwnerSerializedClaims, PositiveInteger, SubscribingTransport, assertPositiveInteger, createCloudEventReaders, createJsonEnvelopeFormat, fromHeader, fromPayloadField, isJsonObject, mediaTypeOf, observeRejection, schedule, sleep, writeStructuredCloudEvent };
+export type { BodyEnvelopeMapping, BodyField, CancelTimer, CloudEventReaders, DecodedEventFields, ExtraBody, ExtraHeaders, ExtraValue, FixedType, HandedOutEntry, HeaderField, IntegerBounds, JsonConstant, JsonEnvelopeFailures, JsonEnvelopeFields, JsonEnvelopeFormat, JsonEnvelopeMapping, JsonWireMessage, LaneLeaseTokenLimits, LaneLeaseTokenParts, LeaseChange, LeaseExtension, OtherFields, PayloadOnlyMapping, ScheduledTask, SettlementChange, TextOption, TimeField, TimeFormat, TransportSubscription, WireField, WireTypes };

package/dist/internal/index.js

@@ -89,6 +89,55 @@ function writeStructuredCloudEvent(envelope, { time, data }) {
   return `${JSON.stringify(attributes).slice(0, -1)},"data":${data}}`;
 }
 
+// src/internal/json-envelope-wire-types.ts
+function compileWireTypes(wireTypes, { fixed }) {
+  if (wireTypes === void 0) {
+    return { wireTypes: /* @__PURE__ */ new Map(), eventTypes: /* @__PURE__ */ new Map() };
+  }
+  if (!isJsonObject(wireTypes) || fixed) {
+    throw new ConfigurationError(
+      "jsonEnvelope wireTypes must be an object of event type to wire name, with a type at { body } or { header }"
+    );
+  }
+  const entries = Object.entries(wireTypes);
+  const eventTypes = /* @__PURE__ */ new Map();
+  for (const [type, wire] of entries) {
+    assertEventType(type);
+    if (typeof wire !== "string" || wire.length === 0 || eventTypes.has(wire)) {
+      throw new ConfigurationError(
+        `jsonEnvelope wireTypes needs a non-empty wire name for '${type}' that no other type uses`
+      );
+    }
+    eventTypes.set(wire, type);
+  }
+  return { wireTypes: new Map(entries), eventTypes };
+}
+function wireTypeOf(envelope, { plan, failures }) {
+  const wire = plan.wireTypes.get(envelope.type);
+  if (wire !== void 0) {
+    return wire;
+  }
+  const other = plan.eventTypes.get(envelope.type);
+  if (other !== void 0) {
+    throw failures.unencodable(
+      `Event ${envelope.id} has type '${envelope.type}', which wireTypes uses as the wire name of '${other}'`
+    );
+  }
+  return envelope.type;
+}
+function eventTypeOf(wire, { plan, failures }) {
+  const type = plan.eventTypes.get(wire);
+  if (type !== void 0) {
+    return type;
+  }
+  try {
+    assertEventType(wire);
+  } catch (error) {
+    throw failures.invalid(`The event type is not a valid event type: ${error.message}`);
+  }
+  return wire;
+}
+
 // src/internal/json-envelope-plan.ts
 var OPTIONAL_NAMES = [
   "key",
@@ -97,6 +146,7 @@ var OPTIONAL_NAMES = [
   "correlationId",
   "causationId"
 ];
+var TIME_FORMATS = ["rfc3339", "epoch-millis", "epoch-seconds"];
 var ARRAY_INDEX = /^(?:0|[1-9]\d*)$/;
 function compile(mapping, transportIds) {
   if (!isJsonObject(mapping)) {
@@ -109,16 +159,72 @@ function compile(mapping, transportIds) {
       optional[name] = toLocation(field, name);
     }
   }
+  const payload = compilePayload(mapping.payload);
+  const topLevelHeaders = mapping.headers === "top-level-fields";
+  if (topLevelHeaders && payload === void 0) {
+    throw new ConfigurationError("jsonEnvelope headers 'top-level-fields' needs a body payload");
+  }
+  const type = compileType(mapping.type);
   const plan = {
-    type: compileType(mapping.type),
+    type,
     id: compileId(mapping.id, transportIds),
+    idWhenMissing: isJsonObject(mapping.id) && "whenMissing" in mapping.id,
     optional,
-    payload: compilePayload(mapping.payload),
-    headers: compileHeaders(mapping.headers),
-    mappedHeaders: /* @__PURE__ */ new Set()
+    payload,
+    headers: topLevelHeaders ? void 0 : compileHeaders(mapping.headers),
+    topLevelHeaders,
+    topLevelNames: /* @__PURE__ */ new Set(),
+    mappedHeaders: /* @__PURE__ */ new Set(),
+    timeFormat: compileTimeFormat(mapping.occurredAt),
+    otherFields: compileOtherFields(mapping, payload !== void 0),
+    ...compileWireTypes(mapping.wireTypes, { fixed: "fixed" in type }),
+    ...compileExtras(mapping, payload !== void 0)
   };
   return assertDisjoint(plan);
 }
+function compileTimeFormat(field) {
+  const format = isJsonObject(field) ? field["format"] : void 0;
+  if (format === void 0) {
+    return "rfc3339";
+  }
+  if (!TIME_FORMATS.includes(format)) {
+    throw new ConfigurationError(
+      `jsonEnvelope occurredAt format must be one of ${TIME_FORMATS.map((name) => `'${name}'`).join(", ")}`
+    );
+  }
+  return format;
+}
+function compileExtras(mapping, hasBody) {
+  const extra = mapping.extra ?? {};
+  const bodyOrder = mapping.bodyOrder ?? [];
+  if (!hasBody && (extra.body !== void 0 || bodyOrder.length > 0)) {
+    throw new ConfigurationError(
+      "jsonEnvelope with a whole-body payload has no body for extra values or a body order"
+    );
+  }
+  return {
+    extraBody: Object.entries(extra.body ?? {}).map(([path, value]) => ({
+      path: toPath(path, "extra body value"),
+      value
+    })),
+    extraHeaders: Object.entries(extra.headers ?? {}),
+    bodyOrder
+  };
+}
+function compileOtherFields(mapping, hasBody) {
+  const otherFields = mapping.otherFields;
+  if (otherFields === void 0) {
+    return void 0;
+  }
+  if (!hasBody) {
+    throw new ConfigurationError("jsonEnvelope otherFields needs a body payload");
+  }
+  const field = isJsonObject(otherFields) ? otherFields["payloadField"] : void 0;
+  if (typeof field !== "string" || field.length === 0) {
+    throw new ConfigurationError("jsonEnvelope otherFields must be { payloadField: '<name>' }");
+  }
+  return field;
+}
 function compileType(type) {
   if (isJsonObject(type) && typeof type["fixed"] === "string") {
     assertEventType(type["fixed"]);
@@ -133,11 +239,15 @@ function compileId(id, transportIds) {
   if (typeof id === "string" && transportIds.includes(id)) {
     return void 0;
   }
+  const names = transportIds.map((name) => `'${name}'`).join(", ");
   if (!isJsonObject(id)) {
     throw new ConfigurationError(
-      `jsonEnvelope needs an id: { body }, { header } or one of ${transportIds.map((name) => `'${name}'`).join(", ")}`
+      `jsonEnvelope needs an id: { body }, { header } or one of ${names}`
     );
   }
+  if ("whenMissing" in id && !transportIds.includes(id["whenMissing"])) {
+    throw new ConfigurationError(`jsonEnvelope id whenMissing must be one of ${names}`);
+  }
   return toLocation(id, "id");
 }
 function compilePayload(payload) {
@@ -186,17 +296,25 @@ function assertDisjoint(plan) {
   const locations = [plan.type, plan.id, ...Object.values(plan.optional)].filter(
     (location) => location !== void 0 && !("fixed" in location)
   );
-  const headers = locations.flatMap((location) => "header" in location ? [location.header] : []);
+  const headers = [
+    ...locations.flatMap((location) => "header" in location ? [location.header] : []),
+    ...plan.extraHeaders.map(([name]) => name)
+  ];
   const duplicate = headers.find((name, index) => headers.indexOf(name) !== index);
   if (duplicate !== void 0) {
     throw new ConfigurationError(`jsonEnvelope maps header '${duplicate}' twice`);
   }
   const paths = [
     ...locations.flatMap((location) => "path" in location ? [location.path] : []),
-    ...[plan.payload, plan.headers].filter((path) => path !== void 0)
+    ...[plan.payload, plan.headers].filter((path) => path !== void 0),
+    ...plan.extraBody.map(({ path }) => path)
   ];
   assertNoNestedPaths(paths);
-  return { ...plan, mappedHeaders: new Set(headers) };
+  return {
+    ...plan,
+    mappedHeaders: new Set(headers),
+    topLevelNames: new Set(paths.map((path) => path[0]))
+  };
 }
 function assertNoNestedPaths(paths) {
   paths.forEach((path, index) => {
@@ -216,8 +334,60 @@ function assertCompatiblePaths(path, other) {
   }
 }
 
+// src/internal/json-envelope-other-fields.ts
+function unusedFields(body, { plan }) {
+  return Object.entries(body).filter(
+    ([name, value]) => !plan.topLevelNames.has(name) && !(plan.topLevelHeaders && typeof value === "string")
+  );
+}
+function withOtherFields(payload, { body, context }) {
+  const field = context.plan.otherFields;
+  if (field === void 0) {
+    return payload;
+  }
+  const fields = unusedFields(body, context);
+  if (!isJsonObject(payload) && fields.length === 0) {
+    return payload;
+  }
+  if (!isJsonObject(payload) || Object.hasOwn(payload, field)) {
+    throw context.failures.invalid(
+      `otherFields keeps the unused top-level fields under the payload field '${field}', but the payload is not an object without that field`
+    );
+  }
+  return Object.fromEntries([...Object.entries(payload), [field, Object.fromEntries(fields)]]);
+}
+function splitOtherFields(envelope, context) {
+  const field = context.plan.otherFields;
+  const { payload } = envelope;
+  if (field === void 0 || !isJsonObject(payload) || !Object.hasOwn(payload, field)) {
+    return { payload, fields: [] };
+  }
+  const others = payload[field];
+  if (!isJsonObject(others)) {
+    throw context.failures.unencodable(
+      `Event ${envelope.id} has a payload field '${field}' that is not an object of top-level fields`
+    );
+  }
+  const fields = Object.entries(others);
+  const refused = fields.find((entry) => isRefused(entry, context));
+  if (refused !== void 0) {
+    throw context.failures.unencodable(
+      `Event ${envelope.id} keeps a top-level field '${refused[0]}' under '${field}' that the mapping reads as another value`
+    );
+  }
+  return {
+    payload: Object.fromEntries(Object.entries(payload).filter(([name]) => name !== field)),
+    fields
+  };
+}
+function isRefused([name, value], { plan }) {
+  return plan.topLevelNames.has(name) || plan.topLevelHeaders && typeof value === "string";
+}
+
 // src/internal/json-envelope-read.ts
 var RFC3339_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/i;
+var EPOCH_PATTERN = /^\d+$/;
+var MILLISECONDS_PER_SECOND = 1e3;
 function readMessage(message, context) {
   const { plan, failures } = context;
   if (plan.payload !== void 0 && !isJsonObject(message.body)) {
@@ -225,7 +395,7 @@ function readMessage(message, context) {
   }
   const read = (location) => location === void 0 ? void 0 : readText(message, { location, failures });
   const fields = {
-    id: plan.id === void 0 ? void 0 : requireText(read(plan.id), { location: plan.id, failures }),
+    id: readId(read(plan.id), context),
     type: readType(message, context),
     payload: readPayload(message.body, context),
     key: read(plan.optional.key),
@@ -233,24 +403,25 @@ function readMessage(message, context) {
     headers: readEventHeaders(message, plan),
     correlationId: read(plan.optional.correlationId) ?? null,
     causationId: read(plan.optional.causationId) ?? null,
-    occurredAt: readTime(read(plan.optional.occurredAt), failures)
+    occurredAt: readTime(read(plan.optional.occurredAt), context)
   };
   return Object.fromEntries(
     Object.entries(fields).filter((entry) => entry[1] !== void 0)
   );
 }
+function readId(id, { plan, failures }) {
+  if (plan.id === void 0 || plan.idWhenMissing) {
+    return id;
+  }
+  return requireText(id, { location: plan.id, failures });
+}
 function readType(message, { plan, failures }) {
   if ("fixed" in plan.type) {
     return plan.type.fixed;
   }
   const location = plan.type;
-  const type = requireText(readText(message, { location, failures }), { location, failures });
-  try {
-    assertEventType(type);
-  } catch (error) {
-    throw failures.invalid(`The event type is not a valid event type: ${error.message}`);
-  }
-  return type;
+  const wire = requireText(readText(message, { location, failures }), { location, failures });
+  return eventTypeOf(wire, { plan, failures });
 }
 function readPayload(body, { plan, failures }) {
   if (plan.payload === void 0) {
@@ -260,25 +431,45 @@ function readPayload(body, { plan, failures }) {
   if (payload === void 0) {
     throw failures.invalid(`The message has no payload at '${plan.payload.join(".")}'`);
   }
-  return payload;
+  return withOtherFields(payload, {
+    body,
+    context: { plan, failures }
+  });
 }
 function readEventHeaders(message, plan) {
+  if (plan.topLevelHeaders) {
+    return textEntries(
+      Object.entries(message.body).filter(
+        ([name]) => !plan.topLevelNames.has(name)
+      )
+    );
+  }
   if (plan.headers === void 0) {
     return Object.fromEntries(
       Object.entries(message.headers).filter(([name]) => !plan.mappedHeaders.has(name))
     );
   }
   const headers = valueAt(message.body, plan.headers);
-  return isJsonObject(headers) ? Object.fromEntries(
-    Object.entries(headers).filter(
-      (entry) => typeof entry[1] === "string"
-    )
-  ) : {};
+  return isJsonObject(headers) ? textEntries(Object.entries(headers)) : {};
 }
-function readTime(text, failures) {
+function textEntries(entries) {
+  return Object.fromEntries(
+    entries.filter((entry) => typeof entry[1] === "string")
+  );
+}
+function readTime(text, { plan, failures }) {
   if (text === void 0) {
     return void 0;
   }
+  if (plan.timeFormat !== "rfc3339") {
+    const time2 = new Date(
+      Number(text) * (plan.timeFormat === "epoch-seconds" ? MILLISECONDS_PER_SECOND : 1)
+    );
+    if (!EPOCH_PATTERN.test(text) || Number.isNaN(time2.getTime())) {
+      throw failures.invalid(`The event time is not a whole ${plan.timeFormat} number: '${text}'`);
+    }
+    return time2;
+  }
   const time = new Date(text);
   if (!RFC3339_PATTERN.test(text) || Number.isNaN(time.getTime())) {
     throw failures.invalid(`The event time is not an RFC 3339 timestamp: '${text}'`);
@@ -320,63 +511,135 @@ function valueAt(body, path) {
 
 // src/internal/json-envelope-write.ts
 var MAXIMUM_RFC3339_YEAR = 9999;
+var MILLISECONDS_PER_SECOND2 = 1e3;
 function writeMessage(envelope, { plan, failures }) {
   const root = {};
   const headers = [];
   const put = (location, value) => {
     if ("header" in location) {
-      headers.push([location.header, value]);
+      headers.push([location.header, String(value)]);
     } else {
       setAt(root, { path: location.path, value });
     }
   };
-  if ("fixed" in plan.type) {
-    if (envelope.type !== plan.type.fixed) {
-      throw failures.unencodable(
-        `Event ${envelope.id} has type '${envelope.type}', but this route carries only '${plan.type.fixed}'`
-      );
-    }
-  } else {
-    put(plan.type, envelope.type);
+  const typeAt = typeLocation(envelope, { plan, failures });
+  if (typeAt !== void 0) {
+    put(typeAt, wireTypeOf(envelope, { plan, failures }));
   }
   if (plan.id !== void 0) {
     put(plan.id, envelope.id);
   }
-  for (const [name, value] of optionalValues(envelope, failures)) {
+  for (const [name, value] of optionalValues(envelope, { plan, failures })) {
     const location = plan.optional[name];
     if (location !== void 0 && value !== null) {
       put(location, value);
     }
   }
   return {
-    body: writeBody(envelope, { plan, root }),
-    headers: Object.fromEntries([...eventHeaderEntries(envelope, { plan, failures }), ...headers])
+    body: writeBody(envelope, { plan, failures, root }),
+    headers: Object.fromEntries([
+      ...eventHeaderEntries(envelope, { plan, failures }),
+      ...headers,
+      ...extraHeaderEntries(envelope, plan)
+    ])
   };
 }
-function optionalValues(envelope, failures) {
+function typeLocation(envelope, { plan, failures }) {
+  if (!("fixed" in plan.type)) {
+    return plan.type;
+  }
+  if (envelope.type !== plan.type.fixed) {
+    throw failures.unencodable(
+      `Event ${envelope.id} has type '${envelope.type}', but this route carries only '${plan.type.fixed}'`
+    );
+  }
+  return void 0;
+}
+function extraHeaderEntries(envelope, plan) {
+  return plan.extraHeaders.map(([name, value]) => [
+    name,
+    typeof value === "function" ? value(envelope) : value
+  ]);
+}
+function optionalValues(envelope, { plan, failures }) {
   return [
     ["key", envelope.key],
     ["source", envelope.source],
-    ["occurredAt", formatTime(envelope, failures)],
+    [
+      "occurredAt",
+      timeValue(formatTime(envelope, failures), { envelope, format: plan.timeFormat })
+    ],
     ["correlationId", envelope.correlationId],
     ["causationId", envelope.causationId]
   ];
 }
-function writeBody(envelope, { plan, root }) {
+function writeBody(envelope, { plan, failures, root }) {
+  const { payload, fields } = splitOtherFields(envelope, { plan, failures });
   if (plan.payload === void 0) {
-    return envelope.payload;
+    return payload;
   }
-  setAt(root, { path: plan.payload, value: envelope.payload });
+  setAt(root, { path: plan.payload, value: payload });
   if (plan.headers !== void 0) {
     setAt(root, {
       path: plan.headers,
       value: Object.fromEntries(Object.entries(envelope.headers))
     });
   }
-  return root;
+  for (const { path, value } of plan.extraBody) {
+    setAt(root, { path, value: typeof value === "function" ? value(envelope) : value });
+  }
+  if (plan.topLevelHeaders) {
+    spreadHeaders(envelope, { plan, failures, root });
+  }
+  spreadOtherFields(envelope, { failures, fields, root });
+  return ordered(root, plan.bodyOrder);
+}
+function spreadHeaders(envelope, { plan, failures, root }) {
+  for (const [name, value] of Object.entries(envelope.headers)) {
+    if (plan.topLevelNames.has(name)) {
+      throw failures.unencodable(
+        `Event ${envelope.id} has a header '${name}', which the mapping uses for another body field`
+      );
+    }
+    setAt(root, { path: [name], value });
+  }
+}
+function spreadOtherFields(envelope, {
+  failures,
+  fields,
+  root
+}) {
+  for (const [name, value] of fields) {
+    if (Object.hasOwn(root, name)) {
+      throw failures.unencodable(
+        `Event ${envelope.id} keeps a top-level field '${name}' that an event header also writes`
+      );
+    }
+    setAt(root, { path: [name], value });
+  }
+}
+function timeValue(text, { envelope, format }) {
+  const milliseconds = envelope.occurredAt.getTime();
+  if (format === "epoch-millis") {
+    return milliseconds;
+  }
+  return format === "epoch-seconds" ? Math.floor(milliseconds / MILLISECONDS_PER_SECOND2) : text;
+}
+function ordered(root, order) {
+  if (order.length === 0) {
+    return root;
+  }
+  const result = {};
+  const names = [...order.filter((name) => Object.hasOwn(root, name)), ...Object.keys(root)];
+  for (const name of names) {
+    if (!Object.hasOwn(result, name)) {
+      defineValue(result, { name, value: root[name] });
+    }
+  }
+  return result;
 }
 function eventHeaderEntries(envelope, { plan, failures }) {
-  if (plan.headers !== void 0) {
+  if (plan.headers !== void 0 || plan.topLevelHeaders) {
     return [];
   }
   const entries = Object.entries(envelope.headers);