@healthzkit/rabbitmq 0.0.0

package/README.md

@@ -0,0 +1,149 @@
+# @healthzkit/rabbitmq
+
+RabbitMQ **healthzkit** `HealthAdapter` helpers for **[`amqplib`](https://github.com/amqp-node/amqplib)** and **[`amqp-connection-manager`](https://github.com/jwalton/node-amqp-connection-manager)**. Successful checks return `ok` with `metadata.latencyMs` plus any fields from an optional `metadata` hook; failures return `fail` with the caught error.
+
+## Install
+
+```bash
+npm install @healthzkit/rabbitmq healthzkit
+# plus one of:
+npm install amqplib
+npm install amqp-connection-manager
+```
+
+Both clients are optional peers—install the library you use.
+
+## Package entrypoints
+
+| Import                                         | Exports                                                     |
+| ---------------------------------------------- | ----------------------------------------------------------- |
+| `@healthzkit/rabbitmq`                         | `amqplibAdapter`, `amqpConnectionManagerAdapter`, and types |
+| `@healthzkit/rabbitmq/amqplib`                 | `amqplibAdapter` only                                       |
+| `@healthzkit/rabbitmq/amqp-connection-manager` | `amqpConnectionManagerAdapter` only                         |
+
+Use subpath imports when you want to avoid pulling both clients into your bundle analysis path.
+
+## Shared options
+
+Both factories accept `BaseRabbitOptions`:
+
+| Option     | Description                                                                                           |
+| ---------- | ----------------------------------------------------------------------------------------------------- |
+| `metadata` | Optional `(client) => Record<string, unknown>` (sync or async) merged into metadata with `latencyMs`. |
+
+Pass either a connection URL (or URLs) or an existing client/connection manager (not both). The shape depends on the adapter (see below).
+
+## `amqplibAdapter` (`amqplib`)
+
+**Peer:** `amqplib` ≥ 1 or ≥ 2.
+
+Each check opens a channel on the connection and closes it immediately. That exercises the broker path without leaving channels open.
+
+### URL
+
+The adapter lazily imports `amqplib`, calls `connect(url, socketOptions)` once, and reuses the same `ChannelModel` across checks.
+
+```ts
+import { createHealthKit } from "healthzkit";
+import { amqplibAdapter } from "@healthzkit/rabbitmq";
+
+const kit = createHealthKit({
+  checks: [
+    {
+      name: "rabbitmq",
+      type: ["readiness"],
+      adapter: amqplibAdapter({
+        url: process.env.AMQP_URL!,
+        socketOptions: { timeout: 2000 },
+      }),
+    },
+  ],
+});
+```
+
+`url` may be a connection string or an `Options.Connect` object accepted by `amqplib.connect`.
+
+### Existing connection
+
+Pass **`connection`** as an existing `ChannelModel` or `RecoveringChannelModel` from your app. The adapter reuses that connection across checks.
+
+```ts
+import amqplib from "amqplib";
+import { amqplibAdapter } from "@healthzkit/rabbitmq/amqplib";
+
+const connection = await amqplib.connect(process.env.AMQP_URL!);
+
+const adapter = amqplibAdapter({
+  connection,
+  metadata: () => ({ driver: "amqplib" }),
+});
+```
+
+## `amqpConnectionManagerAdapter` (`amqp-connection-manager`)
+
+**Peer:** `amqp-connection-manager` ≥ 4 or ≥ 5.
+
+Each check verifies that the connection manager reports at least one active connection via `isConnected()`. Use this when your app already relies on automatic reconnects and you want readiness to reflect the manager’s view of connectivity rather than opening a new channel.
+
+### URLs
+
+The adapter lazily imports `amqp-connection-manager`, calls `connect(urls, connectionOptions)` once, and reuses the same manager across checks.
+
+```ts
+import { amqpConnectionManagerAdapter } from "@healthzkit/rabbitmq/amqp-connection-manager";
+
+const adapter = amqpConnectionManagerAdapter({
+  urls: [process.env.AMQP_URL!],
+  connectionOptions: {
+    heartbeatIntervalInSeconds: 5,
+    reconnectTimeInSeconds: 2,
+  },
+});
+```
+
+### Existing connection manager
+
+Pass **`connection`** as your app’s `AmqpConnectionManager` instance.
+
+```ts
+import { connect } from "amqp-connection-manager";
+import { amqpConnectionManagerAdapter } from "@healthzkit/rabbitmq";
+
+const connection = connect([process.env.AMQP_URL!]);
+
+const adapter = amqpConnectionManagerAdapter({
+  connection,
+  metadata: () => ({ driver: "amqp-connection-manager" }),
+});
+```
+
+If no connection is active, the check fails with `rabbitmq adapter: connection manager has no active connections.`
+
+## Check result
+
+On success:
+
+```json
+{
+  "status": "ok",
+  "metadata": { "latencyMs": 12 }
+}
+```
+
+On failure, `status` is `"fail"` and `error` is set (see [healthzkit](https://github.com/alasti-company/healthzkit) for how that rolls up into probe responses).
+
+## Scheduling
+
+For brokers that should not be probed on every request, pair these adapters with a **`schedule`** on the check so readiness reads cached results instead of opening channels on every probe. See the **Scheduling** section in the `healthzkit` README.
+
+## Development
+
+From the monorepo root:
+
+```bash
+vp install
+vp test --filter @healthzkit/rabbitmq
+vp pack --filter @healthzkit/rabbitmq
+```
+
+See the repo root `AGENTS.md` for Vite+ / `vp` conventions.

package/dist/amqp-connection-manager.d.mts

@@ -0,0 +1,18 @@
+import { n as HealthAdapter, t as BaseRabbitOptions } from "./shared-CBgGC1WB.mjs";
+import { AmqpConnectionManager, AmqpConnectionManagerOptions } from "amqp-connection-manager";
+
+//#region src/amqp-connection-manager.d.ts
+interface AmqpConnectionManagerAdapterOptionsWithConnection extends BaseRabbitOptions<AmqpConnectionManager> {
+  connection: AmqpConnectionManager;
+  urls?: never;
+  connectionOptions?: never;
+}
+interface AmqpConnectionManagerAdapterOptionsWithUrls extends BaseRabbitOptions<AmqpConnectionManager> {
+  urls: string[];
+  connectionOptions?: AmqpConnectionManagerOptions;
+  connection?: never;
+}
+type AmqpConnectionManagerAdapterOptions = AmqpConnectionManagerAdapterOptionsWithConnection | AmqpConnectionManagerAdapterOptionsWithUrls;
+declare function amqpConnectionManagerAdapter(options: AmqpConnectionManagerAdapterOptions): HealthAdapter;
+//#endregion
+export { AmqpConnectionManagerAdapterOptions, AmqpConnectionManagerAdapterOptionsWithConnection, AmqpConnectionManagerAdapterOptionsWithUrls, amqpConnectionManagerAdapter };

package/dist/amqp-connection-manager.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"./shared-B-1hAtzF.mjs";function n(n){let r=null,i=null;async function a(){return`connection`in n&&n.connection?n.connection:r||i||(i=(async()=>{let{connect:e}=await import(`amqp-connection-manager`),t=e(n.urls,n.connectionOptions);return r=t,i=null,t})(),i)}return{async check(){try{let t=await a(),r=Date.now();if(!t.isConnected())throw Error(`rabbitmq adapter: connection manager has no active connections.`);let i=Date.now()-r,o=n.metadata?n.metadata(t):void 0;return e(i,o instanceof Promise?await o:o)}catch(e){return t(e)}}}}export{n as amqpConnectionManagerAdapter};

package/dist/amqplib.d.mts

@@ -0,0 +1,19 @@
+import { n as HealthAdapter, t as BaseRabbitOptions } from "./shared-CBgGC1WB.mjs";
+import { ChannelModel, Options, RecoveringChannelModel, SocketOptions } from "amqplib";
+
+//#region src/amqplib.d.ts
+type AmqplibClient = ChannelModel | RecoveringChannelModel;
+interface AmqplibAdapterOptionsWithConnection extends BaseRabbitOptions<AmqplibClient> {
+  connection: AmqplibClient;
+  url?: never;
+  socketOptions?: never;
+}
+interface AmqplibAdapterOptionsWithUrl extends BaseRabbitOptions<AmqplibClient> {
+  url: string | Options.Connect;
+  socketOptions?: SocketOptions;
+  connection?: never;
+}
+type AmqplibAdapterOptions = AmqplibAdapterOptionsWithConnection | AmqplibAdapterOptionsWithUrl;
+declare function amqplibAdapter(options: AmqplibAdapterOptions): HealthAdapter;
+//#endregion
+export { AmqplibAdapterOptions, AmqplibAdapterOptionsWithConnection, AmqplibAdapterOptionsWithUrl, AmqplibClient, amqplibAdapter };

package/dist/amqplib.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"./shared-B-1hAtzF.mjs";function n(n){let r=null,i=null;async function a(){return`connection`in n&&n.connection?n.connection:r||i||(i=(async()=>{try{let{default:e}=await import(`amqplib`),t=await e.connect(n.url,n.socketOptions);return r=t,t}finally{i=null}})(),i)}return{async check(){try{let t=await a(),r=Date.now();await(await t.createChannel()).close();let i=Date.now()-r,o=n.metadata?n.metadata(t):void 0;return e(i,o instanceof Promise?await o:o)}catch(e){return t(e)}}}}export{n as amqplibAdapter};

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { AmqpConnectionManagerAdapterOptions, amqpConnectionManagerAdapter } from "./amqp-connection-manager.mjs";
+import { AmqplibAdapterOptions, amqplibAdapter } from "./amqplib.mjs";
+export { type AmqpConnectionManagerAdapterOptions, type AmqplibAdapterOptions, amqpConnectionManagerAdapter, amqplibAdapter };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{amqplibAdapter as e}from"./amqplib.mjs";import{amqpConnectionManagerAdapter as t}from"./amqp-connection-manager.mjs";export{t as amqpConnectionManagerAdapter,e as amqplibAdapter};

package/dist/shared-B-1hAtzF.mjs

@@ -0,0 +1 @@
+function e(e,t){return{status:`ok`,metadata:{...t,latencyMs:e}}}function t(e){return{status:`fail`,error:e instanceof Error?e:Error(String(e))}}export{e as n,t};

package/dist/shared-CBgGC1WB.d.mts

@@ -0,0 +1,13 @@
+import { HealthAdapter } from "healthzkit";
+
+//#region src/shared.d.ts
+type MetadataFn<TClient> = (client: TClient) => Promise<Record<string, unknown>> | Record<string, unknown>;
+interface BaseRabbitOptions<TClient> {
+  /**
+   * Optional function to populate metadata in the check result.
+   * Receives the resolved client so you can run additional operations.
+   */
+  metadata?: MetadataFn<TClient>;
+}
+//#endregion
+export { HealthAdapter as n, BaseRabbitOptions as t };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@healthzkit/rabbitmq",
+  "version": "0.0.0",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alasti-company/healthzkit.dev",
+    "directory": "packages/rabbitmq"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./amqp-connection-manager": "./dist/amqp-connection-manager.mjs",
+    "./amqplib": "./dist/amqplib.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "@types/amqplib": "^0.10.8",
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "amqp-connection-manager": "^5.0.0",
+    "amqplib": "^2.0.1",
+    "bumpp": "^11.1.0",
+    "healthzkit": "workspace:*",
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.1.20"
+  },
+  "peerDependencies": {
+    "amqp-connection-manager": ">=4.0.0 || >=5.0.0",
+    "amqplib": ">=1.0.0 || >=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "amqp-connection-manager": {
+      "optional": true
+    },
+    "amqplib": {
+      "optional": true
+    }
+  }
+}