nifra-api

Nifra: typed APIs and the typed client

Fetch exact signatures with nifra_types and compiling snippets with nifra_example before writing anything non-trivial. This skill is the shape of the thing, not a substitute for either.

Two ways to declare routes

server() - chainable, inference-first. Reach for this by default.

import { server } from "@nifrajs/core/server"
import { t } from "@nifrajs/schema"

export const app = server()
  .get("/notes", () => listNotes())
  .get("/notes/:id", { params: t.object({ id: t.string() }) }, (c) => getNote(c.params.id))
  .post("/notes", { body: t.object({ title: t.string(), body: t.string() }) }, (c) =>
    createNote(c.body),
  )

defineContract - the same routes as a standalone, versionable artifact when the contract must be published, shared across repos, or evolved independently of the handlers. Ask nifra_docs for the contract page before choosing it; do not reach for it just because a route feels important.

Validation belongs in the route options

body, query, params, headers, and response all take a schema. Anything that fails becomes a structured 422 before your handler runs, so a handler never defensively re-checks its own input.

@nifrajs/schema (t) is TypeBox-backed and gives you JSON Schema and OpenAPI for free. Any Standard Schema library works too - Zod and Valibot slot into the same option with no adapter.

import { z } from "zod"
app.post("/users", { body: z.object({ email: z.string().email() }) }, (c) => c.body.email)

Typed search params: declare query and read c.query typed. Do not parse new URL(c.req.url) by hand.

The client never throws

const res = await api.notes({ id }).get()
if (!res.ok) return handle(res.error)   // transport and HTTP failures both land here
res.data                                // typed from the route's return type

Three consequences worth internalising:

• No try/catch around a client call for HTTP or network failure. Only genuinely exceptional code throws.
• The client is browser-safe. It carries the server's types, never its code.
• Changing a route's shape breaks every caller at compile time. That is the feature. Fix the callers; do not widen the type to silence tsc.