Skip to main content

ConditionCheck

Builds a condition to check against an entity item for the transaction to succeed, to be used within TransactWriteItems operations:

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

const transaction = PokemonEntity.build(ConditionCheck)

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

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

info

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

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.

Request​

.key(...)​

(required)

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

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

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

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

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

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

.condition(...)​

(required)

The condition to check against:

const transaction = PokemonEntity.build(ConditionCheck)
  .key(...)
  .condition({ attr: 'level', gte: 50 })

See the ConditionParser action for more details on how to write conditions.

.options(...)​

Provides additional options:

const transaction = PokemonEntity.build(ConditionCheck)
  .options({ ... })

You can use the ConditionCheckOptions type to explicitly type an object as a ConditionCheck options object:

import type { ConditionCheckOptions } from 'dynamodb-toolbox/entity/actions/transactCheck'

const options: ConditionCheckOptions<
  typeof PokemonEntity
> = { ... }

const transaction = PokemonEntity.build(ConditionCheck)
  .options(options)

Available options:

OptionTypeDefaultDescription
returnValuesOnConditionFalseReturnValuesOption"NONE"To get the item attributes if the condition fails.

Possible values are "NONE" and "ALL_OLD".
tableNamestring-Overrides the Table name. Mostly useful for multitenancy.
Examples
const transaction = PokemonEntity.build(ConditionCheck)
  .key(...)
  // 👇 Makes sure level is above 50
  .condition({ attr: 'level', gte: 50 })
  .options({
    // 👇 Includes the Item in the error if not so
    returnValuesOnConditionFalse: 'ALL_OLD'
  })