Skip to content
leonardodipacePublic

About

⚡ Zero-dependency TypeScript toolkit for Bun backends. Typed REST APIs, Redis queues, ORM, durable workflows, caching, auth & i18n.

Topics

Resources

Stars

10 stars

Watchers

0 watching

Forks

Repository files navigation

Semola

Semola

Type-safe backend toolkit, zero dependencies

Most backends end up stitching a router, a queue, an ORM, and a validator - each with its own types. Semola is one TypeScript package instead: REST APIs with OpenAPI, Redis queues, durable workflows, SQL, auth, cache, i18n, and more. Empty dependencies field. Import only what you use (semola/api, semola/queue, semola/orm, ...).

Docs: semo.la · npm: semola · Install: bun add semola

Tests npm version Docs Bun TypeScript License

Modules

Module What it does Import
API Typed REST routes, OpenAPI, typed client semola/api
Queue Redis jobs with retries, timeouts, reclaim semola/queue
PubSub Typed channels on Redis or in memory semola/pubsub
Workflow Multi-step work that resumes after a crash semola/workflow
ORM Tables, queries, migrations for SQLite and Postgres semola/orm
Cache Typed Redis values with TTL semola/cache
Cron In-process or OS-level schedules semola/cron
Redis Use ioredis, node-redis, or Valkey GLIDE with the Redis modules semola/redis
Policy Allow / forbid auth rules semola/policy
i18n Translation keys the compiler can reject semola/i18n
Schema Built-in Standard Schema + JSON Schema semola/schema
Errors [error, data] tuples instead of try/catch nests semola/errors
Logging Prefixed loggers to console or files semola/logging
Otel OTLP traces, metrics, and logs over HTTP JSON semola/otel
CLI Commands and flags with schema validation semola/cli
Prompts Interactive terminal prompts semola/prompts
Extra Backoff retries and small helpers semola/extra

Quick start

bun add semola

# or: npm install semola

Typed API

import { Api } from "semola/api";
import { object, string } from "semola/schema";

const api = new Api();

api.defineRoute({
  path: "/hello/:name",
  method: "GET",
  request: {
    params: object({ name: string() }),
  },
  response: {
    200: object({ message: string() }),
  },
  handler: async (ctx) => {
    return ctx.json(200, { message: `Hello, ${ctx.req.params.name}!` });
  },
});

await api.serve(3000);
console.log("Server running on http://localhost:3000");

Handle Errors Without Try-Catch

import { mightThrow } from "semola/errors";

const [error, data] = await mightThrow(fetch("https://api.example.com"));

if (error) {
  console.error("Request failed:", error);
  return;
}

console.log("Success:", data);

mightThrow and mightThrowSync default their error type to Error. If a promise or function can reject or throw non-Error values, pass a custom error generic.

const [customError] = await mightThrow<never, { code: string }>(
  Promise.reject({ code: "RATE_LIMITED" }),
);

Process Background Jobs

import { Queue } from "semola/queue";

const queue = new Queue({
  name: "emails",
  redis: redisClient,
  handler: async (data) => {
    await sendEmail(data);
  },
});

await queue.enqueue({ to: "user@example.com", subject: "Hello" });

Send Real-Time Messages

import { PubSub } from "semola/pubsub";

const pubsub = new PubSub({
  subscriber: redisSubscriber,
  publisher: redisPublisher,
  channel: "notifications",
});

// Subscribe to messages
const unsubscribe = await pubsub.subscribe((message) => {
  console.log("Received:", message);
});

// Publish a message
await pubsub.publish({ userId: 123, text: "New alert!" });

await unsubscribe();

Cache Data with TTL

import { Cache } from "semola/cache";

const cache = new Cache({
  redis: redisClient,
  ttl: 3600000, // 1 hour in milliseconds
});

// Store data
await cache.set("user:123", { name: "John", age: 30 });

// Retrieve data
const user = await cache.get("user:123");
console.log(user);

Schedule Recurring Tasks

import { Cron } from "semola/cron";

const cleanup = new Cron({
  name: "daily-cleanup",
  schedule: "@daily",
  handler: async () => {
    await deleteOldLogs();
    await archiveInactiveUsers();
  }
});

cleanup.run();

Query a Database

import { createOrm, defineTable, json, string, uuid } from "semola/orm";

const users = defineTable({
  sqlName: "users",
  columns: {
    id: uuid("id").primaryKey().notNull(),
    name: string("name").notNull(),
    email: string("email").unique().notNull(),
    metadata: json<{ plan: string }>("metadata"),
  },
});

const db = createOrm({
  adapter: "sqlite",
  url: ":memory:",
  tables: { users },
});

const rows = await db.users.findMany({
  where: { name: { contains: "John" } },
  take: 10,
});

const user = await db.users.create({
  data: {
    id: "1",
    name: "John Doe",
    email: "john@example.com",
  },
});

console.log(rows, user);

Check Permissions

import { Policy, eq, has } from "semola/policy";

type User = { id: number; role: string; permissions: string[] };

const policy = new Policy<User>();

// Allow admins full access
policy.allow({
  action: ["create", "update", "delete"],
  conditions: { role: eq("admin") },
  reason: "Admins have full access",
});

// Allow users with a specific permission
policy.allow({
  action: "read",
  conditions: { permissions: has("posts:read") },
});

// Check if user can perform an action
const user: User = { id: 1, role: "admin", permissions: [] };
const result = policy.can("update", user);
console.log(result.allowed); // true

Internationalize Your App

import { I18n } from "semola/i18n";

const i18n = new I18n({
  defaultLocale: "en",
  locales: {
    en: { greeting: "Hello, {name:string}!" },
    es: { greeting: "¡Hola, {name:string}!" },
  },
});

console.log(i18n.translate("greeting", { name: "World" }));

Log your messages

import { ConsoleProvider, Logger } from "semola/logging";

const logger = new Logger("database", [new ConsoleProvider()]);
logger.info("Hello!");

Retry a function multiple times

import { createRetry } from "semola/extra";

type FriendRequest = {
  from: string;
  to: string;
};

async function sendFriendRequest(req: FriendRequest) {
  console.log(`sending from ${req.from} to ${req.to}`);
  await sender(req);
}

const callable = createRetry({
  input: async () => {
    await sendFriendRequest({ from: "user1@gmail.com", to: "user2@gmail.com" });
  },
  maxRetries: 3,
  onFailedAttempt: () => {
    console.log(`Resending the request`);
  },
  onError: ({ error }) => {
    console.error(error.message);
  },
});

const outcome = await callable();
if (outcome.ok) {
  console.log("sent");
}

📦 Installation

# Install core package (validation built in via semola/schema)
bun add semola

# Optional: another Standard Schema library (Zod, Valibot, ArkType)
# bun add zod

🔥 Why Semola?

Semola (pronounced "seh-MOH-lah") is the batteries-included toolkit TypeScript developers have been waiting for.

Stop piecing together half-baked solutions from npm. Stop wrestling with type definitions that lie to you. Semola gives you everything you need to build production-ready Bun applications with confidence: type-safe APIs, background job queues, real-time messaging, caching, authorization, and error handling. All working together seamlessly out of the box.

API Framework Comparison

Semola Express Fastify Hono Elysia
Bun Native ✅ ❌ ⚠️ ✅ ✅
Zero Dependencies ✅ ❌ ❌ ✅ ❌
Type-Safe Routes ✅ ❌ ⚠️ ✅ ✅
Auto OpenAPI ✅ ❌ ⚠️ ⚠️ ⚠️
Tree-Shakeable ✅ ❌ ❌ ✅ ✅
Standard Schema ✅ ❌ ❌ ⚠️ ✅

Performance Benchmarks

Semola API is the fastest API framework for Bun.

Framework Avg Req/Sec Latency Avg (ms) vs Semola
Semola 40,050 1.88 baseline
Elysia 37,185 2.13 1.1x slower
Hono 34,611 2.31 1.2x slower
Fastify 26,330 3.70 1.5x slower
Express 20,031 5.02 2x slower
NestJS 16,118 6.21 2.5x slower

Higher is better for req/sec, lower is better for latency.

What Makes Semola Different

  • 🎯 Bun-first: Engineered for Bun's performance. The API module also runs on Node, Deno, and Cloudflare Workers; Cron and CronDistributed run on Node too.
  • 🧩 Modular by design: Import only what you need. Your bundle stays lean.
  • 🔒 Type safety that actually works: From request validation to response serialization, TypeScript catches errors before they hit production.
  • 📄 Documentation writes itself: Auto-generated OpenAPI specs from your code. No more stale docs.
  • 🚫 Error handling reimagined: No more try-catch spaghetti. Clean result tuples that compose beautifully.
  • ⚡ Schema validation freedom: Use semola/schema, Zod, Valibot, ArkType, or any Standard Schema library. Your choice.
  • 🔋 Batteries included: Everything you need in one cohesive toolkit. No 50 dependencies to audit.

📖 Documentation

Full docs: https://semo.la · Getting started: https://semo.la/docs/getting-started

Run locally: bun run docs:dev (http://localhost:3000).

  • API Framework - Type-safe REST API framework with OpenAPI
  • Queue - Redis-backed job queue with timeouts & concurrency
  • PubSub - Type-safe Redis pub/sub
  • Cron - In-memory and OS cron scheduler for periodic task execution
  • Workflow - Durable and resumable workflows with retries and hooks
  • Redis - Adapters for ioredis, iovalkey, node-redis, and Valkey GLIDE
  • Policy - Policy-based authorization
  • i18n - Type-safe internationalization
  • Cache - Redis cache wrapper with TTL
  • Schema - Standard Schema validation with JSON Schema output
  • Errors - Result-based error handling
  • Logging - Logging utility
  • Otel - Zero-dependency OTLP/HTTP JSON traces, metrics, and logs
  • Prompts - Interactive CLI prompts
  • CLI - Non-interactive CLI builder
  • ORM - Type-safe data layer with SQLite and Postgres
  • Extra - A collection of tiny utilities

🛠️ Development

# Install dependencies
bun install

# Run docs site
bun run docs:dev

# Run tests
bun test

# Build package
bun run build

# Lint & typecheck
bun check

📝 Publishing

Pushing a new package.json version to main publishes to npm (with provenance) and creates a GitHub Release.

Stable (latest):

bun pm version <major|minor|patch>
git push

Beta (beta dist-tag + GitHub Pre-release). Any version with a - suffix (e.g. 0.7.0-beta.0) uses this path:

bun pm version preminor --preid beta   # first beta of next minor (0.6.6 → 0.7.0-beta.0)
bun pm version prerelease --preid beta # later betas (0.7.0-beta.0 → 0.7.0-beta.1)
git push

Install a beta with bun add semola@beta. Promote to stable with a clean version (no suffix), e.g. bun pm version 0.7.0. That moves npm latest; the beta dist-tag stays on the last prerelease until the next beta. Stable GitHub release notes cover everything since the last stable tag (betas included).

About

⚡ Zero-dependency TypeScript toolkit for Bun backends. Typed REST APIs, Redis queues, ORM, durable workflows, caching, auth & i18n.

Topics

Resources

Stars

10 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages