@macss/modular-api 0.2.0 → 0.4.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)
 
 ---
 
@@ -36,7 +36,9 @@ curl -X POST http://localhost:8080/api/greetings/hello \
 ```
 
 **Docs** → `http://localhost:8080/docs`  
-**Health** → `http://localhost:8080/health`
+**Health** → `http://localhost:8080/health`  
+**OpenAPI JSON** → `http://localhost:8080/openapi.json` _(also /openapi.yaml)_
+**Metrics** → `http://localhost:8080/metrics` _(opt-in)_
 
 See `example/example.ts` for the full implementation including Input, Output, UseCase with `validate()`, and the builder.
 
@@ -49,11 +51,13 @@ See `example/example.ts` for the full implementation including Input, Output, Us
 - `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)
+- Constructor-based unit testing with fake dependency injection
 - `cors()` middleware — built-in CORS support
 - Swagger UI at `/docs` — auto-generated from registered use cases
+- OpenAPI spec at `/openapi.json` and `/openapi.yaml` — raw spec download
 - 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 +66,7 @@ See `example/example.ts` for the full implementation including Input, Output, Us
 ## Installation
 
 ```bash
-npm install modular_api
+npm install @macss/modular-api
 ```
 
 ---
@@ -91,16 +95,74 @@ async execute() {
 
 ## Testing
 
+Write true unit tests by injecting fake dependencies directly through the constructor.
+No HTTP server or real infrastructure needed.
+
 ```ts
-import { useCaseTestHandler } from 'modular_api';
+import { describe, it, expect, beforeEach } from 'vitest';
+import { UseCaseException } from 'modular_api';
+
+// ─── Fake ────────────────────────────────────────────────────
+class FakeGreetingRepository implements GreetingRepository {
+  saved: string[] = [];
+
+  async save(name: string): Promise<void> {
+    this.saved.push(name);
+  }
+}
+
+// ─── Tests ───────────────────────────────────────────────────
+describe('SayHello', () => {
+  let fakeRepo: FakeGreetingRepository;
+
+  beforeEach(() => {
+    fakeRepo = new FakeGreetingRepository();
+  });
+
+  it('greets correctly', async () => {
+    const usecase = new SayHello(new SayHelloInput('World'), { repository: fakeRepo });
+
+    expect(usecase.validate()).toBeNull();
+
+    const output = await usecase.execute();
+
+    expect(output.message).toBe('Hello, World!');
+    expect(fakeRepo.saved).toContain('World');
+  });
+
+  it('rejects empty name', () => {
+    const usecase = new SayHello(new SayHelloInput(''), { repository: fakeRepo });
+
+    expect(usecase.validate()).not.toBeNull();
+  });
 
-const handler = useCaseTestHandler(HelloWorld.fromJson);
-const response = await handler({ name: 'World' });
+  it('throws UseCaseException when repo fails', async () => {
+    const failingRepo = {
+      save: async () => {
+        throw new Error('DB error');
+      },
+    };
 
-console.log(response.statusCode); // 200
-console.log(response.body); // { message: 'Hello, World!' }
+    const usecase = new SayHello(new SayHelloInput('World'), { repository: failingRepo });
+
+    await expect(usecase.execute()).rejects.toThrow(UseCaseException);
+  });
+});
+```
+
+For integration tests against real infrastructure, use `UseCase.fromJson()` directly
+(no helper wrapper needed):
+
+```ts
+it('integration — end to end with real DB', async () => {
+  const usecase = SayHello.fromJson({ name: 'World' });
+  await usecase.execute();
+  expect(usecase.output.message).toBe('Hello, World!');
+});
 ```
 
+See [doc/testing_guide.md](doc/testing_guide.md) for the full guide.
+
 ---
 
 ## Architecture
@@ -116,17 +178,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 &&
@@ -164,9 +175,14 @@ class ModularApi {
             // 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));
+            // Raw spec endpoints
+            this.app.get('/openapi.json', (0, openapi_1.openApiJsonHandler)(spec));
+            this.app.get('/openapi.yaml', (0, openapi_1.openApiYamlHandler)(spec));
             const server = this.app.listen(port, host, () => {
                 console.log(`Docs  → http://localhost:${port}/docs`);
                 console.log(`Health → http://localhost:${port}/health`);
+                console.log(`OpenAPI JSON → http://localhost:${port}/openapi.json`);
+                console.log(`OpenAPI YAML → http://localhost:${port}/openapi.yaml`);
                 if (this.metricsEnabled) {
                     console.log(`Metrics → http://localhost:${port}${this.metricsPath}`);
                 }

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

@@ -5,8 +5,6 @@ export { ModularApi } from './core/modular_api';
 export type { ModularApiOptions } from './core/modular_api';
 export { ModuleBuilder } from './core/module_builder';
 export type { UseCaseOptions } from './core/module_builder';
-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';
@@ -17,3 +15,8 @@ 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';
+export { buildOpenApiSpec, jsonToYaml, openApiJsonHandler, openApiYamlHandler, } from './openapi/openapi';

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.openApiYamlHandler = exports.openApiJsonHandler = exports.jsonToYaml = exports.buildOpenApiSpec = 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.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; } });
@@ -20,9 +20,6 @@ Object.defineProperty(exports, "ModularApi", { enumerable: true, get: function (
 // Module builder (exposed for advanced / manual usage)
 var module_builder_1 = require("./core/module_builder");
 Object.defineProperty(exports, "ModuleBuilder", { enumerable: true, get: function () { return module_builder_1.ModuleBuilder; } });
-// Test helper — use in unit tests without an HTTP server
-var usecase_test_handler_1 = require("./core/usecase_test_handler");
-Object.defineProperty(exports, "useCaseTestHandler", { enumerable: true, get: function () { return usecase_test_handler_1.useCaseTestHandler; } });
 // Middlewares
 var cors_1 = require("./middlewares/cors");
 Object.defineProperty(exports, "cors", { enumerable: true, get: function () { return cors_1.cors; } });
@@ -42,3 +39,16 @@ 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; } });
+// OpenAPI — Raw spec endpoints
+var openapi_1 = require("./openapi/openapi");
+Object.defineProperty(exports, "buildOpenApiSpec", { enumerable: true, get: function () { return openapi_1.buildOpenApiSpec; } });
+Object.defineProperty(exports, "jsonToYaml", { enumerable: true, get: function () { return openapi_1.jsonToYaml; } });
+Object.defineProperty(exports, "openApiJsonHandler", { enumerable: true, get: function () { return openapi_1.openApiJsonHandler; } });
+Object.defineProperty(exports, "openApiYamlHandler", { enumerable: true, get: function () { return openapi_1.openApiYamlHandler; } });

package/dist/openapi/openapi.d.ts

@@ -1,3 +1,4 @@
+import type { RequestHandler } from 'express';
 interface OpenApiOptions {
     title: string;
     port: number;
@@ -19,4 +20,21 @@ interface OpenApiOptions {
  *   - summary and tags from UseCaseDocMeta
  */
 export declare function buildOpenApiSpec(options: OpenApiOptions): Record<string, unknown>;
+/**
+ * Converts a JSON-decoded value to a YAML string.
+ * Zero dependencies — handles objects, arrays, strings, numbers, bools, null.
+ */
+export declare function jsonToYaml(value: unknown, indent?: number, isRoot?: boolean): string;
+/**
+ * Creates an Express handler that returns the OpenAPI spec as JSON.
+ *
+ * @param spec — the pre-built OpenAPI specification object
+ */
+export declare function openApiJsonHandler(spec: Record<string, unknown>): RequestHandler;
+/**
+ * Creates an Express handler that returns the OpenAPI spec as YAML.
+ *
+ * @param spec — the pre-built OpenAPI specification object
+ */
+export declare function openApiYamlHandler(spec: Record<string, unknown>): RequestHandler;
 export {};

package/dist/openapi/openapi.js

@@ -6,6 +6,9 @@
 // ============================================================
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildOpenApiSpec = buildOpenApiSpec;
+exports.jsonToYaml = jsonToYaml;
+exports.openApiJsonHandler = openApiJsonHandler;
+exports.openApiYamlHandler = openApiYamlHandler;
 const registry_1 = require("../core/registry");
 /**
  * Builds a full OpenAPI 3.0 specification object from all registered use
@@ -92,3 +95,137 @@ function _schemaToQueryParams(schema) {
         schema: propSchema,
     }));
 }
+// ============================================================
+// JSON-to-YAML converter (zero dependencies)
+// ============================================================
+/** YAML reserved words that need quoting */
+const YAML_RESERVED = new Set(['true', 'false', 'null', 'yes', 'no', 'on', 'off', 'y', 'n']);
+/** Characters that require quoting in a YAML string value */
+const YAML_SPECIAL_RE = /[:{}\[\],&*?|>!%#@`"\\]/;
+/**
+ * Determines if a string needs quoting in YAML.
+ */
+function needsQuoting(s) {
+    if (s.length === 0)
+        return true;
+    if (YAML_RESERVED.has(s.toLowerCase()))
+        return true;
+    if (YAML_SPECIAL_RE.test(s))
+        return true;
+    if (/^[-? ]/.test(s))
+        return true;
+    if (!isNaN(Number(s)) && s.trim().length > 0)
+        return true;
+    if (s.includes('\n'))
+        return true;
+    return false;
+}
+/** Formats a YAML key, quoting if necessary. */
+function yamlKey(key) {
+    if (needsQuoting(key))
+        return `'${key.replace(/'/g, "''")}'`;
+    return key;
+}
+/** Writes a scalar YAML value. */
+function yamlScalar(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number')
+        return String(value);
+    const s = String(value);
+    if (needsQuoting(s))
+        return `'${s.replace(/'/g, "''")}'`;
+    return s;
+}
+/**
+ * Converts a JSON-decoded value to a YAML string.
+ * Zero dependencies — handles objects, arrays, strings, numbers, bools, null.
+ */
+function jsonToYaml(value, indent = 0, isRoot = true) {
+    const pad = '  '.repeat(indent);
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        const keys = Object.keys(obj);
+        if (keys.length === 0)
+            return '{}\n';
+        let result = isRoot ? '' : '\n';
+        for (const key of keys) {
+            const v = obj[key];
+            if (v !== null && typeof v === 'object') {
+                result += `${pad}${yamlKey(key)}:${jsonToYaml(v, indent + 1, false)}`;
+            }
+            else {
+                result += `${pad}${yamlKey(key)}: ${yamlScalar(v)}\n`;
+            }
+        }
+        return result;
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '[]\n';
+        let result = isRoot ? '' : '\n';
+        for (const item of value) {
+            if (item !== null && typeof item === 'object' && !Array.isArray(item)) {
+                const entries = Object.entries(item);
+                if (entries.length > 0) {
+                    let first = true;
+                    for (const [k, v] of entries) {
+                        if (first) {
+                            result += `${pad}- ${yamlKey(k)}:`;
+                            first = false;
+                        }
+                        else {
+                            result += `${pad}  ${yamlKey(k)}:`;
+                        }
+                        if (v !== null && typeof v === 'object') {
+                            result += jsonToYaml(v, indent + 2, false);
+                        }
+                        else {
+                            result += ` ${yamlScalar(v)}\n`;
+                        }
+                    }
+                }
+                else {
+                    result += `${pad}- {}\n`;
+                }
+            }
+            else if (Array.isArray(item)) {
+                result += `${pad}- ${jsonToYaml(item, indent + 1, false)}`;
+            }
+            else {
+                result += `${pad}- ${yamlScalar(item)}\n`;
+            }
+        }
+        return result;
+    }
+    return `${yamlScalar(value)}\n`;
+}
+// ============================================================
+// Express handlers for /openapi.json and /openapi.yaml
+// ============================================================
+/**
+ * Creates an Express handler that returns the OpenAPI spec as JSON.
+ *
+ * @param spec — the pre-built OpenAPI specification object
+ */
+function openApiJsonHandler(spec) {
+    const json = JSON.stringify(spec, null, 2);
+    return (_req, res) => {
+        res.setHeader('Content-Type', 'application/json');
+        res.send(json);
+    };
+}
+/**
+ * Creates an Express handler that returns the OpenAPI spec as YAML.
+ *
+ * @param spec — the pre-built OpenAPI specification object
+ */
+function openApiYamlHandler(spec) {
+    const yaml = jsonToYaml(spec);
+    return (_req, res) => {
+        res.setHeader('Content-Type', 'application/x-yaml');
+        res.send(yaml);
+    };
+}

package/package.json

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