@babelqueue/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammet Şafak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# BabelQueue for Node.js
+
+[![CI](https://github.com/BabelQueue/babelqueue-node/actions/workflows/ci.yml/badge.svg)](https://github.com/BabelQueue/babelqueue-node/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@babelqueue/core.svg)](https://www.npmjs.com/package/@babelqueue/core)
+[![node](https://img.shields.io/node/v/@babelqueue/core.svg)](https://www.npmjs.com/package/@babelqueue/core)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+> **Polyglot Queues, Simplified.** Read and write the canonical BabelQueue message
+> envelope from Node.js — so your Node services exchange messages with Laravel,
+> Symfony, Python, Go and .NET over one strict JSON format, on the broker you
+> already run.
+
+This is the framework-agnostic **Node/TypeScript core**: the wire-envelope codec,
+contracts and dead-letter helpers — **zero runtime dependencies**, shipped as a
+dual **ESM + CommonJS** package with bundled types. The full standard is documented
+at **[babelqueue.com](https://babelqueue.com)**.
+
+## Installation
+
+```bash
+npm install @babelqueue/core
+```
+
+Requires Node `>=18`.
+
+## Usage
+
+```ts
+import { EnvelopeCodec } from "@babelqueue/core";
+
+// Produce — build the canonical envelope and publish the JSON to your broker.
+const env = EnvelopeCodec.make(
+  "urn:babel:orders:created",
+  { order_id: 1042 },
+  { queue: "orders" },
+);
+const body = EnvelopeCodec.encode(env); // compact UTF-8 JSON string
+// await redis.rpush("queues:orders", body);
+//   /  channel.sendToQueue("orders", Buffer.from(body));
+
+// Consume — decode a message produced by ANY BabelQueue SDK.
+const incoming = EnvelopeCodec.decode(body);
+if (EnvelopeCodec.accepts(incoming)) {
+  // `incoming` is now narrowed to a fully-typed Envelope
+  switch (EnvelopeCodec.urn(incoming)) {
+    case "urn:babel:orders:created":
+      console.log(incoming.data.order_id, incoming.trace_id);
+      break;
+  }
+}
+```
+
+CommonJS works too:
+
+```js
+const { EnvelopeCodec } = require("@babelqueue/core");
+```
+
+The envelope is identical to every other SDK's:
+
+```json
+{
+  "job": "urn:babel:orders:created",
+  "trace_id": "…",
+  "data": { "order_id": 1042 },
+  "meta": { "id": "…", "queue": "orders", "lang": "node", "schema_version": 1, "created_at": 1749132727000 },
+  "attempts": 0
+}
+```
+
+### Typed messages (optional)
+
+```ts
+import { EnvelopeCodec, type PolyglotMessage } from "@babelqueue/core";
+
+class OrderCreated implements PolyglotMessage {
+  constructor(private readonly orderId: number) {}
+  getBabelUrn() {
+    return "urn:babel:orders:created";
+  }
+  toPayload() {
+    return { order_id: this.orderId };
+  }
+}
+
+const env = EnvelopeCodec.fromMessage(new OrderCreated(1042), "orders");
+```
+
+Continue an existing trace by adding `getBabelTraceId(): string | null` (see
+`HasTraceId`), or pass `{ traceId }` to `EnvelopeCodec.make`.
+
+### Dead-letter
+
+```ts
+import { annotate, EnvelopeCodec } from "@babelqueue/core";
+
+const dlq = annotate(env, "failed", "orders", { attempts: 3, error: "boom" });
+// publish EnvelopeCodec.encode(dlq) to the "orders.dlq" queue
+```
+
+`annotate` returns a copy — the original envelope is preserved unchanged inside
+the dead-lettered message, so any-language consumers can still read it.
+
+## What this core is (and isn't)
+
+It enforces the **contract**: the envelope shape, URN identity, trace propagation,
+schema-version gating and the dead-letter block. It is intentionally **not** a
+worker/runtime — broker wiring, acks and retry loops stay in your own code (or a
+future thin adapter), exactly as with the other SDK cores.
+
+`UnknownUrnStrategy` (`FAIL`, `DELETE`, `RELEASE`, `DEAD_LETTER`) is provided for
+adapters to act on.
+
+## Conformance
+
+This core passes the shared **cross-SDK conformance suite** (vendored under
+[`test/conformance/`](test/conformance)) — the same fixtures every BabelQueue SDK
+must satisfy, so a Node producer and, say, a Laravel consumer agree byte-for-byte.
+
+```bash
+npm test
+```
+
+## License
+
+[MIT](LICENSE) © Muhammet Şafak

package/dist/index.cjs

@@ -0,0 +1,200 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BabelQueueError: () => BabelQueueError,
+  EnvelopeCodec: () => EnvelopeCodec,
+  SCHEMA_VERSION: () => SCHEMA_VERSION,
+  SOURCE_LANG: () => SOURCE_LANG,
+  UnknownUrnError: () => UnknownUrnError,
+  UnknownUrnStrategy: () => UnknownUrnStrategy,
+  annotate: () => annotate,
+  deadLetter: () => deadLetter_exports
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/codec.ts
+var import_node_crypto = require("crypto");
+
+// src/errors.ts
+var BabelQueueError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BabelQueueError";
+  }
+};
+var UnknownUrnError = class extends BabelQueueError {
+  constructor(urn) {
+    super(`No handler is mapped for the message URN "${urn}".`);
+    this.name = "UnknownUrnError";
+  }
+};
+
+// src/codec.ts
+var SCHEMA_VERSION = 1;
+var SOURCE_LANG = "node";
+var EnvelopeCodec = {
+  SCHEMA_VERSION,
+  SOURCE_LANG,
+  /**
+   * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id
+   * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.
+   * Throws {@link BabelQueueError} when the URN is blank.
+   */
+  make(urn, data, options = {}) {
+    const resolvedUrn = (urn ?? "").trim();
+    if (resolvedUrn === "") {
+      throw new BabelQueueError(
+        "A polyglot message must expose a stable, non-empty URN so consumers can identify it without any class name."
+      );
+    }
+    const traceId = (options.traceId ?? "").trim() || (0, import_node_crypto.randomUUID)();
+    return {
+      job: resolvedUrn,
+      trace_id: traceId,
+      data: { ...data },
+      meta: {
+        id: (0, import_node_crypto.randomUUID)(),
+        queue: options.queue ?? "default",
+        lang: SOURCE_LANG,
+        schema_version: SCHEMA_VERSION,
+        created_at: Date.now()
+      },
+      attempts: 0
+    };
+  },
+  /**
+   * Build the envelope from a {@link PolyglotMessage}. If the message also
+   * implements {@link HasTraceId} and returns a non-empty value, that trace id is
+   * reused.
+   */
+  fromMessage(message, queue = "default") {
+    const traceId = typeof message.getBabelTraceId === "function" ? message.getBabelTraceId() ?? void 0 : void 0;
+    return EnvelopeCodec.make(message.getBabelUrn(), message.toPayload(), {
+      queue,
+      traceId
+    });
+  },
+  /**
+   * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the
+   * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching
+   * the other SDK cores.
+   */
+  encode(envelope) {
+    return JSON.stringify(envelope);
+  },
+  /**
+   * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call
+   * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound
+   * alias into `job`.
+   */
+  decode(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return {};
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    const envelope = parsed;
+    if (!envelope.job && typeof envelope.urn === "string") {
+      envelope.job = envelope.urn;
+    }
+    return envelope;
+  },
+  /** The message URN — canonical `job`, with `urn` accepted as an alias. */
+  urn(envelope) {
+    const value = envelope?.job ?? envelope?.urn ?? "";
+    return typeof value === "string" ? value.trim() : "";
+  },
+  /**
+   * Whether a consumer should accept this envelope. Rejects a missing URN, an
+   * unsupported `meta.schema_version`, a non-object `data`, a non-integer
+   * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the
+   * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.
+   */
+  accepts(envelope) {
+    if (EnvelopeCodec.urn(envelope) === "") {
+      return false;
+    }
+    const meta = envelope.meta;
+    if (meta === null || typeof meta !== "object" || meta.schema_version !== SCHEMA_VERSION) {
+      return false;
+    }
+    const data = envelope.data;
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+      return false;
+    }
+    const attempts = envelope.attempts;
+    if (typeof attempts !== "number" || !Number.isInteger(attempts)) {
+      return false;
+    }
+    const traceId = envelope.trace_id;
+    if (typeof traceId !== "string" || traceId.trim() === "") {
+      return false;
+    }
+    return true;
+  }
+};
+
+// src/deadLetter.ts
+var deadLetter_exports = {};
+__export(deadLetter_exports, {
+  annotate: () => annotate
+});
+function annotate(envelope, reason, originalQueue, options = {}) {
+  const deadLetter = {
+    reason,
+    error: options.error ?? null,
+    exception: options.exception ?? null,
+    failed_at: Date.now(),
+    original_queue: originalQueue,
+    attempts: options.attempts ?? envelope.attempts ?? 0,
+    lang: SOURCE_LANG
+  };
+  return { ...envelope, dead_letter: deadLetter };
+}
+
+// src/routing.ts
+var UnknownUrnStrategy = {
+  /** Surface an error; let the worker decide. */
+  FAIL: "fail",
+  /** Drop the message. */
+  DELETE: "delete",
+  /** Requeue for another consumer. */
+  RELEASE: "release",
+  /** Route to the dead-letter queue. */
+  DEAD_LETTER: "dead_letter"
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BabelQueueError,
+  EnvelopeCodec,
+  SCHEMA_VERSION,
+  SOURCE_LANG,
+  UnknownUrnError,
+  UnknownUrnStrategy,
+  annotate,
+  deadLetter
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/codec.ts","../src/errors.ts","../src/deadLetter.ts","../src/routing.ts"],"sourcesContent":["/**\n * BabelQueue — Polyglot Queues, Simplified.\n *\n * The framework-agnostic Node/TypeScript core: the canonical wire-envelope codec,\n * contracts and dead-letter helpers. Zero runtime dependencies.\n *\n * ```ts\n * import { EnvelopeCodec } from \"@babelqueue/core\";\n *\n * const env = EnvelopeCodec.make(\"urn:babel:orders:created\", { order_id: 1042 });\n * const body = EnvelopeCodec.encode(env); // publish body to Redis / RabbitMQ / ...\n * ```\n *\n * Full spec: https://babelqueue.com\n */\n\nexport { EnvelopeCodec, SCHEMA_VERSION, SOURCE_LANG } from \"./codec.js\";\nexport type {\n  DeadLetter,\n  Envelope,\n  IncomingEnvelope,\n  MakeOptions,\n  Meta,\n} from \"./codec.js\";\n\nexport type { HasTraceId, PolyglotMessage } from \"./contracts.js\";\n\nexport { annotate } from \"./deadLetter.js\";\nexport type { AnnotateOptions } from \"./deadLetter.js\";\nexport * as deadLetter from \"./deadLetter.js\";\n\nexport { UnknownUrnStrategy } from \"./routing.js\";\n\nexport { BabelQueueError, UnknownUrnError } from \"./errors.js\";\n","import { randomUUID } from \"node:crypto\";\n\nimport type { HasTraceId, PolyglotMessage } from \"./contracts.js\";\nimport { BabelQueueError } from \"./errors.js\";\n\n/** The wire envelope schema version this core implements (versioned independently of the package version). */\nexport const SCHEMA_VERSION = 1;\n\n/** Stamped into `meta.lang` for envelopes produced by this core. */\nexport const SOURCE_LANG = \"node\";\n\n/** Immutable per-message metadata. */\nexport interface Meta {\n  id: string;\n  queue: string;\n  lang: string;\n  schema_version: number;\n  /** Unix milliseconds, UTC. */\n  created_at: number;\n}\n\n/** The additive block appended to an envelope when a message is dead-lettered. */\nexport interface DeadLetter {\n  reason: string;\n  error: string | null;\n  exception: string | null;\n  /** Unix milliseconds, UTC. */\n  failed_at: number;\n  original_queue: string;\n  attempts: number;\n  lang: string;\n}\n\n/**\n * The canonical BabelQueue wire message: a strict, language-neutral JSON shape\n * that every SDK produces and consumes identically. The property order here is\n * significant — it matches the other cores so {@link EnvelopeCodec.encode} is\n * byte-for-byte identical across the insertion-order languages (PHP/Python).\n */\nexport interface Envelope {\n  /** The message URN (never a class name). */\n  job: string;\n  /** Correlation id, preserved across every hop. */\n  trace_id: string;\n  /** The pure-JSON payload. */\n  data: Record<string, unknown>;\n  meta: Meta;\n  /** Top-level transport retry counter. */\n  attempts: number;\n  /** Present only once the message has been dead-lettered. */\n  dead_letter?: DeadLetter;\n}\n\n/**\n * A decoded, not-yet-validated envelope. Fields are loosely typed because they\n * come off the wire; `urn` is accepted as an inbound alias for `job`. Narrow it\n * with {@link EnvelopeCodec.accepts} before trusting the contents.\n */\nexport interface IncomingEnvelope {\n  job?: string;\n  /** Inbound alias for `job`. */\n  urn?: string;\n  trace_id?: string;\n  data?: unknown;\n  meta?: unknown;\n  attempts?: unknown;\n  dead_letter?: unknown;\n}\n\n/** Options for {@link EnvelopeCodec.make}. */\nexport interface MakeOptions {\n  /** Logical queue name recorded in `meta.queue` (default `\"default\"`). */\n  queue?: string;\n  /** Reuse an existing trace id (trace continuation) instead of minting one. */\n  traceId?: string;\n}\n\n/**\n * Builds, encodes and decodes the canonical envelope — the single Node/TypeScript\n * implementation of the wire format.\n */\nexport const EnvelopeCodec = {\n  SCHEMA_VERSION,\n  SOURCE_LANG,\n\n  /**\n   * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id\n   * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.\n   * Throws {@link BabelQueueError} when the URN is blank.\n   */\n  make(\n    urn: string,\n    data: Record<string, unknown>,\n    options: MakeOptions = {},\n  ): Envelope {\n    const resolvedUrn = (urn ?? \"\").trim();\n    if (resolvedUrn === \"\") {\n      throw new BabelQueueError(\n        \"A polyglot message must expose a stable, non-empty URN so consumers can identify it without any class name.\",\n      );\n    }\n\n    const traceId = (options.traceId ?? \"\").trim() || randomUUID();\n\n    return {\n      job: resolvedUrn,\n      trace_id: traceId,\n      data: { ...data },\n      meta: {\n        id: randomUUID(),\n        queue: options.queue ?? \"default\",\n        lang: SOURCE_LANG,\n        schema_version: SCHEMA_VERSION,\n        created_at: Date.now(),\n      },\n      attempts: 0,\n    };\n  },\n\n  /**\n   * Build the envelope from a {@link PolyglotMessage}. If the message also\n   * implements {@link HasTraceId} and returns a non-empty value, that trace id is\n   * reused.\n   */\n  fromMessage(\n    message: PolyglotMessage & Partial<HasTraceId>,\n    queue = \"default\",\n  ): Envelope {\n    const traceId =\n      typeof message.getBabelTraceId === \"function\"\n        ? (message.getBabelTraceId() ?? undefined)\n        : undefined;\n\n    return EnvelopeCodec.make(message.getBabelUrn(), message.toPayload(), {\n      queue,\n      traceId,\n    });\n  },\n\n  /**\n   * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the\n   * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching\n   * the other SDK cores.\n   */\n  encode(envelope: Envelope): string {\n    return JSON.stringify(envelope);\n  },\n\n  /**\n   * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call\n   * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound\n   * alias into `job`.\n   */\n  decode(raw: string): IncomingEnvelope {\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      return {};\n    }\n    if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n      return {};\n    }\n\n    const envelope = parsed as IncomingEnvelope;\n    if (!envelope.job && typeof envelope.urn === \"string\") {\n      envelope.job = envelope.urn;\n    }\n    return envelope;\n  },\n\n  /** The message URN — canonical `job`, with `urn` accepted as an alias. */\n  urn(envelope: IncomingEnvelope): string {\n    const value = envelope?.job ?? envelope?.urn ?? \"\";\n    return typeof value === \"string\" ? value.trim() : \"\";\n  },\n\n  /**\n   * Whether a consumer should accept this envelope. Rejects a missing URN, an\n   * unsupported `meta.schema_version`, a non-object `data`, a non-integer\n   * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the\n   * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.\n   */\n  accepts(envelope: IncomingEnvelope): envelope is Envelope {\n    if (EnvelopeCodec.urn(envelope) === \"\") {\n      return false;\n    }\n\n    const meta = envelope.meta;\n    if (\n      meta === null ||\n      typeof meta !== \"object\" ||\n      (meta as Meta).schema_version !== SCHEMA_VERSION\n    ) {\n      return false;\n    }\n\n    const data = envelope.data;\n    if (data === null || typeof data !== \"object\" || Array.isArray(data)) {\n      return false;\n    }\n\n    const attempts = envelope.attempts;\n    if (typeof attempts !== \"number\" || !Number.isInteger(attempts)) {\n      return false;\n    }\n\n    const traceId = envelope.trace_id;\n    if (typeof traceId !== \"string\" || traceId.trim() === \"\") {\n      return false;\n    }\n\n    return true;\n  },\n} as const;\n","/** Base error for all BabelQueue failures. */\nexport class BabelQueueError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"BabelQueueError\";\n  }\n}\n\n/** Raised when no handler is mapped for a message URN. */\nexport class UnknownUrnError extends BabelQueueError {\n  constructor(urn: string) {\n    super(`No handler is mapped for the message URN \"${urn}\".`);\n    this.name = \"UnknownUrnError\";\n  }\n}\n","import type { DeadLetter, Envelope } from \"./codec.js\";\nimport { SOURCE_LANG } from \"./codec.js\";\n\n/** Options for {@link annotate}. */\nexport interface AnnotateOptions {\n  /** Defaults to the envelope's current `attempts`. */\n  attempts?: number;\n  /** A human-readable error message (JSON `null` when omitted). */\n  error?: string | null;\n  /** The originating error type/class name (JSON `null` when omitted). */\n  exception?: string | null;\n}\n\n/**\n * Return a copy of the envelope with a `dead_letter` block attached, recording\n * why and where it failed. The original envelope is preserved unchanged inside\n * the result, so any-language consumers can still read it.\n */\nexport function annotate(\n  envelope: Envelope,\n  reason: string,\n  originalQueue: string,\n  options: AnnotateOptions = {},\n): Envelope {\n  const deadLetter: DeadLetter = {\n    reason,\n    error: options.error ?? null,\n    exception: options.exception ?? null,\n    failed_at: Date.now(),\n    original_queue: originalQueue,\n    attempts: options.attempts ?? envelope.attempts ?? 0,\n    lang: SOURCE_LANG,\n  };\n\n  return { ...envelope, dead_letter: deadLetter };\n}\n","/**\n * What a consumer does with a message whose URN has no registered handler.\n * Mirrors the constants in every other SDK core.\n */\nexport const UnknownUrnStrategy = {\n  /** Surface an error; let the worker decide. */\n  FAIL: \"fail\",\n  /** Drop the message. */\n  DELETE: \"delete\",\n  /** Requeue for another consumer. */\n  RELEASE: \"release\",\n  /** Route to the dead-letter queue. */\n  DEAD_LETTER: \"dead_letter\",\n} as const;\n\nexport type UnknownUrnStrategy =\n  (typeof UnknownUrnStrategy)[keyof typeof UnknownUrnStrategy];\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,175 @@
+/**
+ * A message that can be produced as a polyglot envelope. Implement it on your
+ * own classes/objects so {@link EnvelopeCodec.fromMessage} can build the canonical
+ * envelope without ever leaking a language-specific class name onto the wire.
+ */
+interface PolyglotMessage {
+    /** The stable URN that identifies this message across languages. */
+    getBabelUrn(): string;
+    /** The pure-JSON payload (no class instances). */
+    toPayload(): Record<string, unknown>;
+}
+/**
+ * Optionally implemented alongside {@link PolyglotMessage} to continue an existing
+ * distributed trace instead of minting a fresh one.
+ */
+interface HasTraceId {
+    /** The trace id to reuse, or null/undefined to mint a new one. */
+    getBabelTraceId(): string | null | undefined;
+}
+
+/** The wire envelope schema version this core implements (versioned independently of the package version). */
+declare const SCHEMA_VERSION = 1;
+/** Stamped into `meta.lang` for envelopes produced by this core. */
+declare const SOURCE_LANG = "node";
+/** Immutable per-message metadata. */
+interface Meta {
+    id: string;
+    queue: string;
+    lang: string;
+    schema_version: number;
+    /** Unix milliseconds, UTC. */
+    created_at: number;
+}
+/** The additive block appended to an envelope when a message is dead-lettered. */
+interface DeadLetter {
+    reason: string;
+    error: string | null;
+    exception: string | null;
+    /** Unix milliseconds, UTC. */
+    failed_at: number;
+    original_queue: string;
+    attempts: number;
+    lang: string;
+}
+/**
+ * The canonical BabelQueue wire message: a strict, language-neutral JSON shape
+ * that every SDK produces and consumes identically. The property order here is
+ * significant — it matches the other cores so {@link EnvelopeCodec.encode} is
+ * byte-for-byte identical across the insertion-order languages (PHP/Python).
+ */
+interface Envelope {
+    /** The message URN (never a class name). */
+    job: string;
+    /** Correlation id, preserved across every hop. */
+    trace_id: string;
+    /** The pure-JSON payload. */
+    data: Record<string, unknown>;
+    meta: Meta;
+    /** Top-level transport retry counter. */
+    attempts: number;
+    /** Present only once the message has been dead-lettered. */
+    dead_letter?: DeadLetter;
+}
+/**
+ * A decoded, not-yet-validated envelope. Fields are loosely typed because they
+ * come off the wire; `urn` is accepted as an inbound alias for `job`. Narrow it
+ * with {@link EnvelopeCodec.accepts} before trusting the contents.
+ */
+interface IncomingEnvelope {
+    job?: string;
+    /** Inbound alias for `job`. */
+    urn?: string;
+    trace_id?: string;
+    data?: unknown;
+    meta?: unknown;
+    attempts?: unknown;
+    dead_letter?: unknown;
+}
+/** Options for {@link EnvelopeCodec.make}. */
+interface MakeOptions {
+    /** Logical queue name recorded in `meta.queue` (default `"default"`). */
+    queue?: string;
+    /** Reuse an existing trace id (trace continuation) instead of minting one. */
+    traceId?: string;
+}
+/**
+ * Builds, encodes and decodes the canonical envelope — the single Node/TypeScript
+ * implementation of the wire format.
+ */
+declare const EnvelopeCodec: {
+    readonly SCHEMA_VERSION: 1;
+    readonly SOURCE_LANG: "node";
+    /**
+     * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id
+     * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.
+     * Throws {@link BabelQueueError} when the URN is blank.
+     */
+    readonly make: (urn: string, data: Record<string, unknown>, options?: MakeOptions) => Envelope;
+    /**
+     * Build the envelope from a {@link PolyglotMessage}. If the message also
+     * implements {@link HasTraceId} and returns a non-empty value, that trace id is
+     * reused.
+     */
+    readonly fromMessage: (message: PolyglotMessage & Partial<HasTraceId>, queue?: string) => Envelope;
+    /**
+     * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the
+     * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching
+     * the other SDK cores.
+     */
+    readonly encode: (envelope: Envelope) => string;
+    /**
+     * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call
+     * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound
+     * alias into `job`.
+     */
+    readonly decode: (raw: string) => IncomingEnvelope;
+    /** The message URN — canonical `job`, with `urn` accepted as an alias. */
+    readonly urn: (envelope: IncomingEnvelope) => string;
+    /**
+     * Whether a consumer should accept this envelope. Rejects a missing URN, an
+     * unsupported `meta.schema_version`, a non-object `data`, a non-integer
+     * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the
+     * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.
+     */
+    readonly accepts: (envelope: IncomingEnvelope) => envelope is Envelope;
+};
+
+/** Options for {@link annotate}. */
+interface AnnotateOptions {
+    /** Defaults to the envelope's current `attempts`. */
+    attempts?: number;
+    /** A human-readable error message (JSON `null` when omitted). */
+    error?: string | null;
+    /** The originating error type/class name (JSON `null` when omitted). */
+    exception?: string | null;
+}
+/**
+ * Return a copy of the envelope with a `dead_letter` block attached, recording
+ * why and where it failed. The original envelope is preserved unchanged inside
+ * the result, so any-language consumers can still read it.
+ */
+declare function annotate(envelope: Envelope, reason: string, originalQueue: string, options?: AnnotateOptions): Envelope;
+
+type deadLetter_AnnotateOptions = AnnotateOptions;
+declare const deadLetter_annotate: typeof annotate;
+declare namespace deadLetter {
+  export { type deadLetter_AnnotateOptions as AnnotateOptions, deadLetter_annotate as annotate };
+}
+
+/**
+ * What a consumer does with a message whose URN has no registered handler.
+ * Mirrors the constants in every other SDK core.
+ */
+declare const UnknownUrnStrategy: {
+    /** Surface an error; let the worker decide. */
+    readonly FAIL: "fail";
+    /** Drop the message. */
+    readonly DELETE: "delete";
+    /** Requeue for another consumer. */
+    readonly RELEASE: "release";
+    /** Route to the dead-letter queue. */
+    readonly DEAD_LETTER: "dead_letter";
+};
+type UnknownUrnStrategy = (typeof UnknownUrnStrategy)[keyof typeof UnknownUrnStrategy];
+
+/** Base error for all BabelQueue failures. */
+declare class BabelQueueError extends Error {
+    constructor(message: string);
+}
+/** Raised when no handler is mapped for a message URN. */
+declare class UnknownUrnError extends BabelQueueError {
+    constructor(urn: string);
+}
+
+export { type AnnotateOptions, BabelQueueError, type DeadLetter, type Envelope, EnvelopeCodec, type HasTraceId, type IncomingEnvelope, type MakeOptions, type Meta, type PolyglotMessage, SCHEMA_VERSION, SOURCE_LANG, UnknownUrnError, UnknownUrnStrategy, annotate, deadLetter };

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+/**
+ * A message that can be produced as a polyglot envelope. Implement it on your
+ * own classes/objects so {@link EnvelopeCodec.fromMessage} can build the canonical
+ * envelope without ever leaking a language-specific class name onto the wire.
+ */
+interface PolyglotMessage {
+    /** The stable URN that identifies this message across languages. */
+    getBabelUrn(): string;
+    /** The pure-JSON payload (no class instances). */
+    toPayload(): Record<string, unknown>;
+}
+/**
+ * Optionally implemented alongside {@link PolyglotMessage} to continue an existing
+ * distributed trace instead of minting a fresh one.
+ */
+interface HasTraceId {
+    /** The trace id to reuse, or null/undefined to mint a new one. */
+    getBabelTraceId(): string | null | undefined;
+}
+
+/** The wire envelope schema version this core implements (versioned independently of the package version). */
+declare const SCHEMA_VERSION = 1;
+/** Stamped into `meta.lang` for envelopes produced by this core. */
+declare const SOURCE_LANG = "node";
+/** Immutable per-message metadata. */
+interface Meta {
+    id: string;
+    queue: string;
+    lang: string;
+    schema_version: number;
+    /** Unix milliseconds, UTC. */
+    created_at: number;
+}
+/** The additive block appended to an envelope when a message is dead-lettered. */
+interface DeadLetter {
+    reason: string;
+    error: string | null;
+    exception: string | null;
+    /** Unix milliseconds, UTC. */
+    failed_at: number;
+    original_queue: string;
+    attempts: number;
+    lang: string;
+}
+/**
+ * The canonical BabelQueue wire message: a strict, language-neutral JSON shape
+ * that every SDK produces and consumes identically. The property order here is
+ * significant — it matches the other cores so {@link EnvelopeCodec.encode} is
+ * byte-for-byte identical across the insertion-order languages (PHP/Python).
+ */
+interface Envelope {
+    /** The message URN (never a class name). */
+    job: string;
+    /** Correlation id, preserved across every hop. */
+    trace_id: string;
+    /** The pure-JSON payload. */
+    data: Record<string, unknown>;
+    meta: Meta;
+    /** Top-level transport retry counter. */
+    attempts: number;
+    /** Present only once the message has been dead-lettered. */
+    dead_letter?: DeadLetter;
+}
+/**
+ * A decoded, not-yet-validated envelope. Fields are loosely typed because they
+ * come off the wire; `urn` is accepted as an inbound alias for `job`. Narrow it
+ * with {@link EnvelopeCodec.accepts} before trusting the contents.
+ */
+interface IncomingEnvelope {
+    job?: string;
+    /** Inbound alias for `job`. */
+    urn?: string;
+    trace_id?: string;
+    data?: unknown;
+    meta?: unknown;
+    attempts?: unknown;
+    dead_letter?: unknown;
+}
+/** Options for {@link EnvelopeCodec.make}. */
+interface MakeOptions {
+    /** Logical queue name recorded in `meta.queue` (default `"default"`). */
+    queue?: string;
+    /** Reuse an existing trace id (trace continuation) instead of minting one. */
+    traceId?: string;
+}
+/**
+ * Builds, encodes and decodes the canonical envelope — the single Node/TypeScript
+ * implementation of the wire format.
+ */
+declare const EnvelopeCodec: {
+    readonly SCHEMA_VERSION: 1;
+    readonly SOURCE_LANG: "node";
+    /**
+     * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id
+     * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.
+     * Throws {@link BabelQueueError} when the URN is blank.
+     */
+    readonly make: (urn: string, data: Record<string, unknown>, options?: MakeOptions) => Envelope;
+    /**
+     * Build the envelope from a {@link PolyglotMessage}. If the message also
+     * implements {@link HasTraceId} and returns a non-empty value, that trace id is
+     * reused.
+     */
+    readonly fromMessage: (message: PolyglotMessage & Partial<HasTraceId>, queue?: string) => Envelope;
+    /**
+     * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the
+     * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching
+     * the other SDK cores.
+     */
+    readonly encode: (envelope: Envelope) => string;
+    /**
+     * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call
+     * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound
+     * alias into `job`.
+     */
+    readonly decode: (raw: string) => IncomingEnvelope;
+    /** The message URN — canonical `job`, with `urn` accepted as an alias. */
+    readonly urn: (envelope: IncomingEnvelope) => string;
+    /**
+     * Whether a consumer should accept this envelope. Rejects a missing URN, an
+     * unsupported `meta.schema_version`, a non-object `data`, a non-integer
+     * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the
+     * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.
+     */
+    readonly accepts: (envelope: IncomingEnvelope) => envelope is Envelope;
+};
+
+/** Options for {@link annotate}. */
+interface AnnotateOptions {
+    /** Defaults to the envelope's current `attempts`. */
+    attempts?: number;
+    /** A human-readable error message (JSON `null` when omitted). */
+    error?: string | null;
+    /** The originating error type/class name (JSON `null` when omitted). */
+    exception?: string | null;
+}
+/**
+ * Return a copy of the envelope with a `dead_letter` block attached, recording
+ * why and where it failed. The original envelope is preserved unchanged inside
+ * the result, so any-language consumers can still read it.
+ */
+declare function annotate(envelope: Envelope, reason: string, originalQueue: string, options?: AnnotateOptions): Envelope;
+
+type deadLetter_AnnotateOptions = AnnotateOptions;
+declare const deadLetter_annotate: typeof annotate;
+declare namespace deadLetter {
+  export { type deadLetter_AnnotateOptions as AnnotateOptions, deadLetter_annotate as annotate };
+}
+
+/**
+ * What a consumer does with a message whose URN has no registered handler.
+ * Mirrors the constants in every other SDK core.
+ */
+declare const UnknownUrnStrategy: {
+    /** Surface an error; let the worker decide. */
+    readonly FAIL: "fail";
+    /** Drop the message. */
+    readonly DELETE: "delete";
+    /** Requeue for another consumer. */
+    readonly RELEASE: "release";
+    /** Route to the dead-letter queue. */
+    readonly DEAD_LETTER: "dead_letter";
+};
+type UnknownUrnStrategy = (typeof UnknownUrnStrategy)[keyof typeof UnknownUrnStrategy];
+
+/** Base error for all BabelQueue failures. */
+declare class BabelQueueError extends Error {
+    constructor(message: string);
+}
+/** Raised when no handler is mapped for a message URN. */
+declare class UnknownUrnError extends BabelQueueError {
+    constructor(urn: string);
+}
+
+export { type AnnotateOptions, BabelQueueError, type DeadLetter, type Envelope, EnvelopeCodec, type HasTraceId, type IncomingEnvelope, type MakeOptions, type Meta, type PolyglotMessage, SCHEMA_VERSION, SOURCE_LANG, UnknownUrnError, UnknownUrnStrategy, annotate, deadLetter };

package/dist/index.js

@@ -0,0 +1,172 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/codec.ts
+import { randomUUID } from "crypto";
+
+// src/errors.ts
+var BabelQueueError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BabelQueueError";
+  }
+};
+var UnknownUrnError = class extends BabelQueueError {
+  constructor(urn) {
+    super(`No handler is mapped for the message URN "${urn}".`);
+    this.name = "UnknownUrnError";
+  }
+};
+
+// src/codec.ts
+var SCHEMA_VERSION = 1;
+var SOURCE_LANG = "node";
+var EnvelopeCodec = {
+  SCHEMA_VERSION,
+  SOURCE_LANG,
+  /**
+   * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id
+   * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.
+   * Throws {@link BabelQueueError} when the URN is blank.
+   */
+  make(urn, data, options = {}) {
+    const resolvedUrn = (urn ?? "").trim();
+    if (resolvedUrn === "") {
+      throw new BabelQueueError(
+        "A polyglot message must expose a stable, non-empty URN so consumers can identify it without any class name."
+      );
+    }
+    const traceId = (options.traceId ?? "").trim() || randomUUID();
+    return {
+      job: resolvedUrn,
+      trace_id: traceId,
+      data: { ...data },
+      meta: {
+        id: randomUUID(),
+        queue: options.queue ?? "default",
+        lang: SOURCE_LANG,
+        schema_version: SCHEMA_VERSION,
+        created_at: Date.now()
+      },
+      attempts: 0
+    };
+  },
+  /**
+   * Build the envelope from a {@link PolyglotMessage}. If the message also
+   * implements {@link HasTraceId} and returns a non-empty value, that trace id is
+   * reused.
+   */
+  fromMessage(message, queue = "default") {
+    const traceId = typeof message.getBabelTraceId === "function" ? message.getBabelTraceId() ?? void 0 : void 0;
+    return EnvelopeCodec.make(message.getBabelUrn(), message.toPayload(), {
+      queue,
+      traceId
+    });
+  },
+  /**
+   * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the
+   * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching
+   * the other SDK cores.
+   */
+  encode(envelope) {
+    return JSON.stringify(envelope);
+  },
+  /**
+   * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call
+   * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound
+   * alias into `job`.
+   */
+  decode(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return {};
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    const envelope = parsed;
+    if (!envelope.job && typeof envelope.urn === "string") {
+      envelope.job = envelope.urn;
+    }
+    return envelope;
+  },
+  /** The message URN — canonical `job`, with `urn` accepted as an alias. */
+  urn(envelope) {
+    const value = envelope?.job ?? envelope?.urn ?? "";
+    return typeof value === "string" ? value.trim() : "";
+  },
+  /**
+   * Whether a consumer should accept this envelope. Rejects a missing URN, an
+   * unsupported `meta.schema_version`, a non-object `data`, a non-integer
+   * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the
+   * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.
+   */
+  accepts(envelope) {
+    if (EnvelopeCodec.urn(envelope) === "") {
+      return false;
+    }
+    const meta = envelope.meta;
+    if (meta === null || typeof meta !== "object" || meta.schema_version !== SCHEMA_VERSION) {
+      return false;
+    }
+    const data = envelope.data;
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+      return false;
+    }
+    const attempts = envelope.attempts;
+    if (typeof attempts !== "number" || !Number.isInteger(attempts)) {
+      return false;
+    }
+    const traceId = envelope.trace_id;
+    if (typeof traceId !== "string" || traceId.trim() === "") {
+      return false;
+    }
+    return true;
+  }
+};
+
+// src/deadLetter.ts
+var deadLetter_exports = {};
+__export(deadLetter_exports, {
+  annotate: () => annotate
+});
+function annotate(envelope, reason, originalQueue, options = {}) {
+  const deadLetter = {
+    reason,
+    error: options.error ?? null,
+    exception: options.exception ?? null,
+    failed_at: Date.now(),
+    original_queue: originalQueue,
+    attempts: options.attempts ?? envelope.attempts ?? 0,
+    lang: SOURCE_LANG
+  };
+  return { ...envelope, dead_letter: deadLetter };
+}
+
+// src/routing.ts
+var UnknownUrnStrategy = {
+  /** Surface an error; let the worker decide. */
+  FAIL: "fail",
+  /** Drop the message. */
+  DELETE: "delete",
+  /** Requeue for another consumer. */
+  RELEASE: "release",
+  /** Route to the dead-letter queue. */
+  DEAD_LETTER: "dead_letter"
+};
+export {
+  BabelQueueError,
+  EnvelopeCodec,
+  SCHEMA_VERSION,
+  SOURCE_LANG,
+  UnknownUrnError,
+  UnknownUrnStrategy,
+  annotate,
+  deadLetter_exports as deadLetter
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/codec.ts","../src/errors.ts","../src/deadLetter.ts","../src/routing.ts"],"sourcesContent":["import { randomUUID } from \"node:crypto\";\n\nimport type { HasTraceId, PolyglotMessage } from \"./contracts.js\";\nimport { BabelQueueError } from \"./errors.js\";\n\n/** The wire envelope schema version this core implements (versioned independently of the package version). */\nexport const SCHEMA_VERSION = 1;\n\n/** Stamped into `meta.lang` for envelopes produced by this core. */\nexport const SOURCE_LANG = \"node\";\n\n/** Immutable per-message metadata. */\nexport interface Meta {\n  id: string;\n  queue: string;\n  lang: string;\n  schema_version: number;\n  /** Unix milliseconds, UTC. */\n  created_at: number;\n}\n\n/** The additive block appended to an envelope when a message is dead-lettered. */\nexport interface DeadLetter {\n  reason: string;\n  error: string | null;\n  exception: string | null;\n  /** Unix milliseconds, UTC. */\n  failed_at: number;\n  original_queue: string;\n  attempts: number;\n  lang: string;\n}\n\n/**\n * The canonical BabelQueue wire message: a strict, language-neutral JSON shape\n * that every SDK produces and consumes identically. The property order here is\n * significant — it matches the other cores so {@link EnvelopeCodec.encode} is\n * byte-for-byte identical across the insertion-order languages (PHP/Python).\n */\nexport interface Envelope {\n  /** The message URN (never a class name). */\n  job: string;\n  /** Correlation id, preserved across every hop. */\n  trace_id: string;\n  /** The pure-JSON payload. */\n  data: Record<string, unknown>;\n  meta: Meta;\n  /** Top-level transport retry counter. */\n  attempts: number;\n  /** Present only once the message has been dead-lettered. */\n  dead_letter?: DeadLetter;\n}\n\n/**\n * A decoded, not-yet-validated envelope. Fields are loosely typed because they\n * come off the wire; `urn` is accepted as an inbound alias for `job`. Narrow it\n * with {@link EnvelopeCodec.accepts} before trusting the contents.\n */\nexport interface IncomingEnvelope {\n  job?: string;\n  /** Inbound alias for `job`. */\n  urn?: string;\n  trace_id?: string;\n  data?: unknown;\n  meta?: unknown;\n  attempts?: unknown;\n  dead_letter?: unknown;\n}\n\n/** Options for {@link EnvelopeCodec.make}. */\nexport interface MakeOptions {\n  /** Logical queue name recorded in `meta.queue` (default `\"default\"`). */\n  queue?: string;\n  /** Reuse an existing trace id (trace continuation) instead of minting one. */\n  traceId?: string;\n}\n\n/**\n * Builds, encodes and decodes the canonical envelope — the single Node/TypeScript\n * implementation of the wire format.\n */\nexport const EnvelopeCodec = {\n  SCHEMA_VERSION,\n  SOURCE_LANG,\n\n  /**\n   * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id\n   * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.\n   * Throws {@link BabelQueueError} when the URN is blank.\n   */\n  make(\n    urn: string,\n    data: Record<string, unknown>,\n    options: MakeOptions = {},\n  ): Envelope {\n    const resolvedUrn = (urn ?? \"\").trim();\n    if (resolvedUrn === \"\") {\n      throw new BabelQueueError(\n        \"A polyglot message must expose a stable, non-empty URN so consumers can identify it without any class name.\",\n      );\n    }\n\n    const traceId = (options.traceId ?? \"\").trim() || randomUUID();\n\n    return {\n      job: resolvedUrn,\n      trace_id: traceId,\n      data: { ...data },\n      meta: {\n        id: randomUUID(),\n        queue: options.queue ?? \"default\",\n        lang: SOURCE_LANG,\n        schema_version: SCHEMA_VERSION,\n        created_at: Date.now(),\n      },\n      attempts: 0,\n    };\n  },\n\n  /**\n   * Build the envelope from a {@link PolyglotMessage}. If the message also\n   * implements {@link HasTraceId} and returns a non-empty value, that trace id is\n   * reused.\n   */\n  fromMessage(\n    message: PolyglotMessage & Partial<HasTraceId>,\n    queue = \"default\",\n  ): Envelope {\n    const traceId =\n      typeof message.getBabelTraceId === \"function\"\n        ? (message.getBabelTraceId() ?? undefined)\n        : undefined;\n\n    return EnvelopeCodec.make(message.getBabelUrn(), message.toPayload(), {\n      queue,\n      traceId,\n    });\n  },\n\n  /**\n   * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the\n   * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching\n   * the other SDK cores.\n   */\n  encode(envelope: Envelope): string {\n    return JSON.stringify(envelope);\n  },\n\n  /**\n   * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call\n   * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound\n   * alias into `job`.\n   */\n  decode(raw: string): IncomingEnvelope {\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      return {};\n    }\n    if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n      return {};\n    }\n\n    const envelope = parsed as IncomingEnvelope;\n    if (!envelope.job && typeof envelope.urn === \"string\") {\n      envelope.job = envelope.urn;\n    }\n    return envelope;\n  },\n\n  /** The message URN — canonical `job`, with `urn` accepted as an alias. */\n  urn(envelope: IncomingEnvelope): string {\n    const value = envelope?.job ?? envelope?.urn ?? \"\";\n    return typeof value === \"string\" ? value.trim() : \"\";\n  },\n\n  /**\n   * Whether a consumer should accept this envelope. Rejects a missing URN, an\n   * unsupported `meta.schema_version`, a non-object `data`, a non-integer\n   * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the\n   * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.\n   */\n  accepts(envelope: IncomingEnvelope): envelope is Envelope {\n    if (EnvelopeCodec.urn(envelope) === \"\") {\n      return false;\n    }\n\n    const meta = envelope.meta;\n    if (\n      meta === null ||\n      typeof meta !== \"object\" ||\n      (meta as Meta).schema_version !== SCHEMA_VERSION\n    ) {\n      return false;\n    }\n\n    const data = envelope.data;\n    if (data === null || typeof data !== \"object\" || Array.isArray(data)) {\n      return false;\n    }\n\n    const attempts = envelope.attempts;\n    if (typeof attempts !== \"number\" || !Number.isInteger(attempts)) {\n      return false;\n    }\n\n    const traceId = envelope.trace_id;\n    if (typeof traceId !== \"string\" || traceId.trim() === \"\") {\n      return false;\n    }\n\n    return true;\n  },\n} as const;\n","/** Base error for all BabelQueue failures. */\nexport class BabelQueueError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"BabelQueueError\";\n  }\n}\n\n/** Raised when no handler is mapped for a message URN. */\nexport class UnknownUrnError extends BabelQueueError {\n  constructor(urn: string) {\n    super(`No handler is mapped for the message URN \"${urn}\".`);\n    this.name = \"UnknownUrnError\";\n  }\n}\n","import type { DeadLetter, Envelope } from \"./codec.js\";\nimport { SOURCE_LANG } from \"./codec.js\";\n\n/** Options for {@link annotate}. */\nexport interface AnnotateOptions {\n  /** Defaults to the envelope's current `attempts`. */\n  attempts?: number;\n  /** A human-readable error message (JSON `null` when omitted). */\n  error?: string | null;\n  /** The originating error type/class name (JSON `null` when omitted). */\n  exception?: string | null;\n}\n\n/**\n * Return a copy of the envelope with a `dead_letter` block attached, recording\n * why and where it failed. The original envelope is preserved unchanged inside\n * the result, so any-language consumers can still read it.\n */\nexport function annotate(\n  envelope: Envelope,\n  reason: string,\n  originalQueue: string,\n  options: AnnotateOptions = {},\n): Envelope {\n  const deadLetter: DeadLetter = {\n    reason,\n    error: options.error ?? null,\n    exception: options.exception ?? null,\n    failed_at: Date.now(),\n    original_queue: originalQueue,\n    attempts: options.attempts ?? envelope.attempts ?? 0,\n    lang: SOURCE_LANG,\n  };\n\n  return { ...envelope, dead_letter: deadLetter };\n}\n","/**\n * What a consumer does with a message whose URN has no registered handler.\n * Mirrors the constants in every other SDK core.\n */\nexport const UnknownUrnStrategy = {\n  /** Surface an error; let the worker decide. */\n  FAIL: \"fail\",\n  /** Drop the message. */\n  DELETE: \"delete\",\n  /** Requeue for another consumer. */\n  RELEASE: \"release\",\n  /** Route to the dead-letter queue. */\n  DEAD_LETTER: \"dead_letter\",\n} as const;\n\nexport type UnknownUrnStrategy =\n  (typeof UnknownUrnStrategy)[keyof typeof UnknownUrnStrategy];\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@babelqueue/core",
+  "version": "0.1.0",
+  "description": "Polyglot Queues, Simplified — the Node/TypeScript core: the canonical BabelQueue wire-envelope codec, contracts and dead-letter helpers.",
+  "keywords": [
+    "queue",
+    "polyglot",
+    "microservices",
+    "json",
+    "envelope",
+    "messaging",
+    "rabbitmq",
+    "redis"
+  ],
+  "homepage": "https://babelqueue.com",
+  "bugs": {
+    "url": "https://github.com/BabelQueue/babelqueue-node/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BabelQueue/babelqueue-node.git"
+  },
+  "license": "MIT",
+  "author": "Muhammet Şafak <info@muhammetsafak.com.tr>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/codec.test.ts test/dead-letter.test.ts test/conformance.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "tsup": "^8",
+    "tsx": "^4",
+    "typescript": "^5.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}