adorn-api 1.0.0 → 1.0.1

package/src/lib/decorators.ts

@@ -1,136 +0,0 @@
-// 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

@@ -1,238 +0,0 @@
-{
-  "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

@@ -1,72 +0,0 @@
-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

@@ -1,52 +0,0 @@
-// 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

@@ -1,35 +0,0 @@
-// 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

@@ -1,8 +0,0 @@
-// 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

@@ -1,16 +0,0 @@
-// 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

@@ -1,102 +0,0 @@
-/* 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

@@ -1,30 +0,0 @@
-// 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");
-});