barejs 0.1.38 → 0.1.40

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
   <br />
-   <h1>Bare<span style="color: #F7DF1E;">JS</span></h1>
+  <h1>Bare<span style="color: #F7DF1E;">JS</span></h1>
   <p><strong>The "Metal" of Web Frameworks</strong></p>
   <p><i>An ultra-high-performance web engine built for Bun, architected strictly for Mechanical Sympathy.</i></p>
 
@@ -29,14 +29,10 @@
   ---
 </div>
 
-
-
 ## 📊 Benchmarks: Real-World Performance
 
-BareJS leads in complex, real-world scenarios. We test using a **"Real-World" Stress Test** involving **10 middlewares** and **Deep Path Routing** to ensure we measure engine efficiency, not just hello-world speed.
-
+BareJS leads in complex, real-world scenarios. We measure engine efficiency using a **stress test** involving **10+ middlewares** and **deep radix tree routing** to ensure performance holds under high concurrency, not just in isolated "Hello World" loops.
 <!-- MARKER: PERFORMANCE_TABLE_START -->
-
 | Framework | Latency | Speed |
 | :--- | :--- | :--- |
 | **BareJS** | **1.15 µs** | **Baseline** |
@@ -48,27 +44,32 @@ BareJS leads in complex, real-world scenarios. We test using a **"Real-World" St
 <!-- MARKER: PERFORMANCE_TABLE_END -->
 > [!TIP]
 > **View our [Continuous Benchmark Dashboard](https://xarhang.github.io/bareJS/dev/benchmarks/)** for historical data and detailed performance trends across different hardware.
----
-### Why BareJS is Faster
-* **Flat Pipeline:** No recursive middleware overhead.
-* **JIT Route Compilation:** Pre-calculates route matching before the first request hits.
-* **Zero Dependency:** Built purely for the Bun runtime.
 
-## 🛠️ Installation & Setup
+## 🚀 Key Features
+
+* **JIT Pipeline Compilation**: Routes and middleware chains are compiled into a single, flattened JavaScript function at runtime to eliminate recursive call overhead.
+* **Object Pooling**: Recycles `Context` objects via a circular buffer, significantly reducing Garbage Collection (GC) pressure.
+* **Lazy Body Parsing**: Requests are processed instantly. Payloads are only parsed on-demand via `ctx.jsonBody()`, maintaining peak speed for GET requests.
+* **Mechanical Sympathy**: Intentionally designed to align with V8's optimization heuristics and Bun's internal I/O architecture.
+
+## 🛠️ Installation
 
 ```bash
 bun add barejs
+
 ```
 
 ### The "Bare" Minimum
+
 ```typescript
-import { BareJS,type Context } from 'barejs';
+import { BareJS, type Context } from 'barejs';
 
 const app = new BareJS();
 
 app.get('/', (ctx: Context) => ctx.json({ hello: "world" }));
 
 app.listen(3000);
+
 ```
 
 ---
@@ -76,7 +77,8 @@ app.listen(3000);
 ## 📘 Comprehensive Guide
 
 ### 1. 🔀 Advanced Routing
-Use `BareRouter` for modularity and nesting.
+
+Modularize your application and maintain clean codebases using `BareRouter`.
 
 ```typescript
 import { BareJS, BareRouter, type Context } from 'barejs';
@@ -86,21 +88,23 @@ const api = new BareRouter("/api/v1");
 
 api.get("/status", (ctx: Context) => ({ status: "ok" }));
 
-app.use(api); // Result: /api/v1/status
+app.use(api); // Accessible at /api/v1/status
+
 ```
 
 ### 2. 🛡️ Security & Authentication
-Full RFC 7515 compliant JWT support and secure password utilities.
+
+Built-in utilities for secure password hashing (Argon2/Bcrypt via Bun) and RFC-compliant JWT handling.
 
 ```typescript
 import { bareAuth, createToken, Password, type Context } from 'barejs';
 
-const SECRET = "your-secret";
+const SECRET = "your-ultra-secure-secret";
 
-// JWT Generation
 app.post('/login', async (ctx: Context) => {
-  const hash = await Password.hash("password123");
-  const isValid = await Password.verify("password123", hash);
+  const body = await ctx.jsonBody();
+  const hash = await Password.hash(body.password);
+  const isValid = await Password.verify(body.password, hash);
   
   if (isValid) {
     const token = await createToken({ id: 1 }, SECRET);
@@ -108,78 +112,108 @@ app.post('/login', async (ctx: Context) => {
   }
 });
 
-// Protection Middleware
+// Protect routes with bareAuth middleware
 app.get('/me', bareAuth(SECRET), (ctx: Context) => {
-  const user = ctx.get('user'); // Set by bareAuth
+  const user = ctx.get('user'); // Identity injected by bareAuth
   return { user };
 });
+
 ```
 
 ### 3. ✅ Data Validation (3 Styles)
-Choose the validation style that fits your workflow.
+
+BareJS integrates deeply with TypeBox for JIT-level speeds but remains compatible with the broader ecosystem.
 
 ```typescript
 import { typebox, zod, native, t, type Context } from 'barejs';
 import { z } from 'zod';
 
-// Style A: TypeBox (Fastest, Highly Recommended)
+// Style A: TypeBox (Highest Performance - Recommended)
 const TypeBoxSchema = t.Object({ name: t.String() });
-app.post('/typebox', typebox(TypeBoxSchema), (ctx: Context) => ctx.body);
+app.post('/typebox', typebox(TypeBoxSchema), async (ctx: Context) => {
+  const body = await ctx.jsonBody();
+  return body;
+});
 
-// Style B: Zod (Standard)
+// Style B: Zod (Industry Standard)
 const ZodSchema = z.object({ age: z.number() });
-app.post('/zod', zod(ZodSchema), (ctx: Context) => ctx.body);
+app.post('/zod', zod(ZodSchema), async (ctx: Context) => {
+  const body = await ctx.jsonBody();
+  return body;
+});
+
+// Style C: Native (Zero Dependency / JSON Schema)
+const NativeSchema = { 
+  type: "object",
+  properties: { id: { type: 'number' } },
+  required: ["id"]
+};
+app.post('/native', native(NativeSchema), async (ctx: Context) => {
+  const body = await ctx.jsonBody();
+  return body;
+});
 
-// Style C: Native (Zero Dependency)
-const NativeSchema = { properties: { id: { type: 'number' } } };
-app.post('/native', native(NativeSchema), (ctx: Context) => ctx.body);
 ```
 
 ### 4. 🔌 Essential Plugins
-Built-in utilities for modern web development.
+
+Standard utilities optimized for the BareJS engine's execution model.
 
 #### **Logger**
-Color-coded terminal logging with millisecond-precision timing.
+
+High-precision terminal logging with color-coded status codes and microsecond timing.
+
 ```typescript
 import { logger } from 'barejs';
 app.use(logger);
+
 ```
 
 #### **CORS**
+
+Highly optimized Cross-Origin Resource Sharing middleware.
+
 ```typescript
 import { cors } from 'barejs';
-app.use(cors({ origin: "*", methods: "GET,POST" }));
+app.use(cors({ origin: "*", methods: ["GET", "POST"] }));
+
 ```
 
 #### **Static Files**
-Efficiently serve files from any directory.
+
+Serves static assets with zero-overhead using Bun's native file system implementation.
+
 ```typescript
 import { staticFile } from 'barejs';
-app.use(staticFile("public")); // Serves ./public/* at /
+app.use(staticFile("public"));
+
 ```
 
-### 5. 🧠 Context API
-The `Context` object is recycled to eliminate GC overhead.
+---
+
+## 🧠 Context API
+
+The `Context` object is pre-allocated in a circular pool to eliminate memory fragmentation.
 
 | Method / Property | Description |
-| :--- | :--- |
-| `ctx.req` | Raw Bun `Request` object |
-| `ctx.params` | Route parameters |
-| `ctx.body` | Validated body (from `typebox`, `zod`, etc.) |
-| `ctx.status(code)` | Sets response status |
-| `ctx.json(data)` | Returns an optimized JSON response |
-| `ctx.set(k, v)` | Stores data in request lifecycle |
-| `ctx.get(k)` | Retrieves stored data |
+| --- | --- |
+| `ctx.req` | Raw incoming Bun `Request` object. |
+| `ctx.params` | Object containing route parameters (e.g., `:id`). |
+| **`ctx.jsonBody()`** | **[Async]** Parses the JSON body on-demand and caches it for the lifecycle. |
+| `ctx.status(code)` | Sets the HTTP status code (Chainable). |
+| `ctx.json(data)` | Finalizes and returns an optimized JSON response. |
+| `ctx.set(k, v)` | Stores metadata in the request-scoped store. |
+| `ctx.get(k)` | Retrieves stored data from the lifecycle store. |
 
 ---
 
 ## ⚙️ Performance Tuning
 
 | OS Variable | Default | Description |
-| :--- | :--- | :--- |
-| `BARE_POOL_SIZE` | `1024` | Pre-allocated context pool. Use power of 2. |
-| `NODE_ENV` | `development` | Use `production` to enable max JIT stability. |
+| --- | --- | --- |
+| `BARE_POOL_SIZE` | `1024` | Pre-allocated context pool size. Must be a **Power of 2**. |
+| `NODE_ENV` | `development` | Use `production` to hide stack traces and enable V8's hot-path optimizations. |
 
 ---
 
-**Maintained by [xarhang](https://github.com/xarhang)** | **License: MIT**
+**Maintained by [xarhang](https://github.com/xarhang) | **License: MIT**