Core Concepts

Before diving into API details, it helps to understand how Katman thinks about your code. There are four main ideas.

Context

Every request starts by running your context factory. This is a function you provide when creating the Katman instance. It receives the raw HTTP request and returns an object.

import { katman } from "katman"

const k = katman({
  context: (req) => ({
    db: getDB(),
    headers: Object.fromEntries(req.headers),
  }),
})

This object — called ctx — is available in every procedure and every guard. Think of it as the shared state for one request.

Guards can add to the context. If a guard returns { user }, then ctx.user becomes available in all procedures that use that guard.

Procedures

A procedure is a single API function. It takes an input, does something, and returns an output. There are three types:

See the Procedures page for how to write them.

Middleware

Middleware runs before (and sometimes after) a procedure. Katman has two kinds:

Guards run before the procedure and can add to the context:

const auth = k.guard(async (ctx) => {
  const user = await verifyToken(ctx.headers.authorization)
  if (!user) throw new KatmanError("UNAUTHORIZED")
  return { user } // added to ctx
})

Wraps run before and after, like an onion:

const timing = k.wrap(async (ctx, next) => {
  const start = Date.now()
  const result = await next()
  console.log(`Took ${Date.now() - start}ms`)
  return result
})

See the Middleware page for details and execution order.

Type inference

Katman infers types from your code. You don't write them yourself and you don't run a code generator.

When you define a procedure with a Zod schema, the client automatically knows the input type. When the procedure returns something, the client knows the return type. When a guard adds { user } to the context, the procedure knows ctx.user exists.

This works because of InferClient:

import type { InferClient } from "katman"

type Client = InferClient<typeof appRouter>
// Client.users.list: (input: { limit?: number }) => Promise<User[]>