Compatibility

Compatibility

Koa versions

Peer dependency range: ^2.15.0 || ^3.0.0.

The adapter uses only stable surface area:

• ctx.method, ctx.path, ctx.query, ctx.req, ctx.request.body, ctx.status, ctx.body, ctx.originalUrl.
• next from the middleware signature (ctx, next) => Promise<void>.

Both Koa 2 (still the most widely deployed) and Koa 3 (current) are supported. Koa 3 dropped some deprecated shims but didn't change the middleware contract.

Sibling adapters

Same wire contract, different host — share one Adapter instance across any of them:

• dynamodb-toolkit-express — Express 4 / 5 middleware.
• dynamodb-toolkit-fetch — Web Fetch (Request) => Promise<Response> for Cloudflare Workers, Deno Deploy, Bun.serve, Hono.
• dynamodb-toolkit-lambda — AWS Lambda (API Gateway v1 / v2, Function URL, ALB).
• dynamodb-toolkit/handler — the bundled node:http handler in the parent toolkit.

Runtimes

The unit test suite runs identically under:

Runtime	Command	Notes
Node	npm test	Node 20+ floor (see below)
Bun	npm run test:bun	Current Bun releases
Deno	npm run test:deno	--allow-* flags provided by tape-six's runner

Cross-runtime support is inherited from:

• dynamodb-toolkit itself — which tests Node / Bun / Deno.
• Koa — Bun and Deno both ship compatible node:http / node:stream shims.
• @aws-sdk/client-dynamodb / @aws-sdk/lib-dynamodb — runnable on Bun and Deno via their Node compat layers.

Node version floor

engines.node is >=20. Two sub-floors worth knowing:

• require(esm) interop for CJS consumers — 20.19+ on the 20.x line, 22.12+ on 22.x, unflagged everywhere newer. The .cjs smoke test exercises this.
• Native TypeScript — Node 22.6+ (with --experimental-strip-types) or 23.6+ (unflagged). Used by npm run ts-test. Bun and Deno run .ts natively without special setup, via npm run ts-test:bun and npm run ts-test:deno.

Both smoke-tests are included so you can verify your target runtime handles the adapter correctly.

CommonJS consumers

require('dynamodb-toolkit-koa') works on Nodes that ship require(esm) (20.19+ / 22.12+ / anything newer). The .cjs smoke test demonstrates:

const {createKoaAdapter} = require('dynamodb-toolkit-koa');
const {readJsonBody} = require('dynamodb-toolkit-koa/read-body.js');

TypeScript consumers

Hand-written .d.ts sidecars ship next to each .js file. package.json declares main, module, and types for all resolution styles:

{
  "main": "./src/index.js",
  "module": "./src/index.js",
  "types": "./src/index.d.ts",
  "exports": {
    ".": "./src/index.js",
    "./*": "./src/*"
  }
}

The factory is generic in TItem so typed Adapter<Item, Key> instances flow through without casts:

import {Adapter} from 'dynamodb-toolkit';
import {createKoaAdapter, type KoaAdapterOptions} from 'dynamodb-toolkit-koa';

interface Planet extends Record<string, unknown> {
  name: string;
  climate?: string;
}
type PlanetKey = Pick<Planet, 'name'>;

const adapter = new Adapter<Planet, PlanetKey>({client, table: 'planets', keyFields: ['name']});

const opts: KoaAdapterOptions<Planet> = {
  keyFromPath: (raw, a) => ({[a.keyFields[0].name]: raw}),
  policy: {defaultLimit: 25, maxLimit: 200}
};
const mw = createKoaAdapter(adapter, opts);

See tests/test-typed.ts in the source tree for a runnable typed example.

Package shape

• ESM-only. The source is .js + hand-written .d.ts, no build step.
• Zero runtime dependencies. dynamodb-toolkit and koa are peerDependencies.
• No node:* imports at runtime. Type-only imports from node:http in .d.ts files are fine; runtime code is framework-neutral where the framework isn't explicitly referenced.

Tested against

The adapter's own test matrix exercises the full route pack:

• 43 tests, 98 assertions, via real Koa + fetch.
• 4 CJS smoke tests.
• 5 TypeScript smoke tests.

All identical across Node / Bun / Deno except the .cjs suite (Node-only by design).