@rtorcato/api-amqp 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Torcato
+
+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,41 @@
+# @rtorcato/api-amqp
+
+Typed [amqplib](https://github.com/amqp-node/amqplib) publisher/consumer helpers for RabbitMQ — JSON encoding, exchange/queue assertion, and ack-on-success / nack-on-throw.
+
+## Install
+
+```sh
+pnpm add @rtorcato/api-amqp amqplib
+```
+
+`amqplib` is a peer dependency — you bring your own version (and often a shared connection).
+
+## Usage
+
+```ts
+import { connect, createPublisher, createConsumer } from '@rtorcato/api-amqp'
+
+const { connection, channel } = await connect('amqp://localhost')
+
+// Publisher — asserts the exchange, then JSON-encodes each message
+const publish = await createPublisher<{ id: string }>(channel, { exchange: 'orders' })
+publish('order.created', { id: '1' })
+
+// Consumer — asserts the queue, acks on success, nacks when the handler throws
+await createConsumer<{ id: string }>(channel, { queue: 'orders' }, async (order) => {
+  await process(order)
+})
+```
+
+`connect` returns `{ connection, channel }`; close the channel then the connection on shutdown. The publisher/consumer helpers also accept a channel you created yourself (e.g. a shared one).
+
+## Options
+
+- **Publisher:** `{ exchange, exchangeType?, durable? }` — `exchangeType` defaults to `'topic'`, `durable` to `true`. Messages are published `persistent` with `content-type: application/json`.
+- **Consumer:** `{ queue, durable?, prefetch?, requeueOnError? }` — `prefetch` defaults to `10`. On handler throw the message is nacked; set `requeueOnError: true` to requeue (beware poison-message loops).
+
+## Reconnection
+
+Not included — amqplib does not reconnect on its own. For production resilience, wrap `connect` in a retry loop or use [`amqp-connection-manager`](https://github.com/jwalton/node-amqp-connection-manager) and pass its channel to these helpers.
+
+Source: https://github.com/rtorcato/api-common/tree/main/packages/api-amqp

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import amqp, { type Channel, type ConsumeMessage, type Options } from 'amqplib';
+/** An open connection + channel. Close the channel then the connection when done. */
+export type AmqpConnection = Awaited<ReturnType<typeof amqp.connect>>;
+export interface AmqpChannel {
+    connection: AmqpConnection;
+    channel: Channel;
+}
+/** Open a connection and a channel to the broker (e.g. `amqp://localhost`). */
+export declare function connect(url: string, socketOptions?: unknown): Promise<AmqpChannel>;
+export interface PublisherOptions {
+    exchange: string;
+    /** Exchange type. Default: `'topic'`. */
+    exchangeType?: 'direct' | 'topic' | 'fanout' | 'headers';
+    /** Survive a broker restart. Default: `true`. */
+    durable?: boolean;
+}
+/**
+ * Assert the exchange and return a typed publish function that JSON-encodes messages.
+ *
+ * @example
+ * ```ts
+ * const publish = await createPublisher(channel, { exchange: 'orders' })
+ * publish('order.created', { id: '1', total: 42 })
+ * ```
+ */
+export declare function createPublisher<T = unknown>(channel: Channel, options: PublisherOptions): Promise<(routingKey: string, message: T, publishOptions?: Options.Publish) => boolean>;
+export interface ConsumerOptions {
+    queue: string;
+    /** Survive a broker restart. Default: `true`. */
+    durable?: boolean;
+    /** Max unacknowledged messages in flight. Default: `10`. */
+    prefetch?: number;
+    /** Requeue a message when the handler throws (risks a poison-message loop). Default: `false`. */
+    requeueOnError?: boolean;
+}
+/**
+ * Assert the queue and consume JSON messages. The message is acked when the handler
+ * resolves, and nacked when it throws (requeued only if `requeueOnError`).
+ *
+ * @example
+ * ```ts
+ * await createConsumer<OrderCreated>(channel, { queue: 'orders' }, async (order) => {
+ *   await process(order)
+ * })
+ * ```
+ */
+export declare function createConsumer<T = unknown>(channel: Channel, options: ConsumerOptions, handler: (message: T, raw: ConsumeMessage) => Promise<void> | void): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,EAAE,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAA;AAU/E,qFAAqF;AACrF,MAAM,MAAM,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,CAAA;AAErE,MAAM,WAAW,WAAW;IAC3B,UAAU,EAAE,cAAc,CAAA;IAC1B,OAAO,EAAE,OAAO,CAAA;CAChB;AAED,+EAA+E;AAC/E,wBAAsB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAIxF;AAED,MAAM,WAAW,gBAAgB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;IACxD,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAChD,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,gBAAgB,GACvB,OAAO,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,cAAc,CAAC,EAAE,OAAO,CAAC,OAAO,KAAK,OAAO,CAAC,CAUxF;AAED,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,cAAc,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,CAAC,GAAG,OAAO,EAC/C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,GAChE,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/index.js

@@ -0,0 +1,54 @@
+import amqp from 'amqplib';
+/** Open a connection and a channel to the broker (e.g. `amqp://localhost`). */
+export async function connect(url, socketOptions) {
+    const connection = await amqp.connect(url, socketOptions);
+    const channel = await connection.createChannel();
+    return { connection, channel };
+}
+/**
+ * Assert the exchange and return a typed publish function that JSON-encodes messages.
+ *
+ * @example
+ * ```ts
+ * const publish = await createPublisher(channel, { exchange: 'orders' })
+ * publish('order.created', { id: '1', total: 42 })
+ * ```
+ */
+export async function createPublisher(channel, options) {
+    await channel.assertExchange(options.exchange, options.exchangeType ?? 'topic', {
+        durable: options.durable ?? true,
+    });
+    return (routingKey, message, publishOptions) => channel.publish(options.exchange, routingKey, Buffer.from(JSON.stringify(message)), {
+        contentType: 'application/json',
+        persistent: true,
+        ...publishOptions,
+    });
+}
+/**
+ * Assert the queue and consume JSON messages. The message is acked when the handler
+ * resolves, and nacked when it throws (requeued only if `requeueOnError`).
+ *
+ * @example
+ * ```ts
+ * await createConsumer<OrderCreated>(channel, { queue: 'orders' }, async (order) => {
+ *   await process(order)
+ * })
+ * ```
+ */
+export async function createConsumer(channel, options, handler) {
+    await channel.assertQueue(options.queue, { durable: options.durable ?? true });
+    await channel.prefetch(options.prefetch ?? 10);
+    await channel.consume(options.queue, async (raw) => {
+        if (!raw)
+            return; // consumer cancelled by the broker
+        try {
+            const message = JSON.parse(raw.content.toString());
+            await handler(message, raw);
+            channel.ack(raw);
+        }
+        catch {
+            channel.nack(raw, false, options.requeueOnError ?? false);
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAyD,MAAM,SAAS,CAAA;AAkB/E,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,GAAW,EAAE,aAAuB;IACjE,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,aAAa,CAAC,CAAA;IACzD,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,aAAa,EAAE,CAAA;IAChD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAA;AAC/B,CAAC;AAUD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACpC,OAAgB,EAChB,OAAyB;IAEzB,MAAM,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,YAAY,IAAI,OAAO,EAAE;QAC/E,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI;KAChC,CAAC,CAAA;IACF,OAAO,CAAC,UAAU,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,CAC9C,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE;QACnF,WAAW,EAAE,kBAAkB;QAC/B,UAAU,EAAE,IAAI;QAChB,GAAG,cAAc;KACjB,CAAC,CAAA;AACJ,CAAC;AAYD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,OAAgB,EAChB,OAAwB,EACxB,OAAkE;IAElE,MAAM,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC,CAAA;IAC9E,MAAM,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAA;IAC9C,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;QAClD,IAAI,CAAC,GAAG;YAAE,OAAM,CAAC,mCAAmC;QACpD,IAAI,CAAC;YACJ,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAM,CAAA;YACvD,MAAM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;YAC3B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACjB,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC,CAAA;QAC1D,CAAC;IACF,CAAC,CAAC,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@rtorcato/api-amqp",
+  "version": "0.2.0",
+  "description": "Typed amqplib publisher/consumer helpers for RabbitMQ — JSON encoding, exchange/queue assertion, and ack/nack handling.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Richard Torcato",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "amqplib": "^0.10.0"
+  },
+  "devDependencies": {
+    "@types/amqplib": "^0.10.5",
+    "amqplib": "^0.10.9",
+    "typescript": "~6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "api",
+    "nodejs",
+    "typescript",
+    "amqp",
+    "amqplib",
+    "rabbitmq",
+    "messaging"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rtorcato/api-common.git",
+    "directory": "packages/api-amqp"
+  },
+  "homepage": "https://github.com/rtorcato/api-common/tree/main/packages/api-amqp#readme",
+  "bugs": {
+    "url": "https://github.com/rtorcato/api-common/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}