PutTransaction

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

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

const transaction = PokemonEntity.build(PutTransaction)

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

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

info

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

Request

.item(...)

(required)

The item to write:

const transaction = PokemonEntity.build(PutTransaction)
  .item({
    pokemonId: 'pikachu1',
    name: 'Pikachu',
    pokeType: 'electric',
    level: 50,
    ...
  })

You can use the PutItemInput type from the PutItemCommand action to explicitly type an object as a PutTransaction item object:

import type { PutItemInput } from 'dynamodb-toolbox/entity/actions/put'

const item: PutItemInput<typeof PokemonEntity> = {
  pokemonId: 'pikachu1',
  name: 'Pikachu',
  ...
}

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

.options(...)

Provides additional options:

const transaction = PokemonEntity.build(PutTransaction)
  .item(...)
  .options({
    // 👇 Checks that item didn't previously exist
    condition: { attr: 'pokemonId', exists: false }
  })

You can use the PutTransactionOptions type to explicitly type an object as a PutTransaction options object:

import type { PutTransactionOptions } from 'dynamodb-toolbox/entity/actions/transactPut'

const options: PutTransactionOptions<
  typeof PokemonEntity
> = {
  condition: { attr: 'pokemonId', exists: false }
}

const transaction = PokemonEntity.build(PutTransaction)
  .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 PutTransaction 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(PutTransaction)
  .item(...)
  .options({
    // 👇 Checks that item didn't previously exist
    condition: { attr: 'pokemonId', exists: false },
    // 👇 Includes the Item in the error if so
    returnValuesOnConditionFalse: 'ALL_OLD'
  })

Multitenant

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

info

Contrary to PutItemCommands, put transactions cannot return the previous values of the written items.