DeleteItemCommand

Performs a DeleteItem Operation on an entity item:

import { DeleteItemCommand } from 'dynamodb-toolbox/entity/actions/delete'

const deleteItemCommand = PokemonEntity.build(
  DeleteItemCommand
)

const params = deleteItemCommand.params()
await deleteItemCommand.send()

Request

.key(...)

(required)

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

await PokemonEntity.build(DeleteItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .send()

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

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

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

await PokemonEntity.build(DeleteItemCommand).key(key).send()

.options(...)

Provides additional options:

await PokemonEntity.build(DeleteItemCommand)
  .key(...)
  .options({
    returnValues: 'ALL_OLD',
    capacity: 'TOTAL',
    ...
  })
  .send()

You can use the DeleteItemOptions type to explicitly type an object as DeleteItemCommand options object:

import type { DeleteItemOptions } from 'dynamodb-toolbox/entity/actions/delete'

const options: DeleteItemOptions<typeof PokemonEntity> = {
  returnValues: 'ALL_OLD',
  capacity: 'TOTAL',
  ...
}

await PokemonEntity.build(DeleteItemCommand)
  .key(...)
  .options(options)
  .send()

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 DeleteItemCommand to succeed. See the ConditionParser action for more details on how to write conditions.
returnValues	ReturnValuesOption	"NONE"	To get the item attributes as they appeared before they were deleted with the request. Possible values are "NONE" and "ALL_OLD".
returnValuesOnConditionFalse	ReturnValuesOption	"NONE"	To get the item attributes if the condition fails. Possible values are "NONE" and "ALL_OLD".
metrics	MetricsOption	"NONE"	Determines whether item collection metrics are returned. Possible values are "NONE" and "SIZE".
capacity	CapacityOption	"NONE"	Determines the level of detail about provisioned or on-demand throughput consumption that is returned in the response. Possible values are "NONE", "TOTAL" and "INDEXES".
tableName	string	-	Overrides the Table name. Mostly useful for multitenancy.

Examples

Conditional write

await PokemonEntity.build(DeleteItemCommand)
  .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'
  })
  .send()

Return values

const { Attributes: prevPikachu } =
  await PokemonEntity.build(DeleteItemCommand)
    .key({ pokemonId: 'pikachu1' })
    .options({
      returnValues: 'ALL_OLD'
    })
    .send()

Multitenancy

await PokemonEntity.build(DeleteItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .options({
    tableName: `tenant-${tenantId}-pokemons`
  })
  .send()

Aborted

const abortController = new AbortController()
const abortSignal = abortController.signal

await PokemonEntity.build(DeleteItemCommand)
  .key({ pokemonId: 'pikachu1' })
  .send({ abortSignal })

// 👇 Aborts the command
abortController.abort()

Response

The data is returned using the same response syntax as the DynamoDB DeleteItem API. If present, the returned item is formatted by the Entity.

You can use the DeleteItemResponse type to explicitly type an object as a DeleteItemCommand response object:

import type { DeleteItemResponse } from 'dynamodb-toolbox/entity/actions/delete'

const deleteItemResponse: DeleteItemResponse<
  typeof PokemonEntity,
  // 👇 Optional options
  { returnValues: 'ALL_OLD' }
  // 👇 Typed as Pokemon | undefined
> = { Attributes: ... }