@moshaver/cmb-health 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mobin Karam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @moshaver/cmb-health
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-neutral health/readiness capability. Applications provide named probes and decide how failures map to HTTP, process, orchestration, or platform-specific behavior.
+
+## Install and use
+
+```bash
+npm install @moshaver/cmb-health
+```
+
+```js
+const { CmbHealthService } = require("@moshaver/cmb-health");
+const health = new CmbHealthService({ serviceName: "api", probes: [] });
+await health.ready();
+```

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@moshaver/cmb-health",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Composable Modular Backend health primitives.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "cmb",
+    "modular-backend",
+    "backend",
+    "framework-agnostic",
+    "health"
+  ],
+  "engines": {
+    "node": ">=22.13.0 <23"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mobin-Karam/moshaver.git",
+    "directory": "packages/cmb/health"
+  },
+  "bugs": {
+    "url": "https://github.com/Mobin-Karam/moshaver/issues"
+  },
+  "homepage": "https://github.com/Mobin-Karam/moshaver/tree/main/packages/cmb",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "dependencies": {
+    "@moshaver/cmb-kernel": "^0.1.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,20 @@
+import type { CmbModuleDescriptor } from "@moshaver/cmb-kernel";
+
+export const HEALTH_MODULE: CmbModuleDescriptor;
+
+export type ReadinessProbe = Readonly<{
+  name: string;
+  check: () => void | Promise<void>;
+}>;
+
+export class ReadinessError extends Error {
+  readonly probe: string;
+  readonly cause: unknown;
+  constructor(probe: string, cause: unknown);
+}
+
+export class CmbHealthService {
+  constructor(options: { serviceName: string; probes?: readonly ReadinessProbe[] });
+  health(): { service: string; status: "ok" };
+  ready(): Promise<Record<string, "ready">>;
+}

package/src/index.js

@@ -0,0 +1,63 @@
+"use strict";
+
+const { defineModule } = require("@moshaver/cmb-kernel");
+
+const HEALTH_MODULE = defineModule({
+  id: "health",
+  version: "0.1.0",
+  kind: "foundation",
+  dependencies: ["kernel"],
+  provides: ["health.service"],
+  health: ["liveness", "readiness"],
+  configuration: { serviceName: "required", probes: "optional" },
+});
+
+class ReadinessError extends Error {
+  constructor(probe, cause) {
+    super(`Readiness probe failed: ${probe}`);
+    this.name = "ReadinessError";
+    this.probe = probe;
+    this.cause = cause;
+  }
+}
+
+class CmbHealthService {
+  constructor(options) {
+    if (!options || typeof options !== "object") throw new TypeError("Health options are required.");
+    this.serviceName = String(options.serviceName ?? "").trim();
+    if (!this.serviceName) throw new TypeError("Health serviceName is required.");
+
+    this.probes = Array.from(options.probes ?? []);
+    const names = new Set();
+    for (const probe of this.probes) {
+      if (!probe || typeof probe !== "object" || typeof probe.check !== "function") throw new TypeError("Each readiness probe requires a check() function.");
+      const name = String(probe.name ?? "").trim();
+      if (!name) throw new TypeError("Each readiness probe requires a name.");
+      if (names.has(name)) throw new TypeError(`Duplicate readiness probe: ${name}`);
+      names.add(name);
+    }
+  }
+
+  health() {
+    return { service: this.serviceName, status: "ok" };
+  }
+
+  async ready() {
+    const result = {};
+    for (const probe of this.probes) {
+      try {
+        await probe.check();
+        result[probe.name] = "ready";
+      } catch (cause) {
+        throw new ReadinessError(probe.name, cause);
+      }
+    }
+    return result;
+  }
+}
+
+module.exports = {
+  HEALTH_MODULE,
+  ReadinessError,
+  CmbHealthService,
+};