Oku

A minimal, opinionated framework built on top of Oak. Zero magic, explicit over implicit.

Philosophy

• KISS — Simple solutions over clever abstractions
• YAGNI — No speculative features
• DRY — Consolidate, don't duplicate
• Explicit — No hidden behavior

Packages

Package	Description
@r3rc/oku-core	App, router, error handling, validation helpers
@r3rc/oku-middleware	CORS, rate limit, security headers, logging, etc.
@r3rc/oku-jwt	JWT token creation and verification
@r3rc/oku-identity	Identity/auth context utilities

Quick Start

bun add @r3rc/oku-core @r3rc/oku-middleware

import {
    createApp,
    createRouter,
    errorHandler,
    validateBody,
    Status
} from "@r3rc/oku-core";
import {
    cors,
    requestId,
    requestLogger,
    secureHeaders
} from "@r3rc/oku-middleware";
import * as v from "valibot";

const app = createApp();
const router = createRouter();

const CreateUserSchema = v.object({
    email: v.pipe(v.string(), v.email()),
    name: v.pipe(v.string(), v.minLength(2))
});

router.post("/users", async (ctx) => {
    const body = await validateBody(ctx, CreateUserSchema);
    ctx.response.status = Status.Created;
    ctx.response.body = { id: "123", ...body };
});

app.use(errorHandler());
app.use(requestId());
app.use(secureHeaders());
app.use(cors());
app.use(requestLogger());
app.use(router.routes());
app.use(router.allowedMethods());

await app.start({ port: 3000 });

Features

Core

• createApp() — Oak app with graceful shutdown
• createRouter() — Oak router
• errorHandler() — Catches HttpError, ValiError, Oak errors
• HttpError — Standard error factories with codes
• validateBody/Query/Params/Headers() — Valibot validation helpers
• defineContext() — AsyncLocalStorage-based context
• logger — Simple colored logger

Middleware

• secureHeaders() — Security headers (OWASP)
• cors() — CORS with Vary header support
• rateLimit() — Request rate limiting
• requestId() — Request ID generation
• requestLogger() — Request logging
• timeout() — Request timeout
• bodyLimit() — Body size limit
• etag() — ETag for optimistic concurrency
• healthCheck() — Health endpoint

Error Format

All errors follow a consistent format:

{
    "code": "USER_NOT_FOUND",
    "message": "User not found",
    "field": "id"
}

Validation errors include details:

{
    "code": "VALIDATION_FAILED",
    "message": "Validation failed",
    "details": [
        {
            "code": "INVALID_EMAIL",
            "field": "email",
            "message": "Invalid email"
        }
    ]
}

License

MIT