Merge pull request #786 from jeremydaly/document-transactions

Document transactions

docs/docs/2-tables/2-actions/4-batch-get/index.md

@@ -25,6 +25,8 @@ const pokeCmd = PokeTable.build(BatchGetCommand).requests(
   PokemonEntity.build(BatchGetRequest).key(charizardKey)
 )
 
+const params = pokeCmd.params()
+
 const otherCmd = OtherTable.build(BatchGetCommand).requests(
   TrainerEntity.build(BatchGetRequest).key(ashKey)
 )
@@ -166,7 +168,7 @@ const commands: (
   OtherTable.build(BatchGetCommand).requests(...)
 ]
 
-await execute(commands)
+await execute(...commands)
 ```
 
 </TabItem>

docs/docs/2-tables/2-actions/5-batch-write/index.md

@@ -26,6 +26,8 @@ const pokeCmd = PokeTable.build(BatchWriteCommand).requests(
   PokemonEntity.build(BatchPutRequest).item(charizard)
 )
 
+const params = pokeCmd.params()
+
 const ashCmd = OtherTable.build(BatchWriteCommand).requests(
   TrainerEntity.build(BatchDeleteRequest).key(ashKey)
 )
@@ -107,7 +109,7 @@ import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'
 
 const documentClient = new DynamoDBDocumentClient(...)
 
-const { Response } = await execute(
+await execute(
   { documentClient },
   ...batchWriteCommands
 )

docs/docs/3-entities/3-actions/10-tansact-get/index.md

@@ -0,0 +1,198 @@
+---
+title: TransactGet
+sidebar_custom_props:
+  sidebarActionType: read
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# GetTransaction
+
+Builds a transaction to get an entity item, to be used within [TransactGetItems operations](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html).
+
+BatchGetItem operations can affect **multiple items**, so `GetTransactions` do not have a `.send(...)` method. Instead, they should be performed via the dedicated `execute` function:
+
+```ts
+import {
+  GetTransaction,
+  execute
+} from 'dynamodb-toolbox/entity/actions/transactGet'
+
+const pikachuTransac =
+  PokemonEntity.build(GetTransaction).key(pikachuKey)
+
+const params = pikachuTransac.params()
+
+const ashTransac =
+  TrainerEntity.build(GetTransaction).key(ashKey)
+
+const { Responses } = await execute(
+  pikachuTransac,
+  ashTransac,
+  ...otherTransacs
+)
+
+// 🙌 Correctly typed!
+const [{ Item: pikachu }, { Item: ash }] = Responses
+```
+
+## Request
+
+### `.key(...)`
+
+<p style={{ marginTop: '-15px' }}><i>(required)</i></p>
+
+The key of the item to get (i.e. attributes that are tagged as part of the primary key):
+
+```ts
+const request = PokemonEntity.build(GetTransaction).key({
+  pokemonId: 'pikachu1'
+})
+```
+
+You can use the `KeyInput` type from the [`EntityParser`](../16-parse/index.md) action to explicitely type an object as a `GetTransaction` key:
+
+```ts
+import type { KeyInput } from 'dynamodb-toolbox/entity/actions/parse'
+
+const key: KeyInput<typeof PokemonEntity> = {
+  pokemonId: 'pikachu1'
+}
+
+const request =
+  PokemonEntity.build(BatchGetRequest).key(key)
+```
+
+### `.options(...)`
+
+Provides additional options:
+
+```ts
+const transaction = PokemonEntity.build(GetTransaction)
+  .key(...)
+  .options({
+    attributes: ["name", "level"]
+  })
+```
+
+You can use the `GetTransactionOptions` type to explicitely type an object as a `GetTransaction` options:
+
+```ts
+import type { GetTransactionOptions } from 'dynamodb-toolbox/entity/actions/transactGet'
+
+const options: GetTransactionOptions<typeof PokemonEntity> =
+  { attributes: ['name', 'level'] }
+
+const transaction = PokemonEntity.build(PutTransaction)
+  .key(...)
+  .options(options)
+```
+
+Available options are (see the [DynamoDB documentation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html#API_TransactGetItems_RequestParameters) for more details):
+
+| Option       |       Type       | Default | Description                                                                                                                                                                                                               |
+| ------------ | :--------------: | :-----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `attributes` | `Path<Entity>[]` |    -    | To specify a list of attributes to retrieve (improves performances but does not reduce costs).<br/><br/>See the [`PathParser`](../18-parse-paths/index.md#paths) action for more details on how to write attribute paths. |
+
+```ts
+PokemonEntity.build(GetTransaction)
+  .key(...)
+  .options({
+    attributes: ['name', 'level']
+  })
+```
+
+## Execution
+
+```ts
+import { execute } from 'dynamodb-toolbox/entity/actions/transactGet'
+
+await execute(...getTransactions)
+```
+
+Note that the transactions can be provided as **tuples** or **arrays** (the output is typed accordingly):
+
+:::noteExamples
+
+<Tabs>
+<TabItem value="tuple" label="Tuple">
+
+```ts
+await execute(
+  PokemonEntity.build(GetTransaction).key(pikachuKey),
+  TrainerEntity.build(GetTransaction).key(ashKey),
+  ...
+)
+```
+
+</TabItem>
+<TabItem value="array" label="Array">
+
+```ts
+const commands: (
+  | GetTransaction<typeof PokemonEntity>
+  | GetTransaction<typeof TrainerEntity>
+)[] = [
+  PokemonEntity.build(GetTransaction).key(pikachuKey),
+  TrainerEntity.build(GetTransaction).key(ashKey),
+  ...
+]
+
+await execute(...commands)
+```
+
+</TabItem>
+</Tabs>
+
+:::
+
+### Options
+
+The `execute` function accepts an additional object as a first argument for **operation-level** options:
+
+```ts
+await execute(options, ...batchGetCommands)
+```
+
+Available options are (see the [DynamoDB documentation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html#API_TransactGetItems_RequestParameters) for more details):
+
+| Option           |       Type       | Default  | Description                                                                                                                                                                              |
+| ---------------- | :--------------: | :------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `capacity`       | `CapacityOption` | `"NONE"` | Determines the level of detail about provisioned or on-demand throughput consumption that is returned in the response.<br/><br/>Possible values are `"NONE"`, `"TOTAL"` and `"INDEXES"`. |
+| `documentClient` | `DocumentClient` |    -     | By default, the `documentClient` attached to the `Table` of the first `GetTransaction` entity is used to execute the operation.<br/><br/>Use this option to override this behavior.      |
+
+:::noteExamples
+
+<Tabs>
+<TabItem value="capacity" label="Capacity">
+
+```ts
+const { ConsumedCapacity } = await execute(
+  { capacity: 'TOTAL' },
+  ...getTransactions
+)
+```
+
+</TabItem>
+<TabItem value="document-client" label="Document client">
+
+```ts
+import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'
+
+const documentClient = new DynamoDBDocumentClient(...)
+
+const { Response } = await execute(
+  { documentClient },
+  ...getTransactions
+)
+```
+
+</TabItem>
+</Tabs>
+
+:::
+
+### Response
+
+The data is returned with the same response syntax as the [DynamoDB TransactGetItems API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactGetItems.html#API_TransactGetItems_ResponseSyntax). Items are formatted by their respective entities.

docs/docs/3-entities/3-actions/12-tansact-put/index.md → docs/docs/3-entities/3-actions/11-tansact-put/index.md

@@ -4,20 +4,28 @@ sidebar_custom_props:
   sidebarActionType: write
 ---
 
-# PutItemTransaction
+# PutTransaction
 
 Builds a transaction to put an entity item, to be used within [TransactWriteItems operations](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html):
 
 ```ts
 import { execute } from 'dynamodb-toolbox/entity/actions/transactWrite'
-import { PutItemTransaction } from 'dynamodb-toolbox/entity/actions/transactPut'
+import { PutTransaction } from 'dynamodb-toolbox/entity/actions/transactPut'
 
-const transaction = PokemonEntity.build(PutItemTransaction)
+const transaction = PokemonEntity.build(PutTransaction)
 
 const params = transaction.params()
-await execute([transaction, ...otherTransactions])
+await execute(transaction, ...otherTransactions)
 ```
 
+`PutTransactions` can be executed in conjunction with [`UpdateTransactions`](../12-tansact-update/index.md), [`DeleteTransactions`](../13-tansact-delete/index.md) and [`ConditionChecks`](../14-condition-check/index.md).
+
+:::info
+
+Check the [Transaction Documentation](../9-transactions/index.md#transactwrite) to learn more on the `execute` function.
+
+:::
+
 ## Request
 
 ### `.item(...)`
@@ -27,7 +35,7 @@ await execute([transaction, ...otherTransactions])
 The item to write:
 
 ```ts
-const transaction = PokemonEntity.build(PutItemTransaction)
+const transaction = PokemonEntity.build(PutTransaction)
   .item({
     pokemonId: 'pikachu1',
     name: 'Pikachu',
@@ -37,7 +45,7 @@ const transaction = PokemonEntity.build(PutItemTransaction)
   })
 ```
 
-You can use the `PutItemInput` type from the [`PutItemCommand`](../2-put-item/index.md) action to explicitely type an object as a `PutItemTransaction` item:
+You can use the `PutItemInput` type from the [`PutItemCommand`](../2-put-item/index.md) action to explicitely type an object as a `PutTransaction` item:
 
 ```ts
 import type { PutItemInput } from 'dynamodb-toolbox/entity/actions/put'
@@ -48,48 +56,47 @@ const item: PutItemInput<typeof PokemonEntity> = {
   ...
 }
 
-const transaction = PokemonEntity.build(
-  PutItemTransaction
-).item(item)
+const transaction =
+  PokemonEntity.build(PutTransaction).item(item)
 ```
 
 ### `.options(...)`
 
 Provides additional options:
 
 ```ts
-const transaction = PokemonEntity.build(PutItemTransaction)
+const transaction = PokemonEntity.build(PutTransaction)
   .item(...)
   .options({
     // 👇 Checks that item didn't previously exist
     condition: { attr: 'pokemonId', exists: false }
   })
 ```
 
-You can use the `PutItemTransactionOptions` type to explicitely type an object as a `PutItemTransaction` options:
+You can use the `PutTransactionOptions` type to explicitely type an object as a `PutTransaction` options:
 
 ```ts
-import type { PutItemTransactionOptions } from 'dynamodb-toolbox/entity/actions/transactPut'
+import type { PutTransactionOptions } from 'dynamodb-toolbox/entity/actions/transactPut'
 
-const options: PutItemTransactionOptions<
+const options: PutTransactionOptions<
   typeof PokemonEntity
 > = {
   condition: { attr: 'pokemonId', exists: false }
 }
 
-const transaction = PokemonEntity.build(PutItemTransaction)
+const transaction = PokemonEntity.build(PutTransaction)
   .item(...)
   .options(options)
 ```
 
 Available options are (see the [DynamoDB documentation](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html#API_TransactWriteItems_RequestParameters) for more details):
 
-| Option      |               Type                | Default | Description                                                                                                                                                                                                                       |
-| ----------- | :-------------------------------: | :-----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `condition` | `Condition<typeof PokemonEntity>` |    -    | A condition that must be satisfied in order for the `PutItemTransaction` to succeed.<br/><br/>See the [`ConditionParser`](../17-parse-condition/index.md#building-conditions) action for more details on how to write conditions. |
+| Option      |               Type                | Default | Description                                                                                                                                                                                                                   |
+| ----------- | :-------------------------------: | :-----: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `condition` | `Condition<typeof PokemonEntity>` |    -    | A condition that must be satisfied in order for the `PutTransaction` to succeed.<br/><br/>See the [`ConditionParser`](../17-parse-condition/index.md#building-conditions) action for more details on how to write conditions. |
 
 ```ts
-PokemonEntity.build(PutItemTransaction)
+PokemonEntity.build(PutTransaction)
   .item(...)
   .options({
     condition: { attr: 'pokemonId', exists: false }