Koa Adapter

@inferdi/koa is Koa v3 middleware. It creates one request scope, exposes it as ctx.state.di, and disposes it after the Node response finishes or closes.

Install

pnpm add @inferdi/inferdi @inferdi/koa koa
pnpm add -D @types/koa

import Koa from 'koa'
import { inferdiKoa, type InferdiScopeOf } from '@inferdi/koa'

Request Scope

const root = buildRootContainer()

declare module 'koa' {
  interface DefaultState {
    di: InferdiScopeOf<typeof root>
  }
}

const app = new Koa()

app.use(inferdiKoa({
  container: root,
  setupScope: (scope, ctx) => {
    const request = scope.get('request')
    request.requestId = crypto.randomUUID()
    request.userId = ctx.get('x-user-id') || undefined
    request.ip = ctx.ip
  },
}))

app.use(async (ctx) => {
  const id = ctx.path.split('/').pop() ?? ''
  ctx.body = await ctx.state.di.get('users').profile(id)
})

Custom State Key

import type { DefaultState, ParameterizedContext } from 'koa'
import { type InferdiKoaState, type InferdiScopeOf } from '@inferdi/koa'

type AppState =
  & DefaultState
  & InferdiKoaState<InferdiScopeOf<typeof root>, 'container'>

type AppContext = ParameterizedContext<AppState>

app.use(inferdiKoa({ container: root, key: 'container' }))

app.use(async (ctx: AppContext) => {
  ctx.body = await ctx.state.container.get('users').profile('42')
})

Options

Option	Default	Description
container	required	Root container. Never disposed by this middleware.
key	'di'	Koa state key.
createScope	root.createScope()	Custom request scope creation.
setupScope	none	Hydrates the scope before downstream middleware.
disposeScope	scope.dispose()	Custom disposal.
autoDispose	true	false or predicate false transfers ownership.
onDisposeError	ctx.app.emit('error')	Cleanup failure sink.

Streaming

Normal Koa stream bodies do not need a skip. The adapter waits for finish or close.

Use skipInferdiDispose(ctx) only when application code intentionally keeps the scope beyond the HTTP response boundary, such as background work:

import { skipInferdiDispose } from '@inferdi/koa'

app.use(async (ctx) => {
  skipInferdiDispose(ctx)
  const scope = ctx.state.di

  queue.add(async () => {
    try {
      await scope.get('jobs').run()
    } finally {
      await scope.dispose()
    }
  })

  ctx.body = { status: 'queued' }
})

A downstream error always disposes the scope; successful skipped requests become application-owned.