PutItemCommand

Performs a PutItem Operation on an entity item:

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

const putItemCommand = PokemonEntity.build(PutItemCommand)

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

Request

.item(...)

(required)

The item to write:

await PokemonEntity.build(PutItemCommand)
  .item({
    pokemonId: 'pikachu1',
    name: 'Pikachu',
    pokeType: 'electric',
    level: 50,
    ...
  })
  .send()

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

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

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

await PokemonEntity.build(PutItemCommand).item(item).send()

.options(...)

Provides additional options:

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

You can use the PutItemOptions type to explicitly type an object as a PutItemCommand options object:

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

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

await PokemonEntity.build(PutItemCommand)
  .item(...)
  .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 PutItemCommand 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 updated 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(PutItemCommand)
  .item({
    pokemonId: 'pikachu1',
    name: 'Pikachu',
    pokeType: 'electric',
    level: 50
  })
  .options({
    // 👇 Checks that item didn't previously exist
    condition: { attr: 'pokemonId', exists: false },
    // 👇 Includes the Item in the error if so
    returnValuesOnConditionFalse: 'ALL_OLD'
  })
  .send()

Return values

const { Attributes: prevPikachu } =
  await PokemonEntity.build(PutItemCommand)
    .item({
      pokemonId: 'pikachu1',
      name: 'Pikachu',
      pokeType: 'electric',
      level: 50
    })
    .options({
      returnValues: 'ALL_OLD'
    })
    .send()

Multitenant

await PokemonEntity.build(PutItemCommand)
  .item({
    pokemonId: 'pikachu1',
    name: 'Pikachu',
    pokeType: 'electric',
    level: 50
  })
  .options({
    tableName: `tenant-${tenantId}-pokemons`
  })
  .send()

Aborted

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

await PokemonEntity.build(PutItemCommand)
  .item({
    pokemonId: 'pikachu1',
    name: 'Pikachu',
    pokeType: 'electric',
    level: 50
  })
  .send({ abortSignal })

// 👇 Aborts the command
abortController.abort()

Response

The data is returned using the same response syntax as the DynamoDB PutItem API, with an additional ToolboxItem property, which allows you to retrieve the item generated by DynamoDB-Toolbox:

const { ToolboxItem: generatedPokemon } =
  await PokemonEntity.build(PutItemCommand)
    .item(...)
    .send()

// 👇 Great for auto-generated attributes
const createdTimestamp = generatedPokemon.created

If present, the returned item is formatted by the Entity.

You can use the PutItemResponse type to explicitly type an object as a PutItemCommand response object:

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

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