adorn-api 1.0.0

package/src/cli/generate-routes.ts

@@ -0,0 +1,123 @@
+// src/cli/generate-routes.ts
+import path from "path";
+import { Project, ClassDeclaration } from "ts-morph";
+import * as fs from "fs";
+
+const PROJECT_ROOT = "./tsconfig.json";
+const OUTPUT_FILE = "./tests/example-app/routes.ts"; // We generate this file!
+
+const project = new Project({ tsConfigFilePath: PROJECT_ROOT });
+
+let routeCode = `/* tslint:disable */
+/* eslint-disable */
+// WARNING: This file was auto-generated by adorn-api. Do not edit.
+import { Express, Request, Response } from 'express';
+`;
+
+// Helper to keep track of imports we need to add to the generated file
+const imports = new Set<string>();
+
+function processController(classDec: ClassDeclaration) {
+  const className = classDec.getName();
+  if (!className) return "";
+
+  // Track import (assuming controllers are in ./controllers/)
+  const sourceFile = classDec.getSourceFile();
+  const exampleAppRoot = path.join(process.cwd(), "tests", "example-app");
+  const relativeDir = path.relative(exampleAppRoot, sourceFile.getDirectoryPath());
+  const relativeSegments = relativeDir ? relativeDir.split(path.sep) : [];
+  const baseName = sourceFile.getBaseName().replace(/\.ts$/, ".js");
+  const importPath = `./${path.posix.join(...relativeSegments, baseName)}`;
+  imports.add(`import { ${className} } from '${importPath}';`);
+
+  const controllerDec = classDec.getDecorators().find(d => d.getName() === "Controller");
+  if (!controllerDec) return "";
+
+  const basePath = controllerDec.getArguments()[0]?.getText().replace(/['"]/g, "") || "/";
+  let methodBlocks = "";
+
+  classDec.getMethods().forEach(method => {
+    const getDec = method.getDecorator("Get");
+    const postDec = method.getDecorator("Post");
+    const putDec = method.getDecorator("Put");
+    const deleteDec = method.getDecorator("Delete");
+    const decorator = getDec || postDec || putDec || deleteDec;
+    if (!decorator) return;
+
+    const httpMethod = getDec ? "get" : postDec ? "post" : putDec ? "put" : "delete";
+    const pathArg = decorator.getArguments()[0]?.getText().replace(/['"]/g, "") || "/";
+    const fullPath = `/${basePath}${pathArg}`.replace("//", "/").replace(/{/g, ":").replace(/}/g, ""); // Convert {id} to :id for Express
+
+    const methodName = method.getName();
+    const params = method.getParameters();
+    
+    // Authentication check
+    const authDec = method.getDecorator("Authorized");
+    const controllerAuthDec = classDec.getDecorator("Authorized");
+    const hasAuth = !!authDec || !!controllerAuthDec;
+    const middlewareArgs = hasAuth ? "authenticationMiddleware, " : "";
+    
+    // Logic to instantiate the DTO
+    let paramInstantiation = "";
+    if (params.length > 0) {
+      const paramName = params[0].getName();
+      const paramType = params[0].getType().getSymbol()?.getName();
+      
+      // We assume the DTO is a class we can instantiate, or a shape we construct
+      // Here we map request parts to the DTO
+      paramInstantiation = `
+        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'
+      `;
+    }
+
+    methodBlocks += `
+    app.${httpMethod}('${fullPath}', ${middlewareArgs}async (req: Request, res: Response) => {
+        const controller = new ${className}();
+        try {
+            ${paramInstantiation}
+            const response = await controller.${methodName}(${params.length > 0 ? 'input' : ''});
+            res.status(200).json(response);
+        } catch (err: any) {
+            console.error(err);
+            res.status(500).send(err.message);
+        }
+    });
+    `;
+  });
+
+  return methodBlocks;
+}
+
+const sourceFiles = project.getSourceFiles("tests/example-app/controllers/**/*.ts");
+let allRoutes = "";
+
+sourceFiles.forEach(file => {
+  file.getClasses().forEach(c => {
+    allRoutes += processController(c);
+  });
+});
+
+// Add authentication middleware import if needed
+if (allRoutes.includes('authenticationMiddleware')) {
+  routeCode += `import { authenticationMiddleware } from './middleware/auth.middleware.js';\n`;
+}
+
+// Prepend imports
+routeCode += Array.from(imports).join('\n');
+routeCode += `
+
+export function RegisterRoutes(app: Express) {
+    ${allRoutes}
+}
+`;
+
+fs.writeFileSync(OUTPUT_FILE, routeCode);
+console.log(`✅ Generated Routes at ${OUTPUT_FILE}`);

package/src/cli/generate-swagger.ts

@@ -0,0 +1,216 @@
+// src/cli/generate-swagger.ts
+import { Project, Type, SyntaxKind, ClassDeclaration, Symbol as MorphSymbol, PropertyDeclaration } from "ts-morph";
+import * as fs from "fs";
+
+const PROJECT_ROOT = "./tsconfig.json";
+const OUTPUT_FILE = "./swagger.json";
+
+const project = new Project({ tsConfigFilePath: PROJECT_ROOT });
+
+const openApiSpec: any = {
+  openapi: "3.0.0",
+  info: { title: "Adorn API", version: "2.0.0" },
+  paths: {},
+  components: { 
+    schemas: {},
+    securitySchemes: {
+      bearerAuth: {
+        type: "http",
+        scheme: "bearer",
+        bearerFormat: "JWT"
+      }
+    }
+  },
+};
+
+// --- Helper: Deep Type Resolver ---
+// This converts TypeScript Types (Generics, Interfaces, Primitives) into JSON Schema
+function resolveSchema(type: Type, collectedSchemas: Record<string, any>): any {
+  // 1. Handle Primitives
+  if (type.isString() || type.isStringLiteral()) return { type: "string" };
+  if (type.isNumber() || type.isNumberLiteral()) return { type: "integer" };
+  if (type.isBoolean() || type.isBooleanLiteral()) return { type: "boolean" };
+  if (type.isArray()) {
+    const arrayType = type.getArrayElementType();
+    return {
+      type: "array",
+      items: arrayType ? resolveSchema(arrayType, collectedSchemas) : {},
+    };
+  }
+
+  // 2. Handle Union Types (Enums)
+  if (type.isUnion()) {
+    const unionTypes = type.getUnionTypes();
+    
+    // Extract literal values (e.g., "active", 100)
+    const literals = unionTypes
+      .map(t => t.isLiteral() ? t.getLiteralValue() : null)
+      .filter(val => val !== null);
+
+    // If we found literals, it's an Enum
+    if (literals.length > 0) {
+      const isString = typeof literals[0] === 'string';
+      return {
+        type: isString ? 'string' : 'integer',
+        enum: literals
+      };
+    }
+    
+    // If it's a mix of objects (e.g. User | Admin), OpenApi uses 'oneOf'
+    // Simplified for this demo: take the first non-null type
+    return resolveSchema(unionTypes[0], collectedSchemas);
+  }
+
+  // 3. Handle Objects (Classes, Interfaces, Nested Literals)
+  if (type.isObject()) {
+    // Recursion Guard: If we've seen this type name before in components, reference it!
+    // (This prevents infinite loops and reduces swagger size)
+    const symbol = type.getSymbol();
+    const typeName = symbol?.getName();
+    
+    // Common excluded types
+    if (typeName === "Promise") {
+        return resolveSchema(type.getTypeArguments()[0], collectedSchemas);
+    }
+    if (typeName === "Date") return { type: "string", format: "date-time" };
+
+    // If it's a named class/interface (e.g. "Address"), and we haven't processed it, 
+    // we could add it to components.schemas. For now, we inline it for simplicity.
+    
+    const properties = type.getProperties();
+    const schema: any = { type: "object", properties: {}, required: [] };
+
+    properties.forEach((prop) => {
+      const propName = prop.getName();
+      if (propName.startsWith("_")) return; // Skip privates
+
+      // Get the type of the property using getTypeAtLocation
+      const declarations = prop.getDeclarations();
+      if (declarations.length > 0) {
+        const propType = prop.getTypeAtLocation(declarations[0]);
+        
+        if (propType) {
+          // RECURSION HERE: Pass the property type back into resolveSchema
+          schema.properties[propName] = resolveSchema(propType, collectedSchemas);
+          
+          if (!prop.isOptional()) {
+            schema.required.push(propName);
+          }
+        }
+      }
+    });
+
+    return schema;
+  }
+
+  return { type: "string" }; // Fallback
+}
+
+function processController(classDec: ClassDeclaration) {
+  const controllerDec = classDec.getDecorators().find((d) => d.getName() === "Controller");
+  if (!controllerDec) return;
+
+  const basePath = controllerDec.getArguments()[0]?.getText().replace(/['"]/g, "") || "/";
+
+  classDec.getMethods().forEach((method) => {
+    const getDec = method.getDecorator("Get");
+    const postDec = method.getDecorator("Post");
+    const putDec = method.getDecorator("Put");
+    const deleteDec = method.getDecorator("Delete");
+    const decorator = getDec || postDec || putDec || deleteDec;
+    if (!decorator) return;
+
+    const httpMethod = getDec ? "get" : postDec ? "post" : putDec ? "put" : "delete";
+    const pathArg = decorator.getArguments()[0]?.getText().replace(/['"]/g, "") || "/";
+    const fullPath = `/${basePath}${pathArg}`.replace("//", "/");
+
+    const parameters: any[] = [];
+    const requestBody: any = { content: {} };
+
+    // --- 1. Request Analysis (Input DTOs) ---
+    const params = method.getParameters();
+    if (params.length > 0) {
+      const param = params[0];
+      const paramType = param.getType(); // This resolves generics and inheritance!
+      
+      // Iterate ALL properties of the type (inherited included)
+      paramType.getProperties().forEach(prop => {
+        const propName = prop.getName();
+        
+        // We need to check Decorators. 
+        // Note: In mapped types/generics, getting decorators is hard.
+        // We fallback to checking the source declaration.
+        const declarations = prop.getDeclarations();
+        let isQuery = false;
+        let isBody = false;
+        let isPath = false;
+
+        // Check decorators on the definition
+        declarations.forEach(decl => {
+            if (decl.getKind() === SyntaxKind.PropertyDeclaration) {
+                const pDecl = decl as PropertyDeclaration;
+                if (pDecl.getDecorator("FromQuery")) isQuery = true;
+                if (pDecl.getDecorator("FromPath")) isPath = true;
+                if (pDecl.getDecorator("FromBody")) isBody = true;
+            }
+        });
+
+        // IMPLICIT RULES:
+        // If it's a GET, and not path, default to Query.
+        // If it's a POST, and not path/query, default to Body.
+        if (!isQuery && !isPath && !isBody) {
+            if (httpMethod === "get") isQuery = true;
+            else isBody = true;
+        }
+
+        const propType = prop.getTypeAtLocation(param.getSourceFile());
+        const propTypeSchema = resolveSchema(propType, openApiSpec.components.schemas);
+
+        if (isPath) {
+            parameters.push({ name: propName, in: "path", required: true, schema: propTypeSchema });
+        } else if (isQuery) {
+            parameters.push({ name: propName, in: "query", required: !prop.isOptional(), schema: propTypeSchema });
+        } else if (isBody) {
+             if (!requestBody.content["application/json"]) {
+                 requestBody.content["application/json"] = { schema: { type: "object", properties: {}, required: [] } };
+              }
+              const bodySchema = requestBody.content["application/json"].schema;
+              bodySchema.properties[propName] = propTypeSchema;
+              if (!prop.isOptional()) bodySchema.required.push(propName);
+        }
+      });
+    }
+
+    // --- 2. Authentication Check ---
+    const authDec = method.getDecorator("Authorized");
+    const controllerAuthDec = classDec.getDecorator("Authorized");
+
+    const isAuth = !!authDec || !!controllerAuthDec;
+
+    // --- 3. Response Analysis (Return Type) ---
+    const returnType = method.getReturnType(); // e.g. Promise<EntityResponse<User>>
+    const responseSchema = resolveSchema(returnType, openApiSpec.components.schemas);
+
+    if (!openApiSpec.paths[fullPath]) openApiSpec.paths[fullPath] = {};
+    openApiSpec.paths[fullPath][httpMethod] = {
+      operationId: method.getName(),
+      parameters,
+      requestBody: Object.keys(requestBody.content).length ? requestBody : undefined,
+      security: isAuth ? [{ bearerAuth: [] }] : undefined,
+      responses: {
+        200: {
+          description: "Success",
+          content: {
+            "application/json": { schema: responseSchema }
+          }
+        }
+      }
+    };
+  });
+}
+
+console.log("🔍 Scanning...");
+const sourceFiles = project.getSourceFiles("tests/example-app/**/*.ts");
+sourceFiles.forEach(file => file.getClasses().forEach(processController));
+fs.writeFileSync(OUTPUT_FILE, JSON.stringify(openApiSpec, null, 2));
+console.log(`✅ Generated ${OUTPUT_FILE}`);

package/src/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// src/index.ts
+// Main entry point for adorn-api library
+__exportStar(require("./lib/decorators.js"), exports);
+__exportStar(require("./lib/common.js"), exports);

package/src/index.ts

@@ -0,0 +1,4 @@
+// src/index.ts
+// Main entry point for adorn-api library
+export * from "./lib/decorators.js";
+export * from "./lib/common.js";

package/src/lib/common.js

@@ -0,0 +1,68 @@
+"use strict";
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaginationQuery = void 0;
+// src/lib/common.ts
+var decorators_js_1 = require("./decorators.js");
+// --- 2. Pagination Logic ---
+// We need a Concrete Class for Pagination because it carries Metadata (@FromQuery)
+var PaginationQuery = function () {
+    var _a;
+    var _page_decorators;
+    var _page_initializers = [];
+    var _page_extraInitializers = [];
+    var _limit_decorators;
+    var _limit_initializers = [];
+    var _limit_extraInitializers = [];
+    return _a = /** @class */ (function () {
+            function PaginationQuery() {
+                this.page = __runInitializers(this, _page_initializers, 1);
+                this.limit = (__runInitializers(this, _page_extraInitializers), __runInitializers(this, _limit_initializers, 20));
+                __runInitializers(this, _limit_extraInitializers);
+            }
+            return PaginationQuery;
+        }()),
+        (function () {
+            var _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _page_decorators = [(0, decorators_js_1.FromQuery)()];
+            _limit_decorators = [(0, decorators_js_1.FromQuery)()];
+            __esDecorate(null, null, _page_decorators, { kind: "field", name: "page", static: false, private: false, access: { has: function (obj) { return "page" in obj; }, get: function (obj) { return obj.page; }, set: function (obj, value) { obj.page = value; } }, metadata: _metadata }, _page_initializers, _page_extraInitializers);
+            __esDecorate(null, null, _limit_decorators, { kind: "field", name: "limit", static: false, private: false, access: { has: function (obj) { return "limit" in obj; }, get: function (obj) { return obj.limit; }, set: function (obj, value) { obj.limit = value; } }, metadata: _metadata }, _limit_initializers, _limit_extraInitializers);
+            if (_metadata) Object.defineProperty(_a, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        })(),
+        _a;
+}();
+exports.PaginationQuery = PaginationQuery;

package/src/lib/common.ts

@@ -0,0 +1,35 @@
+// src/lib/common.ts
+import { FromQuery } from "./decorators.js";
+
+// --- 1. Generic Response Wrappers ---
+
+// Helper to clean up intersection types in tooltips/logs
+export type Jsonify<T> = { [K in keyof T]: T[K] } & {};
+
+export type EntityResponse<TEntity> = Jsonify<TEntity>;
+
+// --- 2. Pagination Logic ---
+
+// We need a Concrete Class for Pagination because it carries Metadata (@FromQuery)
+export class PaginationQuery {
+  @FromQuery()
+  page: number = 1;
+
+  @FromQuery()
+  limit: number = 20;
+}
+
+// The generic type for list queries
+export type ListQuery<TFilters extends object = object> = PaginationQuery & TFilters;
+
+// --- 3. CRUD Input Helpers ---
+// Note: You cannot "extend" these Mapped Types in a class directly in TS.
+// These are best used for Type Checking interfaces or Return Types.
+
+export type CreateInput<
+  TEntityJson extends object,
+  TRequiredKeys extends keyof TEntityJson,
+  TOptionalKeys extends keyof TEntityJson = never,
+> = Pick<TEntityJson, TRequiredKeys> & Partial<Pick<TEntityJson, TOptionalKeys>>;
+
+export type UpdateInput<TCreateInput> = Partial<TCreateInput>;

package/src/lib/decorators.js

@@ -0,0 +1,128 @@
+"use strict";
+// src/lib/decorators.ts
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_META = exports.SCHEMA_META = void 0;
+exports.Get = Get;
+exports.Post = Post;
+exports.Put = Put;
+exports.Delete = Delete;
+exports.Controller = Controller;
+exports.FromQuery = FromQuery;
+exports.FromPath = FromPath;
+exports.FromBody = FromBody;
+exports.Authorized = Authorized;
+// Context metadata symbol for standard decorators
+var META_KEY = Symbol('adorn:route');
+exports.SCHEMA_META = Symbol('adorn:schema');
+exports.AUTH_META = Symbol('adorn:auth');
+// -- Method Decorator --
+// Using Standard TC39 Signature
+function Get(path) {
+    return function (originalMethod, context) {
+        // In standard decorators, we can attach metadata to the class prototype via context
+        context.addInitializer(function () {
+            var routes = this[META_KEY] || [];
+            routes.push({
+                method: 'get',
+                path: path,
+                methodName: String(context.name),
+            });
+            this[META_KEY] = routes;
+        });
+        return originalMethod;
+    };
+}
+function Post(path) {
+    return function (originalMethod, context) {
+        context.addInitializer(function () {
+            var routes = this[META_KEY] || [];
+            routes.push({
+                method: 'post',
+                path: path,
+                methodName: String(context.name),
+            });
+            this[META_KEY] = routes;
+        });
+        return originalMethod;
+    };
+}
+function Put(path) {
+    return function (originalMethod, context) {
+        context.addInitializer(function () {
+            var routes = this[META_KEY] || [];
+            routes.push({
+                method: 'put',
+                path: path,
+                methodName: String(context.name),
+            });
+            this[META_KEY] = routes;
+        });
+        return originalMethod;
+    };
+}
+function Delete(path) {
+    return function (originalMethod, context) {
+        context.addInitializer(function () {
+            var routes = this[META_KEY] || [];
+            routes.push({
+                method: 'delete',
+                path: path,
+                methodName: String(context.name),
+            });
+            this[META_KEY] = routes;
+        });
+        return originalMethod;
+    };
+}
+// -- Class Decorator --
+function Controller(basePath) {
+    return function (target, context) {
+        // We attach the base path to the class constructor
+        context.addInitializer(function () {
+            this._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 }
+function FromQuery(name) {
+    return function (target, context) {
+        context.addInitializer(function () {
+            var meta = this[exports.SCHEMA_META] || {};
+            meta[context.name] = { type: 'query' };
+            this[exports.SCHEMA_META] = meta;
+        });
+        return function (initialValue) { return initialValue; };
+    };
+}
+function FromPath(name) {
+    return function (target, context) {
+        context.addInitializer(function () {
+            var meta = this[exports.SCHEMA_META] || {};
+            meta[context.name] = { type: 'path' };
+            this[exports.SCHEMA_META] = meta;
+        });
+        return function (initialValue) { return initialValue; };
+    };
+}
+function FromBody() {
+    return function (target, context) {
+        context.addInitializer(function () {
+            var meta = this[exports.SCHEMA_META] || {};
+            meta[context.name] = { type: 'body' };
+            this[exports.SCHEMA_META] = meta;
+        });
+        return function (initialValue) { return initialValue; };
+    };
+}
+// -- Authentication Decorator --
+function Authorized(role) {
+    return function (target, context) {
+        context.addInitializer(function () {
+            this[exports.AUTH_META] = role || 'default';
+        });
+        return target;
+    };
+}