@morojs/moro 1.0.0 → 1.0.1

package/src/core/docs/openapi-generator.ts

@@ -1,15 +1,11 @@
 // OpenAPI Specification Generator for Moro Framework
 // Extracts route information from intelligent routing and generates OpenAPI 3.0 specs
 
-import { CompiledRoute, RouteSchema } from "../routing";
-import {
-  zodToOpenAPI,
-  generateExampleFromSchema,
-  OpenAPISchema,
-} from "./zod-to-openapi";
-import { createFrameworkLogger } from "../logger";
+import { CompiledRoute, RouteSchema } from '../routing';
+import { zodToOpenAPI, generateExampleFromSchema, OpenAPISchema } from './zod-to-openapi';
+import { createFrameworkLogger } from '../logger';
 
-const logger = createFrameworkLogger("OpenAPIGenerator");
+const logger = createFrameworkLogger('OpenAPIGenerator');
 
 // OpenAPI 3.0 specification structure
 export interface OpenAPISpec {
@@ -57,7 +53,7 @@ export interface OpenAPIOperation {
 
 export interface OpenAPIParameter {
   name: string;
-  in: "query" | "path" | "header" | "cookie";
+  in: 'query' | 'path' | 'header' | 'cookie';
   required?: boolean;
   description?: string;
   schema: OpenAPISchema;
@@ -102,10 +98,10 @@ export interface OpenAPIComponents {
 }
 
 export interface OpenAPISecurityScheme {
-  type: "apiKey" | "http" | "oauth2" | "openIdConnect";
+  type: 'apiKey' | 'http' | 'oauth2' | 'openIdConnect';
   description?: string;
   name?: string;
-  in?: "query" | "header" | "cookie";
+  in?: 'query' | 'header' | 'cookie';
   scheme?: string;
   bearerFormat?: string;
 }
@@ -136,7 +132,7 @@ export class OpenAPIGenerator {
   private tags = new Set<string>();
 
   constructor(private options: GenerationOptions) {
-    logger.debug("OpenAPI Generator initialized", "Initialization", {
+    logger.debug('OpenAPI Generator initialized', 'Initialization', {
       includeExamples: options.includeExamples,
       includeSchemas: options.includeSchemas,
     });
@@ -147,34 +143,30 @@ export class OpenAPIGenerator {
     this.routes.push(...routes);
 
     // Extract tags from routes
-    routes.forEach((route) => {
+    routes.forEach(route => {
       if (route.schema.tags) {
-        route.schema.tags.forEach((tag) => this.tags.add(tag));
+        route.schema.tags.forEach(tag => this.tags.add(tag));
       }
     });
 
-    logger.debug(
-      `Added ${routes.length} routes to documentation`,
-      "RouteAddition",
-      {
-        totalRoutes: this.routes.length,
-        uniqueTags: this.tags.size,
-      },
-    );
+    logger.debug(`Added ${routes.length} routes to documentation`, 'RouteAddition', {
+      totalRoutes: this.routes.length,
+      uniqueTags: this.tags.size,
+    });
   }
 
   // Generate complete OpenAPI specification
   generate(): OpenAPISpec {
-    logger.info("Generating OpenAPI specification", "Generation", {
+    logger.info('Generating OpenAPI specification', 'Generation', {
       routeCount: this.routes.length,
       tagCount: this.tags.size,
     });
 
     const spec: OpenAPISpec = {
-      openapi: "3.0.3",
+      openapi: '3.0.3',
       info: this.options.info,
       servers: this.options.servers || [
-        { url: "http://localhost:3000", description: "Development server" },
+        { url: 'http://localhost:3000', description: 'Development server' },
       ],
       paths: this.generatePaths(),
       tags: this.generateTags(),
@@ -188,7 +180,7 @@ export class OpenAPIGenerator {
       };
     }
 
-    logger.info("OpenAPI specification generated successfully", "Generation", {
+    logger.info('OpenAPI specification generated successfully', 'Generation', {
       pathCount: Object.keys(spec.paths).length,
       schemaCount: this.schemas.size,
       tagCount: spec.tags?.length || 0,
@@ -231,10 +223,7 @@ export class OpenAPIGenerator {
     }
 
     // Add request body (for POST, PUT, PATCH)
-    if (
-      ["POST", "PUT", "PATCH"].includes(route.method) &&
-      route.validation?.body
-    ) {
+    if (['POST', 'PUT', 'PATCH'].includes(route.method) && route.validation?.body) {
       operation.requestBody = this.generateRequestBody(route);
     }
 
@@ -257,7 +246,7 @@ export class OpenAPIGenerator {
         for (const [name, schema] of Object.entries(paramSchema.properties)) {
           parameters.push({
             name,
-            in: "path",
+            in: 'path',
             required: true,
             schema,
             description: schema.description,
@@ -275,7 +264,7 @@ export class OpenAPIGenerator {
           const isRequired = querySchema.required?.includes(name) || false;
           parameters.push({
             name,
-            in: "query",
+            in: 'query',
             required: isRequired,
             schema,
             description: schema.description,
@@ -293,7 +282,7 @@ export class OpenAPIGenerator {
           const isRequired = headerSchema.required?.includes(name) || false;
           parameters.push({
             name,
-            in: "header",
+            in: 'header',
             required: isRequired,
             schema,
             description: schema.description,
@@ -310,11 +299,11 @@ export class OpenAPIGenerator {
   private generateRequestBody(route: RouteSchema): OpenAPIRequestBody {
     if (!route.validation?.body) {
       return {
-        description: "Request body",
+        description: 'Request body',
         required: true,
         content: {
-          "application/json": {
-            schema: { type: "object" },
+          'application/json': {
+            schema: { type: 'object' },
           },
         },
       };
@@ -326,10 +315,10 @@ export class OpenAPIGenerator {
       : undefined;
 
     return {
-      description: "Request body",
+      description: 'Request body',
       required: true,
       content: {
-        "application/json": {
+        'application/json': {
           schema: bodySchema,
           example,
         },
@@ -338,22 +327,20 @@ export class OpenAPIGenerator {
   }
 
   // Generate responses
-  private generateResponses(
-    route: RouteSchema,
-  ): Record<string, OpenAPIResponse> {
+  private generateResponses(route: RouteSchema): Record<string, OpenAPIResponse> {
     const responses: Record<string, OpenAPIResponse> = {};
 
     // Success response
-    responses["200"] = {
-      description: "Successful response",
+    responses['200'] = {
+      description: 'Successful response',
       content: {
-        "application/json": {
+        'application/json': {
           schema: {
-            type: "object",
+            type: 'object',
             properties: {
-              success: { type: "boolean", example: true },
-              data: { type: "object", description: "Response data" },
-              message: { type: "string", example: "Operation successful" },
+              success: { type: 'boolean', example: true },
+              data: { type: 'object', description: 'Response data' },
+              message: { type: 'string', example: 'Operation successful' },
             },
           },
         },
@@ -361,19 +348,19 @@ export class OpenAPIGenerator {
     };
 
     // Add 201 for POST requests
-    if (route.method === "POST") {
-      responses["201"] = {
-        description: "Resource created successfully",
+    if (route.method === 'POST') {
+      responses['201'] = {
+        description: 'Resource created successfully',
         content: {
-          "application/json": {
+          'application/json': {
             schema: {
-              type: "object",
+              type: 'object',
               properties: {
-                success: { type: "boolean", example: true },
-                data: { type: "object", description: "Created resource" },
+                success: { type: 'boolean', example: true },
+                data: { type: 'object', description: 'Created resource' },
                 message: {
-                  type: "string",
-                  example: "Resource created successfully",
+                  type: 'string',
+                  example: 'Resource created successfully',
                 },
               },
             },
@@ -384,30 +371,30 @@ export class OpenAPIGenerator {
 
     // Validation error response
     if (route.validation) {
-      responses["400"] = {
-        description: "Validation error",
+      responses['400'] = {
+        description: 'Validation error',
         content: {
-          "application/json": {
+          'application/json': {
             schema: {
-              type: "object",
+              type: 'object',
               properties: {
-                success: { type: "boolean", example: false },
-                error: { type: "string", example: "Validation failed" },
+                success: { type: 'boolean', example: false },
+                error: { type: 'string', example: 'Validation failed' },
                 details: {
-                  type: "array",
+                  type: 'array',
                   items: {
-                    type: "object",
+                    type: 'object',
                     properties: {
-                      field: { type: "string", example: "email" },
+                      field: { type: 'string', example: 'email' },
                       message: {
-                        type: "string",
-                        example: "Invalid email address",
+                        type: 'string',
+                        example: 'Invalid email address',
                       },
-                      code: { type: "string", example: "invalid_format" },
+                      code: { type: 'string', example: 'invalid_format' },
                     },
                   },
                 },
-                requestId: { type: "string", example: "req_123456" },
+                requestId: { type: 'string', example: 'req_123456' },
               },
             },
           },
@@ -417,32 +404,32 @@ export class OpenAPIGenerator {
 
     // Auth error response
     if (route.auth) {
-      responses["401"] = {
-        description: "Authentication required",
+      responses['401'] = {
+        description: 'Authentication required',
         content: {
-          "application/json": {
+          'application/json': {
             schema: {
-              type: "object",
+              type: 'object',
               properties: {
-                success: { type: "boolean", example: false },
-                error: { type: "string", example: "Authentication required" },
-                requestId: { type: "string", example: "req_123456" },
+                success: { type: 'boolean', example: false },
+                error: { type: 'string', example: 'Authentication required' },
+                requestId: { type: 'string', example: 'req_123456' },
               },
             },
           },
         },
       };
 
-      responses["403"] = {
-        description: "Insufficient permissions",
+      responses['403'] = {
+        description: 'Insufficient permissions',
         content: {
-          "application/json": {
+          'application/json': {
             schema: {
-              type: "object",
+              type: 'object',
               properties: {
-                success: { type: "boolean", example: false },
-                error: { type: "string", example: "Insufficient permissions" },
-                requestId: { type: "string", example: "req_123456" },
+                success: { type: 'boolean', example: false },
+                error: { type: 'string', example: 'Insufficient permissions' },
+                requestId: { type: 'string', example: 'req_123456' },
               },
             },
           },
@@ -452,17 +439,17 @@ export class OpenAPIGenerator {
 
     // Rate limit error response
     if (route.rateLimit) {
-      responses["429"] = {
-        description: "Rate limit exceeded",
+      responses['429'] = {
+        description: 'Rate limit exceeded',
         content: {
-          "application/json": {
+          'application/json': {
             schema: {
-              type: "object",
+              type: 'object',
               properties: {
-                success: { type: "boolean", example: false },
-                error: { type: "string", example: "Rate limit exceeded" },
-                retryAfter: { type: "number", example: 60 },
-                requestId: { type: "string", example: "req_123456" },
+                success: { type: 'boolean', example: false },
+                error: { type: 'string', example: 'Rate limit exceeded' },
+                retryAfter: { type: 'number', example: 60 },
+                requestId: { type: 'string', example: 'req_123456' },
               },
             },
           },
@@ -471,16 +458,16 @@ export class OpenAPIGenerator {
     }
 
     // Server error response
-    responses["500"] = {
-      description: "Internal server error",
+    responses['500'] = {
+      description: 'Internal server error',
       content: {
-        "application/json": {
+        'application/json': {
           schema: {
-            type: "object",
+            type: 'object',
             properties: {
-              success: { type: "boolean", example: false },
-              error: { type: "string", example: "Internal server error" },
-              requestId: { type: "string", example: "req_123456" },
+              success: { type: 'boolean', example: false },
+              error: { type: 'string', example: 'Internal server error' },
+              requestId: { type: 'string', example: 'req_123456' },
             },
           },
         },
@@ -506,7 +493,7 @@ export class OpenAPIGenerator {
 
   // Generate tags
   private generateTags(): OpenAPITag[] {
-    return Array.from(this.tags).map((tag) => ({
+    return Array.from(this.tags).map(tag => ({
       name: tag,
       description: `Operations related to ${tag}`,
     }));
@@ -515,7 +502,7 @@ export class OpenAPIGenerator {
   // Convert Moro path format to OpenAPI path format
   private convertPathToOpenAPI(path: string): string {
     // Convert :param to {param} format
-    return path.replace(/:([^/]+)/g, "{$1}");
+    return path.replace(/:([^/]+)/g, '{$1}');
   }
 
   // Generate JSON representation
@@ -531,26 +518,26 @@ export class OpenAPIGenerator {
 
   // Simple YAML converter (basic implementation)
   private objectToYAML(obj: any, indent: number = 0): string {
-    const spaces = "  ".repeat(indent);
-    let yaml = "";
+    const spaces = '  '.repeat(indent);
+    let yaml = '';
 
     for (const [key, value] of Object.entries(obj)) {
       if (value === null || value === undefined) continue;
 
       yaml += `${spaces}${key}:`;
 
-      if (typeof value === "object" && !Array.isArray(value)) {
-        yaml += "\n" + this.objectToYAML(value, indent + 1);
+      if (typeof value === 'object' && !Array.isArray(value)) {
+        yaml += '\n' + this.objectToYAML(value, indent + 1);
       } else if (Array.isArray(value)) {
-        yaml += "\n";
+        yaml += '\n';
         for (const item of value) {
-          if (typeof item === "object") {
+          if (typeof item === 'object') {
             yaml += `${spaces}  -\n` + this.objectToYAML(item, indent + 2);
           } else {
             yaml += `${spaces}  - ${item}\n`;
           }
         }
-      } else if (typeof value === "string") {
+      } else if (typeof value === 'string') {
         yaml += ` "${value}"\n`;
       } else {
         yaml += ` ${value}\n`;
@@ -564,7 +551,7 @@ export class OpenAPIGenerator {
 // Convenience function to generate OpenAPI from routes
 export function generateOpenAPIFromRoutes(
   routes: CompiledRoute[],
-  options: GenerationOptions,
+  options: GenerationOptions
 ): OpenAPISpec {
   const generator = new OpenAPIGenerator(options);
   generator.addRoutes(routes);
@@ -574,15 +561,15 @@ export function generateOpenAPIFromRoutes(
 // Default security schemes
 export const defaultSecuritySchemes: Record<string, OpenAPISecurityScheme> = {
   bearerAuth: {
-    type: "http",
-    scheme: "bearer",
-    bearerFormat: "JWT",
-    description: "Bearer token authentication",
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'JWT',
+    description: 'Bearer token authentication',
   },
   apiKey: {
-    type: "apiKey",
-    in: "header",
-    name: "X-API-Key",
-    description: "API key authentication",
+    type: 'apiKey',
+    in: 'header',
+    name: 'X-API-Key',
+    description: 'API key authentication',
   },
 };

package/src/core/docs/simple-docs.ts

@@ -1,10 +1,10 @@
 // Simple Documentation Generator - Fallback for when Swagger UI has issues
 // Generates clean, readable API documentation from routes
 
-import { CompiledRoute, RouteSchema } from "../routing";
-import { createFrameworkLogger } from "../logger";
+import { CompiledRoute, RouteSchema } from '../routing';
+import { createFrameworkLogger } from '../logger';
 
-const logger = createFrameworkLogger("SimpleDocs");
+const logger = createFrameworkLogger('SimpleDocs');
 
 export interface SimpleDocsOptions {
   title?: string;
@@ -17,19 +17,16 @@ export class SimpleDocsGenerator {
 
   constructor(private options: SimpleDocsOptions = {}) {
     this.options = {
-      title: "API Documentation",
-      description: "API documentation generated from intelligent routes",
-      basePath: "/docs",
+      title: 'API Documentation',
+      description: 'API documentation generated from intelligent routes',
+      basePath: '/docs',
       ...options,
     };
   }
 
   addRoutes(routes: CompiledRoute[]): void {
     this.routes = routes;
-    logger.debug(
-      `Added ${routes.length} routes to simple docs`,
-      "RouteAddition",
-    );
+    logger.debug(`Added ${routes.length} routes to simple docs`, 'RouteAddition');
   }
 
   generateHTML(): string {
@@ -156,7 +153,7 @@ export class SimpleDocsGenerator {
     const grouped = new Map<string, CompiledRoute[]>();
 
     for (const route of this.routes) {
-      const tags = route.schema.tags || ["default"];
+      const tags = route.schema.tags || ['default'];
 
       for (const tag of tags) {
         if (!grouped.has(tag)) {
@@ -169,10 +166,8 @@ export class SimpleDocsGenerator {
     return grouped;
   }
 
-  private generateRouteDocumentation(
-    routesByTag: Map<string, CompiledRoute[]>,
-  ): string {
-    let html = "";
+  private generateRouteDocumentation(routesByTag: Map<string, CompiledRoute[]>): string {
+    let html = '';
 
     for (const [tag, routes] of routesByTag) {
       html += `<h2>${tag.charAt(0).toUpperCase() + tag.slice(1)}</h2>`;
@@ -195,9 +190,9 @@ export class SimpleDocsGenerator {
         <span class="path">${route.path}</span>
       </div>
       
-      ${route.description ? `<div class="description">${route.description}</div>` : ""}
+      ${route.description ? `<div class="description">${route.description}</div>` : ''}
       
-      ${route.tags ? `<div class="tags">${route.tags.map((tag) => `<span class="tag">${tag}</span>`).join("")}</div>` : ""}
+      ${route.tags ? `<div class="tags">${route.tags.map(tag => `<span class="tag">${tag}</span>`).join('')}</div>` : ''}
       
       ${this.generateValidationInfo(route)}
       ${this.generateAuthInfo(route)}
@@ -209,27 +204,25 @@ export class SimpleDocsGenerator {
   }
 
   private generateValidationInfo(route: RouteSchema): string {
-    if (!route.validation) return "";
+    if (!route.validation) return '';
 
     const validationTypes = [];
-    if (route.validation.body) validationTypes.push("Body");
-    if (route.validation.query) validationTypes.push("Query Parameters");
-    if (route.validation.params) validationTypes.push("Path Parameters");
-    if (route.validation.headers) validationTypes.push("Headers");
+    if (route.validation.body) validationTypes.push('Body');
+    if (route.validation.query) validationTypes.push('Query Parameters');
+    if (route.validation.params) validationTypes.push('Path Parameters');
+    if (route.validation.headers) validationTypes.push('Headers');
 
     return `
     <div class="validation">
-      <strong>Validation:</strong> ${validationTypes.join(", ")}
+      <strong>Validation:</strong> ${validationTypes.join(', ')}
       <br><small>Request will be validated with Zod schemas for type safety</small>
     </div>`;
   }
 
   private generateAuthInfo(route: RouteSchema): string {
-    if (!route.auth) return "";
+    if (!route.auth) return '';
 
-    const roles = route.auth.roles
-      ? route.auth.roles.join(", ")
-      : "authenticated";
+    const roles = route.auth.roles ? route.auth.roles.join(', ') : 'authenticated';
 
     return `
     <div class="auth">
@@ -239,7 +232,7 @@ export class SimpleDocsGenerator {
   }
 
   private generateRateLimitInfo(route: RouteSchema): string {
-    if (!route.rateLimit) return "";
+    if (!route.rateLimit) return '';
 
     const { requests, window } = route.rateLimit;
     const windowSeconds = Math.round(window / 1000);
@@ -252,19 +245,19 @@ export class SimpleDocsGenerator {
   }
 
   private generateExamples(route: RouteSchema): string {
-    const baseUrl = "http://localhost:3001";
+    const baseUrl = 'http://localhost:3001';
     const fullPath = `${baseUrl}${route.path}`;
 
-    let example = "";
+    let example = '';
 
-    if (route.method === "GET") {
+    if (route.method === 'GET') {
       example = `curl "${fullPath}"`;
 
       // Add query parameter example if validation exists
       if (route.validation?.query) {
         example = `curl "${fullPath}?limit=10&search=example"`;
       }
-    } else if (["POST", "PUT", "PATCH"].includes(route.method)) {
+    } else if (['POST', 'PUT', 'PATCH'].includes(route.method)) {
       example = `curl -X ${route.method} ${fullPath} \\
   -H "Content-Type: application/json" \\
   -d '{"example": "data"}'`;
@@ -283,19 +276,16 @@ export class SimpleDocsGenerator {
 // Create middleware for simple docs
 export function createSimpleDocsMiddleware(
   routes: CompiledRoute[],
-  options: SimpleDocsOptions = {},
+  options: SimpleDocsOptions = {}
 ) {
   const generator = new SimpleDocsGenerator(options);
   generator.addRoutes(routes);
 
-  const basePath = options.basePath || "/docs";
+  const basePath = options.basePath || '/docs';
 
   return (req: any, res: any, next: () => void) => {
-    if (
-      req.path === `${basePath}/simple` ||
-      req.path === `${basePath}/simple/`
-    ) {
-      res.setHeader("Content-Type", "text/html; charset=utf-8");
+    if (req.path === `${basePath}/simple` || req.path === `${basePath}/simple/`) {
+      res.setHeader('Content-Type', 'text/html; charset=utf-8');
       res.send(generator.generateHTML());
       return;
     }