UpdateTransaction

Builds a transaction to update an entity item, to be used within TransactWriteItems operations:

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

const transaction = PokemonEntity.build(UpdateTransaction)

const params = transaction.params()
await execute(transaction, ...otherTransactions)

UpdateTransactions can be executed in conjunction with PutTransactions, DeleteTransactions and ConditionChecks.

info

Check the Transaction Documentation to learn more about the execute function.

Request

.item(...)

(required)

The attributes to update, including the key:

import { $add } from 'dynamodb-toolbox/entity/actions/update'

const transaction = PokemonEntity.build(UpdateTransaction)
  .item({
    pokemonId: 'pikachu1',
    level: $add(1),
    ...
  })

Check the UpdateItemCommand action to learn more about the UpdateItem syntax. You can use the UpdateItemInput type to explicitly type an object as an UpdateTransaction item object:

import type { UpdateItemInput } from 'dynamodb-toolbox/entity/actions/update'

const item: UpdateItemInput<typeof PokemonEntity> = {
  pokemonId: 'pikachu1',
  level: $add(1),
  ...
}

const transaction = PokemonEntity.build(
  UpdateTransaction
).item(item)

.options(...)

Provides additional options:

const transaction = PokemonEntity.build(UpdateTransaction)
  .item({
    pokemonId: 'pikachu1',
    level: $add(1),
    ...
  })
  .options({
    // 👇 Make sure that 'level' stays <= 99
    condition: { attr: 'level', lt: 99 }
  })

You can use the UpdateTransactionOptions type to explicitly type an object as a UpdateTransaction options object:

import type { UpdateTransactionOptions } from 'dynamodb-toolbox/entity/actions/transactUpdate'

const options: UpdateTransactionOptions<
  typeof PokemonEntity
> = {
  condition: { attr: 'level', lt: 99 }
}

const transaction = PokemonEntity.build(UpdateTransaction)
  .item(...)
  .options(options)

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

Option	Type	Default	Description
condition	Condition<typeof PokemonEntity>	-	A condition that must be satisfied in order for the UpdateTransaction to succeed. See the ConditionParser action for more details on how to write conditions.
returnValuesOnConditionFalse	ReturnValuesOption	"NONE"	To get the item attributes if the condition fails. Possible values are "NONE" and "ALL_OLD".
tableName	string	-	Overrides the Table name. Mostly useful for multitenancy.

Examples

Conditional write

PokemonEntity.build(UpdateTransaction)
  .item(...)
  .options({
    // 👇 Makes sure that 'level' stays <= 99
    condition: { attr: 'level', lt: 99 },
    // 👇 Includes the Item in the error if not so
    returnValuesOnConditionFalse: 'ALL_OLD'
  })

Multitenant

PokemonEntity.build(UpdateTransaction)
  .item(...)
  .options({
    tableName: `tenant-${tenantId}-pokemons`
  })

info

Contrary to UpdateItemCommands, update transactions cannot return the previous or new values of the written items.