defineContext
defineContext is the single place dependencies are registered. There is no runtime IoC container and no string-keyed service locator: the registry is a plain object, and the keys you pass become the only keys c.get will accept. It is imported from the core entry point alongside the two slot constructors.
import { defineContext, scoped, singleton } from '@katajs-framework/core'Signature
defineContext takes one argument — the registry — and returns the factory functions bound to it.
function defineContext<const R extends Registry>(
registry: R,
): {
registry: R
defineMiddleware: /* bound to R */
defineRoute: /* bound to R */
createApp: /* bound to R */
resolve: <K extends SingletonKeys<R>>(key: K) => ResolvedValue<R[K]>
}The const type parameter preserves the exact literal type of the registry — each key, and whether its slot is a singleton or scoped — so that information flows into every route, middleware, and c.get call downstream.
A Registry is a read-only record of slots:
type Slot = Singleton<unknown> | Scoped<unknown>
type Registry = Readonly<Record<string, Slot>>Slot constructors
A registry value is never a bare value. It is a slot, built by one of two constructors, which tags the value with its lifetime (ADR-0004).
singleton
function singleton<T>(value: T): Singleton<T>singleton(value) holds one value for the process lifetime. Use it for things created once at boot: a database pool, a logger, a mailer, a configuration object. The value is resolved eagerly — you pass it in here, and every c.get returns that same reference.
const logger: Logger = {
info: (msg, extra) => console.log(`[app] ${msg}`, extra ?? ''),
}
const slots = {
logger: singleton(logger),
}scoped
function scoped<T>(): Scoped<T>scoped<T>() declares one value per request. It takes no argument — there is nothing to provide at registration time. The value is filled later, per request, by a middleware that declares the slot in its provides: list and sets it with c.set (see Middleware and defineMiddleware). Use it for the current user, a tenant id, or a per-request transaction.
const slots = {
currentUser: scoped<User>(),
tx: scoped<Transaction>(),
}Reading a scoped slot before it is set throws
A scoped slot has no value until the providing middleware runs. Reading one in a handler whose use: chain never fills it throws at runtime:
kata: scoped slot 'currentUser' read before being set. Did the providing middleware run?A route that reads a scoped slot must list the providing middleware in its use: chain, or register it as an app-level middleware in createApp.
The returned factory
defineContext returns five members, all bound to your registry R:
| Member | Type | Purpose |
|---|---|---|
registry | R | The literal registry, for typeof k.registry. |
defineRoute | bound | defineRoute — its c.get and use: know R. |
defineMiddleware | bound | defineMiddleware — provides: is keyed to your scoped slots. |
createApp | bound | createApp — builds the Hono app. |
resolve | <K extends SingletonKeys<R>>(key: K) => ResolvedValue<R[K]> | Read a singleton's value outside a request — boot logs, graceful-shutdown teardown. Singleton-only; throws on an unregistered or scoped key. |
resolve is the sanctioned way to reach a singleton when there is no c — at boot to log the listening port, or during shutdown to close a pool. Its SingletonKeys<R> bound rejects scoped keys at compile time, and a scoped or unregistered key also throws at runtime, because a scoped slot holds no process-lifetime value to return:
k.resolve('logger').info(`listening on :${info.port}`)
k.resolve('currentUser') // ✗ compile error — scoped slots aren't resolvableDefine the context once, in src/context.ts, then re-export the bound factory functions. The rest of the app imports them from there and inherits the types automatically — nothing else ever calls defineContext.
// src/context.ts
import { defineContext, scoped, singleton } from '@katajs-framework/core'
import type { User } from './modules/users/users.schema'
type Logger = { info: (msg: string, extra?: object) => void }
const logger: Logger = {
info: (msg, extra) => console.log(`[app] ${msg}`, extra ?? ''),
}
export const k = defineContext({
logger: singleton(logger),
currentUser: scoped<User>(),
})
export const { defineRoute, defineMiddleware, createApp } = k
export type AppRegistry = typeof k.registryExport the registry type
export type AppRegistry = typeof k.registry gives you a name for the registry shape. It is the R that parameterizes Route<R> and Middleware<R>, useful when you write a helper that is generic over any context.
How c.get is typed
c.get is the only way to read a dependency, in both route and middleware handlers. Its key parameter is constrained to keyof R, so an unregistered key is a compile error — not a runtime surprise:
get<K extends keyof R>(key: K): ResolvedValue<R[K]>The return type is unwrapped from the slot by ResolvedValue, so you get the underlying value type back, not the slot wrapper:
type ResolvedValue<S> =
S extends Singleton<infer T> ? T : S extends Scoped<infer T> ? T : neverGiven the context above:
const log = c.get('logger') // Logger
const user = c.get('currentUser') // User
c.get('mailer') // ✗ compile error — not registered in defineContextScoped keys are typed everywhere get is callable
In v1, c.get types every registered key in a handler, including scoped ones — whether the route's middleware chain actually provided a given scoped slot is a lint concern, not a type error. Reading an unprovided scoped slot still throws at runtime, as shown above. See ADR-0004.
Worked example
A context with both slot kinds, the bound factory re-exported, and a handler that reads each. Store comes from src/store.ts — shared infrastructure like this sits at the open src/ root:
// src/context.ts
import { defineContext, scoped, singleton } from '@katajs-framework/core'
import type { Store } from './store'
import { createStore } from './store'
export type CurrentUser = { id: string }
export const k = defineContext({
store: singleton<Store>(createStore()),
currentUser: scoped<CurrentUser>(),
})
export const { defineRoute, defineMiddleware, createApp } = k
export type AppRegistry = typeof k.registry// src/modules/orders/orders.route.ts
import { defineRoute } from '../../context'
import { requireUser } from '../../middlewares/auth'
import { OrderListSchema } from './orders.schema'
import { listOrders } from './orders.service'
export const list = defineRoute({
method: 'GET',
path: '/orders',
use: [requireUser], // fills the `currentUser` scoped slot
input: {},
output: OrderListSchema, // z.array(OrderSchema), declared in orders.schema.ts
handler: (c) => {
const store = c.get('store') // Store — singleton, always available
const user = c.get('currentUser') // CurrentUser — provided by requireUser
return listOrders(store, user.id)
},
})Helper types
These are exported from the core entry point for advanced use — writing a function generic over any registry, or inspecting slot kinds. You rarely need them in application code.
| Type | Meaning |
|---|---|
Singleton<T> | A process-lifetime slot holding a T. |
Scoped<T> | A per-request slot for a T, filled by middleware. |
Slot | Singleton<unknown> | Scoped<unknown>. |
Registry | Readonly<Record<string, Slot>>. |
ResolvedValue<S> | The value type a slot S resolves to. |
SingletonKeys<R> | The union of keys in R whose slot is a singleton. |
ScopedKeys<R> | The union of keys in R whose slot is scoped. |
See also
- Context and DI — the conceptual guide.
- Middleware — how scoped slots get filled.
defineMiddleware— theprovides:contract.defineRoute—c.getanduse:in a handler.createApp— assembling modules and middleware.- ADR-0004 — why DI is two slot kinds and nothing else.