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 provide a callback to partially update previous options:

const multiTenantTransaction = conditionCheck.options(
  prevOptions => ({ ...prevOptions, tableName: 'my-table' })
)

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:

Option	Type	Default	Description
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

Examples

Basic

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

Return Values

const transac = PokemonEntity.build(ConditionCheck)
  .key(...)
  // 👇 Makes sure level is above 50
  .condition({ attr: 'level', gte: 50 })
  // 👇 Includes the Item in the error if not so
  .options({ returnValuesOnConditionFalse: 'ALL_OLD' })

Multitenant

const transac = PokemonEntity.build(ConditionCheck)
  .key(...)
  .condition(...)
  .options({ tableName: `tenant-${tenantId}-pokemons` })