Feat/compt 82 custom indicator api and health service by saadmoumou · Pull Request #14 · CISCODE-MA/HealthKit

saadmoumou · 2026-04-02T13:41:02Z

Summary

What does this PR change?

Why

Why is this change needed?

Checklist

Added/updated tests (if behavior changed)
npm run lint passes
npm run typecheck passes
npm test passes
npm run build passes
Added a changeset (npx changeset) if this affects consumers

Notes

Anything reviewers should pay attention to?

…Result

…or/timeout)

…timeout)

…work/timeout)

…r dist output

…timeout)

…urrency)

…form-agnostic)

…iceUnavailableException)

…onse

…port

…ow/timeout)

…) helper

…n by scope

…ion for DI-based auto-registration

…dicator, HealthIndicatorScope

…sync

…ptions

sonarqubecloud · 2026-04-02T13:41:31Z

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
2.8% Duplication on New Code

See analysis details on SonarQube Cloud

Copilot

Pull request overview

Introduces a new @ciscode/health-kit NestJS module that provides liveness/readiness endpoints backed by pluggable health indicators (built-in + custom indicator APIs), along with supporting TS/Jest path aliases and updated repo tooling.

Changes:

Added HealthKitModule, HealthService, and a controller factory exposing /health/live and /health/ready.
Implemented built-in health indicators (Postgres, Redis, HTTP) plus custom-indicator helpers (factory + base class + decorator).
Updated package identity/tooling (package rename, TS/Jest aliases, ESLint config, Husky + lint-staged).

Reviewed changes

Copilot reviewed 26 out of 29 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
tsconfig.json	Adds `@interfaces/` and `@indicators/` path aliases.
tsconfig.build.json	Forces CommonJS + Node module resolution for build output.
src/services/health.service.ts	Adds orchestration service for liveness/readiness checks.
src/services/health.service.spec.ts	Adds unit tests for health service behavior (currently mismatched with response shape).
src/interfaces/health-indicator.interface.ts	Defines the `IHealthIndicator` contract and result types.
src/indicators/redis.indicator.ts	Adds Redis health indicator with timeout behavior.
src/indicators/redis.indicator.spec.ts	Tests Redis indicator behavior.
src/indicators/postgres.indicator.ts	Adds Postgres health indicator with timeout behavior.
src/indicators/postgres.indicator.spec.ts	Tests Postgres indicator behavior.
src/indicators/http.indicator.ts	Adds HTTP health indicator using Node 20+ `fetch`.
src/indicators/http.indicator.spec.ts	Tests HTTP indicator behavior via mocked `fetch`.
src/indicators/create-indicator.ts	Adds helper factory for inline async-function indicators.
src/indicators/create-indicator.spec.ts	Tests the custom indicator factory (currently leaves timers running on success).
src/indicators/base.indicator.ts	Adds base class for DI-based custom indicators.
src/indicators/base.indicator.spec.ts	Tests the base indicator helper behavior.
src/indicators/mongo.indicator.spec.ts	Adds Mongo indicator tests (implementation missing in this PR).
src/decorators/health-indicator.decorator.ts	Adds decorator for indicator scoping metadata.
src/decorators/health-indicator.decorator.spec.ts	Tests decorator metadata behavior (minor typo in class name).
src/controllers/health.controller.ts	Adds controller factory wired to `HealthService` returning 200/503.
src/controllers/health.controller.spec.ts	Tests controller factory behavior (stub mismatched with service result shape).
src/health-kit.module.ts	Adds dynamic module registration (sync/async) and endpoint controller creation.
src/index.ts	Replaces template exports with `health-kit` public API exports.
package.json	Renames package to `@ciscode/health-kit` and updates peer deps.
package-lock.json	Updates lockfile metadata/dependencies to match package changes.
jest.config.ts	Adds Jest moduleNameMapper entries for new TS aliases.
eslint.config.mjs	Replaces prior config file and expands ignore/ruleset (uses `import.meta.dirname`).
eslint.config.js	Removes the old ESLint config file.
lint-staged.config.mjs	Adds lint-staged rules (currently runs `eslint . --fix` on full repo).
.husky/pre-commit	Simplifies hook to only run lint-staged (currently missing Husky shim/shebang).

Copilot · 2026-04-02T13:48:18Z

src/services/health.service.ts

+export interface HealthCheckResult {
+  status: "ok" | "error";
+  results: HealthIndicatorResult[];
+}


HealthCheckResult exposes a results property, but tests/controllers in this PR use indicators. This inconsistency will break consumers and causes the current unit tests to fail at runtime. Align the public contract and usages (either rename results -> indicators everywhere, or update all call sites/tests to use results).

Copilot · 2026-04-02T13:48:18Z

src/services/health.service.spec.ts

+    it("returns status 'ok' when all liveness indicators are up", async () => {
+      const service = new HealthService([mockIndicator(up("proc"))], []);
+      const result = await service.checkLiveness();
+
+      expect(result.status).toBe("ok");
+      expect(result.indicators).toEqual([up("proc")]);
+    });


Tests assert on result.indicators, but HealthService.checkLiveness() returns HealthCheckResult with a results array. These expectations will fail and should be updated to the actual response shape (or rename the service response property for consistency).

Copilot · 2026-04-02T13:48:19Z

src/services/health.service.spec.ts

+    const result = await service.checkReadiness();
+
+    expect(result.status).toBe("error");
+    const failed = result.indicators.find((r) => r.status === "down");
+    expect(failed?.message).toBe("ECONNREFUSED");
+  });


This test uses result.indicators.find(...), but the service response uses results. Update the test (and any other callers) to use the correct property name, otherwise the test will fail and won’t validate the intended behavior.

Copilot · 2026-04-02T13:48:19Z

src/controllers/health.controller.spec.ts

+    checkLiveness: jest.fn().mockResolvedValue({ status: liveness, indicators: [] }),
+    checkReadiness: jest.fn().mockResolvedValue({ status: readiness, indicators: [] }),


The controller test stub returns { status, indicators: [] }, but the exported HealthCheckResult type uses results. The as unknown as HealthService cast hides the mismatch and makes this test diverge from real behavior. Stub the service with { status, results: [] } to match the actual contract.

Suggested change

checkLiveness: jest.fn().mockResolvedValue({ status: liveness, indicators: [] }),

checkReadiness: jest.fn().mockResolvedValue({ status: readiness, indicators: [] }),

checkLiveness: jest.fn().mockResolvedValue({ status: liveness, results: [] }),

checkReadiness: jest.fn().mockResolvedValue({ status: readiness, results: [] }),

Copilot · 2026-04-02T13:48:19Z

src/indicators/create-indicator.ts

+/**
+ * Factory that creates an {@link IHealthIndicator} from an inline async function.
+ *
+ * The check function may return:
+ * - `false` → indicator reports `"down"`
+ * - `true` or `void` → indicator reports `"up"`
+ * - throws → indicator reports `"down"` with the error message
+ *


createIndicator() docs state that thrown errors are converted into a "down" result, but the implementation lets rejections propagate (and the spec asserts that). This makes the indicator violate the IHealthIndicator.check(): Promise<HealthIndicatorResult> contract and leads to less-informative names in HealthService (e.g. "Object" on failures). Either wrap exceptions/timeouts into a HealthIndicatorResult or update the docs and downstream handling to intentionally allow throws.

Copilot · 2026-04-02T13:48:20Z

src/decorators/health-indicator.decorator.spec.ts

+
+class SomeIndicator {}
+class AnotherIndicator {}
+class UndecotratedIndicator {}


Typo in test helper class name: UndecotratedIndicator should be UndecoratedIndicator for readability and consistency with the test description (“undecorated”).

Copilot · 2026-04-02T13:48:21Z

src/indicators/create-indicator.ts

+      const timeoutPromise = new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error(`${name} timed out after ${timeout}ms`)), timeout),
+      );
+
+      return Promise.race([run(), timeoutPromise]);


The timeout setTimeout started for timeoutPromise is never cleared when checkFn completes quickly. That leaves an active timer handle for up to timeout ms per check, which can slow test runs and keep Node processes alive unnecessarily. Store the timer id and clearTimeout it in a finally once Promise.race settles.

Suggested change

const timeoutPromise = new Promise<never>((_, reject) =>

setTimeout(() => reject(new Error(`${name} timed out after ${timeout}ms`)), timeout),

);

return Promise.race([run(), timeoutPromise]);

let timeoutId: ReturnType<typeof setTimeout> | undefined;

const timeoutPromise = new Promise<never>((_, reject) => {

timeoutId = setTimeout(

() => reject(new Error(`${name} timed out after ${timeout}ms`)),

timeout,

);

});

try {

return await Promise.race([run(), timeoutPromise]);

} finally {

if (timeoutId !== undefined) {

clearTimeout(timeoutId);

}

}

Copilot · 2026-04-02T13:48:21Z

src/indicators/redis.indicator.ts

+  async check(): Promise<HealthIndicatorResult> {
+    try {
+      await Promise.race([this.client.ping(), this._timeout()]);
+      return { name: "redis", status: "up" };
+    } catch (error) {
+      return {
+        name: "redis",
+        status: "down",
+        message: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+  }
+
+  private _timeout(): Promise<never> {
+    return new Promise((_, reject) =>
+      setTimeout(() => reject(new Error("Timeout")), this.timeoutMs),
+    );
+  }


_timeout() schedules a setTimeout but it is never cleared when ping() resolves/rejects first. This leaves an active timer handle for up to timeoutMs per check, which can keep the process running longer than necessary and cause Jest “open handles” warnings. Create/clear the timeout within check() (or return a timeout promise that exposes a cancel function) so the timer is always cleaned up.

Copilot · 2026-04-02T13:48:21Z

src/indicators/postgres.indicator.ts

+  async check(): Promise<HealthIndicatorResult> {
+    try {
+      await Promise.race([this.client.query("SELECT 1"), this._timeout()]);
+      return { name: "postgres", status: "up" };
+    } catch (error) {
+      return {
+        name: "postgres",
+        status: "down",
+        message: error instanceof Error ? error.message : "Unknown error",
+      };
+    }
+  }
+
+  private _timeout(): Promise<never> {
+    return new Promise((_, reject) =>
+      setTimeout(() => reject(new Error("Timeout")), this.timeoutMs),
+    );
+  }


_timeout() starts a setTimeout that is never cleared when the query finishes before the timeout. This leaves active timer handles that can keep the Node event loop alive and trigger Jest “open handles” warnings. Prefer creating the timer in check() and clearing it in a finally after Promise.race settles.

Copilot · 2026-04-02T13:48:21Z

eslint.config.mjs

+      parser: tseslint.parser,
      parserOptions: {
-        projectService: true,
+        project: "./tsconfig.eslint.json",
        tsconfigRootDir: import.meta.dirname,
+        ecmaVersion: "latest",
+        sourceType: "module",


tsconfigRootDir: import.meta.dirname requires Node’s import.meta.dirname support; since engines.node is >=20 (not a specific minor), this may break on Node 20 versions that don’t implement import.meta.dirname. To keep linting portable, derive the directory from import.meta.url (or bump the minimum Node engine to a version that guarantees import.meta.dirname).

SAAD-MOUMOU added 30 commits March 31, 2026 12:01

chore(config): add @interfaces/* and @indicators/* path aliases

afcf4dd

chore(config): rename eslint.config.js to .mjs to fix ESM loading

2e42a1d

chore(git): fix husky pre-commit hook for v10 compatibility

f856137

feat(interfaces): add IHealthIndicator, HealthStatus, HealthIndicator…

c74b8ae

…Result

feat(indicators): add PostgresHealthIndicator (SELECT 1 + timeout)

41d7af3

test(indicators): add PostgresHealthIndicator unit tests (success/err…

8f9af5e

…or/timeout)

feat(indicators): add RedisHealthIndicator (PING + timeout)

5dff0e2

test(indicators): add RedisHealthIndicator unit tests (success/error/…

af6f235

…timeout)

feat(indicators): add HttpHealthIndicator (GET + 2xx check + timeout)

a5d8377

test(indicators): add HttpHealthIndicator unit tests (2xx/non-2xx/net…

914f341

…work/timeout)

chore(deps): update package-lock after npm install

60eedae

fix(interfaces): add optional details field to HealthIndicatorResult

7891e1e

chore(config): set module to CommonJS and moduleResolution to Node fo…

b9e39f6

…r dist output

chore(package): rename to @ciscode/health-kit

dbe9e52

chore(deps): update package-lock

801e648

feat(indicators): add MongoHealthIndicator with ping command and timeout

2e5d559

test(indicators): add MongoHealthIndicator unit tests (success/error/…

83cd1d6

…timeout)

feat(services): add HealthService with Promise.allSettled orchestration

0b633fa

test(services): add HealthService unit tests (liveness/readiness/conc…

10b4423

…urrency)

feat(controllers): add HealthController factory (GET live/ready, plat…

4fdefba

…form-agnostic)

test(controllers): add HealthController unit tests (200 ok / 503 Serv…

bbb1f18

…iceUnavailableException)

feat(module): add HealthKitModule.register() dynamic module

80cdcaf

feat(exports): update public API exports for health-kit

e29be84

fix(services): rename indicators to results in HealthCheckResult resp…

eff4978

…onse

feat(indicators): add createIndicator inline factory with timeout sup…

a73cb21

…port

test(indicators): add createIndicator unit tests (true/false/void/thr…

7898821

…ow/timeout)

feat(indicators): add BaseHealthIndicator abstract class with result(…

543a07a

…) helper

test(indicators): add BaseHealthIndicator unit tests

63c1336

feat(decorators): add @healthindicator decorator for auto-registratio…

f8e8e01

…n by scope

test(decorators): add @healthindicator decorator unit tests

d4947d7

SAAD-MOUMOU added 7 commits April 2, 2026 14:05

feat(module): extend HealthKitModule.register() with indicators[] opt…

36a99ab

…ion for DI-based auto-registration

feat(exports): export createIndicator, BaseHealthIndicator, @healthin…

15c05f7

…dicator, HealthIndicatorScope

chore(package): update description to mention MongoDB

042c48c

chore(indicators): remove MongoHealthIndicator

f63633f

feat(module): make path optional with default 'health', add registerA…

052cecf

…sync

feat(exports): remove MongoHealthIndicator, export HealthModuleAsyncO…

86f470c

…ptions

chore(package): add @nestjs/terminus peer dep, fix description

8eae15f

saadmoumou requested review from a team and Copilot April 2, 2026 13:41

saadmoumou closed this Apr 2, 2026

Copilot started reviewing on behalf of saadmoumou April 2, 2026 13:41 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feat/compt 82 custom indicator api and health service#14

Feat/compt 82 custom indicator api and health service#14
saadmoumou wants to merge 37 commits intomasterfrom
feat/COMPT-82-custom-indicator-api-and-health-service

saadmoumou commented Apr 2, 2026

Uh oh!

sonarqubecloud bot commented Apr 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		checkLiveness: jest.fn().mockResolvedValue({ status: liveness, indicators: [] }),
		checkReadiness: jest.fn().mockResolvedValue({ status: readiness, indicators: [] }),

-      const timeoutPromise = new Promise<never>((_, reject) =>
-        setTimeout(() => reject(new Error(`${name} timed out after ${timeout}ms`)), timeout),
-      );
-      return Promise.race([run(), timeoutPromise]);
+      let timeoutId: ReturnType<typeof setTimeout> | undefined;
+      const timeoutPromise = new Promise<never>((_, reject) => {
+        timeoutId = setTimeout(
+          () => reject(new Error(`${name} timed out after ${timeout}ms`)),
+          timeout,
+        );
+      });
+      try {
+        return await Promise.race([run(), timeoutPromise]);
+      } finally {
+        if (timeoutId !== undefined) {
+          clearTimeout(timeoutId);
+        }
+      }

Conversation

saadmoumou commented Apr 2, 2026

Summary

Why

Checklist

Notes

Uh oh!

sonarqubecloud bot commented Apr 2, 2026

Quality Gate passed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants