@engjts/nexus 0.1.8 → 0.1.10

package/src/advanced/static/serveStatic.ts

@@ -1,225 +0,0 @@
-import { existsSync, statSync, createReadStream } from 'fs';
-import { resolve, join, extname } from 'path/posix';
-import { generateDirectoryListing } from './generateDirectoryListing';
-import { isSafePath } from './isSafePath';
-import { generateETag } from './generateETag';
-import { getMimeType } from './getMimeType';
-import { Plugin, Handler, Response } from '../../core/types';
-import { StaticConfig } from './types';
-
-/**
- * Create static file serving feature
- */
-
-export function serveStatic(config: StaticConfig = {}): Plugin {
-    const {
-        root = './public', prefix = '', index = 'index.html', directory = false, maxAge = 86400, immutable = false, etag = true, lastModified = true, extensions, dotfiles = 'ignore', fallback, headers = {}, precompressed = false
-    } = config;
-
-    const rootPath = resolve(process.cwd(), root);
-    const normalizedPrefix = prefix.startsWith('/') ? prefix : prefix ? `/${prefix}` : '';
-
-    return {
-        name: 'static',
-        version: '1.0.0',
-
-        install(app: any) {
-            // Create the static file handler
-            const staticHandler: Handler = async (ctx) => {
-                let requestPath = ctx.path;
-
-                // Remove prefix if set
-                if (normalizedPrefix && requestPath.startsWith(normalizedPrefix)) {
-                    requestPath = requestPath.slice(normalizedPrefix.length) || '/';
-                } else if (normalizedPrefix) {
-                    // Path doesn't match prefix, skip
-                    return { statusCode: 404, headers: {}, body: 'Not Found' };
-                }
-
-                // Decode URL
-                try {
-                    requestPath = decodeURIComponent(requestPath);
-                } catch {
-                    return { statusCode: 400, headers: {}, body: 'Bad Request' };
-                }
-
-                // Remove leading slash for joining
-                const cleanPath = requestPath.startsWith('/') ? requestPath.slice(1) : requestPath;
-
-                // Security: Check for directory traversal
-                if (!isSafePath(cleanPath, rootPath)) {
-                    return { statusCode: 403, headers: {}, body: 'Forbidden' };
-                }
-
-                const filePath = join(rootPath, cleanPath);
-
-                // Handle dotfiles
-                const basename = cleanPath.split('/').pop() || '';
-                if (basename.startsWith('.')) {
-                    if (dotfiles === 'deny') {
-                        return { statusCode: 403, headers: {}, body: 'Forbidden' };
-                    }
-                    if (dotfiles === 'ignore') {
-                        return { statusCode: 404, headers: {}, body: 'Not Found' };
-                    }
-                }
-
-                // Check if file/directory exists
-                if (!existsSync(filePath)) {
-                    // Try fallback for SPA
-                    if (fallback) {
-                        const fallbackPath = join(rootPath, fallback);
-                        if (existsSync(fallbackPath)) {
-                            return serveFile(fallbackPath, ctx);
-                        }
-                    }
-                    return { statusCode: 404, headers: {}, body: 'Not Found' };
-                }
-
-                const stats = statSync(filePath);
-
-                // Handle directory
-                if (stats.isDirectory()) {
-                    // Try index file(s)
-                    if (index !== false) {
-                        const indexFiles = Array.isArray(index) ? index : [index];
-                        for (const indexFile of indexFiles) {
-                            const indexPath = join(filePath, indexFile);
-                            if (existsSync(indexPath)) {
-                                return serveFile(indexPath, ctx);
-                            }
-                        }
-                    }
-
-                    // Directory listing
-                    if (directory) {
-                        const html = await generateDirectoryListing(filePath, requestPath);
-                        return {
-                            statusCode: 200,
-                            headers: { 'Content-Type': 'text/html; charset=utf-8' },
-                            body: html
-                        };
-                    }
-
-                    return { statusCode: 404, headers: {}, body: 'Not Found' };
-                }
-
-                // Check extension whitelist
-                const ext = extname(filePath);
-                if (extensions && !extensions.includes(ext)) {
-                    return { statusCode: 403, headers: {}, body: 'Forbidden' };
-                }
-
-                return serveFile(filePath, ctx);
-            };
-
-            // Helper to serve a file
-            async function serveFile(filePath: string, ctx: any): Promise<Response> {
-                const stats = statSync(filePath);
-                const ext = extname(filePath);
-                const mimeType = getMimeType(ext);
-
-                const responseHeaders: Record<string, string> = {
-                    'Content-Type': mimeType,
-                    'Content-Length': stats.size.toString(),
-                    ...headers
-                };
-
-                // Cache headers
-                let cacheControl = `public, max-age=${maxAge}`;
-                if (immutable) {
-                    cacheControl += ', immutable';
-                }
-                responseHeaders['Cache-Control'] = cacheControl;
-
-                // ETag
-                if (etag) {
-                    const etagValue = generateETag(stats);
-                    responseHeaders['ETag'] = etagValue;
-
-                    // Check If-None-Match
-                    const ifNoneMatch = ctx.headers['if-none-match'];
-                    if (ifNoneMatch === etagValue) {
-                        return { statusCode: 304, headers: responseHeaders, body: '' };
-                    }
-                }
-
-                // Last-Modified
-                if (lastModified) {
-                    const lastMod = stats.mtime.toUTCString();
-                    responseHeaders['Last-Modified'] = lastMod;
-
-                    // Check If-Modified-Since
-                    const ifModifiedSince = ctx.headers['if-modified-since'];
-                    if (ifModifiedSince) {
-                        const ifModDate = new Date(ifModifiedSince);
-                        if (stats.mtime <= ifModDate) {
-                            return { statusCode: 304, headers: responseHeaders, body: '' };
-                        }
-                    }
-                }
-
-                // Check for pre-compressed version
-                if (precompressed) {
-                    const acceptEncoding = ctx.headers['accept-encoding'] || '';
-                    const compressions = Array.isArray(precompressed)
-                        ? precompressed
-                        : ['br', 'gzip'];
-
-                    for (const encoding of compressions) {
-                        if (acceptEncoding.includes(encoding)) {
-                            const ext = encoding === 'br' ? '.br' : '.gz';
-                            const compressedPath = filePath + ext;
-                            if (existsSync(compressedPath)) {
-                                const compressedStats = statSync(compressedPath);
-                                responseHeaders['Content-Encoding'] = encoding;
-                                responseHeaders['Content-Length'] = compressedStats.size.toString();
-                                responseHeaders['Vary'] = 'Accept-Encoding';
-
-                                return {
-                                    statusCode: 200,
-                                    headers: responseHeaders,
-                                    body: '',
-                                    stream: createReadStream(compressedPath)
-                                };
-                            }
-                        }
-                    }
-                }
-
-                // Stream the file
-                return {
-                    statusCode: 200,
-                    headers: responseHeaders,
-                    body: '',
-                    stream: createReadStream(filePath)
-                };
-            }
-
-            // Register static file handler
-            if (normalizedPrefix) {
-                // With prefix: only serve files under that prefix as routes
-                app.get(`${normalizedPrefix}`, staticHandler);
-                app.get(`${normalizedPrefix}/*`, staticHandler);
-            } else {
-                // Without prefix: register as fallback handler
-                // This is called when no routes match, before 404
-                if (typeof app.setFallbackHandler === 'function') {
-                    app.setFallbackHandler(staticHandler);
-                } else {
-                    // Fallback: register as low-priority wildcard routes
-                    // NOTE: This should be registered LAST after all API routes
-                    app.get('/', staticHandler);
-                    app.get('/*', staticHandler);
-                }
-            }
-
-            if (app.config?.debug) {
-                console.log(`📁 Static files: ${rootPath}`);
-                if (normalizedPrefix) {
-                    console.log(`   Prefix: ${normalizedPrefix}`);
-                }
-            }
-        }
-    };
-}

package/src/advanced/static/spa.ts

@@ -1,24 +0,0 @@
-import { Plugin } from '../../core/types';
-import { serveStatic } from './serveStatic';
-
-/**
- * Create SPA (Single Page Application) static serving
- * Falls back to index.html for client-side routing
- *
- * @example
- * ```typescript
- * app.plugin(spa());           // SPA from ./public
- * app.plugin(spa('./dist'));   // SPA from ./dist
- * ```
- */
-
-export function spa(root = './public'): Plugin {
-    return serveStatic({
-        root,
-        fallback: 'index.html',
-        maxAge: 0, // No cache for HTML
-        etag: true
-    });
-}
-
-export type { Plugin };

package/src/advanced/static/types.ts

@@ -1,159 +0,0 @@
-/**
- * MIME types mapping
- */
-
-export const MIME_TYPES: Record<string, string> = {
-    // Text
-    '.html': 'text/html; charset=utf-8',
-    '.htm': 'text/html; charset=utf-8',
-    '.css': 'text/css; charset=utf-8',
-    '.js': 'text/javascript; charset=utf-8',
-    '.mjs': 'text/javascript; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.xml': 'application/xml; charset=utf-8',
-    '.txt': 'text/plain; charset=utf-8',
-    '.md': 'text/markdown; charset=utf-8',
-    '.csv': 'text/csv; charset=utf-8',
-
-    // Images
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.gif': 'image/gif',
-    '.webp': 'image/webp',
-    '.svg': 'image/svg+xml',
-    '.ico': 'image/x-icon',
-    '.bmp': 'image/bmp',
-    '.avif': 'image/avif',
-
-    // Fonts
-    '.woff': 'font/woff',
-    '.woff2': 'font/woff2',
-    '.ttf': 'font/ttf',
-    '.otf': 'font/otf',
-    '.eot': 'application/vnd.ms-fontobject',
-
-    // Audio
-    '.mp3': 'audio/mpeg',
-    '.wav': 'audio/wav',
-    '.ogg': 'audio/ogg',
-    '.m4a': 'audio/mp4',
-    '.flac': 'audio/flac',
-
-    // Video
-    '.mp4': 'video/mp4',
-    '.webm': 'video/webm',
-    '.avi': 'video/x-msvideo',
-    '.mov': 'video/quicktime',
-    '.mkv': 'video/x-matroska',
-
-    // Documents
-    '.pdf': 'application/pdf',
-    '.doc': 'application/msword',
-    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
-    '.xls': 'application/vnd.ms-excel',
-    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
-    '.ppt': 'application/vnd.ms-powerpoint',
-    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
-
-    // Archives
-    '.zip': 'application/zip',
-    '.rar': 'application/vnd.rar',
-    '.7z': 'application/x-7z-compressed',
-    '.tar': 'application/x-tar',
-    '.gz': 'application/gzip',
-
-    // Data
-    '.wasm': 'application/wasm',
-    '.map': 'application/json',
-
-    // Default
-    '': 'application/octet-stream'
-};
-
-
-/**
- * Static file serving configuration
- */
-export interface StaticConfig {
-    /**
-     * Root directory to serve files from
-     * @default './public'
-     */
-    root?: string;
-
-    /**
-     * URL prefix for static files
-     * @default '' (serve from root)
-     * @example '/static' → /static/image.png serves ./public/image.png
-     */
-    prefix?: string;
-
-    /**
-     * Default file to serve for directory requests
-     * @default 'index.html'
-     */
-    index?: string | string[] | false;
-
-    /**
-     * Enable directory listing
-     * @default false
-     */
-    directory?: boolean;
-
-    /**
-     * Maximum age for Cache-Control header (in seconds)
-     * @default 86400 (1 day)
-     */
-    maxAge?: number;
-
-    /**
-     * Enable immutable caching (for versioned assets)
-     * @default false
-     */
-    immutable?: boolean;
-
-    /**
-     * Enable ETag generation
-     * @default true
-     */
-    etag?: boolean;
-
-    /**
-     * Enable Last-Modified header
-     * @default true
-     */
-    lastModified?: boolean;
-
-    /**
-     * Allowed file extensions (whitelist)
-     * @default undefined (allow all)
-     * @example ['.html', '.css', '.js', '.png']
-     */
-    extensions?: string[];
-
-    /**
-     * Hidden files (dotfiles) handling
-     * @default 'ignore'
-     */
-    dotfiles?: 'allow' | 'deny' | 'ignore';
-
-    /**
-     * Fallback file for SPA routing
-     * @default undefined
-     * @example 'index.html' for SPA
-     */
-    fallback?: string;
-
-    /**
-     * Custom headers to add to responses
-     */
-    headers?: Record<string, string>;
-
-    /**
-     * Enable gzip/brotli pre-compressed files
-     * Looks for .gz or .br versions of files
-     * @default false
-     */
-    precompressed?: boolean | ('gzip' | 'br')[];
-}

package/src/advanced/swagger/SwaggerGenerator.ts

@@ -1,66 +0,0 @@
-import { RouteConfig } from '../../core/types';
-import { generateSpec } from './generateSpec';
-import { generateSwaggerUI } from './generateSwaggerUI';
-import { SwaggerConfig, StoredRoute, OpenAPISchema, OpenAPISpec } from './types';
-
-// ============================================
-// LEGACY EXPORTS (backward compatibility)
-// ============================================
-/**
- * SwaggerGenerator class for advanced/manual usage
- * @deprecated Use swagger() plugin instead
- */
-
-
-export class SwaggerGenerator {
-  private config: SwaggerConfig;
-  private routes: StoredRoute[] = [];
-  private schemas: Map<string, OpenAPISchema> = new Map();
-
-  constructor(config: SwaggerConfig = {}) {
-    this.config = {
-      path: '/docs',
-      specPath: '/openapi.json',
-      ...config,
-      info: {
-        title: 'API Documentation',
-        version: '1.0.0',
-        ...config.info
-      }
-    };
-  }
-
-  registerRoutes(routes: RouteConfig[]): void {
-    this.routes.push(...routes.map(r => ({
-      method: r.method,
-      path: r.path,
-      schema: r.schema,
-      meta: r.meta
-    })));
-  }
-
-  registerRoute(route: RouteConfig): void {
-    this.routes.push({
-      method: route.method,
-      path: route.path,
-      schema: route.schema,
-      meta: route.meta
-    });
-  }
-
-  registerSchema(name: string, schema: OpenAPISchema): void {
-    this.schemas.set(name, schema);
-  }
-
-  generateSpec(): OpenAPISpec {
-    return generateSpec(this.routes, this.schemas, this.config, '');
-  }
-
-  generateSwaggerUI(): string {
-    return generateSwaggerUI(this.config);
-  }
-
-  getConfig(): SwaggerConfig {
-    return this.config;
-  }
-}

package/src/advanced/swagger/buildOperation.ts

@@ -1,61 +0,0 @@
-import { buildRequestBody } from './buildRequestBody';
-import { buildParameters } from './buildParameters';
-import { buildResponses } from './buildResponses';
-import { capitalize } from './capitalize';
-import { generateOperationId } from './generateOperationId';
-import { generateSummary } from './generateSummary';
-import { StoredRoute, SwaggerConfig, OpenAPIOperation } from './types';
-
-/**
- * Build OpenAPI operation from route
- */
-
-
-export function buildOperation(route: StoredRoute, config: SwaggerConfig): OpenAPIOperation {
-  const meta = route.meta || {};
-
-  const operation: OpenAPIOperation = {
-    responses: buildResponses(meta.responses, route.method)
-  };
-
-  // Auto-generate summary from path if not provided
-  if (meta.summary) {
-    operation.summary = meta.summary;
-  } else {
-    operation.summary = generateSummary(route.method, route.path);
-  }
-
-  if (meta.description) {
-    operation.description = meta.description;
-  }
-
-  if (meta.tags && meta.tags.length > 0) {
-    operation.tags = meta.tags;
-  } else if (!config.hideUntagged) {
-    // Auto-tag based on first path segment
-    const firstSegment = route.path.split('/').filter(Boolean)[0];
-    if (firstSegment && !firstSegment.startsWith(':')) {
-      operation.tags = [capitalize(firstSegment)];
-    }
-  }
-
-  if (meta.deprecated) {
-    operation.deprecated = true;
-  }
-
-  // Generate operation ID
-  operation.operationId = generateOperationId(route.method, route.path);
-
-  // Build parameters from schema
-  const parameters = buildParameters(route);
-  if (parameters.length > 0) {
-    operation.parameters = parameters;
-  }
-
-  // Build request body for POST/PUT/PATCH
-  if (route.schema?.body && ['POST', 'PUT', 'PATCH'].includes(route.method)) {
-    operation.requestBody = buildRequestBody(route.schema);
-  }
-
-  return operation;
-}

package/src/advanced/swagger/buildParameters.ts

@@ -1,61 +0,0 @@
-import { zodToOpenAPI } from './zodToOpenAPI';
-import { zodSchemaToOpenAPI } from './zodSchemaToOpenAPI';
-import { capitalize } from './capitalize';
-import { StoredRoute, OpenAPIParameter, OpenAPISchema } from './types';
-
-/**
- * Build parameters from route schema
- */
-
-
-export function buildParameters(route: StoredRoute): OpenAPIParameter[] {
-  const parameters: OpenAPIParameter[] = [];
-
-  // Extract path parameters
-  const pathParams = route.path.match(/:(\w+)/g);
-  if (pathParams) {
-    for (const param of pathParams) {
-      const name = param.slice(1);
-      const schemaFromZod = zodToOpenAPI(route.schema?.params, name);
-      parameters.push({
-        name,
-        in: 'path',
-        required: true,
-        description: `${capitalize(name)} parameter`,
-        schema: schemaFromZod || { type: 'string' }
-      });
-    }
-  }
-
-  // Add query parameters from schema
-  if (route.schema?.query) {
-    const querySchema = zodSchemaToOpenAPI(route.schema.query);
-    if (querySchema.properties) {
-      for (const [name, schema] of Object.entries(querySchema.properties)) {
-        parameters.push({
-          name,
-          in: 'query',
-          required: querySchema.required?.includes(name) || false,
-          schema: schema as OpenAPISchema
-        });
-      }
-    }
-  }
-
-  // Add header parameters from schema
-  if (route.schema?.headers) {
-    const headerSchema = zodSchemaToOpenAPI(route.schema.headers);
-    if (headerSchema.properties) {
-      for (const [name, schema] of Object.entries(headerSchema.properties)) {
-        parameters.push({
-          name,
-          in: 'header',
-          required: headerSchema.required?.includes(name) || false,
-          schema: schema as OpenAPISchema
-        });
-      }
-    }
-  }
-
-  return parameters;
-}

package/src/advanced/swagger/buildRequestBody.ts

@@ -1,21 +0,0 @@
-import { zodSchemaToOpenAPI } from './zodSchemaToOpenAPI';
-import { SchemaConfig } from '../../core/types';
-import { OpenAPIRequestBody, OpenAPISchema } from './types';
-
-/**
- * Build request body from schema
- */
-
-
-export function buildRequestBody(schema: SchemaConfig): OpenAPIRequestBody {
-  const bodySchema = schema.body ? zodSchemaToOpenAPI(schema.body) : { type: 'object' };
-
-  return {
-    required: true,
-    content: {
-      'application/json': {
-        schema: bodySchema as OpenAPISchema
-      }
-    }
-  };
-}

package/src/advanced/swagger/buildResponses.ts

@@ -1,54 +0,0 @@
-import { HTTPMethod } from '../../core/types';
-import { OpenAPIResponse } from './types';
-
-/**
- * Build response objects
- */
-
-
-export function buildResponses(
-  responses?: Record<number, string>,
-  method?: HTTPMethod
-): Record<string, OpenAPIResponse> {
-  const result: Record<string, OpenAPIResponse> = {};
-
-  if (responses) {
-    for (const [code, description] of Object.entries(responses)) {
-      result[code] = {
-        description,
-        content: {
-          'application/json': {
-            schema: { type: 'object' }
-          }
-        }
-      };
-    }
-  }
-
-  // Add default responses based on method
-  if (!result['200'] && !result['201'] && !result['204']) {
-    if (method === 'POST') {
-      result['201'] = {
-        description: 'Created successfully',
-        content: { 'application/json': { schema: { type: 'object' } } }
-      };
-    } else if (method === 'DELETE') {
-      result['204'] = { description: 'Deleted successfully' };
-    } else {
-      result['200'] = {
-        description: 'Successful response',
-        content: { 'application/json': { schema: { type: 'object' } } }
-      };
-    }
-  }
-
-  // Add common error responses
-  if (!result['400']) {
-    result['400'] = { description: 'Bad request' };
-  }
-  if (!result['500']) {
-    result['500'] = { description: 'Internal server error' };
-  }
-
-  return result;
-}

package/src/advanced/swagger/capitalize.ts

@@ -1,5 +0,0 @@
-
-
-export function capitalize(str: string): string {
-  return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
-}

package/src/advanced/swagger/convertPath.ts

@@ -1,9 +0,0 @@
-/**
- * Convert Express-style path to OpenAPI path
- * :id -> {id}
- */
-
-
-export function convertPath(path: string): string {
-  return path.replace(/:(\w+)/g, '{$1}');
-}