@macss/modular-api 0.2.0 → 0.3.0

package/README.md

@@ -3,7 +3,7 @@
 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)
+> Also available in **Dart**: [modular_api](https://pub.dev/packages/modular_api)
 
 ---
 
@@ -54,6 +54,7 @@ See `example/example.ts` for the full implementation including Input, Output, Us
 - 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
 
@@ -62,7 +63,7 @@ See `example/example.ts` for the full implementation including Input, Output, Us
 ## Installation
 
 ```bash
-npm install modular_api
+npm install @macss/modular-api
 ```
 
 ---
@@ -116,17 +117,6 @@ HTTP Request → ModularApi → Module → UseCase → Business Logic → Output
 
 ---
 
-## 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/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;
+}

package/dist/core/logger/logger.js

@@ -0,0 +1,132 @@
+"use strict";
+// ============================================================
+// core/logger/logger.ts
+// LogLevel enum, ModularLogger interface, RequestScopedLogger.
+// Mirror of logger.dart — RFC 5424, JSON to stdout, zero deps.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestScopedLogger = exports.LogLevel = void 0;
+/**
+ * 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.
+ */
+var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["emergency"] = 0] = "emergency";
+    LogLevel[LogLevel["alert"] = 1] = "alert";
+    LogLevel[LogLevel["critical"] = 2] = "critical";
+    LogLevel[LogLevel["error"] = 3] = "error";
+    LogLevel[LogLevel["warning"] = 4] = "warning";
+    LogLevel[LogLevel["notice"] = 5] = "notice";
+    LogLevel[LogLevel["info"] = 6] = "info";
+    LogLevel[LogLevel["debug"] = 7] = "debug";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+/** Human-readable name for each LogLevel value. */
+const LEVEL_NAME = {
+    [LogLevel.emergency]: 'emergency',
+    [LogLevel.alert]: 'alert',
+    [LogLevel.critical]: 'critical',
+    [LogLevel.error]: 'error',
+    [LogLevel.warning]: 'warning',
+    [LogLevel.notice]: 'notice',
+    [LogLevel.info]: 'info',
+    [LogLevel.debug]: 'debug',
+};
+/**
+ * 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.
+ */
+class RequestScopedLogger {
+    constructor(traceId, logLevel, serviceName, writeFn = (line) => process.stdout.write(line + '\n')) {
+        this.traceId = traceId;
+        this.logLevel = logLevel;
+        this.serviceName = serviceName;
+        this.writeFn = writeFn;
+    }
+    // ─── Public API (8 RFC 5424 levels) ──────────────────────────────
+    emergency(msg, fields) {
+        this.log(LogLevel.emergency, msg, { fields });
+    }
+    alert(msg, fields) {
+        this.log(LogLevel.alert, msg, { fields });
+    }
+    critical(msg, fields) {
+        this.log(LogLevel.critical, msg, { fields });
+    }
+    error(msg, fields) {
+        this.log(LogLevel.error, msg, { fields });
+    }
+    warning(msg, fields) {
+        this.log(LogLevel.warning, msg, { fields });
+    }
+    notice(msg, fields) {
+        this.log(LogLevel.notice, msg, { fields });
+    }
+    info(msg, fields) {
+        this.log(LogLevel.info, msg, { fields });
+    }
+    debug(msg, fields) {
+        this.log(LogLevel.debug, msg, { fields });
+    }
+    // ─── Framework-internal: request/response logging ────────────────
+    /** Emits a "request received" log at `info` level. */
+    logRequest(opts) {
+        this.log(LogLevel.info, 'request received', {
+            extra: { method: opts.method, route: opts.route },
+        });
+    }
+    /** Emits a "request completed" log at the level determined by `statusCode`. */
+    logResponse(opts) {
+        this.log(RequestScopedLogger.levelForStatus(opts.statusCode), 'request completed', {
+            extra: {
+                method: opts.method,
+                route: opts.route,
+                status: opts.statusCode,
+                duration_ms: opts.durationMs,
+            },
+        });
+    }
+    /** Emits an "unhandled exception" log at `error` level. No stack trace. */
+    logUnhandledException(opts) {
+        this.log(LogLevel.error, 'unhandled exception', {
+            extra: { route: opts.route, status: 500 },
+        });
+    }
+    // ─── Internal ────────────────────────────────────────────────────
+    log(level, msg, opts = {}) {
+        // Filtering: only emit if the message level <= configured logLevel.
+        if (level > this.logLevel)
+            return;
+        const entry = {
+            ts: Date.now() / 1000,
+            level: LEVEL_NAME[level],
+            severity: level,
+            msg,
+            service: this.serviceName,
+            trace_id: this.traceId,
+        };
+        if (opts.extra)
+            Object.assign(entry, opts.extra);
+        if (opts.fields)
+            entry['fields'] = opts.fields;
+        this.writeFn(JSON.stringify(entry));
+    }
+    /** Maps HTTP status code → RFC 5424 log level. */
+    static levelForStatus(status) {
+        if (status >= 500)
+            return LogLevel.error;
+        if (status >= 400)
+            return LogLevel.warning;
+        if (status >= 200 && status < 400)
+            return LogLevel.info;
+        return LogLevel.notice; // 1xx
+    }
+}
+exports.RequestScopedLogger = RequestScopedLogger;

package/dist/core/logger/logging_middleware.d.ts

@@ -0,0 +1,25 @@
+import type { RequestHandler } from 'express';
+import { LogLevel } from './logger';
+import type { WriteFn } from './logger';
+/** Key used in `res.locals` to propagate the logger to downstream handlers. */
+export declare const LOGGER_LOCALS_KEY = "modularLogger";
+export interface LoggingMiddlewareOptions {
+    logLevel: LogLevel;
+    serviceName: string;
+    excludedRoutes?: string[];
+    /** Override output for testing. Defaults to stdout. */
+    writeFn?: WriteFn;
+}
+/**
+ * Creates an Express middleware that:
+ *
+ * 1. Reads or generates a `trace_id` (from `X-Request-ID` header).
+ * 2. Creates a {@link RequestScopedLogger} scoped to the current request.
+ * 3. Emits a `"request received"` log at `info` level.
+ * 4. Passes the logger via `res.locals` for downstream handlers.
+ * 5. Emits a `"request completed"` log (level based on status code).
+ * 6. Returns the `X-Request-ID` header in the response.
+ *
+ * Requests whose path matches `excludedRoutes` are passed through silently.
+ */
+export declare function loggingMiddleware(opts: LoggingMiddlewareOptions): RequestHandler;

package/dist/core/logger/logging_middleware.js

@@ -0,0 +1,60 @@
+"use strict";
+// ============================================================
+// core/logger/logging_middleware.ts
+// Express middleware — trace_id, structured JSON logs.
+// Mirror of logging_middleware.dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOGGER_LOCALS_KEY = void 0;
+exports.loggingMiddleware = loggingMiddleware;
+const node_crypto_1 = require("node:crypto");
+const logger_1 = require("./logger");
+/** Key used in `res.locals` to propagate the logger to downstream handlers. */
+exports.LOGGER_LOCALS_KEY = 'modularLogger';
+/**
+ * Creates an Express middleware that:
+ *
+ * 1. Reads or generates a `trace_id` (from `X-Request-ID` header).
+ * 2. Creates a {@link RequestScopedLogger} scoped to the current request.
+ * 3. Emits a `"request received"` log at `info` level.
+ * 4. Passes the logger via `res.locals` for downstream handlers.
+ * 5. Emits a `"request completed"` log (level based on status code).
+ * 6. Returns the `X-Request-ID` header in the response.
+ *
+ * Requests whose path matches `excludedRoutes` are passed through silently.
+ */
+function loggingMiddleware(opts) {
+    const excludedSet = new Set(opts.excludedRoutes ?? []);
+    return (req, res, next) => {
+        const path = req.path;
+        // Skip excluded routes (health, metrics, docs).
+        if (excludedSet.has(path)) {
+            return next();
+        }
+        // 1. Resolve trace_id
+        const headerValue = req.headers['x-request-id'];
+        const traceId = typeof headerValue === 'string' && headerValue.length > 0 ? headerValue : (0, node_crypto_1.randomUUID)();
+        // 2. Create per-request logger
+        const logger = new logger_1.RequestScopedLogger(traceId, opts.logLevel, opts.serviceName, opts.writeFn);
+        const method = req.method.toUpperCase();
+        const route = path;
+        // 3. "request received"
+        logger.logRequest({ method, route });
+        // 4. Propagate logger via res.locals
+        res.locals[exports.LOGGER_LOCALS_KEY] = logger;
+        // 5. Attach X-Request-ID to response
+        res.setHeader('X-Request-ID', traceId);
+        // 6. Capture timing and emit response log on finish
+        const startNs = process.hrtime.bigint();
+        res.on('finish', () => {
+            const durationMs = Number(process.hrtime.bigint() - startNs) / 1e6;
+            logger.logResponse({
+                method,
+                route,
+                statusCode: res.statusCode,
+                durationMs,
+            });
+        });
+        next();
+    };
+}

package/dist/core/modular_api.d.ts

@@ -2,6 +2,7 @@ import { type RequestHandler } from 'express';
 import { ModuleBuilder } from './module_builder';
 import type { HealthCheck } from './health/health_check';
 import { MetricsRegistrar } from './metrics/metric_registry';
+import { LogLevel } from './logger/logger';
 export interface ModularApiOptions {
     /** Base path prefix for all module routes. Default: '/api' */
     basePath?: string;
@@ -20,6 +21,11 @@ export interface ModularApiOptions {
     metricsPath?: string;
     /** Routes excluded from instrumentation. Default: ['/metrics', '/health', '/docs'] */
     excludedMetricsRoutes?: string[];
+    /**
+     * Minimum log level for the structured JSON logger.
+     * Default: LogLevel.info (emits emergency..info, suppresses debug).
+     */
+    logLevel?: LogLevel;
 }
 /**
  * Main entry point for modular_api.
@@ -57,6 +63,7 @@ export declare class ModularApi {
     private readonly httpRequestsTotal?;
     private readonly httpRequestsInFlight?;
     private readonly httpRequestDuration?;
+    private readonly logLevel;
     /** Public accessor for custom-metric registration. Undefined when metrics are disabled. */
     get metrics(): MetricsRegistrar | undefined;
     constructor(options?: ModularApiOptions);

package/dist/core/modular_api.js

@@ -17,6 +17,8 @@ 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 logging_middleware_1 = require("./logger/logging_middleware");
+const logger_1 = require("./logger/logger");
 const registry_1 = require("./registry");
 /**
  * Main entry point for modular_api.
@@ -56,6 +58,8 @@ class ModularApi {
         this.metricsEnabled = options.metricsEnabled ?? false;
         this.metricsPath = options.metricsPath ?? '/metrics';
         this.excludedMetricsRoutes = options.excludedMetricsRoutes ?? ['/metrics', '/health', '/docs'];
+        // Logging
+        this.logLevel = options.logLevel ?? logger_1.LogLevel.info;
         if (this.metricsEnabled) {
             this.metricRegistry = new metric_registry_1.MetricRegistry();
             this._metricsRegistrar = new metric_registry_1.MetricsRegistrar(this.metricRegistry);
@@ -134,7 +138,14 @@ class ModularApi {
     serve(options) {
         const { port, host = '0.0.0.0' } = options;
         return new Promise((resolve) => {
-            // Metrics middleware FIRST — before user middlewares & routes.
+            // Logging middleware FIRST — trace_id + structured JSON logs.
+            const excludedLogRoutes = ['/health', this.metricsPath, '/docs', '/docs/'];
+            this.app.use((0, logging_middleware_1.loggingMiddleware)({
+                logLevel: this.logLevel,
+                serviceName: this.title,
+                excludedRoutes: excludedLogRoutes,
+            }));
+            // Metrics middleware — before user middlewares & routes.
             // Created here so registeredPaths is populated from apiRegistry.
             if (this.metricsEnabled &&
                 this.httpRequestsTotal &&

package/dist/core/usecase.d.ts

@@ -1,3 +1,4 @@
+import type { ModularLogger } from './logger/logger';
 /**
  * **Contract** — use `implements Input`.
  *
@@ -94,6 +95,12 @@ export declare abstract class UseCase<I extends Input, O extends Output> {
     abstract readonly input: I;
     /** Output DTO — set in execute(). */
     abstract output: O;
+    /**
+     * Request-scoped logger injected by the framework's logging middleware.
+     * Available inside `execute()`. Undefined when running without middleware
+     * or in tests that don't provide one.
+     */
+    logger?: ModularLogger;
     /**
      * Synchronous validation.
      * Return a human-readable error string to abort execution with HTTP 400.

package/dist/core/usecase_handler.js

@@ -7,6 +7,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useCaseHandler = useCaseHandler;
 const use_case_exception_1 = require("./use_case_exception");
+const logging_middleware_1 = require("./logger/logging_middleware");
 const JSON_HEADERS = { 'Content-Type': 'application/json; charset=utf-8' };
 /**
  * Wraps any UseCase factory into an Express RequestHandler.
@@ -36,6 +37,11 @@ function useCaseHandler(factory) {
                 : (req.body ?? {});
             // 2. Build use case
             const useCase = factory(data);
+            // 2b. Inject request-scoped logger (if logging middleware is active)
+            const logger = res.locals[logging_middleware_1.LOGGER_LOCALS_KEY];
+            if (logger) {
+                useCase.logger = logger;
+            }
             // 3. Validate
             const validationError = useCase.validate();
             if (validationError !== null) {

package/dist/core/usecase_test_handler.d.ts

@@ -1,4 +1,5 @@
 import type { UseCaseFactory, Input, Output } from './usecase';
+import type { ModularLogger } from './logger/logger';
 export interface TestResponse {
     statusCode: number;
     body: Record<string, unknown>;
@@ -21,4 +22,6 @@ export interface TestResponse {
  * expect(response.body).toEqual({ message: 'Hello, World!' });
  * ```
  */
-export declare function useCaseTestHandler<I extends Input, O extends Output>(factory: UseCaseFactory<I, O>, input?: Record<string, unknown>): Promise<TestResponse>;
+export declare function useCaseTestHandler<I extends Input, O extends Output>(factory: UseCaseFactory<I, O>, input?: Record<string, unknown>, options?: {
+    logger?: ModularLogger;
+}): Promise<TestResponse>;

package/dist/core/usecase_test_handler.js

@@ -25,9 +25,13 @@ const use_case_exception_1 = require("./use_case_exception");
  * expect(response.body).toEqual({ message: 'Hello, World!' });
  * ```
  */
-async function useCaseTestHandler(factory, input = {}) {
+async function useCaseTestHandler(factory, input = {}, options) {
     try {
         const useCase = factory(input);
+        // Inject logger if provided
+        if (options?.logger) {
+            useCase.logger = options.logger;
+        }
         const validationError = useCase.validate();
         if (validationError !== null) {
             return {

package/dist/index.d.ts

@@ -17,3 +17,7 @@ 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';
+export { LogLevel, RequestScopedLogger } from './core/logger/logger';
+export type { ModularLogger } from './core/logger/logger';
+export { loggingMiddleware, LOGGER_LOCALS_KEY } from './core/logger/logging_middleware';
+export type { LoggingMiddlewareOptions } from './core/logger/logging_middleware';

package/dist/index.js

@@ -5,7 +5,7 @@
 //   import { ModularApi, UseCase, Input, Output } from 'modular_api'
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.LOGGER_LOCALS_KEY = exports.loggingMiddleware = exports.RequestScopedLogger = exports.LogLevel = 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; } });
@@ -42,3 +42,10 @@ Object.defineProperty(exports, "MetricsRegistrar", { enumerable: true, get: func
 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; } });
+// Logger — Structured JSON logging (Loki/Grafana compatible)
+var logger_1 = require("./core/logger/logger");
+Object.defineProperty(exports, "LogLevel", { enumerable: true, get: function () { return logger_1.LogLevel; } });
+Object.defineProperty(exports, "RequestScopedLogger", { enumerable: true, get: function () { return logger_1.RequestScopedLogger; } });
+var logging_middleware_1 = require("./core/logger/logging_middleware");
+Object.defineProperty(exports, "loggingMiddleware", { enumerable: true, get: function () { return logging_middleware_1.loggingMiddleware; } });
+Object.defineProperty(exports, "LOGGER_LOCALS_KEY", { enumerable: true, get: function () { return logging_middleware_1.LOGGER_LOCALS_KEY; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@macss/modular-api",
-  "version": "0.2.0",
+  "version": "0.3.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",