bro-framework 2.4.4 → 3.0.0

package/package.json

@@ -1,103 +1,138 @@
-{
-  "name": "bro-framework",
-  "version": "2.4.4",
-  "description": "The No-BS Backend Framework for Node.js",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/medyass1ne/bro.js"
-  },
-  "homepage": "https://brojs.yessindevs.me",
-  "author": "Yessindevs",
-  "license": "MIT",
-  "main": "src/index.js",
-  "types": "src/index.d.ts",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./src/index.d.ts",
-      "import": "./src/index.js",
-      "require": "./src/index.js",
-      "default": "./src/index.js"
-    },
-    "./next": {
-      "types": "./src/next.d.ts",
-      "import": "./src/next.js",
-      "require": "./src/next.js",
-      "default": "./src/next.js"
-    }
-  },
-  "bin": {
-    "bro": "./bin/bro.js"
-  },
-  "files": [
-    "src",
-    "bin"
-  ],
-  "dependencies": {
-    "@scalar/express-api-reference": "^0.10.18",
-    "@socket.io/redis-adapter": "^8.3.0",
-    "chokidar": "^5.0.0",
-    "cors": "^2.8.6",
-    "dotenv": "^16.4.5",
-    "express": "^4.21.1",
-    "express-rate-limit": "^8.7.0",
-    "helmet": "^8.3.0",
-    "jsonwebtoken": "^9.0.2",
-    "multer": "^2.3.0",
-    "node-cron": "^4.6.0",
-    "redis": "^6.2.1",
-    "socket.io": "^4.8.3",
-    "tsx": "^4.23.13",
-    "zod": "^3.23.8",
-    "zod-to-json-schema": "^3.25.2"
-  },
-  "keywords": [
-    "bro",
-    "brojs",
-    "bro.js",
-    "bro-framework",
-    "framework",
-    "backend",
-    "api",
-    "server",
-    "node",
-    "nodejs",
-    "express",
-    "rest",
-    "zero-config",
-    "zero-boilerplate",
-    "file-based-routing",
-    "auto-routing",
-    "zod",
-    "validation",
-    "jwt",
-    "authentication",
-    "auth",
-    "websocket",
-    "websockets",
-    "socket.io",
-    "realtime",
-    "openapi",
-    "swagger",
-    "scalar",
-    "docs",
-    "auto-docs",
-    "sdk",
-    "sdk-generator",
-    "rpc",
-    "trpc-alternative",
-    "express-alternative",
-    "cron",
-    "scheduler",
-    "background-tasks",
-    "file-upload",
-    "rate-limit",
-    "esm",
-    "ai-friendly",
-    "developer-experience",
-    "dx"
-  ],
-  "devDependencies": {
-    "ioredis-mock": "^8.13.1"
-  }
-}
+{
+  "name": "bro-framework",
+  "version": "3.0.0",
+  "description": "The No-BS Backend Framework for Node.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/medyass1ne/bro.js"
+  },
+  "homepage": "https://brojs.yessindevs.me",
+  "author": "Yessindevs",
+  "license": "MIT",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "node": {
+        "types": "./src/index.d.ts",
+        "import": "./src/index.js",
+        "require": "./src/index.js"
+      },
+      "edge": {
+        "types": "./src/next.d.ts",
+        "import": "./src/edge.js"
+      },
+      "workerd": {
+        "types": "./src/next.d.ts",
+        "import": "./src/edge.js"
+      },
+      "default": {
+        "types": "./src/index.d.ts",
+        "import": "./src/index.js",
+        "require": "./src/index.js"
+      }
+    },
+    "./next": {
+      "types": "./src/next.d.ts",
+      "import": "./src/next.js",
+      "require": "./src/next.js"
+    },
+    "./engine": {
+      "import": "./src/engine.js"
+    },
+    "./package.json": "./package.json",
+    "./edge": {
+      "types": "./src/next.d.ts",
+      "import": "./src/edge.js"
+    }
+  },
+  "bin": {
+    "bro": "./bin/bro.js"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "dependencies": {
+    "@scalar/express-api-reference": "^0.10.18",
+    "@socket.io/redis-adapter": "^8.3.0",
+    "chokidar": "^5.0.0",
+    "cors": "^2.8.6",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.1",
+    "express-rate-limit": "^8.7.0",
+    "helmet": "^8.3.0",
+    "jsonwebtoken": "^9.0.2",
+    "multer": "^2.3.0",
+    "node-cron": "^4.6.0",
+    "redis": "^6.2.1",
+    "socket.io": "^4.8.3",
+    "tsx": "^4.23.13",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.25.2"
+  },
+  "keywords": [
+    "bro",
+    "brojs",
+    "bro.js",
+    "bro-framework",
+    "framework",
+    "backend",
+    "api",
+    "server",
+    "node",
+    "nodejs",
+    "express",
+    "rest",
+    "zero-config",
+    "zero-boilerplate",
+    "file-based-routing",
+    "auto-routing",
+    "zod",
+    "validation",
+    "jwt",
+    "authentication",
+    "auth",
+    "websocket",
+    "websockets",
+    "socket.io",
+    "realtime",
+    "openapi",
+    "swagger",
+    "scalar",
+    "docs",
+    "auto-docs",
+    "sdk",
+    "sdk-generator",
+    "rpc",
+    "trpc-alternative",
+    "express-alternative",
+    "cron",
+    "scheduler",
+    "background-tasks",
+    "file-upload",
+    "rate-limit",
+    "esm",
+    "ai-friendly",
+    "developer-experience",
+    "dx"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "ioredis-mock": "^8.13.1",
+    "next": "^16.3.5",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "next": ">=13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  }
+}

package/src/dashboard.js

@@ -0,0 +1,80 @@
+import http from 'http';
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * Local Developer Dashboard Server
+ * Serves a dashboard UI that visualizes routes, telemetry, and configuration.
+ */
+export function startDashboard(globalConfig, routes) {
+  const host = '127.0.0.1'; // Strict local binding
+  const port = (globalConfig.port || 5000) + 1;
+
+  const server = http.createServer((req, res) => {
+    // Restrict access to localhost strictly
+    if (req.socket.remoteAddress !== '127.0.0.1' && req.socket.remoteAddress !== '::1') {
+      res.writeHead(403);
+      res.end('Forbidden: Dashboard only available on localhost');
+      return;
+    }
+
+    if (req.url === '/') {
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(`
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <title>bro.js Dev Dashboard</title>
+          <style>
+            body { font-family: system-ui, sans-serif; background: #0f172a; color: #f8fafc; padding: 2rem; }
+            h1 { color: #38bdf8; }
+            .card { background: #1e293b; padding: 1.5rem; border-radius: 8px; margin-bottom: 1rem; }
+            pre { background: #0f172a; padding: 1rem; border-radius: 4px; overflow-x: auto; }
+          </style>
+        </head>
+        <body>
+          <h1>bro.js Dev Dashboard</h1>
+          
+          <div class="card">
+            <h2>Configuration (Redacted)</h2>
+            <pre id="config"></pre>
+          </div>
+          
+          <div class="card">
+            <h2>Active Routes</h2>
+            <pre id="routes"></pre>
+          </div>
+          
+          <script>
+            fetch('/api/state').then(r => r.json()).then(data => {
+              document.getElementById('config').textContent = JSON.stringify(data.config, null, 2);
+              document.getElementById('routes').textContent = JSON.stringify(data.routes, null, 2);
+            });
+          </script>
+        </body>
+        </html>
+      `);
+    } else if (req.url === '/api/state') {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      
+      // Strict Redaction of Secrets
+      const redactedConfig = JSON.parse(JSON.stringify(globalConfig));
+      if (redactedConfig.auth?.jwtSecret) redactedConfig.auth.jwtSecret = '***REDACTED***';
+      if (redactedConfig.db) redactedConfig.db = '[Database Instance]';
+      
+      res.end(JSON.stringify({
+        config: redactedConfig,
+        routes: routes.map(r => ({ method: r.method, path: r.routePath, auth: r.auth }))
+      }));
+    } else {
+      res.writeHead(404);
+      res.end('Not found');
+    }
+  });
+
+  server.listen(port, host, () => {
+    console.log(`[bro.js] 🛠️  Dev Dashboard running locally at http://${host}:${port}`);
+  });
+
+  return server;
+}

package/src/database.js

@@ -0,0 +1,105 @@
+/**
+ * Base Database Adapter Contract for bro.js
+ * Standardizes lifecycle, health checks, and transactions across different DB providers.
+ */
+export class BaseDatabaseAdapter {
+  constructor(config = {}) {
+    this.config = config;
+    this.pool = null;
+    this.isConnected = false;
+  }
+
+  /**
+   * Initializes the connection pool.
+   * Expected to set this.pool and this.isConnected = true
+   */
+  async connect() {
+    throw new Error('connect() must be implemented by the database adapter');
+  }
+
+  /**
+   * Checks if the database is ready for queries.
+   * @returns {Promise<boolean>}
+   */
+  async isReady() {
+    return this.isConnected;
+  }
+
+  /**
+   * Gracefully shuts down the connection pool with a deadline.
+   * @param {number} deadlineMs Timeout in milliseconds
+   */
+  async shutdown(deadlineMs = 5000) {
+    if (!this.isConnected) return;
+    
+    return Promise.race([
+      this._performShutdown(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('Database shutdown timeout exceeded')), deadlineMs))
+    ]);
+  }
+
+  async _performShutdown() {
+    throw new Error('_performShutdown() must be implemented by the database adapter');
+  }
+
+  /**
+   * Executes a callback within a managed transaction.
+   * @param {Function} callback (trx) => Promise<any>
+   */
+  async healthCheck() {
+    return await this.isReady();
+  }
+
+  async transaction(callback) {
+    throw new Error('transaction() must be implemented by the database adapter');
+  }
+}
+
+/**
+ * Example Adapter for PostgreSQL (pg)
+ */
+export class PostgresAdapter extends BaseDatabaseAdapter {
+  async connect() {
+    let pg;
+    try {
+      pg = await import('pg');
+    } catch (e) {
+      throw new Error('Please install pg to use PostgresAdapter');
+    }
+    this.pool = new (pg.default?.Pool || pg.Pool)(this.config);
+    await this.pool.query('SELECT 1');
+    this.isConnected = true;
+    return this.pool;
+  }
+  
+  async _performShutdown() {
+    if (this.pool) await this.pool.end();
+    this.isConnected = false;
+  }
+
+  async isReady() {
+    if (!this.isConnected || !this.pool) return false;
+    try {
+      await this.pool.query('SELECT 1');
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async transaction(callback) {
+    if (!this.isConnected || !this.pool) throw new Error('DB not connected');
+    const client = await this.pool.connect();
+    try {
+      await client.query('BEGIN');
+      const result = await callback(client);
+      await client.query('COMMIT');
+      return result;
+    } catch (e) {
+      await client.query('ROLLBACK');
+      throw e;
+    } finally {
+      client.release();
+    }
+  }
+}

package/src/edge.js

@@ -0,0 +1,244 @@
+import { z } from 'zod';
+import { verifyJwt, signJwt } from './auth.js';
+import { executeRequest, RouteRegistry, resolveIdentity } from './engine.js';
+
+export async function hashIdentity(identity) {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(String(identity));
+  const hash = await crypto.subtle.digest('SHA-256', data);
+  return Array.from(new Uint8Array(hash)).map(b => b.toString(16).padStart(2, '0')).join('');
+}
+export function generateRateLimitKey(req, config, prefix = 'route') { const identity = resolveIdentity(req, config); return `bro:rate_limit:${prefix}:${originalUrl}:${hashIdentity(identity)}`; }
+export function generateCacheKey(req, config, locale) { const identity = resolveIdentity(req, config); return `bro:cache:${method}:${originalUrl}:${locale}:${hashIdentity(identity)}`; }
+
+export { z };
+
+export function createBro(globalConfig = {}) {
+  const globalLogger = { info: console.log, debug: console.debug, warn: console.warn, error: console.error };
+
+  let isInitialized = false;
+  let initPromise = null;
+
+  let globalDb = null;
+  let globalLocale = null;
+  const routeRegistry = new RouteRegistry();
+  
+  const __broRedis = null;
+  const __broMemoryCache = new Map();
+  const __broMemoryRateLimit = new Map();
+
+  async function ensureInitialized() {
+    if (isInitialized) return;
+    if (initPromise) return initPromise;
+
+    initPromise = (async () => {
+      try {
+        if ((typeof process !== 'undefined' ? process.env : {}).NODE_ENV === 'production' && ['dev_secret_please_change', 'bro_default_secret_key', 'your_jwt_secret_here'].includes(globalConfig.auth?.jwtSecret)) {
+          throw new Error('CRITICAL SECURITY ERROR: You are running in production with a default JWT secret!');
+        }
+
+        if (globalConfig.env) {
+          try {
+            globalConfig.env.parse((typeof process !== 'undefined' ? process.env : {}));
+          } catch (err) {
+            console.error('[bro.js/next] Environment Validation Error:', err);
+            throw err;
+          }
+        }
+
+        if (typeof globalConfig.db === 'function') {
+          globalDb = await globalConfig.db();
+        } else if (globalConfig.db && typeof globalConfig.db.init === 'function') {
+          globalDb = await globalConfig.db.init();
+        } else if (globalConfig.db) {
+          globalDb = globalConfig.db;
+          if (globalDb instanceof Promise) globalDb = await globalDb;
+        }
+
+        // Redis is not supported natively in edge.js. Provide via globalConfig.redis client.
+
+        isInitialized = true;
+      } catch (err) {
+        console.error('[bro.js/next] Initialization Error:', err);
+        throw err;
+      }
+    })();
+
+    return initPromise;
+  }
+
+  const resolveLocale = (headers) => {
+    const acceptLanguage = headers['accept-language'] || '';
+    const preferredLanguages = acceptLanguage
+      .split(',')
+      .map(lang => lang.split(';')[0].trim().toLowerCase())
+      .filter(lang => lang);
+    
+    const configuredLocales = Object.keys(globalConfig.locales || {});
+    
+    for (const lang of preferredLanguages) {
+      if (configuredLocales.includes(lang)) {
+        return lang;
+      }
+      const baseLang = lang.split('-')[0];
+      if (configuredLocales.includes(baseLang)) {
+        return baseLang;
+      }
+    }
+    
+    return globalConfig.defaultLocale || 'en';
+  };
+
+  const translate = (locale, key, values = {}) => {
+    let messages = globalConfig.locales?.[locale] || globalConfig.locales?.[globalConfig.defaultLocale || 'en'];
+    if (!messages) return key;
+
+    if (messages.default && typeof messages.default === 'object') {
+      messages = messages.default;
+    }
+
+    const message = key.split('.').reduce((acc, part) => acc && acc[part], messages);
+    if (!message || typeof message !== 'string') return key;
+
+    return message.replace(/\{(\w+)\}/g, (_, name) => {
+      return values[name] !== undefined ? String(values[name]) : `{${name}}`;
+    });
+  };
+
+  const errorHelper = (status, message) => {
+    const err = new Error(message);
+    err.status = status;
+    throw err;
+  };
+
+  function defineRoute(config) {
+    // Register route for OpenAPI in Next environments
+    routeRegistry.register(config);
+
+    return async function (req, context) {
+      try {
+        await ensureInitialized();
+
+        const resolvedLocale = resolveLocale(Object.fromEntries(req.headers.entries()));
+        const url = new URL(req.url);
+        
+        let rawBody = {};
+        const parsedFiles = {};
+        let totalFiles = 0;
+        
+        if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
+          const contentType = req.headers.get('content-type') || '';
+          
+          if (contentType.includes('multipart/form-data')) {
+             try {
+                const formData = await req.formData();
+                for (const [key, value] of formData.entries()) {
+                   if (value instanceof File || value instanceof Blob) {
+                      if (!parsedFiles[key]) parsedFiles[key] = [];
+                      parsedFiles[key].push(value);
+                      totalFiles++;
+                   } else {
+                      rawBody[key] = value;
+                   }
+                }
+             } catch (err) {}
+          } else {
+            try {
+              rawBody = await req.json();
+            } catch (err) {}
+          }
+        }
+
+        let ctxFile = undefined;
+        let ctxFiles = undefined;
+        if (totalFiles === 1) {
+          const keys = Object.keys(parsedFiles);
+          ctxFile = parsedFiles[keys[0]][0];
+          ctxFiles = parsedFiles;
+        } else if (totalFiles > 1) {
+          ctxFiles = parsedFiles;
+        }
+
+        const requestData = {
+          method: req.method,
+          originalUrl: url.pathname + url.search,
+          headers: Object.fromEntries(req.headers.entries()),
+          body: rawBody,
+          query: Object.fromEntries(url.searchParams.entries()),
+          params: context?.params ? await context.params : {},
+          files: ctxFiles || ctxFile,
+          ip: req.headers.get('x-forwarded-for') || 'ip',
+          locale: resolvedLocale
+        };
+
+        let redisFallback = __broRedis;
+        if (!redisFallback) {
+          redisFallback = {
+            async get(key) {
+               const cached = __broMemoryCache.get(key);
+               if (cached && Date.now() < cached.expires) return JSON.stringify(cached.data);
+               return null;
+            },
+            async setEx(key, ex, val) {
+               __broMemoryCache.set(key, { data: JSON.parse(val), expires: Date.now() + (ex * 1000) });
+            },
+            async del(key) { __broMemoryCache.delete(key); },
+            async incr(key) {
+               const now = Date.now();
+               let record = __broMemoryRateLimit.get(key);
+               if (!record || now > record.expires) record = { count: 0, expires: now + 60000 };
+               record.count++;
+               __broMemoryRateLimit.set(key, record);
+               return record.count;
+            },
+            async expire(key, ex) {
+               let record = __broMemoryRateLimit.get(key);
+               if (record) {
+                 record.expires = Date.now() + (ex * 1000);
+                 __broMemoryRateLimit.set(key, record);
+               }
+            }
+          };
+        }
+
+        const ctxExtras = {
+          verifyJwt,
+          generateRateLimitKey,
+          generateCacheKey,
+          generateId: () => crypto.randomUUID(),
+          req, // Native NextRequest
+          db: globalDb,
+          redis: redisFallback,
+          io: { emit: () => console.warn('[bro.js/next] WebSockets require standard bro.js server.') },
+          t: (key, values) => translate(resolvedLocale, key, values),
+          logger: globalLogger,
+          jwt: { sign: (payload, opts) => signJwt(payload, globalConfig?.auth?.jwtSecret || (typeof process !== 'undefined' ? process.env : {}).JWT_SECRET, Object.assign({ expiresIn: globalConfig?.auth?.expiresIn || '1d' }, opts || {})) },
+          error: errorHelper
+        };
+
+        const response = await executeRequest(config, requestData, globalConfig, ctxExtras);
+
+        return Response.json(response.body, { 
+           status: response.status, 
+           headers: response.headers 
+        });
+
+      } catch (error) {
+        console.error('[bro.js/next] Unhandled Error:', error);
+        return Response.json(
+          { 
+            type: 'https://brojs.dev/errors/internal_server_error',
+            title: 'Internal Server Error',
+            status: 500,
+            instance: req.url,
+            requestId: req.headers.get('x-request-id') || 'unknown',
+            detail: error.message || 'An unexpected error occurred'
+          },
+          { status: 500, headers: { 'Content-Type': 'application/problem+json' } }
+        );
+      }
+    };
+  }
+
+  return { defineRoute, z };
+}