Express Server
Express Server
Section titled “Express Server”katanakit-js/adapters/express is an optional subpath built on
Express 5. It ships a reference server: a small,
production-shaped HTTP application you can start with one call, plus the
building blocks to wire KatanaKit into an Express app you already own.
Both express (>=5) and cors (>=2.8) are declared as optional peer
dependencies, so this subpath costs nothing unless you import it deliberately.
What the reference server provides:
- App factory —
useExpressCreate(),useExpressGetApp(),useGetApp()andappall resolve to the same process-wideApplication. - Hardened defaults — CORS allow-list read from
CORS_ORIGINS,x-powered-bydisabled, and 100 kB caps on JSON and URL-encoded bodies. - Lifecycle helpers —
useExpressStart()anduseExpressFinalize()are idempotent, so bootstrapping code can be repeated safely. - Raw body handling — the JSON parser captures the raw request buffer and
useGetRawBody()exposes it for webhook signature verification. - Capability guard —
useRequireCapability()turns auseCan()access check into 401/403 Express middleware. - Demo surface — a health check and a users router mount automatically; a products CRUD controller is exported for you to mount yourself.
| Concern | Default |
|---|---|
| CORS origins | CORS_ORIGINS (comma-separated) or ["http://localhost:3000"] |
| CORS methods | GET, POST, PUT, DELETE |
| Body limits | 100kb for JSON and URL-encoded payloads |
X-Powered-By |
disabled |
| Health check | GET /health |
| Demo users router | mounted at / |
| Error + 404 handler | registered by useExpressFinalize(), invoked by useExpressStart() |
Use the reference server for prototypes, dev servers, demos and small internal APIs where you want a running server with sane defaults in two lines and do not already have an Express app.
Mount the pieces in an existing app when you already run Express: import
only what you need — useRequireCapability(), useGetRawBody(), the products
controller handlers — and skip useExpressCreate() / useExpressStart() so the
demo users router, the automatic /health route and the global 404 never enter
your middleware stack. The caveat: the factory and lifecycle exports share a
module-level singleton, so you cannot build a second independent reference
server in the same process.
Quick example
Section titled “Quick example”import { useExpressStart } from "katanakit-js/adapters/express";
// Finalizes error/404 handling and listens on http://localhost:3000useExpressStart();The server answers immediately:
curl http://localhost:3000/health# {"status":"ok","timestamp":"2026-10-05T12:00:00.000Z"}
curl http://localhost:3000/# {"message":"Get all users"}Pass a port and host when the defaults do not fit:
useExpressStart(8080, "0.0.0.0"); // all interfaces, custom portLifecycle
Section titled “Lifecycle”The adapter keeps three process-wide flags: whether the app was created,
whether error handling was finalized, and whether the server was started.
Every lifecycle call checks its flag first, so useExpressCreate() →
useExpressFinalize() → useExpressStart() is safe to call from more than one
module. The intended order is: create, mount your routers, finalize, start —
useExpressStart() performs the last two steps for you.
useExpressStart(port?, host?)
Section titled “useExpressStart(port?, host?)”const useExpressStart: (port?: number, host?: string) => void;| Parameter | Type | Default | Description |
|---|---|---|---|
port |
number |
3000 |
Port passed to app.listen(). |
host |
string |
"localhost" |
Interface to bind. Loopback only by default. |
Starting is idempotent: the first call sets the started flag, finalizes
error handling, resolves the app and calls app.listen(). When the socket is
listening, the log line Server running on http://<host>:<port> is emitted
through useLogger. Subsequent calls are no-ops, even with different
arguments — whoever starts first wins.
import { useExpressStart } from "katanakit-js/adapters/express";
const port = Number(process.env.PORT ?? 3000);const host = process.env.HOST ?? "localhost";
useExpressStart(port, host);Edge cases:
- No stop or restart. The function returns
voidand discards the underlyinghttp.Server; there is nouseStop(). Stop the process instead. - Binding.
localhostaccepts connections only from the same machine. Containers and PaaS runtimes usually need"0.0.0.0". - Occupied port. No
'error'listener is attached to the server, soEADDRINUSEsurfaces as an unhandled error event — the process crashes rather than receiving a rejected promise. - Random port.
useExpressStart(0)lets the OS pick a port, but the log line prints the literal0, so you cannot discover the assigned port from the adapter.
Real use case — container deployment: read PORT and HOST from the
environment, start once at the top of your entry file, and let the platform
handle restarts.
useStart(port?, host?)
Section titled “useStart(port?, host?)”const useStart: typeof useExpressStart;A shorter alias re-exported from app.ts (export const useStart = useExpressStart). It is the same function reference, so behavior, defaults and
idempotency are identical; pick the name that reads best next to the app
proxy.
import { app, useStart } from "katanakit-js/adapters/express";
app.get("/ping", (_request, response) => response.json({ pong: true }));useStart(3000);Real use case — one-file scripts: app plus useStart keeps route
registration and boot in a single module without importing the longer names.
useExpressFinalize()
Section titled “useExpressFinalize()”const useExpressFinalize: () => void;Registers the two terminal middlewares, in order:
- a global error handler that logs
Unhandled error:with the error object and responds500 { "error": "Internal Server Error" }; - a 404 catch-all that responds
404 { "error": "Not Found" }.
Express runs middleware in registration order, so finalize after mounting
every router; otherwise the 404 catch-all shadows the routes you add later.
useExpressStart() calls it automatically; call it yourself when you want the
error/404 behavior without listening. It is idempotent, but the finalized
flag latches — finalizing too early permanently shadows anything mounted
afterwards in that process.
import { useExpressCreate, useExpressFinalize,} from "katanakit-js/adapters/express";
const app = useExpressCreate();
app.get("/reports", (_request, response) => response.json({ reports: [] }));
// 404 catch-all goes last — then hand `app` to a test runner or an external// HTTP server without starting one here.useExpressFinalize();Real use case — integration tests: build the app, mount the router under
test, finalize, and pass the app to supertest without binding a real port.
The 401/403/404/500 responses you assert on are exactly the reference server’s.
App factory
Section titled “App factory”All four factory exports resolve to the same Application. The first call
builds it, and building applies the full default stack in this order: CORS,
x-powered-by disabled, JSON parser (with raw-body capture), URL-encoded
parser, GET /health, and the demo users router mounted at /. The error
handler and 404 are not part of creation — they only arrive with
useExpressFinalize().
useExpressCreate()
Section titled “useExpressCreate()”const useExpressCreate: () => Application;Returns the existing app when one was already created; otherwise creates an
express() instance, applies the default middleware stack and mounts the
health check plus the demo router. Idempotent — later calls return the same
object. Mount your own routers on the returned app before finalizing or
starting.
import { useExpressCreate, useExpressStart,} from "katanakit-js/adapters/express";
const app = useExpressCreate();
app.use("/products", productsRouter); // your router
useExpressStart(3000); // finalizes first, then listensEdge cases:
CORS_ORIGINSis split on commas, trimmed and filtered. When the variable is unset the fallback is["http://localhost:3000"]; when it is set but empty, the result is an empty allow-list (no fallback), so cross-origin browser requests receive no CORS headers.- Cross-origin
PATCHis not advertised by the CORS config; onlyGET,POST,PUTandDELETEare listed. - The demo users router is always mounted at
/by the factory — if you need a clean root, do not use the factory; import the individual pieces instead.
Real use case — feature-router architecture: create the app once, mount
/users, /products and /webhooks routers from separate modules, then start.
useExpressGetApp()
Section titled “useExpressGetApp()”const useExpressGetApp: () => Application;Returns the app instance, creating it if needed. Behaviorally identical to
useExpressCreate() — both delegate to the same useCreate() method — but the
name documents intent: “give me the app that may already exist”. Prefer it in
middleware-heavy setup code and in tests.
import { useExpressGetApp } from "katanakit-js/adapters/express";
const app = useExpressGetApp();
app.get("/version", (_request, response) => response.json({ version: "1.0.0" }),);Real use case — a plugin module receives no arguments and still needs the
app: useExpressGetApp().use(metricsMiddleware) registers against the shared
instance without care for who created it.
useGetApp()
Section titled “useGetApp()”const useGetApp: typeof useExpressGetApp;The shorter alias, re-exported from app.ts (export const useGetApp = useExpressGetApp). Same function reference, same lazy creation, same
singleton. It exists to pair with useStart and the app proxy in compact
entry modules.
import { useGetApp, useStart } from "katanakit-js/adapters/express";
useGetApp().get("/ready", (_request, response) => response.json({ ready: true }),);useStart();Real use case — smoke-test scripts that need to register a route and boot the server with the shortest names available.
const app: Application;A lazy Proxy around the real application. Importing
katanakit-js/adapters/express has no side effects: the proxy resolves (and
therefore creates) the app on the first property access. Property reads are
forwarded to the real instance, and function properties are returned bound, so
app.get(...), app.use(...) and destructuring all work as expected.
import { app } from "katanakit-js/adapters/express";
app.get("/custom", (_request, response) => response.json({ ok: true }));Edge cases:
- The proxy is not strictly equal to the instance returned by
useGetApp()(app === useGetApp()isfalse). PreferuseGetApp()when you need the concrete reference, for example to pass it to another library that inspects it. - Calling
app.listen()directly bypasses the lifecycle: error handling is never finalized and nothing is logged. UseuseStart()/useExpressStart()instead. - Each access to a method returns a freshly bound function, which is harmless
for calls but makes
app.use === app.usefalse.
Real use case — a module that registers exactly one route and lets the
entry point decide when to start: importing app does not boot anything, so
test setups can import it freely.
Body handling
Section titled “Body handling”The factory installs two parsers:
| Content-Type | Parser | Limit | Raw body |
|---|---|---|---|
application/json |
express.json({ verify }) |
100kb |
captured on request.rawBody |
application/x-www-form-urlencoded |
express.urlencoded({ extended: true }) |
100kb |
not captured |
| anything else (multipart, text, …) | none | — | not captured |
Multipart is not handled by default (there is no multer equivalent), and body
parser failures — malformed JSON, payloads over the limit — are forwarded to
the global error handler, which always responds
500 { "error": "Internal Server Error" } regardless of the error status. To
return 400/413 instead, register your own four-argument error middleware
before calling useExpressFinalize().
useGetRawBody(request)
Section titled “useGetRawBody(request)”function useGetRawBody(request: Request): Buffer | undefined;Returns the raw request body buffer captured by the JSON parser’s verify
hook — the exact bytes the client sent, before parsing. Returns undefined
when the request did not pass through a JSON parser that writes rawBody
(URL-encoded and multipart requests, or your own app where you configured the
parser differently).
| Parameter | Type | Description |
|---|---|---|
request |
Request |
The Express request to inspect. |
Raw bytes matter for HMAC verification: re-serializing request.body with
JSON.stringify() can change key order or whitespace and invalidate the
signature. Capture the buffer and hash it as-is.
import { createHmac, timingSafeEqual } from "node:crypto";import { useExpressGetApp, useGetRawBody } from "katanakit-js/adapters/express";
const app = useExpressGetApp();
app.post("/webhooks/github", (request, response) => { const raw = useGetRawBody(request); const received = request.header("x-hub-signature-256") ?? ""; const expected = `sha256=${createHmac( "sha256", process.env.WEBHOOK_SECRET ?? "", ) .update(raw ?? Buffer.alloc(0)) .digest("hex")}`;
const valid = received.length === expected.length && timingSafeEqual(Buffer.from(received), Buffer.from(expected));
if (!valid) { response.status(401).json({ error: "Invalid signature" }); return; }
response.json({ received: true });});Edge cases:
- The buffer is
undefined— not an emptyBuffer— when no JSON body was parsed, so always guard before hashing. - The
verifyhook runs for every JSON request, including malformed payloads, but the global error handler still turns parse failures into a 500 response. - Mounting KatanaKit in an existing Express app means implementing the
verifyhook yourself if you wantuseGetRawBody()to find anything: the accessor only readsrequest.rawBody.
Real use case — GitHub, Stripe and Slack webhooks all sign the raw
payload; verify the signature before trusting request.body, then dispatch the
parsed object.
Access guard
Section titled “Access guard”useRequireCapability() builds a standard RequestHandler around the toolkit’s
access service. The adapter ships no auth provider on purpose: your callback
resolves the subject from whatever the request carries — JWT, session, API
key — and the guard maps the outcome to an API-shaped response:
| Outcome | Status | Body |
|---|---|---|
resolveSubject returns null |
401 |
{ ok: false, data: null, error: { message: "Authentication required", status: 401 } } |
useCan() returns false or throws |
403 |
{ ok: false, data: null, error: { message: "Missing capability: <capability>", status: 403 } } |
| allowed | — | calls next() |
Returning null means anonymous (401); returning a subject that lacks the
capability means authenticated but forbidden (403). The guard never
redirects — it is designed for JSON APIs.
useRequireCapability(capability, resolveSubject)
Section titled “useRequireCapability(capability, resolveSubject)”function useRequireCapability( capability: AccessCapability, resolveSubject: (request: Request) => AccessSubject | null,): RequestHandler;| Parameter | Type | Description |
|---|---|---|
capability |
AccessCapability |
Capability the route requires. |
resolveSubject |
(request) => AccessSubject | null |
Resolves the caller per request; null for anonymous. |
The subject is structural — any { id, roles } works (a Prisma row, a JWT
payload, a test fixture). AccessSubject and its companions come from the main
katanakit-js barrel:
type AccessRole = "owner" | "admin" | "editor" | "author" | "member" | "guest";
type AccessCapability = | "content:create" | "content:publish" | "content:edit:own" | "content:edit:any" | "content:delete:own" | "content:delete:any" | "conversations:use" | "conversations:moderate" | "members:manage" | "roles:assign" | "system:admin";
interface AccessSubject { id: string | number; roles: AccessRole[];}useCan() grants the capability when any of the subject’s roles provides
it, directly or by inheritance. A malformed subject or unknown role makes
useCan() throw; the guard catches that and fails closed with the 403 body —
an invalid subject never reaches your handler.
import type { Request } from "express";import type { AccessSubject } from "katanakit-js";import { useExpressGetApp, useRequireCapability,} from "katanakit-js/adapters/express";
type RequestWithSubject = Request & { subject?: AccessSubject };
const resolveSubject = (request: Request): AccessSubject | null => (request as RequestWithSubject).subject ?? null;
const app = useExpressGetApp();
app.get( "/admin/reports", useRequireCapability("system:admin", resolveSubject), (_request, response) => response.json({ reports: [] }),);Edge cases:
resolveSubjectruns on every request. Exceptions it throws are not caught by the guard and reach the global error handler as a 500, so keep it total.- Subject resolution is not
async: the callback must return a subject synchronously. Await tokens, sessions or database lookups in an earlier middleware and stash the result onrequest. - Register the guard before the route handler (or via
router.use()) — Express only runs middleware registered upstream in the chain. - A falsy subject covers both
nullandundefined, so?? nullis safe even when the property is missing.
Real use case — session middleware authenticates and attaches request.user,
then every sensitive route composes the guard with its capability:
router.delete("/posts/:id", useRequireCapability("content:delete:any", resolve), handler).
Demo controllers
Section titled “Demo controllers”products.controller.ts is an in-memory CRUD demo. A module-level
const products: ProductType[] = [] holds the records and a nextId counter
starts at 1 and only moves forward, so ids are never reused after deletion.
State lives for the lifetime of the process.
These handlers are exported but not mounted by the reference server — it
only mounts the health check and the users router. Wire them into your own
router when you want a working CRUD surface:
import { Router } from "express";import { useExpressCreateProduct, useExpressDeleteProduct, useExpressGetAllProducts, useExpressGetProductById, useExpressGetApp, useExpressUpdateProduct,} from "katanakit-js/adapters/express";
const productsRouter = Router();
productsRouter.get("/", useExpressGetAllProducts);productsRouter.get("/:id", useExpressGetProductById);productsRouter.post("/", useExpressCreateProduct);productsRouter.put("/:id", useExpressUpdateProduct);productsRouter.delete("/:id", useExpressDeleteProduct);
useExpressGetApp().use("/products", productsRouter);useExpressGetAllProducts(request, response)
Section titled “useExpressGetAllProducts(request, response)”const useExpressGetAllProducts: (request: Request, response: Response) => void;Responds 200 with the whole array, unwrapped:
[{ "id": 1, "name": "Widget", "price": 9.99 }]. Returns [] when nothing has
been created yet.
productsRouter.get("/", useExpressGetAllProducts);// GET /products → [{ "id": 1, "name": "Widget", "price": 9.99 }]Real use case — replacing the demo with a real source: keep the handler’s response shape and swap the module-level array for your Prisma query, so clients do not notice the change.
useExpressGetProductById(request, response)
Section titled “useExpressGetProductById(request, response)”const useExpressGetProductById: (request: Request, response: Response) => void;Reads request.params.id, parses it with Number.parseInt(id, 10) and finds a
matching product. On success responds 200 with the product wrapped under a
productById key; when no product matches, responds
404 { "error": "Product not found" }.
productsRouter.get("/:id", useExpressGetProductById);// GET /products/1 → { "productById": { "id": 1, "name": "Widget", "price": 9.99 } }// GET /products/999 → 404 { "error": "Product not found" }Edge cases:
- Non-numeric ids (
/products/abc) parse toNaN, never match and return 404 rather than throwing. - The wrapper key is
productById, notproduct— preserve it if you write tests against the demo.
Real use case — a typed detail endpoint: the :id param is the natural
place to authorize row-level access with useRequireCapability("content:edit:own", …)
before loading the record.
useExpressCreateProduct(request, response)
Section titled “useExpressCreateProduct(request, response)”const useExpressCreateProduct: (request: Request, response: Response) => void;Reads name and price from request.body, defaulting to "" and 0
respectively. Assigns id = nextId++, coerces price with Number() and
responds 201 with the created product.
productsRouter.post("/", useExpressCreateProduct);// POST /products { "name": "Gadget", "price": 19.99 }// → 201 { "id": 1, "name": "Gadget", "price": 19.99 }Edge cases:
POST /products {}creates{ id, name: "", price: 0 }— the defaults are applied, not rejected.- A missing or non-JSON body is treated as
{}; there is no schema validation in the demo. price: "19.99"is accepted and stored as a number;price: "abc"is stored asNaN(see the update handler for how that serializes).
Real use case — a controller skeleton: replace the array push with your
persistence call, keep the 201 contract, and add validation with a Zod schema
from katanakit-js at the boundary.
useExpressUpdateProduct(request, response)
Section titled “useExpressUpdateProduct(request, response)”const useExpressUpdateProduct: (request: Request, response: Response) => void;Finds the product by parsed :id (404 when missing) and applies partial
updates: name ?? product.name and Number(price ?? product.price). Responds
200 with the updated product.
productsRouter.put("/:id", useExpressUpdateProduct);// PUT /products/1 { "name": "Updated Widget" }// → { "id": 1, "name": "Updated Widget", "price": 9.99 }Edge cases:
nullandundefinedpreserve the current value; an empty string (name: "") overwrites because""is not nullish.priceis always coerced:"5"becomes5, while"abc"becomesNaN— andNaNserializes tonullin JSON responses.- Like the read handler, non-numeric ids fall through to the 404 branch.
Real use case — PATCH-like edits with a PUT route: clients send only the fields they changed, and the demo’s nullish coalescing gives you partial-update semantics without extra code.
useExpressDeleteProduct(request, response)
Section titled “useExpressDeleteProduct(request, response)”const useExpressDeleteProduct: (request: Request, response: Response) => void;Finds the index by parsed :id; responds 404 { "error": "Product not found" }
when absent, otherwise removes the record from the array with splice() and
responds 204 with an empty body.
productsRouter.delete("/:id", useExpressDeleteProduct);// DELETE /products/1 → 204 No Content// DELETE /products/999 → 404 { "error": "Product not found" }Edge cases:
- The
204response intentionally has no JSON body; clients should not parse it. - Deleting frees the array slot but not the id —
nextIdnever decreases, so a later create gets a fresh id.
Real use case — destructive routes are exactly where to require
content:delete:any or content:delete:own, so anonymous and under-privileged
callers are stopped before the handler runs.
router (default export)
Section titled “router (default export)”const router: Router; // default exportA minimal users router mounted at / by the reference server. It is a
placeholder for replacing with your own domain routes:
| Method | Path | Response |
|---|---|---|
GET |
/ |
{ "message": "Get all users" } |
GET |
/:id |
{ "message": "Get user by <id>" } |
POST |
/ |
{ "message": "Create a new user" } |
import { router } from "katanakit-js/adapters/express";Edge cases:
GET /healthis registered before the router, so Express matches it first and it never reachesGET /:id.- Any other single-segment
GET(for example/favicon.ico) falls into the/:iddemo branch and returns a message; replace the router for real services. - Using
useExpressCreate()always mounts it; if that conflicts with your routes, build a plain Express app and import only the pieces you need.
Real use case — scaffolding: keep the router shape as a template
(GET list, GET detail, POST create) while you grow a real API around it.
Putting it together
Section titled “Putting it together”A reference server with guarded product writes, a raw-body webhook and a subject stub:
import type { Request } from "express";import { Router } from "express";import type { AccessSubject } from "katanakit-js";import { useExpressCreateProduct, useExpressDeleteProduct, useExpressGetAllProducts, useExpressGetProductById, useExpressGetApp, useExpressStart, useExpressUpdateProduct, useGetRawBody, useRequireCapability,} from "katanakit-js/adapters/express";
type RequestWithSubject = Request & { subject?: AccessSubject };
const resolveSubject = (request: Request): AccessSubject | null => (request as RequestWithSubject).subject ?? null;
const app = useExpressGetApp();
// Demo identity — replace with JWT/session verification in production.app.use((request, _response, next) => { (request as RequestWithSubject).subject = { id: "demo", roles: ["admin"] }; next();});
const products = Router();products.get("/", useExpressGetAllProducts);products.get("/:id", useExpressGetProductById);products.post( "/", useRequireCapability("content:create", resolveSubject), useExpressCreateProduct,);products.put( "/:id", useRequireCapability("content:edit:any", resolveSubject), useExpressUpdateProduct,);products.delete( "/:id", useRequireCapability("content:delete:any", resolveSubject), useExpressDeleteProduct,);
app.use("/products", products);
app.post("/webhooks/github", (request, response) => { const raw = useGetRawBody(request); response.json({ bytes: raw?.length ?? 0 });});
useExpressStart(3000); // finalizes error/404 handling, then listensRegister routes before useExpressStart() so the 404 catch-all stays last, and
keep granular data validation inside handlers while the guard owns coarse
capability checks.
Related
Section titled “Related”- NestJS — the same
useRequireCapabilitypattern expressed as a NestCanActivateguard. - HTTP Client — call outbound APIs from your route handlers with Safe Results.
- Errors — the
{ ok, data, error }shape reused by the guard’s 401/403 bodies. - Framework Adapters — the client-side adapters that consume the API this server exposes.
- API Reference — every export on this page, generated from source.