@engjts/nexus 0.1.0

package/src/advanced/postman/postman.ts

@@ -0,0 +1,156 @@
+import { Application } from '../../core/application';
+import { RouteConfig, HTTPMethod, Context, Plugin } from '../../core/types';
+import { generateCollection } from './generateCollection';
+import { generateEnvironment } from './generateEnvironment';
+import { slugify } from './slugify';
+import { PostmanConfig, StoredRoute } from './types';
+
+// ============================================
+// POSTMAN FEATURE (PLUGIN)
+// ============================================
+/**
+ * Create Postman feature plugin for Nexus
+ */
+
+export function postman(config: PostmanConfig = {}): Plugin {
+  const resolvedConfig: PostmanConfig = {
+    path: '/postman',
+    name: 'API Collection',
+    description: 'Auto-generated Postman collection',
+    environmentName: 'API Environment',
+    includeExamples: true,
+    ...config
+  };
+
+  const routes: StoredRoute[] = [];
+  let detectedBaseUrl = '';
+
+  return {
+    name: 'postman',
+    version: '1.0.0',
+
+    install(app: Application) {
+      // Hook into route registration
+      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!;
+
+      // GET /postman → Download collection
+      originalGet(basePath, async (ctx: Context) => {
+        // Auto-detect base URL
+        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}`;
+        }
+
+        const baseUrl = resolvedConfig.baseUrl || detectedBaseUrl || 'http://localhost:3000';
+        const collection = generateCollection(routes, resolvedConfig, baseUrl);
+        const filename = `${slugify(resolvedConfig.name!)}_collection.json`;
+
+        return {
+          statusCode: 200,
+          headers: {
+            'Content-Type': 'application/json',
+            'Content-Disposition': `attachment; filename="${filename}"`
+          },
+          body: JSON.stringify(collection, null, 2)
+        };
+      });
+
+      // GET /postman/environment → Download environment
+      originalGet(basePath + '/environment', async (ctx: Context) => {
+        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}`;
+        }
+
+        const baseUrl = resolvedConfig.baseUrl || detectedBaseUrl || 'http://localhost:3000';
+        const environment = generateEnvironment(resolvedConfig, baseUrl);
+        const filename = `${slugify(resolvedConfig.environmentName!)}_environment.json`;
+
+        return {
+          statusCode: 200,
+          headers: {
+            'Content-Type': 'application/json',
+            'Content-Disposition': `attachment; filename="${filename}"`
+          },
+          body: JSON.stringify(environment, null, 2)
+        };
+      });
+
+      // GET /postman/preview → Preview collection (no download)
+      originalGet(basePath + '/preview', async (ctx: Context) => {
+        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}`;
+        }
+
+        const baseUrl = resolvedConfig.baseUrl || detectedBaseUrl || 'http://localhost:3000';
+        const collection = generateCollection(routes, resolvedConfig, baseUrl);
+
+        return ctx.json(collection);
+      });
+
+      if (process.env.DEBUG === 'true' || process.env.NODE_ENV === 'development') {
+        console.log(`📦 Postman Collection: ${basePath}`);
+        console.log(`🌍 Postman Environment: ${basePath}/environment`);
+      }
+    }
+  };
+}

package/src/advanced/postman/slugify.ts

@@ -0,0 +1,7 @@
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_|_$/g, '');
+}

package/src/advanced/postman/types.ts

@@ -0,0 +1,140 @@
+import { HTTPMethod, SchemaConfig, RouteMeta } from '../../core/types';
+
+// ============================================
+// TYPES & INTERFACES
+// ============================================
+/**
+ * Postman configuration options
+ */
+
+export interface PostmanConfig {
+  /** Path to serve Postman endpoints (default: /postman) */
+  path?: string;
+  /** Collection name */
+  name?: string;
+  /** Collection description */
+  description?: string;
+  /** Base URL for requests (auto-detected if not provided) */
+  baseUrl?: string;
+  /** Environment name */
+  environmentName?: string;
+  /** Additional environment variables */
+  variables?: Record<string, string>;
+  /** Auth type for collection */
+  auth?: PostmanAuth;
+  /** Include example responses */
+  includeExamples?: boolean;
+}
+
+
+/**
+ * Postman auth configuration
+ */
+export interface PostmanAuth {
+  type: 'bearer' | 'apikey' | 'basic' | 'oauth2';
+  bearer?: { token: string };
+  apikey?: { key: string; value: string; in: 'header' | 'query' };
+  basic?: { username: string; password: string };
+}
+
+/**
+ * Postman Collection v2.1 format
+ */
+export interface PostmanCollection {
+  info: {
+    _postman_id: string;
+    name: string;
+    description?: string;
+    schema: string;
+  };
+  item: PostmanItem[];
+  auth?: any;
+  variable?: PostmanVariable[];
+}
+
+export interface PostmanItem {
+  name: string;
+  item?: PostmanItem[];
+  request?: PostmanRequest;
+  response?: PostmanResponse[];
+}
+
+export interface PostmanRequest {
+  method: string;
+  header: PostmanHeader[];
+  url: PostmanUrl;
+  body?: PostmanBody;
+  description?: string;
+  auth?: any;
+}
+
+export interface PostmanHeader {
+  key: string;
+  value: string;
+  type: string;
+  disabled?: boolean;
+}
+
+export interface PostmanUrl {
+  raw: string;
+  host: string[];
+  path: string[];
+  query?: PostmanQuery[];
+  variable?: PostmanVariable[];
+}
+
+export interface PostmanQuery {
+  key: string;
+  value: string;
+  disabled?: boolean;
+  description?: string;
+}
+
+export interface PostmanVariable {
+  key: string;
+  value: string;
+  type?: string;
+  description?: string;
+}
+
+export interface PostmanBody {
+  mode: 'raw' | 'formdata' | 'urlencoded';
+  raw?: string;
+  options?: {
+    raw: { language: string };
+  };
+}
+
+export interface PostmanResponse {
+  name: string;
+  status: string;
+  code: number;
+  body?: string;
+}
+
+/**
+ * Postman Environment format
+ */
+export interface PostmanEnvironment {
+  id: string;
+  name: string;
+  values: PostmanEnvVariable[];
+  _postman_variable_scope: string;
+}
+
+export interface PostmanEnvVariable {
+  key: string;
+  value: string;
+  type: string;
+  enabled: boolean;
+}
+
+/**
+ * Internal route storage
+ */
+export interface StoredRoute {
+  method: HTTPMethod;
+  path: string;
+  schema?: SchemaConfig;
+  meta?: RouteMeta;
+}

package/src/advanced/realtime/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Nexus Realtime Module
+ * 
+ * Optional WebSocket/Realtime integration for Nexus framework.
+ * Requires `ws` as peer dependency.
+ * 
+ * Install: npm install ws
+ * 
+ * Usage:
+ * import { WebSocketGateway } from '@engjts/server/realtime';
+ */
+
+export {
+    WebSocketGateway,
+    type WebSocketContext,
+    type WebSocketRoute,
+    type WebSocketRouteConfig
+} from './websocket';

package/src/advanced/realtime/websocket.ts

@@ -0,0 +1,211 @@
+import { IncomingMessage, Server as HTTPServer } from 'http';
+import { parse as parseUrl } from 'url';
+import { EventEmitter } from 'events';
+import WebSocket, { WebSocketServer } from 'ws';
+
+export interface WebSocketContext {
+    path: string;
+    query: Record<string, string | string[]>;
+    headers: IncomingMessage['headers'];
+    user?: any;
+    metadata?: Record<string, any>;
+    raw: {
+        req: IncomingMessage;
+    };
+}
+
+export interface WebSocketRouteConfig {
+    auth?: (ctx: WebSocketContext) => Promise<any>;
+    beforeConnect?: (socket: WebSocket, ctx: WebSocketContext) => Promise<void>;
+    onConnect?: (socket: WebSocket, ctx: WebSocketContext) => Promise<void>;
+    onMessage?: (socket: WebSocket, message: any, ctx: WebSocketContext) => Promise<void>;
+    onClose?: (socket: WebSocket, ctx: WebSocketContext, code: number, reason?: Buffer) => Promise<void>;
+    onError?: (socket: WebSocket, error: Error, ctx: WebSocketContext) => Promise<void>;
+    rooms?: boolean;
+}
+
+export interface WebSocketRoute extends WebSocketRouteConfig {
+    path: string;
+}
+
+export interface ConnectionState {
+    ctx: WebSocketContext;
+    route: WebSocketRoute;
+}
+
+/**
+ * WebSocket gateway with room management and authentication hooks
+ */
+export class WebSocketGateway extends EventEmitter {
+    private routes: Map<string, WebSocketRoute> = new Map();
+    private wss?: WebSocketServer;
+    private connections: WeakMap<WebSocket, ConnectionState> = new WeakMap();
+    private rooms: Map<string, Set<WebSocket>> = new Map();
+    private socketRooms: WeakMap<WebSocket, Set<string>> = new WeakMap();
+
+    register(path: string, config: WebSocketRouteConfig) {
+        if (!path.startsWith('/')) {
+            throw new Error('WebSocket route path must start with "/"');
+        }
+        this.routes.set(path, { ...config, path });
+    }
+
+    attach(server: HTTPServer) {
+        if (this.wss) {
+            return;
+        }
+
+        this.wss = new WebSocketServer({ noServer: true });
+
+        server.on('upgrade', async (req, socket, head) => {
+            try {
+                const pathname = parseUrl(req.url || '').pathname || '/';
+                const route = this.routes.get(pathname);
+
+                if (!route) {
+                    socket.destroy();
+                    return;
+                }
+
+                const ctx = this.createContext(req, pathname);
+                if (route.auth) {
+                    ctx.user = await route.auth(ctx);
+                }
+
+                this.wss!.handleUpgrade(req, socket, head, (ws: WebSocket) => {
+                    this.bindConnection(ws, route, ctx);
+                });
+            } catch (error) {
+                socket.destroy();
+            }
+        });
+    }
+
+    broadcast(room: string, payload: any) {
+        const sockets = this.rooms.get(room);
+        if (!sockets) return;
+
+        for (const socket of sockets) {
+            if (socket.readyState === WebSocket.OPEN) {
+                socket.send(JSON.stringify(payload));
+            }
+        }
+    }
+
+    createRoom(name: string) {
+        if (!this.rooms.has(name)) {
+            this.rooms.set(name, new Set());
+        }
+    }
+
+    joinRoom(room: string, socket: WebSocket) {
+        this.createRoom(room);
+        const sockets = this.rooms.get(room)!;
+        sockets.add(socket);
+
+        const joinedRooms = this.socketRooms.get(socket) ?? new Set<string>();
+        joinedRooms.add(room);
+        this.socketRooms.set(socket, joinedRooms);
+    }
+
+    leaveRoom(room: string, socket: WebSocket) {
+        const sockets = this.rooms.get(room);
+        if (!sockets) return;
+        sockets.delete(socket);
+
+        const joinedRooms = this.socketRooms.get(socket);
+        joinedRooms?.delete(room);
+    }
+
+    private bindConnection(socket: WebSocket, route: WebSocketRoute, ctx: WebSocketContext) {
+        this.connections.set(socket, { ctx, route });
+        this.emit('connection', socket, ctx);
+
+        socket.on('message', async (data: WebSocket.RawData) => {
+            try {
+                const payload = this.parseMessage(data);
+                await route.onMessage?.(socket, payload, ctx);
+                this.emit('message', socket, payload, ctx);
+            } catch (error) {
+                await route.onError?.(socket, error as Error, ctx);
+                this.emit('error', error, socket, ctx);
+            }
+        });
+
+        socket.on('close', async (code: number, buffer: Buffer) => {
+            await route.onClose?.(socket, ctx, code, buffer);
+            this.cleanupSocket(socket);
+            this.emit('close', socket, ctx);
+        });
+
+        socket.on('error', async (error: Error) => {
+            await route.onError?.(socket, error, ctx);
+            this.emit('error', error, socket, ctx);
+        });
+
+        void (async () => {
+            if (route.beforeConnect) {
+                await route.beforeConnect(socket, ctx);
+            }
+            await route.onConnect?.(socket, ctx);
+        })();
+    }
+
+    private createContext(req: IncomingMessage, path: string): WebSocketContext {
+        const parsed = parseUrl(req.url || '', true);
+        return {
+            path,
+            query: parsed.query as Record<string, string | string[]>,
+            headers: req.headers,
+            raw: { req }
+        };
+    }
+
+    private parseMessage(data: WebSocket.RawData): any {
+        if (Buffer.isBuffer(data) || data instanceof ArrayBuffer) {
+            const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+            const stringPayload = buffer.toString('utf-8');
+            try {
+                return JSON.parse(stringPayload);
+            } catch {
+                return stringPayload;
+            }
+        }
+
+        if (Array.isArray(data)) {
+            return data.map((item): any => this.parseMessage(item as WebSocket.RawData));
+        }
+
+        // Handle string case
+        try {
+            return JSON.parse(data as string);
+        } catch {
+            return data as string;
+        }
+    }
+
+    private cleanupSocket(socket: WebSocket) {
+        const rooms = this.socketRooms.get(socket);
+        if (rooms) {
+            for (const room of rooms) {
+                this.rooms.get(room)?.delete(socket);
+            }
+        }
+        this.socketRooms.delete(socket);
+        this.connections.delete(socket);
+    }
+
+    /**
+     * Helper object to expose room operations in a structured way
+     */
+    get roomManager() {
+        return {
+            create: (name: string) => this.createRoom(name),
+            join: (name: string, socket: WebSocket) => this.joinRoom(name, socket),
+            leave: (name: string, socket: WebSocket) => this.leaveRoom(name, socket),
+            broadcast: (name: string, payload: any) => this.broadcast(name, payload),
+            list: () => Array.from(this.rooms.keys())
+        };
+    }
+}
+