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.

Multi-Entity Transactions

Use the TableTransactWrite and TableTransactGet commands to perform transactional operations across multiple entity types in a single DynamoDB request. These are the Document Builder table-level commands executed via table.send().

Preparing Entities

Before passing entity operations to a table-level command, use entity.prepare() to bind each operation to its entity.

For transactional writes, pass an array of write commands:

const userWrites = userEntity.prepare([
  new Put({ item: { userId: 'u1', name: 'Alice', email: 'alice@example.com' } }),
  new Delete({ key: { userId: 'u2', email: 'bob@example.com' } }),
]);

For transactional reads, pass a TransactGet command:

const orderGets = orderEntity.prepare(new TransactGet({
  keys: [{ orderId: 'o1' }, { orderId: 'o2' }],
}));

Multi-Entity Transactional Writes

Pass prepared write groups to TableTransactWrite and execute via table.send(). The entire operation is all-or-nothing — either every write succeeds or none are applied.

await myTable.send(
  new TableTransactWrite({
    transactions: [
      userEntity.prepare([
        new Put({
          item: { userId: 'u1', name: 'Alice', email: 'alice@example.com' },
        }),
        new Delete({
          key: { userId: 'u99', email: 'old@example.com' },
        }),
      ]),
      orderEntity.prepare([
        new Update({
          key: { orderId: 'o1' },
          updates: { status: 'shipped' },
        }),
      ]),
    ],
  }),
);

TableTransactWrite supports all the same write commands as the single-entity TransactWrite:

Idempotency Token

Pass an idempotencyToken to ensure the transaction is only applied once, even if the request is retried. DynamoDB treats duplicate requests with the same token within 10 minutes as no-ops.

await myTable.send(
  new TableTransactWrite({
    transactions: [...],
    idempotencyToken: 'unique-request-token-123',
  }),
);

Multi-Entity Transactional Reads

Pass prepared get groups to TableTransactGet and execute via table.send(). Like TransactGet, this is an all-or-nothing, strongly consistent read — either all items are retrieved or none are.

const { items } = await myTable.send(
  new TableTransactGet({
    gets: [
      userEntity.prepare(new TransactGet({
        keys: [
          { userId: 'u1', email: 'alice@example.com' },
          { userId: 'u2', email: 'bob@example.com' },
        ],
      })),
      orderEntity.prepare(new TransactGet({
        keys: [{ orderId: 'o1' }, { orderId: 'o2' }],
      })),
    ],
  }),
);

The items field is a typed tuple that matches the order of the input gets array. Each index is typed to its corresponding entity, with undefined for keys where no item was found:

const [users, orders] = items;
// users: (User | undefined)[]
// orders: (Order | undefined)[]

// Items preserve the original key order
if (users[0]) {
  console.log('First user:', users[0].name);
}

Table Validation

All entity groups in a TableTransactWrite or TableTransactGet must belong to the same table that table.send() is called on. If any entity references a different table, a DocumentBuilderError is thrown at runtime before any DynamoDB request is made.

// This will throw a DocumentBuilderError at runtime
await tableA.send(new TableTransactGet({
  gets: [
    entityOnTableA.prepare(new TransactGet({ keys: [...] })),
    entityOnTableB.prepare(new TransactGet({ keys: [...] })), // ❌ Wrong table
  ],
}));

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`.

TableTransactWrite Command Config

The TableTransactWrite command expects the following input config:

{
  transactions: PreparedWriteTransaction[];
  idempotencyToken?: string;
  returnItemCollectionMetrics?: ReturnItemCollectionMetrics;
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`transactions` (required)	`PreparedWriteTransaction[]`	An array of prepared write transaction groups, each created via `entity.prepare([...writes])`. All entities must belong to the same table.
`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 and return success without reapplying the writes.
`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`.

TableTransactWrite Command Result

The TableTransactWrite 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`.

TableTransactGet Command Config

The TableTransactGet command expects the following input config:

{
  gets: PreparedGetTransaction[];
  skipValidation?: boolean;
  timeoutMs?: number;
  abortController?: AbortController;
  returnConsumedCapacity?: ReturnConsumedCapacity;
}

Property	Type	Description
`gets` (required)	`PreparedGetTransaction[]`	An array of prepared transactional get groups, each created via `entity.prepare(new TransactGet({ ... }))`. All entities must belong to the same table.
`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`.

TableTransactGet Command Result

The TableTransactGet command returns the following result:

{
  items: Array<(Schema | undefined)[]>;  // tuple, one entry per get group
  responseMetadata?: ResponseMetadata;
  consumedCapacity?: ConsumedCapacity;
}

Property	Type	Description
`items`	`Array<(Schema \| undefined)[]>`	A tuple (one entry per get group in input order) of retrieved items for each entity. Items within each group are in the same order as the keys provided. An item is `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.

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';
import { TableTransactWrite } from 'dynamo-document-builder/commands/table-transact-write';
import { TableTransactGet } from 'dynamo-document-builder/commands/table-transact-get';