@healthzkit/mongo 0.0.1

package/README.md

@@ -0,0 +1,148 @@
+# @healthzkit/mongo
+
+MongoDB **healthzkit** `HealthAdapter` helpers for the official **[`mongodb`](https://www.mongodb.com/docs/drivers/node/current/)** driver and **[`mongoose`](https://mongoosejs.com/)**. Successful checks run an admin **`ping`** and 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/mongo healthzkit
+# plus one of:
+npm install mongodb
+npm install mongoose
+```
+
+`mongodb` and `mongoose` are optional peers—install the driver you use.
+
+## Package entrypoints
+
+| Import                       | Exports                                        |
+| ---------------------------- | ---------------------------------------------- |
+| `@healthzkit/mongo`          | `mongodbAdapter`, `mongooseAdapter`, and types |
+| `@healthzkit/mongo/mongodb`  | `mongodbAdapter` only                          |
+| `@healthzkit/mongo/mongoose` | `mongooseAdapter` only                         |
+
+Use subpath imports when you want to avoid pulling both drivers into your bundle analysis path.
+
+## Shared options
+
+Both factories accept `BaseMongoOptions`:
+
+| Option     | Description                                                                                       |
+| ---------- | ------------------------------------------------------------------------------------------------- |
+| `metadata` | Optional async `(client) => Record<string, unknown>` merged into check metadata with `latencyMs`. |
+
+Pass either `connectionString` or an existing client/connection (not both).
+
+## `mongodbAdapter` (`mongodb`)
+
+**Peer:** `mongodb` ≥ 6 or ≥ 7.
+
+Each check runs `client.db("admin").command({ ping: 1 })` and records round-trip latency.
+
+### Connection string
+
+The adapter lazily imports `mongodb`, creates a shared `MongoClient`, and connects once. Concurrent checks reuse the same client. Call **`close()`** on the adapter when you created it via `connectionString` to shut down the internal client (no-op for injected clients).
+
+```ts
+import { createHealthKit } from "healthzkit";
+import { mongodbAdapter } from "@healthzkit/mongo";
+
+const adapter = mongodbAdapter({
+  connectionString: process.env.MONGODB_URI!,
+  mongoOptions: { serverSelectionTimeoutMS: 2000 },
+});
+
+const kit = createHealthKit({
+  checks: [
+    {
+      name: "mongodb",
+      type: ["readiness"],
+      adapter,
+    },
+  ],
+});
+
+// optional: on process shutdown when using connectionString
+await adapter.close();
+```
+
+### Existing client
+
+Pass **`client`** as an existing `MongoClient`. The adapter calls **`connect()`** once and reuses that client across checks. **`close()`** does not close an injected client.
+
+```ts
+import { MongoClient } from "mongodb";
+import { mongodbAdapter } from "@healthzkit/mongo/mongodb";
+
+const client = new MongoClient(process.env.MONGODB_URI!);
+
+const adapter = mongodbAdapter({
+  client,
+  metadata: async (c) => {
+    const hello = await c.db("admin").command({ hello: 1 });
+    return { setName: hello.setName };
+  },
+});
+```
+
+## `mongooseAdapter` (`mongoose`)
+
+**Peer:** `mongoose` ≥ 8 or ≥ 9.
+
+Each check runs `db.admin().command({ ping: 1 })` on the resolved connection. Works with a **`Mongoose`** instance (`conn.connection.db`) or a mongoose **`Connection`** (`conn.db`).
+
+### Connection string
+
+The adapter dynamically imports `mongoose`, calls **`mongoose.connect(connectionString, mongooseOptions)`** once, and reuses that instance.
+
+```ts
+import { mongooseAdapter } from "@healthzkit/mongo/mongoose";
+
+const adapter = mongooseAdapter({
+  connectionString: process.env.MONGODB_URI!,
+  mongooseOptions: { serverSelectionTimeoutMS: 2000 },
+});
+```
+
+### Existing connection
+
+Pass **`connection`** as your app's `mongoose` instance or a `Connection`. If **`readyState`** is not `1` (connected), the adapter awaits **`connection.asPromise()`** before pinging.
+
+```ts
+import mongoose from "mongoose";
+import { mongooseAdapter } from "@healthzkit/mongo";
+
+await mongoose.connect(process.env.MONGODB_URI!);
+
+const adapter = mongooseAdapter({
+  connection: mongoose,
+  metadata: async () => ({ driver: "mongoose" }),
+});
+```
+
+## Check result
+
+On success:
+
+```json
+{
+  "status": "ok",
+  "metadata": { "latencyMs": 8 }
+}
+```
+
+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 busy clusters, pair these adapters with a **`schedule`** on the check so readiness reads cached results instead of pinging MongoDB on every probe. See the **Scheduling** section in the `healthzkit` README.
+
+## Development
+
+From the monorepo root:
+
+```bash
+vp install
+vp test --filter @healthzkit/mongo
+vp pack --filter @healthzkit/mongo
+```

package/dist/index.d.mts

@@ -0,0 +1,3 @@
+import { MongoDbAdapterOptions, mongodbAdapter } from "./mongodb.mjs";
+import { MongooseAdapterOptions, mongooseAdapter } from "./mongoose.mjs";
+export { type MongoDbAdapterOptions, type MongooseAdapterOptions, mongodbAdapter, mongooseAdapter };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{mongodbAdapter as e}from"./mongodb.mjs";import{mongooseAdapter as t}from"./mongoose.mjs";export{e as mongodbAdapter,t as mongooseAdapter};

package/dist/mongodb.d.mts

@@ -0,0 +1,21 @@
+import { n as HealthAdapter, t as BaseMongoOptions } from "./shared-C_B8UrQ_.mjs";
+import { MongoClient, MongoClientOptions } from "mongodb";
+
+//#region src/mongodb.d.ts
+interface MongoDbAdapterOptionsWithClient extends BaseMongoOptions<MongoClient> {
+  client: MongoClient;
+  connectionString?: never;
+  mongoOptions?: never;
+}
+interface MongoDbAdapterOptionsWithConnectionString extends BaseMongoOptions<MongoClient> {
+  connectionString: string;
+  mongoOptions?: MongoClientOptions;
+  client?: never;
+}
+type MongoDbAdapterOptions = MongoDbAdapterOptionsWithClient | MongoDbAdapterOptionsWithConnectionString;
+type MongoDbAdapter = HealthAdapter & {
+  close(): Promise<void>;
+};
+declare function mongodbAdapter(options: MongoDbAdapterOptions): MongoDbAdapter;
+//#endregion
+export { MongoDbAdapter, MongoDbAdapterOptions, MongoDbAdapterOptionsWithClient, MongoDbAdapterOptionsWithConnectionString, mongodbAdapter };

package/dist/mongodb.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"./shared-B-1hAtzF.mjs";function n(n){let r=null,i=null,a=null;async function o(e,t){return i??=(async()=>{let{MongoClient:n}=await import(`mongodb`),i=new n(e,t);return await i.connect(),r=i,i})().catch(e=>{throw i=null,r=null,e}),i}async function s(){if(`connectionString`in n&&n.connectionString)return o(n.connectionString,n.mongoOptions);if(`client`in n&&n.client)return a??=n.client.connect().then(()=>void 0).catch(e=>{throw a=null,e}),await a,n.client;throw Error(`mongoAdapter: provide a non-empty connectionString or a client`)}return{async check(){try{let t=await s(),r=Date.now();return await t.db(`admin`).command({ping:1}),e(Date.now()-r,n.metadata?await n.metadata(t):void 0)}catch(e){return t(e)}},async close(){r&&(await r.close(),r=null,i=null)}}}export{n as mongodbAdapter};

package/dist/mongoose.d.mts

@@ -0,0 +1,19 @@
+import { n as HealthAdapter, t as BaseMongoOptions } from "./shared-C_B8UrQ_.mjs";
+import { ConnectOptions, Connection, Mongoose } from "mongoose";
+
+//#region src/mongoose.d.ts
+type MongooseConnection = Connection | Mongoose;
+interface MongooseAdapterOptionsWithConnection extends BaseMongoOptions<MongooseConnection> {
+  connection: MongooseConnection;
+  connectionString?: never;
+  mongooseOptions?: never;
+}
+interface MongooseAdapterOptionsWithConnectionString extends BaseMongoOptions<MongooseConnection> {
+  connectionString: string;
+  mongooseOptions?: ConnectOptions;
+  connection?: never;
+}
+type MongooseAdapterOptions = MongooseAdapterOptionsWithConnection | MongooseAdapterOptionsWithConnectionString;
+declare function mongooseAdapter(options: MongooseAdapterOptions): HealthAdapter;
+//#endregion
+export { MongooseAdapterOptions, MongooseAdapterOptionsWithConnection, MongooseAdapterOptionsWithConnectionString, mongooseAdapter };

package/dist/mongoose.mjs

@@ -0,0 +1 @@
+import{n as e,t}from"./shared-B-1hAtzF.mjs";function n(n){let r=null;async function i(e,t){return r??=(async()=>{let{default:n}=await import(`mongoose`);return await n.connect(e,t),n})().catch(e=>{throw r=null,e}),r}async function a(){if(`connectionString`in n&&n.connectionString)return i(n.connectionString,n.mongooseOptions);let e=n.connection;if(!e)throw Error(`mongoose adapter requires connection or connectionString`);return`readyState`in e&&e.readyState!==1&&await e.asPromise(),e}return{async check(){try{let t=await a(),r=Date.now(),i=`db`in t?t.db:t.connection.db;if(!i)throw Error(`mongoose adapter: database unavailable`);return await i.admin().command({ping:1}),e(Date.now()-r,n.metadata?await n.metadata(t):void 0)}catch(e){return t(e)}}}}export{n as mongooseAdapter};

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-C_B8UrQ_.d.mts

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

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@healthzkit/mongo",
+  "version": "0.0.1",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alasti-company/healthzkit.dev",
+    "directory": "packages/mongo"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./mongodb": "./dist/mongodb.mjs",
+    "./mongoose": "./dist/mongoose.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/mongodb": "^4.0.7",
+    "@types/mongoose": "^5.11.97",
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "bumpp": "^11.1.0",
+    "healthzkit": "workspace:*",
+    "mongodb": "^7.2.0",
+    "mongoose": "^9.6.2",
+    "typescript": "^6.0.3",
+    "vite-plus": "^0.1.20"
+  },
+  "peerDependencies": {
+    "mongodb": ">=6.0.0 || >=7.0.0",
+    "mongoose": ">= 8.0.0 || >=9.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mongodb": {
+      "optional": true
+    },
+    "mongoose": {
+      "optional": true
+    }
+  }
+}