@healthzkit/kafka 0.0.0

package/README.md

@@ -0,0 +1,138 @@
+# @healthzkit/kafka
+
+Kafka **healthzkit** `HealthAdapter` helpers for **[`kafkajs`](https://kafka.js.org/)** and **[`node-rdkafka`](https://github.com/Blizzard/node-rdkafka)**. 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/kafka healthzkit
+# plus one of:
+npm install kafkajs
+npm install node-rdkafka
+```
+
+Both clients are optional peers—install the library you use.
+
+`node-rdkafka` is a native addon (requires `librdkafka` at build/runtime). Prefer **`kafkajs`** when you want a pure JavaScript client.
+
+## Shared options
+
+Both factories accept `BaseKafkaOptions`:
+
+| Option     | Description                                                                                           |
+| ---------- | ----------------------------------------------------------------------------------------------------- |
+| `metadata` | Optional `(client) => Record<string, unknown>` (sync or async) merged into metadata with `latencyMs`. |
+
+Pass either client configuration or an existing client/producer/consumer (not both). The shape depends on the adapter (see below).
+
+## `kafkajsAdapter` (`kafkajs`)
+
+**Peer:** `kafkajs` ≥ 2.
+
+Each check creates an admin client, connects, calls `describeCluster()`, and disconnects the admin handle. The underlying `Kafka` instance is reused when you pass `config`.
+
+### Config
+
+The adapter lazily imports `kafkajs`, constructs `new Kafka(config)` once, and reuses it across checks.
+
+```ts
+import { createHealthKit } from "healthzkit";
+import { kafkajsAdapter } from "@healthzkit/kafka";
+
+const kit = createHealthKit({
+  checks: [
+    {
+      name: "kafka",
+      type: ["readiness"],
+      adapter: kafkajsAdapter({
+        config: { brokers: [process.env.KAFKA_BROKERS!] },
+      }),
+    },
+  ],
+});
+```
+
+`config` is the first argument to the `Kafka` constructor (for example `brokers`, `clientId`, `ssl`, `sasl`).
+
+### Existing client
+
+Pass **`client`** as an existing `Kafka` instance from your app. The adapter reuses that client across checks.
+
+```ts
+import { Kafka } from "kafkajs";
+import { kafkajsAdapter } from "@healthzkit/kafka";
+
+const kafka = new Kafka({ brokers: [process.env.KAFKA_BROKERS!] });
+
+const adapter = kafkajsAdapter({
+  client: kafka,
+  metadata: () => ({ driver: "kafkajs" }),
+});
+```
+
+## `nodeRdKafkaAdapter` (`node-rdkafka`)
+
+**Peer:** `node-rdkafka` ≥ 3.
+
+Each check fetches broker metadata via `getMetadata()` when the client is already connected, or `connect({}, cb)` otherwise. That exercises the broker path without producing or consuming messages.
+
+### Config
+
+The adapter lazily imports `node-rdkafka`, constructs `new Producer(config)` once, and reuses it across checks.
+
+```ts
+import { nodeRdKafkaAdapter } from "@healthzkit/kafka";
+
+const adapter = nodeRdKafkaAdapter({
+  config: { "bootstrap.servers": process.env.KAFKA_BROKERS! },
+});
+```
+
+`config` is a `ProducerGlobalConfig` object (for example `bootstrap.servers`, `security.protocol`, `sasl.username`).
+
+### Existing client
+
+Pass **`client`** as an existing `Producer` or `KafkaConsumer` from your app. The adapter reuses that instance across checks.
+
+```ts
+import { Producer } from "node-rdkafka";
+import { nodeRdKafkaAdapter } from "@healthzkit/kafka";
+
+const producer = new Producer({
+  "bootstrap.servers": process.env.KAFKA_BROKERS!,
+});
+
+const adapter = nodeRdKafkaAdapter({
+  client: producer,
+  metadata: () => ({ driver: "node-rdkafka" }),
+});
+```
+
+## 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 hitting Kafka on every probe. See the **Scheduling** section in the `healthzkit` README.
+
+## Development
+
+From the monorepo root:
+
+```bash
+vp install
+vp test --filter @healthzkit/kafka
+vp pack --filter @healthzkit/kafka
+```
+
+See the repo root `AGENTS.md` for Vite+ / `vp` conventions.

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { KafkaJsAdapterOptions, kafkajsAdapter } from "./kafkajs.mjs";
+import { NodeRdKafkaAdapterOptions, nodeRdKafkaAdapter } from "./node-rdkafka.mjs";
+export { type KafkaJsAdapterOptions, type NodeRdKafkaAdapterOptions, kafkajsAdapter, nodeRdKafkaAdapter };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{kafkajsAdapter as e}from"./kafkajs.mjs";import{nodeRdKafkaAdapter as t}from"./node-rdkafka.mjs";export{e as kafkajsAdapter,t as nodeRdKafkaAdapter};

package/dist/kafkajs.d.mts

@@ -0,0 +1,16 @@
+import { n as HealthAdapter, t as BaseKafkaOptions } from "./shared-BQHQT909.mjs";
+import { Kafka } from "kafkajs";
+
+//#region src/kafkajs.d.ts
+interface KafkaJsAdapterOptionsWithClient extends BaseKafkaOptions<Kafka> {
+  client: Kafka;
+  config?: never;
+}
+interface KafkaJsAdapterOptionsWithConfig extends BaseKafkaOptions<Kafka> {
+  config: ConstructorParameters<typeof Kafka>[0];
+  client?: never;
+}
+type KafkaJsAdapterOptions = KafkaJsAdapterOptionsWithClient | KafkaJsAdapterOptionsWithConfig;
+declare function kafkajsAdapter(options: KafkaJsAdapterOptions): HealthAdapter;
+//#endregion
+export { KafkaJsAdapterOptions, KafkaJsAdapterOptionsWithClient, KafkaJsAdapterOptionsWithConfig, kafkajsAdapter };

package/dist/kafkajs.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"./shared-BiUsKU63.mjs";function n(n){let r=null;async function i(){if(`client`in n&&n.client)return n.client;if(!r){let{Kafka:e}=await import(`kafkajs`);r=new e(n.config)}return r}return{async check(){let r=null;try{let t=await i(),a=Date.now();r=t.admin(),await r.connect(),await r.describeCluster();let o=Date.now()-a,s=n.metadata?n.metadata(t):void 0;return e(o,s instanceof Promise?await s:s)}catch(e){return t(e)}finally{r&&await r.disconnect().catch(()=>{})}}}}export{n as kafkajsAdapter};

package/dist/node-rdkafka.d.mts

@@ -0,0 +1,17 @@
+import { n as HealthAdapter, t as BaseKafkaOptions } from "./shared-BQHQT909.mjs";
+import { KafkaConsumer, Producer, ProducerGlobalConfig } from "node-rdkafka";
+
+//#region src/node-rdkafka.d.ts
+type RdKafkaClient = Producer | KafkaConsumer;
+interface NodeRdKafkaOptionsWithClient extends BaseKafkaOptions<RdKafkaClient> {
+  client: RdKafkaClient;
+  config?: never;
+}
+interface NodeRdKafkaOptionsWithConfig extends BaseKafkaOptions<RdKafkaClient> {
+  config: ProducerGlobalConfig;
+  client?: never;
+}
+type NodeRdKafkaAdapterOptions = NodeRdKafkaOptionsWithClient | NodeRdKafkaOptionsWithConfig;
+declare function nodeRdKafkaAdapter(options: NodeRdKafkaAdapterOptions): HealthAdapter;
+//#endregion
+export { NodeRdKafkaAdapterOptions, NodeRdKafkaOptionsWithClient, NodeRdKafkaOptionsWithConfig, nodeRdKafkaAdapter };

package/dist/node-rdkafka.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"./shared-BiUsKU63.mjs";function n(e){return new Promise((t,n)=>{let r=e=>{e?n(e):t()};if(e.isConnected()){e.getMetadata({},r);return}e.connect({},t=>{if(t){n(t);return}e.getMetadata({},r)})})}function r(r){let i=null,a=null;async function o(){return`client`in r&&r.client?r.client:i||(a||=(async()=>{try{let{Producer:e}=await import(`node-rdkafka`);return i=new e(r.config),i}finally{a=null}})(),a)}return{async check(){try{let t=await o(),i=Date.now();await n(t);let a=Date.now()-i,s=r.metadata?r.metadata(t):void 0;return e(a,s instanceof Promise?await s:s)}catch(e){return t(e)}}}}export{r as nodeRdKafkaAdapter};

package/dist/shared-BQHQT909.d.mts

@@ -0,0 +1,12 @@
+import { HealthAdapter, MetadataFn } from "@healthzkit/shared";
+
+//#region src/shared.d.ts
+interface BaseKafkaOptions<TClient> {
+  /**
+   * Optional function to populate metadata in the check result.
+   * Receives the resolved client so you can additional operations.
+   */
+  metadata?: MetadataFn<TClient>;
+}
+//#endregion
+export { HealthAdapter as n, BaseKafkaOptions as t };

package/dist/shared-BiUsKU63.mjs

@@ -0,0 +1 @@
+import{buildErrorResult as e,buildResult as t}from"@healthzkit/shared";export{t as n,e as t};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@healthzkit/kafka",
+  "version": "0.0.0",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alasti-company/healthzkit.dev",
+    "directory": "packages/kafka"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./kafkajs": "./dist/kafkajs.mjs",
+    "./node-rdkafka": "./dist/node-rdkafka.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"
+  },
+  "dependencies": {
+    "@healthzkit/shared": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "bumpp": "^11.1.0",
+    "healthzkit": "workspace:*",
+    "kafkajs": "^2.2.4",
+    "node-rdkafka": "^3.6.1",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:"
+  },
+  "peerDependencies": {
+    "kafkajs": ">=2.0.0",
+    "node-rdkafka": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "kafkajs": {
+      "optional": true
+    },
+    "node-rdkafka": {
+      "optional": true
+    }
+  }
+}