barejs 0.1.4 → 0.1.5

package/README.md

@@ -1,9 +1,28 @@
 # 🚀 BareJS
-BareJS is an ultra-high-performance web engine built on the Bun runtime, designed for minimalism and the lowest possible latency.
+### The Ultra-Low Latency JIT Web Engine for Bun
+
+BareJS is a minimalist, high-performance web engine architected for the **Bun** ecosystem. By utilizing a **Just-In-Time (JIT) Route Compilation** strategy and an asynchronous **Onion-Model** pipeline, BareJS achieves near-native throughput, outperforming traditional frameworks by eliminating runtime routing overhead.
 
 ![Benchmark Status](https://github.com/xarhang/bareJS/actions/workflows/bench.yml/badge.svg)
 [![Performance Dashboard](https://img.shields.io/badge/Performance-Dashboard-blueviolet?style=flat-square&logo=speedtest)](https://xarhang.github.io/bareJS/dev/benchmarks/)
 [![Bun Version](https://img.shields.io/badge/Bun-%3E%3D1.0.0-black?style=flat-square&logo=bun)](https://bun.sh)
+[![NPM Version](https://img.shields.io/npm/v/barejs.svg?style=flat-square)](https://www.npmjs.com/package/barejs)
+
+---
+
+## 🏛 Architectural Engineering
+
+Unlike traditional frameworks that iterate through arrays or regex patterns on every request, BareJS utilizes a **Static Compilation Phase**.
+
+
+
+### The JIT Lifecycle
+When `app.listen()` is invoked, the engine:
+1. **Analyzes** the complete route tree and global middleware stack.
+2. **Serializes** the execution logic into a flat, optimized JavaScript function.
+3. **Binds** the function using `new Function()`, allowing the **JavaScriptCore (JSC)** engine to perform aggressive inline caching and speculative optimizations.
+
+---
 
 ---
 
@@ -26,7 +45,8 @@ Performance comparison between **BareJS**, **Elysia**, and **Hono**.
 
 ---
 
-✨ **Features**
+
+### ✨ **Features**
 
 * **Ultra Low Latency:** Optimized to minimize processing overhead.
 * **Zero Dependency:** Built natively for security and raw speed.
@@ -35,50 +55,88 @@ Performance comparison between **BareJS**, **Elysia**, and **Hono**.
 
 ---
 
-## 📖 Documentation
-
-### ⚡ The Core Engine
-
-BareJS uses a **Static Route Compiler**. When you call `app.listen()`, BareJS transforms your routes into an optimized lookup table. This ensures  routing complexity, meaning your app stays fast whether you have 10 routes or 10,000.
-
-### 🏗️ Request Context
-
-Every handler receives a `Context` object:
+## 📦 Installation
 
-* `ctx.req`: The native Bun `Request`.
-* `ctx.params`: Route parameters (e.g., `/user/:id`).
-* `ctx.json(data)`: High-speed JSON response helper.
-* `ctx.body`: The validated JSON payload (available when using validators).
+```bash
+bun add barejs
+```
 
 ---
 
-## 🛠 Usage Examples
+## ⚡ Quick Start
 
-### 1. Basic Server
+Create an `index.ts` and get your server running in seconds:
 
 ```typescript
 import { BareJS } from 'barejs';
 
 const app = new BareJS();
 
+// Simple Route
 app.get('/ping', (ctx) => ctx.json({ message: 'pong' }));
 
+// Start Server
 app.listen('0.0.0.0', 3000);
 
 ```
+---
+
+## 📖 Manual & Documentation
+
+### 1. Request Context (`ctx`)
 
-### 2. Validation (Choose Your Weapon)
+Every handler receives a `Context` object, providing a high-speed interface to the request:
 
-BareJS allows you to use different validators for different routes.
+* `ctx.req`: The [Native Bun Request](https://www.google.com/search?q=https://bun.sh/docs/api/http%23request).
+* `ctx.json(data)`: Optimized JSON response helper with pre-defined headers.
+* `ctx.body`: The validated JSON payload (available when using validators).
+* `ctx.params`: Route parameters (e.g., `/user/:id`).
+
+### 2. Middleware (The Onion Model)
+
+BareJS supports an asynchronous recursive pipeline, allowing you to wrap logic before and after the handler.
+
+```typescript
+app.use(async (ctx, next) => {
+  const start = performance.now();
+  const response = await next(); // Proceed to next middleware or handler
+  console.log(`Latency: ${(performance.now() - start).toFixed(2)}ms`);
+  return response;
+});
+
+```
+
+### 3. Full Plugin System
+
+Encapsulate complex logic into reusable modules that plug directly into the engine lifecycle.
+
+```typescript
+const databasePlugin = {
+  name: 'barejs-db',
+  version: '1.0.0',
+  install: (app: BareJS) => {
+    app.use(async (ctx, next) => {
+      ctx.db = "CONNECTED";
+      return await next();
+    });
+  }
+};
+
+app.use(databasePlugin);
+
+```
+
+---
+
+## 🛡️ Schema Validation
+
+BareJS allows you to use different validators for different routes, focusing on high-speed schema checks.
 
 ```typescript
-import { BareJS } from 'barejs';
 import { typebox, zod, native } from 'barejs/middleware';
 import { Type } from '@sinclair/typebox';
 import { z } from 'zod';
 
-const app = new BareJS();
-
 // High Performance: TypeBox
 const UserSchema = Type.Object({ name: Type.String() });
 app.post('/tb', typebox(UserSchema), (ctx) => ctx.json(ctx.body));
@@ -87,41 +145,30 @@ app.post('/tb', typebox(UserSchema), (ctx) => ctx.json(ctx.body));
 const ZodSchema = z.object({ age: z.number() });
 app.post('/zod', zod(ZodSchema), (ctx) => ctx.json(ctx.body));
 
-// No Dependencies: Native
+// Zero Dependency: Native
 app.post('/native', native({ properties: { id: { type: 'number' } } }), (ctx) => ctx.json(ctx.body));
 
 ```
 
 ---
 
-## 🛠 Getting Started
-
-### Prerequisites
-
-* **Bun** v1.0.0 or higher
-
-### Installation
-
-```bash
-bun install barejs
-
-```
-
-### Running Benchmarks Locally
+## 🏗 Roadmap
 
-```bash
-bun run bench
+* [x] **Middleware Support**: Async/Await "Onion" execution chain.
+* [x] **JIT Static Routing**:  lookup via compiled static maps.
+* [x] **Validation Integration**: Support for TypeBox, Zod, and Native JSON.
+* [x] **Full Plugin System**: Modular extensibility with zero overhead.
+* [ ] **Dynamic Path JIT**: Compiled Regex for parameterized routes (e.g., `/user/:id`).
+* [ ] **Native WebSocket Support**: High-speed binary streaming.
 
-```
-
-## 🏗 Roadmap
+---
 
-* [x] Middleware Pattern Support (Chain Execution)
-* [x] High-Speed Static Routing ( Lookup Table)
-* [x] Schema Validation Integration
-* [x] Modular Validator Support (TypeBox, Zod, Native)
-* [ ] Full Plugin System
+## 💎 Credits & Dependencies
 
-**Maintained by xarhang**
+* **[Bun](https://bun.sh/)**: The foundational runtime for BareJS.
+* **[TypeBox](https://github.com/sinclairzx81/typebox)** & **[Zod](https://zod.dev/)**: For high-speed type safety.
+* **Inspiration**: Architectural patterns from **Koa** and **ElysiaJS**.
 
----
+**Maintained by [xarhang**](https://www.google.com/search?q=https://github.com/xarhang)
+**License: MIT**
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "barejs",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "author": "xarhang",
   "description": "High-performance JIT-specialized web framework for Bun",
   "main": "src/bare.ts",

package/src/bare.ts

@@ -2,7 +2,7 @@ export interface Context {
   req: Request;
   params: Record<string, string>;
   json: (data: any) => Response;
-  body?: any; 
+  body?: any;
   [key: string]: any;
 }
 
@@ -10,65 +10,94 @@ export type Next = () => Promise<any> | any;
 export type Middleware = (ctx: Context, next: Next) => any;
 export type Handler = (ctx: Context) => any;
 
+export interface BarePlugin {
+  name: string;
+  version: string;
+  install: (app: BareJS) => void;
+}
+
 export class BareJS {
   private routes: { method: string; path: string; handlers: (Middleware | Handler)[] }[] = [];
   private globalMiddlewares: Middleware[] = [];
-  private compiledFetch?: (req: Request) => Promise<Response>;
+  private compiledFetch?: (req: Request) => Promise<Response> | Response;
   private staticMap: Record<string, any> = {};
 
+  // --- Routing Methods ---
+  public get = (path: string, ...h: (Middleware | Handler)[]) => { this.routes.push({ method: "GET", path, handlers: h }); return this; };
   public post = (path: string, ...h: (Middleware | Handler)[]) => { this.routes.push({ method: "POST", path, handlers: h }); return this; };
   public put = (path: string, ...h: (Middleware | Handler)[]) => { this.routes.push({ method: "PUT", path, handlers: h }); return this; };
   public patch = (path: string, ...h: (Middleware | Handler)[]) => { this.routes.push({ method: "PATCH", path, handlers: h }); return this; };
   public delete = (path: string, ...h: (Middleware | Handler)[]) => { this.routes.push({ method: "DELETE", path, handlers: h }); return this; };
-  public get = (path: string, ...h: (Middleware | Handler)[]) => { this.routes.push({ method: "GET", path, handlers: h }); return this; };
-  public use = (...m: Middleware[]) => { this.globalMiddlewares.push(...m); return this; };
 
+  // --- Plugin & Middleware System ---
+  public use = (arg: Middleware | BarePlugin) => {
+    if (typeof arg === 'object' && 'install' in arg) {
+      arg.install(this);
+    } else {
+      this.globalMiddlewares.push(arg as Middleware);
+    }
+    return this;
+  };
+
+  // --- Core Engine ---
   public fetch = (req: Request): Promise<Response> | Response => {
     if (!this.compiledFetch) this.compile();
     return this.compiledFetch!(req);
-  }
+  };
 
   private compile() {
     this.routes.forEach((route) => {
-      const chain = (ctx: Context) => {
+      // Middleware Onion Runner
+      const chain = async (ctx: Context) => {
         let idx = 0;
         const middlewares = [...this.globalMiddlewares, ...route.handlers];
-        const next = (): any => {
+        const next = async (): Promise<any> => {
           const handler = middlewares[idx++];
           if (!handler) return;
-          return handler(ctx, next);
+          // Support both async and sync handlers
+          return await (handler.length > 1 
+            ? (handler as Middleware)(ctx, next) 
+            : (handler as Handler)(ctx));
         };
-        return next();
+        return await next();
       };
       this.staticMap[`${route.method}:${route.path}`] = chain;
     });
 
+    // JIT Optimized Fetch Function
     const fnBody = `
       const staticMap = this.staticMap;
       const EMPTY_PARAMS = Object.freeze({});
       const jsonHeader = { "content-type": "application/json" };
-      return (req) => {
+      
+      return async (req) => {
         const url = req.url;
         const pathStart = url.indexOf('/', 8);
         const path = pathStart === -1 ? '/' : url.substring(pathStart);
         const key = req.method + ":" + path;
+        
         const runner = staticMap[key];
         if (runner) {
-          const ctx = { req, params: EMPTY_PARAMS, json: (d) => new Response(JSON.stringify(d), { headers: jsonHeader }) };
-          return runner(ctx);
+          const ctx = { 
+            req, 
+            params: EMPTY_PARAMS, 
+            json: (d) => new Response(JSON.stringify(d), { headers: jsonHeader }) 
+          };
+          return await runner(ctx);
         }
         return new Response('404 Not Found', { status: 404 });
       };`;
+
     this.compiledFetch = new Function(fnBody).bind(this)();
   }
 
-  listen(ip: string = '0.0.0.0', port: number = 3000) {
+  public listen(ip: string = '0.0.0.0', port: number = 3000) {
     this.compile();
     console.log(`🚀 BareJS running at http://${ip}:${port}`);
     return Bun.serve({
       hostname: ip,
       port,
-      fetch: (req) => this.compiledFetch!(req),
+      fetch: (req) => this.fetch(req),
     });
   }
 }

package/src/types.ts

@@ -0,0 +1,24 @@
+// src/context.ts
+export class Context {
+  public res: Response;
+
+  constructor(public req: Request) {
+    this.res = new Response("Not Found", { status: 404 });
+  }
+
+  json(data: any) {
+    this.res = new Response(JSON.stringify(data), {
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+
+  setResHeader(key: string, value: string) {
+    const newHeaders = new Headers(this.res.headers);
+    newHeaders.set(key, value);
+    this.res = new Response(this.res.body, {
+      status: this.res.status,
+      headers: newHeaders,
+    });
+  }
+}