DeleteTransaction

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

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

const transaction = PokemonEntity.build(DeleteTransaction)

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

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

info

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

Request

.key(...)

(required)

The key of the item to delete (i.e. attributes that are tagged as part of the primary key):

const transaction = PokemonEntity.build(
  DeleteTransaction
).key({ pokemonId: 'pikachu1' })

You can use the KeyInputItem generic type to explicitly type an object as a BatchDeleteItemRequest key object:

import type { KeyInputItem } from 'dynamodb-toolbox/entity'

const key: KeyInputItem<typeof PokemonEntity> = {
  pokemonId: 'pikachu1'
}

const transaction = PokemonEntity.build(
  DeleteTransaction
).key(key)

.options(...)

Provides additional options:

const transaction = PokemonEntity.build(
  DeleteTransaction
)
  .key(...)
  .options({
    condition: { attr: 'archived', eq: true }
  })

You can use the DeleteTransactionOptions type to explicitly type an object as a DeleteTransaction options object:

import type { DeleteTransactionOptions } from 'dynamodb-toolbox/entity/actions/transactDelete'

const options: DeleteTransactionOptions<
  typeof PokemonEntity
> = {
  condition: { attr: 'archived', eq: true }
}

const transaction = PokemonEntity.build(
  DeleteTransaction
)
  .key(...)
  .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 DeleteTransaction 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

const transaction = PokemonEntity.build(DeleteTransaction)
  .key({ pokemonId: 'pikachu1' })
  .options({
    // 👇 Makes sure pokemon was archived
    condition: { attr: 'archived', eq: true },
    // 👇 Includes the Item in the error if not so
    returnValuesOnConditionFalse: 'ALL_OLD'
  })

Multitenant

const transaction = PokemonEntity.build(DeleteTransaction)
  .key({ pokemonId: 'pikachu1' })
  .options({
    tableName: `tenant-${tenantId}-pokemons`
  })

info

Contrary to DeleteItemCommand, delete transactions cannot return the values of the deleted items.