barejs 0.1.3 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xarhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,10 +1,28 @@
 # 🚀 BareJS
+### The Ultra-Low Latency JIT Web Engine for Bun
 
-BareJS is an ultra-high-performance web engine built on the Bun runtime, designed for minimalism and the lowest possible latency.
+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.
+
+---
 
 ---
 
@@ -18,7 +36,7 @@ Performance comparison between **BareJS**, **Elysia**, and **Hono**.
 <!-- MARKER: PERFORMANCE_TABLE_START -->
 | Framework | Latency (Avg) | Speed Ratio |
 | :--- | :--- | :--- |
-| **BareJS (Your Engine)** | **-- ns/iter** | **Baseline (1.0x)** |
+| **BareJS** | **-- ns/iter** | **Baseline (1.0x)** |
 | Elysia | -- ns/iter | --x slower |
 | Hono | -- ns/iter | --x slower |
 <!-- MARKER: PERFORMANCE_TABLE_END -->
@@ -27,27 +45,108 @@ Performance comparison between **BareJS**, **Elysia**, and **Hono**.
 
 ---
 
-## ✨ Features
 
-- **Ultra Low Latency:** Optimized to minimize processing overhead.
-- **Zero Dependency:** Built natively for security and raw speed.
-- **Optimized for Bun:** Leverages native Bun APIs for maximum performance.
-- **Memory Efficient:** Minimal heap usage and clean garbage collection.
+### ✨ **Features**
 
-## 🛠 Getting Started
+* **Ultra Low Latency:** Optimized to minimize processing overhead.
+* **Zero Dependency:** Built natively for security and raw speed.
+* **Optimized for Bun:** Leverages native Bun APIs for maximum performance.
+* **Memory Efficient:** Minimal heap usage and clean garbage collection.
 
-### Prerequisites
-- [Bun](https://bun.sh) v1.0.0 or higher
+---
+
+## 📦 Installation
 
-### Installation
 ```bash
-bun install
+bun add barejs
 ```
 
-### Running Benchmarks Locally
+---
 
-```bash
-bun run benchmarks/index.ts
+## ⚡ Quick Start
+
+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`)
+
+Every handler receives a `Context` object, providing a high-speed interface to the request:
+
+* `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 { typebox, zod, native } from 'barejs/middleware';
+import { Type } from '@sinclair/typebox';
+import { z } from 'zod';
+
+// High Performance: TypeBox
+const UserSchema = Type.Object({ name: Type.String() });
+app.post('/tb', typebox(UserSchema), (ctx) => ctx.json(ctx.body));
+
+// Popular Choice: Zod
+const ZodSchema = z.object({ age: z.number() });
+app.post('/zod', zod(ZodSchema), (ctx) => ctx.json(ctx.body));
+
+// Zero Dependency: Native
+app.post('/native', native({ properties: { id: { type: 'number' } } }), (ctx) => ctx.json(ctx.body));
 
 ```
 
@@ -55,11 +154,21 @@ bun run benchmarks/index.ts
 
 ## 🏗 Roadmap
 
-* [x] Middleware Pattern Support (Chain Execution)
-* [x] High-Speed Static Routing (O(1) Lookup Table)
-* [x] Schema Validation Integration
-* [ ] Full Documentation
+* [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.
 
 ---
 
-*Maintained by xarhang*
+## 💎 Credits & Dependencies
+
+* **[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.3",
+  "version": "0.1.5",
   "author": "xarhang",
   "description": "High-performance JIT-specialized web framework for Bun",
   "main": "src/bare.ts",
@@ -36,6 +36,7 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ]
 }

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,
+    });
+  }
+}