@engjts/nexus 0.1.0

package/src/advanced/playground/generateSummary.ts

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

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

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

@@ -0,0 +1,170 @@
+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';
+
+
+export function playground(config: PlaygroundConfig = {}): Plugin {
+    const resolvedConfig: PlaygroundConfig = {
+        path: '/playground',
+        title: 'API Playground',
+        theme: 'dark',
+        enableHistory: true,
+        maxHistory: 50,
+        enableVariables: 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) {
+            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!;
+
+            originalGet(basePath, async (ctx: any) => {
+                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) => {
+                // 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

@@ -0,0 +1,20 @@
+import { HTTPMethod, RouteMeta, SchemaConfig } from "../../core/types";
+
+export interface PlaygroundConfig {
+    path?: string;
+    title?: string;
+    theme?: 'dark' | 'light';
+    defaultHeaders?: Record<string, string>;
+    enableHistory?: boolean;
+    maxHistory?: number;
+    enableVariables?: boolean;
+    variables?: Record<string, string>;
+}
+
+
+export interface StoredRoute {
+    method: HTTPMethod;
+    path: string;
+    schema?: SchemaConfig;
+    meta?: RouteMeta;
+}

package/src/advanced/playground/zodToExample.ts

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

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

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

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

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

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

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

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

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

package/src/advanced/postman/generateCollection.ts

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

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

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

package/src/advanced/postman/generateFieldExample.ts

@@ -0,0 +1,45 @@
+import { generateExampleFromZod } from './generateExampleFromZod';
+
+
+export function generateFieldExample(field: any, fieldName: string): any {
+  if (!field?._def) return '';
+
+  const def = field._def;
+  const typeName = def.typeName;
+
+  switch (typeName) {
+    case 'ZodString': {
+      // Check for specific formats
+      for (const check of def.checks || []) {
+        if (check.kind === 'email') return 'user@example.com';
+        if (check.kind === 'url') return 'https://example.com';
+        if (check.kind === 'uuid') return '550e8400-e29b-41d4-a716-446655440000';
+      }
+      // Generate based on field name
+      if (fieldName.toLowerCase().includes('email')) return 'user@example.com';
+      if (fieldName.toLowerCase().includes('password')) return 'password123';
+      if (fieldName.toLowerCase().includes('name')) return 'John Doe';
+      if (fieldName.toLowerCase().includes('username')) return 'johndoe';
+      if (fieldName.toLowerCase().includes('phone')) return '+1234567890';
+      if (fieldName.toLowerCase().includes('token')) return 'your-token-here';
+      return 'string';
+    }
+    case 'ZodNumber':
+      return 0;
+    case 'ZodBoolean':
+      return true;
+    case 'ZodArray':
+      return [generateFieldExample(def.type, 'item')];
+    case 'ZodObject':
+      return generateExampleFromZod(field);
+    case 'ZodEnum':
+      return def.values?.[0] || 'enum';
+    case 'ZodOptional':
+    case 'ZodNullable':
+      return generateFieldExample(def.innerType, fieldName);
+    case 'ZodDefault':
+      return def.defaultValue();
+    default:
+      return '';
+  }
+}

package/src/advanced/postman/generateName.ts

@@ -0,0 +1,20 @@
+import { HTTPMethod } from '../../core/types';
+
+
+export function generateName(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} by ID` : `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/postman/generateUUID.ts

@@ -0,0 +1,11 @@
+// ============================================
+// UTILITIES
+// ============================================
+
+export function generateUUID(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    const v = c === 'x' ? r : (r & 0x3 | 0x8);
+    return v.toString(16);
+  });
+}

package/src/advanced/postman/getTagFromPath.ts

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

package/src/advanced/postman/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Postman Collection Generator for Nexus Framework
+ * Auto-generate Postman collection & environment from routes
+ * 
+ * @example
+ * ```typescript
+ * import { createApp, postman } from 'nexus';
+ * 
+ * const app = createApp();
+ * 
+ * // Zero config
+ * app.feature(postman());
+ * 
+ * // With config
+ * app.feature(postman({
+ *   path: '/postman',
+ *   name: 'My API',
+ *   baseUrl: 'http://localhost:3000'
+ * }));
+ * 
+ * // Access:
+ * // GET /postman → Download collection.json
+ * // GET /postman/environment → Download environment.json
+ * ```
+ */
+
+import { postman } from './postman';
+export default postman;