Skip to main content
The @healthzkit/mongo package provides HealthAdapter helpers for the official mongodb driver and mongoose. 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 the adapter package and one client library:
mongodb and mongoose are optional peers — install the driver you use.

Package entrypoints

  • @healthzkit/mongo - mongodbAdapter, mongooseAdapter, and their option 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 share BaseMongoOptions:

mongodbAdapter (mongodb)

Peer: mongodb >= 6 or >= 7. Each check runs client.db("admin").command({ ping: 1 }) and records round-trip latency.

Connection string

Pass connectionString (and optional mongoOptions). The adapter lazily imports mongodb, creates a shared MongoClient, and connects once. Concurrent checks reuse the same client. Call adapter.close() when the adapter owns the client (created from connectionString) to shut down the internal connection. close() is a no-op when you pass an existing client.

Existing client

Pass client as an existing MongoClient. The adapter calls connect() once and reuses that client across checks.

mongooseAdapter (mongoose)

Peer: mongoose >= 8 or >= 9. Each check runs db.admin().command({ ping: 1 }) on the resolved connection. The adapter supports a Mongoose instance (conn.db) or a mongoose Connection (conn.connection.db).

Connection string

Pass connectionString (and optional mongooseOptions). The adapter dynamically imports mongoose, creates a private mongoose.createConnection(), and reuses that connection after it connects. Failed initial connections are closed and retried with a fresh connection on the next check.

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.

Wiring into createHealthKit

Treat each factory’s return value as adapter on a check (same as a hand-written { check() { ... } } object):
Combine with schedule on the check if you want cached readiness results instead of pinging MongoDB on every probe (see Scheduling).

Resource ownership

Connection-string adapters own their MongoDB client or private Mongoose Connection. Mongoose metadata receives that private connection; the adapter does not connect or disconnect the global Mongoose instance. Supplied client or connection objects remain caller-owned. Use await kit.close() for terminal disposal after pending checks finish. Direct adapter users can call await adapter.dispose?.(). The MongoDB adapter’s existing close() method remains available as a reusable reset that allows later reconnection; use dispose() for terminal shutdown. See Scheduling for full shutdown behavior.