@techiev2/vajra 1.0.1 → 1.1.0

package/README

@@ -0,0 +1,193 @@
+# Vajra ⚡
+
+![Vajra Thunderbolt](assets/vajra.jpg)  <!-- or use one of the above hosted URLs if you like -->
+
+
+**Ultra-minimal, zero-dependency Node.js HTTP server**  
+Routing · Middleware · Multipart parsing · HTML templating  
+All in **111 lines** of pure JavaScript
+
+## Name Origin
+
+Vajra draws from the Rigvedic thunderbolt weapon of Indra — crafted from the bones of Sage Dadhichi, symbolizing unbreakable strength through selfless sacrifice.
+
+Like the Vajra, this server delivers maximum power in minimal form.
+
+
+[![npm version](https://img.shields.io/npm/v/vajra.svg?style=flat-square)](https://www.npmjs.com/package/vajra)
+[![npm downloads](https://img.shields.io/npm/dm/vajra.svg?style=flat-square)](https://www.npmjs.com/package/vajra)
+[![Node.js version](https://img.shields.io/node/v/vajra.svg?style=flat-square)](https://nodejs.org)
+[![License](https://img.shields.io/npm/l/vajra.svg?style=flat-square)](LICENSE)
+
+## Features
+
+- Zero external dependencies
+- Built-in routing with named parameters (`:id`)
+- Global middleware support with `next()` chaining
+- JSON, urlencoded, and **multipart/form-data** body parsing
+- Fast HTML templating with loops, nested objects, and simple array headers
+- Helper methods: `res.json()`, `res.html()`, `res.status()`, `res.writeMessage()`
+- Payload size limiting with 413 responses
+- Sensible defaults for 404/405/500
+
+## Performance (Apple M4, Node 20+)
+
+| Test Case                                      | Vajra          | Express + Multer | Notes                     |
+|------------------------------------------------|----------------|------------------|---------------------------|
+| 1MB Multipart Upload (wrk -t16 -c600)          | **~94–98k req/s** | ~72k req/s      | +30% faster               |
+| Idle RSS                                       | ~52–53 MB      | ~44 MB           | Zero deps vs extra packages |
+| Peak RSS under load                            | ~228 MB        | ~209 MB          | Full buffering trade-off  |
+| Code size (source)                             | **111 lines**  | ~2k+ lines       | Hand-crafted minimalism   |
+
+## Performance Benchmarks (wrk)
+
+![wrk multipart benchmarks on M4 and VPS](assets/wrk-benchmarks.png)
+
+## Installation
+
+```bash
+npm install vajra
+```
+
+
+## Quick Start
+```JavaScript
+import Vajra from '../index.js';
+import { encode } from 'node:querystring';
+
+async function getUsers(query = {}) {
+  return (await fetch(`https://jsonplaceholder.typicode.com/users?${encode(query)}`)).json()
+}
+
+const { get, post, use, start, setProperty } = Vajra.create();
+
+setProperty({ viewsRoot: `${import.meta.url}/views` })
+// Or as a key-value pair
+// setProperty('viewsRoot', `${import.meta.url}/views`)
+
+use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`);
+  next();
+});
+
+get('/', (req, res) => {
+  res.writeMessage('Hello from Vajra ⚡');
+});
+
+post('/upload', (req, res) => {
+  res.json({ received: true, filesCount: req.files.length, files: req.files, body: req.body });
+});
+
+start({ port: 4002 }, () => {
+  console.log('Ready at http://localhost:4002');
+});
+
+get('/api/users', async ({ query }, res) => {
+  const users = await getUsers(query)
+  return res.json({ users })
+})
+
+get('/web/users', async ({ query }, res) => {
+  const users = await getUsers(query)
+  const headers = Object.keys(users[0])
+  return res.html(`users.html`, { users, headers })
+})
+```
+
+## HTML Templating
+```JavaScript
+import Vajra from '../index.js';
+const { get, post, use, start, setProperty } = Vajra.create();
+
+get('/users', (req, res) => {
+  const data = {
+    users: [
+      { id: 1, name: 'Alice' },
+      { id: 2, name: 'Bob' }
+    ],
+    headers: ['ID', 'Name']
+  };
+
+  // If no view root is set, .html() expects the absolute path.
+  res.html('views/users.html', data);
+});
+```
+
+#### views/users.html
+```html
+<table>
+  <thead>
+    {{# headers }}
+      <th>{{ header@ }}</th>
+    {{/ headers }}
+  </thead>
+  <tbody>
+    {{# users }}
+      <tr>
+        <td>{{ id }}</td>
+        <td>{{ name }}</td>
+      </tr>
+    {{/ users }}
+  </tbody>
+</table>
+```
+
+Supports:
+
+- Loops ({{# array }} ... {{/ array }})
+- Dot notation ({{ user.name }})
+- Special header shorthand ({{ header@ }} for simple arrays)
+
+
+## Configuration
+```JavaScript
+const app = vajra.create({
+  maxFileSize: 10 // in MB (default: 2)
+});
+
+// Set view root path
+app.setProperty('viewRoot', './views');
+```
+
+
+## API
+
+- `get/post/put/patch/delete/head/options(path, handler)`
+- `use(middleware)`
+- `start({ port, host }, callback?)`
+- `setProperty(key, value)` or `setProperty({ key: value })`
+
+
+#### Response helpers:
+
+`res.status(code)`
+`res.json(data)`
+`res.writeMessage(text)`
+`res.html(pathOrString, data)`
+
+
+## Philosophy
+
+Vajra is built on the principle that minimalism can maximise outcomes.
+
+Everything you need for real internal tools, admin panels, APIs, and prototypes — without the bloat.
+
+No dependencies.
+No build step.
+Just copy `index.js` and go.
+
+
+## Benchmarks & Memory
+Run under extreme multipart load (wrk -t16 -c600 -d30s 1MB payloads):
+
+Throughput: ~95k req/s
+Idle RSS: ~52 MB
+Peak under load: ~228 MB (drops back on idle)
+
+## License
+MIT
+
+## Credits
+Hand-crafted by [[Sriram Velamur](https://linkedin.com/in/techiev2)/[@techiev2](https://x.com/techiev2)]
+
+Inspired by the desire for a truly tiny, powerful, and dependency-free Node server.

package/README.md

@@ -14,15 +14,16 @@ Vajra draws from the Rigvedic thunderbolt weapon of Indra — crafted from the b
 Like the Vajra, this server delivers maximum power in minimal form.
 
 
-[![npm version](https://img.shields.io/npm/v/vajra.svg?style=flat-square)](https://www.npmjs.com/package/vajra)
-[![npm downloads](https://img.shields.io/npm/dm/vajra.svg?style=flat-square)](https://www.npmjs.com/package/vajra)
-[![Node.js version](https://img.shields.io/node/v/vajra.svg?style=flat-square)](https://nodejs.org)
-[![License](https://img.shields.io/npm/l/vajra.svg?style=flat-square)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@techiev2/vajra.svg?style=flat-square)](https://www.npmjs.com/package/@techiev2/vajra)
+[![npm downloads](https://img.shields.io/npm/dm/vajra.svg?style=flat-square)](https://www.npmjs.com/package/@techiev2/vajra)
+[![Node.js version](https://img.shields.io/node/v/@techiev2/vajra.svg?style=flat-square)](https://nodejs.org)
+[![License](https://img.shields.io/npm/l/@techiev2/vajra.svg?style=flat-square)](LICENSE)
 
 ## Features
 
 - Zero external dependencies
 - Built-in routing with named parameters (`:id`)
+- Asynchronous batched logging for performance
 - Global middleware support with `next()` chaining
 - JSON, urlencoded, and **multipart/form-data** body parsing
 - Fast HTML templating with loops, nested objects, and simple array headers
@@ -59,14 +60,17 @@ async function getUsers(query = {}) {
   return (await fetch(`https://jsonplaceholder.typicode.com/users?${encode(query)}`)).json()
 }
 
-const { get, post, use, start, setProperty } = Vajra.create();
+const { get, post, use, start, setProperty, log } = Vajra.create();
 
 setProperty({ viewsRoot: `${import.meta.url}/views` })
 // Or as a key-value pair
 // setProperty('viewsRoot', `${import.meta.url}/views`)
 
 use((req, res, next) => {
-  console.log(`${req.method} ${req.url}`);
+  // Vajra provides an async batched logger to provide a balance between 100% log coverage and performance.
+  // If you prefer blocking immediate logs, you can switch to console.log
+  // or any other library of your choice.
+  log(`${req.method} ${req.url}`);
   next();
 });
 
@@ -156,6 +160,7 @@ app.setProperty('viewRoot', './views');
 - `use(middleware)`
 - `start({ port, host }, callback?)`
 - `setProperty(key, value)` or `setProperty({ key: value })`
+- `log(message)`
 
 
 #### Response helpers:

package/examples/api.js

@@ -5,12 +5,12 @@ async function getUsers(query = {}) {
   return (await fetch(`https://jsonplaceholder.typicode.com/users?${encode(query)}`)).json()
 }
 
-const { get, post, use, start, setProperty } = Vajra.create();
+const { get, post, use, start, setProperty, log } = Vajra.create();
 
 setProperty({ viewRoot: `${import.meta.dirname}/views` })
 
 use((req, res, next) => {
-  console.log(`${req.method} ${req.url}`);
+  log(`${req.method} ${req.url}`)
   next();
 });
 

package/index.js

@@ -25,8 +25,11 @@ const MAX_MB = 2; const MAX_FILE_SIZE = MAX_MB * 1024 * 1024
 export default class Vajra {
   static #app; static #routes = {}; static #middlewares = []; static #straightRoutes = {}; static #MAX_FILE_SIZE; static #onCreate; static #props = {}
   static create({ maxFileSize } = { maxFileSize: 2 }) {
-    Vajra.#MAX_FILE_SIZE = !+MAX_FILE_SIZE ? +maxFileSize * 1024 * 1024 : MAX_FILE_SIZE
     Vajra.#app = createServer()
+    const _queue = []; const LOG_QUEUE_SIZE = 100; const logOut = () => { if (_queue.length) { process.stdout.write(`${_queue.join('').trim()}\n`) }; _queue.length = 0 };
+    const flushAndShutDown = () => { logOut(); Vajra.#app.close(() => { process.exit(0); }); }; 'SIGINT_SIGTERM_SIGABRT'.split('_').map((evt) => process.on(evt, flushAndShutDown));
+    process.on('exit', logOut); function log(message) { _queue.push(`${message}\n`); if (_queue.length >= LOG_QUEUE_SIZE) { logOut(); _queue.length = 0; } }
+    Vajra.#MAX_FILE_SIZE = !+MAX_FILE_SIZE ? +maxFileSize * 1024 * 1024 : MAX_FILE_SIZE
     Vajra.#app.on('request', async (req, res) => {
       res.sent = false;
       res.status = (/**@type{code} Number*/ code) => {
@@ -104,8 +107,6 @@ export default class Vajra {
       if (typeof fn !== "function") { throw new Error(`${fn} is not a function. Can't use as middleware`) }
       Vajra.#middlewares.push(fn);  return defaults
     }
-    const defaults = Object.freeze(
-      Object.assign({}, { use, setProperty, start }, Object.fromEntries('get__post__put__patch__delete__head__options'.split('__').map((method) => [method, (...args) => register(method, ...args)]))
-    )); return Object.assign({}, { start }, defaults)
+    const defaults = Object.freeze(Object.assign({}, { use, setProperty, start, log }, Object.fromEntries('get__post__put__patch__delete__head__options'.split('__').map((method) => [method, (...args) => register(method, ...args)])))); return Object.assign({}, { start }, defaults)
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techiev2/vajra",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Blazing-fast, zero-dependency Node.js server with routing, middleware, multipart uploads, and templating. 111 lines · ~95k req/s · ~52 MB idle.",
   "keywords": [
     "http-server",