🌐 railiz

LIVE EXAMPLE

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

It’s not a full framework; it’s the engine
Railiz is the runtime layer for building your own backend architecture.

Basic

import { Railiz } from 'railiz'

const app = new Railiz()

app.get('/', (ctx) => {
  ctx.json({ hello: 'railiz' })
})

app.run(3000)

What is Railiz (in 10 seconds)

• Not a framework → no opinions forced
• Not a router → more than routing
• Not just middleware → execution engine

👉 Railiz = control + guarantees

Why railiz?

Most Node frameworks make you choose:

• Flexibility → chaos (Express)
• Speed → constraints (Fastify)
• Structure → heaviness (NestJS)

railiz removes the trade-off.

Core Features

• ⚡ 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)

Build with railiz?

• REST APIs (faster & safer than Express)
• Custom backend frameworks (like NestJS, but yours)
• High-performance microservices
• Edge / serverless handlers

Mental Model

Request
  ↓
Context
  ↓
Pipeline (middlewares)
  ↓
Router (linear | hybrid | radix | compiled)
  ↓
Handler
  ↓
Response

👉 Everything is explicit.
👉 Nothing is hidden.

Installation

npm install railiz

Quick example

import { Railiz, safeHandler } from 'railiz'

const app = new Railiz()

// Execution order is GUARANTEED
app.pipeline((p) => {
  const auth = p.use(authMiddleware)
  p.use(rateLimit).after(auth)
})

app.get('/', safeHandler(async (ctx) => {
  return {
    message: 'Hello Railiz 🚀',
    url: ctx.url,
    host: ctx.host,
    ip: ctx.ip,
    headers: ctx.headers,
  }
}))

app.get('/page404', (ctx) => {
  ctx.throw(404, 'Page not found')
})

app.createServer().listen(3000, () => {
  console.log('🚀 Server running at http://localhost:3000')
})

// app.run(3000)

Deterministic Execution

No more middleware order bugs.

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

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

auth → rateLimit → cache → db

👉 Execution order is guaranteed.
❌ No middleware order bugs
❌ No “who runs first?” confusion.

Context API

| Property / Method | Type / Usage | Description | | -------------------------------------------- | ------------------------ | -------------------------------------------------------------- | | ctx.params | Record<string, string> | URL parameters, e.g. /users/:id → { id: '123' } | | ctx.query | Record<string, string> | Query string params, e.g. /search?q=hello → { q: 'hello' } | | ctx.data.body | any | Parsed request body (JSON/form) | | ctx.state | any | Per-request storage for middleware or handler | | ctx.json<T>(data: T) | Function | Send JSON response | | ctx.text(text: string) | Function | Send plain text | | ctx.html(html: string) | Function | Send HTML response | | ctx.send(data: any) | Function | Generic send (auto-detect type) | | ctx.statusCode(code: number) | Function | Set HTTP status code | | ctx.set(name: string, value: string) | Function | Set header | | ctx.redirect(url: string, status?: number) | Function | Redirect client | | ctx.sendFile(filePath: string) | Function | Send static file | | ctx.ok<T>(data?: T) | Function | Shortcut 200 OK (JSON) | | ctx.created<T>(data?: T) | Function | Shortcut 201 Created | | ctx.accepted<T>(data?: T) | Function | Shortcut 202 Accepted | | ctx.noContent() | Function | Shortcut 204 No Content | | ctx.badRequest(msg?: string) | Function | Shortcut 400 Bad Request | | ctx.unauthorized(msg?: string) | Function | Shortcut 401 Unauthorized | | ctx.forbidden(msg?: string) | Function | Shortcut 403 Forbidden | | ctx.notFound(msg?: string) | Function | Shortcut 404 Not Found | | ctx.internalError(msg?: string) | Function | Shortcut 500 Internal Server Error |

👉 Inspired by Koa, but stricter and typed.

⚠️ TTL and expiration values are always in milliseconds (ms) Example: 60000 = 60 seconds

Routing

Railiz uses a multi-stage routing engine that automatically adapts based on the number of registered routes.

| Mode | Engine | When used | |----------|-------------------------|-----------------| | linear | simple sequential scan | < 100 routes | | hybrid | indexed + LRU cache | < 1000 routes | | compiled | precompiled matcher | > 1000 routes |

Routing is designed to be explicit, predictable, and REST-friendly. Wildcards (*) are only allowed for middleware, fallback, or proxy routes, and should be avoided in core API endpoints to prevent ambiguity.

Router Options

const app = new Railiz() // auto mode (recommended)

Or explicitly:

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

Available modes:

• linear → simple matcher (small apps, fast startup)
• radix → radix tree routing (default fast mode)
• auto → automatic engine switching based on scale
• compiled → precompiled route matcher (large-scale production)

Supported Routes

| Type | Path | Example | |--------|--------------|----------------------------------| | Static | /users | List all users | | Param | /users/:id | Get user by ID |

Route Definition

const app = new Railiz()

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

Routing Evolution

Railiz automatically upgrades its routing engine as the application scales:

• < 100 routes → linear scan (minimal overhead, fastest startup)
• < 1000 routes → hybrid engine (LRU + indexed lookup)

• 1000 routes → compiled router (precomputed match functions for maximum throughput)

Grouping

basic

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

with middleware

app.group('/admin', [authMiddleware], (r) => {
  r.get('/dashboard', (ctx) => ctx.ok({ message: 'Admin dashboard' }))
})

nested

app.group('/api', (r) => {
  r.group('/v1', (r2) => {
    r2.get('/status', (ctx) => ctx.ok({ status: 'ok' }))
  })
})

Plugin System

app.plugin((app) => {
  app.use(async (ctx, next) => {
    console.log('Custom plugin triggered', ctx.path)
    await next?.()
  })
})

You can create your own plugins for purposes such as:

• Proxy requests: forward requests to another server (reverse proxy)
• Auth / JWT: add middleware to check tokens

💡 Notes:

• Pipeline order matters: Plugins are executed in the order they are registered. Place app.plugin calls carefully to control execution sequence.
• Reusability: Plugins can be packaged and reused across multiple apps, making it easy to share common functionality like logging, auth, or proxying.

Middleware

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

Error Boundary

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

Http Error

| Case | Use | | ---------------- | -------------------- | | 4xx client error | ✅ HttpError | | 5xx system error | ❌ normal Error | | validation | ✅ HttpError(400) | | auth | ✅ HttpError(401/403) |

if (!ctx.user) {
  throw new HttpError(401, 'Unauthorized')
}

throw new HttpError(422, 'Validation failed', {
  field: 'email',
  reason: 'invalid format',
})

Presets

Built-in Presets:

• apiPreset – JSON parsing, query parser, optional CORS.
• loggerPreset – Log request → response time.
• authPreset – JWT / API key auth middleware.

Example with Presets & Dependencies:

import { Railiz } from 'railiz'
import { apiPreset, loggerPreset, authPreset, applyPresets } from 'railiz'

const app = new Railiz({ trace: true })

const presets = [
  apiPreset({ cors: true }),
  loggerPreset({ enabled: true }),
  authPreset({ strategy: 'jwt' }),
]

// Example: authPreset depends on apiPreset
presets.find(p => p.name === 'auth').dependsOn = ['api']

applyPresets(app, presets)

app.get('/profile', (ctx) => {
  ctx.ok({ user: ctx.state.user })
})

app.run(3000)

Hooks

app.on('request', (ctx) => console.log('Incoming request', ctx.path))
app.on('response', (ctx) => console.log('Response status', ctx.status))
app.on('error', (ctx, err) => console.error('Error:', err.message))

App Factory (createApp)

const { app } = createApp({
  // railizOptions: {
  //   router: 'radix',
  // },

  presets: [
    loggerPreset({ enabled: true }),
  ],

  debug: true,

  onCreate() {
    console.log('🚀 create')
  },

  onReady() {
    console.log('✅ ready')
  },
})

app.get('/hello', (ctx) => {
  return ctx.ok({ message: 'Hello Railiz' })
})


app.run(3000)
// NODE_ENV != production => 🚀 Server running at http://localhost:3000

Build your own opinionated backend in seconds.

Background Tasks

Railiz allows running tasks after the response has been sent:

app.get('/send-email', async (ctx) => {
  // Respond immediately
  ctx.ok({ message: 'Email will be sent in background' })

  // Push background task
  ctx.backgroundTasks!.push(async () => {
    await sendEmail(ctx.query.to, 'Hello from Railiz!')
    console.log(`✅ Email sent to ${ctx.query.to}`)
  })
})

• ctx.backgroundTasks is a per-request array.
• Tasks run in parallel, and errors are logged without affecting the response.
• You can push multiple tasks at once:

ctx.backgroundTasks!.push(task1, task2, task3)

DI (Dependency Injection)

Register DI

app.inject('db', () => new Database(), 'singleton')

app.inject('requestId', () => crypto.randomUUID(), 'scoped')

app.inject('cache', () => new Map(), 'transient')

app.get('/test', (ctx) => {
  const db = ctx.di.resolve('db')
  const user = await db.user.findMany()
  const requestId = ctx.di.resolve('requestId')

  return ctx.json({ requestId })
})

Scoped DI behavior

| Scope | Behavior | | --------- | -------------------- | | singleton | 1 instance app | | scoped | 1 instance / request | | transient | always create |

scoped = per request context

Adapter Support (Quick)

• Express (expressAdapter)
• Fastify (fastifyAdapter)
• Lambda (lambdaAdapter)
• Cloudflare Workers (workersAdapter)
• Bun (bunAdapter)

app.use(expressAdapter(app))
export const handler = lambdaAdapter(app)
export default workersAdapter(app)
Bun.serve(bunAdapter(app))
fastify.all('*', fastifyAdapter(app))

Ecosystem (Middleware Runtime)

app.use(errorHandler())

| Middleware / Feature | Node.js | Lambda | Edge | Notes | |------------------------|:------: |:------:|:-----:|----------------------------------------------------| | serveStatic | ❌ | ❌ | ❌ | Static assets (early exit before pipeline) | | logger | ✅ | ✅ | ✅ | Logs request lifecycle | | normalizeHeaders | ⚠️ | ⚠️ | ⚠️ | Normalizes incoming headers | | cors | ✅ | ✅ | ✅ | CORS policy | | helmet | ✅ | ✅ | ⚠️ | Security headers | | json parser | 🔁 | 🔁 | ⚠️ | Parses JSON body | | bodyParser | 🔁 | ❌ | ❌ | Parses form/urlencoded bodies | | queryParser | ✅ | ✅ | ✅ | Parses query string | | jwtAuth | ✅ | ✅ | ⚠️ | Authentication layer | | validateDynamic | ✅ | ✅ | ✅ | Request validation (headers/body/transform) | | rateLimit | ❌ | ❌ | ❌ | Traffic control (anti-abuse protection) | | timeout | ❌ | ❌ | ❌ | Aborts slow requests | | cache (memory) | ❌ | ❌ | ❌ | Local cache (not distributed-safe) | | httpResponseCache | ❌ | ❌ | ❌ | Full HTTP response caching | | session | ⚠️ | ❌ | ❌ | Stateful session storage | | cookies | ⚠️ | ⚠️ | ⚠️ | Cookie handling | | retry | ⚠️ | ⚠️ | ⚠️ | Retry transient failures | | redirect | ⚠️ | ⚠️ | ⚠️ | Redirect handling | | buffer | ❌ | ❌ | ❌ | Response buffering layer | | circuit-breaker | ⚠️ | ⚠️ | ⚠️ | Prevents cascading failures | | dedupe | ⚠️ | ⚠️ | ⚠️ | Single-flight request deduplication | | content-negotiation | ✅ | ✅ | ⚠️ | Response format negotiation | | metrics | ⚠️ | ⚠️ | ⚠️ | Observability (latency, errors, counts) | | errorHandler | ✅ | ✅ | ✅ | Global error boundary (MUST be last) |

✅ Fully supported.
⚠️ Works with limitations.
🔁 Requires hybrid/adapter implementation.
❌ Not suitable for runtime.

Middleware should be applied in order from inbound (security + parsing) → authentication + validation → traffic control → cache + business logic → resilience → response → error handler at the end.

Example

import { 
  Railiz, 
  json, 
  bodyParser, 
  logger, 
  cors, 
  rateLimit, 
  cache, 
  cookies, 
  httpResponseCache,
  helmet,  
  validateDynamic, 
  timeout, 
  retry, 
  redirect, 
  buffer, 
  errorHandler, 
  serveStatic 
} from 'railiz'

const app = new Railiz()

app.use(serveStatic('./public')) 
// serves static files (HTML, CSS, JS) with early exit

app.use(logger()) 
// logs incoming requests + responses

app.use(cors({ origin: '*' })) 
// enables cross-origin requests

app.use(helmet()) 
// adds security headers (XSS, clickjacking protection)

// --------------------
// Parsing layer
// --------------------
app.use(json()) 
// parses JSON request body

app.use(bodyParser({ json: { limit: '2mb' } })) 
// parses form/urlencoded + enforces body size limit

// --------------------
// Auth layer (MUST be here)
// --------------------
app.use(jwtAuth('mysecret', { mandatory: true })) 
// verifies JWT and blocks unauthorized requests

// --------------------
// Traffic control
// --------------------
app.use(rateLimit({ limit: 100, windowMs: 60_000 })) 
// prevents abuse by limiting requests per time window

app.use(timeout({ response: 5000, socket: 10000 })) 
// aborts slow/hanging requests

// --------------------
// Cache layer
// --------------------
app.use(cache({ ttl: 30_000 })) 
// generic cache for data/service-level results

app.use(httpResponseCache({ ttl: 60 })) 
// caches full HTTP responses per request key

// --------------------
// Reliability layer
// --------------------
app.use(retry({ limit: 2, interval: 100 })) 
// retries failed transient operations

app.use(redirect({ limit: 3, sameHost: true })) 
// handles redirects safely with limits

// --------------------
// Response processing
// --------------------
app.use(cookies({ ttl: 60 * 60 * 1000 })) 
// manages cookie storage and sending

app.use(buffer()) 
// buffers response for post-processing

// --------------------
// Error boundary (ALWAYS LAST)
// --------------------
app.use(errorHandler()) 
// catches all errors and prevents crash


// ------------------------
// Routes
// ------------------------

// Simple GET
app.get('/ping', (ctx) => ctx.ok({ message: 'pong' }))

// POST with validation
app.post(
  '/users',
  validateDynamic({
    body: (data) => {
      if (!data.name) return 'Missing name'
      if (!data.age || typeof data.age !== 'number') return 'Invalid age'
      return true
    },
  }),
  (ctx) => {
    if (ctx.response.validate?.body) {
      return ctx.badRequest(ctx.response.validate.body)
    }
    const id = Date.now()
    return ctx.created({ id, ...ctx.data.body })
  }
)

// Route with redirect
app.get('/old-route', (ctx) => ctx.redirect('/new-route'))
app.get('/new-route', (ctx) => ctx.ok({ message: 'You are redirected here!' }))

// POST that sets cookies
app.post('/login', (ctx) => {
  const { username } = ctx.data.body || {}
  if (!username) return ctx.badRequest('Missing username')

  ctx.response!.headers = ctx.response!.headers || {}
  ctx.response!.headers['Set-Cookie'] = [`user=${username}; HttpOnly; Max-Age=3600`]

  return ctx.ok({ message: `Welcome ${username}` })
})

// GET route that reads cookies
app.get('/me', (ctx) => {
  const cookies = ctx.req.headers['cookie'] || ''
  return ctx.ok({ cookies })
})

// Fallback route
app.get('/*', (ctx) => ctx.notFound('Route not found'))

// ------------------------
// Run server
// ------------------------
app.run(3000)
console.log('🚀 Railiz server running on http://localhost:3000')

security → parse → auth → rate limit → cache → business → response → error

OpenAPI

This plugin automatically generates OpenAPI 3 documentation for your Railiz app and can optionally mock API responses for rapid development, limitation (type inference partial / runtime metadata required)

Features

• Automatically collects metadata from your routes.
• Supports path parameters, query parameters, and request/response bodies.
• Exposes /openapi.json endpoint for OpenAPI 3 spec.
• Can mock API responses based on defined schemas.
• Works with both linear and radix routers.

Use

import { Railiz, openApi } from 'railiz'

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

// Register plugin with mock responses
app.plugin(openApi({ title: 'My API', version: '1.0.0', mock: true }))

// Define routes
app.get('/users/:id', async (ctx) => {
  ctx.json({ success: true, userId: ctx.params.id })
})

app.post('/login', async (ctx) => {
  ctx.json({ success: true, token: 'fake-jwt-token' })
})

// Run server
app.run(3000)

Accessing OpenAPI

Visit http://localhost:3000/openapi.json to see your API documentation.

Mock Responses

When mock: true is enabled, routes return fake data based on their response schema, allowing frontend teams to start development before the backend is fully implemented.

Cache System

Railiz provides a 3-layer caching model:

Cache Architecture

L1 (memo) → L2 (requestCache) → Plugin Cache → Origin (DB/API)

Priority

When cache layers are combined, resolution order is:

• DI cacheClient (HIGHEST)
• L1 memo()
• L2 requestCache()
• Plugin cache

L1 memo() (In-request)

Use case:

• deduplicate repeated calls in same request
• avoid redundant DB/API calls

app.get('/users/:id', async (ctx) => {
  const user = await ctx.memo(
    { id: ctx.params.id },
    () =>
      ctx.requestCache(
        { route: 'user', id: ctx.params.id },
        () => getUser(ctx.params.id),
        { ttl: 30_000 },
      ),
    { ttl: 5_000 },
  )

  return ctx.json({
    cache: ctx.state.cacheHit ?? 'MISS',
    user,
  })
})

Use case:

• deduplicate repeated calls in same request
• avoid redundant DB/API calls

L2 requestCache()

Use case:

• cache API responses
• reduce DB load
• shared across requests

app.get('/users/:id', async (ctx) => {
  const user = await ctx.requestCache(
    { route: 'user', id: ctx.params.id },
    () => getUser(ctx.params.id),
    {
      ttl: 30000, debug: true,
      // force: true,
      // FORCE REFRESH (bypass cache completely)
    }
  )

  return ctx.json({
    source: 'L2 requestCache',
    cache: ctx.state.cacheHit ?? 'MISS',
    user,
  })
})

DI Override

app.inject('cacheClient', new MemoryCache())

Plugin Cache

app.plugin(cachePlugin([new MemoryCache()]))

inject > plugin

Circuit Breaker

Protect your system from cascading failures by short-circuiting unstable services.

Basic usage

import { circuitBreaker } from 'railiz'

app.use(
  circuitBreaker({
    failureThreshold: 5,
    resetTimeout: 30_000, // ms
  })
)

Per-service isolation (recommended)

app.use(
  circuitBreaker({
    key: (ctx) => {
      if (ctx.path.startsWith('/payments')) return 'payment-service'
      if (ctx.path.startsWith('/users')) return 'user-service'
      return 'default'
    },
  })
)

⚠️ IMPORTANT:

If you don't provide a key, the circuit state is GLOBAL. One failing route can block all others. Use key to isolate circuits per service or dependency.

Each service has its own circuit state

Example with external API

app.get(
  '/payments/:id',
  circuitBreaker({
    key: () => 'payment-api',
    failureThreshold: 3,
    resetTimeout: 10_000,
  }),
  async (ctx) => {
    const data = await fetchPayment(ctx.params.id) // external call
    ctx.ok(data)
  }
)

Behavior

| State | Description | | --------- | --------------------------------- | | CLOSED | Normal operation | | OPEN | Requests are blocked (fast fail) | | HALF_OPEN | Allows 1 request to test recovery |

Flow

CLOSED --(fail x N)--> OPEN

OPEN --(after resetTimeout)--> HALF_OPEN

HALF_OPEN --(success)--> CLOSED
HALF_OPEN --(fail)--> OPEN

When circuit is OPEN

// HTTP Status: 503
{
  "message": "Service unavailable (circuit open: payment-api)"
}

Use cases

• External APIs (payment, auth, analytics)
• Microservices communication
• Database protection (when unstable)

Tip

// ❌ BAD (global breaker)
app.use(circuitBreaker())

// ✅ GOOD (isolated per dependency)
app.use(
  circuitBreaker({
    key: (ctx) => ctx.path.startsWith('/payments')
      ? 'payment-api'
      : 'default'
  })
)

Always prefer per dependency, not global

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 | ❌ weak | ✅ strong | ✅ strong | | Architecture | ✅ flexible core | ❌ unstructured | ⚠️ opinionated | ⚠️ enforced patterns | | Plugin system | 🔌 simple & explicit | ⚠️ ad-hoc | ✅ rich | ✅ DI-based | | Boilerplate | 🪶 minimal | 🪶 minimal | ⚠️ medium | ❌ high | | Learning curve | 🟢 low | 🟢 low | 🟡 medium | 🔴 high | | Use case | Engine / custom arch | Small apps / legacy | APIs / services | Enterprise apps |

💡 Takeaways:

• Express → Freedom, then chaos.
• Fastify → Structured, plugin-based.
• NestJS → Enterprise-ready, heavy, opinionated.
• Railiz → Lightweight, deterministic, full control — build your own backend architecture with guarantees.

Design Principles

• Deterministic execution > implicit magic
• Explicit routing > dynamic guessing
• Runtime control > framework opinion
• Composition over inheritance

When to Use

• Build your own backend framework
• Internal APIs
• High-performance systems
• Edge runtimes

Performance

• Radix routing: O(k)
• ~2-5x faster than Express (micro benchmarks)

When NOT to use Railiz

• You want a batteries-included framework → use NestJS
• You don’t care about execution order → use Express
• You want conventions over control → use Fastify

👉 Railiz is for engineers who want control.

Philosophy

You control:
- architecture
- data
- plugins

railiz controls:
- execution
- routing
- lifecycle

License

MIT