@inferdi/koa 4.0.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InferDI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# @inferdi/koa
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/inferdi/inferdi/main/assets/logo.png" alt="InferDI" width="150" height="150" />
+
+[![JSR](https://jsr.io/badges/@inferdi/koa)](https://jsr.io/@inferdi/koa)
+[![npm version](https://img.shields.io/npm/v/@inferdi/koa)](https://www.npmjs.com/package/@inferdi/koa)
+![License](https://img.shields.io/npm/l/@inferdi/koa.svg)
+
+Koa request-scope middleware for [InferDI](https://github.com/inferdi/inferdi).
+</div>
+
+> **Part of the [InferDI](https://github.com/inferdi/inferdi) project** — a
+> zero-dependency, decorator-free, strongly typed DI container for TypeScript.
+> Core package: [`@inferdi/inferdi`](https://www.npmjs.com/package/@inferdi/inferdi)
+> ([JSR](https://jsr.io/@inferdi/inferdi)).
+
+This middleware wires InferDI into Koa v3 without decorators, reflection,
+controller scanning, router patching, `app.context` mutation, or handler
+parameter injection. Your application still builds an explicit InferDI graph and
+resolves services with `.get(key)` — the adapter only manages the per-request
+scope.
+
+## Table of Contents
+
+- [Install](#install)
+- [Request Scope](#request-scope)
+- [Options](#options)
+- [Streaming](#streaming)
+- [API](#api)
+- [Related](#related)
+
+## Install
+
+```bash
+pnpm add @inferdi/inferdi @inferdi/koa koa
+pnpm add -D @types/koa
+# or
+deno add jsr:@inferdi/inferdi jsr:@inferdi/koa npm:koa
+```
+
+```ts
+import Koa from 'koa'
+import { inferdiKoa } from '@inferdi/koa'
+```
+
+Koa publishes JavaScript and keeps TypeScript declarations in `@types/koa`.
+`@inferdi/koa` lists that package as an optional peer so TypeScript consumers
+can keep Koa's own context types in their application dependency graph.
+
+## Request Scope
+
+The middleware creates one InferDI scope per request, exposes it as
+`ctx.state.di`, and disposes it after the underlying Node response finishes or
+the connection closes.
+
+```ts
+import Koa from 'koa'
+import { inferdiKoa, type InferdiScopeOf } from '@inferdi/koa'
+import { buildRootContainer } from './container.js'
+
+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)
+})
+```
+
+For a custom state key, pass `key` and publish that key in your Koa state type:
+
+```ts
+import type { DefaultState, ParameterizedContext } from 'koa'
+import {
+  inferdiKoa,
+  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')
+})
+```
+
+The package does not globally augment Koa state with `any`, `unknown`, or a base
+container. You own the concrete state type through declaration merging or local
+Koa generics.
+
+## Options
+
+```ts
+app.use(inferdiKoa({
+  container: root,
+  createScope: (root, ctx) => root.createScope(),
+  setupScope: (scope, ctx) => {},
+  disposeScope: (scope, ctx) => scope.dispose(),
+  autoDispose: true,
+  onDisposeError: (error, ctx) => {
+    ctx.app.emit('error', error, ctx)
+  },
+}))
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `container` | — | **Required.** The root container. Must structurally provide `createScope()`. The root is never disposed by this middleware. |
+| `key` | `'di'` | Koa `ctx.state` key used to expose the request scope. |
+| `createScope` | `root.createScope()` | Overrides how a request scope is created. May be async. |
+| `setupScope` | — | Hydrates the scope before it is exposed to downstream middleware. May be async. |
+| `disposeScope` | `scope.dispose()` | Overrides request-scope disposal. May be async. |
+| `autoDispose` | `true` | Set to `false`, or return `false`, when application code owns disposal. |
+| `onDisposeError` | — | Optional sink for cleanup failures. Returning normally marks the cleanup error as handled. |
+
+If `setupScope` fails after a scope has been created, the middleware disposes
+that half-built scope before rethrowing. If setup cleanup also fails, the
+failure is surfaced as an `AggregateError`.
+
+Response-completion cleanup failures happen after Koa's `await next()` promise
+chain. By default they are emitted through `ctx.app.emit('error', error, ctx)`
+and swallowed so an already-completed response is not corrupted. If
+`onDisposeError` throws or rejects, the adapter emits an `AggregateError`
+containing both the original cleanup error and the handler error.
+
+## Streaming
+
+Normal Koa stream bodies do not need a special skip. When `ctx.body` is a Node
+stream, Koa pipes it through `ctx.res`, and this middleware waits for the
+response `finish` or `close` event before disposing the scope.
+
+Use `skipInferdiDispose(ctx)` only when application code intentionally keeps the
+scope beyond the HTTP response boundary:
+
+```ts
+import { skipInferdiDispose } from '@inferdi/koa'
+
+app.use(async (ctx) => {
+  if (ctx.path !== '/background') return
+
+  skipInferdiDispose(ctx)
+  const scope = ctx.state.di
+
+  queue.add(async () => {
+    try {
+      await scope.get('jobs').run()
+    } finally {
+      await scope.dispose()
+    }
+  })
+
+  ctx.body = { status: 'queued' }
+})
+```
+
+If an application sets `ctx.respond = false` and writes to `ctx.res` manually,
+the adapter still relies on `finish` or `close`. If the response is never ended
+or closed, no middleware can know when to dispose the request scope.
+
+## API
+
+```ts
+export type MaybePromise<T> = T | Promise<T>
+
+export interface InferdiScope {
+  dispose(): MaybePromise<void>
+}
+
+export interface InferdiRoot<Scope extends InferdiScope = InferdiScope> {
+  createScope(): Scope
+}
+
+export type InferdiScopeOf<Root extends InferdiRoot> =
+  ReturnType<Root['createScope']>
+
+export type InferdiKoaState<
+  Scope extends InferdiScope,
+  Key extends string = 'di',
+> = { [P in Key]: Scope }
+
+export type InferdiKoaContext<StateT, ContextT, Scope, Key> =
+  ParameterizedContext<StateT & InferdiKoaState<Scope, Key>, ContextT>
+
+export interface InferdiKoaOptions<Root, StateT, ContextT, Key, Scope> {
+  /* ... */
+}
+
+export function inferdiKoa(options: InferdiKoaOptions): Middleware
+export function skipInferdiDispose(context: Context): void
+```
+
+## Related
+
+| Package | JSR | npm | Description |
+| --- | --- | --- | --- |
+| [`@inferdi/inferdi`](https://github.com/inferdi/inferdi/tree/main/packages/inferdi) | [JSR](https://jsr.io/@inferdi/inferdi) | [npm](https://www.npmjs.com/package/@inferdi/inferdi) | Core DI container — zero-dependency, decorator-free, strongly typed |
+| [`@inferdi/fastify`](https://github.com/inferdi/inferdi/tree/main/packages/fastify) | [JSR](https://jsr.io/@inferdi/fastify) | [npm](https://www.npmjs.com/package/@inferdi/fastify) | Fastify v5 request-scope adapter |
+| [`@inferdi/hono`](https://github.com/inferdi/inferdi/tree/main/packages/hono) | [JSR](https://jsr.io/@inferdi/hono) | [npm](https://www.npmjs.com/package/@inferdi/hono) | Hono request-scope middleware |
+| [`@inferdi/koa`](https://github.com/inferdi/inferdi/tree/main/packages/koa) | [JSR](https://jsr.io/@inferdi/koa) | [npm](https://www.npmjs.com/package/@inferdi/koa) | Koa v3 request-scope middleware |
+| [`@inferdi/elysia`](https://github.com/inferdi/inferdi/tree/main/packages/elysia) | [JSR](https://jsr.io/@inferdi/elysia) | [npm](https://www.npmjs.com/package/@inferdi/elysia) | Elysia request-scope plugin |
+
+The project repository lives at [inferdi/inferdi](https://github.com/inferdi/inferdi). This adapter targets [Koa](https://koajs.com) v3.

package/dist/index.cjs

@@ -0,0 +1,167 @@
+'use strict';
+
+// src/index.ts
+var skippedContexts = /* @__PURE__ */ new WeakSet();
+function isPromiseLike(value) {
+  return value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+function cleanupError(errors) {
+  if (errors.length === 1) return errors[0];
+  return new AggregateError(errors, "InferDI Koa request cleanup failed");
+}
+function throwCollected(errors) {
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  throw new AggregateError(errors, "InferDI Koa request lifecycle failed");
+}
+function emitAppError(error, context) {
+  try {
+    context.app.emit("error", error, context);
+  } catch {
+  }
+}
+function emitUnhandledCleanupErrors(errors, context) {
+  if (errors.length === 0) return;
+  emitAppError(cleanupError(errors), context);
+}
+function handleCleanupError(error, context, onDisposeError, errors) {
+  if (onDisposeError === void 0) {
+    errors.push(error);
+    return;
+  }
+  try {
+    const handling = onDisposeError(error, context);
+    if (isPromiseLike(handling)) {
+      return handling.then(void 0, (handlerError) => {
+        errors.push(error);
+        errors.push(handlerError);
+      });
+    }
+  } catch (handlerError) {
+    errors.push(error);
+    errors.push(handlerError);
+  }
+}
+function disposeWithErrors(scope, context, disposeScope, onDisposeError, errors) {
+  try {
+    const disposing = disposeScope(scope, context);
+    if (isPromiseLike(disposing)) {
+      return disposing.then(
+        void 0,
+        (error) => handleCleanupError(
+          error,
+          context,
+          onDisposeError,
+          errors
+        )
+      );
+    }
+  } catch (error) {
+    return handleCleanupError(error, context, onDisposeError, errors);
+  }
+}
+async function disposeAfterSetupFailure(scope, context, setupError, disposeScope, onDisposeError) {
+  const errors = [setupError];
+  const disposing = disposeWithErrors(
+    scope,
+    context,
+    disposeScope,
+    onDisposeError,
+    errors
+  );
+  await disposing;
+  throwCollected(errors);
+}
+function skipInferdiDispose(context) {
+  skippedContexts.add(context);
+}
+function inferdiKoa(options) {
+  const root = options.container;
+  const key = options.key ?? "di";
+  const createScope = options.createScope ?? ((root2) => root2.createScope());
+  const setupScope = options.setupScope;
+  const disposeScope = options.disposeScope ?? ((scope) => scope.dispose());
+  const autoDispose = options.autoDispose;
+  const onDisposeError = options.onDisposeError;
+  return async function inferdiKoaMiddleware(context, next) {
+    const setupContext = context;
+    const typedContext = context;
+    const scopeResult = createScope(root, setupContext);
+    const scope = isPromiseLike(scopeResult) ? await scopeResult : scopeResult;
+    typedContext.state[key] = scope;
+    if (setupScope !== void 0) {
+      try {
+        const setupResult = setupScope(scope, setupContext);
+        if (isPromiseLike(setupResult)) {
+          await setupResult;
+        }
+      } catch (error) {
+        skippedContexts.delete(context);
+        await disposeAfterSetupFailure(
+          scope,
+          typedContext,
+          error,
+          disposeScope,
+          onDisposeError
+        );
+      }
+    }
+    let disposed = false;
+    const response = context.res;
+    const runCleanup = async () => {
+      if (disposed) return;
+      disposed = true;
+      const skipped = skippedContexts.delete(context);
+      if (skipped) return;
+      const errors = [];
+      let shouldDispose = autoDispose !== false;
+      if (typeof autoDispose === "function") {
+        try {
+          const autoDisposeResult = autoDispose(typedContext);
+          shouldDispose = isPromiseLike(autoDisposeResult) ? await autoDisposeResult !== false : autoDisposeResult !== false;
+        } catch (error) {
+          shouldDispose = true;
+          const handling = handleCleanupError(
+            error,
+            typedContext,
+            onDisposeError,
+            errors
+          );
+          if (isPromiseLike(handling)) {
+            await handling;
+          }
+        }
+      }
+      if (shouldDispose) {
+        const disposing = disposeWithErrors(
+          scope,
+          typedContext,
+          disposeScope,
+          onDisposeError,
+          errors
+        );
+        if (isPromiseLike(disposing)) {
+          await disposing;
+        }
+      }
+      emitUnhandledCleanupErrors(errors, context);
+    };
+    const onComplete = () => {
+      response.removeListener("finish", onComplete);
+      response.removeListener("close", onComplete);
+      void runCleanup().then(void 0, (error) => {
+        emitAppError(error, context);
+      });
+    };
+    response.on("finish", onComplete);
+    response.on("close", onComplete);
+    if (response.destroyed) onComplete();
+    await next();
+  };
+}
+
+exports.inferdiKoa = inferdiKoa;
+exports.skipInferdiDispose = skipInferdiDispose;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["root"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Koa v3 request-scope middleware for InferDI.\n *\n * Creates one InferDI scope per Koa request, exposes it through `ctx.state`,\n * and disposes it from the underlying Node response completion events. The\n * package is lifecycle glue only: no decorators, reflection, route scanning,\n * controller layer, or handler parameter injection.\n *\n * @example\n * ```ts\n * import Koa from 'koa'\n * import { inferdiKoa, type InferdiScopeOf } from '@inferdi/koa'\n *\n * const root = buildRootContainer()\n *\n * declare module 'koa' {\n *   interface DefaultState {\n *     di: InferdiScopeOf<typeof root>\n *   }\n * }\n *\n * const app = new Koa()\n * app.use(inferdiKoa({ container: root }))\n *\n * app.use(async (ctx) => {\n *   ctx.body = await ctx.state.di.get('users').profile('42')\n * })\n * ```\n *\n * @module\n */\n\nimport type {\n  Context,\n  DefaultContext,\n  DefaultState,\n  Middleware,\n  ParameterizedContext,\n} from 'koa'\n\n/**\n * A value of type `T` or a promise resolving to it. Used by scope hooks so they\n * accept both synchronous and asynchronous implementations.\n *\n * @template T - The resolved value type.\n */\nexport type MaybePromise<T> = T | Promise<T>\n\n/**\n * Minimal structural contract for a disposable InferDI request scope. Any\n * `Container` instance satisfies it.\n */\nexport interface InferdiScope {\n  /**\n   * Releases everything the scope owns. InferDI's `Container.dispose()` is\n   * idempotent; custom scope implementations should preserve that behavior.\n   */\n  dispose(): MaybePromise<void>\n}\n\n/**\n * Structural contract for the root container handed to the middleware.\n *\n * @template Scope - The per-request scope type produced by `createScope()`.\n */\nexport interface InferdiRoot<Scope extends InferdiScope = InferdiScope> {\n  /** Opens a fresh request scope. Called once per request. */\n  createScope(): Scope\n}\n\n/**\n * Extracts the request-scope type created by a root container.\n *\n * @template Root - A structural root container with `createScope()`.\n */\nexport type InferdiScopeOf<Root extends InferdiRoot> =\n  ReturnType<Root['createScope']>\n\n/**\n * Koa state fragment that exposes a concrete scope under a state key.\n *\n * @template Scope - The scope exposed on `ctx.state`.\n * @template Key   - The Koa state key. Defaults to `'di'`.\n */\nexport type InferdiKoaState<\n  Scope extends InferdiScope,\n  Key extends string = 'di',\n> = {\n  [P in Key]: Scope\n}\n\n/**\n * Koa context with a concrete InferDI request scope present on `ctx.state`.\n *\n * @template StateT  - Existing Koa state type.\n * @template ContextT - Existing Koa context extension type.\n * @template Scope   - The scope exposed on `ctx.state`.\n * @template Key     - The Koa state key. Defaults to `'di'`.\n */\nexport type InferdiKoaContext<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string = 'di',\n> = ParameterizedContext<\n  StateT & InferdiKoaState<Scope, Key>,\n  ContextT\n>\n\n/**\n * Options for {@link inferdiKoa}.\n *\n * @template Root    - The root container type.\n * @template StateT  - Existing Koa state available to setup hooks.\n * @template ContextT - Existing Koa context extensions available to hooks.\n * @template Key     - The `ctx.state` key.\n * @template Scope   - The per-request scope type.\n */\nexport interface InferdiKoaOptions<\n  Root extends InferdiRoot,\n  StateT = DefaultState,\n  ContextT = DefaultContext,\n  Key extends string = 'di',\n  Scope extends InferdiScope = InferdiScopeOf<Root>,\n> {\n  /** The root container. It is never disposed by this middleware. */\n  readonly container: Root\n  /** Koa `ctx.state` key. Defaults to `'di'`. */\n  readonly key?: Key\n  /**\n   * Overrides how a request scope is created. Defaults to\n   * `root.createScope()`. May be async.\n   */\n  readonly createScope?: (\n    root: Root,\n    context: ParameterizedContext<StateT, ContextT>,\n  ) => MaybePromise<Scope>\n  /**\n   * Optional hook to hydrate the freshly created scope before downstream\n   * middleware can read it from `ctx.state`.\n   */\n  readonly setupScope?: (\n    scope: Scope,\n    context: ParameterizedContext<StateT, ContextT>,\n  ) => MaybePromise<void>\n  /**\n   * Overrides request-scope disposal. Defaults to `scope.dispose()`.\n   */\n  readonly disposeScope?: (\n    scope: Scope,\n    context: InferdiKoaContext<StateT, ContextT, Scope, Key>,\n  ) => MaybePromise<void>\n  /**\n   * Controls whether the middleware disposes the request scope after response\n   * completion. Returning `false` transfers disposal responsibility to\n   * application code.\n   */\n  readonly autoDispose?:\n    | boolean\n    | ((\n        context: InferdiKoaContext<StateT, ContextT, Scope, Key>,\n      ) => MaybePromise<boolean>)\n  /**\n   * Optional sink for cleanup failures. Returning normally marks the cleanup\n   * error as handled; omitted failures are emitted through `ctx.app`.\n   */\n  readonly onDisposeError?: (\n    error: unknown,\n    context: InferdiKoaContext<StateT, ContextT, Scope, Key>,\n  ) => MaybePromise<void>\n}\n\ntype TypedContext<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string,\n> = InferdiKoaContext<StateT, ContextT, Scope, Key>\n\nconst skippedContexts = new WeakSet<Context>()\n\nfunction isPromiseLike<T>(value: T | PromiseLike<T>): value is PromiseLike<T> {\n  return (\n    value !== null &&\n    (typeof value === 'object' || typeof value === 'function') &&\n    typeof (value as { then?: unknown }).then === 'function'\n  )\n}\n\nfunction cleanupError(errors: unknown[]): unknown {\n  if (errors.length === 1) return errors[0]\n\n  return new AggregateError(errors, 'InferDI Koa request cleanup failed')\n}\n\nfunction throwCollected(errors: unknown[]): never {\n  if (errors.length === 1) {\n    throw errors[0]\n  }\n\n  throw new AggregateError(errors, 'InferDI Koa request lifecycle failed')\n}\n\nfunction emitAppError(error: unknown, context: Context): void {\n  try {\n    context.app.emit('error', error, context)\n  } catch {\n    // Response cleanup must not fail because application error reporting failed.\n  }\n}\n\nfunction emitUnhandledCleanupErrors(\n  errors: unknown[],\n  context: Context,\n): void {\n  if (errors.length === 0) return\n\n  emitAppError(cleanupError(errors), context)\n}\n\nfunction handleCleanupError<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string,\n>(\n  error: unknown,\n  context: TypedContext<StateT, ContextT, Scope, Key>,\n  onDisposeError:\n    | ((\n        error: unknown,\n        context: TypedContext<StateT, ContextT, Scope, Key>,\n      ) => MaybePromise<void>)\n    | undefined,\n  errors: unknown[],\n): void | PromiseLike<void> {\n  if (onDisposeError === undefined) {\n    errors.push(error)\n    return\n  }\n\n  try {\n    const handling = onDisposeError(error, context)\n    if (isPromiseLike(handling)) {\n      return handling.then(undefined, (handlerError) => {\n        errors.push(error)\n        errors.push(handlerError)\n      })\n    }\n  } catch (handlerError) {\n    errors.push(error)\n    errors.push(handlerError)\n  }\n}\n\nfunction disposeWithErrors<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string,\n>(\n  scope: Scope,\n  context: TypedContext<StateT, ContextT, Scope, Key>,\n  disposeScope: (\n    scope: Scope,\n    context: TypedContext<StateT, ContextT, Scope, Key>,\n  ) => MaybePromise<void>,\n  onDisposeError:\n    | ((\n        error: unknown,\n        context: TypedContext<StateT, ContextT, Scope, Key>,\n      ) => MaybePromise<void>)\n    | undefined,\n  errors: unknown[],\n): void | PromiseLike<void> {\n  try {\n    const disposing = disposeScope(scope, context)\n    if (isPromiseLike(disposing)) {\n      return disposing.then(\n        undefined,\n        (error) => handleCleanupError(\n          error,\n          context,\n          onDisposeError,\n          errors,\n        ),\n      )\n    }\n  } catch (error) {\n    return handleCleanupError(error, context, onDisposeError, errors)\n  }\n}\n\nasync function disposeAfterSetupFailure<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string,\n>(\n  scope: Scope,\n  context: TypedContext<StateT, ContextT, Scope, Key>,\n  setupError: unknown,\n  disposeScope: (\n    scope: Scope,\n    context: TypedContext<StateT, ContextT, Scope, Key>,\n  ) => MaybePromise<void>,\n  onDisposeError:\n    | ((\n        error: unknown,\n        context: TypedContext<StateT, ContextT, Scope, Key>,\n      ) => MaybePromise<void>)\n    | undefined,\n): Promise<never> {\n  const errors = [setupError]\n  const disposing = disposeWithErrors(\n    scope,\n    context,\n    disposeScope,\n    onDisposeError,\n    errors,\n  )\n\n  await disposing\n  throwCollected(errors)\n}\n\n/**\n * Marks the current Koa request scope as manually owned by application code.\n *\n * Koa stream responses normally do not need this: the middleware waits for the\n * underlying Node response `finish` / `close` events. Use this only when a\n * route intentionally keeps the scope beyond the HTTP response boundary, such\n * as background work that will dispose the scope later.\n *\n * @param context - The current Koa context.\n */\nexport function skipInferdiDispose(context: Context): void {\n  skippedContexts.add(context)\n}\n\n/**\n * Creates Koa middleware that opens one InferDI request scope per request and\n * exposes it as `ctx.state.di`.\n *\n * @template Root    - The root container type.\n * @template StateT  - Existing Koa state visible in setup hooks.\n * @template ContextT - Existing Koa context extensions visible in hooks.\n * @template Scope   - The request scope type.\n */\nexport function inferdiKoa<\n  Root extends InferdiRoot,\n  StateT = DefaultState,\n  ContextT = DefaultContext,\n  Scope extends InferdiScope = InferdiScopeOf<Root>,\n>(\n  options: Omit<\n    InferdiKoaOptions<Root, StateT, ContextT, 'di', Scope>,\n    'key'\n  > & {\n    readonly key?: 'di'\n  },\n): Middleware<StateT & InferdiKoaState<Scope, 'di'>, ContextT>\n\n/**\n * Creates Koa middleware that opens one InferDI request scope per request and\n * exposes it under a custom `ctx.state` key.\n *\n * @template Root    - The root container type.\n * @template StateT  - Existing Koa state visible in setup hooks.\n * @template ContextT - Existing Koa context extensions visible in hooks.\n * @template Key     - The Koa state key.\n * @template Scope   - The request scope type.\n */\nexport function inferdiKoa<\n  Root extends InferdiRoot,\n  StateT = DefaultState,\n  ContextT = DefaultContext,\n  Key extends string = string,\n  Scope extends InferdiScope = InferdiScopeOf<Root>,\n>(\n  options: InferdiKoaOptions<Root, StateT, ContextT, Key, Scope> & {\n    readonly key: Key\n  },\n): Middleware<StateT & InferdiKoaState<Scope, Key>, ContextT>\n\nexport function inferdiKoa<\n  Root extends InferdiRoot,\n  StateT = DefaultState,\n  ContextT = DefaultContext,\n  Key extends string = string,\n  Scope extends InferdiScope = InferdiScopeOf<Root>,\n>(\n  options: InferdiKoaOptions<Root, StateT, ContextT, Key, Scope>,\n): Middleware<StateT & InferdiKoaState<Scope, Key>, ContextT> {\n  const root = options.container\n  const key = (options.key ?? 'di') as Key\n  const createScope =\n    options.createScope ??\n    ((root: Root) => root.createScope() as Scope)\n  const setupScope = options.setupScope\n  const disposeScope =\n    options.disposeScope ??\n    ((scope: Scope) => scope.dispose())\n  const autoDispose = options.autoDispose\n  const onDisposeError = options.onDisposeError\n\n  return async function inferdiKoaMiddleware(context, next) {\n    const setupContext = context as ParameterizedContext<StateT, ContextT>\n    const typedContext = context as TypedContext<\n      StateT,\n      ContextT,\n      Scope,\n      Key\n    >\n    const scopeResult = createScope(root, setupContext)\n    const scope = isPromiseLike(scopeResult)\n      ? await scopeResult\n      : scopeResult\n\n    // Expose the scope before `setupScope` so the setup-failure disposal hooks\n    // (`disposeScope` / `onDisposeError`) see the same `ctx.state[key]` their\n    // typed context promises. Nothing downstream runs until `next()`, so a\n    // half-built scope is never observable outside cleanup.\n    ;(typedContext.state as InferdiKoaState<Scope, Key>)[key] = scope\n\n    if (setupScope !== undefined) {\n      try {\n        const setupResult = setupScope(scope, setupContext)\n        if (isPromiseLike(setupResult)) {\n          await setupResult\n        }\n      } catch (error) {\n        skippedContexts.delete(context)\n        await disposeAfterSetupFailure(\n          scope,\n          typedContext,\n          error,\n          disposeScope,\n          onDisposeError,\n        )\n      }\n    }\n\n    let disposed = false\n    const response = context.res\n\n    const runCleanup = async () => {\n      if (disposed) return\n\n      disposed = true\n      const skipped = skippedContexts.delete(context)\n      if (skipped) return\n\n      const errors: unknown[] = []\n      let shouldDispose = autoDispose !== false\n\n      if (typeof autoDispose === 'function') {\n        try {\n          const autoDisposeResult = autoDispose(typedContext)\n          shouldDispose = isPromiseLike(autoDisposeResult)\n            ? await autoDisposeResult !== false\n            : autoDisposeResult !== false\n        } catch (error) {\n          shouldDispose = true\n          const handling = handleCleanupError(\n            error,\n            typedContext,\n            onDisposeError,\n            errors,\n          )\n          if (isPromiseLike(handling)) {\n            await handling\n          }\n        }\n      }\n\n      if (shouldDispose) {\n        const disposing = disposeWithErrors(\n          scope,\n          typedContext,\n          disposeScope,\n          onDisposeError,\n          errors,\n        )\n        if (isPromiseLike(disposing)) {\n          await disposing\n        }\n      }\n\n      emitUnhandledCleanupErrors(errors, context)\n    }\n\n    // One shared completion handler, attached with `on` rather than `once`: it\n    // removes both listeners on the first event, so each request avoids the two\n    // per-listener `once` wrapper allocations, while `runCleanup`'s `disposed`\n    // flag keeps it idempotent. `finish` = response written; `close` =\n    // connection closed before completion.\n    const onComplete = () => {\n      response.removeListener('finish', onComplete)\n      response.removeListener('close', onComplete)\n      // `runCleanup` handles lifecycle errors itself; this is a final bug guard.\n      /* v8 ignore next 3 */\n      void runCleanup().then(undefined, (error) => {\n        emitAppError(error, context)\n      })\n    }\n\n    response.on('finish', onComplete)\n    response.on('close', onComplete)\n\n    // An async `createScope` / `setupScope` can yield the event loop long enough\n    // for the client to disconnect. If `close` already fired during that await,\n    // the listeners above missed it; `destroyed` is true iff that already\n    // happened, so dispose now instead of leaking the scope.\n    if (response.destroyed) onComplete()\n\n    await next()\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,163 @@
+import { ParameterizedContext, DefaultState, DefaultContext, Middleware, Context } from 'koa';
+
+/**
+ * Koa v3 request-scope middleware for InferDI.
+ *
+ * Creates one InferDI scope per Koa request, exposes it through `ctx.state`,
+ * and disposes it from the underlying Node response completion events. The
+ * package is lifecycle glue only: no decorators, reflection, route scanning,
+ * controller layer, or handler parameter injection.
+ *
+ * @example
+ * ```ts
+ * import Koa from 'koa'
+ * import { inferdiKoa, type InferdiScopeOf } from '@inferdi/koa'
+ *
+ * const root = buildRootContainer()
+ *
+ * declare module 'koa' {
+ *   interface DefaultState {
+ *     di: InferdiScopeOf<typeof root>
+ *   }
+ * }
+ *
+ * const app = new Koa()
+ * app.use(inferdiKoa({ container: root }))
+ *
+ * app.use(async (ctx) => {
+ *   ctx.body = await ctx.state.di.get('users').profile('42')
+ * })
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * A value of type `T` or a promise resolving to it. Used by scope hooks so they
+ * accept both synchronous and asynchronous implementations.
+ *
+ * @template T - The resolved value type.
+ */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Minimal structural contract for a disposable InferDI request scope. Any
+ * `Container` instance satisfies it.
+ */
+interface InferdiScope {
+    /**
+     * Releases everything the scope owns. InferDI's `Container.dispose()` is
+     * idempotent; custom scope implementations should preserve that behavior.
+     */
+    dispose(): MaybePromise<void>;
+}
+/**
+ * Structural contract for the root container handed to the middleware.
+ *
+ * @template Scope - The per-request scope type produced by `createScope()`.
+ */
+interface InferdiRoot<Scope extends InferdiScope = InferdiScope> {
+    /** Opens a fresh request scope. Called once per request. */
+    createScope(): Scope;
+}
+/**
+ * Extracts the request-scope type created by a root container.
+ *
+ * @template Root - A structural root container with `createScope()`.
+ */
+type InferdiScopeOf<Root extends InferdiRoot> = ReturnType<Root['createScope']>;
+/**
+ * Koa state fragment that exposes a concrete scope under a state key.
+ *
+ * @template Scope - The scope exposed on `ctx.state`.
+ * @template Key   - The Koa state key. Defaults to `'di'`.
+ */
+type InferdiKoaState<Scope extends InferdiScope, Key extends string = 'di'> = {
+    [P in Key]: Scope;
+};
+/**
+ * Koa context with a concrete InferDI request scope present on `ctx.state`.
+ *
+ * @template StateT  - Existing Koa state type.
+ * @template ContextT - Existing Koa context extension type.
+ * @template Scope   - The scope exposed on `ctx.state`.
+ * @template Key     - The Koa state key. Defaults to `'di'`.
+ */
+type InferdiKoaContext<StateT, ContextT, Scope extends InferdiScope, Key extends string = 'di'> = ParameterizedContext<StateT & InferdiKoaState<Scope, Key>, ContextT>;
+/**
+ * Options for {@link inferdiKoa}.
+ *
+ * @template Root    - The root container type.
+ * @template StateT  - Existing Koa state available to setup hooks.
+ * @template ContextT - Existing Koa context extensions available to hooks.
+ * @template Key     - The `ctx.state` key.
+ * @template Scope   - The per-request scope type.
+ */
+interface InferdiKoaOptions<Root extends InferdiRoot, StateT = DefaultState, ContextT = DefaultContext, Key extends string = 'di', Scope extends InferdiScope = InferdiScopeOf<Root>> {
+    /** The root container. It is never disposed by this middleware. */
+    readonly container: Root;
+    /** Koa `ctx.state` key. Defaults to `'di'`. */
+    readonly key?: Key;
+    /**
+     * Overrides how a request scope is created. Defaults to
+     * `root.createScope()`. May be async.
+     */
+    readonly createScope?: (root: Root, context: ParameterizedContext<StateT, ContextT>) => MaybePromise<Scope>;
+    /**
+     * Optional hook to hydrate the freshly created scope before downstream
+     * middleware can read it from `ctx.state`.
+     */
+    readonly setupScope?: (scope: Scope, context: ParameterizedContext<StateT, ContextT>) => MaybePromise<void>;
+    /**
+     * Overrides request-scope disposal. Defaults to `scope.dispose()`.
+     */
+    readonly disposeScope?: (scope: Scope, context: InferdiKoaContext<StateT, ContextT, Scope, Key>) => MaybePromise<void>;
+    /**
+     * Controls whether the middleware disposes the request scope after response
+     * completion. Returning `false` transfers disposal responsibility to
+     * application code.
+     */
+    readonly autoDispose?: boolean | ((context: InferdiKoaContext<StateT, ContextT, Scope, Key>) => MaybePromise<boolean>);
+    /**
+     * Optional sink for cleanup failures. Returning normally marks the cleanup
+     * error as handled; omitted failures are emitted through `ctx.app`.
+     */
+    readonly onDisposeError?: (error: unknown, context: InferdiKoaContext<StateT, ContextT, Scope, Key>) => MaybePromise<void>;
+}
+/**
+ * Marks the current Koa request scope as manually owned by application code.
+ *
+ * Koa stream responses normally do not need this: the middleware waits for the
+ * underlying Node response `finish` / `close` events. Use this only when a
+ * route intentionally keeps the scope beyond the HTTP response boundary, such
+ * as background work that will dispose the scope later.
+ *
+ * @param context - The current Koa context.
+ */
+declare function skipInferdiDispose(context: Context): void;
+/**
+ * Creates Koa middleware that opens one InferDI request scope per request and
+ * exposes it as `ctx.state.di`.
+ *
+ * @template Root    - The root container type.
+ * @template StateT  - Existing Koa state visible in setup hooks.
+ * @template ContextT - Existing Koa context extensions visible in hooks.
+ * @template Scope   - The request scope type.
+ */
+declare function inferdiKoa<Root extends InferdiRoot, StateT = DefaultState, ContextT = DefaultContext, Scope extends InferdiScope = InferdiScopeOf<Root>>(options: Omit<InferdiKoaOptions<Root, StateT, ContextT, 'di', Scope>, 'key'> & {
+    readonly key?: 'di';
+}): Middleware<StateT & InferdiKoaState<Scope, 'di'>, ContextT>;
+/**
+ * Creates Koa middleware that opens one InferDI request scope per request and
+ * exposes it under a custom `ctx.state` key.
+ *
+ * @template Root    - The root container type.
+ * @template StateT  - Existing Koa state visible in setup hooks.
+ * @template ContextT - Existing Koa context extensions visible in hooks.
+ * @template Key     - The Koa state key.
+ * @template Scope   - The request scope type.
+ */
+declare function inferdiKoa<Root extends InferdiRoot, StateT = DefaultState, ContextT = DefaultContext, Key extends string = string, Scope extends InferdiScope = InferdiScopeOf<Root>>(options: InferdiKoaOptions<Root, StateT, ContextT, Key, Scope> & {
+    readonly key: Key;
+}): Middleware<StateT & InferdiKoaState<Scope, Key>, ContextT>;
+
+export { type InferdiKoaContext, type InferdiKoaOptions, type InferdiKoaState, type InferdiRoot, type InferdiScope, type InferdiScopeOf, type MaybePromise, inferdiKoa, skipInferdiDispose };

package/dist/index.d.ts

@@ -0,0 +1,163 @@
+import { ParameterizedContext, DefaultState, DefaultContext, Middleware, Context } from 'koa';
+
+/**
+ * Koa v3 request-scope middleware for InferDI.
+ *
+ * Creates one InferDI scope per Koa request, exposes it through `ctx.state`,
+ * and disposes it from the underlying Node response completion events. The
+ * package is lifecycle glue only: no decorators, reflection, route scanning,
+ * controller layer, or handler parameter injection.
+ *
+ * @example
+ * ```ts
+ * import Koa from 'koa'
+ * import { inferdiKoa, type InferdiScopeOf } from '@inferdi/koa'
+ *
+ * const root = buildRootContainer()
+ *
+ * declare module 'koa' {
+ *   interface DefaultState {
+ *     di: InferdiScopeOf<typeof root>
+ *   }
+ * }
+ *
+ * const app = new Koa()
+ * app.use(inferdiKoa({ container: root }))
+ *
+ * app.use(async (ctx) => {
+ *   ctx.body = await ctx.state.di.get('users').profile('42')
+ * })
+ * ```
+ *
+ * @module
+ */
+
+/**
+ * A value of type `T` or a promise resolving to it. Used by scope hooks so they
+ * accept both synchronous and asynchronous implementations.
+ *
+ * @template T - The resolved value type.
+ */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Minimal structural contract for a disposable InferDI request scope. Any
+ * `Container` instance satisfies it.
+ */
+interface InferdiScope {
+    /**
+     * Releases everything the scope owns. InferDI's `Container.dispose()` is
+     * idempotent; custom scope implementations should preserve that behavior.
+     */
+    dispose(): MaybePromise<void>;
+}
+/**
+ * Structural contract for the root container handed to the middleware.
+ *
+ * @template Scope - The per-request scope type produced by `createScope()`.
+ */
+interface InferdiRoot<Scope extends InferdiScope = InferdiScope> {
+    /** Opens a fresh request scope. Called once per request. */
+    createScope(): Scope;
+}
+/**
+ * Extracts the request-scope type created by a root container.
+ *
+ * @template Root - A structural root container with `createScope()`.
+ */
+type InferdiScopeOf<Root extends InferdiRoot> = ReturnType<Root['createScope']>;
+/**
+ * Koa state fragment that exposes a concrete scope under a state key.
+ *
+ * @template Scope - The scope exposed on `ctx.state`.
+ * @template Key   - The Koa state key. Defaults to `'di'`.
+ */
+type InferdiKoaState<Scope extends InferdiScope, Key extends string = 'di'> = {
+    [P in Key]: Scope;
+};
+/**
+ * Koa context with a concrete InferDI request scope present on `ctx.state`.
+ *
+ * @template StateT  - Existing Koa state type.
+ * @template ContextT - Existing Koa context extension type.
+ * @template Scope   - The scope exposed on `ctx.state`.
+ * @template Key     - The Koa state key. Defaults to `'di'`.
+ */
+type InferdiKoaContext<StateT, ContextT, Scope extends InferdiScope, Key extends string = 'di'> = ParameterizedContext<StateT & InferdiKoaState<Scope, Key>, ContextT>;
+/**
+ * Options for {@link inferdiKoa}.
+ *
+ * @template Root    - The root container type.
+ * @template StateT  - Existing Koa state available to setup hooks.
+ * @template ContextT - Existing Koa context extensions available to hooks.
+ * @template Key     - The `ctx.state` key.
+ * @template Scope   - The per-request scope type.
+ */
+interface InferdiKoaOptions<Root extends InferdiRoot, StateT = DefaultState, ContextT = DefaultContext, Key extends string = 'di', Scope extends InferdiScope = InferdiScopeOf<Root>> {
+    /** The root container. It is never disposed by this middleware. */
+    readonly container: Root;
+    /** Koa `ctx.state` key. Defaults to `'di'`. */
+    readonly key?: Key;
+    /**
+     * Overrides how a request scope is created. Defaults to
+     * `root.createScope()`. May be async.
+     */
+    readonly createScope?: (root: Root, context: ParameterizedContext<StateT, ContextT>) => MaybePromise<Scope>;
+    /**
+     * Optional hook to hydrate the freshly created scope before downstream
+     * middleware can read it from `ctx.state`.
+     */
+    readonly setupScope?: (scope: Scope, context: ParameterizedContext<StateT, ContextT>) => MaybePromise<void>;
+    /**
+     * Overrides request-scope disposal. Defaults to `scope.dispose()`.
+     */
+    readonly disposeScope?: (scope: Scope, context: InferdiKoaContext<StateT, ContextT, Scope, Key>) => MaybePromise<void>;
+    /**
+     * Controls whether the middleware disposes the request scope after response
+     * completion. Returning `false` transfers disposal responsibility to
+     * application code.
+     */
+    readonly autoDispose?: boolean | ((context: InferdiKoaContext<StateT, ContextT, Scope, Key>) => MaybePromise<boolean>);
+    /**
+     * Optional sink for cleanup failures. Returning normally marks the cleanup
+     * error as handled; omitted failures are emitted through `ctx.app`.
+     */
+    readonly onDisposeError?: (error: unknown, context: InferdiKoaContext<StateT, ContextT, Scope, Key>) => MaybePromise<void>;
+}
+/**
+ * Marks the current Koa request scope as manually owned by application code.
+ *
+ * Koa stream responses normally do not need this: the middleware waits for the
+ * underlying Node response `finish` / `close` events. Use this only when a
+ * route intentionally keeps the scope beyond the HTTP response boundary, such
+ * as background work that will dispose the scope later.
+ *
+ * @param context - The current Koa context.
+ */
+declare function skipInferdiDispose(context: Context): void;
+/**
+ * Creates Koa middleware that opens one InferDI request scope per request and
+ * exposes it as `ctx.state.di`.
+ *
+ * @template Root    - The root container type.
+ * @template StateT  - Existing Koa state visible in setup hooks.
+ * @template ContextT - Existing Koa context extensions visible in hooks.
+ * @template Scope   - The request scope type.
+ */
+declare function inferdiKoa<Root extends InferdiRoot, StateT = DefaultState, ContextT = DefaultContext, Scope extends InferdiScope = InferdiScopeOf<Root>>(options: Omit<InferdiKoaOptions<Root, StateT, ContextT, 'di', Scope>, 'key'> & {
+    readonly key?: 'di';
+}): Middleware<StateT & InferdiKoaState<Scope, 'di'>, ContextT>;
+/**
+ * Creates Koa middleware that opens one InferDI request scope per request and
+ * exposes it under a custom `ctx.state` key.
+ *
+ * @template Root    - The root container type.
+ * @template StateT  - Existing Koa state visible in setup hooks.
+ * @template ContextT - Existing Koa context extensions visible in hooks.
+ * @template Key     - The Koa state key.
+ * @template Scope   - The request scope type.
+ */
+declare function inferdiKoa<Root extends InferdiRoot, StateT = DefaultState, ContextT = DefaultContext, Key extends string = string, Scope extends InferdiScope = InferdiScopeOf<Root>>(options: InferdiKoaOptions<Root, StateT, ContextT, Key, Scope> & {
+    readonly key: Key;
+}): Middleware<StateT & InferdiKoaState<Scope, Key>, ContextT>;
+
+export { type InferdiKoaContext, type InferdiKoaOptions, type InferdiKoaState, type InferdiRoot, type InferdiScope, type InferdiScopeOf, type MaybePromise, inferdiKoa, skipInferdiDispose };

package/dist/index.js

@@ -0,0 +1,164 @@
+// src/index.ts
+var skippedContexts = /* @__PURE__ */ new WeakSet();
+function isPromiseLike(value) {
+  return value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+function cleanupError(errors) {
+  if (errors.length === 1) return errors[0];
+  return new AggregateError(errors, "InferDI Koa request cleanup failed");
+}
+function throwCollected(errors) {
+  if (errors.length === 1) {
+    throw errors[0];
+  }
+  throw new AggregateError(errors, "InferDI Koa request lifecycle failed");
+}
+function emitAppError(error, context) {
+  try {
+    context.app.emit("error", error, context);
+  } catch {
+  }
+}
+function emitUnhandledCleanupErrors(errors, context) {
+  if (errors.length === 0) return;
+  emitAppError(cleanupError(errors), context);
+}
+function handleCleanupError(error, context, onDisposeError, errors) {
+  if (onDisposeError === void 0) {
+    errors.push(error);
+    return;
+  }
+  try {
+    const handling = onDisposeError(error, context);
+    if (isPromiseLike(handling)) {
+      return handling.then(void 0, (handlerError) => {
+        errors.push(error);
+        errors.push(handlerError);
+      });
+    }
+  } catch (handlerError) {
+    errors.push(error);
+    errors.push(handlerError);
+  }
+}
+function disposeWithErrors(scope, context, disposeScope, onDisposeError, errors) {
+  try {
+    const disposing = disposeScope(scope, context);
+    if (isPromiseLike(disposing)) {
+      return disposing.then(
+        void 0,
+        (error) => handleCleanupError(
+          error,
+          context,
+          onDisposeError,
+          errors
+        )
+      );
+    }
+  } catch (error) {
+    return handleCleanupError(error, context, onDisposeError, errors);
+  }
+}
+async function disposeAfterSetupFailure(scope, context, setupError, disposeScope, onDisposeError) {
+  const errors = [setupError];
+  const disposing = disposeWithErrors(
+    scope,
+    context,
+    disposeScope,
+    onDisposeError,
+    errors
+  );
+  await disposing;
+  throwCollected(errors);
+}
+function skipInferdiDispose(context) {
+  skippedContexts.add(context);
+}
+function inferdiKoa(options) {
+  const root = options.container;
+  const key = options.key ?? "di";
+  const createScope = options.createScope ?? ((root2) => root2.createScope());
+  const setupScope = options.setupScope;
+  const disposeScope = options.disposeScope ?? ((scope) => scope.dispose());
+  const autoDispose = options.autoDispose;
+  const onDisposeError = options.onDisposeError;
+  return async function inferdiKoaMiddleware(context, next) {
+    const setupContext = context;
+    const typedContext = context;
+    const scopeResult = createScope(root, setupContext);
+    const scope = isPromiseLike(scopeResult) ? await scopeResult : scopeResult;
+    typedContext.state[key] = scope;
+    if (setupScope !== void 0) {
+      try {
+        const setupResult = setupScope(scope, setupContext);
+        if (isPromiseLike(setupResult)) {
+          await setupResult;
+        }
+      } catch (error) {
+        skippedContexts.delete(context);
+        await disposeAfterSetupFailure(
+          scope,
+          typedContext,
+          error,
+          disposeScope,
+          onDisposeError
+        );
+      }
+    }
+    let disposed = false;
+    const response = context.res;
+    const runCleanup = async () => {
+      if (disposed) return;
+      disposed = true;
+      const skipped = skippedContexts.delete(context);
+      if (skipped) return;
+      const errors = [];
+      let shouldDispose = autoDispose !== false;
+      if (typeof autoDispose === "function") {
+        try {
+          const autoDisposeResult = autoDispose(typedContext);
+          shouldDispose = isPromiseLike(autoDisposeResult) ? await autoDisposeResult !== false : autoDisposeResult !== false;
+        } catch (error) {
+          shouldDispose = true;
+          const handling = handleCleanupError(
+            error,
+            typedContext,
+            onDisposeError,
+            errors
+          );
+          if (isPromiseLike(handling)) {
+            await handling;
+          }
+        }
+      }
+      if (shouldDispose) {
+        const disposing = disposeWithErrors(
+          scope,
+          typedContext,
+          disposeScope,
+          onDisposeError,
+          errors
+        );
+        if (isPromiseLike(disposing)) {
+          await disposing;
+        }
+      }
+      emitUnhandledCleanupErrors(errors, context);
+    };
+    const onComplete = () => {
+      response.removeListener("finish", onComplete);
+      response.removeListener("close", onComplete);
+      void runCleanup().then(void 0, (error) => {
+        emitAppError(error, context);
+      });
+    };
+    response.on("finish", onComplete);
+    response.on("close", onComplete);
+    if (response.destroyed) onComplete();
+    await next();
+  };
+}
+
+export { inferdiKoa, skipInferdiDispose };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["root"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Koa v3 request-scope middleware for InferDI.\n *\n * Creates one InferDI scope per Koa request, exposes it through `ctx.state`,\n * and disposes it from the underlying Node response completion events. The\n * package is lifecycle glue only: no decorators, reflection, route scanning,\n * controller layer, or handler parameter injection.\n *\n * @example\n * ```ts\n * import Koa from 'koa'\n * import { inferdiKoa, type InferdiScopeOf } from '@inferdi/koa'\n *\n * const root = buildRootContainer()\n *\n * declare module 'koa' {\n *   interface DefaultState {\n *     di: InferdiScopeOf<typeof root>\n *   }\n * }\n *\n * const app = new Koa()\n * app.use(inferdiKoa({ container: root }))\n *\n * app.use(async (ctx) => {\n *   ctx.body = await ctx.state.di.get('users').profile('42')\n * })\n * ```\n *\n * @module\n */\n\nimport type {\n  Context,\n  DefaultContext,\n  DefaultState,\n  Middleware,\n  ParameterizedContext,\n} from 'koa'\n\n/**\n * A value of type `T` or a promise resolving to it. Used by scope hooks so they\n * accept both synchronous and asynchronous implementations.\n *\n * @template T - The resolved value type.\n */\nexport type MaybePromise<T> = T | Promise<T>\n\n/**\n * Minimal structural contract for a disposable InferDI request scope. Any\n * `Container` instance satisfies it.\n */\nexport interface InferdiScope {\n  /**\n   * Releases everything the scope owns. InferDI's `Container.dispose()` is\n   * idempotent; custom scope implementations should preserve that behavior.\n   */\n  dispose(): MaybePromise<void>\n}\n\n/**\n * Structural contract for the root container handed to the middleware.\n *\n * @template Scope - The per-request scope type produced by `createScope()`.\n */\nexport interface InferdiRoot<Scope extends InferdiScope = InferdiScope> {\n  /** Opens a fresh request scope. Called once per request. */\n  createScope(): Scope\n}\n\n/**\n * Extracts the request-scope type created by a root container.\n *\n * @template Root - A structural root container with `createScope()`.\n */\nexport type InferdiScopeOf<Root extends InferdiRoot> =\n  ReturnType<Root['createScope']>\n\n/**\n * Koa state fragment that exposes a concrete scope under a state key.\n *\n * @template Scope - The scope exposed on `ctx.state`.\n * @template Key   - The Koa state key. Defaults to `'di'`.\n */\nexport type InferdiKoaState<\n  Scope extends InferdiScope,\n  Key extends string = 'di',\n> = {\n  [P in Key]: Scope\n}\n\n/**\n * Koa context with a concrete InferDI request scope present on `ctx.state`.\n *\n * @template StateT  - Existing Koa state type.\n * @template ContextT - Existing Koa context extension type.\n * @template Scope   - The scope exposed on `ctx.state`.\n * @template Key     - The Koa state key. Defaults to `'di'`.\n */\nexport type InferdiKoaContext<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string = 'di',\n> = ParameterizedContext<\n  StateT & InferdiKoaState<Scope, Key>,\n  ContextT\n>\n\n/**\n * Options for {@link inferdiKoa}.\n *\n * @template Root    - The root container type.\n * @template StateT  - Existing Koa state available to setup hooks.\n * @template ContextT - Existing Koa context extensions available to hooks.\n * @template Key     - The `ctx.state` key.\n * @template Scope   - The per-request scope type.\n */\nexport interface InferdiKoaOptions<\n  Root extends InferdiRoot,\n  StateT = DefaultState,\n  ContextT = DefaultContext,\n  Key extends string = 'di',\n  Scope extends InferdiScope = InferdiScopeOf<Root>,\n> {\n  /** The root container. It is never disposed by this middleware. */\n  readonly container: Root\n  /** Koa `ctx.state` key. Defaults to `'di'`. */\n  readonly key?: Key\n  /**\n   * Overrides how a request scope is created. Defaults to\n   * `root.createScope()`. May be async.\n   */\n  readonly createScope?: (\n    root: Root,\n    context: ParameterizedContext<StateT, ContextT>,\n  ) => MaybePromise<Scope>\n  /**\n   * Optional hook to hydrate the freshly created scope before downstream\n   * middleware can read it from `ctx.state`.\n   */\n  readonly setupScope?: (\n    scope: Scope,\n    context: ParameterizedContext<StateT, ContextT>,\n  ) => MaybePromise<void>\n  /**\n   * Overrides request-scope disposal. Defaults to `scope.dispose()`.\n   */\n  readonly disposeScope?: (\n    scope: Scope,\n    context: InferdiKoaContext<StateT, ContextT, Scope, Key>,\n  ) => MaybePromise<void>\n  /**\n   * Controls whether the middleware disposes the request scope after response\n   * completion. Returning `false` transfers disposal responsibility to\n   * application code.\n   */\n  readonly autoDispose?:\n    | boolean\n    | ((\n        context: InferdiKoaContext<StateT, ContextT, Scope, Key>,\n      ) => MaybePromise<boolean>)\n  /**\n   * Optional sink for cleanup failures. Returning normally marks the cleanup\n   * error as handled; omitted failures are emitted through `ctx.app`.\n   */\n  readonly onDisposeError?: (\n    error: unknown,\n    context: InferdiKoaContext<StateT, ContextT, Scope, Key>,\n  ) => MaybePromise<void>\n}\n\ntype TypedContext<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string,\n> = InferdiKoaContext<StateT, ContextT, Scope, Key>\n\nconst skippedContexts = new WeakSet<Context>()\n\nfunction isPromiseLike<T>(value: T | PromiseLike<T>): value is PromiseLike<T> {\n  return (\n    value !== null &&\n    (typeof value === 'object' || typeof value === 'function') &&\n    typeof (value as { then?: unknown }).then === 'function'\n  )\n}\n\nfunction cleanupError(errors: unknown[]): unknown {\n  if (errors.length === 1) return errors[0]\n\n  return new AggregateError(errors, 'InferDI Koa request cleanup failed')\n}\n\nfunction throwCollected(errors: unknown[]): never {\n  if (errors.length === 1) {\n    throw errors[0]\n  }\n\n  throw new AggregateError(errors, 'InferDI Koa request lifecycle failed')\n}\n\nfunction emitAppError(error: unknown, context: Context): void {\n  try {\n    context.app.emit('error', error, context)\n  } catch {\n    // Response cleanup must not fail because application error reporting failed.\n  }\n}\n\nfunction emitUnhandledCleanupErrors(\n  errors: unknown[],\n  context: Context,\n): void {\n  if (errors.length === 0) return\n\n  emitAppError(cleanupError(errors), context)\n}\n\nfunction handleCleanupError<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string,\n>(\n  error: unknown,\n  context: TypedContext<StateT, ContextT, Scope, Key>,\n  onDisposeError:\n    | ((\n        error: unknown,\n        context: TypedContext<StateT, ContextT, Scope, Key>,\n      ) => MaybePromise<void>)\n    | undefined,\n  errors: unknown[],\n): void | PromiseLike<void> {\n  if (onDisposeError === undefined) {\n    errors.push(error)\n    return\n  }\n\n  try {\n    const handling = onDisposeError(error, context)\n    if (isPromiseLike(handling)) {\n      return handling.then(undefined, (handlerError) => {\n        errors.push(error)\n        errors.push(handlerError)\n      })\n    }\n  } catch (handlerError) {\n    errors.push(error)\n    errors.push(handlerError)\n  }\n}\n\nfunction disposeWithErrors<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string,\n>(\n  scope: Scope,\n  context: TypedContext<StateT, ContextT, Scope, Key>,\n  disposeScope: (\n    scope: Scope,\n    context: TypedContext<StateT, ContextT, Scope, Key>,\n  ) => MaybePromise<void>,\n  onDisposeError:\n    | ((\n        error: unknown,\n        context: TypedContext<StateT, ContextT, Scope, Key>,\n      ) => MaybePromise<void>)\n    | undefined,\n  errors: unknown[],\n): void | PromiseLike<void> {\n  try {\n    const disposing = disposeScope(scope, context)\n    if (isPromiseLike(disposing)) {\n      return disposing.then(\n        undefined,\n        (error) => handleCleanupError(\n          error,\n          context,\n          onDisposeError,\n          errors,\n        ),\n      )\n    }\n  } catch (error) {\n    return handleCleanupError(error, context, onDisposeError, errors)\n  }\n}\n\nasync function disposeAfterSetupFailure<\n  StateT,\n  ContextT,\n  Scope extends InferdiScope,\n  Key extends string,\n>(\n  scope: Scope,\n  context: TypedContext<StateT, ContextT, Scope, Key>,\n  setupError: unknown,\n  disposeScope: (\n    scope: Scope,\n    context: TypedContext<StateT, ContextT, Scope, Key>,\n  ) => MaybePromise<void>,\n  onDisposeError:\n    | ((\n        error: unknown,\n        context: TypedContext<StateT, ContextT, Scope, Key>,\n      ) => MaybePromise<void>)\n    | undefined,\n): Promise<never> {\n  const errors = [setupError]\n  const disposing = disposeWithErrors(\n    scope,\n    context,\n    disposeScope,\n    onDisposeError,\n    errors,\n  )\n\n  await disposing\n  throwCollected(errors)\n}\n\n/**\n * Marks the current Koa request scope as manually owned by application code.\n *\n * Koa stream responses normally do not need this: the middleware waits for the\n * underlying Node response `finish` / `close` events. Use this only when a\n * route intentionally keeps the scope beyond the HTTP response boundary, such\n * as background work that will dispose the scope later.\n *\n * @param context - The current Koa context.\n */\nexport function skipInferdiDispose(context: Context): void {\n  skippedContexts.add(context)\n}\n\n/**\n * Creates Koa middleware that opens one InferDI request scope per request and\n * exposes it as `ctx.state.di`.\n *\n * @template Root    - The root container type.\n * @template StateT  - Existing Koa state visible in setup hooks.\n * @template ContextT - Existing Koa context extensions visible in hooks.\n * @template Scope   - The request scope type.\n */\nexport function inferdiKoa<\n  Root extends InferdiRoot,\n  StateT = DefaultState,\n  ContextT = DefaultContext,\n  Scope extends InferdiScope = InferdiScopeOf<Root>,\n>(\n  options: Omit<\n    InferdiKoaOptions<Root, StateT, ContextT, 'di', Scope>,\n    'key'\n  > & {\n    readonly key?: 'di'\n  },\n): Middleware<StateT & InferdiKoaState<Scope, 'di'>, ContextT>\n\n/**\n * Creates Koa middleware that opens one InferDI request scope per request and\n * exposes it under a custom `ctx.state` key.\n *\n * @template Root    - The root container type.\n * @template StateT  - Existing Koa state visible in setup hooks.\n * @template ContextT - Existing Koa context extensions visible in hooks.\n * @template Key     - The Koa state key.\n * @template Scope   - The request scope type.\n */\nexport function inferdiKoa<\n  Root extends InferdiRoot,\n  StateT = DefaultState,\n  ContextT = DefaultContext,\n  Key extends string = string,\n  Scope extends InferdiScope = InferdiScopeOf<Root>,\n>(\n  options: InferdiKoaOptions<Root, StateT, ContextT, Key, Scope> & {\n    readonly key: Key\n  },\n): Middleware<StateT & InferdiKoaState<Scope, Key>, ContextT>\n\nexport function inferdiKoa<\n  Root extends InferdiRoot,\n  StateT = DefaultState,\n  ContextT = DefaultContext,\n  Key extends string = string,\n  Scope extends InferdiScope = InferdiScopeOf<Root>,\n>(\n  options: InferdiKoaOptions<Root, StateT, ContextT, Key, Scope>,\n): Middleware<StateT & InferdiKoaState<Scope, Key>, ContextT> {\n  const root = options.container\n  const key = (options.key ?? 'di') as Key\n  const createScope =\n    options.createScope ??\n    ((root: Root) => root.createScope() as Scope)\n  const setupScope = options.setupScope\n  const disposeScope =\n    options.disposeScope ??\n    ((scope: Scope) => scope.dispose())\n  const autoDispose = options.autoDispose\n  const onDisposeError = options.onDisposeError\n\n  return async function inferdiKoaMiddleware(context, next) {\n    const setupContext = context as ParameterizedContext<StateT, ContextT>\n    const typedContext = context as TypedContext<\n      StateT,\n      ContextT,\n      Scope,\n      Key\n    >\n    const scopeResult = createScope(root, setupContext)\n    const scope = isPromiseLike(scopeResult)\n      ? await scopeResult\n      : scopeResult\n\n    // Expose the scope before `setupScope` so the setup-failure disposal hooks\n    // (`disposeScope` / `onDisposeError`) see the same `ctx.state[key]` their\n    // typed context promises. Nothing downstream runs until `next()`, so a\n    // half-built scope is never observable outside cleanup.\n    ;(typedContext.state as InferdiKoaState<Scope, Key>)[key] = scope\n\n    if (setupScope !== undefined) {\n      try {\n        const setupResult = setupScope(scope, setupContext)\n        if (isPromiseLike(setupResult)) {\n          await setupResult\n        }\n      } catch (error) {\n        skippedContexts.delete(context)\n        await disposeAfterSetupFailure(\n          scope,\n          typedContext,\n          error,\n          disposeScope,\n          onDisposeError,\n        )\n      }\n    }\n\n    let disposed = false\n    const response = context.res\n\n    const runCleanup = async () => {\n      if (disposed) return\n\n      disposed = true\n      const skipped = skippedContexts.delete(context)\n      if (skipped) return\n\n      const errors: unknown[] = []\n      let shouldDispose = autoDispose !== false\n\n      if (typeof autoDispose === 'function') {\n        try {\n          const autoDisposeResult = autoDispose(typedContext)\n          shouldDispose = isPromiseLike(autoDisposeResult)\n            ? await autoDisposeResult !== false\n            : autoDisposeResult !== false\n        } catch (error) {\n          shouldDispose = true\n          const handling = handleCleanupError(\n            error,\n            typedContext,\n            onDisposeError,\n            errors,\n          )\n          if (isPromiseLike(handling)) {\n            await handling\n          }\n        }\n      }\n\n      if (shouldDispose) {\n        const disposing = disposeWithErrors(\n          scope,\n          typedContext,\n          disposeScope,\n          onDisposeError,\n          errors,\n        )\n        if (isPromiseLike(disposing)) {\n          await disposing\n        }\n      }\n\n      emitUnhandledCleanupErrors(errors, context)\n    }\n\n    // One shared completion handler, attached with `on` rather than `once`: it\n    // removes both listeners on the first event, so each request avoids the two\n    // per-listener `once` wrapper allocations, while `runCleanup`'s `disposed`\n    // flag keeps it idempotent. `finish` = response written; `close` =\n    // connection closed before completion.\n    const onComplete = () => {\n      response.removeListener('finish', onComplete)\n      response.removeListener('close', onComplete)\n      // `runCleanup` handles lifecycle errors itself; this is a final bug guard.\n      /* v8 ignore next 3 */\n      void runCleanup().then(undefined, (error) => {\n        emitAppError(error, context)\n      })\n    }\n\n    response.on('finish', onComplete)\n    response.on('close', onComplete)\n\n    // An async `createScope` / `setupScope` can yield the event loop long enough\n    // for the client to disconnect. If `close` already fired during that await,\n    // the listeners above missed it; `destroyed` is true iff that already\n    // happened, so dispose now instead of leaking the scope.\n    if (response.destroyed) onComplete()\n\n    await next()\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@inferdi/koa",
+  "version": "4.0.8",
+  "description": "Koa request-scope middleware for InferDI.",
+  "keywords": [
+    "typescript",
+    "dependency-injection",
+    "di",
+    "ioc",
+    "inferdi",
+    "koa",
+    "middleware",
+    "request-scope"
+  ],
+  "author": {
+    "name": "Viacheslav Kabanov",
+    "email": "vkabanov@inferdi.com",
+    "url": "https://github.com/maxrendel"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/inferdi/inferdi/tree/main/packages/koa#readme",
+  "bugs": {
+    "url": "https://github.com/inferdi/inferdi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inferdi/inferdi.git",
+    "directory": "packages/koa"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@inferdi/inferdi": "^4.0.0",
+    "@types/koa": "^3.0.0",
+    "koa": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/koa": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/koa": "^3.0.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "koa": "^3.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.5",
+    "@inferdi/inferdi": "4.0.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:types": "vitest --typecheck.enabled --run"
+  }
+}