@openstatus/health-cloudflare-kv 0.1.4-dev.0

package/README.md

@@ -0,0 +1,80 @@
+# @openstatus/health-cloudflare-kv
+
+[Cloudflare Workers KV](https://developers.cloudflare.com/kv/) probe for
+[`@openstatus/health`](https://jsr.io/@openstatus/health). Reads one key
+through a `KVNamespace` binding and fails the check when the read does — a
+missing key is a healthy answer, only an error is not.
+
+```sh
+deno add jsr:@openstatus/health jsr:@openstatus/health-cloudflare-kv
+npm install @openstatus/health @openstatus/health-cloudflare-kv
+```
+
+```ts
+import { createLazyHealthHandler } from "@openstatus/health";
+import { kvProbe } from "@openstatus/health-cloudflare-kv";
+
+interface Env {
+  CACHE: KVNamespace;
+}
+
+export default {
+  fetch: createLazyHealthHandler<Request, Env>((env) => ({
+    path: "/health",
+    probes: [kvProbe({ namespace: env.CACHE })],
+  })),
+};
+```
+
+Bindings only exist inside `fetch(request, env)` in Workers, but the handler
+must be built once or every request gets a fresh cache and the probe runs on
+every poll. `createLazyHealthHandler` runs your callback on the first request
+and reuses the handler it builds; with Hono, build the probe once inside a
+route handler that receives `c.env` and memoise it the same way. The probe
+calls `namespace.get("health")`; pass `key` to read a key your Worker
+actually depends on. KV reads are served from the edge cache, so a
+successful probe proves the binding and the nearest cache answer, not that
+a write would reach the origin.
+
+```ts
+kvProbe({
+  namespace: env.CACHE,
+  key: "config:v1",
+  // optional overrides from the Probe contract
+  name: "sessions",
+  critical: true,
+  timeoutMs: 1000,
+  skip: () => env.HEALTH_SKIP_KV === "true",
+});
+```
+
+The factory validates `namespace` when it is called, before `skip` is ever
+consulted, so `skip` cannot stand in for a missing binding; leave the probe
+out of `probes` instead when the Worker may run without KV.
+
+Non-critical by default: KV is usually a cache or configuration store whose
+outage degrades the report instead of taking the Worker out of rotation.
+Set `critical: true` when requests cannot proceed without it.
+
+The binding is typed structurally as `{ get(key) }`, so the package has no
+dependency on `@cloudflare/workers-types` and works with the types
+`wrangler types` generates. The factory throws `ProbeConfigError` at
+construction when the binding has no `get()` or `key` is empty.
+
+## 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,35 @@
+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 kvDefaultName = "kv";
+/** Key read when `key` is unset. */
+const kvDefaultKey = "health";
+/** A probe that reads `key`; non-critical by default. Throws `ProbeConfigError` without `get()` or with an empty `key`. */
+function kvProbe(options) {
+	const namespace = options.namespace;
+	if (typeof namespace?.get !== "function") throw new __openstatus_health.ProbeConfigError("kvProbe", "namespace", `must expose get(), got ${describe(namespace)}`);
+	const key = options.key === void 0 ? kvDefaultKey : options.key;
+	if (typeof key !== "string" || key.length === 0) throw new __openstatus_health.ProbeConfigError("kvProbe", "key", typeof key !== "string" ? `must be a string, got ${String(key)}` : "must not be empty");
+	return {
+		name: options.name ?? kvDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async () => {
+			await namespace.get(key);
+		}
+	};
+}
+function describe(namespace) {
+	if (namespace == null) return String(namespace);
+	if (typeof namespace !== "object") return typeof namespace;
+	const keys = Object.keys(namespace);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+exports.kvDefaultKey = kvDefaultKey;
+exports.kvDefaultName = kvDefaultName;
+exports.kvProbe = kvProbe;

package/dist/mod.d.cts

@@ -0,0 +1,26 @@
+import { Probe, ProbeOverrides, ProbeResult } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const kvDefaultName = "kv";
+/** Key read when `key` is unset. */
+declare const kvDefaultKey = "health";
+/** The subset of a `KVNamespace` binding the probe uses. */
+interface KVLikeNamespace {
+  /** Read one key; resolves with `null` when it does not exist. */
+  get(key: string): PromiseLike<ProbeResult>;
+}
+/** Options for `kvProbe()`. */
+interface KVProbeOptions extends ProbeOverrides {
+  /** The `KVNamespace` binding from `env`. */
+  readonly namespace: KVLikeNamespace;
+  /** Key to read. Default `kvDefaultKey`; it does not need to exist. */
+  readonly key?: string;
+}
+/** A probe that reads `key`; non-critical by default. Throws `ProbeConfigError` without `get()` or with an empty `key`. */
+declare function kvProbe(options: KVProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { KVLikeNamespace, KVProbeOptions, kvDefaultKey, kvDefaultName, kvProbe };
+//# 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":";;;;;AA6CuD,cAnB1C,aAAA,GAmB0C,IAAA;;cAjB1C,YAAA;;UAGI,eAAA;;oBAEG,YAAY;;;UAIf,cAAA,SAAuB;;sBAElB;;;;;iBAMN,OAAA,UAAiB,iBAAiB"}

package/dist/mod.d.ts

@@ -0,0 +1,26 @@
+import { Probe, ProbeOverrides, ProbeResult } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const kvDefaultName = "kv";
+/** Key read when `key` is unset. */
+declare const kvDefaultKey = "health";
+/** The subset of a `KVNamespace` binding the probe uses. */
+interface KVLikeNamespace {
+  /** Read one key; resolves with `null` when it does not exist. */
+  get(key: string): PromiseLike<ProbeResult>;
+}
+/** Options for `kvProbe()`. */
+interface KVProbeOptions extends ProbeOverrides {
+  /** The `KVNamespace` binding from `env`. */
+  readonly namespace: KVLikeNamespace;
+  /** Key to read. Default `kvDefaultKey`; it does not need to exist. */
+  readonly key?: string;
+}
+/** A probe that reads `key`; non-critical by default. Throws `ProbeConfigError` without `get()` or with an empty `key`. */
+declare function kvProbe(options: KVProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { KVLikeNamespace, KVProbeOptions, kvDefaultKey, kvDefaultName, kvProbe };
+//# 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":";;;;;AA6CuD,cAnB1C,aAAA,GAmB0C,IAAA;;cAjB1C,YAAA;;UAGI,eAAA;;oBAEG,YAAY;;;UAIf,cAAA,SAAuB;;sBAElB;;;;;iBAMN,OAAA,UAAiB,iBAAiB"}

package/dist/mod.js

@@ -0,0 +1,33 @@
+import { ProbeConfigError } from "@openstatus/health";
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const kvDefaultName = "kv";
+/** Key read when `key` is unset. */
+const kvDefaultKey = "health";
+/** A probe that reads `key`; non-critical by default. Throws `ProbeConfigError` without `get()` or with an empty `key`. */
+function kvProbe(options) {
+	const namespace = options.namespace;
+	if (typeof namespace?.get !== "function") throw new ProbeConfigError("kvProbe", "namespace", `must expose get(), got ${describe(namespace)}`);
+	const key = options.key === void 0 ? kvDefaultKey : options.key;
+	if (typeof key !== "string" || key.length === 0) throw new ProbeConfigError("kvProbe", "key", typeof key !== "string" ? `must be a string, got ${String(key)}` : "must not be empty");
+	return {
+		name: options.name ?? kvDefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async () => {
+			await namespace.get(key);
+		}
+	};
+}
+function describe(namespace) {
+	if (namespace == null) return String(namespace);
+	if (typeof namespace !== "object") return typeof namespace;
+	const keys = Object.keys(namespace);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+export { kvDefaultKey, kvDefaultName, kvProbe };
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["options: KVProbeOptions","namespace: KVLikeNamespace"],"sources":["../src/mod.ts"],"sourcesContent":["/**\n * Cloudflare Workers KV probe for `@openstatus/health`: reads one key\n * through a `KVNamespace` binding.\n *\n * ```ts\n * import { createLazyHealthHandler } from \"@openstatus/health\";\n * import { kvProbe } from \"@openstatus/health-cloudflare-kv\";\n *\n * export default {\n *   fetch: createLazyHealthHandler<Request, Env>((env) => ({\n *     probes: [kvProbe({ namespace: env.CACHE })],\n *   })),\n * };\n * ```\n *\n * @module\n */\n\nimport {\n  type Probe,\n  ProbeConfigError,\n  type ProbeOverrides,\n  type ProbeResult,\n} from \"@openstatus/health\";\n\n/** Probe name when `name` is unset. */\nexport const kvDefaultName = \"kv\";\n/** Key read when `key` is unset. */\nexport const kvDefaultKey = \"health\";\n\n/** The subset of a `KVNamespace` binding the probe uses. */\nexport interface KVLikeNamespace {\n  /** Read one key; resolves with `null` when it does not exist. */\n  get(key: string): PromiseLike<ProbeResult>;\n}\n\n/** Options for `kvProbe()`. */\nexport interface KVProbeOptions extends ProbeOverrides {\n  /** The `KVNamespace` binding from `env`. */\n  readonly namespace: KVLikeNamespace;\n  /** Key to read. Default `kvDefaultKey`; it does not need to exist. */\n  readonly key?: string;\n}\n\n/** A probe that reads `key`; non-critical by default. Throws `ProbeConfigError` without `get()` or with an empty `key`. */\nexport function kvProbe(options: KVProbeOptions): Probe {\n  const namespace = options.namespace;\n  if (typeof namespace?.get !== \"function\") {\n    throw new ProbeConfigError(\n      \"kvProbe\",\n      \"namespace\",\n      `must expose get(), got ${describe(namespace)}`,\n    );\n  }\n  const key = options.key === undefined ? kvDefaultKey : options.key;\n  if (typeof key !== \"string\" || key.length === 0) {\n    throw new ProbeConfigError(\n      \"kvProbe\",\n      \"key\",\n      typeof key !== \"string\"\n        ? `must be a string, got ${String(key)}`\n        : \"must not be empty\",\n    );\n  }\n  return {\n    name: options.name ?? kvDefaultName,\n    critical: options.critical ?? false,\n    timeoutMs: options.timeoutMs,\n    skip: options.skip,\n    run: async () => {\n      await namespace.get(key);\n    },\n  };\n}\n\nfunction describe(namespace: KVLikeNamespace): string {\n  if (namespace == null) return String(namespace);\n  if (typeof namespace !== \"object\") return typeof namespace;\n  const keys = Object.keys(namespace);\n  return keys.length === 0\n    ? \"an object with no keys\"\n    : `an object with keys ${keys.slice(0, 8).join(\", \")}`;\n}\n"],"mappings":";;;;AA0BA,MAAa,gBAAgB;;AAE7B,MAAa,eAAe;;AAiB5B,SAAgB,QAAQA,SAAgC;CACtD,MAAM,YAAY,QAAQ;AAC1B,YAAW,WAAW,QAAQ,WAC5B,OAAM,IAAI,iBACR,WACA,cACC,yBAAyB,SAAS,UAAU,CAAC;CAGlD,MAAM,MAAM,QAAQ,iBAAoB,eAAe,QAAQ;AAC/D,YAAW,QAAQ,YAAY,IAAI,WAAW,EAC5C,OAAM,IAAI,iBACR,WACA,cACO,QAAQ,YACV,wBAAwB,OAAO,IAAI,CAAC,IACrC;AAGR,QAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,UAAU,QAAQ,YAAY;EAC9B,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd,KAAK,YAAY;AACf,SAAM,UAAU,IAAI,IAAI;EACzB;CACF;AACF;AAED,SAAS,SAASC,WAAoC;AACpD,KAAI,aAAa,KAAM,QAAO,OAAO,UAAU;AAC/C,YAAW,cAAc,SAAU,eAAc;CACjD,MAAM,OAAO,OAAO,KAAK,UAAU;AACnC,QAAO,KAAK,WAAW,IACnB,4BACC,sBAAsB,KAAK,MAAM,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC;AACxD"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@openstatus/health-cloudflare-kv",
+  "version": "0.1.4-dev.0",
+  "description": "Cloudflare Workers KV probe for @openstatus/health",
+  "keywords": [
+    "openstatus",
+    "health",
+    "healthcheck",
+    "cloudflare",
+    "kv",
+    "workers",
+    "cache"
+  ],
+  "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/cloudflare-kv/"
+  },
+  "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"
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.7",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "test": "node --experimental-transform-types --test"
+  }
+}