-
Notifications
You must be signed in to change notification settings - Fork 167
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #786 from jeremydaly/document-transactions
Document transactions
- Loading branch information
Showing
19 changed files
with
475 additions
and
92 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.