@engjts/nexus 0.1.0

package/src/advanced/static/serveStatic.ts

@@ -0,0 +1,225 @@
+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

@@ -0,0 +1,24 @@
+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.feature(spa());           // SPA from ./public
+ * app.feature(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

@@ -0,0 +1,159 @@
+/**
+ * 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

@@ -0,0 +1,66 @@
+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

@@ -0,0 +1,61 @@
+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

@@ -0,0 +1,61 @@
+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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,54 @@
+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

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

package/src/advanced/swagger/convertPath.ts

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