brahma-firelight/ReadMe.md

A blazing-fast, fire-and-forget orchestrator built with Rust and JavaScript, designed for ultra-low-latency task routing, message triggering, and lightweight logic execution — all without blocking. A native rust AddOn for NodeJS, BunJS and DenoJS.

# 🌀 BRAHMA-JS
 
![Node.js](https://img.shields.io/badge/Node.js-14%2B-brightgreen?logo=node.js) ![Rust](https://img.shields.io/badge/Rust-1.0+-black?logo=rust)  
**Fire-and-Forget Orchestrator for Node.js** — built for ultra-fast request routing with a Rust backend.

---


## 🔥 Overview

**Brahma-JS** is a blazing-fast, binary-backed **fire-and-forget** orchestrator.  
It gives you a tiny, Express/Hono-like JS surface while the heavy lifting runs natively for throughput and low latency.

**Author:** [Shyam20001](https://github.com/Shyam20001)  
**License:** MIT

---


## 📦 Install

```bash
npm install brahma-firelight
```

---


## 🚀 Quick Start — Hello World (Simple & Sync)

> **Important:** **Handlers must be synchronous** (no `async`, no Promises). Brahma-JS is fire-and-forget — async handlers will throw.

```javascript
const { useBrahma, startServer, redirect } = require("brahma-firelight");

useBrahma((req) => {
  if (req.path === "/hi") {
    return {
      headers: { "Content-Type": "application/json" },
      status: 200,
      body: JSON.stringify({ message: "Hello World from Brahma-JS!" }),
    };
  }

  if (req.path === "/bye") {
    return redirect("https://example.com");
  }

  return {
    status: 404,
    body: "Route not found",
  };
});

const port = process.env.PORT || 3000;
const host = process.env.HOST || "0.0.0.0";

startServer(host, +port).then(() => {
  console.log(`🌀 Brahma-JS server running at http://${host}:${port}`);
});
```

---


## ⚠️ **SYNC-ONLY HANDLERS** (READ THIS)

- **Do not** use `async` functions for handlers.
- **Do not** return a `Promise`.
- If your handler returns a Promise, Brahma will throw:

```text
Error: BrahmaJS handler must return synchronously (no Promise).
```

This design keeps the runtime truly _fire-and-forget_ and avoids cross-runtime async traps.

---


## 🧪 Test with `curl`

```bash
# JSON GET
curl -X GET http://127.0.0.1:3000/hi

# Redirect
curl -X GET http://127.0.0.1:3000/bye -v
```

---


## ✨ Features (short)

- Native Rust backend for throughput and low latency
- Small JS API (`useBrahma`, `startServer`, `redirect`, `parseFile`)
- Binary-only distribution (drop-in .node binaries)
- Synchronous, deterministic handler model for fire-and-forget routing

---


## 🧾 License

**MIT** © [LICENSE](https://github.com/Shyam20001/rsjs/blob/master/LICENSE)

---