Mass operations

Mass operations

dynamodb-toolkit/mass exports primitives the Adapter composes for its mass methods (see Adapter:-Mass-methods). Use them directly when you need finer control or when you don't have an Adapter.

import {
  paginateList, iterateList, iterateItems,
  readList, readListGetItems, readListByKeys, readOrderedListByKeys,
  writeList, deleteList, deleteListByKeys,
  copyList, moveList, getTotal
} from 'dynamodb-toolkit/mass';

Pagination

paginateList(client, params, options?, needTotal?, minLimit?, maxLimit?)

Offset/limit pagination over a Query or Scan. Returns {data, offset, limit, total?}.

When params.FilterExpression is set, paginateList accumulates matches across pages — DynamoDB's Limit is pre-filter, so naive use returns short pages and false-empty results. paginateList paginates until enough matches are accumulated.

const r = await paginateList(client, {TableName: 'planets'}, {offset: 0, limit: 10});
// → {data: [...10 items...], offset: 0, limit: 10, total: 61}

needTotal: false skips the Select: 'COUNT' round trips for the rest of the dataset — much cheaper for endless-scroll feeds.

Iteration

iterateList(client, params) and iterateItems(client, params)

Async generators. iterateList yields raw page objects; iterateItems yields individual items.

for await (const item of iterateItems(client, {TableName: 'planets'})) {
  console.log(item.name);
}

Single-page reads

readList(client, params, fn) / readListGetItems(client, params)

readList calls fn(page) once, then returns nextParams | null for chaining. readListGetItems returns {nextParams, items} directly.

Batch reads by key

readListByKeys(client, table, keys, params?)

Wrapper over getBatch that returns just the items as a plain array.

const items = await readListByKeys(client, 'planets', [{name: 'Hoth'}, {name: 'Bespin'}]);

readOrderedListByKeys(client, table, keys, params?)

Same but preserves caller key order, with undefined for missing keys. The SDK's BatchGetItem returns items in arbitrary order — this helper rebuilds the original order.

const items = await readOrderedListByKeys(client, 'planets', [{name: 'A'}, {name: 'B'}, {name: 'C'}]);
// items[0] is A, items[1] is B, items[2] is C — or undefined for misses

Mass writes

writeList(client, table, items, mapFn?)

BatchWriteItem puts. Returns the count of items processed.

await writeList(client, 'planets', planets, item => ({...item, '-t': 1}));

deleteList(client, params, keyFn?) / deleteListByKeys(client, table, keys)

deleteList reads via scan/query then batch-deletes the matching keys. keyFn extracts the key from each item.

deleteListByKeys batch-deletes a list of keys directly.

copyList(client, params, mapFn?)

Read items via scan/query, optionally transform, batch-write back to the same table.

moveList(client, params, mapFn?, keyFn?)

Read via scan/query, paired puts + deletes per chunk (12 puts + 12 deletes per BatchWrite to stay under the 25-action limit). Returns the total batch-actions count (puts + deletes).

Counting

getTotal(client, params)

Select: 'COUNT' pagination — counts items matching the query/scan without returning them. Useful for the total in pagination envelopes when needTotal: true.