One package for your backend, typed end to end.

Zero-dependency TypeScript for APIs, jobs, workflows, SQL, and auth - same patterns throughout. Import only what you use.

Open the docs
server.tsHover underlined code
import { Api } from "semola/api";
import {  } from "semola/queue";
import { boolean, email, object } from "semola/schema";

const  = new Queue<{ to: string }>({
  name: "emails",
  redis: redisClient,
  handler: async () => sendWelcomeEmail(job.to),
});

export const api = new ();

export const signup = api.({
  path: "/signup",
  method: "POST",
  request: { body: object({ email: () }) },
  response: { 201: object({ queued: boolean() }) },
  handler: async (c) => {
    await emails.({ to: c.req.body. });
    return c.(201, { : true });
  },
});

await api.(3000);
00TypeScriptsemola 0.6.9
PROBLEMS0

No problems in server.ts

Responses are checked against the schema too. Try breaking it.

Composition

server.ts can grow. package.json should not.

Flip on a queue, a cache, a workflow - they plug into the same defineRoute handler. Your lockfile still lists a single package.

server.ts16 lines - 1 imports
import { Api } from "semola/api";import { signupBody, signupCreated } from "./signup.schema.ts";import { emails } from "./emails.queue.ts";import { profiles } from "./profiles.cache.ts";import { onboard } from "./onboard.workflow.ts";import { accounts } from "./accounts.policy.ts";import { i18n } from "./i18n.ts";import { log } from "./logger.ts";
const api = new Api();

export const signup = api.defineRoute({
  path: "/signup",
  method: "POST",  request: { body: signupBody },
  response: { 201: signupCreated },  handler: async (c) => {    const { email, name } = await c.raw.json();    const { email, name } = c.req.body;    let message = `Welcome, ${name}!`;    if (!accounts.("signup", { plan: "free" }).allowed) {
      throw new Error("signup forbidden");
    }    await emails.({ to: email, name });    await profiles.(email, { name });    await onboard.({ email, name });    message = i18n.("welcome", { name });    log.({ event: "signup" });
    return c.json(201, { ok: true, message });
  },
});

await api.serve(3000);

Contract

Define the route once. Collect the rest for free.

Validation, handler types, a typed client, OpenAPI, and in-memory tests all come from the same defineRoute call. No second schema file to keep honest.

import { Api } from "semola/api";
import { boolean, email, object } from "semola/schema";
import { emails } from "./jobs";

export const api = new Api({
  openapi: { title: "Accounts", version: "1.0.0" },
});

export const  = api.defineRoute({
  path: "/signup",
  method: "POST",
  : "Create an account",
  tags: ["auth"],
  request: { : object({ email: email() }) },
  response: { : object({ queued: boolean() }) },
  handler: async (c) => {
    await emails.enqueue({ to: c.req.body. });
    return c.json(201, { queued: true });
  },
});
import { ApiClient } from "semola/api";
import { signup } from "./server";

const client = ApiClient({
  router: { auth: { signup } },
  baseUrl: "https://api.example.com",
});

const {  } = await client.auth.({
  : { email: "hi@semo.la" },
});

await client.auth.signup({
  body: { : "hi@semo.la" },
});
{
  "/signup": {
    "post": {
      "": "Create an account",
      "tags": ["auth"],
      "requestBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "email": { "type": "string", "": "email" }
              },
              "required": ["email"]
            }
          }
        }
      },
      "responses": {
        "201": {
          "description": "Response with status 201",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "": { "type": "boolean" }
                },
                "required": ["queued"]
              }
            }
          }
        }
      }
    }
  }
}
import { expect, test } from "bun:test";
import { api } from "./server";

test("rejects an invalid email", async () => {
  const  = await api.(
    new Request("http://localhost/signup", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ email: "nope" }),
    }),
  );

  expect(res.status).toBe(400);
  expect(await res.json()).toEqual({
    message: "email: Invalid email",
  });
});

Principles

A few things we will not compromise on.

Wrong response? Your editor complains first

Request bodies are typed - that part everyone does. Semola also types what you return. A typo in a field name dies in the editor, not in a 2am bug report.

Keep Zod. Or don't.

Slots take any Standard Schema library: Zod, Valibot, ArkType, or the built-in semola/schema. Swap later without rewriting the app.

The dependencies field is empty

On purpose. bun add semola puts one line in package.json. No transitive tree to audit, pin, or wake up for on a CVE Friday.

Pay only for what you import

semola/queue is not a back door into the ORM or the CLI. Each module is its own entry point, so unused code stays out of the process.

Elsewhere

Jobs, tables, workflows - same instincts.

Learn how one module feels and the next one is familiar. Break something on purpose and watch TypeScript catch it.

1 of 9

semola/orm

Define the table. The types come along.

One table definition drives queries, inserts, relations, and transactions on SQLite or Postgres. The migration CLI writes SQL from the same shape - no parallel schema to drift.

ORM docs

semola/queue

Enqueue it. Retries are already handled.

Jobs live in Redis. Handlers that throw get backoff retries; dead workers get their jobs reclaimed. The payload type is the same from enqueue to the handler.

Queue docs

semola/workflow

Crash mid-run. Pick up where you left off.

Each named step saves its result in Redis. If the process dies, another worker resumes and skips steps that already finished - no double charge, no blank stare.

Workflow docs

semola/cache

Cache values with a real TypeScript type

Set the value type once; every set and get is checked against it. Fixed or per-entry TTLs, plus a key prefix so namespaces stay out of each other's way.

Cache docs

semola/pubsub

Publish and subscribe on the same type

Both ends share one message shape. Rename a field and the build fails - better than a silent consumer in production.

PubSub docs

semola/policy

Auth rules you can read out loud

Allow and forbid rules match fields on your own types. Forbid always wins. No matching rule means denied - no accidental open doors.

Policy docs

semola/i18n

Misspell a key. Fail the build.

Keys and placeholders come from the default locale, so typos are type errors. Missing translations fall back at runtime instead of showing a blank string.

i18n docs

semola/errors

Handle the error branch on purpose

mightThrow turns a promise into an [error, data] tuple. Deal with the failure first; after that the compiler knows data is safe to use.

Errors docs

semola/cli

CLIs whose flags arrive already typed

Arguments and options go through any Standard Schema. By the time your action runs, the values are validated and typed - no manual argv parsing.

CLI docs

Try it

db.tsTypes check
import { createOrm, defineTable, string, uuid } from "semola/orm";

const users = defineTable({
  sqlName: "users",
  columns: {
    id: uuid("id").primaryKey().notNull(),
    email: string("email").unique().notNull(),
  },
});

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

const user = await db.users.findFirst({
  where: { email: "hi@semo.la" },
});

console.log(user?.);
import { Queue } from "semola/queue";

type EmailJob = {
  to: string;
  subject: string;
};

const  = new Queue<EmailJob>({
  name: "emails",
  redis: redisClient,
  concurrency: 4,
  retries: 3,
  handler: async () => {
    await sendEmail(data.to, data.subject);
  },
});

await emails.enqueue({ to: "hi@semo.la", subject: "Welcome" });
import { defineWorkflow } from "semola/workflow";

const fulfillOrder = defineWorkflow<{ orderId: string }>({
  name: "fulfill-order",
  redis: redisClient,
  handler: async ({ , step }) => {
    const  = await step("charge", async () => {
      return charge(input.orderId);
    });

    await step("ship", async () => {
      await ship(payment.orderId);
    });
  },
});

await fulfillOrder.start({ orderId: "ord_123" });
import { Cache } from "semola/cache";

type Session = {
  userId: string;
  role: "admin" | "member";
};

const sessions = new Cache<Session>({
  redis: redisClient,
  prefix: "session",
  ttl: (_key, ) => {
    if (session.role === "admin") return 3_600_000;

    return 60_000;
  },
});

await sessions.set("abc", { userId: "u_1", role: "member" });

const  = await sessions.get("abc");
import { PubSub } from "semola/pubsub";

type UserEvent = {
  userId: string;
  action: "login" | "logout";
};

const events = new PubSub<UserEvent>({
  subscriber: redisSubscriber,
  publisher: redisPublisher,
  channel: "user-events",
});

await events.subscribe(async () => {
  console.log(message.userId, message.action);
});

await events.publish({ userId: "123", action: "login" });
import { eq, Policy } from "semola/policy";

type Post = {
  authorId: string;
  status: "draft" | "published";
};

const posts = new Policy<Post>();

posts.allow({
  action: ["update", "delete"],
  conditions: { authorId: eq(user.id) },
});

posts.forbid({
  action: "delete",
  conditions: { status: eq("published") },
  reason: "Published posts cannot be deleted",
});

const  = posts.can("delete", post);
import { I18n } from "semola/i18n";

const i18n = new I18n({
  defaultLocale: "en",
  locales: {
    en: {
      welcome: "Welcome, {name:string}!",
      inbox: { unread: "You have {count:number} unread messages" },
    },
    it: {
      welcome: "Benvenuto, {name:string}!",
    },
  },
});

i18n.setLocale("it");

const unread = i18n.translate("inbox.unread", { : 3 });
import { mightThrow } from "semola/errors";

export const loadMe = async () => {
  const [, response] = await mightThrow(
    fetch("https://api.example.com/me"),
  );

  if (error) {
    console.error(error.message);
    return;
  }

  return .json();
};
import { CLI } from "semola/cli";
import { boolean, string } from "semola/schema";

const program = new CLI({ name: "deploy", version: "1.0.0" });

program
  .command("release")
  .argument("tag", { schema: string() })
  .option("dryRun", { schema: boolean(), aliases: ["d"] })
  .action((, ) => {
    console.log(args.tag.toUpperCase(), options.dryRun);
  });

await program.parse();

Property 'name' does not exist on type '{ id: string; email: string }'.

db.ts Ln 21, Col 19 ts(2339)

FAQ

The questions before install.

Runtimes, Redis, databases, validators, tree-shaking, and what pre-1.0 actually means for you.

Still stuck? Open an issue
What is Semola?

Semola is a TypeScript backend toolkit. Instead of installing a router, a queue, an ORM, and three helper libraries, you install one package with an empty dependencies field. Modules cover typed REST APIs with OpenAPI, Redis queues, durable workflows, SQL, auth policies, caching, i18n, and smaller utilities - each imported on its own path like semola/api or semola/queue.

How do I install it?

bun add semola. npm, pnpm, and yarn work too. Then import only the modules you need. The getting started guide builds a small typed API from scratch.

Is this a framework?

No. There is no app shell you have to live inside. You import the pieces you want, compose them in your own server.ts, and leave the rest out. It is closer to a set of libraries that share types and habits than to a framework with opinions about folders.

Does it run on Node.js?

The API module runs on Node, Deno, and Cloudflare Workers, and Redis-backed modules accept ioredis, node-redis, or Valkey GLIDE through semola/redis. The ORM uses Bun's SQL client, so it needs Bun. Schema, errors, policy, and i18n are plain TypeScript. Check each module page for what it needs.

Do I need Redis or a database on day one?

Only if you use the modules that store state. Queue, workflow, cache, and Redis pub/sub need Redis. The ORM needs SQLite or Postgres. API routes, policies, i18n, and in-process cron run with nothing extra.

Can I keep using Zod?

Yes. Anything that implements Standard Schema works - Zod, Valibot, ArkType, and the built-in semola/schema. Drop schemas into the same slots. For OpenAPI you need schemas that can emit JSON Schema; semola/schema and Zod 4 both do.

Will unused modules bloat my bundle?

No. Each module is its own entry point. Importing semola/api does not load the ORM, the CLI, or anything else. What you do not import is not there.

How stable is it?

Pre-1.0 - currently v0.6.9. APIs can still move between minor versions. Pin the version you ship with and read the release notes before you bump.

What about the license?

MIT. Commercial projects, open source, forks - all fine.

Can coding agents read the docs?

Yes. Full docs are plain text at /llms.txt and /llms-full.txt, and every docs page can copy itself as Markdown.

Install once. Import what you need.

import { Api } from "semola/api"

You do not have to adopt the whole toolkit. Start with the API, add a queue next week, leave the ORM until you need SQL.

Open the docs