Custom indicator api and health service by saadmoumou · Pull Request #6 · CISCODE-MA/HealthKit

saadmoumou · 2026-04-02T11:31:34Z

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)

…port

…ow/timeout)

…) helper

…n by scope

…ion for DI-based auto-registration

…dicator, HealthIndicatorScope

sonarqubecloud · 2026-04-02T11:32:08Z

Quality Gate passed

Issues
5 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

Copilot

Pull request overview

Adds a reusable @ciscode/health-kit NestJS module that exposes liveness/readiness HTTP endpoints and a small indicator API (built-in indicators + custom indicator helpers) for composing health checks in consumer applications.

Changes:

Introduces HealthKitModule, HealthService, and a /live + /ready controller factory.
Adds built-in health indicators (Postgres, Redis, Mongo, HTTP) plus custom-indicator helpers (createIndicator, BaseHealthIndicator, @HealthIndicator decorator).
Updates tooling/config for the new package (path aliases, Jest mappers, ESLint config, lint-staged, Husky hook, build tsconfig, package rename).

Reviewed changes

Copilot reviewed 27 out of 30 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tsconfig.json	Adds `@interfaces/` and `@indicators/` path aliases.
tsconfig.build.json	Adjusts build output to CommonJS/Node module resolution for `dist`.
src/services/health.service.ts	New orchestrator for running indicators and returning aggregate status.
src/services/health.service.spec.ts	Unit tests for `HealthService` behavior and exception handling.
src/interfaces/health-indicator.interface.ts	Defines indicator contracts and result types.
src/indicators/redis.indicator.ts	Adds Redis indicator implementation.
src/indicators/redis.indicator.spec.ts	Tests Redis indicator success/error/timeout paths.
src/indicators/postgres.indicator.ts	Adds Postgres indicator implementation.
src/indicators/postgres.indicator.spec.ts	Tests Postgres indicator success/error/timeout paths.
src/indicators/mongo.indicator.ts	Adds Mongo indicator implementation.
src/indicators/mongo.indicator.spec.ts	Tests Mongo indicator success/error/timeout paths.
src/indicators/http.indicator.ts	Adds HTTP indicator using `fetch` + `AbortController` timeout.
src/indicators/http.indicator.spec.ts	Tests HTTP indicator for 2xx/non-2xx/errors/timeout.
src/indicators/create-indicator.ts	Adds functional factory for creating ad-hoc indicators.
src/indicators/create-indicator.spec.ts	Tests `createIndicator` behavior including timeout/error cases.
src/indicators/base.indicator.ts	Adds base class helper for DI-driven indicator implementations.
src/indicators/base.indicator.spec.ts	Tests `BaseHealthIndicator.result()` helper behavior.
src/index.ts	Updates public exports to expose health-kit module/services/indicators/decorator/types.
src/health-kit.module.ts	Adds dynamic module wiring + auto-registration of DI indicators via metadata.
src/decorators/health-indicator.decorator.ts	Adds `@HealthIndicator` scope metadata decorator.
src/decorators/health-indicator.decorator.spec.ts	Tests decorator metadata behavior.
src/controllers/health.controller.ts	Adds controller factory for configurable health routes.
src/controllers/health.controller.spec.ts	Tests controller behavior (200 vs 503).
package.json	Renames package and updates description/peers.
package-lock.json	Updates lockfile for rename and dependency changes.
lint-staged.config.mjs	Adds lint-staged configuration for formatting/linting staged files.
jest.config.ts	Adds Jest moduleNameMapper entries for new path aliases.
eslint.config.mjs	Reworks ESLint config (ignores, TS parser setup, import ordering rules).
eslint.config.js	Removes old ESLint config file.
.husky/pre-commit	Changes pre-commit hook to run lint-staged (but drops Husky header).

Copilot · 2026-04-02T11:36:01Z

.husky/pre-commit

-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
 npx lint-staged


The Husky hook header was removed. Without the shebang and sourcing ./_/husky.sh, the hook can fail in some environments (e.g., PATH not set to include local node binaries). Restore the standard Husky pre-commit header like the pre-push hook uses.

Copilot · 2026-04-02T11:36:01Z

src/indicators/redis.indicator.ts

+ * Built-in health indicator for a Redis dependency.
+ *
+ * Sends a `PING` command and expects a `"PONG"` response.
+ * Returns `"down"` if the command fails or exceeds the configured timeout.
+ *


The JSDoc says the PING expects a "PONG" response, but the implementation treats any resolved ping() result as healthy. Either validate the returned value (e.g., equals "PONG") or adjust the documentation to match the behavior.

Copilot · 2026-04-02T11:36:01Z

src/indicators/redis.indicator.ts

+  async check(): Promise<HealthIndicatorResult> {
+    try {
+      await Promise.race([this.client.ping(), this._timeout()]);
+      return { name: "redis", status: "up" };


This uses Promise.race([ping(), _timeout()]) but the _timeout() sets a timer that is never cleared when ping() resolves quickly. This leaves extra timers queued (can keep the event loop alive and adds overhead under load). Consider creating the timeout timer in check() and clearTimeout it in a finally block once the race settles.

Copilot · 2026-04-02T11:36:02Z

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" };


Same timer issue as Redis: _timeout() schedules a setTimeout that isn't cleared when the query resolves first. Refactor to clear the timer in finally to avoid unnecessary timers keeping the event loop active.

Copilot · 2026-04-02T11:36:02Z

src/indicators/mongo.indicator.ts

+  async check(): Promise<HealthIndicatorResult> {
+    try {
+      await Promise.race([this.db.command({ ping: 1 }), this._timeout()]);
+      return { name: "mongo", status: "up" };


Same timer issue as Redis/Postgres: _timeout() schedules a setTimeout that isn't cleared if the ping command resolves first. Clearing the timer once the race completes avoids leaking timers and reduces overhead.

Copilot · 2026-04-02T11:36:02Z

src/indicators/create-indicator.ts

+ * The check function may return:
+ * - `false` → indicator reports `"down"`
+ * - `true` or `void` → indicator reports `"up"`
+ * - throws → indicator reports `"down"` with the error message
+ *


The doc comment says “throws → indicator reports "down" with the error message”, but this implementation lets rejections/timeouts propagate (the returned promise rejects) instead of returning a HealthIndicatorResult. Either update the docs (and potentially the IHealthIndicator contract) or catch errors/timeouts here and return { name, status: 'down', message } for consistency with the other indicators.

Copilot · 2026-04-02T11:36:02Z

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 promise uses setTimeout but the timer is never cleared when run() completes first. While Promise.race attaches handlers, the pending timer still adds overhead and can keep the event loop alive. Consider storing the timeout handle and clearTimeout it in a finally block once the race settles.

Copilot · 2026-04-02T11:36:03Z

src/services/health.service.ts

+ * Runs all registered indicators concurrently via `Promise.allSettled` so a
+ * single slow/failing dependency never blocks the others.
+ * Returns `status: "ok"` only when every indicator reports `"up"`.


The comment claims Promise.allSettled ensures a single slow dependency “never blocks the others”, but allSettled still waits for all indicators to settle before returning (so a slow indicator will delay the overall health response). Consider rewording to clarify it avoids short-circuiting on failure, not latency impact.

Suggested change

* Runs all registered indicators concurrently via `Promise.allSettled` so a

* single slow/failing dependency never blocks the others.

* Returns `status: "ok"` only when every indicator reports `"up"`.

* Runs all registered indicators concurrently via `Promise.allSettled`, so a

* failure in one indicator does not short‑circuit or prevent others from running.

* The overall check still waits for all indicators to settle, and returns

* `status: "ok"` only when every indicator reports `"up"`.

Copilot · 2026-04-02T11:36:03Z

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

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


Typo in class name UndecotratedIndicator → UndecoratedIndicator. This is user-facing in test names/examples and makes the intent harder to read.

Copilot · 2026-04-02T11:36:03Z

src/health-kit.module.ts

+ * import { HealthModule } from '@ciscode/health-kit';
+ * import { MongoHealthIndicator } from '@ciscode/health-kit';
+ *
+ * @Module({
+ *   imports: [
+ *     HealthModule.register({


The module JSDoc example uses HealthModule.register(...), but the exported class is HealthKitModule (and index.ts exports HealthKitModule). Update the example imports/usages to match the actual public API so consumers can copy/paste it successfully.

Suggested change

* import { HealthModule } from '@ciscode/health-kit';

* import { MongoHealthIndicator } from '@ciscode/health-kit';

*

* @Module({

* imports: [

* HealthModule.register({

* import { HealthKitModule, MongoHealthIndicator } from '@ciscode/health-kit';

*

* @Module({

* imports: [

* HealthKitModule.register({

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

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

f27a411

…r dist output

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

a3ff296

chore(deps): update package-lock

e732894

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

15f7b7f

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

686dc9e

…timeout)

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

90f4e9d

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

e0c0e53

…urrency)

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

de52d73

…form-agnostic)

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

224ad90

…iceUnavailableException)

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

831dcc1

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

5b5f872

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

bcdc00c

…port

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

3cb5a91

…ow/timeout)

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

dcf3e60

…) helper

test(indicators): add BaseHealthIndicator unit tests

84b2254

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

b285d64

…n by scope

test(decorators): add @healthindicator decorator unit tests

cbd5cf2

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

bdcd32c

…ion for DI-based auto-registration

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

881d0f2

…dicator, HealthIndicatorScope

chore(package): update description to mention MongoDB

9bfea9f

saadmoumou requested review from a team and Copilot April 2, 2026 11:31

saadmoumou closed this Apr 2, 2026

Copilot started reviewing on behalf of saadmoumou April 2, 2026 11:32 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Custom indicator api and health service#6

Custom indicator api and health service#6
saadmoumou wants to merge 31 commits intomasterfrom
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

- * Runs all registered indicators concurrently via `Promise.allSettled` so a
- * single slow/failing dependency never blocks the others.
- * Returns `status: "ok"` only when every indicator reports `"up"`.
+ * Runs all registered indicators concurrently via `Promise.allSettled`, so a
+ * failure in one indicator does not short‑circuit or prevent others from running.
+ * The overall check still waits for all indicators to settle, and returns
+ * `status: "ok"` only when every indicator reports `"up"`.

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