Skip to content

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.

ts
import { defineContext, scoped, singleton } from '@katajs-framework/core'

Signature ​

defineContext takes one argument — the registry — and returns the factory functions bound to it.

ts
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:

ts
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 ​

ts
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.

ts
const logger: Logger = {
  info: (msg, extra) => console.log(`[app] ${msg}`, extra ?? ''),
}

const slots = {
  logger: singleton(logger),
}

scoped ​

ts
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.

ts
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:

MemberTypePurpose
registryRThe literal registry, for typeof k.registry.
defineRoutebounddefineRoute — its c.get and use: know R.
defineMiddlewarebounddefineMiddleware — provides: is keyed to your scoped slots.
createAppboundcreateApp — 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:

ts
k.resolve('logger').info(`listening on :${info.port}`)
k.resolve('currentUser') // ✗ compile error — scoped slots aren't resolvable

Define 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.

ts
// 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.registry

Export 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:

ts
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:

ts
type ResolvedValue<S> =
  S extends Singleton<infer T> ? T : S extends Scoped<infer T> ? T : never

Given the context above:

ts
const log = c.get('logger') // Logger
const user = c.get('currentUser') // User
c.get('mailer') // ✗ compile error — not registered in defineContext

Scoped 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:

ts
// 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
ts
// 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.

TypeMeaning
Singleton<T>A process-lifetime slot holding a T.
Scoped<T>A per-request slot for a T, filled by middleware.
SlotSingleton<unknown> | Scoped<unknown>.
RegistryReadonly<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 ​

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