Getting started

Getting started

See also (AWS JS SDK v3): DynamoDBClient · DynamoDBDocumentClient · Credential providers. New here? Read Concepts next for the vocabulary and the additive-params model.

Install

npm install dynamodb-toolkit @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

The toolkit declares both AWS SDK packages as peer dependencies — your project supplies them. Requires Node 20+ (works on the latest Bun and Deno too).

Minimal example

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient} from '@aws-sdk/lib-dynamodb';
import {Adapter} from 'dynamodb-toolkit';

const client = new DynamoDBClient({region: 'us-east-1'});
const docClient = DynamoDBDocumentClient.from(client, {
  marshallOptions: {removeUndefinedValues: true}
});

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

await adapter.put({name: 'Alderaan', diameter: 12500}, {force: true});

const planet = await adapter.getByKey({name: 'Alderaan'});
// → {name: 'Alderaan', diameter: 12500}

await adapter.patch({name: 'Alderaan'}, {diameter: 13000});
await adapter.delete({name: 'Alderaan'});

Recommended client construction

DynamoDBDocumentClient.from(...) with removeUndefinedValues: true is the v2-parity setup — it lets undefined values be stripped instead of throwing. Use the credential providers from @aws-sdk/credential-providers for non-default credential chains:

import {fromIni} from '@aws-sdk/credential-providers';

const client = new DynamoDBClient({
  region: 'us-east-1',
  credentials: fromIni({profile: 'staging'})
});

Mass writes

await adapter.putAll([
  {name: 'Tatooine', climate: 'arid'},
  {name: 'Hoth', climate: 'frozen'},
  {name: 'Bespin', climate: 'temperate'}
]);
// → {processed: 3}

Listing with pagination

const page = await adapter.getAllByParams({}, {offset: 0, limit: 10});
// → {data: [...], offset: 0, limit: 10, total: N}

REST handler

Drop a node:http server in front of the Adapter:

import {createServer} from 'node:http';
import {createHandler} from 'dynamodb-toolkit/handler';

const handler = createHandler(adapter);
createServer(handler).listen(3000);

The standard route pack lives at HTTP handler.

What to read next

• Concepts for the vocabulary (technical fields, additive-params model, GSI/projection/KeyCondition, SDK-link conventions).
• Adapter for the constructor + method surface.
• Adapter: Hooks to customize prepare / revive / validateItem / checkConsistency.
• Migration: v2 to v3 if you're upgrading from v2.