@macss/modular-api 0.1.0 → 0.3.0

package/README.md

@@ -1,131 +1,122 @@
-# 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.
+
+> Also available in **Dart**: [modular_api](https://pub.dev/packages/modular_api)
+
+---
+
+## 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)
+- Structured JSON logging — Loki/Grafana compatible, [request-scoped with trace_id](doc/logger_guide.md)
+- All endpoints default to `POST` (configurable per use case)
+- Full TypeScript declarations (`.d.ts`) included
+
+---
+
+## Installation
+
+```bash
+npm install @macss/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
+
+---
+
+## 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/logger/logger.d.ts

@@ -0,0 +1,79 @@
+/**
+ * RFC 5424 log levels in descending severity order.
+ *
+ * Filtering rule: if configured `logLevel = X`, only messages with
+ * `value <= X` are emitted. Higher values produce total silence.
+ */
+export declare enum LogLevel {
+    emergency = 0,// system unusable
+    alert = 1,// immediate action required
+    critical = 2,// critical condition
+    error = 3,// operation error, 5xx
+    warning = 4,// abnormal condition, 4xx
+    notice = 5,// normal but significant
+    info = 6,// normal flow, 2xx/3xx
+    debug = 7
+}
+/**
+ * Public logger interface exposed to UseCases.
+ *
+ * Each method corresponds to an RFC 5424 severity level.
+ * `fields` is an optional map of structured data attached to the log entry.
+ */
+export interface ModularLogger {
+    /** Request-scoped trace ID for correlation. */
+    readonly traceId: string;
+    emergency(msg: string, fields?: Record<string, unknown>): void;
+    alert(msg: string, fields?: Record<string, unknown>): void;
+    critical(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+    warning(msg: string, fields?: Record<string, unknown>): void;
+    notice(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    debug(msg: string, fields?: Record<string, unknown>): void;
+}
+/** Function signature for the output sink — defaults to `console.log`. */
+export type WriteFn = (line: string) => void;
+/**
+ * Per-request logger that carries `traceId` and respects `logLevel` filtering.
+ *
+ * Created by `loggingMiddleware` for each incoming HTTP request and injected
+ * into the UseCase via the `logger` property.
+ *
+ * Accepts an optional `writeFn` for output — defaults to `console.log`.
+ * In tests, pass a capturing function to inspect output without side-effects.
+ */
+export declare class RequestScopedLogger implements ModularLogger {
+    readonly traceId: string;
+    readonly logLevel: LogLevel;
+    readonly serviceName: string;
+    private readonly writeFn;
+    constructor(traceId: string, logLevel: LogLevel, serviceName: string, writeFn?: WriteFn);
+    emergency(msg: string, fields?: Record<string, unknown>): void;
+    alert(msg: string, fields?: Record<string, unknown>): void;
+    critical(msg: string, fields?: Record<string, unknown>): void;
+    error(msg: string, fields?: Record<string, unknown>): void;
+    warning(msg: string, fields?: Record<string, unknown>): void;
+    notice(msg: string, fields?: Record<string, unknown>): void;
+    info(msg: string, fields?: Record<string, unknown>): void;
+    debug(msg: string, fields?: Record<string, unknown>): void;
+    /** Emits a "request received" log at `info` level. */
+    logRequest(opts: {
+        method: string;
+        route: string;
+    }): void;
+    /** Emits a "request completed" log at the level determined by `statusCode`. */
+    logResponse(opts: {
+        method: string;
+        route: string;
+        statusCode: number;
+        durationMs: number;
+    }): void;
+    /** Emits an "unhandled exception" log at `error` level. No stack trace. */
+    logUnhandledException(opts: {
+        route: string;
+    }): void;
+    private log;
+    /** Maps HTTP status code → RFC 5424 log level. */
+    static levelForStatus(status: number): LogLevel;
+}