🌐 railiz

LIVE EXAMPLE

🚀 A deterministic, high-performance HTTP engine for modern TypeScript backends.

Not a framework. Not a wrapper.
Railiz is the runtime layer for building your own backend architecture.

Why railiz?

Most Node frameworks force trade-offs:

• Express → flexible but chaotic
• Fastify → fast but opinionated
• NestJS → powerful but heavy

👉 railiz gives you control without chaos.

Advantages

• ⚡ Radix-tree routing (O(k))
• 🧠 Deterministic middleware execution (no order bugs)
• 🧩 Pipeline-based orchestration (not just chain)
• 🔌 Plugin-first architecture
• 🪶 Ultra-lightweight core
• 📝 Full TypeScript inference (params, context)
• 🌐 Framework-agnostic (works anywhere)

Mental Model

Request
  ↓
Context (ctx)
  ↓
Middleware Pipeline
  ↓
Router (Radix / Linear)
  ↓
Handler
  ↓
Response

👉 Everything is explicit.
👉 Nothing is hidden.

Installation

npm install railiz

Quick Example

import { Railiz } from 'railiz'

const app = new Railiz()

app.get('/users/:id', async (ctx) => {
  ctx.ok({
    id: ctx.params.id
  })
})

app.createServer().listen(3000, () => {
  console.log('Server running on')
})

Context API

ctx.params
ctx.query
ctx.data.body
ctx.state

ctx.ok()
ctx.badRequest()
ctx.notFound()
ctx.redirect()

👉 Inspired by Koa, but stricter and typed.

Routing

Default: Radix (fast)

const app = new Railiz()

Optional: Linear (simple)

const app = new Railiz({ router: 'linear' })

Supported

• Static → /users
• Params → /users/:id
• Wildcard → /*
• Regex → /^\/api\/.*/

Route Definition

// linear
const app = new Railiz({ router: 'linear' })

app.route({
  method: 'GET',
  path: '/users/:id',
  middleware: [auth],
  handler: async (ctx) => {
    return ctx.ok({ id: ctx.params.id })
  },
})

Grouping

app.group('/api', (r) => {
  r.get('/health', ctx => ctx.ok())
})

Plugin System

app.plugin((app) => {
  app.use(logger())
})

Middleware Example

app.use(async (ctx, next) => {
  console.log(ctx.path)
  await next()
})

Killer Feature: Deterministic Pipeline

app.pipeline((p) => {
  const auth = p.use(authMiddleware)
  const db = p.use(dbMiddleware)

  p.use(cache).before(db)
  p.use(rateLimit).after(auth)
})

👉 Execution order is guaranteed:

auth → rateLimit → cache → db

❌ No middleware order bugs
❌ No “who runs first?” confusion

Error Boundary

app.route({
  method: 'GET',
  path: '/boom',
  handler: async () => {
    throw new Error('boom')
  },
  errorBoundary: async (ctx) => {
    ctx.status = 500
    ctx.body = 'Handled error'
  },
})

Ecosystem (Recommended)

app
  .use(errorHandler())
  .use(logger())
  .use(cors())
  .use(bodyParser())
  .use(jwtAuth('secret'))
  .use(rateLimit())
  .use(serveStatic('public'))

Recommended Plugins

| Plugin | Purpose | | ---------------- | ------------------------------ | | json() | Parse JSON request bodies | | cors() | Handle CORS | | logger() | Log requests and responses | | jwtAuth() | JWT-based authentication | | session() | Manage user sessions | | bodyParser() | Parse form or URL-encoded data | | multipart() | Handle file uploads | | queryParser() | Parse query parameters | | rateLimit() | Prevent abuse / rate limiting | | serveStatic() | Serve static files | | validate() | Validate request data | | errorHandler() | Catch and format errors |

Architecture

Node HTTP
   ↓
Railiz Core
   ↓
Router (Radix / Linear)
   ↓
Context
   ↓
Handlers

Comparison

railiz is the only one here that gives you deterministic middleware execution.

| Criteria | railiz | Express.js | Fastify | NestJS | | ------------------- | --------------------- | -------------------- | ---------------- | ---------------------- | | Core concept | Execution engine | Minimal framework | Web framework | Full framework | | Abstraction level | 🔥 Low (full control) | Low | Medium | High | | Middleware model | ✅ deterministic | ❌ implicit order | ⚠️ plugin-based | ⚠️ decorator-based | | Routing performance | ⚡ Radix O(k) | ❌ Linear scan | ⚡ Optimized | ⚡ (Fastify under hood) | | Type safety | ✅ strong TS | ❌ weak | ✅ strong | ✅ strong | | Architecture | 🧠 flexible core | ❌ unstructured | ⚠️ opinionated | ⚠️ enforced patterns | | Plugin system | 🔌 simple & explicit | ⚠️ ad-hoc | ✅ rich ecosystem | ✅ DI-based system | | Boilerplate | 🪶 minimal | 🪶 minimal | ⚠️ medium | ❌ high | | Learning curve | 🟢 low | 🟢 low | 🟡 medium | 🔴 high | | Use case | Engine / custom arch | Small apps / legacy | APIs / services | Enterprise apps |

vs Express

• ❌ implicit flow
• ❌ weak typing
• ❌ middleware chaos

👉 railiz fixes all.

vs Fastify

• Fastify = structured framework
• Railiz = execution engine

👉 railiz gives lower-level control

vs NestJS

• Nest = enterprise framework
• Railiz = core runtime

👉 Build your own Nest-like system on top.

When to Use

• Build your own backend framework
• Microservices / internal APIs
• High-performance systems
• Edge runtimes

When NOT to Use

• Need batteries-included framework
• Want built-in ORM / DI / validation

Philosophy

You control:
- architecture
- data
- plugins

railiz controls:
- execution
- routing
- lifecycle

License

MIT