@openstatus/health-bullmq 0.1.4-dev.0

package/README.md

@@ -0,0 +1,73 @@
+# @openstatus/health-bullmq
+
+[BullMQ](https://bullmq.io/) probe for
+[`@openstatus/health`](https://jsr.io/@openstatus/health). Counts the
+waiting jobs of a `Queue` — one `LLEN` against Redis — and fails the check
+when Redis does not answer or, with `maxWaiting`, when the backlog grows
+past a threshold.
+
+```sh
+deno add jsr:@openstatus/health jsr:@openstatus/health-bullmq
+npm install @openstatus/health @openstatus/health-bullmq
+```
+
+```ts
+import { Queue } from "bullmq";
+import { createHealthHandler } from "@openstatus/health";
+import { bullmqProbe } from "@openstatus/health-bullmq";
+
+const emails = new Queue("emails", { connection: { url: env.REDIS_URL } });
+
+Deno.serve(
+  createHealthHandler({
+    probes: [bullmqProbe({ queue: emails, maxWaiting: 10_000 })],
+  }),
+);
+```
+
+Reuse the `Queue` your application already holds: BullMQ keeps a Redis
+connection per `Queue`, so constructing one for the health endpoint would
+add a connection of its own. Without `maxWaiting` the probe only proves the
+queue's Redis is reachable; with it the check also turns `failed` when
+producers outrun workers, which is usually the earlier warning.
+
+```ts
+bullmqProbe({
+  queue: emails,
+  maxWaiting: 10_000,
+  // optional overrides from the Probe contract
+  name: "emails",
+  critical: true,
+  timeoutMs: 1000,
+  skip: () => env.REDIS_URL == null,
+});
+```
+
+Non-critical by default: a queue usually carries background work, so an
+outage or backlog degrades the report instead of taking the service out of
+rotation. Set `critical: true` when requests cannot complete without
+enqueuing.
+
+The queue is typed structurally as `{ getWaitingCount(): PromiseLike<number> }`,
+so `bullmq` is an optional peer dependency for its types only and the probe
+adds no runtime import of it. The factory throws `ProbeConfigError` at
+construction when the queue has no `getWaitingCount()` or `maxWaiting` is
+not a finite number of zero or more.
+
+## About openstatus
+
+[openstatus](https://www.openstatus.dev/) is the open-source uptime monitoring
+and status page platform. This package is part of
+[`@openstatus/health`](https://github.com/openstatusHQ/health), the `/health`
+endpoints behind openstatus's own services, extracted so any JavaScript server
+can expose one. Point an
+[openstatus monitor](https://www.openstatus.dev/docs/reference/http-monitor)
+at the endpoint and assert on `status` in the body to be alerted on
+`degraded` before it becomes `unhealthy`.
+
+Source: [github.com/openstatusHQ/health](https://github.com/openstatusHQ/health).
+Issues and PRs welcome.
+
+## License
+
+[MIT](https://github.com/openstatusHQ/health/blob/main/LICENSE)

package/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/mod.cjs

@@ -0,0 +1,47 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const __openstatus_health = require_rolldown_runtime.__toESM(require("@openstatus/health"));
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const bullmqDefaultName = "queue";
+/** Thrown by the probe when the waiting count exceeds `maxWaiting`. */
+var BullmqBacklogError = class extends Error {
+	/** The number of waiting jobs. */
+	waiting;
+	/** Build the error for `waiting` jobs against the `max` threshold. */
+	constructor(waiting, max) {
+		super(`${waiting} jobs waiting exceeds ${max}`);
+		this.name = "BullmqBacklogError";
+		this.waiting = waiting;
+	}
+};
+/** A probe that counts waiting jobs and fails above `maxWaiting`; non-critical by default. Throws `ProbeConfigError` without `getWaitingCount()` or when `maxWaiting` is not a finite number of zero or more. */
+function bullmqProbe(options) {
+	const queue = options.queue;
+	if (typeof queue?.getWaitingCount !== "function") throw new __openstatus_health.ProbeConfigError("bullmqProbe", "queue", `must expose getWaitingCount(), got ${describe(queue)}`);
+	const maxWaiting = options.maxWaiting;
+	if (maxWaiting != null && (typeof maxWaiting !== "number" || !Number.isFinite(maxWaiting) || maxWaiting < 0)) throw new __openstatus_health.ProbeConfigError("bullmqProbe", "maxWaiting", `must be a non-negative number, got ${String(maxWaiting)}`);
+	return {
+		name: options.name ?? bullmqDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async () => {
+			const waiting = await queue.getWaitingCount();
+			if (typeof waiting !== "number" || !Number.isFinite(waiting)) throw new Error("unexpected waiting count");
+			if (maxWaiting != null && waiting > maxWaiting) throw new BullmqBacklogError(waiting, maxWaiting);
+			return { waiting };
+		}
+	};
+}
+function describe(queue) {
+	if (queue == null) return String(queue);
+	if (typeof queue !== "object") return typeof queue;
+	const keys = Object.keys(queue);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+exports.BullmqBacklogError = BullmqBacklogError;
+exports.bullmqDefaultName = bullmqDefaultName;
+exports.bullmqProbe = bullmqProbe;

package/dist/mod.d.cts

@@ -0,0 +1,31 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const bullmqDefaultName = "queue";
+/** The subset of a BullMQ `Queue` the probe uses. */
+interface BullmqLikeQueue {
+  /** Count the jobs in the `waiting` state. */
+  getWaitingCount(): PromiseLike<number>;
+}
+/** Options for `bullmqProbe()`. */
+interface BullmqProbeOptions extends ProbeOverrides {
+  /** A BullMQ `Queue`. */
+  readonly queue: BullmqLikeQueue;
+  /** Fail when more jobs than this are waiting. Unlimited by default. */
+  readonly maxWaiting?: number;
+}
+/** Thrown by the probe when the waiting count exceeds `maxWaiting`. */
+declare class BullmqBacklogError extends Error {
+  /** The number of waiting jobs. */
+  readonly waiting: number;
+  /** Build the error for `waiting` jobs against the `max` threshold. */
+  constructor(waiting: number, max: number);
+}
+/** A probe that counts waiting jobs and fails above `maxWaiting`; non-critical by default. Throws `ProbeConfigError` without `getWaitingCount()` or when `maxWaiting` is not a finite number of zero or more. */
+declare function bullmqProbe(options: BullmqProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { BullmqBacklogError, BullmqLikeQueue, BullmqProbeOptions, bullmqDefaultName, bullmqProbe };
+//# sourceMappingURL=mod.d.cts.map

package/dist/mod.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.cts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;AAoD+D;cA9BlD,iBAAA;;UAGI,eAAA;;qBAEI;;;UAIJ,kBAAA,SAA2B;;kBAE1B;;;;;cAML,kBAAA,SAA2B,KAAK;;;;;;;iBAa7B,WAAA,UAAqB,qBAAqB"}

package/dist/mod.d.ts

@@ -0,0 +1,31 @@
+import { Probe, ProbeOverrides } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const bullmqDefaultName = "queue";
+/** The subset of a BullMQ `Queue` the probe uses. */
+interface BullmqLikeQueue {
+  /** Count the jobs in the `waiting` state. */
+  getWaitingCount(): PromiseLike<number>;
+}
+/** Options for `bullmqProbe()`. */
+interface BullmqProbeOptions extends ProbeOverrides {
+  /** A BullMQ `Queue`. */
+  readonly queue: BullmqLikeQueue;
+  /** Fail when more jobs than this are waiting. Unlimited by default. */
+  readonly maxWaiting?: number;
+}
+/** Thrown by the probe when the waiting count exceeds `maxWaiting`. */
+declare class BullmqBacklogError extends Error {
+  /** The number of waiting jobs. */
+  readonly waiting: number;
+  /** Build the error for `waiting` jobs against the `max` threshold. */
+  constructor(waiting: number, max: number);
+}
+/** A probe that counts waiting jobs and fails above `maxWaiting`; non-critical by default. Throws `ProbeConfigError` without `getWaitingCount()` or when `maxWaiting` is not a finite number of zero or more. */
+declare function bullmqProbe(options: BullmqProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { BullmqBacklogError, BullmqLikeQueue, BullmqProbeOptions, bullmqDefaultName, bullmqProbe };
+//# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;AAoD+D;cA9BlD,iBAAA;;UAGI,eAAA;;qBAEI;;;UAIJ,kBAAA,SAA2B;;kBAE1B;;;;;cAML,kBAAA,SAA2B,KAAK;;;;;;;iBAa7B,WAAA,UAAqB,qBAAqB"}

package/dist/mod.js

@@ -0,0 +1,45 @@
+import { ProbeConfigError } from "@openstatus/health";
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const bullmqDefaultName = "queue";
+/** Thrown by the probe when the waiting count exceeds `maxWaiting`. */
+var BullmqBacklogError = class extends Error {
+	/** The number of waiting jobs. */
+	waiting;
+	/** Build the error for `waiting` jobs against the `max` threshold. */
+	constructor(waiting, max) {
+		super(`${waiting} jobs waiting exceeds ${max}`);
+		this.name = "BullmqBacklogError";
+		this.waiting = waiting;
+	}
+};
+/** A probe that counts waiting jobs and fails above `maxWaiting`; non-critical by default. Throws `ProbeConfigError` without `getWaitingCount()` or when `maxWaiting` is not a finite number of zero or more. */
+function bullmqProbe(options) {
+	const queue = options.queue;
+	if (typeof queue?.getWaitingCount !== "function") throw new ProbeConfigError("bullmqProbe", "queue", `must expose getWaitingCount(), got ${describe(queue)}`);
+	const maxWaiting = options.maxWaiting;
+	if (maxWaiting != null && (typeof maxWaiting !== "number" || !Number.isFinite(maxWaiting) || maxWaiting < 0)) throw new ProbeConfigError("bullmqProbe", "maxWaiting", `must be a non-negative number, got ${String(maxWaiting)}`);
+	return {
+		name: options.name ?? bullmqDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async () => {
+			const waiting = await queue.getWaitingCount();
+			if (typeof waiting !== "number" || !Number.isFinite(waiting)) throw new Error("unexpected waiting count");
+			if (maxWaiting != null && waiting > maxWaiting) throw new BullmqBacklogError(waiting, maxWaiting);
+			return { waiting };
+		}
+	};
+}
+function describe(queue) {
+	if (queue == null) return String(queue);
+	if (typeof queue !== "object") return typeof queue;
+	const keys = Object.keys(queue);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+export { BullmqBacklogError, bullmqDefaultName, bullmqProbe };
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["waiting: number","max: number","options: BullmqProbeOptions","queue: BullmqLikeQueue"],"sources":["../src/mod.ts"],"sourcesContent":["/**\n * BullMQ probe for `@openstatus/health`: counts the waiting jobs of a\n * `Queue`, which round-trips to Redis, and optionally fails above a backlog\n * threshold.\n *\n * ```ts\n * import { Queue } from \"bullmq\";\n * import { bullmqProbe } from \"@openstatus/health-bullmq\";\n *\n * const probe = bullmqProbe({ queue: new Queue(\"emails\"), maxWaiting: 10_000 });\n * ```\n *\n * @module\n */\n\nimport {\n  type Probe,\n  ProbeConfigError,\n  type ProbeOverrides,\n} from \"@openstatus/health\";\n\n/** Probe name when `name` is unset. */\nexport const bullmqDefaultName = \"queue\";\n\n/** The subset of a BullMQ `Queue` the probe uses. */\nexport interface BullmqLikeQueue {\n  /** Count the jobs in the `waiting` state. */\n  getWaitingCount(): PromiseLike<number>;\n}\n\n/** Options for `bullmqProbe()`. */\nexport interface BullmqProbeOptions extends ProbeOverrides {\n  /** A BullMQ `Queue`. */\n  readonly queue: BullmqLikeQueue;\n  /** Fail when more jobs than this are waiting. Unlimited by default. */\n  readonly maxWaiting?: number;\n}\n\n/** Thrown by the probe when the waiting count exceeds `maxWaiting`. */\nexport class BullmqBacklogError extends Error {\n  /** The number of waiting jobs. */\n  readonly waiting: number;\n\n  /** Build the error for `waiting` jobs against the `max` threshold. */\n  constructor(waiting: number, max: number) {\n    super(`${waiting} jobs waiting exceeds ${max}`);\n    this.name = \"BullmqBacklogError\";\n    this.waiting = waiting;\n  }\n}\n\n/** A probe that counts waiting jobs and fails above `maxWaiting`; non-critical by default. Throws `ProbeConfigError` without `getWaitingCount()` or when `maxWaiting` is not a finite number of zero or more. */\nexport function bullmqProbe(options: BullmqProbeOptions): Probe {\n  const queue = options.queue;\n  if (typeof queue?.getWaitingCount !== \"function\") {\n    throw new ProbeConfigError(\n      \"bullmqProbe\",\n      \"queue\",\n      `must expose getWaitingCount(), got ${describe(queue)}`,\n    );\n  }\n  const maxWaiting = options.maxWaiting;\n  if (\n    maxWaiting != null &&\n    (typeof maxWaiting !== \"number\" || !Number.isFinite(maxWaiting) ||\n      maxWaiting < 0)\n  ) {\n    throw new ProbeConfigError(\n      \"bullmqProbe\",\n      \"maxWaiting\",\n      `must be a non-negative number, got ${String(maxWaiting)}`,\n    );\n  }\n  return {\n    name: options.name ?? bullmqDefaultName,\n    critical: options.critical ?? false,\n    timeoutMs: options.timeoutMs,\n    skip: options.skip,\n    run: async () => {\n      const waiting = await queue.getWaitingCount();\n      if (typeof waiting !== \"number\" || !Number.isFinite(waiting)) {\n        throw new Error(\"unexpected waiting count\");\n      }\n      if (maxWaiting != null && waiting > maxWaiting) {\n        throw new BullmqBacklogError(waiting, maxWaiting);\n      }\n      return { waiting };\n    },\n  };\n}\n\nfunction describe(queue: BullmqLikeQueue): string {\n  if (queue == null) return String(queue);\n  if (typeof queue !== \"object\") return typeof queue;\n  const keys = Object.keys(queue);\n  return keys.length === 0\n    ? \"an object with no keys\"\n    : `an object with keys ${keys.slice(0, 8).join(\", \")}`;\n}\n"],"mappings":";;;;AAsBA,MAAa,oBAAoB;;AAiBjC,IAAa,qBAAb,cAAwC,MAAM;;CAE5C,AAAS;;CAGT,YAAYA,SAAiBC,KAAa;AACxC,SAAO,EAAE,QAAQ,wBAAwB,IAAI,EAAE;AAC/C,OAAK,OAAO;AACZ,OAAK,UAAU;CAChB;AACF;;AAGD,SAAgB,YAAYC,SAAoC;CAC9D,MAAM,QAAQ,QAAQ;AACtB,YAAW,OAAO,oBAAoB,WACpC,OAAM,IAAI,iBACR,eACA,UACC,qCAAqC,SAAS,MAAM,CAAC;CAG1D,MAAM,aAAa,QAAQ;AAC3B,KACE,cAAc,gBACN,eAAe,aAAa,OAAO,SAAS,WAAW,IAC7D,aAAa,GAEf,OAAM,IAAI,iBACR,eACA,eACC,qCAAqC,OAAO,WAAW,CAAC;AAG7D,QAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,UAAU,QAAQ,YAAY;EAC9B,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd,KAAK,YAAY;GACf,MAAM,UAAU,MAAM,MAAM,iBAAiB;AAC7C,cAAW,YAAY,aAAa,OAAO,SAAS,QAAQ,CAC1D,OAAM,IAAI,MAAM;AAElB,OAAI,cAAc,QAAQ,UAAU,WAClC,OAAM,IAAI,mBAAmB,SAAS;AAExC,UAAO,EAAE,QAAS;EACnB;CACF;AACF;AAED,SAAS,SAASC,OAAgC;AAChD,KAAI,SAAS,KAAM,QAAO,OAAO,MAAM;AACvC,YAAW,UAAU,SAAU,eAAc;CAC7C,MAAM,OAAO,OAAO,KAAK,MAAM;AAC/B,QAAO,KAAK,WAAW,IACnB,4BACC,sBAAsB,KAAK,MAAM,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC;AACxD"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@openstatus/health-bullmq",
+  "version": "0.1.4-dev.0",
+  "description": "BullMQ queue probe for @openstatus/health",
+  "keywords": [
+    "openstatus",
+    "health",
+    "healthcheck",
+    "bullmq",
+    "bull",
+    "queue",
+    "redis",
+    "background-jobs"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "openstatus",
+    "url": "https://www.openstatus.dev/"
+  },
+  "homepage": "https://github.com/openstatusHQ/health",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openstatusHQ/health.git",
+    "directory": "packages/bullmq/"
+  },
+  "bugs": {
+    "url": "https://github.com/openstatusHQ/health/issues"
+  },
+  "type": "module",
+  "module": "./dist/mod.js",
+  "main": "./dist/mod.cjs",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/mod.d.ts",
+        "require": "./dist/mod.d.cts"
+      },
+      "import": "./dist/mod.js",
+      "require": "./dist/mod.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@openstatus/health": "^0.1.4-dev.0",
+    "bullmq": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "bullmq": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.7",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "test": "node --experimental-transform-types --test"
+  }
+}