@engjts/nexus 0.1.8 → 0.1.10

package/src/advanced/playground/generateSummary.ts

@@ -1,19 +0,0 @@
-import { HTTPMethod } from '../../core/types';
-
-
-
-export function generateSummary(method: HTTPMethod, path: string): string {
-    const parts = path.split('/').filter(Boolean);
-    const resource = parts.find(p => !p.startsWith(':')) || 'resource';
-    const hasId = parts.some(p => p.startsWith(':'));
-    const actions: Record<HTTPMethod, string> = {
-        'GET': hasId ? `Get ${resource}` : `List ${resource}`,
-        'POST': `Create ${resource}`,
-        'PUT': `Update ${resource}`,
-        'PATCH': `Patch ${resource}`,
-        'DELETE': `Delete ${resource}`,
-        'HEAD': `Head ${resource}`,
-        'OPTIONS': `Options ${resource}`
-    };
-    return actions[method] || `${method} ${path}`;
-}

package/src/advanced/playground/getTagFromPath.ts

@@ -1,9 +0,0 @@
-
-
-export function getTagFromPath(path: string): string {
-    const firstSegment = path.split('/').filter(Boolean)[0];
-    if (firstSegment && !firstSegment.startsWith(':')) {
-        return firstSegment.charAt(0).toUpperCase() + firstSegment.slice(1);
-    }
-    return 'General';
-}

package/src/advanced/playground/index.ts

@@ -1,8 +0,0 @@
-
-
-/**
- * API Playground for Nexus Framework
- * Interactive API explorer with Monaco Editor (VS Code's editor)
- */
-export { playground } from './playground';
-export { PlaygroundConfig } from './types';

package/src/advanced/playground/playground.ts

@@ -1,250 +0,0 @@
-import { extractPathParams } from './extractPathParams';
-import { zodToParams } from './zodToParams';
-import { zodToExample } from './zodToExample';
-import { getTagFromPath } from './getTagFromPath';
-import { generateSummary } from './generateSummary';
-import { generatePlaygroundHTML } from './generatePlaygroundHTML';
-import { Application } from '../../core/application';
-import { RouteConfig, HTTPMethod, Context, Plugin, SchemaConfig, RouteMeta } from '../../core/types';
-import { PlaygroundConfig, StoredRoute } from './types';
-
-
-/**
- * API Playground Plugin
- * Provides an interactive API explorer with authentication and development-mode security
- * 
- * @param config - Configuration options for the playground
- * @returns Plugin instance
- * 
- * @example
- * ```typescript
- * app.use(playground({
- *   path: '/playground',
- *   developmentOnly: true,
- *   auth: {
- *     username: 'admin',
- *     password: 'secret123'
- *   }
- * }));
- * ```
- */
-export function playground(config: PlaygroundConfig = {}): Plugin {
-  const resolvedConfig: PlaygroundConfig = {
-    path: '/playground',
-    title: 'API Playground',
-    theme: 'dark',
-    enableHistory: true,
-    maxHistory: 50,
-    enableVariables: true,
-    developmentOnly: true,
-    defaultHeaders: { 'Content-Type': 'application/json' },
-    variables: { baseUrl: 'http://localhost:3000', token: '' },
-    ...config
-  };
-
-  const routes: StoredRoute[] = [];
-  let detectedBaseUrl = '';
-  let appInstance: Application | null = null;
-
-  return {
-    name: 'playground',
-    version: '1.0.0',
-
-    install(app: Application) {
-      // Check if playground should be disabled in production
-      if (resolvedConfig.developmentOnly && process.env.NODE_ENV === 'production') {
-        console.warn('⚠️  API Playground is disabled in production mode');
-        return;
-      }
-
-      appInstance = app;
-      const originalRoute = app.route.bind(app);
-      const originalGet = app.get.bind(app);
-      const originalPost = app.post.bind(app);
-      const originalPut = app.put.bind(app);
-      const originalDelete = app.delete.bind(app);
-      const originalPatch = app.patch.bind(app);
-
-      app.route = function (routeConfig: RouteConfig) {
-        routes.push({
-          method: routeConfig.method,
-          path: routeConfig.path,
-          schema: routeConfig.schema,
-          meta: routeConfig.meta
-        });
-        return originalRoute(routeConfig);
-      };
-
-      const wrapMethod = (method: HTTPMethod, original: Function) => {
-        return function (pathOrRoute: string | any, handlerOrConfig?: any) {
-          // Class-based routing
-          if (typeof pathOrRoute === 'object' && 'pathName' in pathOrRoute) {
-            const route = pathOrRoute;
-            routes.push({
-              method,
-              path: route.pathName,
-              schema: route.schema?.(),
-              meta: route.meta?.()
-            });
-            return original(pathOrRoute);
-          }
-
-          const path = pathOrRoute;
-          if (typeof handlerOrConfig !== 'function' && handlerOrConfig) {
-            routes.push({ method, path, schema: handlerOrConfig.schema, meta: handlerOrConfig.meta });
-          } else {
-            routes.push({ method, path });
-          }
-          return original(path, handlerOrConfig);
-        };
-      };
-
-      app.get = wrapMethod('GET', originalGet);
-      app.post = wrapMethod('POST', originalPost);
-      app.put = wrapMethod('PUT', originalPut);
-      app.delete = wrapMethod('DELETE', originalDelete);
-      app.patch = wrapMethod('PATCH', originalPatch);
-
-      const basePath = resolvedConfig.path!;
-
-      /**
-       * Authentication middleware for playground routes
-       * Implements HTTP Basic Authentication when auth config is provided
-       */
-      const authMiddleware = (ctx: any) => {
-        if (!resolvedConfig.auth) {
-          return true; // No auth required
-        }
-
-        const authHeader = ctx.raw?.req?.headers?.authorization || ctx.headers?.get?.('authorization');
-
-        if (!authHeader || !authHeader.startsWith('Basic ')) {
-          return false;
-        }
-
-        try {
-          const base64Credentials = authHeader.substring(6);
-          const credentials = Buffer.from(base64Credentials, 'base64').toString('utf-8');
-          const [username, password] = credentials.split(':');
-
-          return (
-            username === resolvedConfig.auth.username &&
-            password === resolvedConfig.auth.password
-          );
-        } catch (error) {
-          return false;
-        }
-      };
-
-      /**
-       * Returns 401 Unauthorized response with WWW-Authenticate header
-       * This triggers the browser's native authentication dialog
-       */
-      const unauthorizedResponse = () => {
-        return {
-          statusCode: 401,
-          headers: {
-            'WWW-Authenticate': 'Basic realm="API Playground"',
-            'Content-Type': 'text/plain'
-          },
-          body: 'Unauthorized'
-        };
-      };
-
-      originalGet(basePath, async (ctx: any) => {
-        // Check authentication
-        if (!authMiddleware(ctx)) {
-          return unauthorizedResponse();
-        }
-
-        if (!detectedBaseUrl && ctx.raw?.req) {
-          const req = ctx.raw.req;
-          const protocol = req.headers['x-forwarded-proto'] || 'http';
-          const host = req.headers.host || 'localhost:3000';
-          detectedBaseUrl = `${protocol}://${host}`;
-        }
-        return {
-          statusCode: 200,
-          headers: { 'Content-Type': 'text/html; charset=utf-8' },
-          body: generatePlaygroundHTML(resolvedConfig, detectedBaseUrl)
-        };
-      });
-
-      originalGet(basePath + '/api/routes', async (ctx: Context) => {
-        // Check authentication
-        if (!authMiddleware(ctx)) {
-          return unauthorizedResponse();
-        }
-
-        // Combine intercepted routes with routes from router (for file-based routing)
-        const allRoutes = getAllRoutes(routes, appInstance, basePath);
-
-        const routesData = allRoutes.map(r => ({
-          method: r.method,
-          path: r.path,
-          summary: r.meta?.summary || generateSummary(r.method as HTTPMethod, r.path),
-          description: r.meta?.description,
-          tags: r.meta?.tags || [getTagFromPath(r.path)],
-          deprecated: r.meta?.deprecated,
-          responses: r.meta?.responses,
-          example: r.meta?.example,
-          schema: {
-            body: r.schema?.body ? zodToExample(r.schema.body) : null,
-            query: r.schema?.query ? zodToParams(r.schema.query) : null,
-            params: extractPathParams(r.path)
-          }
-        }));
-        return ctx.json(routesData);
-      });
-    }
-  };
-}
-
-/**
- * Get all routes by combining intercepted routes with routes from the router
- * This ensures file-based routes are also included
- */
-function getAllRoutes(
-  interceptedRoutes: StoredRoute[],
-  app: Application | null,
-  basePath: string
-): StoredRoute[] {
-  // Create a Set of already tracked route keys (method + path)
-  const trackedKeys = new Set(
-    interceptedRoutes.map(r => `${r.method}:${r.path}`)
-  );
-
-  // Start with intercepted routes (filtered)
-  const allRoutes: StoredRoute[] = interceptedRoutes.filter(
-    r => !r.path.startsWith(basePath)
-  );
-
-  // Get routes from router (includes file-based routes)
-  if (app) {
-    const routerRoutes = app.getRoutes() as Array<{
-      method: string;
-      path: string;
-      schema?: SchemaConfig;
-      meta?: RouteMeta;
-    }>;
-
-    for (const route of routerRoutes) {
-      const key = `${route.method}:${route.path}`;
-
-      // Skip if already tracked or is playground route
-      if (trackedKeys.has(key) || route.path.startsWith(basePath)) {
-        continue;
-      }
-
-      allRoutes.push({
-        method: route.method as HTTPMethod,
-        path: route.path,
-        schema: route.schema,
-        meta: route.meta
-      });
-    }
-  }
-
-  // Sort routes by path for consistent ordering
-  return allRoutes.sort((a, b) => a.path.localeCompare(b.path));
-}

package/src/advanced/playground/types.ts

@@ -1,49 +0,0 @@
-import { HTTPMethod, RouteMeta, SchemaConfig } from "../../core/types";
-
-/**
- * Configuration options for the API Playground
- */
-export interface PlaygroundConfig {
-    /** URL path where the playground will be accessible (default: '/playground') */
-    path?: string;
-    
-    /** Title displayed in the playground UI (default: 'API Playground') */
-    title?: string;
-    
-    /** Color theme for the playground interface (default: 'dark') */
-    theme?: 'dark' | 'light';
-    
-    /** Default HTTP headers to include in API requests */
-    defaultHeaders?: Record<string, string>;
-    
-    /** Enable/disable request history tracking (default: true) */
-    enableHistory?: boolean;
-    
-    /** Maximum number of requests to keep in history (default: 50) */
-    maxHistory?: number;
-    
-    /** Enable/disable variable substitution in requests (default: true) */
-    enableVariables?: boolean;
-    
-    /** Predefined variables for use in requests (e.g., {{baseUrl}}, {{token}}) */
-    variables?: Record<string, string>;
-    
-    /** Enable only in development mode (default: true) */
-    developmentOnly?: boolean;
-    
-    /** Basic authentication configuration to protect playground access */
-    auth?: {
-        /** Username for basic authentication */
-        username: string;
-        /** Password for basic authentication */
-        password: string;
-    };
-}
-
-
-export interface StoredRoute {
-    method: HTTPMethod;
-    path: string;
-    schema?: SchemaConfig;
-    meta?: RouteMeta;
-}

package/src/advanced/playground/zodToExample.ts

@@ -1,16 +0,0 @@
-import { generateFieldExample } from './generateFieldExample';
-
-
-
-export function zodToExample(schema: any): any {
-    if (!schema?._def) return {};
-    try {
-        const shape = schema._def?.shape?.() || schema.shape;
-        if (!shape) return {};
-        const example: Record<string, any> = {};
-        for (const [key, value] of Object.entries(shape)) {
-            example[key] = generateFieldExample(value, key);
-        }
-        return example;
-    } catch { return {}; }
-}

package/src/advanced/playground/zodToParams.ts

@@ -1,15 +0,0 @@
-
-
-export function zodToParams(schema: any): Array<{ name: string; optional: boolean; }> {
-    const params: Array<{ name: string; optional: boolean; }> = [];
-    try {
-        const shape = schema._def?.shape?.() || schema.shape;
-        if (shape) {
-            for (const [key, value] of Object.entries(shape)) {
-                const def = (value as any)?._def;
-                params.push({ name: key, optional: def?.typeName === 'ZodOptional' });
-            }
-        }
-    } catch { }
-    return params;
-}

package/src/advanced/postman/buildAuth.ts

@@ -1,31 +0,0 @@
-import { PostmanAuth } from './types';
-
-
-export function buildAuth(auth: PostmanAuth): any {
-  switch (auth.type) {
-    case 'bearer':
-      return {
-        type: 'bearer',
-        bearer: [{ key: 'token', value: auth.bearer?.token || '{{token}}', type: 'string' }]
-      };
-    case 'apikey':
-      return {
-        type: 'apikey',
-        apikey: [
-          { key: 'key', value: auth.apikey?.key || 'X-API-Key', type: 'string' },
-          { key: 'value', value: auth.apikey?.value || '{{apiKey}}', type: 'string' },
-          { key: 'in', value: auth.apikey?.in || 'header', type: 'string' }
-        ]
-      };
-    case 'basic':
-      return {
-        type: 'basic',
-        basic: [
-          { key: 'username', value: auth.basic?.username || '{{username}}', type: 'string' },
-          { key: 'password', value: auth.basic?.password || '{{password}}', type: 'string' }
-        ]
-      };
-    default:
-      return undefined;
-  }
-}

package/src/advanced/postman/buildBody.ts

@@ -1,15 +0,0 @@
-import { generateExampleFromZod } from './generateExampleFromZod';
-import { PostmanBody } from './types';
-
-
-export function buildBody(bodySchema: any): PostmanBody {
-  const example = generateExampleFromZod(bodySchema);
-
-  return {
-    mode: 'raw',
-    raw: JSON.stringify(example, null, 2),
-    options: {
-      raw: { language: 'json' }
-    }
-  };
-}

package/src/advanced/postman/buildQueryParams.ts

@@ -1,27 +0,0 @@
-import { PostmanQuery } from './types';
-
-
-export function buildQueryParams(querySchema: any): PostmanQuery[] {
-  const params: PostmanQuery[] = [];
-
-  try {
-    const shape = querySchema._def?.shape?.() || querySchema.shape;
-    if (shape) {
-      for (const [key, value] of Object.entries(shape)) {
-        const def = (value as any)?._def;
-        const isOptional = def?.typeName === 'ZodOptional';
-
-        params.push({
-          key,
-          value: '',
-          disabled: isOptional,
-          description: isOptional ? '(optional)' : undefined
-        });
-      }
-    }
-  } catch {
-    // Ignore errors
-  }
-
-  return params;
-}

package/src/advanced/postman/buildRequestItem.ts

@@ -1,36 +0,0 @@
-import { buildBody } from './buildBody';
-import { buildResponses } from './buildResponses';
-import { buildUrl } from './buildUrl';
-import { generateName } from './generateName';
-import { StoredRoute, PostmanConfig, PostmanItem } from './types';
-
-
-export function buildRequestItem(route: StoredRoute, config: PostmanConfig): PostmanItem {
-  const meta = route.meta || {};
-  const name = meta.summary || generateName(route.method, route.path);
-
-  const item: PostmanItem = {
-    name,
-    request: {
-      method: route.method,
-      header: [
-        { key: 'Content-Type', value: 'application/json', type: 'text' },
-        { key: 'Accept', value: 'application/json', type: 'text' }
-      ],
-      url: buildUrl(route),
-      description: meta.description
-    }
-  };
-
-  // Add request body for POST/PUT/PATCH
-  if (route.schema?.body && ['POST', 'PUT', 'PATCH'].includes(route.method)) {
-    item.request!.body = buildBody(route.schema.body);
-  }
-
-  // Add example responses
-  if (config.includeExamples && meta.responses) {
-    item.response = buildResponses(meta.responses, name);
-  }
-
-  return item;
-}

package/src/advanced/postman/buildResponses.ts

@@ -1,11 +0,0 @@
-import { PostmanResponse } from './types';
-
-
-export function buildResponses(responses: Record<number, string>, requestName: string): PostmanResponse[] {
-  return Object.entries(responses).map(([code, description]) => ({
-    name: `${requestName} - ${description}`,
-    status: description,
-    code: parseInt(code),
-    body: JSON.stringify({ message: description }, null, 2)
-  }));
-}

package/src/advanced/postman/buildUrl.ts

@@ -1,33 +0,0 @@
-import { buildQueryParams } from './buildQueryParams';
-import { capitalize } from './capitalize';
-import { StoredRoute, PostmanUrl } from './types';
-
-
-export function buildUrl(route: StoredRoute): PostmanUrl {
-  // Convert :param to {{param}} for Postman
-  const pathWithVars = route.path.replace(/:(\w+)/g, '{{$1}}');
-  const pathParts = pathWithVars.split('/').filter(Boolean);
-
-  const url: PostmanUrl = {
-    raw: '{{baseUrl}}' + pathWithVars,
-    host: ['{{baseUrl}}'],
-    path: pathParts
-  };
-
-  // Add path variables
-  const pathParams = route.path.match(/:(\w+)/g);
-  if (pathParams) {
-    url.variable = pathParams.map(p => ({
-      key: p.slice(1),
-      value: '',
-      description: `${capitalize(p.slice(1))} parameter`
-    }));
-  }
-
-  // Add query parameters from schema
-  if (route.schema?.query) {
-    url.query = buildQueryParams(route.schema.query);
-  }
-
-  return url;
-}

package/src/advanced/postman/capitalize.ts

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

package/src/advanced/postman/generateCollection.ts

@@ -1,59 +0,0 @@
-import { buildAuth } from './buildAuth';
-import { buildRequestItem } from './buildRequestItem';
-import { generateUUID } from './generateUUID';
-import { getTagFromPath } from './getTagFromPath';
-import { StoredRoute, PostmanConfig, PostmanCollection, PostmanItem } from './types';
-
-// ============================================
-// COLLECTION GENERATION
-// ============================================
-
-export function generateCollection(
-  routes: StoredRoute[],
-  config: PostmanConfig,
-  baseUrl: string
-): PostmanCollection {
-  const collection: PostmanCollection = {
-    info: {
-      _postman_id: generateUUID(),
-      name: config.name!,
-      description: config.description,
-      schema: 'https://schema.getpostman.com/json/collection/v2.1.0/collection.json'
-    },
-    item: [],
-    variable: [
-      { key: 'baseUrl', value: baseUrl, type: 'string' }
-    ]
-  };
-
-  // Add auth if configured
-  if (config.auth) {
-    collection.auth = buildAuth(config.auth);
-  }
-
-  // Group routes by tags
-  const grouped = new Map<string, StoredRoute[]>();
-
-  for (const route of routes) {
-    // Skip postman's own endpoints
-    if (route.path.startsWith(config.path!)) continue;
-
-    const tag = route.meta?.tags?.[0] || getTagFromPath(route.path);
-
-    if (!grouped.has(tag)) {
-      grouped.set(tag, []);
-    }
-    grouped.get(tag)!.push(route);
-  }
-
-  // Build folder structure
-  for (const [tag, tagRoutes] of grouped) {
-    const folder: PostmanItem = {
-      name: tag,
-      item: tagRoutes.map(route => buildRequestItem(route, config))
-    };
-    collection.item.push(folder);
-  }
-
-  return collection;
-}

package/src/advanced/postman/generateEnvironment.ts

@@ -1,34 +0,0 @@
-import { generateUUID } from './generateUUID';
-import { PostmanConfig, PostmanEnvironment, PostmanEnvVariable } from './types';
-
-// ============================================
-// ENVIRONMENT GENERATION
-// ============================================
-
-export function generateEnvironment(config: PostmanConfig, baseUrl: string): PostmanEnvironment {
-  const variables: PostmanEnvVariable[] = [
-    { key: 'baseUrl', value: baseUrl, type: 'default', enabled: true },
-    { key: 'token', value: '', type: 'secret', enabled: true },
-    { key: 'apiKey', value: '', type: 'secret', enabled: true }
-  ];
-
-  // Add custom variables
-  if (config.variables) {
-    for (const [key, value] of Object.entries(config.variables)) {
-      variables.push({
-        key,
-        value,
-        type: key.toLowerCase().includes('secret') || key.toLowerCase().includes('key')
-          ? 'secret' : 'default',
-        enabled: true
-      });
-    }
-  }
-
-  return {
-    id: generateUUID(),
-    name: config.environmentName!,
-    values: variables,
-    _postman_variable_scope: 'environment'
-  };
-}

package/src/advanced/postman/generateExampleFromZod.ts

@@ -1,21 +0,0 @@
-import { generateFieldExample } from './generateFieldExample';
-
-
-export function generateExampleFromZod(schema: any): any {
-  if (!schema?._def) return {};
-
-  try {
-    const shape = schema._def?.shape?.() || schema.shape;
-    if (!shape) return {};
-
-    const example: Record<string, any> = {};
-
-    for (const [key, value] of Object.entries(shape)) {
-      example[key] = generateFieldExample(value, key);
-    }
-
-    return example;
-  } catch {
-    return {};
-  }
-}