adorn-api 1.0.0

package/src/lib/decorators.ts

@@ -0,0 +1,136 @@
+// src/lib/decorators.ts
+
+// 1. HTTP Methods
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete';
+
+// Context metadata symbol for standard decorators
+const META_KEY = Symbol('adorn:route');
+export const SCHEMA_META = Symbol('adorn:schema');
+export const AUTH_META = Symbol('adorn:auth');
+
+export interface RouteDefinition {
+  method: HttpMethod;
+  path: string;
+  methodName: string;
+}
+
+// -- Method Decorator --
+// Using Standard TC39 Signature
+export function Get(path: string) {
+  return function (originalMethod: any, context: ClassMethodDecoratorContext) {
+    // In standard decorators, we can attach metadata to the class prototype via context
+    context.addInitializer(function () {
+      const routes: RouteDefinition[] = (this as any)[META_KEY] || [];
+      routes.push({
+        method: 'get',
+        path,
+        methodName: String(context.name),
+      });
+      (this as any)[META_KEY] = routes;
+    });
+    return originalMethod;
+  };
+}
+
+export function Post(path: string) {
+  return function (originalMethod: any, context: ClassMethodDecoratorContext) {
+    context.addInitializer(function () {
+      const routes: RouteDefinition[] = (this as any)[META_KEY] || [];
+      routes.push({
+        method: 'post',
+        path,
+        methodName: String(context.name),
+      });
+      (this as any)[META_KEY] = routes;
+    });
+    return originalMethod;
+  };
+}
+
+export function Put(path: string) {
+  return function (originalMethod: any, context: ClassMethodDecoratorContext) {
+    context.addInitializer(function () {
+      const routes: RouteDefinition[] = (this as any)[META_KEY] || [];
+      routes.push({
+        method: 'put',
+        path,
+        methodName: String(context.name),
+      });
+      (this as any)[META_KEY] = routes;
+    });
+    return originalMethod;
+  };
+}
+
+export function Delete(path: string) {
+  return function (originalMethod: any, context: ClassMethodDecoratorContext) {
+    context.addInitializer(function () {
+      const routes: RouteDefinition[] = (this as any)[META_KEY] || [];
+      routes.push({
+        method: 'delete',
+        path,
+        methodName: String(context.name),
+      });
+      (this as any)[META_KEY] = routes;
+    });
+    return originalMethod;
+  };
+}
+
+// -- Class Decorator --
+export function Controller(basePath: string) {
+  return function (target: any, context: ClassDecoratorContext) {
+    // We attach the base path to the class constructor
+    context.addInitializer(function () {
+      (this as any)._basePath = basePath;
+    });
+    return target;
+  };
+}
+
+// -- DTO Field Decorators --
+// Since we can't decorate parameters, we decorate fields in a class
+// e.g. class GetUserParams { @FromPath id: string }
+
+export function FromQuery(name?: string) {
+  return function (target: undefined, context: ClassFieldDecoratorContext) {
+    context.addInitializer(function () {
+      const meta = (this as any)[SCHEMA_META] || {};
+      meta[context.name] = { type: 'query' };
+      (this as any)[SCHEMA_META] = meta;
+    });
+    return function (initialValue: any) { return initialValue; };
+  };
+}
+
+export function FromPath(name?: string) {
+  return function (target: undefined, context: ClassFieldDecoratorContext) {
+    context.addInitializer(function () {
+      const meta = (this as any)[SCHEMA_META] || {};
+      meta[context.name] = { type: 'path' };
+      (this as any)[SCHEMA_META] = meta;
+    });
+    return function (initialValue: any) { return initialValue; };
+  };
+}
+
+export function FromBody() {
+  return function (target: undefined, context: ClassFieldDecoratorContext) {
+    context.addInitializer(function () {
+      const meta = (this as any)[SCHEMA_META] || {};
+      meta[context.name] = { type: 'body' };
+      (this as any)[SCHEMA_META] = meta;
+    });
+    return function (initialValue: any) { return initialValue; };
+  };
+}
+
+// -- Authentication Decorator --
+export function Authorized(role?: string) {
+  return function (target: any, context: ClassMethodDecoratorContext | ClassDecoratorContext) {
+    context.addInitializer(function () {
+      (this as any)[AUTH_META] = role || 'default';
+    });
+    return target;
+  };
+}

package/swagger.json

@@ -0,0 +1,238 @@
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "Adorn API",
+    "version": "2.0.0"
+  },
+  "paths": {
+    "/advanced/{tenantId}/users": {
+      "get": {
+        "operationId": "listUsers",
+        "parameters": [
+          {
+            "name": "search",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "tenantId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "page",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer"
+            }
+          },
+          {
+            "name": "limit",
+            "in": "query",
+            "required": true,
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": {
+                        "type": "string"
+                      },
+                      "name": {
+                        "type": "string"
+                      },
+                      "email": {
+                        "type": "string"
+                      },
+                      "isActive": {
+                        "type": "boolean"
+                      },
+                      "createdAt": {
+                        "type": "string"
+                      }
+                    },
+                    "required": [
+                      "id",
+                      "name",
+                      "email",
+                      "isActive",
+                      "createdAt"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/advanced/": {
+      "post": {
+        "operationId": "create",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "email": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "name",
+                  "email"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "name": {
+                      "type": "string"
+                    },
+                    "email": {
+                      "type": "string"
+                    },
+                    "isActive": {
+                      "type": "boolean"
+                    },
+                    "createdAt": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "name",
+                    "email",
+                    "isActive",
+                    "createdAt"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/users/{userId}": {
+      "get": {
+        "operationId": "getUser",
+        "parameters": [
+          {
+            "name": "userId",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "details",
+            "in": "query",
+            "required": false,
+            "schema": {
+              "type": "integer",
+              "enum": [
+                null,
+                null
+              ]
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/users/": {
+      "post": {
+        "operationId": "createUser",
+        "parameters": [],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string"
+                  },
+                  "email": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "name",
+                  "email"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {},
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
+      }
+    }
+  }
+}

package/tests/e2e.test.ts

@@ -0,0 +1,72 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { spawn, ChildProcessWithoutNullStreams } from "node:child_process";
+import path from "node:path";
+import { projectRoot, runTsNodeScript } from "./utils.js";
+
+const BASE_URL = "http://localhost:3000";
+
+let serverProcess: ChildProcessWithoutNullStreams | undefined;
+
+beforeAll(
+  async () => {
+    await runTsNodeScript("src/cli/generate-swagger.ts");
+    await runTsNodeScript("src/cli/generate-routes.ts");
+    serverProcess = spawn(process.execPath, [path.join(projectRoot, "scripts", "run-example.js")], {
+      cwd: projectRoot,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    await waitForServerReady(serverProcess);
+  },
+  30000
+);
+
+afterAll(() => {
+  if (serverProcess && !serverProcess.killed) {
+    serverProcess.kill();
+  }
+});
+
+describe("adorn-api example server", () => {
+  it("lists users from the advanced endpoint", async () => {
+    const response = await fetch(`${BASE_URL}/advanced/tenant-12/users?page=1&limit=5`);
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(Array.isArray(body)).toBe(true);
+    expect(body[0]).toMatchObject({
+      id: "1",
+      name: "Alice",
+    });
+  });
+
+  it("returns user details from the user controller", async () => {
+    const response = await fetch(`${BASE_URL}/users/abc?details=true`);
+    expect(response.status).toBe(200);
+    const text = await response.text();
+    expect(text).toContain("Getting user abc");
+    expect(text).toContain("details: true");
+  });
+});
+
+async function waitForServerReady(proc: ChildProcessWithoutNullStreams, timeoutMs = 20000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (proc.exitCode !== null) {
+      throw new Error("Example server exited before becoming ready");
+    }
+
+    try {
+      const response = await fetch(`${BASE_URL}/docs`);
+      if (response.ok) {
+        await response.text();
+        return;
+      }
+    } catch {
+      // ignore errors while the server is starting
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+
+  throw new Error("Timed out waiting for the example server to become ready");
+}

package/tests/example-app/controllers/advanced.controller.ts

@@ -0,0 +1,52 @@
+// src/controllers/advanced.controller.ts
+import { Controller, Get, Post, FromBody, FromPath, PaginationQuery, EntityResponse, CreateInput } from "../../../src/index.js";
+import { User } from "../entities/user.entity.js";
+
+// --- 1. Advanced Request DTOs ---
+
+// INHERITANCE: UserListRequest automatically gets 'page' and 'limit' from PaginationQuery
+// AND the generator will find them because we scan the Type properties.
+export class UserListRequest extends PaginationQuery {
+  // Implicitly @FromQuery because it's a GET request and extends a class
+  search?: string; 
+  
+  @FromPath()
+  tenantId!: string;
+}
+
+// COMPOSITION: Using the Type Helper for safety, but class for Decorators
+// We implement the Type Helper to ensure our Class matches the Entity rule
+export class CreateUserDto implements CreateInput<User, 'name' | 'email'> {
+  @FromBody()
+  name!: string;
+
+  @FromBody()
+  email!: string;
+  
+  // If I miss a field here that is required in CreateInput, TS throws an error at edit time.
+}
+
+// --- 2. The Controller ---
+
+@Controller("advanced")
+export class AdvancedController {
+
+  @Get("/{tenantId}/users")
+  // Generic Return Type: The generator must resolve EntityResponse<User[]> -> User schema
+  public async listUsers(req: UserListRequest): Promise<EntityResponse<User[]>> {
+    return [
+      { id: "1", name: "Alice", email: "a@a.com", isActive: true, createdAt: "now" }
+    ];
+  }
+
+  @Post("/")
+  public async create(req: CreateUserDto): Promise<EntityResponse<User>> {
+    return { 
+        id: "123", 
+        name: req.name, 
+        email: req.email, 
+        isActive: true, 
+        createdAt: "now" 
+    };
+  }
+}

package/tests/example-app/controllers/user.controller.ts

@@ -0,0 +1,35 @@
+// src/controllers/user.controller.ts
+import { Controller, Get, Post, FromQuery, FromPath, FromBody } from "../../../src/index.js";
+
+// --- DTO Definitions (The substitute for Parameter Decorators) ---
+export class GetUserRequest {
+  @FromPath()
+  userId!: string;
+  
+  @FromQuery()
+  details?: boolean;
+}
+
+export class CreateUserRequest {
+  @FromBody()
+  name!: string;
+
+  @FromBody()
+  email!: string;
+}
+
+// --- The Controller ---
+@Controller("users")
+export class UserController {
+
+  // Strong typing: 'req' is checked at edit time.
+  @Get("/{userId}")
+  public async getUser(req: GetUserRequest): Promise<string> {
+    return `Getting user ${req.userId} with details: ${req.details}`;
+  }
+
+  @Post("/")
+  public async createUser(req: CreateUserRequest): Promise<void> {
+    console.log(`Creating user ${req.name}`);
+  }
+}

package/tests/example-app/entities/user.entity.ts

@@ -0,0 +1,8 @@
+// src/entities/user.entity.ts
+export interface User {
+  id: string;
+  name: string;
+  email: string;
+  isActive: boolean;
+  createdAt: string;
+}

package/tests/example-app/middleware/auth.middleware.ts

@@ -0,0 +1,16 @@
+// src/middleware/auth.middleware.ts
+import { Request, Response, NextFunction } from "express";
+
+export function authenticationMiddleware(req: Request, res: Response, next: NextFunction) {
+  const token = req.headers.authorization;
+  if (!token) {
+    res.status(401).json({ message: "No token provided" });
+    return;
+  }
+  
+  if (token === "Bearer secret") {
+    next();
+  } else {
+    res.status(403).json({ message: "Invalid token" });
+  }
+}

package/tests/example-app/routes.ts

@@ -0,0 +1,102 @@
+/* tslint:disable */
+/* eslint-disable */
+// WARNING: This file was auto-generated by adorn-api. Do not edit.
+import { Express, Request, Response } from 'express';
+import { UserListRequest } from './controllers/advanced.controller.js';
+import { CreateUserDto } from './controllers/advanced.controller.js';
+import { AdvancedController } from './controllers/advanced.controller.js';
+import { GetUserRequest } from './controllers/user.controller.js';
+import { CreateUserRequest } from './controllers/user.controller.js';
+import { UserController } from './controllers/user.controller.js';
+
+export function RegisterRoutes(app: Express) {
+    
+    app.get('/advanced/:tenantId/users', async (req: Request, res: Response) => {
+        const controller = new AdvancedController();
+        try {
+            
+        const input: any = {};
+        // Map Query
+        Object.assign(input, req.query);
+        // Map Params
+        Object.assign(input, req.params);
+        // Map Body
+        Object.assign(input, req.body);
+        
+        // In a real app, you would run 'zod' or 'class-validator' here on 'input'
+      
+            const response = await controller.listUsers(input);
+            res.status(200).json(response);
+        } catch (err: any) {
+            console.error(err);
+            res.status(500).send(err.message);
+        }
+    });
+    
+    app.post('/advanced/', async (req: Request, res: Response) => {
+        const controller = new AdvancedController();
+        try {
+            
+        const input: any = {};
+        // Map Query
+        Object.assign(input, req.query);
+        // Map Params
+        Object.assign(input, req.params);
+        // Map Body
+        Object.assign(input, req.body);
+        
+        // In a real app, you would run 'zod' or 'class-validator' here on 'input'
+      
+            const response = await controller.create(input);
+            res.status(200).json(response);
+        } catch (err: any) {
+            console.error(err);
+            res.status(500).send(err.message);
+        }
+    });
+    
+    app.get('/users/:userId', async (req: Request, res: Response) => {
+        const controller = new UserController();
+        try {
+            
+        const input: any = {};
+        // Map Query
+        Object.assign(input, req.query);
+        // Map Params
+        Object.assign(input, req.params);
+        // Map Body
+        Object.assign(input, req.body);
+        
+        // In a real app, you would run 'zod' or 'class-validator' here on 'input'
+      
+            const response = await controller.getUser(input);
+            res.status(200).json(response);
+        } catch (err: any) {
+            console.error(err);
+            res.status(500).send(err.message);
+        }
+    });
+    
+    app.post('/users/', async (req: Request, res: Response) => {
+        const controller = new UserController();
+        try {
+            
+        const input: any = {};
+        // Map Query
+        Object.assign(input, req.query);
+        // Map Params
+        Object.assign(input, req.params);
+        // Map Body
+        Object.assign(input, req.body);
+        
+        // In a real app, you would run 'zod' or 'class-validator' here on 'input'
+      
+            const response = await controller.createUser(input);
+            res.status(200).json(response);
+        } catch (err: any) {
+            console.error(err);
+            res.status(500).send(err.message);
+        }
+    });
+    
+}

package/tests/example-app/server.ts

@@ -0,0 +1,30 @@
+// tests/example-app/server.ts
+// Example Express server using adorn-api
+import express, { Express } from "express";
+import bodyParser from "body-parser";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import swaggerUi from "swagger-ui-express";
+
+// Import generated routes
+import { RegisterRoutes } from "./routes.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const app: Express = express();
+
+app.use(bodyParser.json());
+
+// Register the Generated Routes
+RegisterRoutes(app);
+
+// Serve Swagger UI
+const swaggerDoc = JSON.parse(readFileSync(join(__dirname, "../../swagger.json"), "utf-8"));
+app.use("/docs", swaggerUi.serve, swaggerUi.setup(swaggerDoc));
+
+app.listen(3000, () => {
+  console.log("🚀 Example server running on http://localhost:3000");
+  console.log("📄 Swagger running on http://localhost:3000/docs");
+});