@aetherionfw/docs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Londoño
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/builder/OpenApiBuilder.d.ts

@@ -0,0 +1,3 @@
+export declare class OpenApiBuilder {
+    build(title: string, version?: string): any;
+}

package/dist/builder/OpenApiBuilder.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenApiBuilder = void 0;
+const core_1 = require("@aetherionfw/core");
+const DocsRegistry_1 = require("../registry/DocsRegistry");
+class OpenApiBuilder {
+    build(title, version = '1.0.0') {
+        const metaRegistry = core_1.MetadataRegistry.getInstance();
+        const docsRegistry = DocsRegistry_1.DocsRegistry.getInstance();
+        const openapi = {
+            openapi: '3.0.0',
+            info: { title, version },
+            paths: {},
+            components: {
+                schemas: {}
+            }
+        };
+        // 1. Build Schemas
+        const schemas = docsRegistry.getSchemas();
+        for (const [target, properties] of schemas) {
+            const schemaName = target.name;
+            const requiredProps = [];
+            const propertiesObj = {};
+            for (const prop of properties) {
+                propertiesObj[prop.name] = {
+                    type: prop.type,
+                    description: prop.description,
+                    example: prop.example
+                };
+                if (prop.required !== false) {
+                    requiredProps.push(prop.name);
+                }
+            }
+            openapi.components.schemas[schemaName] = {
+                type: 'object',
+                properties: propertiesObj,
+                required: requiredProps.length > 0 ? requiredProps : undefined
+            };
+        }
+        // 2. Build Paths & Operations
+        const controllers = metaRegistry.getControllers();
+        for (const [target, _] of controllers) {
+            const tagMeta = docsRegistry.getTag(target);
+            const routes = metaRegistry.getRoutes(target);
+            // In a real implementation we would map route -> prototype method name.
+            // For this simplified version, let's assume route paths are properly mapped
+            // and we just try to find the matching documentation via a heuristic (or the stored method name).
+            const prototype = target.prototype;
+            const methods = Object.getOwnPropertyNames(prototype).filter(m => m !== 'constructor');
+            for (const method of methods) {
+                // Did @Route tag this method?
+                const routeMeta = Reflect.getMetadata('route', prototype, method);
+                if (routeMeta && routeMeta.path && routeMeta.method) {
+                    const path = routeMeta.path;
+                    const httpMethod = routeMeta.method.toLowerCase();
+                    if (!openapi.paths[path]) {
+                        openapi.paths[path] = {};
+                    }
+                    const opMeta = docsRegistry.getOperation(target, method) || { summary: method };
+                    const responsesMeta = docsRegistry.getResponses(target, method);
+                    const responsesObj = {};
+                    if (responsesMeta.length === 0) {
+                        responsesObj['200'] = { description: 'Success' };
+                    }
+                    else {
+                        for (const res of responsesMeta) {
+                            responsesObj[String(res.status)] = {
+                                description: res.description,
+                                content: res.type ? {
+                                    'application/json': {
+                                        schema: { $ref: `#/components/schemas/${res.type.name}` }
+                                    }
+                                } : undefined
+                            };
+                        }
+                    }
+                    openapi.paths[path][httpMethod] = {
+                        summary: opMeta.summary,
+                        description: opMeta.description,
+                        tags: tagMeta ? [tagMeta.name] : ['Default'],
+                        responses: responsesObj
+                    };
+                }
+            }
+        }
+        return openapi;
+    }
+}
+exports.OpenApiBuilder = OpenApiBuilder;

package/dist/decorators/api-operation.decorator.d.ts

@@ -0,0 +1,4 @@
+import { ApiOperationMetadata, ApiResponseMetadata } from '../registry/DocsRegistry';
+export declare function ApiTag(name: string, description?: string): ClassDecorator;
+export declare function ApiOperation(metadata: ApiOperationMetadata): MethodDecorator;
+export declare function ApiResponse(metadata: ApiResponseMetadata): MethodDecorator;

package/dist/decorators/api-operation.decorator.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiTag = ApiTag;
+exports.ApiOperation = ApiOperation;
+exports.ApiResponse = ApiResponse;
+const DocsRegistry_1 = require("../registry/DocsRegistry");
+function ApiTag(name, description) {
+    return (target) => {
+        DocsRegistry_1.DocsRegistry.getInstance().registerTag(target, name, description);
+    };
+}
+function ApiOperation(metadata) {
+    return (target, propertyKey) => {
+        DocsRegistry_1.DocsRegistry.getInstance().registerOperation(target.constructor, String(propertyKey), metadata);
+    };
+}
+function ApiResponse(metadata) {
+    return (target, propertyKey) => {
+        DocsRegistry_1.DocsRegistry.getInstance().registerResponse(target.constructor, String(propertyKey), metadata);
+    };
+}

package/dist/decorators/api-property.decorator.d.ts

@@ -0,0 +1,2 @@
+import { ApiPropertyMetadata } from '../registry/DocsRegistry';
+export declare function ApiProperty(metadata?: Omit<ApiPropertyMetadata, 'name'>): PropertyDecorator;

package/dist/decorators/api-property.decorator.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiProperty = ApiProperty;
+const DocsRegistry_1 = require("../registry/DocsRegistry");
+function ApiProperty(metadata = { type: 'string' }) {
+    return (target, propertyKey) => {
+        DocsRegistry_1.DocsRegistry.getInstance().registerProperty(target.constructor, {
+            name: String(propertyKey),
+            ...metadata,
+        });
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './registry/DocsRegistry';
+export * from './decorators/api-operation.decorator';
+export * from './decorators/api-property.decorator';
+export * from './builder/OpenApiBuilder';
+export * from './scalar';

package/dist/index.js

@@ -0,0 +1,21 @@
+"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 });
+__exportStar(require("./registry/DocsRegistry"), exports);
+__exportStar(require("./decorators/api-operation.decorator"), exports);
+__exportStar(require("./decorators/api-property.decorator"), exports);
+__exportStar(require("./builder/OpenApiBuilder"), exports);
+__exportStar(require("./scalar"), exports);

package/dist/registry/DocsRegistry.d.ts

@@ -0,0 +1,36 @@
+export interface ApiPropertyMetadata {
+    name: string;
+    type?: any;
+    description?: string;
+    example?: any;
+    required?: boolean;
+}
+export interface ApiOperationMetadata {
+    summary: string;
+    description?: string;
+}
+export interface ApiResponseMetadata {
+    status: number;
+    description: string;
+    type?: any;
+}
+export declare class DocsRegistry {
+    private static instance;
+    private schemas;
+    private operations;
+    private responses;
+    private tags;
+    private constructor();
+    static getInstance(): DocsRegistry;
+    registerProperty(target: any, metadata: ApiPropertyMetadata): void;
+    getSchemas(): [any, ApiPropertyMetadata[]][];
+    registerOperation(target: any, method: string, metadata: ApiOperationMetadata): void;
+    getOperation(target: any, method: string): ApiOperationMetadata | undefined;
+    registerResponse(target: any, method: string, metadata: ApiResponseMetadata): void;
+    getResponses(target: any, method: string): ApiResponseMetadata[];
+    registerTag(target: any, name: string, description?: string): void;
+    getTag(target: any): {
+        name: string;
+        description?: string;
+    } | undefined;
+}

package/dist/registry/DocsRegistry.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocsRegistry = void 0;
+class DocsRegistry {
+    static instance;
+    schemas = new Map();
+    operations = new Map(); // Controller -> method -> Metadata
+    responses = new Map(); // Controller -> method -> Metadata
+    tags = new Map(); // Controller -> Tag
+    constructor() { }
+    static getInstance() {
+        if (!DocsRegistry.instance) {
+            DocsRegistry.instance = new DocsRegistry();
+        }
+        return DocsRegistry.instance;
+    }
+    registerProperty(target, metadata) {
+        if (!this.schemas.has(target)) {
+            this.schemas.set(target, []);
+        }
+        this.schemas.get(target).push(metadata);
+    }
+    getSchemas() {
+        return Array.from(this.schemas.entries());
+    }
+    registerOperation(target, method, metadata) {
+        if (!this.operations.has(target)) {
+            this.operations.set(target, new Map());
+        }
+        this.operations.get(target).set(method, metadata);
+    }
+    getOperation(target, method) {
+        return this.operations.get(target)?.get(method);
+    }
+    registerResponse(target, method, metadata) {
+        if (!this.responses.has(target)) {
+            this.responses.set(target, new Map());
+        }
+        const methodResponses = this.responses.get(target);
+        if (!methodResponses.has(method)) {
+            methodResponses.set(method, []);
+        }
+        methodResponses.get(method).push(metadata);
+    }
+    getResponses(target, method) {
+        return this.responses.get(target)?.get(method) || [];
+    }
+    registerTag(target, name, description) {
+        this.tags.set(target, { name, description });
+    }
+    getTag(target) {
+        return this.tags.get(target);
+    }
+}
+exports.DocsRegistry = DocsRegistry;

package/dist/scalar/index.d.ts

@@ -0,0 +1,2 @@
+export declare function generateStaticDocs(outputDir: string, title?: string): void;
+export declare function startScalarServer(port?: number, title?: string): void;

package/dist/scalar/index.js

@@ -0,0 +1,84 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateStaticDocs = generateStaticDocs;
+exports.startScalarServer = startScalarServer;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const express_1 = __importDefault(require("express"));
+const OpenApiBuilder_1 = require("../builder/OpenApiBuilder");
+function generateStaticDocs(outputDir, title = 'Aetherion API') {
+    const builder = new OpenApiBuilder_1.OpenApiBuilder();
+    const spec = builder.build(title);
+    const fullPath = path.resolve(outputDir, 'openapi.json');
+    fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+    fs.writeFileSync(fullPath, JSON.stringify(spec, null, 2));
+    console.log(`Generated OpenAPI spec at ${fullPath}`);
+}
+function startScalarServer(port = 3000, title = 'Aetherion API') {
+    const app = (0, express_1.default)();
+    app.get('/openapi.json', (req, res) => {
+        const builder = new OpenApiBuilder_1.OpenApiBuilder();
+        const spec = builder.build(title);
+        res.json(spec);
+    });
+    app.get('/docs', (req, res) => {
+        const html = `
+      <!doctype html>
+      <html>
+        <head>
+          <title>${title} Reference</title>
+          <meta charset="utf-8" />
+          <meta
+            name="viewport"
+            content="width=device-width, initial-scale=1" />
+        </head>
+        <body>
+          <script
+            id="api-reference"
+            data-url="/openapi.json"></script>
+          <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+        </body>
+      </html>
+    `;
+        res.send(html);
+    });
+    app.listen(port, () => {
+        console.log(`Scalar docs available at http://localhost:${port}/docs`);
+    });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@aetherionfw/docs",
+  "version": "1.0.0",
+  "description": "OpenAPI Documentation & Scalar for Aetherion Framework",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "express": "^4.19.0",
+    "reflect-metadata": "^0.2.2",
+    "@aetherionfw/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "typescript": "^5.5.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "author": "CrisD3v",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  }
+}