@babelqueue/bullmq 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @babelqueue/bullmq
+
+[![npm](https://img.shields.io/npm/v/@babelqueue/bullmq.svg)](https://www.npmjs.com/package/@babelqueue/bullmq)
+
+> **Polyglot Queues, Simplified.** A [BullMQ](https://docs.bullmq.io) adapter for
+> BabelQueue: your BullMQ jobs carry the canonical BabelQueue envelope and are
+> routed by URN — the same contract the PHP/Laravel, Python, Go, Java and .NET SDKs
+> speak.
+
+```bash
+npm install @babelqueue/bullmq bullmq
+```
+
+## Produce
+
+```ts
+import { Queue } from "bullmq";
+import { publish } from "@babelqueue/bullmq";
+
+const queue = new Queue("orders", { connection: { host: "localhost", port: 6379 } });
+await publish(queue, "urn:babel:orders:created", { order_id: 1042 });
+// job name = the URN; job data = the canonical { job, trace_id, data, meta, attempts } envelope
+```
+
+## Consume
+
+```ts
+import { Worker } from "bullmq";
+import { processor } from "@babelqueue/bullmq";
+
+new Worker(
+  "orders",
+  processor({
+    "urn:babel:orders:created": async (env) => {
+      console.log(env.data.order_id, env.trace_id);
+    },
+  }),
+  { connection: { host: "localhost", port: 6379 } },
+);
+```
+
+`processor` validates each envelope (`EnvelopeCodec.accepts`) and routes by URN; a
+non-conformant envelope throws (BullMQ retries/fails per its options), and an
+unmapped URN throws unless you pass `onUnknownUrn`.
+
+> BullMQ stores jobs in its own Redis structures, so this gives the canonical
+> envelope **shape + URN routing + trace propagation** to BullMQ-based Node
+> services. For raw cross-language queues, other SDKs read/write plain broker
+> queues directly.
+
+## License
+
+[MIT](../../LICENSE) © Muhammet Şafak · [babelqueue.com](https://babelqueue.com)

package/dist/index.cjs

@@ -0,0 +1,60 @@
+"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, {
+  processor: () => processor,
+  publish: () => publish
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@babelqueue/core");
+async function publish(queue, urn, data, options = {}) {
+  const envelope = import_core.EnvelopeCodec.make(urn, data, {
+    queue: queue.name,
+    traceId: options.traceId
+  });
+  await queue.add(urn, envelope, options.jobsOptions);
+  return envelope.meta.id;
+}
+function processor(handlers, options = {}) {
+  return async (job) => {
+    const envelope = job.data;
+    if (!import_core.EnvelopeCodec.accepts(envelope)) {
+      throw new import_core.BabelQueueError(
+        `Rejected a non-conformant BabelQueue envelope on job ${job.id ?? "?"}.`
+      );
+    }
+    const urn = import_core.EnvelopeCodec.urn(envelope);
+    const handler = handlers[urn];
+    if (!handler) {
+      if (options.onUnknownUrn) {
+        return options.onUnknownUrn(envelope, job);
+      }
+      throw new import_core.UnknownUrnError(urn);
+    }
+    return handler(envelope, job);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  processor,
+  publish
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * BullMQ adapter for BabelQueue.\n *\n * It makes your BullMQ jobs carry the canonical BabelQueue envelope and routes\n * them by URN, so a BullMQ-based Node service speaks the same contract (envelope\n * shape, URN identity, trace propagation) as the PHP/Laravel, Python, Go, Java and\n * .NET SDKs.\n *\n *     import { Queue, Worker } from \"bullmq\";\n *     import { publish, processor } from \"@babelqueue/bullmq\";\n *\n *     const queue = new Queue(\"orders\", { connection });\n *     await publish(queue, \"urn:babel:orders:created\", { order_id: 1042 });\n *\n *     new Worker(\"orders\", processor({\n *       \"urn:babel:orders:created\": async (env) => { ... },\n *     }), { connection });\n */\n\nimport {\n  BabelQueueError,\n  EnvelopeCodec,\n  UnknownUrnError,\n  type Envelope,\n  type IncomingEnvelope,\n} from \"@babelqueue/core\";\nimport type { Job, JobsOptions, Queue } from \"bullmq\";\n\n/** A URN handler. Receives the validated envelope and the raw BullMQ job. */\nexport type BabelHandler = (envelope: Envelope, job: Job) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link publish}. */\nexport interface PublishOptions {\n  /** Reuse an existing trace id (trace continuation). */\n  traceId?: string;\n  /** BullMQ job options (delay, attempts, backoff, …). */\n  jobsOptions?: JobsOptions;\n}\n\n/**\n * Build the canonical envelope for `(urn, data)` and add it as a BullMQ job (the\n * job name is the URN, the job data is the envelope). Returns the message id\n * (`meta.id`).\n */\nexport async function publish(\n  queue: Queue,\n  urn: string,\n  data: Record<string, unknown>,\n  options: PublishOptions = {},\n): Promise<string> {\n  const envelope = EnvelopeCodec.make(urn, data, {\n    queue: queue.name,\n    traceId: options.traceId,\n  });\n  await queue.add(urn, envelope, options.jobsOptions);\n  return envelope.meta.id;\n}\n\n/** Options for {@link processor}. */\nexport interface ProcessorOptions {\n  /** Called instead of throwing when a job's URN has no handler. */\n  onUnknownUrn?: (envelope: IncomingEnvelope, job: Job) => unknown | Promise<unknown>;\n}\n\n/**\n * Build a BullMQ processor that decodes each job's envelope, validates it, and\n * routes it to the handler registered for its URN. A non-conformant envelope\n * throws (so BullMQ retries / fails the job per its options); an unmapped URN\n * throws unless `onUnknownUrn` is given.\n *\n *     new Worker(\"orders\", processor(handlers), { connection });\n */\nexport function processor(\n  handlers: BabelHandlers,\n  options: ProcessorOptions = {},\n): (job: Job) => Promise<unknown> {\n  return async (job: Job): Promise<unknown> => {\n    const envelope = job.data as IncomingEnvelope;\n\n    if (!EnvelopeCodec.accepts(envelope)) {\n      throw new BabelQueueError(\n        `Rejected a non-conformant BabelQueue envelope on job ${job.id ?? \"?\"}.`,\n      );\n    }\n\n    const urn = EnvelopeCodec.urn(envelope);\n    const handler = handlers[urn];\n    if (!handler) {\n      if (options.onUnknownUrn) {\n        return options.onUnknownUrn(envelope, job);\n      }\n      throw new UnknownUrnError(urn);\n    }\n\n    return handler(envelope, job);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAmBA,kBAMO;AAsBP,eAAsB,QACpB,OACA,KACA,MACA,UAA0B,CAAC,GACV;AACjB,QAAM,WAAW,0BAAc,KAAK,KAAK,MAAM;AAAA,IAC7C,OAAO,MAAM;AAAA,IACb,SAAS,QAAQ;AAAA,EACnB,CAAC;AACD,QAAM,MAAM,IAAI,KAAK,UAAU,QAAQ,WAAW;AAClD,SAAO,SAAS,KAAK;AACvB;AAgBO,SAAS,UACd,UACA,UAA4B,CAAC,GACG;AAChC,SAAO,OAAO,QAA+B;AAC3C,UAAM,WAAW,IAAI;AAErB,QAAI,CAAC,0BAAc,QAAQ,QAAQ,GAAG;AACpC,YAAM,IAAI;AAAA,QACR,wDAAwD,IAAI,MAAM,GAAG;AAAA,MACvE;AAAA,IACF;AAEA,UAAM,MAAM,0BAAc,IAAI,QAAQ;AACtC,UAAM,UAAU,SAAS,GAAG;AAC5B,QAAI,CAAC,SAAS;AACZ,UAAI,QAAQ,cAAc;AACxB,eAAO,QAAQ,aAAa,UAAU,GAAG;AAAA,MAC3C;AACA,YAAM,IAAI,4BAAgB,GAAG;AAAA,IAC/B;AAEA,WAAO,QAAQ,UAAU,GAAG;AAAA,EAC9B;AACF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,55 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+import { Job, JobsOptions, Queue } from 'bullmq';
+
+/**
+ * BullMQ adapter for BabelQueue.
+ *
+ * It makes your BullMQ jobs carry the canonical BabelQueue envelope and routes
+ * them by URN, so a BullMQ-based Node service speaks the same contract (envelope
+ * shape, URN identity, trace propagation) as the PHP/Laravel, Python, Go, Java and
+ * .NET SDKs.
+ *
+ *     import { Queue, Worker } from "bullmq";
+ *     import { publish, processor } from "@babelqueue/bullmq";
+ *
+ *     const queue = new Queue("orders", { connection });
+ *     await publish(queue, "urn:babel:orders:created", { order_id: 1042 });
+ *
+ *     new Worker("orders", processor({
+ *       "urn:babel:orders:created": async (env) => { ... },
+ *     }), { connection });
+ */
+
+/** A URN handler. Receives the validated envelope and the raw BullMQ job. */
+type BabelHandler = (envelope: Envelope, job: Job) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link publish}. */
+interface PublishOptions {
+    /** Reuse an existing trace id (trace continuation). */
+    traceId?: string;
+    /** BullMQ job options (delay, attempts, backoff, …). */
+    jobsOptions?: JobsOptions;
+}
+/**
+ * Build the canonical envelope for `(urn, data)` and add it as a BullMQ job (the
+ * job name is the URN, the job data is the envelope). Returns the message id
+ * (`meta.id`).
+ */
+declare function publish(queue: Queue, urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+/** Options for {@link processor}. */
+interface ProcessorOptions {
+    /** Called instead of throwing when a job's URN has no handler. */
+    onUnknownUrn?: (envelope: IncomingEnvelope, job: Job) => unknown | Promise<unknown>;
+}
+/**
+ * Build a BullMQ processor that decodes each job's envelope, validates it, and
+ * routes it to the handler registered for its URN. A non-conformant envelope
+ * throws (so BullMQ retries / fails the job per its options); an unmapped URN
+ * throws unless `onUnknownUrn` is given.
+ *
+ *     new Worker("orders", processor(handlers), { connection });
+ */
+declare function processor(handlers: BabelHandlers, options?: ProcessorOptions): (job: Job) => Promise<unknown>;
+
+export { type BabelHandler, type BabelHandlers, type ProcessorOptions, type PublishOptions, processor, publish };

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+import { Job, JobsOptions, Queue } from 'bullmq';
+
+/**
+ * BullMQ adapter for BabelQueue.
+ *
+ * It makes your BullMQ jobs carry the canonical BabelQueue envelope and routes
+ * them by URN, so a BullMQ-based Node service speaks the same contract (envelope
+ * shape, URN identity, trace propagation) as the PHP/Laravel, Python, Go, Java and
+ * .NET SDKs.
+ *
+ *     import { Queue, Worker } from "bullmq";
+ *     import { publish, processor } from "@babelqueue/bullmq";
+ *
+ *     const queue = new Queue("orders", { connection });
+ *     await publish(queue, "urn:babel:orders:created", { order_id: 1042 });
+ *
+ *     new Worker("orders", processor({
+ *       "urn:babel:orders:created": async (env) => { ... },
+ *     }), { connection });
+ */
+
+/** A URN handler. Receives the validated envelope and the raw BullMQ job. */
+type BabelHandler = (envelope: Envelope, job: Job) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link publish}. */
+interface PublishOptions {
+    /** Reuse an existing trace id (trace continuation). */
+    traceId?: string;
+    /** BullMQ job options (delay, attempts, backoff, …). */
+    jobsOptions?: JobsOptions;
+}
+/**
+ * Build the canonical envelope for `(urn, data)` and add it as a BullMQ job (the
+ * job name is the URN, the job data is the envelope). Returns the message id
+ * (`meta.id`).
+ */
+declare function publish(queue: Queue, urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+/** Options for {@link processor}. */
+interface ProcessorOptions {
+    /** Called instead of throwing when a job's URN has no handler. */
+    onUnknownUrn?: (envelope: IncomingEnvelope, job: Job) => unknown | Promise<unknown>;
+}
+/**
+ * Build a BullMQ processor that decodes each job's envelope, validates it, and
+ * routes it to the handler registered for its URN. A non-conformant envelope
+ * throws (so BullMQ retries / fails the job per its options); an unmapped URN
+ * throws unless `onUnknownUrn` is given.
+ *
+ *     new Worker("orders", processor(handlers), { connection });
+ */
+declare function processor(handlers: BabelHandlers, options?: ProcessorOptions): (job: Job) => Promise<unknown>;
+
+export { type BabelHandler, type BabelHandlers, type ProcessorOptions, type PublishOptions, processor, publish };

package/dist/index.js

@@ -0,0 +1,38 @@
+// src/index.ts
+import {
+  BabelQueueError,
+  EnvelopeCodec,
+  UnknownUrnError
+} from "@babelqueue/core";
+async function publish(queue, urn, data, options = {}) {
+  const envelope = EnvelopeCodec.make(urn, data, {
+    queue: queue.name,
+    traceId: options.traceId
+  });
+  await queue.add(urn, envelope, options.jobsOptions);
+  return envelope.meta.id;
+}
+function processor(handlers, options = {}) {
+  return async (job) => {
+    const envelope = job.data;
+    if (!EnvelopeCodec.accepts(envelope)) {
+      throw new BabelQueueError(
+        `Rejected a non-conformant BabelQueue envelope on job ${job.id ?? "?"}.`
+      );
+    }
+    const urn = EnvelopeCodec.urn(envelope);
+    const handler = handlers[urn];
+    if (!handler) {
+      if (options.onUnknownUrn) {
+        return options.onUnknownUrn(envelope, job);
+      }
+      throw new UnknownUrnError(urn);
+    }
+    return handler(envelope, job);
+  };
+}
+export {
+  processor,
+  publish
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * BullMQ adapter for BabelQueue.\n *\n * It makes your BullMQ jobs carry the canonical BabelQueue envelope and routes\n * them by URN, so a BullMQ-based Node service speaks the same contract (envelope\n * shape, URN identity, trace propagation) as the PHP/Laravel, Python, Go, Java and\n * .NET SDKs.\n *\n *     import { Queue, Worker } from \"bullmq\";\n *     import { publish, processor } from \"@babelqueue/bullmq\";\n *\n *     const queue = new Queue(\"orders\", { connection });\n *     await publish(queue, \"urn:babel:orders:created\", { order_id: 1042 });\n *\n *     new Worker(\"orders\", processor({\n *       \"urn:babel:orders:created\": async (env) => { ... },\n *     }), { connection });\n */\n\nimport {\n  BabelQueueError,\n  EnvelopeCodec,\n  UnknownUrnError,\n  type Envelope,\n  type IncomingEnvelope,\n} from \"@babelqueue/core\";\nimport type { Job, JobsOptions, Queue } from \"bullmq\";\n\n/** A URN handler. Receives the validated envelope and the raw BullMQ job. */\nexport type BabelHandler = (envelope: Envelope, job: Job) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link publish}. */\nexport interface PublishOptions {\n  /** Reuse an existing trace id (trace continuation). */\n  traceId?: string;\n  /** BullMQ job options (delay, attempts, backoff, …). */\n  jobsOptions?: JobsOptions;\n}\n\n/**\n * Build the canonical envelope for `(urn, data)` and add it as a BullMQ job (the\n * job name is the URN, the job data is the envelope). Returns the message id\n * (`meta.id`).\n */\nexport async function publish(\n  queue: Queue,\n  urn: string,\n  data: Record<string, unknown>,\n  options: PublishOptions = {},\n): Promise<string> {\n  const envelope = EnvelopeCodec.make(urn, data, {\n    queue: queue.name,\n    traceId: options.traceId,\n  });\n  await queue.add(urn, envelope, options.jobsOptions);\n  return envelope.meta.id;\n}\n\n/** Options for {@link processor}. */\nexport interface ProcessorOptions {\n  /** Called instead of throwing when a job's URN has no handler. */\n  onUnknownUrn?: (envelope: IncomingEnvelope, job: Job) => unknown | Promise<unknown>;\n}\n\n/**\n * Build a BullMQ processor that decodes each job's envelope, validates it, and\n * routes it to the handler registered for its URN. A non-conformant envelope\n * throws (so BullMQ retries / fails the job per its options); an unmapped URN\n * throws unless `onUnknownUrn` is given.\n *\n *     new Worker(\"orders\", processor(handlers), { connection });\n */\nexport function processor(\n  handlers: BabelHandlers,\n  options: ProcessorOptions = {},\n): (job: Job) => Promise<unknown> {\n  return async (job: Job): Promise<unknown> => {\n    const envelope = job.data as IncomingEnvelope;\n\n    if (!EnvelopeCodec.accepts(envelope)) {\n      throw new BabelQueueError(\n        `Rejected a non-conformant BabelQueue envelope on job ${job.id ?? \"?\"}.`,\n      );\n    }\n\n    const urn = EnvelopeCodec.urn(envelope);\n    const handler = handlers[urn];\n    if (!handler) {\n      if (options.onUnknownUrn) {\n        return options.onUnknownUrn(envelope, job);\n      }\n      throw new UnknownUrnError(urn);\n    }\n\n    return handler(envelope, job);\n  };\n}\n"],"mappings":";AAmBA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AAsBP,eAAsB,QACpB,OACA,KACA,MACA,UAA0B,CAAC,GACV;AACjB,QAAM,WAAW,cAAc,KAAK,KAAK,MAAM;AAAA,IAC7C,OAAO,MAAM;AAAA,IACb,SAAS,QAAQ;AAAA,EACnB,CAAC;AACD,QAAM,MAAM,IAAI,KAAK,UAAU,QAAQ,WAAW;AAClD,SAAO,SAAS,KAAK;AACvB;AAgBO,SAAS,UACd,UACA,UAA4B,CAAC,GACG;AAChC,SAAO,OAAO,QAA+B;AAC3C,UAAM,WAAW,IAAI;AAErB,QAAI,CAAC,cAAc,QAAQ,QAAQ,GAAG;AACpC,YAAM,IAAI;AAAA,QACR,wDAAwD,IAAI,MAAM,GAAG;AAAA,MACvE;AAAA,IACF;AAEA,UAAM,MAAM,cAAc,IAAI,QAAQ;AACtC,UAAM,UAAU,SAAS,GAAG;AAC5B,QAAI,CAAC,SAAS;AACZ,UAAI,QAAQ,cAAc;AACxB,eAAO,QAAQ,aAAa,UAAU,GAAG;AAAA,MAC3C;AACA,YAAM,IAAI,gBAAgB,GAAG;AAAA,IAC/B;AAEA,WAAO,QAAQ,UAAU,GAAG;AAAA,EAC9B;AACF;","names":[]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@babelqueue/bullmq",
+  "version": "0.1.0",
+  "description": "BullMQ adapter for BabelQueue — canonical-envelope jobs and a URN-routed processor.",
+  "keywords": ["babelqueue", "bullmq", "queue", "polyglot", "redis", "messaging"],
+  "homepage": "https://babelqueue.com",
+  "bugs": {
+    "url": "https://github.com/BabelQueue/babelqueue-node-adapters/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BabelQueue/babelqueue-node-adapters.git",
+    "directory": "packages/bullmq"
+  },
+  "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/*.test.ts"
+  },
+  "dependencies": {
+    "@babelqueue/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "bullmq": "^5.0.0"
+  },
+  "devDependencies": {
+    "bullmq": "^5.34.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}