bro-framework 2.4.2 → 2.4.4

package/README.md

@@ -35,6 +35,7 @@
 - [Architecture & Request Lifecycle](#architecture--request-lifecycle)
 - [Tech Stack Breakdown](#tech-stack-breakdown)
 - [CLI Reference](#cli-reference)
+- [Next.js App Router Integration](#nextjs-app-router-integration)
 - [Author & License](#author--license)
 
 ---
@@ -309,9 +310,36 @@ For Redis-backed integration tests without an external Redis server, install `io
 | `bro init` | Automated workspace scaffolder. Generates configuration files and forcefully ensures your `package.json` respects `"type": "module"`. |
 | `bro sdk` | Route parser and browser client compiler. Generates your typed `bro-sdk.js` frontend SDK in one hit. |
 
+## Next.js App Router Integration
+
+You can natively use `bro.js` syntax, Zod validation, and Authentication inside your Next.js API routes (`app/api/.../route.ts`)!
+
+First, create your factory instance (e.g., `lib/bro.ts`):
+```typescript
+import { createBro } from 'bro-framework/next';
+
+export const { defineRoute, z } = createBro({
+  auth: { apiKey: process.env.API_KEY }
+});
+```
+
+Then use it seamlessly in your route files:
+```typescript
+import { defineRoute, z } from '@/lib/bro';
+
+export const POST = defineRoute({
+  body: z.object({ name: z.string() }),
+  handler: async ({ body }) => {
+    return { success: true, hello: body.name };
+  }
+});
+```
+
+> **Capabilities & Limitations**: Because Next.js API routes are "Serverless" (meaning they sleep when not actively processing a request), features that require a constantly running server such as **WebSockets**, **Background Tasks (Cron)**, **Rate Limiting**, and **Auto-generated Docs** are strictly limited to the standalone `bro.js` framework and are not available in the Next.js adapter.
+
 ---
 
 ## Author & License
 
-- **Author**: Yessin (@medyass1ne)
+- **Author**: Yass1n (@medyass1ne)
 - **License**: MIT

package/bin/bro.js

@@ -207,7 +207,8 @@ async function bootstrap() {
   }
 
   const localeDir = globalConfig.locale?.directory || path.join(cwd, 'locale');
-  const { app, server, routes: initialRoutes, reload, reloadLocale, io, shutdown } = await createServer(globalConfig, routesDir, db);
+  const tasksDir = path.join(cwd, 'tasks');
+  const { app, server, routes: initialRoutes, reload, reloadLocale, reloadTasks, io, shutdown } = await createServer(globalConfig, routesDir, db);
   const port = globalConfig.port;
   
   let currentRoutes = initialRoutes;
@@ -234,28 +235,35 @@ async function bootstrap() {
       
       printCurrentRoutes(currentRoutes);
 
-      const localeGlob = localeDir.replace(/\\/g, '/') + '/*.{js,mjs,ts}';
-      const watcher = chokidar.watch([routesDir, localeGlob], { ignoreInitial: true });
+      const localeGlob = localeDir.replace(/\\/g, '/') + '/*.{js,mjs,ts,json}';
+      const watcher = chokidar.watch([routesDir, localeGlob, tasksDir], { ignoreInitial: true });
       
       watcher.on('all', async (event, filepath) => {
-        const isJavaScriptFile = filepath.endsWith('.js') || filepath.endsWith('.ts') || filepath.endsWith('.mjs');
-        if (!isJavaScriptFile) return;
+        const isValidFile = filepath.match(/\.(js|ts|mjs|json)$/);
+        if (!isValidFile) return;
         const relLocale = path.relative(path.resolve(localeDir), filepath);
         const isLocaleFile = !relLocale.startsWith('..') && !path.isAbsolute(relLocale);
+        
+        const relTask = path.relative(path.resolve(tasksDir), filepath);
+        const isTaskFile = !relTask.startsWith('..') && !path.isAbsolute(relTask);
 
         try {
           const reloadStartTime = performance.now();
           if (isLocaleFile) {
             await reloadLocale();
+          } else if (isTaskFile) {
+            await reloadTasks();
           } else {
             currentRoutes = await reload();
           }
           const reloadTimeMs = performance.now() - reloadStartTime;
           
-          printHotReload(path.basename(filepath), event, reloadTimeMs, isLocaleFile ? 'Locale' : 'Route');
+          const fileType = isTaskFile ? 'Task' : (isLocaleFile ? 'Locale' : 'Route');
+          printHotReload(path.basename(filepath), event, reloadTimeMs, fileType);
           printCurrentRoutes(currentRoutes);
         } catch (err) {
-          console.error(`\n  ✗ Error hot-reloading ${isLocaleFile ? 'locale' : 'routes'}:`, err);
+          const fileType = isTaskFile ? 'tasks' : (isLocaleFile ? 'locale' : 'routes');
+          console.error(`\n  ✗ Error hot-reloading ${fileType}:`, err);
         }
       });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bro-framework",
-  "version": "2.4.2",
+  "version": "2.4.4",
   "description": "The No-BS Backend Framework for Node.js",
   "repository": {
     "type": "git",
@@ -15,7 +15,15 @@
   "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": {

package/src/locale.js

@@ -3,7 +3,7 @@ import path from 'path';
 import { pathToFileURL } from 'url';
 import crypto from 'node:crypto';
 
-const LOCALE_EXTENSIONS = new Set(['.js', '.mjs', '.ts']);
+const LOCALE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.json']);
 
 function localeFromFilename(fileName) {
 	return path.basename(fileName, path.extname(fileName));

package/src/next.d.ts

@@ -0,0 +1,70 @@
+import { z, ZodTypeAny } from 'zod';
+
+export { z };
+
+export interface UploadedFile {
+  name: string;
+  type: string;
+  size: number;
+  arrayBuffer: () => Promise<ArrayBuffer>;
+  stream: () => ReadableStream;
+  text: () => Promise<string>;
+}
+
+export interface NextBroGlobalConfig<TDb = any> {
+  env?: ZodTypeAny;
+  locales?: Record<string, any>;
+  defaultLocale?: string;
+  redisUrl?: string;
+  rateLimit?: { windowMs: number; max: number; };
+  auth?: {
+    jwtSecret?: string;
+    apiKey?: string | string[];
+    expiresIn?: string | number;
+  };
+  db?: TDb | Promise<TDb> | (() => TDb | Promise<TDb>) | { init: () => TDb | Promise<TDb> };
+}
+
+export interface NextRouteContext<TBody = any, TQuery = any, TParams = any, TDb = any> {
+  req: Request;
+  env: Record<string, string | undefined>;
+  db: TDb;
+  redis: any;
+  io: { emit: (event: string, data: any) => void };
+  body: TBody extends ZodTypeAny ? z.infer<TBody> : any;
+  query: TQuery extends ZodTypeAny ? z.infer<TQuery> : any;
+  params: TParams extends ZodTypeAny ? z.infer<TParams> : any;
+  file?: UploadedFile;
+  files?: Record<string, UploadedFile[]>;
+  locale: string;
+  t: (key: string, values?: any) => string;
+  user?: any;
+  jwt: { sign: (payload: any, opts?: any) => string };
+  error: (status: number, message: string) => never;
+}
+
+export interface NextRouteConfig<TBody = any, TQuery = any, TParams = any, TDb = any> {
+  auth?: boolean | string[] | 'api-key' | string;
+  body?: TBody;
+  query?: TQuery;
+  params?: TParams;
+  cache?: number;
+  rateLimit?: { windowMs: number; max: number; } | false;
+  response?: ZodTypeAny;
+  summary?: string;
+  upload?: any;
+  handler: (ctx: NextRouteContext<TBody, TQuery, TParams, TDb>) => Promise<any> | any;
+}
+
+export interface BroNextInstance<TDb = any> {
+  z: typeof z;
+  defineRoute: <
+    TBody extends ZodTypeAny = any,
+    TQuery extends ZodTypeAny = any,
+    TParams extends ZodTypeAny = any
+  >(
+    config: NextRouteConfig<TBody, TQuery, TParams, TDb>
+  ) => (req: Request | any, context: any) => Promise<any>;
+}
+
+export declare function createBro<TDb = any>(config?: NextBroGlobalConfig<TDb>): BroNextInstance<TDb>;

package/src/next.js

@@ -0,0 +1,291 @@
+import { NextResponse } from 'next/server';
+import { z } from 'zod';
+import { verifyJwt, signJwt } from './auth.js';
+import { createClient } from 'redis';
+
+export { z };
+
+export function createBro(globalConfig = {}) {
+  let isInitialized = false;
+  let initPromise = null;
+
+  let globalDb = null;
+  let globalRedis = null;
+  let globalLocale = null;
+
+  async function ensureInitialized() {
+    if (isInitialized) return;
+    if (initPromise) return initPromise;
+
+    initPromise = (async () => {
+      try {
+        if (globalConfig.env) {
+          try {
+            globalConfig.env.parse(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;
+        }
+
+        if (globalConfig.redisUrl) {
+          globalRedis = createClient({ url: globalConfig.redisUrl });
+          globalRedis.on('error', (err) => console.error('[bro.js/next] Redis Error:', err));
+          if (globalRedis.status === 'wait' || !globalRedis.status) {
+             await globalRedis.connect().catch(err => {
+                if (!err.message.includes('already connecting') && !err.message.includes('already connected')) {
+                  throw err;
+                }
+             });
+          }
+        }
+
+        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;
+
+    // Handle Webpack / ES module JSON interop where the object is under .default
+    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) {
+    return async function (req, context) {
+      try {
+        await ensureInitialized();
+
+        const resolvedLocale = resolveLocale(Object.fromEntries(req.headers.entries()));
+
+        // Auth extraction early for Identity caching
+        let user = null;
+        let apiKeyUsed = null;
+        if (config.auth) {
+          if (config.auth === 'api-key') {
+            const apiKey = req.headers.get('x-api-key') || req.headers.get('authorization')?.replace('Bearer ', '');
+            const configuredKey = globalConfig?.auth?.apiKey || process.env.API_KEY;
+            
+            let isValid = false;
+            if (configuredKey) {
+              const keys = (Array.isArray(configuredKey) ? configuredKey : configuredKey.split(',')).map(k => String(k).trim());
+              isValid = keys.includes(apiKey);
+            }
+            
+            if (!isValid) {
+              return NextResponse.json({ error: 'Unauthorized', details: 'Missing or invalid API key' }, { status: 401 });
+            }
+            apiKeyUsed = apiKey;
+          } else {
+            const authHeader = req.headers.get('authorization');
+            if (!authHeader || !authHeader.startsWith('Bearer ')) {
+              return NextResponse.json({ error: 'Unauthorized', details: 'Missing Bearer token' }, { status: 401 });
+            }
+            
+            const token = authHeader.split(' ')[1];
+            const secret = globalConfig?.auth?.jwtSecret || process.env.JWT_SECRET;
+            
+            if (!secret) {
+               return NextResponse.json({ error: 'Internal Server Error', details: 'JWT_SECRET is not configured' }, { status: 500 });
+            }
+            
+            const decoded = verifyJwt(token, secret);
+            if (!decoded.valid) {
+              return NextResponse.json({ error: 'Unauthorized', details: decoded.error }, { status: 401 });
+            }
+            
+            user = decoded.payload;
+            
+            if (Array.isArray(config.auth) && config.auth.length > 0) {
+              if (!user.role || !config.auth.includes(user.role)) {
+                return NextResponse.json({ error: 'Forbidden', details: 'Insufficient permissions' }, { status: 403 });
+              }
+            }
+          }
+        }
+
+        // Rate Limiting
+        const activeRateLimit = config.rateLimit === false ? null : (config.rateLimit || globalConfig.rateLimit);
+        if (activeRateLimit && globalRedis) {
+          const ip = req.headers.get('x-forwarded-for') || 'ip';
+          const urlObj = new URL(req.url);
+          const rlKey = `rate-limit:${urlObj.pathname}:${ip}`;
+          const currentCount = await globalRedis.incr(rlKey);
+          if (currentCount === 1) {
+            await globalRedis.expire(rlKey, Math.ceil(activeRateLimit.windowMs / 1000));
+          }
+          if (currentCount > activeRateLimit.max) {
+            return NextResponse.json({ error: 'Too Many Requests' }, { status: 429 });
+          }
+        }
+
+        // Caching
+        let cacheKey = null;
+        if (config.cache && globalRedis && req.method === 'GET') {
+          const urlObj = new URL(req.url);
+          const identity = user ? (user.id || user.role || 'user') : (apiKeyUsed || 'anon');
+          cacheKey = `cache:${urlObj.pathname}${urlObj.search}:${resolvedLocale}:${identity}`;
+          
+          const cachedData = await globalRedis.get(cacheKey);
+          if (cachedData) {
+            return NextResponse.json(JSON.parse(cachedData), { status: 200 });
+          }
+        }
+
+        const rawParams = context?.params ? await context.params : {};
+        const url = new URL(req.url);
+        const rawQuery = Object.fromEntries(url.searchParams.entries());
+        
+        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 body, params, query;
+        try {
+          if (config.body) body = await config.body.parseAsync(rawBody);
+        } catch (err) {
+          if (err instanceof z.ZodError) return NextResponse.json({ error: 'Invalid Request Body', details: err.issues }, { status: 400 });
+          throw err;
+        }
+        try {
+          if (config.params) params = await config.params.parseAsync(rawParams);
+        } catch (err) {
+          if (err instanceof z.ZodError) return NextResponse.json({ error: 'Invalid URL Parameters', details: err.issues }, { status: 400 });
+          throw err;
+        }
+        try {
+          if (config.query) query = await config.query.parseAsync(rawQuery);
+        } catch (err) {
+          if (err instanceof z.ZodError) return NextResponse.json({ error: 'Invalid Query Parameters', details: err.issues }, { status: 400 });
+          throw 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 ctx = {
+          req,
+          env: process.env,
+          db: globalDb,
+          redis: globalRedis,
+          io: { emit: () => console.warn('[bro.js/next] WebSockets require standard bro.js server.') },
+          body,
+          params,
+          query,
+          file: ctxFile,
+          files: ctxFiles,
+          locale: resolvedLocale,
+          t: (key, values) => translate(resolvedLocale, key, values),
+          user,
+          jwt: { 
+             sign: (payload, opts) => signJwt(payload, globalConfig?.auth?.jwtSecret || process.env.JWT_SECRET, Object.assign({ expiresIn: globalConfig?.auth?.expiresIn || '1d' }, opts || {})) 
+          },
+          error: errorHelper
+        };
+
+        const result = await config.handler(ctx);
+
+        if (cacheKey && globalRedis) {
+           await globalRedis.set(cacheKey, JSON.stringify(result), { EX: config.cache });
+        }
+
+        return NextResponse.json(result, { status: 200 });
+
+      } catch (error) {
+        if (error.status) {
+           return NextResponse.json({ error: error.message }, { status: error.status });
+        }
+        console.error('[bro.js/next] Unhandled Error:', error);
+        return NextResponse.json(
+          { error: 'Internal Server Error', message: error.message },
+          { status: 500 }
+        );
+      }
+    };
+  }
+
+  return { defineRoute, z };
+}

package/src/router.js

@@ -157,7 +157,6 @@ export async function loadRoutes(app, routesDir, createHandler, openApiSpec) {
         }
       }
       
-      // Auto-inject security definition if auth is true
       if (config.auth === 'api-key') {
         operation.security = [{ apiKeyAuth: [] }];
       } else if (config.auth) {

package/src/server.js

@@ -407,7 +407,12 @@ export async function createServer(globalConfig, routesDir, db) {
 
   const initialRoutes = await reload();
 
-  const taskManager = await scanTasks({ db, io });
+  let taskManager = await scanTasks({ db, io });
+
+  const reloadTasks = async () => {
+    if (taskManager) taskManager.stopAll();
+    taskManager = await scanTasks({ db, io });
+  };
 
   let isShuttingDown = false;
   const shutdown = async () => {
@@ -434,5 +439,5 @@ export async function createServer(globalConfig, routesDir, db) {
     });
   };
 
-  return { app, server, routes: initialRoutes, reload, reloadLocale, io, shutdown };
+  return { app, server, routes: initialRoutes, reload, reloadLocale, reloadTasks, io, shutdown };
 }