Skip to content

API reference ​

Kata ships one package, @katajs-framework/core, with three import paths and one binary. Nothing is re-exported from Hono — the public surface is exactly what the tables below list, derived from the package's own entry points.

ImportPurpose
@katajs-framework/coreCore: the context factory, slot constructors, the error envelope, built-in middleware, and every public type.
@katajs-framework/core/jwtStateless JWT primitives plus the jwtAuth middleware and authorization guards.
@katajs-framework/core/nodeNode-only gracefulShutdown for draining a server on SIGTERM / SIGINT.
kata (bin)The CLI: kata init scaffolds a full app, kata new adds a module, kata verify runs the lint rules.
ts
import { defineContext, scoped, singleton } from '@katajs-framework/core'
import { jwtAuth, requireRole, signJwt } from '@katajs-framework/core/jwt'
import { gracefulShutdown } from '@katajs-framework/core/node'

The split is deliberate: @katajs-framework/core is runtime-neutral and runs wherever Hono runs (Node, Bun, Deno, edge), @katajs-framework/core/jwt is the only module that touches hono/jwt, and @katajs-framework/core/node is the only module that touches node:process — so an edge build that imports @katajs-framework/core never pulls in Node internals.

Peer dependencies ​

Kata declares two peer dependencies. Install them alongside @katajs-framework/core; it bundles neither.

json
{
  "peerDependencies": {
    "hono": "^4",
    "zod": "^3"
  }
}
PeerRangeUsed for
hono^4The router, context, runtime adapters, and the typed RPC client (hc).
zod^3Every input / output schema and the claims schemas in @katajs-framework/core/jwt.

@katajs-framework/core — core ​

Values:

ExportKindPurpose
defineContextfunctionThe single DI registry. Takes a registry of slots and returns { registry, defineRoute, defineMiddleware, createApp }, all bound to it.
singletonfunctionsingleton(value) — declare a process-lifetime slot holding value.
scopedfunctionscoped<T>() — declare a per-request slot of type T, filled by a middleware.
corsfunctionBuilt-in CORS middleware.
secureHeadersfunctionBuilt-in security-headers middleware.
bodyLimitfunctionBuilt-in request-body size limit middleware.
fromHonoTransformfunctionAdapt a response-transforming Hono middleware (compress, etag) so it can rewrite kata's final response body.
DEFAULT_MAX_BODY_SIZEconstThe default byte cap bodyLimit enforces when no maxBytes is given.
buildErrorBodyfunctionBuild the unified error envelope (ADR-0008) as a plain object — { error, message, issues? }.
formatZodIssuesfunctionConvert a ZodError into the FieldIssue[] shape used in error envelopes.
serializeErrorfunctionFlatten an unhandled throw into a SerializedError — the shape Kata's own logger.error calls receive under extra.err.
ErrorBodySchemaZod schemaZod schema for the error envelope; declare it behind a 4xx/5xx status in an output map.
FieldIssueSchemaZod schemaZod schema for one structured field issue; composes ErrorBodySchema.
REQUEST_ID_HEADERconstThe header (x-request-id) Kata reads an inbound correlation id from and echoes back.

Types:

ExportPurpose
AppConfigThe object createApp accepts (modules, middlewares?, requestLogging?, outputValidation?).
RouteA route value produced by defineRoute.
ModuleA record of named routes — what an import * as of a *.route.ts file yields.
MiddlewareA middleware value produced by defineMiddleware.
MiddlewareContextThe c passed to a middleware handler (get, set, header, json, error, raw, requestId).
RouteContextThe c passed to a route handler (get, input, json, error, raw, requestId).
HttpMethodThe supported methods: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'.
InputSchemasThe input shape: { params?, query?, body?, headers? } of Zod schemas.
InferInputz.infer of an InputSchemas, as exposed on c.input.
OutputSpecA route's output: a single Zod schema or an OutputMap.
OutputMapA status-code → Zod schema map, e.g. { 200: X, 404: Y }.
SuccessOutputThe 200 body type a handler may return as a plain value.
RouteHandlerReturnWhat a handler may return: SuccessOutput or a Response.
RegistryThe registry type defineContext accepts — a record of Slots.
SlotA Singleton<unknown> or Scoped<unknown>.
SingletonA singleton slot type.
ScopedA scoped slot type.
SingletonKeysThe singleton keys of a registry.
ScopedKeysThe scoped keys of a registry — the only keys a middleware may provides/set.
ResolvedValueThe value type a slot resolves to via c.get.
SlotValue<R, K>ResolvedValue<R[K]> for a scoped key K — the same projection c.get uses, and what @katajs-framework/core/jwt's guard derives authorize's parameter from.
LoggerThe structured logger shape a logger singleton may satisfy for per-request logging. extra.err arrives pre-flattened as a SerializedError, never a raw Error.
SerializedErrorThe plain-data mirror of an Error — { name, message, stack?, cause?, errors? } — that logger.error receives under extra.err.
LogExtraThe extra payload type of every Logger method: open (Record<string, unknown>), with the reserved err key typed as SerializedError.
RequestLogFieldsThe per-request record requestLogging passes as extra: { requestId, method, path, status, durationMs }. See createApp.
OutputValidationMode'strict' | 'log' | 'off' — how an output-schema mismatch is handled (ADR-0009).
ErrorBodyThe error-envelope object type: { error, message, issues? }.
ErrorExtraThe optional extras for c.error / buildErrorBody: { status?, issues? }.
FieldIssueOne structured field error: { path, message, code, expected?, received? }.
FieldIssuesRecord<string, FieldIssue[]>, keyed by input source.
KataAppThe parametric Hono app type createApp returns — export type AppType = KataApp<typeof modules> powers the RPC client.
RpcModuleThe wire-relevant projection of a module used by the RPC type bridge.
ModulesToHonoSchemaThe Hono RPC Schema derived from a modules tuple.

Built-in middleware option types — CorsOptions, SecureHeadersOptions, and BodyLimitOptions — are also exported. See Middleware for their fields.

@katajs-framework/core/jwt — auth ​

Values:

ExportKindPurpose
signJwtfunctionsignJwt(claims, options) — sign a claims object into a compact JWT. Stamps iat; options set the registered claims (exp, nbf, iss, aud, sub).
verifyJwtfunctionverifyJwt(token, options) — verify signature + time claims, then parse the payload through options.claims. Returns a Result, never throws.
jwtAuthfunctionBuild a middleware handler that reads Authorization: Bearer <token>, verifies it, and writes the claims (or a resolved user) into a scoped slot. Wrap with defineMiddleware({ provides: [...] }).
guardfunctionBuild an authorization guard handler that reads an already-provided slot and rejects with a 403 envelope when authorize returns false.
requireRolefunctionSugar over guard: allow only when the slot value's role is (one of) the given role(s).
requireClaimfunctionSugar over guard: allow only when the slot value's claim at key equals expected (or passes the given predicate).

Types:

ExportPurpose
JwtAlgorithmThe supported signing algorithms (HS*, RS*, PS*, ES*, EdDSA).
SignOptionsOptions for signJwt: secret, alg?, expiresInSeconds?, notBeforeSeconds?, issuer?, audience?, subject?.
VerifyOptionsOptions for verifyJwt: secret, claims, alg?, issuer?, audience?.
JwtVerifyResultThe verifyJwt result: { ok: true, claims } or { ok: false, error }.
JwtErrorA verify failure: { code, message, issues? }.
JwtErrorCode'invalid_token' | 'expired' | 'claims_mismatch'.
JwtAuthOptionsOptions for jwtAuth: secret, claims, slot?, alg?, issuer?, audience?, header?, resolve?.
GuardOptionsOptions for guard: slot?, authorize, code?, message?.

You own the login flow

@katajs-framework/core/jwt gives you signing, verification, the auth middleware, and guards. Password hashing, the user store, the login route, and refresh tokens stay yours. See the Authentication cookbook for the full pattern.

@katajs-framework/core/node — Node runtime ​

Values:

ExportKindPurpose
gracefulShutdownfunctiongracefulShutdown(server, options) — trap termination signals, stop accepting connections, drain in-flight requests, then run onClose.

Types:

ExportPurpose
ServerTypeThe node:http / node:http2 server handle @hono/node-server's serve() returns.
GracefulShutdownOptionsOptions for gracefulShutdown: onClose, signals? (default ['SIGTERM', 'SIGINT']), timeoutMs? (default 10_000).

gracefulShutdown takes the server, not the app: the app is the request handler, the server owns the socket that must be close()d to drain. Opt in from main.ts — createApp installs no signal handlers.

kata — the bin ​

The package installs a kata binary with three commands: kata init scaffolds a project, kata new <domain> adds a module, and kata verify runs the lint rules.

bash
kata init [dir] [options]
OptionPurpose
-C, --cwd <dir>Base directory to resolve [dir] against. Defaults to the current directory.
--minimalWrite only the harness configs — no app (for existing projects).
-f, --forceOverwrite existing source files (never the manifests/configs).
-h, --helpPrint usage and exit.

By default kata init writes a complete, runnable app: the harness (.claude / .codex / .agents + AGENTS.md / CLAUDE.md / lefthook.yml), the canonical src/ layout with two example modules, and — only if absent — package.json, tsconfig.json, and the lint configs. See The CLI for the full walkthrough.

Reference pages ​

Open-source — license TBD. Built on Hono + Zod.