@macss/modular-api 0.3.0 → 0.4.0

package/README.md

@@ -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,9 +51,10 @@ 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)
@@ -92,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();
 
-const handler = useCaseTestHandler(HelloWorld.fromJson);
-const response = await handler({ name: 'World' });
+    expect(output.message).toBe('Hello, World!');
+    expect(fakeRepo.saved).toContain('World');
+  });
 
-console.log(response.statusCode); // 200
-console.log(response.body); // { message: 'Hello, World!' }
+  it('rejects empty name', () => {
+    const usecase = new SayHello(new SayHelloInput(''), { repository: fakeRepo });
+
+    expect(usecase.validate()).not.toBeNull();
+  });
+
+  it('throws UseCaseException when repo fails', async () => {
+    const failingRepo = {
+      save: async () => {
+        throw new Error('DB error');
+      },
+    };
+
+    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

package/dist/core/modular_api.js

@@ -175,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/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';
@@ -21,3 +19,4 @@ 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.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;
+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; } });
@@ -49,3 +46,9 @@ Object.defineProperty(exports, "RequestScopedLogger", { enumerable: true, get: f
 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.3.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",