transactPut

Introduction

transactPut method performs transact put request using aws-sdk TransactWriteItemsCommand.

In addition to TransactWriteItemsCommandOutput transactPut response will include Items which is fully typed based on your Schema declaration.
Items is usefull as your Schema may include default, set or other transformer options.

execute

transactPut takes 2 arguments:

1. (required) list of object which:
   • must include item to be put
   • optionnally condition related to the same item.
   • optionnally ReturnValuesOnConditionCheckFailure
2. (optionnal) options

any invalid value in Item will lead to dev time and runtime error

const res = await User.transactPut(
  [
    {
      item: {
        id: "user-1",
        age: 27,
        firstname: "John",
        sex: "male",
        data: "something",
      },
    },
    {
      item: {
        id: "user-2",
        age: 22,
        firstname: "Sara",
        sex: "female",
        data: "something",
        friends: ["user-1"],
        isActive: false,
      },
      condition: {
        firstname: {
          $neq: "Sara",
        },
      },
    },
  ],
  { ReturnConsumedCapacity: "TOTAL" }
);

options

options is an object which accepts TransactWriteItemsCommandInput options and DynamoQL specific options.

exec

exec boolean directive to execute or not the actual request.
When false transactPut will return TransactWriteItemsCommandInput object.

import type { TransactWriteItemsCommandInput } from "@aws-sdk/client-dynamodb";

const cmd: TransactWriteItemsCommandInput = await User.transactPut(
  [
    {
      item: {
        id: "user-1",
        age: 27,
        firstname: "John",
        sex: "male",
        data: "something",
      },
    },
    {
      item: {
        id: "user-2",
        age: 22,
        firstname: "Sara",
        sex: "female",
        data: "something",
        friends: ["user-1"],
        isActive: false,
      },
    },
  ],
  { exec: false }
);

setterInfo

setterInfo allows you to pass any value to your Schema set function's third argument.

const res = await User.transactPut(
  [
    {
      item: {
        id: "user-1",
        age: 27,
        firstname: "John",
        sex: "male",
        data: "something",
      },
    },
    {
      item: {
        id: "user-2",
        age: 22,
        firstname: "Sara",
        sex: "female",
        data: "something",
        friends: ["user-1"],
        isActive: false,
      },
    },
  ],
  { setterInfo: { generateHash: true } }
);

check

ConditionCheck on the same table.

const res = await User.transactPut(
  [
    {
      item: {
        id: "user-1",
        age: 27,
        firstname: "John",
        sex: "male",
        data: "something",
      },
    },
    {
      item: {
        id: "user-2",
        age: 22,
        firstname: "Sara",
        sex: "female",
        data: "something",
        friends: ["user-1"],
        isActive: false,
      },
      condition: {
        firstname: {
          $neq: "Sara",
        },
      },
    },
  ],
  {
    check: [
      {
        id: "user-64",
        isActive: false,
      },
    ],
  }
);

If you need ConditionCheck on another table, use { exec: false } then merge your conditions manually.

import { TransactWriteItemsCommand } from "@aws-sdk/client-dynamodb";
import type { TransactWriteItemsInput } from "@aws-sdk/client-dynamodb";

const cmd: TransactWriteItemsInput = await User.transactPut(
  [
    {
      item: {
        id: "user-1",
        age: 27,
        firstname: "John",
        sex: "male",
        data: "something",
      },
    },
    {
      item: {
        id: "user-2",
        age: 22,
        firstname: "Sara",
        sex: "female",
        data: "something",
        friends: ["user-1"],
        isActive: false,
      },
    },
  ],
  { exec: false }
);

// pretending UserOrders is another instance of Model

const orderCheck: TransactWriteItemsInput = await UserOrders.transactWrite(
  [
    {
      check: [
        {
          id: "user-id",
          orders: {
            $size: 0,
          },
        },
      ],
    },
  ],
  { exec: false }
);

cmd.TransactItems.push(orderCheck.TransactItems[0]);

await User.client.send(new TransactWriteItemsCommand(cmd));