@macss/modular-api 0.1.0 → 0.2.0

package/README.md

@@ -1,131 +1,132 @@
-# modular_api
-
-Use-case centric toolkit for building modular APIs with Express.  
-Define `UseCase` classes (input → validate → execute → output), connect them to HTTP routes, and get automatic Swagger/OpenAPI documentation.
-
-> TypeScript port of [modular_api](https://pub.dev/packages/modular_api) (Dart/Shelf)
-
----
-
-## Quick start
-
-```ts
-import { ModularApi, ModuleBuilder } from 'modular_api';
-
-// ─── Module builder (separate file in real projects) ──────────
-function buildGreetingsModule(m: ModuleBuilder): void {
-  m.usecase('hello', HelloWorld.fromJson);
-}
-
-// ─── Server ───────────────────────────────────────────────────
-const api = new ModularApi({ basePath: '/api' });
-
-api.module('greetings', buildGreetingsModule);
-
-api.serve({ port: 8080 });
-```
-
-```bash
-curl -X POST http://localhost:8080/api/greetings/hello \
-  -H "Content-Type: application/json" \
-  -d '{"name":"World"}'
-```
-
-```json
-{"message":"Hello, World!"}
-```
-
-**Docs** → `http://localhost:8080/docs`  
-**Health** → `http://localhost:8080/health`
-
-See `example/example.ts` for the full implementation including Input, Output, UseCase with `validate()`, and the builder.
-
----
-
-## Features
-
-- `UseCase<I, O>` — pure business logic, no HTTP concerns
-- `Input` / `Output` — DTOs with `toJson()` and `toSchema()` for automatic OpenAPI
-- `Output.statusCode` — custom HTTP status codes per response
-- `UseCaseException` — structured error handling (status code, message, error code, details)
-- `ModularApi` + `ModuleBuilder` — module registration and routing
-- `useCaseTestHandler` — unit test helper (no HTTP server needed)
-- `cors()` middleware — built-in CORS support
-- Swagger UI at `/docs` — auto-generated from registered use cases
-- Health check at `GET /health`
-- All endpoints default to `POST` (configurable per use case)
-- Full TypeScript declarations (`.d.ts`) included
-
----
-
-## Installation
-
-```bash
-npm install modular_api
-```
-
----
-
-## Error handling
-
-```ts
-async execute() {
-  const user = await repository.findById(this.input.userId);
-  if (!user) {
-    throw new UseCaseException({
-      statusCode: 404,
-      message: 'User not found',
-      errorCode: 'USER_NOT_FOUND',
-    });
-  }
-  this.output = new GetUserOutput(user);
-}
-```
-
-```json
-{"error": "USER_NOT_FOUND", "message": "User not found"}
-```
-
----
-
-## Testing
-
-```ts
-import { useCaseTestHandler } from 'modular_api';
-
-const handler = useCaseTestHandler(HelloWorld.fromJson);
-const response = await handler({ name: 'World' });
-
-console.log(response.statusCode); // 200
-console.log(response.body);       // { message: 'Hello, World!' }
-```
-
----
-
-## Architecture
-
-```
-HTTP Request → ModularApi → Module → UseCase → Business Logic → Output → HTTP Response
-```
-
-- **UseCase layer** — pure logic, independent of HTTP
-- **HTTP adapter** — turns a UseCase into an Express RequestHandler
-- **Middlewares** — cross-cutting concerns (CORS, logging)
-- **Swagger UI** — documentation served automatically
-
----
-
-## Dart version
-
-This is the TypeScript port. The original Dart version is available at:
-
-- **pub.dev**: [modular_api](https://pub.dev/packages/modular_api)
-- **GitHub**: [macss-dev/modular_api](https://github.com/macss-dev/modular_api)
-
-Both SDKs share the same architecture and API surface at v0.1.0.
-
----
-
-## License
-
-MIT © [ccisne.dev](https://ccisne.dev)
+# modular_api
+
+Use-case centric toolkit for building modular APIs with Express.  
+Define `UseCase` classes (input → validate → execute → output), connect them to HTTP routes, and get automatic Swagger/OpenAPI documentation.
+
+> TypeScript port of [modular_api](https://pub.dev/packages/modular_api) (Dart/Shelf)
+
+---
+
+## Quick start
+
+```ts
+import { ModularApi, ModuleBuilder } from 'modular_api';
+
+// ─── Module builder (separate file in real projects) ──────────
+function buildGreetingsModule(m: ModuleBuilder): void {
+  m.usecase('hello', HelloWorld.fromJson);
+}
+
+// ─── Server ───────────────────────────────────────────────────
+const api = new ModularApi({ basePath: '/api' });
+
+api.module('greetings', buildGreetingsModule);
+
+api.serve({ port: 8080 });
+```
+
+```bash
+curl -X POST http://localhost:8080/api/greetings/hello \
+  -H "Content-Type: application/json" \
+  -d '{"name":"World"}'
+```
+
+```json
+{ "message": "Hello, World!" }
+```
+
+**Docs** → `http://localhost:8080/docs`  
+**Health** → `http://localhost:8080/health`
+
+See `example/example.ts` for the full implementation including Input, Output, UseCase with `validate()`, and the builder.
+
+---
+
+## Features
+
+- `UseCase<I, O>` — pure business logic, no HTTP concerns
+- `Input` / `Output` — DTOs with `toJson()` and `toSchema()` for automatic OpenAPI
+- `Output.statusCode` — custom HTTP status codes per response
+- `UseCaseException` — structured error handling (status code, message, error code, details)
+- `ModularApi` + `ModuleBuilder` — module registration and routing
+- `useCaseTestHandler` — unit test helper (no HTTP server needed)
+- `cors()` middleware — built-in CORS support
+- Swagger UI at `/docs` — auto-generated from registered use cases
+- Health check at `GET /health` — [IETF Health Check Response Format](doc/health_check_guide.md)
+- Prometheus metrics at `GET /metrics` — [Prometheus exposition format](doc/metrics_guide.md)
+- All endpoints default to `POST` (configurable per use case)
+- Full TypeScript declarations (`.d.ts`) included
+
+---
+
+## Installation
+
+```bash
+npm install modular_api
+```
+
+---
+
+## Error handling
+
+```ts
+async execute() {
+  const user = await repository.findById(this.input.userId);
+  if (!user) {
+    throw new UseCaseException({
+      statusCode: 404,
+      message: 'User not found',
+      errorCode: 'USER_NOT_FOUND',
+    });
+  }
+  this.output = new GetUserOutput(user);
+}
+```
+
+```json
+{ "error": "USER_NOT_FOUND", "message": "User not found" }
+```
+
+---
+
+## Testing
+
+```ts
+import { useCaseTestHandler } from 'modular_api';
+
+const handler = useCaseTestHandler(HelloWorld.fromJson);
+const response = await handler({ name: 'World' });
+
+console.log(response.statusCode); // 200
+console.log(response.body); // { message: 'Hello, World!' }
+```
+
+---
+
+## Architecture
+
+```
+HTTP Request → ModularApi → Module → UseCase → Business Logic → Output → HTTP Response
+```
+
+- **UseCase layer** — pure logic, independent of HTTP
+- **HTTP adapter** — turns a UseCase into an Express RequestHandler
+- **Middlewares** — cross-cutting concerns (CORS, logging)
+- **Swagger UI** — documentation served automatically
+
+---
+
+## Dart version
+
+This is the TypeScript port. The original Dart version is available at:
+
+- **pub.dev**: [modular_api](https://pub.dev/packages/modular_api)
+- **GitHub**: [macss-dev/modular_api](https://github.com/macss-dev/modular_api)
+
+Both SDKs share the same architecture and API surface at v0.1.0.
+
+---
+
+## License
+
+MIT © [ccisne.dev](https://ccisne.dev)

package/dist/core/health/health_check.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Health status values.
+ *
+ * - `'pass'` — The component is healthy.
+ * - `'warn'` — The component is healthy but has a warning condition.
+ * - `'fail'` — The component is unhealthy.
+ */
+export type HealthStatus = 'pass' | 'warn' | 'fail';
+/** Compare two statuses and return the worse one. */
+export declare function worstStatus(a: HealthStatus, b: HealthStatus): HealthStatus;
+/**
+ * Result returned by a single {@link HealthCheck}.
+ */
+export declare class HealthCheckResult {
+    readonly status: HealthStatus;
+    readonly responseTime?: number;
+    readonly output?: string;
+    constructor(status: HealthStatus, options?: {
+        responseTime?: number;
+        output?: string;
+    });
+    /** Return a copy with `responseTime` set. */
+    withResponseTime(ms: number): HealthCheckResult;
+    /** Serialize to the IETF JSON structure. Only includes optional fields when defined. */
+    toJson(): Record<string, unknown>;
+}
+/**
+ * Abstract base for custom health checks.
+ *
+ * Implementors must provide `name` and `check()`.
+ * Override `timeout` to change the default 5 000 ms deadline.
+ *
+ * ```ts
+ * class DatabaseHealthCheck extends HealthCheck {
+ *   readonly name = 'database';
+ *   async check() {
+ *     await db.ping();
+ *     return new HealthCheckResult('pass');
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class HealthCheck {
+    /** Display name used as the key in the `checks` map. */
+    abstract readonly name: string;
+    /** Maximum time (ms) before the check is considered failed. Default: 5 000. */
+    get timeout(): number;
+    /** Execute the health check and return a result. */
+    abstract check(): Promise<HealthCheckResult>;
+}

package/dist/core/health/health_check.js

@@ -0,0 +1,69 @@
+"use strict";
+// ============================================================
+// core/health/health_check.ts
+// Health check types — IETF Health Check Response Format draft.
+// Mirror of health_check.dart in Dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthCheck = exports.HealthCheckResult = void 0;
+exports.worstStatus = worstStatus;
+/** Severity order for worst-status-wins aggregation. */
+const SEVERITY = {
+    pass: 0,
+    warn: 1,
+    fail: 2,
+};
+/** Compare two statuses and return the worse one. */
+function worstStatus(a, b) {
+    return SEVERITY[a] >= SEVERITY[b] ? a : b;
+}
+/**
+ * Result returned by a single {@link HealthCheck}.
+ */
+class HealthCheckResult {
+    constructor(status, options) {
+        this.status = status;
+        this.responseTime = options?.responseTime;
+        this.output = options?.output;
+    }
+    /** Return a copy with `responseTime` set. */
+    withResponseTime(ms) {
+        return new HealthCheckResult(this.status, {
+            responseTime: ms,
+            output: this.output,
+        });
+    }
+    /** Serialize to the IETF JSON structure. Only includes optional fields when defined. */
+    toJson() {
+        const json = { status: this.status };
+        if (this.responseTime !== undefined)
+            json.responseTime = this.responseTime;
+        if (this.output !== undefined)
+            json.output = this.output;
+        return json;
+    }
+}
+exports.HealthCheckResult = HealthCheckResult;
+/**
+ * Abstract base for custom health checks.
+ *
+ * Implementors must provide `name` and `check()`.
+ * Override `timeout` to change the default 5 000 ms deadline.
+ *
+ * ```ts
+ * class DatabaseHealthCheck extends HealthCheck {
+ *   readonly name = 'database';
+ *   async check() {
+ *     await db.ping();
+ *     return new HealthCheckResult('pass');
+ *   }
+ * }
+ * ```
+ */
+class HealthCheck {
+    /** Maximum time (ms) before the check is considered failed. Default: 5 000. */
+    get timeout() {
+        return 5000;
+    }
+}
+exports.HealthCheck = HealthCheck;

package/dist/core/health/health_handler.d.ts

@@ -0,0 +1,9 @@
+import type { RequestHandler } from 'express';
+import type { HealthService } from './health_service';
+/**
+ * Creates an Express request handler that responds to `GET /health`
+ * with `application/health+json` following the IETF draft.
+ *
+ * Returns 200 for pass/warn, 503 for fail.
+ */
+export declare function healthHandler(service: HealthService): RequestHandler;

package/dist/core/health/health_handler.js

@@ -0,0 +1,23 @@
+"use strict";
+// ============================================================
+// core/health/health_handler.ts
+// Express handler for GET /health — application/health+json.
+// Mirror of health_handler.dart in Dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.healthHandler = healthHandler;
+/**
+ * Creates an Express request handler that responds to `GET /health`
+ * with `application/health+json` following the IETF draft.
+ *
+ * Returns 200 for pass/warn, 503 for fail.
+ */
+function healthHandler(service) {
+    return async (_req, res) => {
+        const response = await service.evaluate();
+        res
+            .status(response.httpStatusCode)
+            .set('Content-Type', 'application/health+json')
+            .json(response.toJson());
+    };
+}

package/dist/core/health/health_service.d.ts

@@ -0,0 +1,60 @@
+import { type HealthStatus, HealthCheck, HealthCheckResult } from './health_check';
+/**
+ * Aggregated health response following the IETF Health Check Response Format.
+ *
+ * `httpStatusCode`: 200 for pass/warn, 503 for fail.
+ */
+export declare class HealthResponse {
+    readonly status: HealthStatus;
+    readonly version: string;
+    readonly releaseId: string;
+    readonly checks: Record<string, HealthCheckResult>;
+    constructor(options: {
+        status: HealthStatus;
+        version: string;
+        releaseId: string;
+        checks: Record<string, HealthCheckResult>;
+    });
+    /** HTTP status code: 200 for pass/warn, 503 for fail. */
+    get httpStatusCode(): number;
+    /** Serialize to the IETF-compliant JSON structure. */
+    toJson(): Record<string, any>;
+}
+export interface HealthServiceOptions {
+    /** API version string (e.g. '1.0.0'). */
+    version: string;
+    /**
+     * Release identifier. Defaults to `version-debug`.
+     * Override via `process.env.RELEASE_ID`.
+     */
+    releaseId?: string;
+}
+/**
+ * Service that manages and evaluates {@link HealthCheck}s.
+ *
+ * Checks are executed in parallel with per-check timeout.
+ * The overall status uses worst-status-wins aggregation: fail > warn > pass.
+ *
+ * ```ts
+ * const service = new HealthService({ version: '1.0.0' });
+ * service.addHealthCheck(new DatabaseHealthCheck());
+ * const response = await service.evaluate();
+ * ```
+ */
+export declare class HealthService {
+    readonly version: string;
+    readonly releaseId: string;
+    private readonly checks;
+    constructor(options: HealthServiceOptions);
+    /** Register a health check to be evaluated on each call to {@link evaluate}. */
+    addHealthCheck(check: HealthCheck): void;
+    /**
+     * Execute all registered checks in parallel and return an aggregated
+     * {@link HealthResponse}.
+     */
+    evaluate(): Promise<HealthResponse>;
+    /** Run a single check with timeout and timing. */
+    private runCheck;
+    /** Execute a check with its configured timeout. */
+    private withTimeout;
+}

package/dist/core/health/health_service.js

@@ -0,0 +1,132 @@
+"use strict";
+// ============================================================
+// core/health/health_service.ts
+// HealthService — evaluates checks in parallel with timeout.
+// Mirror of health_service.dart in Dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthService = exports.HealthResponse = void 0;
+const health_check_1 = require("./health_check");
+/**
+ * Aggregated health response following the IETF Health Check Response Format.
+ *
+ * `httpStatusCode`: 200 for pass/warn, 503 for fail.
+ */
+class HealthResponse {
+    constructor(options) {
+        this.status = options.status;
+        this.version = options.version;
+        this.releaseId = options.releaseId;
+        this.checks = options.checks;
+    }
+    /** HTTP status code: 200 for pass/warn, 503 for fail. */
+    get httpStatusCode() {
+        return this.status === 'fail' ? 503 : 200;
+    }
+    /** Serialize to the IETF-compliant JSON structure. */
+    toJson() {
+        const checksJson = {};
+        for (const [key, result] of Object.entries(this.checks)) {
+            checksJson[key] = result.toJson();
+        }
+        return {
+            status: this.status,
+            version: this.version,
+            releaseId: this.releaseId,
+            checks: checksJson,
+        };
+    }
+}
+exports.HealthResponse = HealthResponse;
+/**
+ * Service that manages and evaluates {@link HealthCheck}s.
+ *
+ * Checks are executed in parallel with per-check timeout.
+ * The overall status uses worst-status-wins aggregation: fail > warn > pass.
+ *
+ * ```ts
+ * const service = new HealthService({ version: '1.0.0' });
+ * service.addHealthCheck(new DatabaseHealthCheck());
+ * const response = await service.evaluate();
+ * ```
+ */
+class HealthService {
+    constructor(options) {
+        this.checks = [];
+        this.version = options.version;
+        this.releaseId = options.releaseId ?? process.env.RELEASE_ID ?? `${options.version}-debug`;
+    }
+    /** Register a health check to be evaluated on each call to {@link evaluate}. */
+    addHealthCheck(check) {
+        this.checks.push(check);
+    }
+    /**
+     * Execute all registered checks in parallel and return an aggregated
+     * {@link HealthResponse}.
+     */
+    async evaluate() {
+        if (this.checks.length === 0) {
+            return new HealthResponse({
+                status: 'pass',
+                version: this.version,
+                releaseId: this.releaseId,
+                checks: {},
+            });
+        }
+        const entries = await Promise.all(this.checks.map((c) => this.runCheck(c)));
+        const checks = {};
+        for (const [name, result] of entries) {
+            checks[name] = result;
+        }
+        // Worst-status-wins: fail > warn > pass
+        const status = Object.values(checks)
+            .map((r) => r.status)
+            .reduce(health_check_1.worstStatus);
+        return new HealthResponse({
+            status,
+            version: this.version,
+            releaseId: this.releaseId,
+            checks,
+        });
+    }
+    /** Run a single check with timeout and timing. */
+    async runCheck(check) {
+        const start = Date.now();
+        try {
+            const result = await this.withTimeout(check);
+            const elapsed = Date.now() - start;
+            return [check.name, result.withResponseTime(elapsed)];
+        }
+        catch (err) {
+            const elapsed = Date.now() - start;
+            return [
+                check.name,
+                new health_check_1.HealthCheckResult('fail', {
+                    responseTime: elapsed,
+                    output: String(err),
+                }),
+            ];
+        }
+    }
+    /** Execute a check with its configured timeout. */
+    withTimeout(check) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                resolve(new health_check_1.HealthCheckResult('fail', {
+                    output: `Health check "${check.name}" timeout after ${check.timeout}ms`,
+                }));
+            }, check.timeout);
+            check
+                .check()
+                .then((result) => {
+                clearTimeout(timer);
+                resolve(result);
+            })
+                .catch((err) => {
+                clearTimeout(timer);
+                reject(err);
+            });
+        });
+    }
+}
+exports.HealthService = HealthService;

package/dist/core/metrics/metric_registry.d.ts

@@ -0,0 +1,32 @@
+import { Registry, Counter, Gauge, Histogram, type CounterConfiguration, type GaugeConfiguration, type HistogramConfiguration } from 'prom-client';
+/**
+ * Internal registry wrapping prom-client's `Registry`.
+ *
+ * On construction, registers `process_start_time_seconds` as a gauge
+ * set to the current epoch in seconds.
+ */
+export declare class MetricRegistry {
+    readonly registry: Registry;
+    private readonly names;
+    constructor();
+    createCounter<T extends string = string>(config: Pick<CounterConfiguration<T>, 'name' | 'help' | 'labelNames'>): Counter<T>;
+    createGauge<T extends string = string>(config: Pick<GaugeConfiguration<T>, 'name' | 'help' | 'labelNames'>): Gauge<T>;
+    createHistogram<T extends string = string>(config: Pick<HistogramConfiguration<T>, 'name' | 'help' | 'labelNames' | 'buckets'>): Histogram<T>;
+    /** Serializes all metrics to Prometheus text exposition format. */
+    serialize(): Promise<string>;
+    /** Content type for the Prometheus text format. */
+    get contentType(): string;
+    private assertUnique;
+}
+/**
+ * Public API for users to register custom metrics.
+ * Validates names and rejects reserved prefixes before delegating.
+ */
+export declare class MetricsRegistrar {
+    private readonly registry;
+    constructor(registry: MetricRegistry);
+    createCounter<T extends string = string>(config: Pick<CounterConfiguration<T>, 'name' | 'help' | 'labelNames'>): Counter<T>;
+    createGauge<T extends string = string>(config: Pick<GaugeConfiguration<T>, 'name' | 'help' | 'labelNames'>): Gauge<T>;
+    createHistogram<T extends string = string>(config: Pick<HistogramConfiguration<T>, 'name' | 'help' | 'labelNames' | 'buckets'>): Histogram<T>;
+    private validate;
+}

package/dist/core/metrics/metric_registry.js

@@ -0,0 +1,104 @@
+"use strict";
+// ============================================================
+// core/metrics/metric_registry.ts
+// Wraps prom-client with a two-layer API:
+//   MetricRegistry — internal, manages prom-client Registry
+//   MetricsRegistrar — public, validates names before delegating
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsRegistrar = exports.MetricRegistry = void 0;
+const prom_client_1 = require("prom-client");
+/** Prometheus metric name regex. */
+const VALID_NAME = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+function assertValidName(name) {
+    if (!name || !VALID_NAME.test(name)) {
+        throw new Error(`Invalid metric name "${name}": must match [a-zA-Z_:][a-zA-Z0-9_:]*`);
+    }
+}
+// ── MetricRegistry (internal) ─────────────────────────────────────────
+/**
+ * Internal registry wrapping prom-client's `Registry`.
+ *
+ * On construction, registers `process_start_time_seconds` as a gauge
+ * set to the current epoch in seconds.
+ */
+class MetricRegistry {
+    constructor() {
+        this.names = new Set();
+        this.registry = new prom_client_1.Registry();
+        // Auto-register process_start_time_seconds.
+        const startTime = this.createGauge({
+            name: 'process_start_time_seconds',
+            help: 'Start time of the process since unix epoch in seconds.',
+        });
+        startTime.set(Date.now() / 1000);
+    }
+    createCounter(config) {
+        this.assertUnique(config.name);
+        const counter = new prom_client_1.Counter({
+            ...config,
+            registers: [this.registry],
+        });
+        return counter;
+    }
+    createGauge(config) {
+        this.assertUnique(config.name);
+        const gauge = new prom_client_1.Gauge({
+            ...config,
+            registers: [this.registry],
+        });
+        return gauge;
+    }
+    createHistogram(config) {
+        this.assertUnique(config.name);
+        const histogram = new prom_client_1.Histogram({
+            ...config,
+            registers: [this.registry],
+        });
+        return histogram;
+    }
+    /** Serializes all metrics to Prometheus text exposition format. */
+    async serialize() {
+        return this.registry.metrics();
+    }
+    /** Content type for the Prometheus text format. */
+    get contentType() {
+        return this.registry.contentType;
+    }
+    assertUnique(name) {
+        if (this.names.has(name)) {
+            throw new Error(`Metric "${name}" is already registered.`);
+        }
+        this.names.add(name);
+    }
+}
+exports.MetricRegistry = MetricRegistry;
+// ── MetricsRegistrar (public) ─────────────────────────────────────────
+/**
+ * Public API for users to register custom metrics.
+ * Validates names and rejects reserved prefixes before delegating.
+ */
+class MetricsRegistrar {
+    constructor(registry) {
+        this.registry = registry;
+    }
+    createCounter(config) {
+        this.validate(config.name);
+        return this.registry.createCounter(config);
+    }
+    createGauge(config) {
+        this.validate(config.name);
+        return this.registry.createGauge(config);
+    }
+    createHistogram(config) {
+        this.validate(config.name);
+        return this.registry.createHistogram(config);
+    }
+    validate(name) {
+        assertValidName(name);
+        if (name.startsWith('__')) {
+            throw new Error(`Metric name "${name}" uses reserved prefix "__".`);
+        }
+    }
+}
+exports.MetricsRegistrar = MetricsRegistrar;

package/dist/core/metrics/metrics_middleware.d.ts

@@ -0,0 +1,24 @@
+import type { RequestHandler } from 'express';
+import type { Counter, Gauge, Histogram } from 'prom-client';
+import type { MetricRegistry } from './metric_registry';
+export interface MetricsMiddlewareOptions {
+    requestsTotal: Counter<'method' | 'route' | 'status_code'>;
+    requestsInFlight: Gauge;
+    requestDuration: Histogram<'method' | 'route' | 'status_code'>;
+    excludedRoutes: string[];
+    registeredPaths: string[];
+}
+/**
+ * Creates an Express middleware that instruments HTTP requests.
+ *
+ * Records:
+ * - `requestsTotal` — counter with labels: method, route, status_code
+ * - `requestsInFlight` — gauge (inc on entry, dec on finish)
+ * - `requestDuration` — histogram with labels: method, route, status_code
+ */
+export declare function metricsMiddleware(opts: MetricsMiddlewareOptions): RequestHandler;
+/**
+ * Creates an Express handler that returns Prometheus metrics.
+ * Always returns HTTP 200 with `text/plain; version=0.0.4; charset=utf-8`.
+ */
+export declare function metricsHandler(registry: MetricRegistry): RequestHandler;

package/dist/core/metrics/metrics_middleware.js

@@ -0,0 +1,51 @@
+"use strict";
+// ============================================================
+// core/metrics/metrics_middleware.ts
+// Express middleware + handler for Prometheus metrics.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metricsMiddleware = metricsMiddleware;
+exports.metricsHandler = metricsHandler;
+/**
+ * Creates an Express middleware that instruments HTTP requests.
+ *
+ * Records:
+ * - `requestsTotal` — counter with labels: method, route, status_code
+ * - `requestsInFlight` — gauge (inc on entry, dec on finish)
+ * - `requestDuration` — histogram with labels: method, route, status_code
+ */
+function metricsMiddleware(opts) {
+    const excludedSet = new Set(opts.excludedRoutes);
+    const registeredSet = new Set(opts.registeredPaths);
+    return (req, res, next) => {
+        const path = req.path;
+        // Skip excluded routes.
+        if (excludedSet.has(path)) {
+            return next();
+        }
+        const method = req.method.toUpperCase();
+        const route = registeredSet.has(path) ? path : 'UNMATCHED';
+        opts.requestsInFlight.inc();
+        const startTime = process.hrtime.bigint();
+        res.on('finish', () => {
+            opts.requestsInFlight.dec();
+            const durationNs = Number(process.hrtime.bigint() - startTime);
+            const durationSecs = durationNs / 1e9;
+            const statusCode = res.statusCode.toString();
+            const labels = { method, route, status_code: statusCode };
+            opts.requestsTotal.inc(labels);
+            opts.requestDuration.observe(labels, durationSecs);
+        });
+        next();
+    };
+}
+/**
+ * Creates an Express handler that returns Prometheus metrics.
+ * Always returns HTTP 200 with `text/plain; version=0.0.4; charset=utf-8`.
+ */
+function metricsHandler(registry) {
+    return async (_req, res) => {
+        const body = await registry.serialize();
+        res.status(200).set('Content-Type', 'text/plain; version=0.0.4; charset=utf-8').send(body);
+    };
+}

package/dist/core/modular_api.d.ts

@@ -1,10 +1,25 @@
 import { type RequestHandler } from 'express';
 import { ModuleBuilder } from './module_builder';
+import type { HealthCheck } from './health/health_check';
+import { MetricsRegistrar } from './metrics/metric_registry';
 export interface ModularApiOptions {
     /** Base path prefix for all module routes. Default: '/api' */
     basePath?: string;
     /** API title shown in Swagger UI. Default: 'API' */
     title?: string;
+    /** API version string (e.g. '1.0.0'). Used in health check response. Default: '0.0.0' */
+    version?: string;
+    /**
+     * Release identifier. Defaults to `version-debug`.
+     * Override via `process.env.RELEASE_ID`.
+     */
+    releaseId?: string;
+    /** Opt-in Prometheus metrics endpoint. Default: false */
+    metricsEnabled?: boolean;
+    /** Path for the metrics endpoint. Default: '/metrics' */
+    metricsPath?: string;
+    /** Routes excluded from instrumentation. Default: ['/metrics', '/health', '/docs'] */
+    excludedMetricsRoutes?: string[];
 }
 /**
  * Main entry point for modular_api.
@@ -24,7 +39,7 @@ export interface ModularApiOptions {
  * ```
  *
  * Auto-mounted endpoints:
- *   GET /health  → 200 "ok"
+ *   GET /health  → 200/503 application/health+json (IETF draft)
  *   GET /docs    → Swagger UI
  */
 export declare class ModularApi {
@@ -33,7 +48,27 @@ export declare class ModularApi {
     private readonly basePath;
     private readonly title;
     private readonly middlewares;
+    private readonly healthService;
+    private readonly metricsEnabled;
+    private readonly metricsPath;
+    private readonly excludedMetricsRoutes;
+    private readonly metricRegistry?;
+    private readonly _metricsRegistrar?;
+    private readonly httpRequestsTotal?;
+    private readonly httpRequestsInFlight?;
+    private readonly httpRequestDuration?;
+    /** Public accessor for custom-metric registration. Undefined when metrics are disabled. */
+    get metrics(): MetricsRegistrar | undefined;
     constructor(options?: ModularApiOptions);
+    /**
+     * Register a {@link HealthCheck} to be evaluated on `GET /health`.
+     * Returns `this` for method chaining.
+     *
+     * ```ts
+     * api.addHealthCheck(new DatabaseHealthCheck());
+     * ```
+     */
+    addHealthCheck(check: HealthCheck): this;
     /**
      * Registers a group of use cases under a named module.
      * Returns `this` for method chaining.

package/dist/core/modular_api.js

@@ -13,6 +13,11 @@ const express_1 = __importDefault(require("express"));
 const module_builder_1 = require("./module_builder");
 const openapi_1 = require("../openapi/openapi");
 const swagger_ui_express_1 = __importDefault(require("swagger-ui-express"));
+const health_service_1 = require("./health/health_service");
+const health_handler_1 = require("./health/health_handler");
+const metric_registry_1 = require("./metrics/metric_registry");
+const metrics_middleware_1 = require("./metrics/metrics_middleware");
+const registry_1 = require("./registry");
 /**
  * Main entry point for modular_api.
  *
@@ -31,18 +36,59 @@ const swagger_ui_express_1 = __importDefault(require("swagger-ui-express"));
  * ```
  *
  * Auto-mounted endpoints:
- *   GET /health  → 200 "ok"
+ *   GET /health  → 200/503 application/health+json (IETF draft)
  *   GET /docs    → Swagger UI
  */
 class ModularApi {
+    /** Public accessor for custom-metric registration. Undefined when metrics are disabled. */
+    get metrics() {
+        return this._metricsRegistrar;
+    }
     constructor(options = {}) {
         this.middlewares = [];
         this.basePath = options.basePath ?? '/api';
-        this.title = options.title ?? 'API';
+        this.title = options.title ?? 'Modular API';
+        this.healthService = new health_service_1.HealthService({
+            version: options.version ?? 'x.y.z',
+            releaseId: options.releaseId,
+        });
+        // Metrics setup
+        this.metricsEnabled = options.metricsEnabled ?? false;
+        this.metricsPath = options.metricsPath ?? '/metrics';
+        this.excludedMetricsRoutes = options.excludedMetricsRoutes ?? ['/metrics', '/health', '/docs'];
+        if (this.metricsEnabled) {
+            this.metricRegistry = new metric_registry_1.MetricRegistry();
+            this._metricsRegistrar = new metric_registry_1.MetricsRegistrar(this.metricRegistry);
+            this.httpRequestsTotal = this.metricRegistry.createCounter({
+                name: 'http_requests_total',
+                help: 'Total number of HTTP requests.',
+                labelNames: ['method', 'route', 'status_code'],
+            });
+            this.httpRequestsInFlight = this.metricRegistry.createGauge({
+                name: 'http_requests_in_flight',
+                help: 'Number of HTTP requests currently being processed.',
+            });
+            this.httpRequestDuration = this.metricRegistry.createHistogram({
+                name: 'http_request_duration_seconds',
+                help: 'HTTP request duration in seconds.',
+                labelNames: ['method', 'route', 'status_code'],
+            });
+        }
         this.app = (0, express_1.default)();
         this.app.use(express_1.default.json());
         this.rootRouter = express_1.default.Router();
-        this.app.use(this.rootRouter);
+    }
+    /**
+     * Register a {@link HealthCheck} to be evaluated on `GET /health`.
+     * Returns `this` for method chaining.
+     *
+     * ```ts
+     * api.addHealthCheck(new DatabaseHealthCheck());
+     * ```
+     */
+    addHealthCheck(check) {
+        this.healthService.addHealthCheck(check);
+        return this;
     }
     /**
      * Registers a group of use cases under a named module.
@@ -88,18 +134,42 @@ class ModularApi {
     serve(options) {
         const { port, host = '0.0.0.0' } = options;
         return new Promise((resolve) => {
+            // Metrics middleware FIRST — before user middlewares & routes.
+            // Created here so registeredPaths is populated from apiRegistry.
+            if (this.metricsEnabled &&
+                this.httpRequestsTotal &&
+                this.httpRequestsInFlight &&
+                this.httpRequestDuration) {
+                const registeredPaths = registry_1.apiRegistry.routes.map((r) => r.path);
+                this.app.use((0, metrics_middleware_1.metricsMiddleware)({
+                    requestsTotal: this.httpRequestsTotal,
+                    requestsInFlight: this.httpRequestsInFlight,
+                    requestDuration: this.httpRequestDuration,
+                    excludedRoutes: this.excludedMetricsRoutes,
+                    registeredPaths,
+                }));
+            }
             // Register middlewares before routes
             for (const mw of this.middlewares) {
                 this.app.use(mw);
             }
-            // Health endpoint
-            this.app.get('/health', (_req, res) => res.status(200).send('ok'));
+            // Metrics endpoint (before rootRouter — its own handler).
+            if (this.metricsEnabled && this.metricRegistry) {
+                this.app.get(this.metricsPath, (0, metrics_middleware_1.metricsHandler)(this.metricRegistry));
+            }
+            // Health endpoint — IETF Health Check Response Format
+            this.app.get('/health', (0, health_handler_1.healthHandler)(this.healthService));
+            // Module use case routes.
+            this.app.use(this.rootRouter);
             // Swagger / OpenAPI docs
             const spec = (0, openapi_1.buildOpenApiSpec)({ title: this.title, port });
             this.app.use('/docs', swagger_ui_express_1.default.serve, swagger_ui_express_1.default.setup(spec));
             const server = this.app.listen(port, host, () => {
                 console.log(`Docs  → http://localhost:${port}/docs`);
                 console.log(`Health → http://localhost:${port}/health`);
+                if (this.metricsEnabled) {
+                    console.log(`Metrics → http://localhost:${port}${this.metricsPath}`);
+                }
                 resolve(server);
             });
         });

package/dist/core/usecase_handler.js

@@ -33,7 +33,7 @@ function useCaseHandler(factory) {
             // 1. Extract payload
             const data = req.method.toUpperCase() === 'GET' || req.method.toUpperCase() === 'DELETE'
                 ? { ...req.query, ...req.params }
-                : req.body ?? {};
+                : (req.body ?? {});
             // 2. Build use case
             const useCase = factory(data);
             // 3. Validate

package/dist/index.d.ts

@@ -9,3 +9,11 @@ export { useCaseTestHandler } from './core/usecase_test_handler';
 export type { TestResponse } from './core/usecase_test_handler';
 export { cors } from './middlewares/cors';
 export type { CorsOptions } from './middlewares/cors';
+export { HealthCheck, HealthCheckResult } from './core/health/health_check';
+export type { HealthStatus } from './core/health/health_check';
+export { HealthService, HealthResponse } from './core/health/health_service';
+export type { HealthServiceOptions } from './core/health/health_service';
+export { healthHandler } from './core/health/health_handler';
+export { MetricRegistry, MetricsRegistrar } from './core/metrics/metric_registry';
+export { metricsMiddleware, metricsHandler } from './core/metrics/metrics_middleware';
+export type { MetricsMiddlewareOptions } from './core/metrics/metrics_middleware';

package/dist/index.js

@@ -5,7 +5,7 @@
 //   import { ModularApi, UseCase, Input, Output } from 'modular_api'
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cors = exports.useCaseTestHandler = exports.ModuleBuilder = exports.ModularApi = exports.UseCaseException = exports.UseCase = exports.Output = exports.Input = void 0;
+exports.metricsHandler = exports.metricsMiddleware = exports.MetricsRegistrar = exports.MetricRegistry = exports.healthHandler = exports.HealthResponse = exports.HealthService = exports.HealthCheckResult = exports.HealthCheck = exports.cors = exports.useCaseTestHandler = exports.ModuleBuilder = exports.ModularApi = exports.UseCaseException = exports.UseCase = exports.Output = exports.Input = void 0;
 // Core abstractions
 var usecase_1 = require("./core/usecase");
 Object.defineProperty(exports, "Input", { enumerable: true, get: function () { return usecase_1.Input; } });
@@ -26,3 +26,19 @@ Object.defineProperty(exports, "useCaseTestHandler", { enumerable: true, get: fu
 // Middlewares
 var cors_1 = require("./middlewares/cors");
 Object.defineProperty(exports, "cors", { enumerable: true, get: function () { return cors_1.cors; } });
+// Health — IETF Health Check Response Format
+var health_check_1 = require("./core/health/health_check");
+Object.defineProperty(exports, "HealthCheck", { enumerable: true, get: function () { return health_check_1.HealthCheck; } });
+Object.defineProperty(exports, "HealthCheckResult", { enumerable: true, get: function () { return health_check_1.HealthCheckResult; } });
+var health_service_1 = require("./core/health/health_service");
+Object.defineProperty(exports, "HealthService", { enumerable: true, get: function () { return health_service_1.HealthService; } });
+Object.defineProperty(exports, "HealthResponse", { enumerable: true, get: function () { return health_service_1.HealthResponse; } });
+var health_handler_1 = require("./core/health/health_handler");
+Object.defineProperty(exports, "healthHandler", { enumerable: true, get: function () { return health_handler_1.healthHandler; } });
+// Metrics — Prometheus /metrics endpoint
+var metric_registry_1 = require("./core/metrics/metric_registry");
+Object.defineProperty(exports, "MetricRegistry", { enumerable: true, get: function () { return metric_registry_1.MetricRegistry; } });
+Object.defineProperty(exports, "MetricsRegistrar", { enumerable: true, get: function () { return metric_registry_1.MetricsRegistrar; } });
+var metrics_middleware_1 = require("./core/metrics/metrics_middleware");
+Object.defineProperty(exports, "metricsMiddleware", { enumerable: true, get: function () { return metrics_middleware_1.metricsMiddleware; } });
+Object.defineProperty(exports, "metricsHandler", { enumerable: true, get: function () { return metrics_middleware_1.metricsHandler; } });

package/dist/openapi/openapi.js

@@ -19,9 +19,7 @@ const registry_1 = require("../core/registry");
  */
 function buildOpenApiSpec(options) {
     const { title, port, version = '0.1.0', description = 'Auto-generated by modular-api', servers, } = options;
-    const defaultServers = [
-        { url: `http://localhost:${port}`, description: 'Local' },
-    ];
+    const defaultServers = [{ url: `http://localhost:${port}`, description: 'Local' }];
     const paths = {};
     for (const route of registry_1.apiRegistry.routes) {
         const method = route.method.toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macss/modular-api",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Use-case-centric toolkit for building modular APIs with Express. Define UseCase classes (input → validate → execute → output), connect them to HTTP routes, and expose Swagger/OpenAPI documentation automatically.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,9 @@
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
     "dev": "ts-node src/index.ts",
-    "test": "echo \"No tests yet\" && exit 0"
+    "test": "vitest run",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "keywords": [
     "api",
@@ -25,13 +27,18 @@
   "license": "MIT",
   "dependencies": {
     "express": "^4.22.1",
+    "prom-client": "^15.1.3",
     "swagger-ui-express": "^5.0.1"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
     "@types/node": "^22.19.11",
+    "@types/supertest": "^6.0.3",
     "@types/swagger-ui-express": "^4.1.8",
+    "prettier": "^3.8.1",
+    "supertest": "^7.2.2",
     "ts-node": "^10.9.2",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   }
 }