bro-framework 2.2.2 → 2.3.1

package/README.md

@@ -20,7 +20,7 @@
 
 ---
 
-> "NestJS wants four decorators, three modules, and an existential crisis just to handle a GET request. Express makes you write the same 40 lines of CORS, JSON parsing, and auth middleware for every project. bro.js gives you file routing, auto-validation, JWT auth, WebSockets, and live docs out of the box. Be honest: you just want to return an object."
+> Skip the boilerplate. bro.js gives you file-based routing, automatic Zod validation, JWT auth, and WebSockets right out of the box. Just write your business logic, return an object, and let the framework handle the rest.
 
 ---
 
@@ -97,7 +97,7 @@ export default defineRoute({
 Create a `.js` file in the `routes/` directory, and it automatically becomes an endpoint. We use Next.js-style bracket syntax for dynamic parameters. A file named `routes/users/[id].get.js` translates natively to a `GET /users/:id` Express route under the hood.
 
 ### Bouncer-Grade Validation
-Powered by Zod. Attach a schema to `body`, `query`, or `params` in your route definition. If the client sends malformed data, `bro.js` automatically rejects the request with a structured `400 Bad Request` JSON payload *before* your handler ever executes. You never have to manually validate inputs again.
+Powered by Zod. Attach a schema to `body`, `query`, or `params` directly in your route definition. If the client sends malformed data, `bro.js` automatically rejects the request with a structured `400 Bad Request` JSON payload *before* your handler ever executes. You never have to manually validate inputs again. You can also define a `response` schema to strongly type your OpenAPI documentation (strictly opt-in; arbitrary 200s work out of the box).
 
 ### Zero-Config JWTs
 Add `auth: true` to your route config. `bro.js` will intercept the request, extract the `Authorization: Bearer <token>` header, verify the signature using your `jwtSecret`, and inject the decoded payload directly into `ctx.user`.
@@ -115,7 +115,22 @@ Tired of writing frontend `fetch` wrappers? Run `bro sdk`. The CLI will parse yo
 Don't spin up a separate worker server. Drop a JavaScript file anywhere in the `tasks/` folder, export a cron string (e.g., `"0 0 * * *"`), and an async handler. `bro.js` natively schedules it as a background worker with full access to your injected database and WebSocket contexts.
 
 ### Zero-Boilerplate File Uploads
-Add `upload: true` to a route. `bro.js` automatically hooks into `multer`, parses the `multipart/form-data` payload in memory, and injects the files directly into `ctx.files`.
+Add `upload: true` to a route. `bro.js` automatically hooks into `multer`, parses the `multipart/form-data` payload in memory, and injects the files directly into `ctx.files`. It also natively supports granular file limits, restricting max sizes, parts, and fielding counts instantly to protect your RAM. (Note: Use the `storage` configuration for heavy production disk writing to prevent memory exhaustion).
+
+### File-Based Locale
+Create a `locale/` folder with one translation file per locale, such as `locale/en.js` and `locale/fr.js`. Export a plain object from each file, then use `t()` in any route:
+
+```javascript
+// locale/fr.js
+export default { welcome: 'Bienvenue, {name} !' };
+
+// routes/welcome.get.js
+export default defineRoute({
+  handler: async ({ t }) => ({ message: t('welcome', { name: 'Sam' }) })
+});
+```
+
+The locale is negotiated dynamically using RFC 9110 `Accept-Language` headers, supporting full region fallback and custom defaults, and the generated SDK can securely set it via `setLocale('fr')`.
 
 ---
 
@@ -178,9 +193,9 @@ Add `upload: true` to a route. `bro.js` automatically hooks into `multer`, parse
 | Command | Description |
 | :--- | :--- |
 | `bro dev` | Development server featuring instant boot, visual CLI banner, and `chokidar`-powered hot module remapping. |
-| `bro start` &nbsp; | Production runner locked down for security. Zero watcher overhead, suppressed internal logs, and isolated API docs. |
+| `bro start` &nbsp; | Production runner locked down for security. Features Graceful Shutdown APIs (with `onShutdown` DB teardown), suppressed internal logs, and isolated API docs. |
 | `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 frontend SDK in one hit. |
+| `bro sdk` | Route parser and browser client compiler. Generates your typed `bro-sdk.js` frontend SDK in one hit. |
 
 ---
 

package/bin/bro.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import path from 'path';
 import fs from 'fs';
@@ -37,6 +37,12 @@ export default defineConfig({
     jwtSecret: 'dev_secret_please_change',
     expiresIn: '7d'
   },
+
+  // Optional file-based API translations
+  // Add locale/en.js, locale/fr.js, etc.
+  locale: {
+    defaultLocale: 'en'
+  },
   
   // API Documentation (Scalar UI)
   docs: process.env.NODE_ENV !== 'production', // Set to false to disable completely, or true to force in prod
@@ -190,7 +196,8 @@ async function bootstrap() {
     process.exit(1);
   }
 
-  const { app, server, routes: initialRoutes, reload, io, shutdown } = await createServer(globalConfig, routesDir, db);
+  const localeDir = globalConfig.locale?.directory || path.join(cwd, 'locale');
+  const { app, server, routes: initialRoutes, reload, reloadLocale, io, shutdown } = await createServer(globalConfig, routesDir, db);
   const port = globalConfig.port;
   
   let currentRoutes = initialRoutes;
@@ -217,20 +224,28 @@ async function bootstrap() {
       
       printCurrentRoutes(currentRoutes);
 
-      const watcher = chokidar.watch(routesDir, { ignoreInitial: true });
+      const localeGlob = localeDir.replace(/\\/g, '/') + '/*.{js,mjs,ts}';
+      const watcher = chokidar.watch([routesDir, localeGlob], { ignoreInitial: true });
       
       watcher.on('all', async (event, filepath) => {
-        if (!filepath.endsWith('.js') && !filepath.endsWith('.ts')) return;
-        
+        const isJavaScriptFile = filepath.endsWith('.js') || filepath.endsWith('.ts') || filepath.endsWith('.mjs');
+        if (!isJavaScriptFile) return;
+        const relLocale = path.relative(path.resolve(localeDir), filepath);
+        const isLocaleFile = !relLocale.startsWith('..') && !path.isAbsolute(relLocale);
+
         try {
           const reloadStartTime = performance.now();
-          currentRoutes = await reload();
+          if (isLocaleFile) {
+            await reloadLocale();
+          } else {
+            currentRoutes = await reload();
+          }
           const reloadTimeMs = performance.now() - reloadStartTime;
           
-          printHotReload(path.basename(filepath), event, reloadTimeMs);
+          printHotReload(path.basename(filepath), event, reloadTimeMs, isLocaleFile ? 'Locale' : 'Route');
           printCurrentRoutes(currentRoutes);
         } catch (err) {
-          console.error(`\n  ✗ Error hot-reloading routes:`, err);
+          console.error(`\n  ✗ Error hot-reloading ${isLocaleFile ? 'locale' : 'routes'}:`, err);
         }
       });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bro-framework",
-  "version": "2.2.2",
+  "version": "2.3.1",
   "description": "The No-BS Backend Framework for Node.js",
   "repository": {
     "type": "git",

package/src/index.d.ts

@@ -12,16 +12,18 @@ export interface BroContext<Body = any, Params = any, Query = any> {
   db?: any;
   io?: any;
   files?: any[];
+  locale: string;
+  t: (key: string, values?: Record<string, unknown>) => string;
   error?: any;
 }
 
 export interface RouteConfig<Body = any, Params = any, Query = any> {
   auth?: boolean;
   upload?: boolean | { limits?: any, fields?: { name: string, maxCount?: number }[], single?: string, array?: string, fileFilter?: any, storage?: any };
-  schema?: { body?: Body; params?: Params; query?: Query; };
   body?: Body;
   params?: Params;
   query?: Query;
+  response?: ZodTypeAny;
   rateLimit?: {
     windowMs: number;
     max: number;
@@ -34,12 +36,23 @@ export function defineRoute<Body = any, Params = any, Query = any>(
   config: RouteConfig<Body, Params, Query>
 ): RouteConfig<Body, Params, Query>;
 
+export function loadLocale(directory: string, options?: { defaultLocale?: string }): Promise<{
+  locales: string[];
+  defaultLocale: string;
+  resolveLocale: (request: any) => string;
+  translate: (locale: string, key: string, values?: Record<string, unknown>) => string;
+}>;
+
 export interface BroConfig {
   env?: ZodTypeAny;
   server?: {
     port?: number;
     cors?: boolean | object;
   };
+  locale?: {
+    directory?: string;
+    defaultLocale?: string;
+  };
   auth?: {
     jwtSecret?: string;
     expiresIn?: string | number;
@@ -59,6 +72,7 @@ export interface BroConfig {
   };
   db?: () => Promise<any> | any;
   sockets?: (io: any, db: any) => Promise<void> | void;
+  onShutdown?: (db: any) => Promise<void> | void;
 }
 
 export function defineConfig(config: BroConfig): BroConfig;

package/src/index.js

@@ -26,3 +26,4 @@ export function defineConfig(config) {
 }
 
 export { z };
+export { loadLocale } from './locale.js';

package/src/locale.js

@@ -0,0 +1,118 @@
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import crypto from 'node:crypto';
+
+const LOCALE_EXTENSIONS = new Set(['.js', '.mjs', '.ts']);
+
+function localeFromFilename(fileName) {
+	return path.basename(fileName, path.extname(fileName));
+}
+
+function normalizeLocale(locale) {
+	const normalized = String(locale || '').trim().replaceAll('_', '-').toLowerCase();
+	const aliases = {
+		english: 'en',
+		arabic: 'ar',
+		french: 'fr',
+		spanish: 'es',
+		german: 'de',
+		portuguese: 'pt',
+		italian: 'it',
+		japanese: 'ja',
+		korean: 'ko',
+		chinese: 'zh'
+	};
+	return aliases[normalized] || normalized;
+}
+
+function findLocale(locales, requestedLocale, fallbackLocale) {
+	const requested = normalizeLocale(requestedLocale);
+	const exact = locales.find(locale => normalizeLocale(locale) === requested);
+	if (exact) return exact;
+
+	const language = requested.split('-')[0];
+	const languageMatch = locales.find(locale => normalizeLocale(locale).split('-')[0] === language);
+	if (languageMatch) return languageMatch;
+
+	return fallbackLocale;
+}
+
+function readMessage(messages, key) {
+	return key.split('.').reduce((value, part) => value?.[part], messages);
+}
+
+function interpolate(message, values) {
+	return message.replace(/\{(\w+)\}/g, (_, name) => {
+		return values[name] === undefined ? `{${name}}` : String(values[name]);
+	});
+}
+
+function parseAcceptLanguage(header) {
+	return String(header || '')
+		.split(',')
+		.map(value => {
+			const [tag, qVal] = value.split(';').map(s => s.trim());
+			let q = 1;
+			if (qVal && qVal.startsWith('q=')) {
+				const parsedQ = parseFloat(qVal.slice(2));
+				if (!isNaN(parsedQ)) q = parsedQ;
+			}
+			return { tag, q };
+		})
+		.filter(item => item.tag && item.q > 0)
+		.sort((a, b) => b.q - a.q)
+		.map(item => item.tag);
+}
+
+/**
+ * Loads translation files from the application's locale directory.
+ * Each file name becomes a locale, for example locale/en-US.js.
+ * @param {string} directory
+ * @param {{ defaultLocale?: string }} [options]
+ */
+export async function loadLocale(directory, options = {}) {
+	const files = fs.existsSync(directory)
+		? fs.readdirSync(directory).filter(file => {
+			const fullPath = path.join(directory, file);
+			return fs.statSync(fullPath).isFile() && LOCALE_EXTENSIONS.has(path.extname(file));
+		})
+		: [];
+
+	const messages = {};
+	for (const file of files) {
+		const module = await import(`${pathToFileURL(path.join(directory, file)).href}?update=${crypto.randomUUID()}`);
+		const catalog = module.default || module.messages || module;
+		if (catalog && typeof catalog === 'object') {
+			messages[localeFromFilename(file)] = catalog;
+		}
+	}
+
+	const locales = Object.keys(messages);
+	const configuredDefault = options.defaultLocale;
+	const defaultLocale = findLocale(locales, configuredDefault, null)
+		|| locales.find(locale => ['en', 'en-us'].includes(normalizeLocale(locale)))
+		|| locales[0]
+		|| 'en';
+
+	function resolveLocale(request) {
+		const requestedLocales = parseAcceptLanguage(request?.headers?.['accept-language']);
+		for (const requested of requestedLocales) {
+			const match = findLocale(locales, requested, null);
+			if (match) return match;
+		}
+		return defaultLocale;
+	}
+
+	function translate(locale, key, values = {}) {
+		const selectedLocale = findLocale(locales, locale, defaultLocale);
+		const message = readMessage(messages[selectedLocale], key)
+			?? readMessage(messages[defaultLocale], key);
+
+		if (message === undefined) return key;
+		if (typeof message !== 'string') return message;
+		return interpolate(message, values);
+	}
+
+	return { locales, defaultLocale, resolveLocale, translate };
+}

package/src/logger.js

@@ -72,8 +72,8 @@ export function printRoute(method, routePath, hasAuth, isLast = false) {
   console.log(`  ${colors.dim}${branch}${colors.reset} ${coloredMethod} ${routePath}${authIcon}`);
 }
 
-export function printHotReload(fileName, event, reloadTimeMs) {
+export function printHotReload(fileName, event, reloadTimeMs, resourceType = 'Route') {
   const time = typeof reloadTimeMs === 'number' ? reloadTimeMs.toFixed(0) : reloadTimeMs;
-  console.log(`\n  ${colors.cyan}Route updated:${colors.reset} ${colors.bold}${fileName}${colors.reset} ${colors.dim}(${event})${colors.reset}`);
+  console.log(`\n  ${colors.cyan}${resourceType} updated:${colors.reset} ${colors.bold}${fileName}${colors.reset} ${colors.dim}(${event})${colors.reset}`);
   console.log(`  ${colors.dim}Remapped in ${time}ms${colors.reset}\n`);
 }

package/src/router.js

@@ -116,10 +116,15 @@ export async function loadRoutes(app, routesDir, createHandler, openApiSpec) {
         summary: config.summary || `${method.toUpperCase()} ${routePath}`,
         responses: { '200': { description: 'Successful response' } }
       };
-      
-      const bodySchema = config.schema?.body || config.body;
-      const paramsSchema = config.schema?.params || config.params;
-      const querySchema = config.schema?.query || config.query;
+
+      if (config.response) {
+        operation.responses['200'].content = {
+          'application/json': { schema: zodToJsonSchema(config.response) }
+        };
+      }
+      const bodySchema = config.body;
+      const paramsSchema = config.params;
+      const querySchema = config.query;
 
       if (bodySchema) {
         operation.requestBody = {

package/src/sdk.js

@@ -21,11 +21,16 @@ export async function generateSDK() {
   const code = `// Auto-generated by bro.js
 const CONFIG = {
   baseURL: 'http://localhost:5000',
-  tokenKey: 'bro_token'
+  tokenKey: 'bro_token',
+  locale: undefined
 };
 
 async function request(method, path, data) {
   const headers = {};
+
+  if (CONFIG.locale) {
+    headers['Accept-Language'] = CONFIG.locale;
+  }
   
   if (typeof localStorage !== 'undefined') {
     const token = localStorage.getItem(CONFIG.tokenKey);
@@ -76,6 +81,10 @@ export function setBaseURL(url) {
 export function setTokenKey(key) {
   CONFIG.tokenKey = key;
 }
+
+export function setLocale(locale) {
+  CONFIG.locale = locale;
+}
 `;
 
   fs.writeFileSync(path.join(process.cwd(), 'bro-sdk.js'), code, 'utf-8');

package/src/server.js

@@ -1,11 +1,13 @@
 import express from 'express';
 import cors from 'cors';
 import http from 'node:http';
+import path from 'node:path';
 import { Server } from 'socket.io';
 import rateLimit from 'express-rate-limit';
 import multer from 'multer';
 import { apiReference } from '@scalar/express-api-reference';
 import { verifyJwt, signJwt } from './auth.js';
+import { loadLocale } from './locale.js';
 import { loadRoutes } from './router.js';
 import { scanTasks } from './tasks.js';
 
@@ -14,7 +16,7 @@ import { scanTasks } from './tasks.js';
  * @param {Object} globalConfig - User's bro.config.js configurations.
  * @param {string} routesDir - Path to the target routes directory.
  * @param {any} db - Initialized database instance.
- * @returns {Promise<{ app: import('express').Application, server: http.Server, routes: Array, reload: Function, io: import('socket.io').Server }>}
+ * @returns {Promise<{ app: import('express').Application, server: http.Server, routes: Array, reload: Function, reloadLocale: Function, io: import('socket.io').Server, shutdown: Function }>}
  */
 export async function createServer(globalConfig, routesDir, db) {
   if (process.env.NODE_ENV === 'production' && ['dev_secret_please_change', 'bro_default_secret_key'].includes(globalConfig.jwtSecret)) {
@@ -23,6 +25,8 @@ export async function createServer(globalConfig, routesDir, db) {
 
   const app = express();
   const server = http.createServer(app);
+  const localeDirectory = globalConfig.locale?.directory || path.join(process.cwd(), 'locale');
+  let locale = await loadLocale(localeDirectory, globalConfig.locale);
   
   const corsConfig = globalConfig.server?.cors !== undefined ? globalConfig.server.cors : true;
   
@@ -41,12 +45,14 @@ export async function createServer(globalConfig, routesDir, db) {
   if (globalConfig.sockets) {
     await globalConfig.sockets(io, db);
   }
-  
   const createHandler = (routeConfig) => {
     const middlewares = [];
-    const bodySchema = routeConfig.schema?.body || routeConfig.body;
-    const paramsSchema = routeConfig.schema?.params || routeConfig.params;
-    const querySchema = routeConfig.schema?.query || routeConfig.query;
+    if (routeConfig.schema) {
+      throw new Error("Nested 'schema' object is no longer supported in bro.js v2.3.0+. Please use flat, top-level properties (body, query, params) instead.");
+    }
+    const bodySchema = routeConfig.body;
+    const paramsSchema = routeConfig.params;
+    const querySchema = routeConfig.query;
     
     if (routeConfig.rateLimit) {
       middlewares.push(rateLimit(routeConfig.rateLimit));
@@ -80,6 +86,7 @@ export async function createServer(globalConfig, routesDir, db) {
     
     middlewares.push(async (req, res) => {
       try {
+        const requestLocale = locale.resolveLocale(req);
         const ctx = {
           env: globalConfig.envData || process.env,
           db,
@@ -88,6 +95,8 @@ export async function createServer(globalConfig, routesDir, db) {
           params: req.params,
           query: req.query,
           files: req.files || req.file,
+          locale: requestLocale,
+          t: (key, values) => locale.translate(requestLocale, key, values),
           user: null,
           jwt: { sign: (payload, opts) => signJwt(payload, globalConfig.jwtSecret, opts || { expiresIn: globalConfig.auth?.expiresIn || '1d' }) },
           error: (status, message) => {
@@ -97,21 +106,18 @@ export async function createServer(globalConfig, routesDir, db) {
           }
         };
 
-        if (routeConfig.auth) {
-          const authHeader = req.headers.authorization;
-          if (!authHeader || !authHeader.startsWith('Bearer ')) {
-            return res.status(401).json({ error: 'Unauthorized', details: 'Missing or invalid Bearer token' });
-          }
-          
-          const token = authHeader.split(' ')[1];
-          const authResult = verifyJwt(token, globalConfig.jwtSecret);
-          
-          if (!authResult.valid) {
-            return res.status(401).json({ error: 'Unauthorized', details: authResult.error });
-          }
-          
-          ctx.user = authResult.payload;
+        const authHeader = req.headers.authorization;
+        if ((!authHeader || !authHeader.startsWith('Bearer ')) && routeConfig.auth) {
+          return res.status(401).json({ error: 'Unauthorized', details: 'Missing or invalid Bearer token' });
         }
+        
+        const token = authHeader?.split(' ')[1] ?? '';
+        const authResult = verifyJwt(token, globalConfig.jwtSecret);
+        
+        if (!authResult.valid && routeConfig.auth) {
+          return res.status(401).json({ error: 'Unauthorized', details: authResult.error });
+        }
+        ctx.user = authResult?.payload ?? null;
 
         if (paramsSchema) {
           const result = paramsSchema.safeParse(req.params);
@@ -235,17 +241,34 @@ export async function createServer(globalConfig, routesDir, db) {
     return routes;
   };
 
+  const reloadLocale = async () => {
+    locale = await loadLocale(localeDirectory, globalConfig.locale);
+    return locale;
+  };
+
   const initialRoutes = await reload();
 
   const taskManager = await scanTasks({ db, io });
 
+  let isShuttingDown = false;
   const shutdown = async () => {
+    if (isShuttingDown) return;
+    isShuttingDown = true;
     if (taskManager) taskManager.stopAll();
     if (io) io.close();
+    
+    if (typeof globalConfig.onShutdown === 'function') {
+      try {
+        await globalConfig.onShutdown(db);
+      } catch (err) {
+        console.error('[bro.js] Error during database teardown hook:', err);
+      }
+    }
+
     return new Promise((resolve) => {
       server.close(() => resolve());
     });
   };
 
-  return { app, server, routes: initialRoutes, reload, io, shutdown };
+  return { app, server, routes: initialRoutes, reload, reloadLocale, io, shutdown };
 }