@macss/modular-api 0.1.0

package/README.md

@@ -0,0 +1,131 @@
+# 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)

package/dist/core/modular_api.d.ts

@@ -0,0 +1,74 @@
+import { type RequestHandler } from 'express';
+import { ModuleBuilder } from './module_builder';
+export interface ModularApiOptions {
+    /** Base path prefix for all module routes. Default: '/api' */
+    basePath?: string;
+    /** API title shown in Swagger UI. Default: 'API' */
+    title?: string;
+}
+/**
+ * Main entry point for modular_api.
+ *
+ * Dart equivalent:
+ * ```dart
+ * final api = ModularApi(basePath: '/api');
+ * api.module('greetings', (m) => m.usecase('hello', SayHello.fromJson));
+ * await api.serve(port: 8080);
+ * ```
+ *
+ * TypeScript equivalent:
+ * ```ts
+ * const api = new ModularApi({ basePath: '/api' });
+ * api.module('greetings', (m) => m.usecase('hello', SayHello.fromJson));
+ * await api.serve({ port: 8080 });
+ * ```
+ *
+ * Auto-mounted endpoints:
+ *   GET /health  → 200 "ok"
+ *   GET /docs    → Swagger UI
+ */
+export declare class ModularApi {
+    private readonly app;
+    private readonly rootRouter;
+    private readonly basePath;
+    private readonly title;
+    private readonly middlewares;
+    constructor(options?: ModularApiOptions);
+    /**
+     * Registers a group of use cases under a named module.
+     * Returns `this` for method chaining.
+     *
+     * ```ts
+     * api
+     *   .module('users', (m) => {
+     *     m.usecase('create', CreateUser.fromJson);
+     *     m.usecase('list',   ListUsers.fromJson, { method: 'GET' });
+     *   })
+     *   .module('products', buildProductsModule);
+     * ```
+     */
+    module(name: string, build: (m: ModuleBuilder) => void): this;
+    /**
+     * Adds an Express middleware to the pipeline.
+     * Applied in the order they are registered, before any module handler.
+     * Returns `this` for method chaining.
+     *
+     * ```ts
+     * api.use(cors()).use(myAuthMiddleware);
+     * ```
+     */
+    use(middleware: RequestHandler): this;
+    /**
+     * Starts the Express server on the given port.
+     *
+     * Auto-mounts:
+     *   GET /health → 200 "ok"
+     *   GET /docs   → Swagger UI (built from registered use cases)
+     *
+     * @returns The Node.js http.Server instance
+     */
+    serve(options: {
+        port: number;
+        host?: string;
+    }): Promise<import('http').Server>;
+}

package/dist/core/modular_api.js

@@ -0,0 +1,108 @@
+"use strict";
+// ============================================================
+// core/modular_api.ts
+// ModularApi — main orchestrator.
+// Mirror of ModularApi in Dart.
+// ============================================================
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModularApi = void 0;
+const express_1 = __importDefault(require("express"));
+const module_builder_1 = require("./module_builder");
+const openapi_1 = require("../openapi/openapi");
+const swagger_ui_express_1 = __importDefault(require("swagger-ui-express"));
+/**
+ * Main entry point for modular_api.
+ *
+ * Dart equivalent:
+ * ```dart
+ * final api = ModularApi(basePath: '/api');
+ * api.module('greetings', (m) => m.usecase('hello', SayHello.fromJson));
+ * await api.serve(port: 8080);
+ * ```
+ *
+ * TypeScript equivalent:
+ * ```ts
+ * const api = new ModularApi({ basePath: '/api' });
+ * api.module('greetings', (m) => m.usecase('hello', SayHello.fromJson));
+ * await api.serve({ port: 8080 });
+ * ```
+ *
+ * Auto-mounted endpoints:
+ *   GET /health  → 200 "ok"
+ *   GET /docs    → Swagger UI
+ */
+class ModularApi {
+    constructor(options = {}) {
+        this.middlewares = [];
+        this.basePath = options.basePath ?? '/api';
+        this.title = options.title ?? 'API';
+        this.app = (0, express_1.default)();
+        this.app.use(express_1.default.json());
+        this.rootRouter = express_1.default.Router();
+        this.app.use(this.rootRouter);
+    }
+    /**
+     * Registers a group of use cases under a named module.
+     * Returns `this` for method chaining.
+     *
+     * ```ts
+     * api
+     *   .module('users', (m) => {
+     *     m.usecase('create', CreateUser.fromJson);
+     *     m.usecase('list',   ListUsers.fromJson, { method: 'GET' });
+     *   })
+     *   .module('products', buildProductsModule);
+     * ```
+     */
+    module(name, build) {
+        const builder = new module_builder_1.ModuleBuilder(this.basePath, name, this.rootRouter);
+        build(builder);
+        builder._mount();
+        return this;
+    }
+    /**
+     * Adds an Express middleware to the pipeline.
+     * Applied in the order they are registered, before any module handler.
+     * Returns `this` for method chaining.
+     *
+     * ```ts
+     * api.use(cors()).use(myAuthMiddleware);
+     * ```
+     */
+    use(middleware) {
+        this.middlewares.push(middleware);
+        return this;
+    }
+    /**
+     * Starts the Express server on the given port.
+     *
+     * Auto-mounts:
+     *   GET /health → 200 "ok"
+     *   GET /docs   → Swagger UI (built from registered use cases)
+     *
+     * @returns The Node.js http.Server instance
+     */
+    serve(options) {
+        const { port, host = '0.0.0.0' } = options;
+        return new Promise((resolve) => {
+            // Register middlewares before routes
+            for (const mw of this.middlewares) {
+                this.app.use(mw);
+            }
+            // Health endpoint
+            this.app.get('/health', (_req, res) => res.status(200).send('ok'));
+            // Swagger / OpenAPI docs
+            const spec = (0, openapi_1.buildOpenApiSpec)({ title: this.title, port });
+            this.app.use('/docs', swagger_ui_express_1.default.serve, swagger_ui_express_1.default.setup(spec));
+            const server = this.app.listen(port, host, () => {
+                console.log(`Docs  → http://localhost:${port}/docs`);
+                console.log(`Health → http://localhost:${port}/health`);
+                resolve(server);
+            });
+        });
+    }
+}
+exports.ModularApi = ModularApi;

package/dist/core/module_builder.d.ts

@@ -0,0 +1,48 @@
+import { Router } from 'express';
+import type { Input, Output, UseCaseFactory } from './usecase';
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface UseCaseOptions {
+    /** HTTP method. Defaults to POST (same as Dart version). */
+    method?: HttpMethod;
+    summary?: string;
+    description?: string;
+    /** Override input schema for OpenAPI (if fromJson fails with empty data) */
+    inputSchema?: Record<string, unknown>;
+    /** Override output schema for OpenAPI (if fromJson fails with empty data) */
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * Fluent builder that registers use cases on a module-scoped Express Router.
+ * Returned and used inside the callback of `ModularApi.module()`.
+ *
+ * Dart equivalent:
+ *   api.module('users', (m) {
+ *     m.usecase('create', CreateUser.fromJson);
+ *   });
+ *
+ * TypeScript:
+ *   api.module('users', (m) => {
+ *     m.usecase('create', CreateUser.fromJson);
+ *   });
+ */
+export declare class ModuleBuilder {
+    private readonly basePath;
+    private readonly moduleName;
+    private readonly rootRouter;
+    private readonly router;
+    constructor(basePath: string, moduleName: string, rootRouter: Router);
+    /**
+     * Registers a use case as an HTTP endpoint.
+     *
+     * @param name     Route segment, e.g. 'create' → POST /api/users/create
+     * @param factory  The static `fromJson` of your UseCase class
+     * @param options  Optional HTTP method, summary and description for OpenAPI
+     */
+    usecase<I extends Input, O extends Output>(name: string, factory: UseCaseFactory<I, O>, options?: UseCaseOptions): this;
+    /** Try to get schemas from a dummy factory call. Fails gracefully. */
+    private _extractSchemas;
+    /** @internal — called by ModularApi after the builder callback runs */
+    _mount(): void;
+    private _normalizeBase;
+}
+export {};

package/dist/core/module_builder.js

@@ -0,0 +1,94 @@
+"use strict";
+// ============================================================
+// core/module_builder.ts
+// ModuleBuilder — collects use cases and mounts them on a Router.
+// Mirror of ModuleBuilder in Dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ModuleBuilder = void 0;
+const express_1 = require("express");
+const usecase_handler_1 = require("./usecase_handler");
+const registry_1 = require("./registry");
+/**
+ * Fluent builder that registers use cases on a module-scoped Express Router.
+ * Returned and used inside the callback of `ModularApi.module()`.
+ *
+ * Dart equivalent:
+ *   api.module('users', (m) {
+ *     m.usecase('create', CreateUser.fromJson);
+ *   });
+ *
+ * TypeScript:
+ *   api.module('users', (m) => {
+ *     m.usecase('create', CreateUser.fromJson);
+ *   });
+ */
+class ModuleBuilder {
+    constructor(basePath, moduleName, rootRouter) {
+        this.basePath = basePath;
+        this.moduleName = moduleName;
+        this.rootRouter = rootRouter;
+        this.router = (0, express_1.Router)();
+    }
+    /**
+     * Registers a use case as an HTTP endpoint.
+     *
+     * @param name     Route segment, e.g. 'create' → POST /api/users/create
+     * @param factory  The static `fromJson` of your UseCase class
+     * @param options  Optional HTTP method, summary and description for OpenAPI
+     */
+    usecase(name, factory, options = {}) {
+        const { method = 'POST', summary, description, inputSchema, outputSchema } = options;
+        // Normalize name: trim and remove leading slash
+        const cleanName = name.trim().replace(/^\//, '');
+        const subPath = `/${cleanName}`;
+        const methodL = method.toLowerCase();
+        // Mount the Express handler
+        this.router[methodL](subPath, (0, usecase_handler_1.useCaseHandler)(factory));
+        // Try to capture schemas via dummy factory call, or use overrides
+        const extracted = this._extractSchemas(factory);
+        const schemas = {
+            input: inputSchema ?? extracted.input,
+            output: outputSchema ?? extracted.output,
+        };
+        // Register in the global registry for OpenAPI generation
+        registry_1.apiRegistry.routes.push({
+            module: this.moduleName,
+            name: cleanName,
+            method: method,
+            path: `${this._normalizeBase(this.basePath)}/${this.moduleName}/${cleanName}`,
+            factory: factory,
+            schemas,
+            doc: {
+                summary: summary ?? `Use case ${cleanName} in module ${this.moduleName}`,
+                description: description ?? `Auto-generated documentation for ${cleanName}`,
+                tags: [this.moduleName],
+            },
+        });
+        return this;
+    }
+    /** Try to get schemas from a dummy factory call. Fails gracefully. */
+    _extractSchemas(factory) {
+        try {
+            const instance = factory({});
+            return {
+                input: instance.input.toSchema(),
+                output: instance.output?.toSchema?.() ?? {},
+            };
+        }
+        catch {
+            return { input: {}, output: {} };
+        }
+    }
+    /** @internal — called by ModularApi after the builder callback runs */
+    _mount() {
+        const mountPath = `${this._normalizeBase(this.basePath)}/${this.moduleName}`;
+        this.rootRouter.use(mountPath, this.router);
+    }
+    _normalizeBase(p) {
+        if (!p)
+            return '';
+        return p.startsWith('/') ? p : `/${p}`;
+    }
+}
+exports.ModuleBuilder = ModuleBuilder;

package/dist/core/registry.d.ts

@@ -0,0 +1,37 @@
+import type { UseCaseFactory } from './usecase';
+import type { Input, Output } from './usecase';
+export interface UseCaseDocMeta {
+    summary?: string;
+    description?: string;
+    /** Tags for Swagger grouping — typically the module name */
+    tags?: string[];
+    /** Override for the Input JSON Schema (captured at registration time) */
+    inputSchema?: Record<string, unknown>;
+    /** Override for the Output JSON Schema (captured at registration time) */
+    outputSchema?: Record<string, unknown>;
+}
+export interface UseCaseRegistration {
+    module: string;
+    name: string;
+    /** HTTP method in uppercase: "POST" | "GET" | "PUT" | "PATCH" | "DELETE" */
+    method: string;
+    /** Full path e.g. "/api/users/create" */
+    path: string;
+    factory: UseCaseFactory<Input, Output>;
+    doc?: UseCaseDocMeta;
+    /** Schemas captured at registration time via dummy factory call */
+    schemas: {
+        input: Record<string, unknown>;
+        output: Record<string, unknown>;
+    };
+}
+/**
+ * Singleton registry — holds all registered routes for OpenAPI generation.
+ * Populated by ModuleBuilder.usecase() at startup.
+ */
+declare class ApiRegistry {
+    readonly routes: UseCaseRegistration[];
+    clear(): void;
+}
+export declare const apiRegistry: ApiRegistry;
+export {};

package/dist/core/registry.js

@@ -0,0 +1,22 @@
+"use strict";
+// ============================================================
+// core/registry.ts
+// In-memory registry of all registered use cases.
+// Used by the OpenAPI generator to build the spec automatically.
+// Mirror of _ApiRegistry + UseCaseRegistration in Dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.apiRegistry = void 0;
+/**
+ * Singleton registry — holds all registered routes for OpenAPI generation.
+ * Populated by ModuleBuilder.usecase() at startup.
+ */
+class ApiRegistry {
+    constructor() {
+        this.routes = [];
+    }
+    clear() {
+        this.routes.length = 0;
+    }
+}
+exports.apiRegistry = new ApiRegistry();

package/dist/core/use_case_exception.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Throw this inside `execute()` to return a specific HTTP status code
+ * and a structured JSON error body — instead of a generic 500.
+ *
+ * Dart equivalent:
+ *   throw UseCaseException(statusCode: 404, message: 'Not found');
+ *
+ * TypeScript usage:
+ * ```ts
+ * throw new UseCaseException({
+ *   statusCode: 404,
+ *   message: 'User not found',
+ *   errorCode: 'USER_NOT_FOUND',
+ * });
+ * ```
+ *
+ * HTTP response body:
+ * ```json
+ * { "error": "USER_NOT_FOUND", "message": "User not found" }
+ * ```
+ */
+export declare class UseCaseException extends Error {
+    readonly statusCode: number;
+    readonly message: string;
+    readonly errorCode?: string;
+    readonly details?: Record<string, unknown>;
+    constructor(params: {
+        statusCode: number;
+        message: string;
+        errorCode?: string;
+        details?: Record<string, unknown>;
+    });
+    /** Serializes to the JSON body sent in the HTTP error response. */
+    toJson(): Record<string, unknown>;
+    toString(): string;
+}

package/dist/core/use_case_exception.js

@@ -0,0 +1,55 @@
+"use strict";
+// ============================================================
+// core/use_case_exception.ts
+// Structured exception for controlled HTTP error responses.
+// Mirror of UseCaseException in Dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UseCaseException = void 0;
+/**
+ * Throw this inside `execute()` to return a specific HTTP status code
+ * and a structured JSON error body — instead of a generic 500.
+ *
+ * Dart equivalent:
+ *   throw UseCaseException(statusCode: 404, message: 'Not found');
+ *
+ * TypeScript usage:
+ * ```ts
+ * throw new UseCaseException({
+ *   statusCode: 404,
+ *   message: 'User not found',
+ *   errorCode: 'USER_NOT_FOUND',
+ * });
+ * ```
+ *
+ * HTTP response body:
+ * ```json
+ * { "error": "USER_NOT_FOUND", "message": "User not found" }
+ * ```
+ */
+class UseCaseException extends Error {
+    constructor(params) {
+        super(params.message);
+        this.name = 'UseCaseException';
+        this.statusCode = params.statusCode;
+        this.message = params.message;
+        this.errorCode = params.errorCode;
+        this.details = params.details;
+    }
+    /** Serializes to the JSON body sent in the HTTP error response. */
+    toJson() {
+        const body = {
+            error: this.errorCode ?? 'error',
+            message: this.message,
+        };
+        if (this.details !== undefined) {
+            body['details'] = this.details;
+        }
+        return body;
+    }
+    toString() {
+        const code = this.errorCode ? ` [${this.errorCode}]` : '';
+        return `UseCaseException(${this.statusCode}): ${this.message}${code}`;
+    }
+}
+exports.UseCaseException = UseCaseException;

package/dist/core/usecase.d.ts

@@ -0,0 +1,113 @@
+/**
+ * **Contract** — use `implements Input`.
+ *
+ * Pure interface: all members must be provided by the implementor.
+ * No default behavior is inherited — every Input is self-contained.
+ *
+ * ```ts
+ * class HelloInput implements Input {
+ *   constructor(readonly name: string) {}
+ *   toJson()   { return { name: this.name }; }
+ *   toSchema() { return { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }; }
+ * }
+ * ```
+ */
+export declare abstract class Input {
+    abstract toJson(): Record<string, unknown>;
+    /**
+     * Returns an OpenAPI-compatible JSON Schema describing this input.
+     * Used to auto-generate Swagger documentation.
+     */
+    abstract toSchema(): Record<string, unknown>;
+}
+/**
+ * **Contract** — use `implements Output`.
+ *
+ * Pure interface: all members must be provided by the implementor.
+ * The implementor must define `statusCode` explicitly — this forces
+ * developers to think about HTTP status codes for every response.
+ *
+ * ```ts
+ * class HelloOutput implements Output {
+ *   constructor(readonly message: string) {}
+ *   get statusCode() { return 200; }
+ *   toJson()   { return { message: this.message }; }
+ *   toSchema() { return { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] }; }
+ * }
+ * ```
+ */
+export declare abstract class Output {
+    abstract toJson(): Record<string, unknown>;
+    abstract toSchema(): Record<string, unknown>;
+    /**
+     * HTTP status code for the response.
+     * Must be implemented explicitly (e.g. 200, 201, 400, 404).
+     */
+    abstract get statusCode(): number;
+}
+/**
+ * Factory function type — the signature every UseCase class must expose
+ * as a static method `fromJson`.
+ *
+ * Dart equivalent:
+ *   static MyUseCase fromJson(Map<String, dynamic> json) { ... }
+ */
+export type UseCaseFactory<I extends Input = Input, O extends Output = Output> = (json: Record<string, unknown>) => UseCase<I, O>;
+/**
+ * **Contract** — use `implements UseCase<I, O>`.
+ *
+ * Pure interface: all members must be provided by the implementor.
+ * This mirrors the Dart version where UseCase is 100% abstract.
+ *
+ * Lifecycle (handled by the framework):
+ *   1. `fromJson(json)`    — static factory, builds the use case
+ *   2. `validate()`        — return error string or null
+ *   3. `execute()`         — run business logic, set `this.output`
+ *   4. `output.toJson()`   — serialize and return to HTTP client
+ *
+ * ```ts
+ * class SayHello implements UseCase<HelloInput, HelloOutput> {
+ *   input: HelloInput;
+ *   output!: HelloOutput;
+ *
+ *   constructor(input: HelloInput) { this.input = input; }
+ *
+ *   static fromJson(json: Record<string, unknown>) {
+ *     return new SayHello(HelloInput.fromJson(json));
+ *   }
+ *
+ *   validate(): string | null {
+ *     if (!this.input.name) return 'name is required';
+ *     return null;
+ *   }
+ *
+ *   async execute(): Promise<void> {
+ *     this.output = new HelloOutput(`Hello, ${this.input.name}!`);
+ *   }
+ *
+ *   toJson() { return this.output.toJson(); }
+ * }
+ * ```
+ */
+export declare abstract class UseCase<I extends Input, O extends Output> {
+    /** Input DTO — set in constructor. */
+    abstract readonly input: I;
+    /** Output DTO — set in execute(). */
+    abstract output: O;
+    /**
+     * Synchronous validation.
+     * Return a human-readable error string to abort execution with HTTP 400.
+     * Return null to proceed.
+     */
+    abstract validate(): string | null;
+    /**
+     * Business logic. Must set `this.output` before returning.
+     * Keep this method free of HTTP concerns.
+     */
+    abstract execute(): Promise<void>;
+    /**
+     * Serializes the output DTO to a plain object for the HTTP response.
+     * Typically implemented as `return this.output.toJson();`
+     */
+    abstract toJson(): Record<string, unknown>;
+}

package/dist/core/usecase.js

@@ -0,0 +1,83 @@
+"use strict";
+// ============================================================
+// core/usecase.ts
+// Base classes: Input, Output, UseCase<I, O>
+// Mirror of the Dart abstract classes in usecase.dart
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UseCase = exports.Output = exports.Input = void 0;
+/**
+ * **Contract** — use `implements Input`.
+ *
+ * Pure interface: all members must be provided by the implementor.
+ * No default behavior is inherited — every Input is self-contained.
+ *
+ * ```ts
+ * class HelloInput implements Input {
+ *   constructor(readonly name: string) {}
+ *   toJson()   { return { name: this.name }; }
+ *   toSchema() { return { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }; }
+ * }
+ * ```
+ */
+class Input {
+}
+exports.Input = Input;
+/**
+ * **Contract** — use `implements Output`.
+ *
+ * Pure interface: all members must be provided by the implementor.
+ * The implementor must define `statusCode` explicitly — this forces
+ * developers to think about HTTP status codes for every response.
+ *
+ * ```ts
+ * class HelloOutput implements Output {
+ *   constructor(readonly message: string) {}
+ *   get statusCode() { return 200; }
+ *   toJson()   { return { message: this.message }; }
+ *   toSchema() { return { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] }; }
+ * }
+ * ```
+ */
+class Output {
+}
+exports.Output = Output;
+/**
+ * **Contract** — use `implements UseCase<I, O>`.
+ *
+ * Pure interface: all members must be provided by the implementor.
+ * This mirrors the Dart version where UseCase is 100% abstract.
+ *
+ * Lifecycle (handled by the framework):
+ *   1. `fromJson(json)`    — static factory, builds the use case
+ *   2. `validate()`        — return error string or null
+ *   3. `execute()`         — run business logic, set `this.output`
+ *   4. `output.toJson()`   — serialize and return to HTTP client
+ *
+ * ```ts
+ * class SayHello implements UseCase<HelloInput, HelloOutput> {
+ *   input: HelloInput;
+ *   output!: HelloOutput;
+ *
+ *   constructor(input: HelloInput) { this.input = input; }
+ *
+ *   static fromJson(json: Record<string, unknown>) {
+ *     return new SayHello(HelloInput.fromJson(json));
+ *   }
+ *
+ *   validate(): string | null {
+ *     if (!this.input.name) return 'name is required';
+ *     return null;
+ *   }
+ *
+ *   async execute(): Promise<void> {
+ *     this.output = new HelloOutput(`Hello, ${this.input.name}!`);
+ *   }
+ *
+ *   toJson() { return this.output.toJson(); }
+ * }
+ * ```
+ */
+class UseCase {
+}
+exports.UseCase = UseCase;

package/dist/core/usecase_handler.d.ts

@@ -0,0 +1,22 @@
+import type { RequestHandler } from 'express';
+import type { UseCaseFactory, Input, Output } from './usecase';
+/**
+ * Wraps any UseCase factory into an Express RequestHandler.
+ *
+ * Lifecycle (mirrors Dart useCaseHttpHandler):
+ *   1. Parse body (POST/PUT/PATCH) or query params (GET/DELETE)
+ *   2. Build UseCase via factory(json)
+ *   3. Call validate() — return 400 if error string returned
+ *   4. Call execute()
+ *   5. Return output.toJson() with output.statusCode
+ *
+ * Errors:
+ *   - UseCaseException  → statusCode from exception, structured JSON body
+ *   - Any other Error   → 500 Internal Server Error
+ *
+ * Usage:
+ * ```ts
+ * router.post('/hello', useCaseHandler(SayHello.fromJson));
+ * ```
+ */
+export declare function useCaseHandler<I extends Input, O extends Output>(factory: UseCaseFactory<I, O>): RequestHandler;

package/dist/core/usecase_handler.js

@@ -0,0 +1,60 @@
+"use strict";
+// ============================================================
+// core/usecase_handler.ts
+// Express RequestHandler adapter for any UseCase.
+// Mirror of useCaseHttpHandler() in Dart (Shelf).
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCaseHandler = useCaseHandler;
+const use_case_exception_1 = require("./use_case_exception");
+const JSON_HEADERS = { 'Content-Type': 'application/json; charset=utf-8' };
+/**
+ * Wraps any UseCase factory into an Express RequestHandler.
+ *
+ * Lifecycle (mirrors Dart useCaseHttpHandler):
+ *   1. Parse body (POST/PUT/PATCH) or query params (GET/DELETE)
+ *   2. Build UseCase via factory(json)
+ *   3. Call validate() — return 400 if error string returned
+ *   4. Call execute()
+ *   5. Return output.toJson() with output.statusCode
+ *
+ * Errors:
+ *   - UseCaseException  → statusCode from exception, structured JSON body
+ *   - Any other Error   → 500 Internal Server Error
+ *
+ * Usage:
+ * ```ts
+ * router.post('/hello', useCaseHandler(SayHello.fromJson));
+ * ```
+ */
+function useCaseHandler(factory) {
+    return async (req, res) => {
+        try {
+            // 1. Extract payload
+            const data = req.method.toUpperCase() === 'GET' || req.method.toUpperCase() === 'DELETE'
+                ? { ...req.query, ...req.params }
+                : req.body ?? {};
+            // 2. Build use case
+            const useCase = factory(data);
+            // 3. Validate
+            const validationError = useCase.validate();
+            if (validationError !== null) {
+                res.status(400).set(JSON_HEADERS).json({ error: validationError });
+                return;
+            }
+            // 4. Execute
+            await useCase.execute();
+            // 5. Respond
+            res.status(useCase.output.statusCode).set(JSON_HEADERS).json(useCase.toJson());
+        }
+        catch (err) {
+            if (err instanceof use_case_exception_1.UseCaseException) {
+                console.error('UseCaseException:', err.toString());
+                res.status(err.statusCode).set(JSON_HEADERS).json(err.toJson());
+                return;
+            }
+            console.error('useCaseHandler unexpected error:', err);
+            res.status(500).set(JSON_HEADERS).json({ error: 'Internal server error' });
+        }
+    };
+}

package/dist/core/usecase_test_handler.d.ts

@@ -0,0 +1,24 @@
+import type { UseCaseFactory, Input, Output } from './usecase';
+export interface TestResponse {
+    statusCode: number;
+    body: Record<string, unknown>;
+}
+/**
+ * Executes a UseCase directly from a plain JSON object, without Express.
+ * Ideal for unit tests — no HTTP server needed.
+ *
+ * Mirrors the Dart `useCaseTestHandler` pattern.
+ *
+ * Returns a `TestResponse` with `statusCode` and `body` so you can assert
+ * on both the HTTP status and the JSON payload.
+ *
+ * Usage:
+ * ```ts
+ * import { useCaseTestHandler } from 'modular_api';
+ *
+ * const response = await useCaseTestHandler(SayHello.fromJson, { name: 'World' });
+ * expect(response.statusCode).toBe(200);
+ * 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>;

package/dist/core/usecase_test_handler.js

@@ -0,0 +1,56 @@
+"use strict";
+// ============================================================
+// core/usecase_test_handler.ts
+// Test helper — runs a UseCase without an HTTP server.
+// Mirror of useCaseTestHandler() in Dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useCaseTestHandler = useCaseTestHandler;
+const use_case_exception_1 = require("./use_case_exception");
+/**
+ * Executes a UseCase directly from a plain JSON object, without Express.
+ * Ideal for unit tests — no HTTP server needed.
+ *
+ * Mirrors the Dart `useCaseTestHandler` pattern.
+ *
+ * Returns a `TestResponse` with `statusCode` and `body` so you can assert
+ * on both the HTTP status and the JSON payload.
+ *
+ * Usage:
+ * ```ts
+ * import { useCaseTestHandler } from 'modular_api';
+ *
+ * const response = await useCaseTestHandler(SayHello.fromJson, { name: 'World' });
+ * expect(response.statusCode).toBe(200);
+ * expect(response.body).toEqual({ message: 'Hello, World!' });
+ * ```
+ */
+async function useCaseTestHandler(factory, input = {}) {
+    try {
+        const useCase = factory(input);
+        const validationError = useCase.validate();
+        if (validationError !== null) {
+            return {
+                statusCode: 400,
+                body: { error: validationError },
+            };
+        }
+        await useCase.execute();
+        return {
+            statusCode: useCase.output.statusCode,
+            body: useCase.toJson(),
+        };
+    }
+    catch (err) {
+        if (err instanceof use_case_exception_1.UseCaseException) {
+            return {
+                statusCode: err.statusCode,
+                body: err.toJson(),
+            };
+        }
+        return {
+            statusCode: 500,
+            body: { error: 'Internal server error' },
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { Input, Output, UseCase } from './core/usecase';
+export type { UseCaseFactory } from './core/usecase';
+export { UseCaseException } from './core/use_case_exception';
+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';

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+// ============================================================
+// index.ts  — Public API barrel export
+// This is the single entry point users import from:
+//   import { ModularApi, UseCase, Input, Output } from 'modular_api'
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cors = exports.useCaseTestHandler = exports.ModuleBuilder = exports.ModularApi = exports.UseCaseException = exports.UseCase = exports.Output = exports.Input = void 0;
+// Core abstractions
+var usecase_1 = require("./core/usecase");
+Object.defineProperty(exports, "Input", { enumerable: true, get: function () { return usecase_1.Input; } });
+Object.defineProperty(exports, "Output", { enumerable: true, get: function () { return usecase_1.Output; } });
+Object.defineProperty(exports, "UseCase", { enumerable: true, get: function () { return usecase_1.UseCase; } });
+// Controlled error responses
+var use_case_exception_1 = require("./core/use_case_exception");
+Object.defineProperty(exports, "UseCaseException", { enumerable: true, get: function () { return use_case_exception_1.UseCaseException; } });
+// Main orchestrator
+var modular_api_1 = require("./core/modular_api");
+Object.defineProperty(exports, "ModularApi", { enumerable: true, get: function () { return modular_api_1.ModularApi; } });
+// 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; } });

package/dist/middlewares/cors.d.ts

@@ -0,0 +1,23 @@
+import type { RequestHandler } from 'express';
+export interface CorsOptions {
+    /** Allowed origins. Default: '*' */
+    origin?: string | string[];
+    /** Allowed methods. Default: 'GET,POST,PUT,PATCH,DELETE,OPTIONS' */
+    methods?: string;
+    /** Allowed headers. Default: 'Content-Type,Authorization' */
+    allowedHeaders?: string;
+}
+/**
+ * Returns an Express middleware that sets CORS headers on every response.
+ *
+ * Dart equivalent:  api.use(cors())
+ * TypeScript:       api.use(cors())
+ *
+ * Usage:
+ * ```ts
+ * const api = new ModularApi();
+ * api.use(cors());
+ * api.use(cors({ origin: 'https://myapp.com' }));
+ * ```
+ */
+export declare function cors(options?: CorsOptions): RequestHandler;

package/dist/middlewares/cors.js

@@ -0,0 +1,39 @@
+"use strict";
+// ============================================================
+// middlewares/cors.ts
+// Simple CORS middleware — no external dependencies.
+// Mirror of cors() in Dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cors = cors;
+/**
+ * Returns an Express middleware that sets CORS headers on every response.
+ *
+ * Dart equivalent:  api.use(cors())
+ * TypeScript:       api.use(cors())
+ *
+ * Usage:
+ * ```ts
+ * const api = new ModularApi();
+ * api.use(cors());
+ * api.use(cors({ origin: 'https://myapp.com' }));
+ * ```
+ */
+function cors(options = {}) {
+    const origin = Array.isArray(options.origin)
+        ? options.origin.join(', ')
+        : (options.origin ?? '*');
+    const methods = options.methods ?? 'GET,POST,PUT,PATCH,DELETE,OPTIONS';
+    const allowedHeaders = options.allowedHeaders ?? 'Content-Type,Authorization';
+    return (req, res, next) => {
+        res.setHeader('Access-Control-Allow-Origin', origin);
+        res.setHeader('Access-Control-Allow-Methods', methods);
+        res.setHeader('Access-Control-Allow-Headers', allowedHeaders);
+        // Respond immediately to pre-flight OPTIONS requests
+        if (req.method === 'OPTIONS') {
+            res.status(204).end();
+            return;
+        }
+        next();
+    };
+}

package/dist/openapi/openapi.d.ts

@@ -0,0 +1,22 @@
+interface OpenApiOptions {
+    title: string;
+    port: number;
+    version?: string;
+    description?: string;
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+}
+/**
+ * Builds a full OpenAPI 3.0 specification object from all registered use
+ * cases in `apiRegistry`. Called by ModularApi.serve() automatically.
+ *
+ * Each use case contributes:
+ *   - A path entry (e.g. POST /api/users/create)
+ *   - requestBody schema from Input.toSchema()
+ *   - response schema from Output.toSchema()
+ *   - summary and tags from UseCaseDocMeta
+ */
+export declare function buildOpenApiSpec(options: OpenApiOptions): Record<string, unknown>;
+export {};

package/dist/openapi/openapi.js

@@ -0,0 +1,96 @@
+"use strict";
+// ============================================================
+// openapi/openapi.ts
+// Builds an OpenAPI 3.0 spec from the global registry.
+// Mirror of OpenApi.init() / OpenApi.docs in Dart.
+// ============================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOpenApiSpec = buildOpenApiSpec;
+const registry_1 = require("../core/registry");
+/**
+ * Builds a full OpenAPI 3.0 specification object from all registered use
+ * cases in `apiRegistry`. Called by ModularApi.serve() automatically.
+ *
+ * Each use case contributes:
+ *   - A path entry (e.g. POST /api/users/create)
+ *   - requestBody schema from Input.toSchema()
+ *   - response schema from Output.toSchema()
+ *   - summary and tags from UseCaseDocMeta
+ */
+function buildOpenApiSpec(options) {
+    const { title, port, version = '0.1.0', description = 'Auto-generated by modular-api', servers, } = options;
+    const defaultServers = [
+        { url: `http://localhost:${port}`, description: 'Local' },
+    ];
+    const paths = {};
+    for (const route of registry_1.apiRegistry.routes) {
+        const method = route.method.toLowerCase();
+        const path = route.path;
+        // Use schemas captured at registration time
+        const inputSchema = route.schemas.input;
+        const outputSchema = route.schemas.output;
+        if (!paths[path]) {
+            paths[path] = {};
+        }
+        paths[path][method] = {
+            summary: route.doc?.summary,
+            description: route.doc?.description,
+            tags: route.doc?.tags ?? [route.module],
+            ...(method !== 'get' && method !== 'delete'
+                ? {
+                    requestBody: {
+                        required: true,
+                        content: {
+                            'application/json': {
+                                schema: inputSchema,
+                            },
+                        },
+                    },
+                }
+                : {
+                    parameters: _schemaToQueryParams(inputSchema),
+                }),
+            responses: {
+                '200': {
+                    description: 'Successful response',
+                    content: {
+                        'application/json': {
+                            schema: outputSchema,
+                        },
+                    },
+                },
+                '400': {
+                    description: 'Validation error',
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                properties: { error: { type: 'string' } },
+                            },
+                        },
+                    },
+                },
+                '500': {
+                    description: 'Internal server error',
+                },
+            },
+        };
+    }
+    return {
+        openapi: '3.0.0',
+        info: { title, version, description },
+        servers: servers ?? defaultServers,
+        paths,
+    };
+}
+/** Converts a JSON Schema object properties to OpenAPI query parameters */
+function _schemaToQueryParams(schema) {
+    const properties = schema['properties'] ?? {};
+    const required = schema['required'] ?? [];
+    return Object.entries(properties).map(([name, propSchema]) => ({
+        name,
+        in: 'query',
+        required: required.includes(name),
+        schema: propSchema,
+    }));
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@macss/modular-api",
+  "version": "0.1.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",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "dev": "ts-node src/index.ts",
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "api",
+    "usecase",
+    "openapi",
+    "express",
+    "modular"
+  ],
+  "author": "ccisne.dev",
+  "license": "MIT",
+  "dependencies": {
+    "express": "^4.22.1",
+    "swagger-ui-express": "^5.0.1"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.19.11",
+    "@types/swagger-ui-express": "^4.1.8",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3"
+  }
+}