App

import { inkan, t } from "@vxnsin/inkan";

const app = inkan({ title: "Tea Shop", version: "1.0.0" })
  .get("/hello", () => ({ hello: "world" }));

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

inkan(options) makes an app. Routes, hooks, decorations and plugins are added to it in a chain, and each one returns the app, so the type of the app grows with every route. That type is what the typed client reads.

RoutesCopy Anchor Link

app.get("/teas", () => store.all());
app.post("/teas", { body: NewTea, response: { 201: Tea } }, ({ body, reply }) => reply(201, store.add(body)));
app.put("/teas/:id", spec, handler);
app.patch("/teas/:id", spec, handler);
app.delete("/teas/:id", spec, handler);
app.all("/legacy/*", spec, handler); // GET, POST, PUT, PATCH and DELETE

One method per HTTP method: the path, the spec (optional) and the handler. all defines the same route for GET, POST, PUT, PATCH and DELETE at once. A HEAD request is answered by the GET route of its path, without the body. An OPTIONS request gets the methods the path takes. Routing has everything a spec can say.

use()Copy Anchor Link

app.use(async (ctx, next) => {
  const started = Date.now();
  await next();
  ctx.header("x-took", `${Date.now() - started}ms`);
});

Middleware for every request, before routing. On a group made with routes(), it runs for the routes of that group, after their input was checked.

onRequest(), preHandler(), onSend(), onResponse(), onProblem()Copy Anchor Link

app
  .onRequest((ctx) => {
    if (!ctx.headers.authorization) throw problem(401, "unauthorized");
  })
  .onSend((ctx, answer) => {
    answer.headers["x-frame-options"] = "DENY";
  })
  .onProblem((ctx, p) => {
    if (p.status >= 500) report(p);
  });

Hooks run for the routes of their scope, in this order:

A route with no hooks anywhere above it takes the fast path, with no hook machinery at all.

Every hook takes { order: "last" }: it then runs after every other hook of its kind on the route, wherever those were added, outermost scope first among the last ones too. For an onSend hook that changes the body's bytes, as compress does, that is where it belongs.

app.onSend((ctx, answer) => sign(answer), { order: "last" });

around()Copy Anchor Link

app.around(async (ctx, next) => {
  const t0 = performance.now();
  await next();
  metrics.observe(ctx.route!.path, performance.now() - t0);
});

Wraps the handler of every route in the scope and the scopes inside it, those defined before the call too. It runs where a route's own middleware runs (after the input is checked and the preHandler hooks), outside that middleware, and await next() runs the rest. Outer scopes' around wrap inner ones'. It is joined into each route once, before the first request, so a route pays for it only when a scope above it has one. Experimental, new in 0.8.0.

register()Copy Anchor Link

import { plugin } from "@vxnsin/inkan";

const admin = plugin((scope, options: { token: string }) => {
  scope.onRequest((ctx) => {
    if (ctx.headers.authorization !== `Bearer ${options.token}`) throw problem(401, "unauthorized");
  });
  scope.get("/stats", () => stats());
});

app.register(admin, { token: process.env.ADMIN_TOKEN! }, { prefix: "/admin" });

register(plugin, options, { prefix }): the second argument is what the plugin is handed, the third where it is mounted. A plugin gets a scope of its own: its hooks, decorations and layout reach the routes defined inside it and nothing outside. Made with plugin(fn, { shared: true }), it acts on the scope it is registered in instead, which is right for a plugin like a rate limit. Plugins run in the order they are registered; one that returns a promise holds back the ones after it, and listen() waits for all of them. A shared plugin that returns its scope hands on the types of its decorations: register() returns the app typed with them. See Writing a plugin.

decorate()Copy Anchor Link

app.decorate("db", openDatabase());
app.get("/teas", ({ db }) => db.teas.all()); // typed

Puts a value on every context of the scope, once, on the context's prototype: it costs nothing per request. A name the context already has is refused.

decorateRequest()Copy Anchor Link

app.decorateRequest("user", (ctx) => sessions.get(ctx.cookies.sid));
app.get("/me", ({ user }) => user); // typed

A value made anew for each request. The function runs the first time a request reads ctx.user, and the value is kept for the rest of that request; a request that never reads it never makes it. Names are refused as with decorate. An init that returns a promise, with { resolve: "preHandler", when }, is awaited before the handler: see async decorations. New in 0.7.0.

job()Copy Anchor Link

app.job("/exports", { body: Range, progress: Progress, result: Export }, async (job) => {
  job.progress({ done: 1, total: 2 });
  return { url: "/x.csv", rows: 2 };
});

Work that takes longer than a request, as five routes around a queue: start it, look at it, follow it as server-sent events, wait for its result, cancel it. Jobs run in this process. Jobs has the routes, the options and the limits. schedule starts one on a cron schedule, and store keeps jobs in a Store the processes share. New in 0.7.0.

ws()Copy Anchor Link

app.ws("/rooms/:room", { params: t.object({ room: t.string() }), message: Say, send: Said }, (socket, ctx) => {
  socket.on("message", (m) => {
    if (m.type === "say") void socket.send({ type: "said", text: m.text, from: ctx.params.room });
  });
});

A WebSocket route: the upgrade goes through the hooks, the security and the input checks like a GET, then the socket speaks JSON by the message and send contracts. WebSockets has the socket, the origins, the options and the close codes. New in 0.7.0.

onOperation()Copy Anchor Link

app.onOperation((op, route, components, ref) => {
  if (route.security.length) op.responses["403"] ??= { description: "Not allowed for these credentials" };
  if (route.spec.tags?.includes("billing")) {
    op.responses["402"] ??= { description: "Pay first", content: { "application/json": { schema: ref(Invoice, "Invoice") } } };
  }
});

Adds to the OpenAPI operation of every route in the scope: header parameters, answers, descriptions, details of a security scheme. It runs when the document is written, never per request, outer scopes first. Experimental.

dev, prefixCopy Anchor Link

const audit = plugin((scope) => {
  if (scope.dev) scope.get("/_audit", () => recent());
  logger.info(`audit under ${scope.prefix || "/"}`);
});

Read-only. dev is whether the app runs in development (the dev option, by default NODE_ENV is not "production"), on the app and on every scope; set it with the option. prefix is the path prefix of the scope: "" for the app, "/v1" for a plugin registered with register(p, options, { prefix: "/v1" }). New in 0.7.0.

import { joinPath } from "@vxnsin/inkan";

joinPath(scope.prefix, "/login"); // "/auth/login", one slash between the parts

joinPath(a, b) puts two paths together with one slash between them, for a plugin that writes a link or a cookie path under its own prefix. New in 0.8.0.

layout()Copy Anchor Link

app.layout((content, { title }) => html`<!doctype html><title>${title}</title><main>${content}</main>`);

How the pages of the scope look around what ctx.render() hands in. A plugin can have its own, and the closest one wins.

security()Copy Anchor Link

app.security("bearer").get("/me", ({ headers }) => me(headers.authorization));

The credentials the routes after it ask for: "bearer", "basic", { apiKey, in }, or a list of them. A request without them is a 401 before its input is read; OpenAPI and the docs page list them. Whether the credentials are good is for your hook or handler to say.

mount()Copy Anchor Link

import { routes } from "@vxnsin/inkan";

const teas = routes().get("/", list).get("/:id", spec, one);
app.mount("/teas", teas);

A group made with routes(), under a prefix, with its types: the typed client knows its routes too.

load()Copy Anchor Link

app.load(new URL("./routes", import.meta.url));

A route for every file in a folder: teas/[id].ts exporting GET is GET /teas/:id.

listen()Copy Anchor Link

await app.listen();                                  // $PORT, or 3000
await app.listen({ port: 8080, host: "127.0.0.1" });

const ac = new AbortController();
await app.listen({ port: 0, signal: ac.signal });
ac.abort(); // stops the server and the app, as SIGTERM would, without ending the process

Starts the server once every plugin has loaded. The port comes from port, then $PORT, then 3000, the host from host, then $HOST, then every interface. On SIGINT or SIGTERM it lets open requests finish, up to ten seconds. Aborting signal does the same (jobs, sockets, onClose hooks) and leaves the process running, which is what a test wants. listen(port, host) works too.

When development mode was guessed (no dev option, NODE_ENV is not "production") and the address is one other machines reach, listen warns: that is most likely a deploy without NODE_ENV=production. dev: true or a loopback host quiets it.

onListen(), onClose()Copy Anchor Link

app.onListen(() => db.connect()).onClose(() => db.end());

onListen is awaited before listen() resolves, and a throw there stops the start. onClose runs after the last request on shutdown.

fetch()Copy Anchor Link

Bun.serve({ fetch: (req, server) => app.fetch(req, { remote: server.requestIP(req)?.address }) });
Deno.serve((req, info) => app.fetch(req, { remote: info.remoteAddr.hostname }));
export default { fetch: (req: Request) => app.fetch(req) }; // serverless

The app as a web-standard handler: a Request in, a Response out.

listener, exchange(), bodyFor()Copy Anchor Link

http.createServer(app.listener).listen(3000);

listener is a plain Node (req, res) function. exchange(request) takes and gives plain values, which is all an adapter to another server needs, and bodyFor(method, url) tells such an adapter how much body a route takes, and whether it reads it itself. An adapter hands the request's httpVersion in, for ctx.httpVersion.

app.logRequest({ time: new Date().toISOString(), method, path, status: 101, ms, notes: [] });

logRequest(entry) writes one request's log line the way the app's log and logger options say, for an adapter that answers some requests itself (an upgrade, a file it serves without the app). Requests through exchange, fetch or listen are logged already. New in 0.8.0.

inject()Copy Anchor Link

const res = await app.inject<Tea>({ method: "POST", url: "/teas", body: { name: "Sencha" } });
res.status;    // 201
res.body.name; // the parsed JSON, typed as a Tea

A request straight into the app, with no port and no network: for tests. It answers { status, headers, cookies, text, body }. inject<T>() types the body; it is not checked against T.

check()Copy Anchor Link

const report = await app.check();

Runs every route's examples against the app, as inkan check does from the command line.

openapi(), routes(), sealed()Copy Anchor Link

openapi() is the OpenAPI 3.1 document, routes() every route as it was written (method, path, security, meta, spec), frozen, and sealed() how the seal went: how many contracts run on it, and which changed since.

OptionsCopy Anchor Link

app.options hands the options back, read-only: they are fixed once the app is made.