@openstatus/health-neon 0.1.4-dev.0

package/README.md

@@ -0,0 +1,75 @@
+# @openstatus/health-neon
+
+[Neon](https://neon.com/) serverless Postgres probe for
+[`@openstatus/health`](https://jsr.io/@openstatus/health). Runs `select 1`
+through [`@neondatabase/serverless`](https://github.com/neondatabase/serverless)
+— the HTTP `neon()` driver or the WebSocket `Pool` / `Client` — and fails the
+check when the round trip does.
+
+```sh
+deno add jsr:@openstatus/health jsr:@openstatus/health-neon
+npm install @openstatus/health @openstatus/health-neon
+```
+
+```ts
+import { neon } from "@neondatabase/serverless";
+import { createHealthHandler } from "@openstatus/health";
+import { neonProbe } from "@openstatus/health-neon";
+
+const sql = neon(env.DATABASE_URL);
+
+Deno.serve(
+  createHealthHandler({ probes: [neonProbe({ client: sql })] }),
+);
+```
+
+The HTTP driver is the best fit for a health endpoint: every probe is one
+stateless `fetch`, nothing stays open between requests, and it runs on edge
+runtimes; the probe's `AbortSignal` is passed as `fetchOptions.signal`, so
+a `timeoutMs` cancels the request in flight. `Pool` and `Client` work the
+same way — the probe calls `client.query("select 1")` on whichever you
+pass — but their `query()` takes no signal, so a timed-out query runs to
+completion on the connection. On a scale-to-zero branch
+the first probe after idle also pays the compute wake-up, so give it a
+`timeoutMs` that allows for it or point the probe at a branch that stays
+warm.
+
+```ts
+neonProbe({
+  client: sql,
+  // optional overrides from the Probe contract
+  name: "primary",
+  critical: false,
+  timeoutMs: 3000,
+  skip: () => env.DATABASE_URL == null,
+});
+```
+
+Critical by default: a Postgres that does not answer usually means requests
+cannot be served, so the report turns `unhealthy` and the instance is taken
+out of rotation. Set `critical: false` for a read replica or a branch that
+only serves reporting.
+
+The client is typed structurally as `{ query(text, params?, options?) }`, so
+`@neondatabase/serverless` is an optional peer dependency for its types only
+and the probe adds no runtime import of it. It needs `1.0.0` or newer, where
+`neon()`'s `sql.query()` became a plain function call. The factory throws
+`ProbeConfigError` at construction when the client has no `query()`.
+
+## 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 neonDefaultName = "database";
+/** A probe that runs `select 1`; critical by default. The HTTP driver from `neon()` receives the probe's `AbortSignal` through `fetchOptions`; `Pool` / `Client` take no signal. Throws `ProbeConfigError` without `query()`. */
+function neonProbe(options) {
+	const client = options.client;
+	if (typeof client?.query !== "function") throw new __openstatus_health.ProbeConfigError("neonProbe", "client", `must expose query(), got ${describe(client)}`);
+	const httpDriver = isCallable(client);
+	return {
+		name: options.name ?? neonDefaultName,
+		critical: options.critical ?? true,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async (signal) => {
+			if (httpDriver) await client.query("select 1", [], { fetchOptions: { signal } });
+			else await client.query("select 1");
+		}
+	};
+}
+function isCallable(client) {
+	return typeof client === "function";
+}
+function describe(client) {
+	if (client == null) return String(client);
+	if (typeof client !== "object" && typeof client !== "function") return typeof client;
+	const keys = Object.keys(client);
+	return keys.length === 0 ? `${typeof client === "function" ? "a function" : "an object"} with no keys` : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+exports.neonDefaultName = neonDefaultName;
+exports.neonProbe = neonProbe;

package/dist/mod.d.cts

@@ -0,0 +1,29 @@
+import { Probe, ProbeOverrides, ProbeResult } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const neonDefaultName = "database";
+/** What the probe passes to the HTTP driver's `query()` after the statement. */
+interface NeonQueryOptions {
+  /** Merged into the `fetch` call; carries the probe's `AbortSignal`. */
+  readonly fetchOptions?: {
+    readonly signal?: AbortSignal;
+  };
+}
+/** The subset of `@neondatabase/serverless` the probe uses: `neon()`'s `sql.query()`, or `Pool` / `Client`. */
+interface NeonLikeClient {
+  /** Run one statement; the HTTP driver also receives `params` and `options`. */
+  query(text: string, params?: never[], options?: NeonQueryOptions): PromiseLike<ProbeResult>;
+}
+/** Options for `neonProbe()`. */
+interface NeonProbeOptions extends ProbeOverrides {
+  /** The `sql` function from `neon()`, or a `Pool` / `Client`. */
+  readonly client: NeonLikeClient;
+}
+/** A probe that runs `select 1`; critical by default. The HTTP driver from `neon()` receives the probe's `AbortSignal` through `fetchOptions`; `Pool` / `Client` take no signal. Throws `ProbeConfigError` without `query()`. */
+declare function neonProbe(options: NeonProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { NeonLikeClient, NeonProbeOptions, NeonQueryOptions, neonDefaultName, neonProbe };
+//# 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":";;;;;AAyCwD,cAnB3C,eAAA,GAmB2C,UAAA;AAMxD;AAAyB,UAtBR,gBAAA,CAsBQ;EAAA;EAA0B,SAAG,YAAA,CAAA,EAAA;IAAK,SAAA,MAAA,CAAA,EApBb,WAoBa;;;;UAhB1C,cAAA;;kDAKH,mBACT,YAAY;;;UAIA,gBAAA,SAAyB;;mBAEvB;;;iBAIH,SAAA,UAAmB,mBAAmB"}

package/dist/mod.d.ts

@@ -0,0 +1,29 @@
+import { Probe, ProbeOverrides, ProbeResult } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const neonDefaultName = "database";
+/** What the probe passes to the HTTP driver's `query()` after the statement. */
+interface NeonQueryOptions {
+  /** Merged into the `fetch` call; carries the probe's `AbortSignal`. */
+  readonly fetchOptions?: {
+    readonly signal?: AbortSignal;
+  };
+}
+/** The subset of `@neondatabase/serverless` the probe uses: `neon()`'s `sql.query()`, or `Pool` / `Client`. */
+interface NeonLikeClient {
+  /** Run one statement; the HTTP driver also receives `params` and `options`. */
+  query(text: string, params?: never[], options?: NeonQueryOptions): PromiseLike<ProbeResult>;
+}
+/** Options for `neonProbe()`. */
+interface NeonProbeOptions extends ProbeOverrides {
+  /** The `sql` function from `neon()`, or a `Pool` / `Client`. */
+  readonly client: NeonLikeClient;
+}
+/** A probe that runs `select 1`; critical by default. The HTTP driver from `neon()` receives the probe's `AbortSignal` through `fetchOptions`; `Pool` / `Client` take no signal. Throws `ProbeConfigError` without `query()`. */
+declare function neonProbe(options: NeonProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { NeonLikeClient, NeonProbeOptions, NeonQueryOptions, neonDefaultName, neonProbe };
+//# 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":";;;;;AAyCwD,cAnB3C,eAAA,GAmB2C,UAAA;AAMxD;AAAyB,UAtBR,gBAAA,CAsBQ;EAAA;EAA0B,SAAG,YAAA,CAAA,EAAA;IAAK,SAAA,MAAA,CAAA,EApBb,WAoBa;;;;UAhB1C,cAAA;;kDAKH,mBACT,YAAY;;;UAIA,gBAAA,SAAyB;;mBAEvB;;;iBAIH,SAAA,UAAmB,mBAAmB"}

package/dist/mod.js

@@ -0,0 +1,34 @@
+import { ProbeConfigError } from "@openstatus/health";
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const neonDefaultName = "database";
+/** A probe that runs `select 1`; critical by default. The HTTP driver from `neon()` receives the probe's `AbortSignal` through `fetchOptions`; `Pool` / `Client` take no signal. Throws `ProbeConfigError` without `query()`. */
+function neonProbe(options) {
+	const client = options.client;
+	if (typeof client?.query !== "function") throw new ProbeConfigError("neonProbe", "client", `must expose query(), got ${describe(client)}`);
+	const httpDriver = isCallable(client);
+	return {
+		name: options.name ?? neonDefaultName,
+		critical: options.critical ?? true,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async (signal) => {
+			if (httpDriver) await client.query("select 1", [], { fetchOptions: { signal } });
+			else await client.query("select 1");
+		}
+	};
+}
+function isCallable(client) {
+	return typeof client === "function";
+}
+function describe(client) {
+	if (client == null) return String(client);
+	if (typeof client !== "object" && typeof client !== "function") return typeof client;
+	const keys = Object.keys(client);
+	return keys.length === 0 ? `${typeof client === "function" ? "a function" : "an object"} with no keys` : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+export { neonDefaultName, neonProbe };
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["options: NeonProbeOptions","client: object","client: NeonLikeClient"],"sources":["../src/mod.ts"],"sourcesContent":["/**\n * Neon serverless Postgres probe for `@openstatus/health`: runs `select 1`\n * over the HTTP driver, or a `Pool` / `Client`, from `@neondatabase/serverless`.\n *\n * ```ts\n * import { neon } from \"@neondatabase/serverless\";\n * import { neonProbe } from \"@openstatus/health-neon\";\n *\n * const probe = neonProbe({ client: neon(env.DATABASE_URL) });\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 neonDefaultName = \"database\";\n\n/** What the probe passes to the HTTP driver's `query()` after the statement. */\nexport interface NeonQueryOptions {\n  /** Merged into the `fetch` call; carries the probe's `AbortSignal`. */\n  readonly fetchOptions?: { readonly signal?: AbortSignal };\n}\n\n/** The subset of `@neondatabase/serverless` the probe uses: `neon()`'s `sql.query()`, or `Pool` / `Client`. */\nexport interface NeonLikeClient {\n  /** Run one statement; the HTTP driver also receives `params` and `options`. */\n  query(\n    text: string,\n    params?: never[],\n    options?: NeonQueryOptions,\n  ): PromiseLike<ProbeResult>;\n}\n\n/** Options for `neonProbe()`. */\nexport interface NeonProbeOptions extends ProbeOverrides {\n  /** The `sql` function from `neon()`, or a `Pool` / `Client`. */\n  readonly client: NeonLikeClient;\n}\n\n/** A probe that runs `select 1`; critical by default. The HTTP driver from `neon()` receives the probe's `AbortSignal` through `fetchOptions`; `Pool` / `Client` take no signal. Throws `ProbeConfigError` without `query()`. */\nexport function neonProbe(options: NeonProbeOptions): Probe {\n  const client = options.client;\n  if (typeof client?.query !== \"function\") {\n    throw new ProbeConfigError(\n      \"neonProbe\",\n      \"client\",\n      `must expose query(), got ${describe(client)}`,\n    );\n  }\n  const httpDriver = isCallable(client);\n  return {\n    name: options.name ?? neonDefaultName,\n    critical: options.critical ?? true,\n    timeoutMs: options.timeoutMs,\n    skip: options.skip,\n    run: async (signal) => {\n      if (httpDriver) {\n        await client.query(\"select 1\", [], { fetchOptions: { signal } });\n      } else {\n        await client.query(\"select 1\");\n      }\n    },\n  };\n}\n\nfunction isCallable(client: object): boolean {\n  return typeof client === \"function\";\n}\n\nfunction describe(client: NeonLikeClient): string {\n  if (client == null) return String(client);\n  if (typeof client !== \"object\" && typeof client !== \"function\") {\n    return typeof client;\n  }\n  const keys = Object.keys(client);\n  return keys.length === 0\n    ? `${\n      typeof client === \"function\" ? \"a function\" : \"an object\"\n    } with no keys`\n    : `an object with keys ${keys.slice(0, 8).join(\", \")}`;\n}\n"],"mappings":";;;;AAsBA,MAAa,kBAAkB;;AAyB/B,SAAgB,UAAUA,SAAkC;CAC1D,MAAM,SAAS,QAAQ;AACvB,YAAW,QAAQ,UAAU,WAC3B,OAAM,IAAI,iBACR,aACA,WACC,2BAA2B,SAAS,OAAO,CAAC;CAGjD,MAAM,aAAa,WAAW,OAAO;AACrC,QAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,UAAU,QAAQ,YAAY;EAC9B,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd,KAAK,OAAO,WAAW;AACrB,OAAI,WACF,OAAM,OAAO,MAAM,YAAY,CAAE,GAAE,EAAE,cAAc,EAAE,OAAQ,EAAE,EAAC;OAEhE,OAAM,OAAO,MAAM,WAAW;EAEjC;CACF;AACF;AAED,SAAS,WAAWC,QAAyB;AAC3C,eAAc,WAAW;AAC1B;AAED,SAAS,SAASC,QAAgC;AAChD,KAAI,UAAU,KAAM,QAAO,OAAO,OAAO;AACzC,YAAW,WAAW,mBAAmB,WAAW,WAClD,eAAc;CAEhB,MAAM,OAAO,OAAO,KAAK,OAAO;AAChC,QAAO,KAAK,WAAW,KAClB,SACM,WAAW,aAAa,eAAe,YAC/C,kBACE,sBAAsB,KAAK,MAAM,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC;AACxD"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@openstatus/health-neon",
+  "version": "0.1.4-dev.0",
+  "description": "Neon serverless Postgres probe for @openstatus/health",
+  "keywords": [
+    "openstatus",
+    "health",
+    "healthcheck",
+    "neon",
+    "postgres",
+    "serverless",
+    "database"
+  ],
+  "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/neon/"
+  },
+  "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",
+    "@neondatabase/serverless": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@neondatabase/serverless": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@neondatabase/serverless": "^1.0.0",
+    "tsdown": "^0.12.7",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "test": "node --experimental-transform-types --test"
+  }
+}