Adapter： Mass methods

Adapter: Mass methods

Bulk operations over many items. All return {processed: number}.

See also (AWS JS SDK v3): BatchWriteCommand · BatchGetCommand · BatchWriteItem API · BatchGetItem API. Vocabulary: Concepts.

Method	Strategy
putItems(items, options?)	'native' (default) → BatchWriteItem. 'sequential' → individual Put per item.
deleteByKeys(keys, options?)	Same dual strategy.
deleteListByParams(params, options?)	Read keys via scan/query, delete in batches.
cloneByKeys(keys, mapFn?, options?)	BatchGet + BatchWrite.
cloneListByParams(params, mapFn?, options?)	Read items via scan/query, write transformed copies.
moveByKeys(keys, mapFn?, options?)	BatchGet + paired put/delete chunks (12 puts + 12 deletes per BatchWrite).
moveListByParams(params, mapFn?, options?)	Read via scan/query, paired put/delete chunks.

interface MassOptions {
  strategy?: 'native' | 'sequential';
  params?: object;
}

mapFn defaults to identity

cloneByKeys, cloneListByParams, moveByKeys, moveListByParams all accept an optional mapFn. When omitted, the item is copied/moved as-is (the default is the identity function, x => x). Without a mapFn, clone-to-same-key throws ConditionalCheckFailedException (the Adapter's default write path adds an existence condition); the common case is to supply a mapFn that rewrites the key or some attribute so the destination is distinct. See Adapter: CRUD methods clone / move for the single-item version of the same pattern.

Examples

// Bulk load
const r = await adapter.putItems(planets);
// → {processed: 61}

// Delete by keys
await adapter.deleteByKeys([{name: 'Hoth'}, {name: 'Bespin'}]);

// Delete via filter
await adapter.deleteListByParams({
  TableName: 'planets',
  FilterExpression: 'climate = :c',
  ExpressionAttributeValues: {':c': 'frozen'}
});

// Clone with overlay — mapFn rewrites the key + transforms an attribute
await adapter.cloneByKeys(
  [{name: 'Tatooine'}, {name: 'Hoth'}],
  item => ({...item, name: item.name + '-copy', diameter: item.diameter * 2})
);

// Move (rename) under a transform — atomic put + delete within each chunk
await adapter.moveByKeys(
  [{name: 'old-name'}],
  item => ({...item, name: 'new-name'})
);

Underlying primitives

The mass methods compose on top of dynamodb-toolkit/mass helpers (writeList, deleteList, copyList, moveList, …) plus the dynamodb-toolkit/batch chunkers. See Mass operations and Batch and transactions for the standalone API.

Strategy choice

• native — default. Maximizes throughput by batching and lets lib-dynamodb's UnprocessedItems retry handle backpressure. Loses per-item conditions (BatchWriteItem doesn't support them).
• sequential — slower; one Command per item. Each item flows through the full single-op path including checkConsistency, so per-item transactions and conditions work as expected. Use when you need per-item validation or can't tolerate partial-batch failures.