Transactions

TransactGet

DynamoDB-Toolbox exposes the GetTransaction actions to perform TransactGetItems operations.

TransactWrite

DynamoDB-Toolbox exposes the following actions to perform TransactWriteItems operations:

• PutTransaction: Builds a transaction to put an entity item
• UpdateTransaction: Builds a transaction to update an entity item
• DeleteTransaction: Builds a transaction to delete an entity item
• ConditionCheck: Builds a condition to check against an entity item for the transaction to succeed

TransactWriteItems operations can affect multiple items, so transactions do not have a .send(...) method. Instead, they should be performed via the dedicated execute function:

import { execute } from 'dynamodb-toolbox/entity/actions/transactWrite'

const put = PokemonEntity.build(PutTransaction).item(...)
const update = PokemonEntity.build(UpdateTransaction).item(...)
const del = PokemonEntity.build(DeleteTransaction).key(...)
const check = PokemonEntity.build(ConditionCheck).key(...).condition(...)

await execute(put, update, del, check, ...otherTransactions)

warning

Only one transaction per item is supported. For instance, you cannot run a ConditionCheck and an UpdateTransaction on the same item: You can, however, condition the UpdateTransaction itself.

Options

The execute function accepts an additional object as a first argument for operation-level options, as well as DocumentClient options such as abortSignal:

await execute(options, ...writeTransactions)

Available options (see the DynamoDB documentation for more details):

Option	Type	Default	Description
capacity	CapacityOption	"NONE"	Determines the level of detail about provisioned or on-demand throughput consumption that is returned in the response. Possible values are "NONE", "TOTAL" and "INDEXES".
metrics	MetricsOption	"NONE"	Determines whether item collection metrics are returned. Possible values are "NONE" and "SIZE".
clientRequestToken	string	-	Providing a clientRequestToken makes the execution idempotent, meaning that multiple identical calls have the same effect as one single call.
documentClient	DocumentClient	-	By default, the documentClient attached to the Table of the first WriteTransaction is used to execute the operation. Use this option to override this behavior.

Examples

Capacity

const { ConsumedCapacity } = await execute(
  { capacity: 'TOTAL' },
  ...writeTransactions
)

Metrics

const { ItemCollectionMetrics } = await execute(
  { metrics: 'SIZE' },
  ...writeTransactions
)

Client request token

await execute(
  { clientRequestToken: '123' },
  ...writeTransactions
)

Document client

import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'

const documentClient = new DynamoDBDocumentClient(...)

await execute(
  { documentClient },
  ...writeTransactions
)

Aborted

const abortController = new AbortController()
const abortSignal = abortController.signal

await execute({ abortSignal }, ...writeTransactions)

// 👇 Aborts the command
abortController.abort()

Response

The data is returned using the same response syntax as the DynamoDB TransactWriteItems API, with an additional ToolboxItems property, which allows you to retrieve the items generated by DynamoDB-Toolbox in PutTransactions and UpdateTransactions:

const { ToolboxItems } = await execute(
  putTransaction,
  deleteTransaction,
  conditionCheck,
  updateTransaction
)

const [
  putPokemon,
  // 👇 Both undefined
  _,
  __,
  updatedPokemon
] = ToolboxItems

// 👇 Great for auto-generated attributes
const createdTimestamp = putPokemon.created
const modifiedTimestamp = updatedPokemon.modified