Transactions

Transactions are all or nothing, meaning the entire transaction will succeed, or the entire transaction will fail. In the event the transaction fails, state of the database will be the same as if the transaction did not take place. You can also run transaction across multiple tables at once.

transactionGet(transactions, options?)

Description

This function is used to get multiple items in a single transaction. It uses the TransactGetItems DynamoDB operation.

Arguments

transactions: TransactionGet[] - Array of get operations generated with EntityManager.transactionGet(primaryKey, options?) method.

You can add optional options parameter that is an object. The table below represents options that you can pass in:

Name	Description	Type	Default
return	What the method should return. For 'default' method returns initialized classes with retrieved data. For 'input' method returns prepared DynamoDB input command and no request is made to DynamoDB (method no longer returns a promise). For 'output' method returns the bare output from DynamoDB operation.	'default' | 'input' | 'output'	'default'
throwOnNotFound	By default Dynamode will throw an error in case an item was not found. If you want to prevent throwing errors when items are not found set throwOnNotFound prop to false.	boolean	true
extraInput	Extra input that is passed to TransactGetItems DynamoDB operation. Use it only in case that you know what are you are doing as it may override other properties passed to DynamoDB operation.	TransactGetItemsCommandInput	undefined

Examples

return: 'default'

const transactions = await transactionGet(
  [
    KeyValueManager.transactionGet({ key: 'key1' }), 
    UserManager.transactionGet({ partitionKey: '1', sortKey: 'blazej' }),
  ]
);
// OR 
const transactions = await transactionGet(
  [
    KeyValueManager.transactionGet({ key: 'key1' }), 
    UserManager.transactionGet({ partitionKey: '1', sortKey: 'blazej' }),
  ],
  {
    return: 'default'
  }
);

Output:

{
  items: [
    KeyValue {
      dynamodeEntity: 'KeyValue',
      key: 'key1',
      value: [Object]
    },
    User {
      dynamodeEntity: 'User',
      partitionKey: '1',
      sortKey: 'blazej',
      username: 'blazej',
      email: 'blazej@gmail.com',
      age: 18,
      friends: [Array],
      config: [Object]
    }
  ],
  count: 2
}

return: 'input'

const input = transactionGet(
  [
    KeyValueManager.transactionGet({ key: 'key1' }), 
    UserManager.transactionGet({ partitionKey: '1', sortKey: 'blazej' }),
  ],
  {
    return: 'input'
  },
);

Output:

{
  TransactItems: [
    { Get: [Object] },
    { Get: [Object] }
  ]
}

return: 'output'

const output = await transactionGet(
  [
    KeyValueManager.transactionGet({ key: 'key1' }), 
    UserManager.transactionGet({ partitionKey: '1', sortKey: 'blazej' }),
  ],
  {
    return: 'output'
  },
);

Output:

{
  '$metadata': {
    ...
  },
  ConsumedCapacity: undefined,
  Responses: [ { Item: [Object] }, { Item: [Object] } ]
}

transactionWrite(transactions, options?)

Description

This function is used to insert/update/delete multiple items in a single transaction. It uses the TransactWriteItems DynamoDB operation.

Arguments

transactions: TransactionWrite[] - Array of operations generated with methods that are described below:

Method	Description
EntityManager.transaction.put(item, options?)	Insert an item to DynamoDB.
EntityManager.transaction.create(item, options?)	Insert an item to DynamoDB (without overwrite).
EntityManager.transaction.update(primaryKey, props, options?)	Update an item in DynamoDB.
EntityManager.transaction.delete(primaryKey, options?)	Delete an item in DynamoDB.
EntityManager.transaction.condition(primaryKey, conditionInstance)	Condition for the transaction.

You can add optional options parameter that is an object. The table below represents options that you can pass in:

Name	Description	Type	Default
return	What the method should return. For 'default' method returns inserted/updated/deleted classes. For 'input' method returns prepared DynamoDB input command and no request is made to DynamoDB (method no longer returns a promise). For 'output' method returns the bare output from DynamoDB operation.	'default' | 'input' | 'output'	'default'
idempotencyKey	Providing a idempotencyKey makes the call idempotent, meaning that multiple identical calls have the same effect as one single call. It uses DynamoDB's ClientRequestToken.	string	undefined
extraInput	Extra input that is passed to TransactWriteItems DynamoDB operation. Use it only in case that you know what are you are doing as it may override other properties passed to DynamoDB operation.	TransactWriteItemsCommandInput	undefined

Examples

return: 'default'

const transactions = await transactionWrite(
  [
    UserManager.transaction.update(
      { partitionKey: '1', sortKey: 'blazej' },
      {
        set: {
          age: 18,
        },
      },
    ),
    KeyValueManager.transaction.put(
      new KeyValue({
        key: 'key2',
        value: { test: 'test2' },
      }),
    ),
    KeyValueManager.transaction.create(
      new KeyValue({
        key: 'key3',
        value: { test: 'test3' },
      }),
    ),
    KeyValueManager.transaction.delete({ key: 'key4' }),
    KeyValueManager.transaction.condition({ key: 'key5' }, KeyValueManager.condition().attribute('key').eq('key5')),
  ],
);
// OR
const transactions = await transactionWrite(
  [
    UserManager.transaction.update(
      { partitionKey: '1', sortKey: 'blazej' },
      {
        set: {
          age: 18,
        },
      },
    ),
    KeyValueManager.transaction.put(
      new KeyValue({
        key: 'key2',
        value: { test: 'test2' },
      }),
    ),
    KeyValueManager.transaction.create(
      new KeyValue({
        key: 'key3',
        value: { test: 'test3' },
      }),
    ),
    KeyValueManager.transaction.delete({ key: 'key4' }),
    KeyValueManager.transaction.condition({ key: 'key5' }, KeyValueManager.condition().attribute('key').eq('key5')),
  ],
  { return: 'default' },
);

Output:

{
  items: [
    KeyValue {
      dynamodeEntity: 'KeyValue',
      key: 'key2',
      value: [Object]
    },
    KeyValue {
      dynamodeEntity: 'KeyValue',
      key: 'key3',
      value: [Object]
    }
  ],
  count: 2
}

return: 'input'

const input = transactionWrite(
  [
    UserManager.transaction.update(
      { partitionKey: '1', sortKey: 'blazej' },
      {
        set: {
          age: 18,
        },
      },
    ),
    KeyValueManager.transaction.put(
      new KeyValue({
        key: 'key2',
        value: { test: 'test2' },
      }),
    ),
    KeyValueManager.transaction.create(
      new KeyValue({
        key: 'key3',
        value: { test: 'test3' },
      }),
    ),
    KeyValueManager.transaction.delete({ key: 'key4' }),
    KeyValueManager.transaction.condition({ key: 'key5' }, KeyValueManager.condition().attribute('key').eq('key5')),
  ],
  { return: 'input' },
);

Output:

{
  TransactItems: [
    { Update: [Object] },
    { Put: [Object] },
    { Put: [Object] },
    { Delete: [Object] },
    { ConditionCheck: [Object] }
  ],
  ClientRequestToken: undefined
}

return: 'output'

const output = await transactionWrite(
  [
    UserManager.transaction.update(
      { partitionKey: '1', sortKey: 'blazej' },
      {
        set: {
          age: 18,
        },
      },
    ),
    KeyValueManager.transaction.put(
      new KeyValue({
        key: 'key2',
        value: { test: 'test2' },
      }),
    ),
    KeyValueManager.transaction.create(
      new KeyValue({
        key: 'key3',
        value: { test: 'test3' },
      }),
    ),
    KeyValueManager.transaction.delete({ key: 'key4' }),
    KeyValueManager.transaction.condition({ key: 'key5' }, KeyValueManager.condition().attribute('key').eq('key5')),
  ],
  { return: 'output' },
);

Output:

{
  '$metadata': {
    ...
  },
  ConsumedCapacity: undefined,
  ItemCollectionMetrics: undefined
}