Transactions

Use the TransactGet and TransactWrite commands to perform transactional read and write operations in DynamoDB. These are the Document Builder commands for TransactGetItems and TransactWriteItems operations.

Transactional Reads

The TransactGet command enables you to retrieve multiple items by primary key in a single operation:

const transactGet = new TransactGet({
  keys: [
    { userId: '123', todoId: '456' },
    { userId: '789', todoId: '101' },
  ],
});

const { items } = await todoEntity.send(transactGet);
console.log(items);

Transactional Writes

The TransactWrite command enables you to perform multiple write operations in a single atomic transaction. This commands works slightly differently than other Document Builder commands in that it wraps other commands into a single prepared transaction.

const transactWrite = new TransactWrite({
  writes: [
    new Put({
      item: {
        userId: '123',
        todoId: '456',
        title: 'Take out the trash',
        completed: false,
      },
    }),
    new Delete({
      key: {
        userId: '789',
        todoId: '101',
      },
    }),
  ],
});

In the above example, a Put and Delete command are wrapped into a single transaction. Either both operations will succeed, or neither will be applied.

Supported Write Operations

TransactWrite supports the following commands that can be passed as writes:

Condition Checks

While TransactWrite supports all of the conditional version of writes (such as ConditionalPut), these conditions are scoped to the individual write operation. For use cases when you want to add a separate condition check to the transaction, you can use the special ConditionCheck command.

const transactWrite = new TransactWrite({
  writes: [
    new ConditionCheck({
      key: {
        userId: '123',
        todoId: '456',
      },
      condition: {
        completed: false,
      }
    }),
    new Update({
      key: {
        userId: '123',
        todoId: '456',
      },
      updates: {
        completed: true,
      },
    }),
  ],
});

This command can only be used in the context of a TransactWrite operation.

Transact Get Command Config

The TransactGet command expects the following input config:

{
  keys: Array<Partial<Schema>>;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`keys` (required)	`Array<Partial<Schema>>`	An array of primary keys for the items to retrieve transactionally. Each key should contain the attributes that make up the primary key. If using computed primary keys, only include the attributes used by your key builder functions.
`skipValidation?`	`boolean`	If set to true, schema validation is bypassed entirely. Defaults to `false`.
`timeoutMs?`	`number`	Number of milliseconds to wait before the operation times out and auto-cancels.
`abortController?`	`AbortController`	If you need to abort the commands operation, you can use the abort controller to signal cancellation.
`returnConsumedCapacity?`	`ReturnConsumedCapacity`	Determines the level of detail about provisioned throughput consumption that is returned in the response. Valid values are `TOTAL`, `INDEXES`, and `NONE`.

Transact Get Command Result

The TransactGet command returns the following result:

{
  items: Array<Schema | undefined>;
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity;
}

Property	Type	Description
`items`	`Array<Schema \| undefined>`	An array of retrieved items in the same order as the keys provided. An item will be `undefined` if no item was found for the corresponding key.
`responseMetadata?`	`ResponseMetadata`	Metadata about the response from DynamoDB.
`consumedCapacity?`	`ConsumedCapacity`	Information about the capacity units consumed by the operation, if requested via the `returnConsumedCapacity` config.

Transact Write Command Config

The TransactWrite command expects the following input config:

{
  writes: WriteTransactable<Schema>[];
  idempotencyToken?: string;
  returnItemCollectionMetrics?: ReturnItemCollectionMetrics;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`writes` (required)	`WriteTransactable<Schema>[]`	An array of write operations to execute transactionally. Valid write operations include `Put`, `ConditionalPut`, `Update`, `ConditionalUpdate`, `Delete`, `ConditionalDelete`, and `ConditionCheck` commands.
`idempotencyToken`	`string`	A unique token for ensuring idempotent transactions. If the same token is provided within 10 minutes, DynamoDB will treat it as a duplicate request.
`returnItemCollectionMetrics`	`ReturnItemCollectionMetrics`	Determines whether item collection metrics are returned. Valid values are `SIZE` and `NONE`.
`skipValidation?`	`boolean`	If set to true, schema validation is bypassed entirely. Defaults to `false`.
`timeoutMs?`	`number`	Number of milliseconds to wait before the operation times out and auto-cancels.
`abortController?`	`AbortController`	If you need to abort the commands operation, you can use the abort controller to signal cancellation.
`returnConsumedCapacity?`	`ReturnConsumedCapacity`	Determines the level of detail about provisioned throughput consumption that is returned in the response. Valid values are `TOTAL`, `INDEXES`, and `NONE`.

Transact Write Command Result

The TransactWrite command returns the following result:

{
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity[];
  itemCollectionMetrics?: ItemCollectionMetrics;
}

Property	Type	Description
`responseMetadata?`	`ResponseMetadata`	Metadata about the response from DynamoDB.
`consumedCapacity?`	`ConsumedCapacity[]`	An array of consumed capacity units for each table or index accessed during the transaction, if requested via `returnConsumedCapacity`.
`itemCollectionMetrics?`	`ItemCollectionMetrics`	Information about item collection metrics, if requested via `returnItemCollectionMetrics`.

Tree-shakable Imports

import { TransactGet } from 'dynamo-document-builder/commands/transact-get';
import { TransactWrite } from 'dynamo-document-builder/commands/transact-write';
import { ConditionCheck } from 'dynamo-document-builder/commands/condition-check';