Compatibility

Compatibility

dynamodb-toolkit publishes as a single ESM package — one source tree, .d.ts sidecars next to every .js, zero build step. This page summarizes what consumers can expect across TypeScript, CommonJS, and alternative JavaScript runtimes, and points at the tests that demonstrate each path.

See also (AWS JS SDK v3): Package overview. Vocabulary: Concepts.

TypeScript

Every .js file in src/ has a hand-written .d.ts sidecar. The published package exports both from the same entry, so TypeScript consumers get typings automatically:

import {Adapter, type Raw, raw} from 'dynamodb-toolkit';
import {buildUpdate, type ConditionClause} from 'dynamodb-toolkit/expressions';
import {type TransactWriteDescriptor} from 'dynamodb-toolkit/batch';

• No build step, no generation round-trip. Sidecars are authored by hand, reviewed like source, and shipped verbatim.
• Generics where they help. Adapter<TItem, TKey> binds the item shape to method signatures; buildUpdate<T> / buildCondition<T> preserve caller-supplied params typing.
• Type-checking in this repo runs over tests/**/* as well as src/**/* — any .ts file dropped into tests/ is picked up by npm run ts-check for free.
• Runnable TS smoke test: tests/test-typed.ts exercises the typed public surface (typed Adapter, typed condition clauses, typed descriptor unions, the returnFailedItem option). Invoke via npm run ts-test (Node 22+; tape-six runs .ts natively — no tsx / ts-node needed).

CommonJS

The package itself is "type": "module", but CJS consumers can pull it in with require() on current Node 20+ (require(esm) shipped unflagged in Node 20.19 for the 20.x line and 22.12 for 22.x):

const {Adapter, raw} = require('dynamodb-toolkit');
const {buildUpdate} = require('dynamodb-toolkit/expressions');
const {applyTransaction} = require('dynamodb-toolkit/batch');

• Uses sync require(). No await import() needed — the source has no top-level await.
• All sub-exports available from CJS: main entry, /expressions, /batch, /mass, /paths, /rest-core, /handler.
• Runnable CJS smoke test: tests/test-smoke.cjs imports every sub-export via require() and exercises a minimal flow (builders, Adapter constructor, Raw round-trip). Part of the default npm test under Node.

Runtimes

The same source tree is tested on three JS runtimes:

Runtime	Script	Notes
Node	npm test	Default. Includes .cjs tests via tape-six's Node-only glob.
Deno	npm run test:deno	Runs the .js / .mjs suite. .cjs tests skipped by config (Node-only).
Bun	npm run test:bun	Runs the .js / .mjs suite. .cjs tests skipped by config (Node-only).

Cross-runtime test counts match exactly (same .js / .mjs suite); the .cjs smoke-test is the only delta, and it's scoped to Node because require(esm) is the Node-specific story. Everything else — ESM imports, the Adapter, the expression builders, batch/transaction chunking, the REST handler — is portable.

If you ship a library that consumes dynamodb-toolkit and you also target Deno or Bun, the same support matrix applies to your consumers: the package works in any runtime that supports ESM, and the typings work in any editor / type-checker that understands .d.ts.

See also

• Getting started
• Concepts
• HTTP handler