adorn-api 1.0.0 → 1.0.1

package/README.md

@@ -1,249 +1,51 @@
-# Adorn API
-
-A TypeScript API framework using **Standard TC39 Decorators** (not experimental decorators) to build type-safe, self-documenting APIs with automatic OpenAPI/Swagger generation.
-
-## Features
-
-- ✅ **Standard Decorators**: Uses TC39 Stage 3 decorators (no experimental flags needed)
-- ✅ **Type-Safe DTOs**: Full TypeScript type checking at edit time
-- ✅ **Automatic Swagger Generation**: Generates OpenAPI 3.0 documentation from your code
-- ✅ **Runtime Route Generation**: Automatically creates Express routes
-- ✅ **Inheritance Support**: Extend base DTO classes with full type information
-- ✅ **Generic Response Types**: `EntityResponse<T>`, `CreateInput<T>`, etc.
-- ✅ **Authentication**: Built-in `@Authorized` decorator
-- ✅ **Union Types & Enums**: Automatically converted to Swagger enums
-- ✅ **Nested Objects**: Recursive type resolution for complex DTOs
-
-## Installation
-
-```bash
-npm install adorn-api
-```
-
-## Quick Start
-
-### 1. Create a Controller
-
-```typescript
-// src/controllers/user.controller.ts
-import { Controller, Get, Post, FromQuery, FromPath, FromBody } from "adorn-api";
-
-class GetUserRequest {
-  @FromPath()
-  userId!: string;
-  
-  @FromQuery()
-  details?: boolean;
-}
-
-@Controller("users")
-export class UserController {
-  @Get("/{userId}")
-  public async getUser(req: GetUserRequest): Promise<string> {
-    return `Getting user ${req.userId} with details: ${req.details}`;
-  }
-}
-```
-
-### 2. Generate Swagger and Routes
-
-```bash
-npx adorn-api gen
-```
-
-This generates:
-- `swagger.json` - OpenAPI 3.0 specification
-- `src/routes.ts` - Express route handlers
-
-### 3. Start Your Server
-
-```typescript
-// src/server.ts
-import express from "express";
-import { RegisterRoutes } from "./routes.js";
-
-const app = express();
-app.use(express.json());
-
-RegisterRoutes(app);
-
-app.listen(3000, () => {
-  console.log("Server running on http://localhost:3000");
-});
-```
-
-Visit http://localhost:3000/docs to see your Swagger UI.
-
-## Advanced Usage
-
-### Inheritance & Generics
-
-```typescript
-import { PaginationQuery, EntityResponse, CreateInput } from "../lib/common.js";
-
-// Inherit pagination properties
-class UserListRequest extends PaginationQuery {
-  search?: string; 
-  
-  @FromPath()
-  tenantId!: string;
-}
-
-// Use generic type helpers
-class CreateUserDto implements CreateInput<User, 'name' | 'email'> {
-  @FromBody()
-  name!: string;
-
-  @FromBody()
-  email!: string;
-}
-
-@Controller("advanced")
-export class AdvancedController {
-  @Get("/{tenantId}/users")
-  public async listUsers(req: UserListRequest): Promise<EntityResponse<User[]>> {
-    return [/* ... */];
-  }
-}
-```
-
-### Authentication
-
-```typescript
-import { Authorized } from "../lib/decorators.js";
-
-@Controller("profile")
-export class ProfileController {
-  @Authorized("admin")
-  @Post("/update")
-  public async update(req: UpdateProfileDto) {
-    // Only accessible with valid Bearer token
-    return { success: true };
-  }
-}
-```
-
-## Project Structure
-
-```
-adorn-api/
-├── src/
-│   ├── lib/
-│   │   ├── decorators.ts      # Standard decorators (@Get, @Post, @Controller, etc.)
-│   │   └── common.ts          # Common types (PaginationQuery, EntityResponse, etc.)
-│   ├── cli/
-│   │   ├── generate-swagger.ts # Swagger/OpenAPI generator
-│   │   └── generate-routes.ts  # Express route generator
-│   └── index.ts               # Main library entry point
-├── tests/
-│   └── example-app/           # Example application using adorn-api
-│       ├── controllers/       # Example controllers
-│       ├── entities/          # Example entities
-│       ├── middleware/        # Example middleware
-│       ├── routes.ts         # Generated routes (auto-generated)
-│       └── server.ts         # Example Express server
-├── swagger.json              # Generated OpenAPI spec
-└── package.json
-```
-
-## Development
-
-### Available Scripts
-
-- `npm run build` - Compile TypeScript to JavaScript
-- `npm run gen:spec` - Generate Swagger documentation only
-- `npm run gen:routes` - Generate Express routes only
-- `npm run gen` - Generate both Swagger and routes
-- `npm run example` - Run the example application
-
-### Testing the Library
-
-```bash
-# Generate from example app
-npm run gen
-
-# Run the example server
-npm run example
-```
-
-## How It Works
-
-### 1. Decorators (src/lib/decorators.ts)
-
-Uses **Standard TC39 Decorators** with `context.addInitializer()` to attach metadata:
-
-```typescript
-export function Get(path: string) {
-  return function (originalMethod: any, context: ClassMethodDecoratorContext) {
-    context.addInitializer(function () {
-      // Store route metadata
-      const routes = (this as any)[META_KEY] || [];
-      routes.push({ method: 'get', path, methodName: String(context.name) });
-      (this as any)[META_KEY] = routes;
-    });
-    return originalMethod;
-  };
-}
-```
-
-### 2. Swagger Generator (src/cli/generate-swagger.ts)
-
-Uses **ts-morph** to statically analyze TypeScript code:
-
-- Parses `@Controller` and `@Get`/`@Post` decorators
-- Resolves DTO types including inheritance and generics
-- Converts TypeScript types to JSON Schema
-- Handles union types (enums), nested objects, and Promise unwrapping
-- Generates OpenAPI 3.0 specification
-
-### 3. Route Generator (src/cli/generate-routes.ts)
-
-Generates actual Express route handlers:
-
-```typescript
-// Generated code in src/routes.ts
-app.get('/users/:userId', async (req: Request, res: Response) => {
-    const controller = new UserController();
-    const input: any = {};
-    Object.assign(input, req.query);
-    Object.assign(input, req.params);
-    Object.assign(input, req.body);
-    
-    const response = await controller.getUser(input);
-    res.status(200).json(response);
-});
-```
-
-## Why Standard Decorators?
-
-1. **Future-Proof**: Uses the official TC39 decorator proposal (Stage 3)
-2. **No Experimental Flags**: Works with `"experimentalDecorators": false`
-3. **Better Type Safety**: Leverages TypeScript's type system instead of runtime reflection
-4. **Cleaner API**: Single-parameter DTO pattern is more explicit than parameter decorators
-
-## Comparison with tsoa
-
-| Feature | tsoa (Legacy) | adorn-api |
-|---------|---------------|-----------|
-| Decorators | Experimental (`emitDecoratorMetadata`) | Standard TC39 |
-| Parameter Decorators | `@Body() body: string` | DTO classes with `@FromBody()` |
-| Type Safety | Runtime reflection | Edit-time type checking |
-| Inheritance | Limited | Full support |
-| Generics | Complex | Native TypeScript |
-| Future Compatibility | Deprecated in future TS | Officially supported |
-
-## Next Steps
-
-To make this production-ready:
-
-1. **Validation**: Integrate Zod or class-validator in the route generator
-2. **Error Handling**: Add centralized error handling middleware
-3. **Database Integration**: Add ORM support (Prisma, TypeORM, etc.)
-4. **Testing**: Add unit and integration test utilities
-5. **CORS**: Add CORS configuration
-6. **Rate Limiting**: Add rate limiting middleware
-7. **Logging**: Add structured logging (Winston, Pino)
-
-## License
-
-ISC
+# Adorn API
+Adorn API turns TypeScript classes into HTTP controllers with Stage-3 decorators, then wires Express routes, validation, and OpenAPI docs from the same metadata. It stays small and focused while still supporting MetalORM-backed persistence when you want it.
+
+## Why Adorn API
+- One source of truth: decorators and schemas drive routing, validation, and OpenAPI.
+- Express-native by default, without locking you into a large framework.
+- MetalORM helpers keep DTOs, filters, and entities in sync.
+- Test-first ergonomics with clear e2e coverage of the runtime wiring.
+
+## Features
+- Controller decorators (`@Controller`, `@Get`, `@Post`, etc.) backed by a registry/router that mounts on Express.
+- Built-in OpenAPI generator with optional Swagger UI serving through the Express adapter.
+- MetalORM helpers (`entityDto`, `filtersFromEntity`, `tableDefOf`) to reuse entity metadata for payload validation and database filtering.
+- End-to-end coverage for both direct API handlers and MetalORM REST routes using Vitest + Supertest.
+
+For detailed writeups of each feature, see the companion guides under `docs/`.
+
+## Requirements
+- Node.js v18+
+- SQLite (only for in-memory tests; runtime persistence is pluggable via MetalORM executors)
+
+## Getting started
+1. `npm install` to pull runtime and dev dependencies (Express, MetalORM, Vitest).
+2. `npm run build` to compile the TypeScript sources into `dist/`.
+3. `npm run test` to run the full Vitest suite (unit + integration/e2e tests).
+
+For quick feedback on a single spec file: `npm run test -- test/e2e/metal-orm.adorn-api.rest.spec.ts`.
+
+## Scripts
+- `npm run clean`: removes the `dist` directory.
+- `npm run build`: transpiles `src/**/*.ts` via the `tsconfig.build.json` bundle target.
+- `npm run typecheck`: runs `tsc` with strict settings against `src` + `test`.
+- `npm run check`: runs the decorated-return contract check plus the test suite.
+- `npm run test` / `npm run test:e2e`: run the entire Vitest suite or just the e2e directory.
+
+## MetalORM integration
+- Controllers create `OrmSession` instances with a shared in-memory SQLite executor for tests.
+- DTOs and filter schemas derive directly from `metal-orm` entity definitions via helpers in `src/integrations/metal-orm/schema`.
+- The REST controller examples show how to load entities via `selectFromEntity`, update tracked instances, and rely on `OrmSession` flush/commit semantics without manually writing SQL.
+
+Learn more about MetalORM on npm: https://www.npmjs.com/package/metal-orm
+
+## Project layout
+- `src/`: exports glue code (`express`, `metal-orm`, validation helpers, adapters).
+- `test/e2e/`: Vitest suites exercising the Express and MetalORM API surface.
+- `src/types/metal-orm.d.ts`: local type definitions used while the shared MetalORM package upgrades.
+
+## Next steps
+1. Add real decorators and metadata for your domain models under `src`.
+2. Extend `src/adapters/express` to add middleware or transports as needed.
+3. Hook a persistent MetalORM executor when moving beyond the in-memory SQLite setup used in tests.

package/dist/adapters/express/createApp.d.ts

@@ -0,0 +1,20 @@
+import { type Express } from 'express';
+import type { ControllerCtor } from '../../core/registry/types.js';
+import type { Validator } from '../../contracts/validator.js';
+import { type ApplyRoutesOptions } from './router.js';
+import type { OpenApiBuildOptions } from '../../core/openapi/buildOpenApi.js';
+export type CreateAdornExpressAppOptions = ApplyRoutesOptions & {
+    controllers: ControllerCtor[];
+    mountPath?: string;
+    jsonBodyParser?: boolean;
+    validator?: Validator;
+    openapi?: (OpenApiBuildOptions & {
+        enabled?: boolean;
+        jsonPath?: string;
+        docsPath?: string;
+        swaggerUi?: boolean;
+        swaggerUiConfig?: Record<string, unknown>;
+    });
+};
+export declare function createAdornExpressApp(options: CreateAdornExpressAppOptions): Express;
+//# sourceMappingURL=createApp.d.ts.map

package/dist/adapters/express/createApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createApp.d.ts","sourceRoot":"","sources":["../../../src/adapters/express/createApp.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAgC,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEpF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAG9E,MAAM,MAAM,4BAA4B,GAAG,kBAAkB,GAAG;IAC9D,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB,OAAO,CAAC,EAAE,CAAC,mBAAmB,GAAG;QAC/B,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC3C,CAAC,CAAC;CACJ,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAyCpF"}

package/dist/adapters/express/createApp.js

@@ -0,0 +1,35 @@
+import express, {} from 'express';
+import { buildRegistry } from '../../core/registry/buildRegistry.js';
+import { applyRegistryToExpressRouter } from './router.js';
+import { adornErrorHandler } from './middleware/errorHandler.js';
+import { serveOpenApi } from './swagger/serve.js';
+export function createAdornExpressApp(options) {
+    const app = express();
+    if (options.jsonBodyParser ?? true) {
+        app.use(express.json());
+    }
+    const registry = buildRegistry(options.controllers);
+    const router = express.Router();
+    applyRegistryToExpressRouter(router, registry, options);
+    const oa = options.openapi;
+    if (oa?.enabled ?? true) {
+        if (oa?.title && oa?.version) {
+            const openApiOptions = {
+                title: oa.title,
+                version: oa.version,
+                ...(oa.servers !== undefined ? { servers: oa.servers } : {}),
+            };
+            const serveOptions = {
+                ...(oa.jsonPath !== undefined ? { jsonPath: oa.jsonPath } : {}),
+                ...(oa.docsPath !== undefined ? { docsPath: oa.docsPath } : {}),
+                ...(oa.swaggerUi !== undefined ? { swaggerUi: oa.swaggerUi } : {}),
+                ...(oa.swaggerUiConfig !== undefined ? { swaggerUiConfig: oa.swaggerUiConfig } : {}),
+            };
+            router.use(serveOpenApi(registry, openApiOptions, serveOptions));
+        }
+    }
+    app.use(options.mountPath ?? '/', router);
+    app.use(adornErrorHandler);
+    return app;
+}
+//# sourceMappingURL=createApp.js.map

package/dist/adapters/express/createApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createApp.js","sourceRoot":"","sources":["../../../src/adapters/express/createApp.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAgB,MAAM,SAAS,CAAC;AAGhD,OAAO,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AACrE,OAAO,EAAE,4BAA4B,EAA2B,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEjE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAiBlD,MAAM,UAAU,qBAAqB,CAAC,OAAqC;IACzE,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IAEtB,IAAI,OAAO,CAAC,cAAc,IAAI,IAAI,EAAE,CAAC;QACnC,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAEpD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAChC,4BAA4B,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAExD,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAC3B,IAAI,EAAE,EAAE,OAAO,IAAI,IAAI,EAAE,CAAC;QACxB,IAAI,EAAE,EAAE,KAAK,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC;YAC7B,MAAM,cAAc,GAAwB;gBAC1C,KAAK,EAAE,EAAE,CAAC,KAAK;gBACf,OAAO,EAAE,EAAE,CAAC,OAAO;gBACnB,GAAG,CAAC,EAAE,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC7D,CAAC;YACF,MAAM,YAAY,GAAG;gBACnB,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/D,GAAG,CAAC,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/D,GAAG,CAAC,EAAE,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClE,GAAG,CAAC,EAAE,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACrF,CAAC;YAEF,MAAM,CAAC,GAAG,CACR,YAAY,CACV,QAAQ,EACR,cAAc,EACd,YAAY,CACb,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,GAAG,EAAE,MAAM,CAAC,CAAC;IAC1C,GAAG,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAE3B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/adapters/express/index.d.ts

@@ -0,0 +1,7 @@
+export * from './createApp.js';
+export * from './router.js';
+export * from './transport/request.js';
+export * from './transport/response.js';
+export * from './middleware/errorHandler.js';
+export * from './swagger/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/express/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/express/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}

package/dist/adapters/express/index.js

@@ -0,0 +1,7 @@
+export * from './createApp.js';
+export * from './router.js';
+export * from './transport/request.js';
+export * from './transport/response.js';
+export * from './middleware/errorHandler.js';
+export * from './swagger/index.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/express/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adapters/express/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oBAAoB,CAAC"}

package/dist/adapters/express/middleware/errorHandler.d.ts

@@ -0,0 +1,3 @@
+import type { NextFunction, Request, Response } from 'express';
+export declare function adornErrorHandler(err: unknown, req: Request, res: Response, _next: NextFunction): void;
+//# sourceMappingURL=errorHandler.d.ts.map

package/dist/adapters/express/middleware/errorHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.d.ts","sourceRoot":"","sources":["../../../../src/adapters/express/middleware/errorHandler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG/D,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,QAI/F"}

package/dist/adapters/express/middleware/errorHandler.js

@@ -0,0 +1,6 @@
+import { toProblemDetails } from '../../../core/errors/problem.js';
+export function adornErrorHandler(err, req, res, _next) {
+    const problem = toProblemDetails(err, req.originalUrl || req.path);
+    res.status(problem.status).json(problem);
+}
+//# sourceMappingURL=errorHandler.js.map

package/dist/adapters/express/middleware/errorHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandler.js","sourceRoot":"","sources":["../../../../src/adapters/express/middleware/errorHandler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEnE,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAE,GAAY,EAAE,GAAa,EAAE,KAAmB;IAC9F,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,WAAW,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAEnE,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC"}

package/dist/adapters/express/middleware/requestContext.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=requestContext.d.ts.map

package/dist/adapters/express/middleware/requestContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestContext.d.ts","sourceRoot":"","sources":["../../../../src/adapters/express/middleware/requestContext.ts"],"names":[],"mappings":""}

package/dist/adapters/express/middleware/requestContext.js

@@ -0,0 +1,3 @@
+export {};
+// placeholder for src\adapters\express\middleware\requestContext.ts
+//# sourceMappingURL=requestContext.js.map

package/dist/adapters/express/middleware/requestContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestContext.js","sourceRoot":"","sources":["../../../../src/adapters/express/middleware/requestContext.ts"],"names":[],"mappings":";AAAA,oEAAoE"}

package/dist/adapters/express/router.d.ts

@@ -0,0 +1,10 @@
+import type { Request, Response, Router } from 'express';
+import type { Registry, ControllerCtor } from '../../core/registry/types.js';
+export type ControllerFactory = (ctor: ControllerCtor, req: Request, res: Response) => any;
+export type ApplyRoutesOptions = {
+    lifecycle?: 'singleton' | 'transient';
+    controllerFactory?: ControllerFactory;
+    passContext?: boolean;
+};
+export declare function applyRegistryToExpressRouter(router: Router, registry: Registry, opts?: ApplyRoutesOptions): void;
+//# sourceMappingURL=router.d.ts.map

package/dist/adapters/express/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../src/adapters/express/router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAc,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAUzF,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,KAAK,GAAG,CAAC;AAE3F,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;IACtC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAkCF,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,IAAI,GAAE,kBAAuB,GAC5B,IAAI,CAoFN"}

package/dist/adapters/express/router.js

@@ -0,0 +1,103 @@
+import { createExpressContext } from './transport/request.js';
+import { sendJson, sendReply } from './transport/response.js';
+import { bindArgs } from '../../core/binding/binder.js';
+import { ValidationError } from '../../core/errors/validation-error.js';
+import { isReply } from '../../contracts/reply.js';
+import { pickSuccessStatus } from '../../core/responses/pickStatus.js';
+function toExpressPath(template) {
+    return template.replace(/\{([^}]+)\}/g, (_m, name) => `:${String(name)}`);
+}
+function wrapAsync(fn) {
+    return (req, res, next) => {
+        try {
+            const p = fn(req, res, next);
+            if (p && typeof p.then === 'function')
+                p.catch(next);
+        }
+        catch (e) {
+            next(e);
+        }
+    };
+}
+function methodToExpress(router, method) {
+    switch (method) {
+        case 'GET':
+            return router.get.bind(router);
+        case 'POST':
+            return router.post.bind(router);
+        case 'PUT':
+            return router.put.bind(router);
+        case 'PATCH':
+            return router.patch.bind(router);
+        case 'DELETE':
+            return router.delete.bind(router);
+        default:
+            throw new Error(`Unsupported HTTP method: ${method}`);
+    }
+}
+export function applyRegistryToExpressRouter(router, registry, opts = {}) {
+    const lifecycle = opts.lifecycle ?? 'singleton';
+    const passContext = opts.passContext ?? true;
+    const singletonCache = new Map();
+    const getControllerInstance = (ctor, req, res) => {
+        if (opts.controllerFactory)
+            return opts.controllerFactory(ctor, req, res);
+        if (lifecycle === 'transient')
+            return new ctor();
+        const cached = singletonCache.get(ctor);
+        if (cached)
+            return cached;
+        const created = new ctor();
+        singletonCache.set(ctor, created);
+        return created;
+    };
+    for (const r of registry.routes) {
+        const expressPath = toExpressPath(r.fullPath);
+        const register = methodToExpress(router, r.method);
+        register(expressPath, wrapAsync(async (req, res) => {
+            const controller = getControllerInstance(r.controller, req, res);
+            const handler = controller?.[r.handlerName];
+            if (typeof handler !== 'function') {
+                throw Object.assign(new Error(`Handler not found: ${r.controller.name}.${r.handlerName}`), {
+                    status: 500,
+                });
+            }
+            const ctx = createExpressContext(req, res);
+            const { args, prepared } = bindArgs(r, handler, ctx, {
+                passContext,
+                coerce: 'smart',
+                csv: true,
+            });
+            const validate = r.options?.validate;
+            if (validate?.params) {
+                const res = validate.params.parse(prepared.params, ['params']);
+                if (!res.ok)
+                    throw ValidationError.fromIssues(res.issues, 'Params validation failed');
+                prepared.params = res.value;
+            }
+            if (validate?.query) {
+                const res = validate.query.parse(prepared.query, ['query']);
+                if (!res.ok)
+                    throw ValidationError.fromIssues(res.issues, 'Query validation failed');
+                prepared.query = res.value;
+            }
+            if (validate?.body) {
+                const res = validate.body.parse(prepared.body, ['body']);
+                if (!res.ok)
+                    throw ValidationError.fromIssues(res.issues, 'Body validation failed');
+                prepared.body = res.value;
+            }
+            const result = await handler.apply(controller, args);
+            if (res.headersSent)
+                return;
+            if (isReply(result)) {
+                sendReply(res, result);
+                return;
+            }
+            const routeOptions = (r.options ?? {});
+            const status = pickSuccessStatus(r.method, routeOptions.responses, routeOptions.successStatus);
+            sendJson(res, status, result);
+        }));
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/adapters/express/router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.js","sourceRoot":"","sources":["../../../src/adapters/express/router.ts"],"names":[],"mappings":"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"}

package/dist/adapters/express/swagger/index.d.ts

@@ -0,0 +1,2 @@
+export * from './serve.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/express/swagger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/express/swagger/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/adapters/express/swagger/index.js

@@ -0,0 +1,2 @@
+export * from './serve.js';
+//# sourceMappingURL=index.js.map

package/dist/adapters/express/swagger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/adapters/express/swagger/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/adapters/express/swagger/serve.d.ts

@@ -0,0 +1,12 @@
+import type { Router } from 'express';
+import type { Registry } from '../../../core/registry/types.js';
+import { type OpenApiBuildOptions } from '../../../core/openapi/buildOpenApi.js';
+export type ServeOpenApiOptions = {
+    jsonPath?: string;
+    docsPath?: string;
+    swaggerUi?: boolean;
+    getRegistry?: () => Registry;
+    swaggerUiConfig?: Record<string, unknown>;
+};
+export declare function serveOpenApi(registry: Registry, buildOpts: OpenApiBuildOptions, opts?: ServeOpenApiOptions): Router;
+//# sourceMappingURL=serve.d.ts.map

package/dist/adapters/express/swagger/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../../src/adapters/express/swagger/serve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAqB,MAAM,SAAS,CAAC;AAGzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAgB,KAAK,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AAE/F,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,WAAW,CAAC,EAAE,MAAM,QAAQ,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C,CAAC;AAEF,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,mBAAmB,EAC9B,IAAI,GAAE,mBAAwB,GAC7B,MAAM,CA6DR"}