Compatibility

Compatibility

Express versions

Peer dependency range: ^4.21.0 || ^5.0.0.

The adapter uses only stable surface area:

• req.method, req.path, req.query, req.body, req.url, req.originalUrl.
• res.status(N).json(obj), res.status(N).end().
• next from the middleware signature (req, res, next) => void.

Both Express 4 (still the most widely deployed) and Express 5 (current) are supported. Express 5 auto-awaits async handlers and forwards rejections to next(err); Express 4 does not. The adapter wraps its own dispatch in a try/catch that forwards to next(err) for unexpected failures, so error propagation works identically on both.

Sibling adapters

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

• dynamodb-toolkit-koa — Koa 2 / 3 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.
• Express — 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-express') works on Nodes that ship require(esm) (20.19+ / 22.12+ / anything newer). The .cjs smoke test demonstrates:

const {createExpressAdapter} = require('dynamodb-toolkit-express');
const {readJsonBody} = require('dynamodb-toolkit-express/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 {createExpressAdapter, type ExpressAdapterOptions} from 'dynamodb-toolkit-express';

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: ExpressAdapterOptions<Planet> = {
  keyFromPath: (raw, a) => ({[a.keyFields[0].name]: raw}),
  policy: {defaultLimit: 25, maxLimit: 200}
};
const mw = createExpressAdapter(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 express 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 Express + fetch.
• 5 CJS smoke tests.
• 5 TypeScript smoke tests.

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