npm - @morojs/moro - Versions diffs - 1.6.2 → 1.6.3 - Mend

@morojs/moro 1.6.2 → 1.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (366) hide show

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

@@ -1,295 +0,0 @@
-// Simple Documentation Generator - Fallback for when Swagger UI has issues
-// Generates clean, readable API documentation from routes
-import { CompiledRoute, RouteSchema } from '../routing/index.js';
-import { createFrameworkLogger } from '../logger/index.js';
-const logger = createFrameworkLogger('SimpleDocs');
-export interface SimpleDocsOptions {
-  title?: string;
-  description?: string;
-  basePath?: string;
-}
-export class SimpleDocsGenerator {
-  private routes: CompiledRoute[] = [];
-  constructor(private options: SimpleDocsOptions = {}) {
-    this.options = {
-      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');
-  }
-  generateHTML(): string {
-    const routesByTag = this.groupRoutesByTag();
-    return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${this.options.title}</title>
-  <style>
-    body {
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-      line-height: 1.6;
-      margin: 0;
-      padding: 20px;
-      background: #f8f9fa;
-    }
-    .container {
-      max-width: 1200px;
-      margin: 0 auto;
-      background: white;
-      padding: 30px;
-      border-radius: 8px;
-      box-shadow: 0 2px 10px rgba(0,0,0,0.1);
-    }
-    h1 { color: #2563eb; margin-bottom: 10px; }
-    h2 { color: #374151; border-bottom: 2px solid #e5e7eb; padding-bottom: 10px; }
-    h3 { color: #6b7280; }
-    .endpoint {
-      background: #f3f4f6;
-      border-left: 4px solid #2563eb;
-      padding: 15px;
-      margin: 15px 0;
-      border-radius: 4px;
-    }
-    .method {
-      display: inline-block;
-      padding: 4px 8px;
-      border-radius: 4px;
-      font-weight: bold;
-      margin-right: 10px;
-      color: white;
-    }
-    .method.GET { background: #10b981; }
-    .method.POST { background: #f59e0b; }
-    .method.PUT { background: #3b82f6; }
-    .method.DELETE { background: #ef4444; }
-    .method.PATCH { background: #8b5cf6; }
-    .path { font-family: monospace; font-size: 16px; font-weight: bold; }
-    .description { color: #6b7280; margin: 8px 0; }
-    .tags { margin: 8px 0; }
-    .tag {
-      display: inline-block;
-      background: #e5e7eb;
-      color: #374151;
-      padding: 2px 8px;
-      border-radius: 12px;
-      font-size: 12px;
-      margin-right: 5px;
-    }
-    .validation {
-      background: #fef3c7;
-      border: 1px solid #f59e0b;
-      padding: 10px;
-      border-radius: 4px;
-      margin: 10px 0;
-    }
-    .auth {
-      background: #fee2e2;
-      border: 1px solid #ef4444;
-      padding: 10px;
-      border-radius: 4px;
-      margin: 10px 0;
-    }
-    .rate-limit {
-      background: #e0f2fe;
-      border: 1px solid #0284c7;
-      padding: 10px;
-      border-radius: 4px;
-      margin: 10px 0;
-    }
-    .example {
-      background: #f3f4f6;
-      border: 1px solid #d1d5db;
-      padding: 10px;
-      border-radius: 4px;
-      margin: 10px 0;
-      font-family: monospace;
-      font-size: 14px;
-    }
-    .footer {
-      margin-top: 40px;
-      padding-top: 20px;
-      border-top: 1px solid #e5e7eb;
-      text-align: center;
-      color: #6b7280;
-    }
-  </style>
-</head>
-<body>
-  <div class="container">
-    <h1>${this.options.title}</h1>
-    <p>${this.options.description}</p>
-    <div class="example">
-      <strong>Interactive Swagger UI:</strong> <a href="${this.options.basePath}" target="_blank">${this.options.basePath}</a><br>
-      <strong>OpenAPI JSON:</strong> <a href="${this.options.basePath}/openapi.json" target="_blank">${this.options.basePath}/openapi.json</a>
-    </div>
-    ${this.generateRouteDocumentation(routesByTag)}
-    <div class="footer">
-      <p>Generated automatically from Moro Framework intelligent routes</p>
-      <p>Built with Moro Framework - Intelligent Routing + Type-Safe Validation</p>
-    </div>
-  </div>
-</body>
-</html>`;
-  }
-  private groupRoutesByTag(): Map<string, CompiledRoute[]> {
-    const grouped = new Map<string, CompiledRoute[]>();
-    for (const route of this.routes) {
-      const tags = route.schema.tags || ['default'];
-      for (const tag of tags) {
-        if (!grouped.has(tag)) {
-          grouped.set(tag, []);
-        }
-        grouped.get(tag)!.push(route);
-      }
-    }
-    return grouped;
-  }
-  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>`;
-      for (const route of routes) {
-        html += this.generateRouteSection(route.schema);
-      }
-    }
-    return html;
-  }
-  private generateRouteSection(route: RouteSchema): string {
-    const methodClass = route.method.toLowerCase();
-    const html = `
-    <div class="endpoint">
-      <div>
-        <span class="method ${route.method}">${route.method}</span>
-        <span class="path">${route.path}</span>
-      </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>` : ''}
-      ${this.generateValidationInfo(route)}
-      ${this.generateAuthInfo(route)}
-      ${this.generateRateLimitInfo(route)}
-      ${this.generateExamples(route)}
-    </div>`;
-    return html;
-  }
-  private generateValidationInfo(route: RouteSchema): string {
-    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');
-    return `
-    <div class="validation">
-      <strong>Validation:</strong> ${validationTypes.join(', ')}
-      <br><small>Request will be validated with Validation schemas for type safety</small>
-    </div>`;
-  }
-  private generateAuthInfo(route: RouteSchema): string {
-    if (!route.auth) return '';
-    const roles = route.auth.roles ? route.auth.roles.join(', ') : 'authenticated';
-    return `
-    <div class="auth">
-      <strong>Authentication Required:</strong> ${roles}
-      <br><small>Requires valid authentication token</small>
-    </div>`;
-  }
-  private generateRateLimitInfo(route: RouteSchema): string {
-    if (!route.rateLimit) return '';
-    const { requests, window } = route.rateLimit;
-    const windowSeconds = Math.round(window / 1000);
-    return `
-    <div class="rate-limit">
-      <strong>Rate Limit:</strong> ${requests} requests per ${windowSeconds} seconds
-      <br><small>Automatic protection against abuse</small>
-    </div>`;
-  }
-  private generateExamples(route: RouteSchema): string {
-    const baseUrl = 'http://localhost:3001';
-    const fullPath = `${baseUrl}${route.path}`;
-    let example = '';
-    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)) {
-      example = `curl -X ${route.method} ${fullPath} \\
-  -H "Content-Type: application/json" \\
-  -d '{"example": "data"}'`;
-    } else {
-      example = `curl -X ${route.method} ${fullPath}`;
-    }
-    return `
-    <div class="example">
-      <strong>Example:</strong><br>
-      <code>${example}</code>
-    </div>`;
-  }
-}
-// Create middleware for simple docs
-export function createSimpleDocsMiddleware(
-  routes: CompiledRoute[],
-  options: SimpleDocsOptions = {}
-) {
-  const generator = new SimpleDocsGenerator(options);
-  generator.addRoutes(routes);
-  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');
-      res.send(generator.generateHTML());
-      return;
-    }
-    next();
-  };
-}

package/src/core/docs/swagger-ui.ts DELETED Viewed

@@ -1,354 +0,0 @@
-// Swagger UI Integration for Moro Framework
-// Serves interactive API documentation using Swagger UI
-import { readFileSync } from 'fs';
-import { join } from 'path';
-import { createUserRequire } from '../utilities/package-utils.js';
-import { HttpRequest, HttpResponse } from '../http/index.js';
-import { OpenAPISpec } from './openapi-generator.js';
-import { createFrameworkLogger } from '../logger/index.js';
-const logger = createFrameworkLogger('SwaggerUI');
-// Swagger UI configuration options
-export interface SwaggerUIOptions {
-  title?: string;
-  favicon?: string;
-  customCss?: string;
-  customJs?: string;
-  swaggerOptions?: Record<string, any>;
-  enableTryItOut?: boolean;
-  enableFilter?: boolean;
-  enableDeepLinking?: boolean;
-}
-// Swagger UI middleware
-export class SwaggerUIMiddleware {
-  private swaggerUIAssetPath: string;
-  private openAPISpec: OpenAPISpec;
-  private options: SwaggerUIOptions;
-  constructor(openAPISpec: OpenAPISpec, options: SwaggerUIOptions = {}) {
-    this.openAPISpec = openAPISpec;
-    this.options = {
-      title: 'API Documentation',
-      enableTryItOut: true,
-      enableFilter: true,
-      enableDeepLinking: true,
-      swaggerOptions: {
-        dom_id: '#swagger-ui',
-        presets: ['SwaggerUIBundle.presets.apis', 'SwaggerUIBundle.presets.standalone'],
-        plugins: ['SwaggerUIBundle.plugins.DownloadUrl'],
-        layout: 'StandaloneLayout',
-      },
-      ...options,
-    };
-    try {
-      // Find swagger-ui-dist assets using ESM-compatible resolution
-      // Create a require function from the user's working directory to find their installed packages
-      const require = createUserRequire();
-      this.swaggerUIAssetPath = require
-        .resolve('swagger-ui-dist/package.json')
-        .replace('/package.json', '');
-      logger.debug('Swagger UI assets found', 'Initialization', {
-        assetPath: this.swaggerUIAssetPath,
-      });
-    } catch (error) {
-      logger.error('Failed to locate Swagger UI assets', 'Initialization', {
-        error: error instanceof Error ? error.message : String(error),
-      });
-      throw new Error(
-        'swagger-ui-dist package not found. Install with: npm install swagger-ui-dist'
-      );
-    }
-  }
-  // Generate HTML page for Swagger UI
-  private generateHTML(basePath: string): string {
-    const swaggerOptions = {
-      ...this.options.swaggerOptions,
-      url: `${basePath}/openapi.json`, // Relative URL to the OpenAPI spec
-      tryItOutEnabled: this.options.enableTryItOut,
-      filter: this.options.enableFilter,
-      deepLinking: this.options.enableDeepLinking,
-    };
-    return `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>${this.options.title}</title>
-  <link rel="stylesheet" type="text/css" href="${basePath}/swagger-ui.css" />
-  <style>
-    html {
-      box-sizing: border-box;
-      overflow: -moz-scrollbars-vertical;
-      overflow-y: scroll;
-    }
-    *, *:before, *:after {
-      box-sizing: inherit;
-    }
-    body {
-      margin:0;
-      background: #fafafa;
-    }
-    #loading-message {
-      padding: 20px;
-      text-align: center;
-      font-family: Arial, sans-serif;
-      color: #666;
-    }
-    #error-display {
-      display: none;
-      padding: 20px;
-      background: #ffebee;
-      border-left: 4px solid #f44336;
-      margin: 20px;
-      font-family: monospace;
-      color: #c62828;
-    }
-    ${this.options.customCss || ''}
-  </style>
-  ${this.options.favicon ? `<link rel="icon" type="image/png" href="${this.options.favicon}" sizes="32x32" />` : ''}
-</head>
-<body>
-  <div id="loading-message">
-    <h2>Loading Swagger UI...</h2>
-    <p>Please wait while the API documentation loads.</p>
-  </div>
-  <div id="swagger-ui"></div>
-  <div id="error-display">
-    <h3>Failed to Load Swagger UI</h3>
-    <div id="error-details"></div>
-  </div>
-  <script src="${basePath}/swagger-ui-bundle.js" charset="UTF-8"></script>
-  <script src="${basePath}/swagger-ui-standalone-preset.js" charset="UTF-8"></script>
-  <script>
-    console.log('Starting Swagger UI initialization...');
-    function showError(message, details) {
-      console.error('Swagger UI Error:', message, details);
-      document.getElementById('loading-message').style.display = 'none';
-      document.getElementById('error-display').style.display = 'block';
-      document.getElementById('error-details').innerHTML =
-        '<p><strong>Error:</strong> ' + message + '</p>' +
-        (details ? '<pre>' + JSON.stringify(details, null, 2) + '</pre>' : '');
-    }
-    function initializeSwaggerUI() {
-      console.log('Initializing Swagger UI...');
-      if (typeof SwaggerUIBundle === 'undefined') {
-        showError('SwaggerUIBundle not loaded', { SwaggerUIBundle: typeof SwaggerUIBundle });
-        return;
-      }
-      if (typeof SwaggerUIStandalonePreset === 'undefined') {
-        showError('SwaggerUIStandalonePreset not loaded', { SwaggerUIStandalonePreset: typeof SwaggerUIStandalonePreset });
-        return;
-      }
-      try {
-        console.log('Creating SwaggerUIBundle...');
-        const ui = SwaggerUIBundle({
-          url: '${basePath}/openapi.json',
-          dom_id: '#swagger-ui',
-          deepLinking: ${this.options.enableDeepLinking},
-          presets: [
-            SwaggerUIBundle.presets.apis,
-            SwaggerUIStandalonePreset
-          ],
-          plugins: [
-            SwaggerUIBundle.plugins.DownloadUrl
-          ],
-          layout: "StandaloneLayout",
-          tryItOutEnabled: ${this.options.enableTryItOut},
-          filter: ${this.options.enableFilter},
-          onComplete: function() {
-            console.log('Swagger UI loaded successfully');
-            document.getElementById('loading-message').style.display = 'none';
-          },
-          onFailure: function(error) {
-            console.error('Swagger UI failed to load:', error);
-            showError('Swagger UI initialization failed', error);
-          }
-        });
-        window.ui = ui;
-        console.log('SwaggerUIBundle created successfully');
-        // Hide loading message after timeout if onComplete doesn't fire
-        setTimeout(function() {
-          var loadingEl = document.getElementById('loading-message');
-          if (loadingEl && loadingEl.style.display !== 'none') {
-            console.log('Hiding loading message after timeout');
-            loadingEl.style.display = 'none';
-          }
-        }, 5000);
-      } catch (error) {
-        console.error('Error creating SwaggerUIBundle:', error);
-        showError('Failed to create SwaggerUIBundle', {
-          name: error.name,
-          message: error.message
-        });
-      }
-    }
-    // Initialize when DOM is ready and scripts are loaded
-    if (document.readyState === 'loading') {
-      document.addEventListener('DOMContentLoaded', function() {
-        setTimeout(initializeSwaggerUI, 100);
-      });
-    } else {
-      setTimeout(initializeSwaggerUI, 100);
-    }
-  </script>
-</body>
-</html>`;
-  }
-  // Create middleware function that serves Swagger UI
-  createMiddleware(basePath: string = '/docs') {
-    return (req: HttpRequest, res: HttpResponse, next: () => void) => {
-      const path = req.path;
-      logger.debug(`Docs middleware handling: ${path}`, 'DocsMiddleware', {
-        basePath,
-      });
-      // Serve the main HTML page
-      if (path === basePath || path === `${basePath}/`) {
-        logger.debug('Serving Swagger UI HTML', 'DocsServing');
-        // Set CSP headers to allow Swagger UI to work
-        res.setHeader(
-          'Content-Security-Policy',
-          "default-src 'self'; " +
-            "script-src 'self' 'unsafe-inline' 'unsafe-eval'; " +
-            "style-src 'self' 'unsafe-inline'; " +
-            "img-src 'self' data: https:; " +
-            "font-src 'self' data:; " +
-            "connect-src 'self'"
-        );
-        res.setHeader('Content-Type', 'text/html; charset=utf-8');
-        res.send(this.generateHTML(basePath));
-        return;
-      }
-      // Serve the OpenAPI JSON spec
-      if (path === `${basePath}/openapi.json`) {
-        logger.debug('Serving OpenAPI JSON spec', 'DocsServing');
-        res.setHeader('Content-Type', 'application/json');
-        res.json(this.openAPISpec);
-        return;
-      }
-      // Serve Swagger UI assets
-      if (path.startsWith(`${basePath}/`)) {
-        const assetName = path.replace(`${basePath}/`, '');
-        logger.debug(`Attempting to serve asset: ${assetName}`, 'AssetServing', {
-          fullPath: path,
-          basePath,
-          assetPath: this.swaggerUIAssetPath,
-        });
-        // Security: only allow specific asset files
-        const allowedAssets = [
-          'swagger-ui-bundle.js',
-          'swagger-ui.css',
-          'swagger-ui-standalone-preset.js',
-          'favicon-16x16.png',
-          'favicon-32x32.png',
-        ];
-        if (allowedAssets.includes(assetName)) {
-          try {
-            const assetPath = join(this.swaggerUIAssetPath, assetName);
-            logger.debug(`Reading asset from: ${assetPath}`, 'AssetServing');
-            const content = readFileSync(assetPath);
-            // Set appropriate content type
-            const contentType = this.getContentType(assetName);
-            res.setHeader('Content-Type', contentType);
-            res.setHeader('Cache-Control', 'public, max-age=86400'); // Cache for 1 day
-            logger.debug(`Serving asset: ${assetName} (${content.length} bytes)`, 'AssetServing');
-            res.send(content);
-            return;
-          } catch (error) {
-            logger.error(`Failed to serve Swagger UI asset: ${assetName}`, 'AssetServing', {
-              error: error instanceof Error ? error.message : String(error),
-              assetPath: join(this.swaggerUIAssetPath, assetName),
-            });
-            res.status(404);
-            res.send(`Asset not found: ${assetName}`);
-            return;
-          }
-        } else {
-          logger.warn(`Asset not allowed: ${assetName}`, 'AssetServing', {
-            allowedAssets,
-          });
-          res.status(404);
-          res.send(`Asset not allowed: ${assetName}`);
-          return;
-        }
-      }
-      // Not a docs request, continue to next middleware
-      next();
-    };
-  }
-  // Get content type for asset files
-  private getContentType(filename: string): string {
-    if (filename.endsWith('.js')) return 'application/javascript';
-    if (filename.endsWith('.css')) return 'text/css';
-    if (filename.endsWith('.png')) return 'image/png';
-    if (filename.endsWith('.ico')) return 'image/x-icon';
-    return 'text/plain';
-  }
-  // Update the OpenAPI spec (useful for dynamic updates)
-  updateSpec(newSpec: OpenAPISpec): void {
-    this.openAPISpec = newSpec;
-    logger.debug('OpenAPI specification updated', 'SpecUpdate', {
-      pathCount: Object.keys(newSpec.paths).length,
-    });
-  }
-}
-// Convenience function to create documentation middleware
-export function createDocsMiddleware(openAPISpec: OpenAPISpec, options: SwaggerUIOptions = {}) {
-  const middleware = new SwaggerUIMiddleware(openAPISpec, options);
-  return middleware.createMiddleware();
-}
-// Helper function to generate documentation for an app
-export function generateDocsForApp(
-  routes: any[],
-  info: { title: string; version: string; description?: string },
-  options: SwaggerUIOptions = {}
-) {
-  const openAPISpec: OpenAPISpec = {
-    openapi: '3.0.3',
-    info,
-    servers: [{ url: 'http://localhost:3000', description: 'Development server' }],
-    paths: {},
-    tags: [],
-  };
-  // This will be enhanced when integrated with the routing system
-  logger.info('Documentation generated for app', 'AppDocumentation', {
-    routeCount: routes.length,
-    title: info.title,
-  });
-  return createDocsMiddleware(openAPISpec, options);
-}