⚡ Zoltraak

Ultra-fast Bun web framework with gnet-level performance.

Website • Documentation • Examples • Benchmarks

Why Zoltraak?

• ⚡ gnet-Level Performance - 120k+ req/s with 0.5ms latency
• 🛡️ Type-Safe - Full TypeScript support with excellent inference
• 🔌 Middleware & Guards - Express-style with compile-time optimization
• 🌐 WebSocket Support - First-class WebSocket integration
• ✅ Validation - Built-in Zod schema validation
• 📦 Zero Dependencies - Lean and focused

Performance

Achieving 80% of raw Bun performance with full framework features:

Simple Endpoint (/ping):
├─ Zoltraak (optimized) → 120k req/s | 0.5ms
├─ Zoltraak (standard)  → 80k req/s  | 0.8ms
└─ Elysia               → 75k req/s  | 0.9ms

Path Parameters (/users/:id):
├─ Zoltraak (optimized) → 100k req/s | 0.8ms
├─ Zoltraak (standard)  → 70k req/s  | 1.2ms
└─ Elysia               → 65k req/s  | 1.3ms

Key Optimizations:

• Context pooling (20-30% less GC pressure)
• Zero-copy responses (185x faster for static content)
• Radix tree router (O(k) vs O(n))
• Ultra-fast param extraction (2-3x faster)

See PERFORMANCE_IMPROVEMENTS_SUMMARY.md for details.

Quick Start

# Create new project
bun create zoltraak my-app
cd my-app

# Or add to existing project
bun add zoltraak

Hello World

import { Zoltraak } from 'zoltraak'

const app = new Zoltraak()

app.get('/', (ctx) => {
  return ctx.json({ message: 'Hello, Zoltraak!' })
})

app.listen(3000)

With gnet-Level Optimizations

import { Zoltraak, ZeroCopy } from 'zoltraak'

const app = new Zoltraak()

// 185x faster static responses
app.get('/ping', () => ZeroCopy.static.pong)

// Fast dynamic responses
app.get('/users/:id', (ctx) => {
  return ZeroCopy.json({
    id: ctx.params.id,
    name: 'User'
  })
})

app.listen(3000)

Features

Routing

// Basic routes
app.get('/users', getUsers)
app.post('/users', createUser)
app.put('/users/:id', updateUser)
app.delete('/users/:id', deleteUser)

// Path parameters
app.get('/users/:id/posts/:postId', (ctx) => {
  const { id, postId } = ctx.params
  return ctx.json({ id, postId })
})

// Query parameters
app.get('/search', (ctx) => {
  const query = ctx.query.get('q')
  return ctx.json({ query })
})

Guards

import { Guard } from 'zoltraak'

// Authentication guard
const authGuard: Guard = async (ctx) => {
  const token = ctx.headers.get('Authorization')
  if (!token) return false

  const user = await validateToken(token)
  ctx.state.user = user
  return true
}

// Protected route
app.get('/profile', (ctx) => {
  return ctx.json({ user: ctx.state.user })
}, [authGuard])

Middleware

import { cors } from 'zoltraak/middleware'

// CORS middleware
app.use(cors({
  origin: '*',
  credentials: true
}))

// Custom middleware
app.use(async (ctx, next) => {
  const start = performance.now()
  const response = await next()
  const duration = performance.now() - start

  console.log(`${ctx.method} ${ctx.path} - ${duration.toFixed(2)}ms`)
  return response
})

Validation

import { z } from 'zod'
import { validateBody } from 'zoltraak/validation'

const UserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
  age: z.number().min(18)
})

app.post('/users',
  async (ctx) => {
    const user = await ctx.body<z.infer<typeof UserSchema>>()
    // user is fully typed!
    return ctx.json(user)
  },
  [validateBody(UserSchema)]
)

WebSockets

app.ws('/chat', {
  open: (ws) => {
    console.log('Client connected')
  },
  message: (ws, message) => {
    // Broadcast to all clients
    ws.publish('chat', message)
  },
  close: (ws) => {
    console.log('Client disconnected')
  }
})

Documentation

• Quick Start Guide
• Performance Guide
• Architecture
• Performance Tuning
• API Reference

Examples

Check out the examples/ directory:

• basic-server.ts - Simple API server
• gnet-optimized-server.ts - Maximum performance
• todo-api/ - Full CRUD API
• realtime-chat/ - WebSocket chat app

Benchmarks

Run benchmarks:

# Micro-benchmarks (component performance)
bun run benchmarks/gnet-level-bench.ts --micro

# Full benchmarks (requires 3 terminals)
bun run benchmarks/gnet-level-bench.ts --server1
bun run benchmarks/gnet-level-bench.ts --server2
bun run benchmarks/gnet-level-bench.ts --bench

Development

# Clone repository
git clone https://github.com/yourusername/zoltraak.git
cd zoltraak

# Install dependencies
bun install

# Build
bun run build

# Run tests
bun test

# Run examples
bun run examples/gnet-optimized-server.ts

Architecture

Zoltraak is built with performance in mind:

┌─────────────────────────────────────┐
│         Application Layer           │
│  (Routes, Guards, Middleware)       │
└───────────────┬─────────────────────┘
                │
┌───────────────▼─────────────────────┐
│         Compilation Layer           │
│  (Route Compiler, Optimization)     │
└───────────────┬─────────────────────┘
                │
┌───────────────▼─────────────────────┐
│         Runtime Layer               │
│  (Context Pool, Radix Router)       │
└───────────────┬─────────────────────┘
                │
┌───────────────▼─────────────────────┐
│            Bun Server               │
└─────────────────────────────────────┘

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Credits

Built with ❤️ for the Bun community.

Inspired by:

• gnet - High-performance Go networking
• Elysia - Excellent Bun framework
• Fastify - Fast Node.js framework

Links

• Website
• npm Package
• GitHub
• Issues
• Discussions

Made with Bun 🥟