DynamoDB Toolbox

https://www.dynamodbtoolbox.com/docs
Admin
A toolkit for simplifying interactions with AWS DynamoDB, providing abstractions for databases,...
Tokens:114,609
Snippets:1,178
Trust Score:7.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install DynamoDB-Toolbox

Source: https://www.dynamodbtoolbox.com/docs/getting-started/installation

Install the core library using your preferred package manager.

```bash
# npm  
npm install dynamodb-toolbox  
  
# pnpm  
pnpm add dynamodb-toolbox  
  
# yarn  
yarn add dynamodb-toolbox
```

--------------------------------

### Basic BatchWriteCommand Example

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-write

A simple example of building a BatchWriteCommand with multiple put requests.

```typescript
const command = PokeTable.build(BatchWriteCommand).requests(
  PokemonEntity.build(BatchPutRequest).item(pikachu),
  PokemonEntity.build(BatchPutRequest).item(charizard)
)
```

--------------------------------

### Execution Examples

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/transact-get

Various examples demonstrating basic usage, capacity configuration, custom document clients, and abort signals.

```typescript
const pikachuTransac =  
  PokemonEntity.build(GetTransaction).key(...)  
  
const ashTransac =  
  TrainerEntity.build(GetTransaction).key(...)  
  
const { Responses } = await execute(  
  pikachuTransac,  
  ashTransac,  
  ...otherTransacs  
)
```

```typescript
const { ConsumedCapacity } = await execute(  
  { capacity: 'TOTAL' },  
  ...getTransactions  
)
```

```typescript
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'  
  
const documentClient = new DynamoDBDocumentClient(...)  
  
const { Responses } = await execute(  
  { documentClient },  
  ...getTransactions  
)
```

```typescript
const abortController = new AbortController()  
const abortSignal = abortController.signal  
  
const { Responses } = await execute(  
  { abortSignal },  
  ...getTransactions  
)  
  
// 👇 Aborts the command  
abortController.abort()
```

--------------------------------

### Example InputItem for 'update' mode

Source: https://www.dynamodbtoolbox.com/docs/entities/type-inference

An example of an InputItem for the 'update' mode, showing attributes that can be updated.

```json
{
  "pokemonClass": "bulbasaur",
  "pokemonId": "123",
  "name": "PlantyDino",
}
```

--------------------------------

### Example InputItem for 'put' mode

Source: https://www.dynamodbtoolbox.com/docs/entities/type-inference

An example of an InputItem for the 'put' mode, showing required attributes before transformation.

```json
{
  "pokemonClass": "pikachu",
  "pokemonId": "123",
  "name": "Pikachu"
}
```

--------------------------------

### Example InputItem for 'key' mode

Source: https://www.dynamodbtoolbox.com/docs/entities/type-inference

An example of an InputItem for the 'key' mode, where only key attributes are required.

```json
{
  "pokemonClass": "pikachu",
  "pokemonId": "123",
}
```

--------------------------------

### Basic ConditionCheck Example

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/condition-check

A simple example demonstrating the initialization of a ConditionCheck transaction with a specified key.

```typescript
const transac = PokemonEntity.build(ConditionCheck).key({  
  pokemonId: 'pikachu1'  
})
```

--------------------------------

### Install Peer Dependencies

Source: https://www.dynamodbtoolbox.com/docs/getting-started/installation

Install the required AWS SDK client and library packages as peer dependencies.

```bash
# npm  
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb  
  
# pnpm  
pnpm add @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb  
  
# yarn  
yarn add @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```

--------------------------------

### Basic ConditionCheck Transaction Setup

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/condition-check

Demonstrates the basic setup for a ConditionCheck transaction. This snippet shows how to initialize a ConditionCheck for an entity and prepare it for execution within a transaction.

```typescript
import { execute } from 'dynamodb-toolbox/entity/actions/transactWrite'  
import { ConditionCheck } from 'dynamodb-toolbox/entity/actions/transactCheck'  
  
const transaction = PokemonEntity.build(ConditionCheck)  
  
const params = transaction.params()  
await execute(transaction, ...otherTransactions)
```

--------------------------------

### Initialize MCPToolkit

Source: https://www.dynamodbtoolbox.com/docs/databases/actions/mcp-toolkit

Setup the MCPToolkit and register tools with an existing McpServer instance.

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
import { MCPToolkit } from 'dynamodb-toolbox/database/actions/mcpToolkit'

// Set up your MCP Server as usual
const server = new McpServer(...)

const mcpToolkit = PokeDB.build(MCPToolkit)
mcpToolkit.addTools(server)
```

--------------------------------

### Key Mode Examples

Source: https://www.dynamodbtoolbox.com/docs/schemas/type-inference

Input, Valid, and Transformed values for the 'key' mode.

```json
{
  "pokemonClass": "pikachu",
  "pokemonId": "123",
}
+ // (Only key attributes are required)
```

```json
{
  "pokemonClass": "pikachu",
  "pokemonId": "123",
}
```

```json
{
- "pokemonClass": "pikachu",
+ "partitionKey": "POKEMON#pikachu",
- "pokemonId": "123",
+ "sortKey": "123",
}
```

--------------------------------

### Example ValidItem for 'put' mode

Source: https://www.dynamodbtoolbox.com/docs/entities/type-inference

An example of a ValidItem for the 'put' mode, showing attributes after defaults and transformations are applied.

```json
{
  "pokemonClass": "pikachu",
  "pokemonId": "123",
  "created": "2022-01-01T00:00:00.000Z",
  "modified": "2022-01-01T00:00:00.000Z",
  "name": "Pikachu",
  "level": 1,
  "levelPlusOne": 2,
}
```

--------------------------------

### Formatter Start Method

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/format

Use the start method to return a generator for inspecting intermediate formatting results.

```typescript
const formattingGenerator = pokemonSchema  
  .build(Formatter)  
  .start(pokemon)  
  
const transformedPokemon = formattingGenerator.next().value  
const formattedPokemon = formattingGenerator.next().value  
```

```typescript
const formattingGenerator = pokemonSchema  
  .build(Formatter)  
  .start(pokemon, { transform: false })  
  
// 👇 No `transform` step  
const formattedPokemon = formattingGenerator.next().value  
```

--------------------------------

### Put Mode Examples

Source: https://www.dynamodbtoolbox.com/docs/schemas/type-inference

Input, Valid, and Transformed values for the 'put' mode.

```json
{
  "pokemonClass": "pikachu",
  "pokemonId": "123",
  "name": "Pikachu"
}
```

```json
{
  "pokemonClass": "pikachu",
  "pokemonId": "123",
+ "created": "2022-01-01T00:00:00.000Z",
+ "modified": "2022-01-01T00:00:00.000Z",
  "name": "Pikachu",
+ "level": 1,
+ "levelPlusOne": 2,
}
```

```json
{
- "pokemonClass": "pikachu",
+ "partitionKey": "POKEMON#pikachu",
- "pokemonId": "123",
+ "sortKey": "123",
  "created": "2022-01-01T00:00:00.000Z",
  "modified": "2022-01-01T00:00:00.000Z",
  "name": "Pikachu",
  "level": 1,
  "levelPlusOne": 2,
}
```

--------------------------------

### start(input, options?)

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/format

Returns a Generator to inspect intermediate results of the formatting steps (transformation and formatting).

```APIDOC
## start(input, options?)

### Description
Similar to .format(), but returns a Generator that yields intermediate results of the formatting workflow.

### Parameters
- **input** (unknown) - Required - The input to process.
- **options** (FormatValueOptions) - Optional - Formatting options.

### Example
```typescript
const generator = pokemonSchema.build(Formatter).start(pokemon);
const transformed = generator.next().value;
const formatted = generator.next().value;
```
```

--------------------------------

### Extended Syntax: $get

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/update-item

Example of the $get symbol and its corresponding type guard.

```typescript
import {  
  $get,  
  $GET,  
  $IS_EXTENSION,  
  isGetting  
} from 'dynamodb-toolbox/entity/actions/update/symbols'  
  
const getting = $get('attr', 'fallback')  
  
// 👇 Equivalent to  
const getting = {  
  [$GET]: ['attr', 'fallback'],  
  [$IS_EXTENSION]: true  
}  
  
const link = (input: UpdateItemInput) => {  
  if (isGetting(input)) {  
    input[$GET] // => ['attr', 'fallback']  
  }  
}  
```

--------------------------------

### Update Mode Examples

Source: https://www.dynamodbtoolbox.com/docs/schemas/type-inference

Input, Valid, and Transformed values for the 'update' mode.

```json
{
  "pokemonClass": "bulbasaur",
  "pokemonId": "123",
  "name": "PlantyDino",
}
```

```json
{
  "pokemonClass": "bulbasaur",
  "pokemonId": "123",
+ "modified": "2022-01-01T00:00:00.000Z",
  "name": "PlantyDino",
}
```

```json
{
- "pokemonClass": "bulbasaur",
+ "partitionKey": "POKEMON#bulbasaur",
- "pokemonId": "123",
+ "sortKey": "123",
  "modified": "2022-01-01T00:00:00.000Z",
  "name": "PlantyDino",
}
```

--------------------------------

### BatchGetCommand Execution Example

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-get

Demonstrates building and executing a BatchGetCommand involving multiple tables and entities. It shows how to construct requests and retrieve typed responses.

```typescript
import {
  BatchGetCommand,
  execute
} from 'dynamodb-toolbox/table/actions/batchGet'
import { BatchGetRequest } from 'dynamodb-toolbox/entity/actions/batchGet'

const pokeCmd = PokeTable.build(BatchGetCommand).requests(
  PokemonEntity.build(BatchGetRequest).key(pikachuKey),
  PokemonEntity.build(BatchGetRequest).key(charizardKey)
)

const params = pokeCmd.params()

const otherCmd = OtherTable.build(BatchGetCommand).requests(
  TrainerEntity.build(BatchGetRequest).key(ashKey)
)

const { Responses } = await execute(pokeCmd, otherCmd)

// 🙌 Correctly typed!
const [[pikachu, charizard], [ash]] = Responses
```

--------------------------------

### Example TransformedItem for 'key' mode

Source: https://www.dynamodbtoolbox.com/docs/entities/type-inference

An example of a TransformedItem for the 'key' mode, showing how key attributes are renamed for DynamoDB storage.

```json
{
  "partitionKey": "POKEMON#pikachu",
  "sortKey": "123",
}
```

--------------------------------

### Example TransformedItem for 'put' mode

Source: https://www.dynamodbtoolbox.com/docs/entities/type-inference

An example of a TransformedItem for the 'put' mode, showing how attributes are renamed for DynamoDB storage.

```json
{
  "partitionKey": "POKEMON#pikachu",
  "sortKey": "123",
  "created": "2022-01-01T00:00:00.000Z",
  "modified": "2022-01-01T00:00:00.000Z",
  "name": "Pikachu",
  "level": 1,
  "levelPlusOne": 2,
}
```

--------------------------------

### Querying Partitions and Indexes

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/query

Examples of querying by partition key and handling multi-attribute keys in global secondary indexes.

```typescript
// Get 'ashKetchum' pokemons  
await PokeTable.build(QueryCommand)  
  .query({ partition: 'ashKetchum' })  
  .send()  
```

```typescript
await PokeTable.build(QueryCommand)  
  .query({  
    index: 'byTrainerIdCaptureYearPokeTypeAndLevel',  
    partition: ['ashKetchum', 2022], // trainerId > captureYear  
    range: ['fire', { gte: 50 }] // type > level (range must be last)  
  })  
  .send()  
```

--------------------------------

### Multitenant BatchWriteCommand Example

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-write

Shows how to configure a BatchWriteCommand with a specific tableName option for multitenant environments.

```typescript
const command = PokeTable.build(BatchWriteCommand)
  .requests(...)
  .options({ tableName: `tenant-${tenantId}-pokemons` })
```

--------------------------------

### start(input, options)

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/parse

Returns a Generator to inspect intermediate results of the parsing steps, such as filling defaults, linking, and transformation.

```APIDOC
## start(input, options)

### Description
Similar to .parse, but returns the underlying Generator to inspect the intermediate results of the parsing steps.

### Signature
`(input: unknown, options?: ParseValueOptions) => Generator<ParsingResults<SCHEMA>>`
```

--------------------------------

### Parsing Modes

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/parse

Examples demonstrating different parsing modes including put, key, and update.

```typescript
const pokemon = {  
  pokemonId: 'pikachu1',  
  name: 'Pikachu',  
  types: ['Electric'],  
  ...  
}  
  
const validPokemon = pokemonSchema.build(Parser).parse(pokemon)
```

```typescript
const validKey = pokemonSchema  
  .build(Parser)  
  .parse({ pokemonId: 'pikachu1' }, { mode: 'key' })
```

```typescript
const validUpdate = pokemonSchema  
  .build(Parser)  
  .parse(  
    { pokemonId: 'bulbasaur1', customName: 'PlantyDino' },  
    { mode: 'update' }  
  )
```

--------------------------------

### Transaction Examples

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/transact-put

Common patterns for basic, conditional, and multitenant put transactions.

```typescript
const transac = PokemonEntity.build(PutTransaction).item({  
  pokemonId: 'pikachu1',  
  name: 'Pikachu',  
  pokeType: 'electric',  
  level: 50  
})  
```

```typescript
const transac = PokemonEntity.build(PutTransaction)  
  .item(...)  
  .options({  
    // 👇 Checks that item didn't previously exist  
    condition: { attr: 'pokemonId', exists: false },  
    // 👇 Includes the Item in the error if so  
    returnValuesOnConditionFalse: 'ALL_OLD'  
  })  
```

```typescript
const transac = PokemonEntity.build(PutTransaction)  
  .item(...)  
  .options({ tableName: `tenant-${tenantId}-pokemons` })  
```

--------------------------------

### Example ValidItem for 'update' mode

Source: https://www.dynamodbtoolbox.com/docs/entities/type-inference

An example of a ValidItem for the 'update' mode, showing attributes after defaults and transformations, including modified timestamp.

```json
{
  "pokemonClass": "bulbasaur",
  "pokemonId": "123",
  "modified": "2022-01-01T00:00:00.000Z",
  "name": "PlantyDino",
}
```

--------------------------------

### Formatter Options Examples

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/format

Demonstrates various formatting options including partial updates, attribute selection, and disabling specific transformation or formatting steps.

```typescript
const transformed = {  
  pokemonId: 'pikachu1',  
  name: 'Pikachu'  
}  
  
// 🙌 Typed as `DeepPartial<FormattedPokemon>`  
const formatted = pokemonSchema  
  .build(Formatter)  
  .format(transformed, { partial: true })  
```

```typescript
const transformed = {  
  pokemonId: 'pikachu1',  
  name: 'Pikachu',  
  level: 42,  
  ...  
}  
  
// 🙌 Typed as `Pick<FormattedPokemon, 'name' | 'level'>`  
const formatted = pokemonSchema  
  .build(Formatter)  
  .format(transformed, { attributes: ['name', 'level'] })  
```

```typescript
// 👇 Not transformed  
const valid = {  
  pokemonId: 'pikachu1',  
  name: 'Pikachu',  
  level: 42,  
  ...  
}  
  
// 👇 Only omits hidden attributes  
const formatted = pokemonSchema  
  .build(Formatter)  
  .format(valid, { transform: false })  
```

```typescript
const transformed = {  
  pokemonId: 'pikachu1',  
  name: 'Pikachu',  
  level: 42,  
  ...  
}  
  
// 👇 Keeps hidden attributes  
const valid = pokemonSchema  
  .build(Formatter)  
  .format(transformed, { format: false })  
```

--------------------------------

### Install MCPToolkit dependencies

Source: https://www.dynamodbtoolbox.com/docs/databases/actions/mcp-toolkit

Required dependencies for using MCPToolkit in your project.

```bash
npm install zod @modelcontextprotocol/sdk
```

--------------------------------

### Schema Definition

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/parse

Example schema definition used for parsing demonstrations.

```typescript
const now = () => new Date().toISOString()  
  
const pokemonSchema = item({  
  // key attributes  
  pokemonClass: string()  
    .key()  
    .transform(prefix('POKEMON'))  
    .savedAs('partitionKey'),  
  pokemonId: string().key().savedAs('sortKey'),  
  
  // timestamps  
  created: string().default(now),  
  updated: string()  
    .required('always')  
    .putDefault(now)  
    .updateDefault(now),  
  
  // other attributes  
  name: string().optional(),  
  level: number().default(1)  
}).and(prevSchema => ({  
  levelPlusOne: number().link<typeof prevSchema>(  
    ({ level }) => level + 1  
  )  
}))  
```

--------------------------------

### Multitenant ConditionCheck Example

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/condition-check

Illustrates how to configure a ConditionCheck for a multitenant environment by overriding the table name using the `options` method.

```typescript
const transac = PokemonEntity.build(ConditionCheck)  
  .key(...)  
  .condition(...)  
  .options({ tableName: `tenant-${tenantId}-pokemons` })
```

--------------------------------

### DocumentClient Setup with AWS SDK

Source: https://www.dynamodbtoolbox.com/docs/tables/usage

Configures the DynamoDB-Toolbox Table with an AWS SDK DocumentClient instance. This is required for commands to interact with DynamoDB.

```javascript
// From peer dependencies  
import { DynamoDBClient } from '@aws-sdk/client-dynamodb'  
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'  
  
const dynamoDBClient = new DynamoDBClient()
  
const documentClient = DynamoDBDocumentClient.from(
  dynamoDBClient,
  {
    marshallOptions: {
      // Specify your client options as usual
      removeUndefinedValues: true,
      convertEmptyValues: false
      ...
    }
  }
)
  
const PokeTable = new Table({
  documentClient,
  ...
})
```

--------------------------------

### GetTransaction Examples

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/transact-get

Common usage patterns for basic retrieval, attribute projection, and multitenant table overrides.

```typescript
const transac = PokemonEntity.build(GetTransaction).key({  
  pokemonId: 'pikachu1'  
})
```

```typescript
const transac = PokemonEntity.build(GetTransaction)  
  .key({ pokemonId: 'pikachu1' })  
  .options({ attributes: ['type', 'level'] })
```

```typescript
const transac = PokemonEntity.build(GetTransaction)  
  .key({ pokemonId: 'pikachu1' })  
  .options({ tableName: `tenant-${tenantId}-pokemons` })
```

--------------------------------

### Transaction Input Formats

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/transact-get

Examples of passing transactions as arguments or using an array with 'as const'.

```typescript
await execute(  
  PokemonEntity.build(GetTransaction).key(pikachuKey),  
  TrainerEntity.build(GetTransaction).key(ashKey),  
  ...  
)  
  
// Using the `as const` statement also works  
const transactions = [  
  PokemonEntity.build(GetTransaction).key(pikachuKey),  
  TrainerEntity.build(GetTransaction).key(ashKey),  
  ...  
] as const  
await execute(...transactions)
```

```typescript
const commands = [  
  PokemonEntity.build(GetTransaction).key(pikachuKey),  
  TrainerEntity.build(GetTransaction).key(ashKey),  
  ...  
]  
  
// Equivalent to:  
const commands: (  
  | GetTransaction<typeof PokemonEntity>  
  | GetTransaction<typeof TrainerEntity>  
)[] = [...]  
  
await execute(...commands)
```

--------------------------------

### Building and Executing an UpdateTransaction

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/transact-update

Basic setup for building an update transaction and executing it with other transactions.

```typescript
import { execute } from 'dynamodb-toolbox/entity/actions/transactWrite'  
import { UpdateTransaction } from 'dynamodb-toolbox/entity/actions/transactUpdate'  
  
const transaction = PokemonEntity.build(UpdateTransaction)  
  
const params = transaction.params()  
await execute(transaction, ...otherTransactions)  
```

--------------------------------

### Initialize Database with Registry

Source: https://www.dynamodbtoolbox.com/docs/databases/usage

Demonstrates how to build a Registry and then initialize the Database class with it. Shows how to access tables, entities, and access patterns through the Database instance.

```typescript
import { Database } from 'dynamodb-toolbox/database'  
  
// Build `Registry` first  
const PokeRegistry = PokeTable.build(Registry)  
  .registerEntities(TrainerEntity, PokemonEntity)  
  .registerAccessPatterns({ trainers, trainerPokemons })  
  
const PokeDB = new Database({
  pokedex: PokeRegistry  
})
  
// Get a Registry by key  
PokeDB.tables.pokedex  
  
// Get an Entity by `entityName`  
PokeDB.tables.pokedex.entities.trainer  
  
// Get an AccessPattern by key  
PokeDB.tables.pokedex.accessPatterns.trainers.query(...)
  
// Or use the `.query` shorthand  
PokeDB.tables.pokedex.query.trainers(...)

```

--------------------------------

### Get Attribute Reference

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/update-attributes

Using $get to reference existing attribute values during an update.

```typescript
import { $get } from 'dynamodb-toolbox/entity/actions/update'  
  
await PokemonEntity.build(UpdateAttributesCommand)  
  .item({  
    ...  
    level: 42,  
    // 👇 fill 'previousLevel' with current 'level'  
    previousLevel: $get('level')  
  })  
  .send()
```

--------------------------------

### Building Database Actions with MCPToolkit

Source: https://www.dynamodbtoolbox.com/docs/databases/usage

Demonstrates how to use the `.build()` method on a Database instance to create specific database actions, such as the MCPToolkit. This is recommended for extensibility, code-splitting, and lighter bundles.

```typescript
import { MCPToolkit } from 'dynamodb-toolbox/database/actions/mcpToolkit'  

const mcpToolkit = PokeDB.build(MCPToolkit)

```

--------------------------------

### Using Query Shorthand for AccessPatterns

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/registry

Provides an example of using the `query` shorthand property on the Registry to access registered access patterns' query methods.

```typescript
PokeRegistry.query.trainers(...)  
  
// 👇 Equivalent to  
PokeRegistry.accessPatterns.trainers.query(...)  
```

--------------------------------

### Include Metadata in JSON Schema

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/json-schemer

Shows how meta attributes like title, description, and examples are mapped to JSON Schema keywords.

```typescript
const levelSchema = number().meta({  
  title: 'Level',  
  description: 'The Pokémon level',  
  examples: [42]  
})  
  
const jsonSchema = levelSchema  
  .build(JSONSchemer)  
  .formattedValueSchema()  
// =>  
// {  
//   type: 'number',  
//   title: 'Level',  
//   description: 'The Pokémon level',  
//   examples: [42]  
// }  
```

--------------------------------

### Basic Batch Get Execution

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-get

Executes batch get commands and returns the responses. Ensure `batchGetCommands` are properly defined.

```typescript
import { execute } from 'dynamodb-toolbox/table/actions/batchGet'  
  
const { Responses } = await execute(...batchGetCommands)
```

--------------------------------

### Basic QueryCommand Usage

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/query

Demonstrates how to import, build, and execute a basic query, including parameter retrieval and pagination.

```typescript
import { QueryCommand } from 'dynamodb-toolbox/table/actions/query'  
  
const queryCommand = PokeTable.build(QueryCommand)  
  
const params = queryCommand.params()  
const { Items } = await queryCommand.send()  
  
for await (const page of queryCommand.paginate()) {  
  const { Items } = page  
}  
```

--------------------------------

### BatchWriteCommand with Item Collection Metrics

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-write

Illustrates how to get item collection metrics for a batch write operation by setting the 'metrics' option to 'SIZE'.

```javascript
const { ItemCollectionMetrics } = await execute(
  { metrics: 'SIZE' },
  ...batchWriteCommands
)
```

--------------------------------

### Referencing Attributes with $get

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/update-item

Uses $get to resolve attribute values at write time, including support for fallbacks and chained references.

```typescript
import { $get } from 'dynamodb-toolbox/entity/actions/update'  
  
await PokemonEntity.build(UpdateItemCommand)  
  .item({  
    ...  
    level: 42,  
    // 👇 fill 'previousLevel' with current 'level'  
    previousLevel: $get('level')  
  })  
  .send()  
```

```typescript
await PokemonEntity.build(UpdateItemCommand)  
  .item({  
    ...  
    previousLevel: $get('level', 1),  
    // 👇 fallback can also be a reference!  
    chainedRefs: $get(  
      'firstRef',  
      $get('secondRef', 'Sky is the limit!')  
    )  
  })  
  .send()  
```

```typescript
await PokemonEntity.build(UpdateItemCommand)  
  .item({  
    ...  
    optionalAttribute: $get('optionalAttribute', 'fallback'),  
  })  
  .send()  
```

```typescript
await PokemonEntity.build(UpdateItemCommand)  
  .item({  
    // ❌ Raises a type error  
    name: $get('non.existing[0].attribute'),  
    // ...but overriding a number by a string doesn't 🙈  
    level: $get('name')  
  })  
  .send()  
```

--------------------------------

### Batch Get Request with EntityRepository

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/repository

Builds a request to get an entity item for use within BatchGetCommands. Specify the key of the item to retrieve.

```javascript
const request = pokemonRepository.batchGet({
  pokemonId: 'pikachu1'
})
```

--------------------------------

### Example TransformedItem for 'update' mode

Source: https://www.dynamodbtoolbox.com/docs/entities/type-inference

An example of a TransformedItem for the 'update' mode, showing how attributes are renamed for DynamoDB storage, including modified timestamp.

```json
{
  "partitionKey": "POKEMON#bulbasaur",
  "sortKey": "123",
  "modified": "2022-01-01T00:00:00.000Z",
  "name": "PlantyDino",
}
```

--------------------------------

### Batch Get with Abort Signal

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-get

Executes batch get operations with the ability to abort the request using an AbortSignal. This is useful for cancelling long-running operations.

```typescript
const abortController = new AbortController()  
const abortSignal = abortController.signal  
  
const { Response } = await execute(  
  { abortSignal },  
  ...batchGetCommands  
)  
  
// 👇 Aborts the command  
abortController.abort()
```

--------------------------------

### Build Table Actions using .build()

Source: https://www.dynamodbtoolbox.com/docs/tables/usage

Uses the `.build()` method as a gateway to perform table actions like Scan, Query, etc. This promotes extensibility, better code-splitting, and lighter bundles. Requires importing specific commands.

```javascript
import { ScanCommand } from 'dynamodb-toolbox/table/actions/scan'

const { Items } = await PokeTable.build(ScanCommand).send()
```

--------------------------------

### Batch Get with Tuple Commands

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-get

Executes batch get operations where commands are provided as tuples, allowing for items from different tables in a single execution.

```typescript
const { Response } = await execute(  
  PokeTable.build(BatchGetCommand).requests(...),  
  OtherTable.build(BatchGetCommand).requests(...),  
  ...  
)
```

--------------------------------

### Setting Options Directly

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/delete-partition

Use .options() to set command-specific configurations like consistency.

```javascript
await PokeTable.build(DeletePartitionCommand)  
  .options({
    consistent: true,  
    ...  
  })  
  .send()
```

--------------------------------

### Batch Get with Max Attempts Option

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-get

Executes batch get operations with automatic retries for failed requests. Configure `maxAttempts` to control the number of retries.

```typescript
const { Response } = await execute(  
  { maxAttempts: 3 },  
  ...batchGetCommands  
)
```

--------------------------------

### Batch Get with Capacity Option

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-get

Executes batch get operations and retrieves detailed capacity consumption information. Set `capacity` to 'TOTAL' or 'INDEXES' to enable this.

```typescript
const { ConsumedCapacity } = await execute(  
  { capacity: 'TOTAL' },  
  ...batchGetCommands  
)
```

--------------------------------

### Batch Get with Array Commands

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-get

Executes batch get operations where commands are provided as an array of `BatchGetCommand` objects. This is useful when commands are dynamically generated or collected.

```typescript
const commands: (  
  | BatchGetCommand<typeof PokeTable>  
  | BatchGetCommand<typeof OtherTable>  
)[] = [  
  PokeTable.build(BatchGetCommand).requests(...),  
  OtherTable.build(BatchGetCommand).requests(...)  
]  
  
const { Response } = await execute(...commands)
```

--------------------------------

### BatchGetCommand Usage

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-get

Demonstrates how to build and execute a BatchGetCommand involving multiple tables and entities. It shows the construction of requests and the final execution using the 'execute' function, along with accessing the typed responses.

```APIDOC
## BatchGetCommand

Groups one or several `BatchGetRequest` from the `Table` entities to execute a `BatchGetItem` operation.

`BatchGetItem` operations can affect **multiple tables**, so `BatchGetCommands` do not have a `.send(...)` method. Instead, they should be performed via the dedicated `execute` function:

```typescript
import {
  BatchGetCommand,
  execute
} from 'dynamodb-toolbox/table/actions/batchGet'
import { BatchGetRequest } from 'dynamodb-toolbox/entity/actions/batchGet'

const pokeCmd = PokeTable.build(BatchGetCommand).requests(
  PokemonEntity.build(BatchGetRequest).key(pikachuKey),
  PokemonEntity.build(BatchGetRequest).key(charizardKey)
)

const params = pokeCmd.params()

const otherCmd = OtherTable.build(BatchGetCommand).requests(
  TrainerEntity.build(BatchGetRequest).key(ashKey)
)

const { Responses } = await execute(pokeCmd, otherCmd)

// 🙌 Correctly typed!
const [[pikachu, charizard], [ash]] = Responses
```

### `.requests(...)`
_(required)_
The `BatchGetRequests` to execute. Note that the requests can be provided as **tuples** or **arrays** (the output is typed accordingly):

**Tuple Example:**
```typescript
const command = PokeTable.build(BatchGetCommand).requests(
  PokemonEntity.build(BatchGetRequest).key(pikachuKey),
  PokemonEntity.build(BatchGetRequest).key(charizardKey),
  ...
)
```

**Array Example:**
```typescript
const requests: BatchGetRequest<typeof PokemonEntity>[] = [
  PokemonEntity.build(BatchGetRequest).key(pikachuKey),
  PokemonEntity.build(BatchGetRequest).key(charizardKey),
  ...
]

const command =
  PokeTable.build(BatchGetCommand).requests(...requests)
```

### `.options(...)`
Provides additional **table-level** options:

**Basic Options Example:**
```typescript
const command = PokeTable.build(BatchGetCommand).options({
  consistent: true,
  ...
})
```

**Callback Options Example:**
```typescript
const consistentCommand = batchGetCommand.options(
  prevOptions => ({ ...prevOptions, consistent: true })
)
```

**Typed Options Example:**
```typescript
import type { BatchGetCommandOptions } from 'dynamodb-toolbox/table/actions/batchGet'

const batchGetOptions: BatchGetCommandOptions<
  // 👇 Optional entities
  [typeof PokemonEntity, typeof TrainerEntity]
> = {
  consistent: true,
  ...
}

const command = PokeTable.build(BatchGetCommand)
  .requests(...)
  .options(batchGetOptions)
```

**Available Options:**
- `consistent` (boolean, default: `false`): Use strongly consistent reads.
- `attributes` (string[]): Specify a list of attributes to retrieve.
- `tableName` (string): Overrides the `Table` name.
```

--------------------------------

### Batch Get with Custom Document Client

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-get

Executes batch get operations using a custom DynamoDB Document Client instance. This allows for specific configurations or shared client instances.

```typescript
import { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb'  
  
const documentClient = new DynamoDBDocumentClient(...)  
  
const { Response } = await execute(  
  { documentClient },  
  ...batchGetCommands  
)
```

--------------------------------

### BatchWriteCommand Usage

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/batch-write

Demonstrates how to build and execute BatchWriteCommands for both putting and deleting items, potentially across different tables. It shows the use of `build`, `requests`, `params`, and `execute`.

```APIDOC
## BatchWriteCommand

Groups one or several `BatchPutRequest` and `BatchDeleteRequest` from the `Table` entities to execute a `BatchWriteItem` operation.

`BatchWriteItem` operations can affect **multiple tables**, so `BatchWriteCommands` do not have a `.send(...)` method. Instead, they should be performed via the dedicated `execute` function:

```javascript
import { BatchWriteCommand, execute } from 'dynamodb-toolbox/table/actions/batchWrite'
import { BatchPutRequest } from 'dynamodb-toolbox/entity/actions/batchPut'
import { BatchDeleteRequest } from 'dynamodb-toolbox/entity/actions/batchDelete'

const pokeCmd = PokeTable.build(BatchWriteCommand).requests(
  PokemonEntity.build(BatchPutRequest).item(pikachu),
  PokemonEntity.build(BatchPutRequest).item(charizard)
)

const params = pokeCmd.params()

const ashCmd = OtherTable.build(BatchWriteCommand).requests(
  TrainerEntity.build(BatchDeleteRequest).key(ashKey)
)

await execute(pokeCmd, ashCmd)
```

### Request

#### `.requests(...)`
_(required)_
The `BatchPutRequests` and `BatchDeleteRequests` to execute.

#### `.options(...)`
Provides additional **table-level** options:

```javascript
const command = PokeTable.build(BatchWriteCommand).options({
  ...
})
```

You can **provide a callback** to partially update previous options:

```javascript
const multiTenantCommand = batchWriteCommand.options(
  prevOptions => ({ ...prevOptions, tableName: 'my-table' })
)
```

You can use the `BatchWriteCommandOptions` type to explicitly type an object as a `BatchWriteCommand` options object:

```javascript
import type { BatchWriteCommandOptions } from 'dynamodb-toolbox/table/actions/batchWrite'

const batchWriteOptions: BatchWriteCommandOptions= {
  ...
}

const command = PokeTable.build(BatchWriteCommand)
  .requests(...)
  .options(batchWriteOptions)
```

Available options:
Option| Type| Default| Description
---|---|---|---
`tableName`| `string`| -| Overrides the `Table` name. Mostly useful for multitenancy.

### Examples

* Basic
```javascript
const command = PokeTable.build(BatchWriteCommand).requests(
  PokemonEntity.build(BatchPutRequest).item(pikachu),
  PokemonEntity.build(BatchPutRequest).item(charizard)
)
```

* Multitenant
```javascript
const command = PokeTable.build(BatchWriteCommand)
  .requests(...)
  .options({ tableName: `tenant-${tenantId}-pokemons` })
```

## Execution

```javascript
import { execute } from 'dynamodb-toolbox/table/actions/batchWrite'

await execute(...batchWriteCommands)
```

### Options

The `execute` function accepts an additional object as a first argument for **operation-level** options, as well as DocumentClient options such as `abortSignal`:

```javascript
await execute(options, ...batchWriteCommands)
```

Available options (see the DynamoDB documentation 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.
Possible values are "NONE", "TOTAL" and "INDEXES".
`metrics`| `MetricsOption`| "NONE"| Determines whether item collection metrics are returned.
Possible values are "NONE" and "SIZE".
`documentClient`| `DocumentClient`| -| By default, the `documentClient` attached to the `Table` of the first `BatchWriteCommand` is used to execute the operation.
Use this option to override this behavior.
`maxAttempts`| `integer ≥ 1`| `1`| A "meta" option provided by DynamoDB-Toolbox to retry failed requests in a single promise.
Note that `Infinity` is a valid (albeit dangerous) option.
```

--------------------------------

### executeTransactGet

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/repository

Executes a batch of get transactions.

```APIDOC
## `executeTransactGet`

### Description
Executes a batch of `TransactGet` operations. This is a static method.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **opt** (OPTIONS) - Optional - Options for the transaction execution, such as capacity.
- **...transac** (TRANSACTIONS) - Required - One or more `GetTransaction` objects to execute.

### Request Example
```javascript
const { Responses } = await EntityRepository.executeTransactGet(
  pokemonRepository.transactGet(...),
  pokemonRepository.transactGet(...)
);

const { Responses } = await EntityRepository.executeTransactGet(
  { capacity: 'TOTAL' },
  pokemonRepository.transactGet(...),
  pokemonRepository.transactGet(...)
);
```

### Response
#### Success Response (200)
- **ExecuteTransactGetResponses<TRANSACTIONS>** - An object containing the responses from the executed transactions.

#### Response Example
```json
{
  "Responses": [
    {
      "pokemonId": "pikachu1",
      "name": "Pikachu",
      "level": 50
    }
  ]
}
```
```

--------------------------------

### Database Constructor with Options (Meta)

Source: https://www.dynamodbtoolbox.com/docs/databases/usage

Illustrates how to provide optional configuration to the Database constructor, specifically the 'meta' object. The 'meta' object can include 'title' and 'description', and custom fields of any type.

```typescript
const PokeDB = new Database(
  ...,
  {
    meta: {
      title: 'Pokedex',
      description:
        'An Awesome Database for development use',
      other: { field: 'of any type' }
    }
  }
)

// 👇 Directly access/modify metadata  
console.log(PokeDB.meta)
PokeDB.meta.foo = 'A new field'

```

--------------------------------

### Basic Query

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/query

Performs a standard query on a partition.

```javascript
const { Items } = await PokeTable.build(QueryCommand)  
  .query({ partition: 'ashKetchum' })  
  .send()  
```

--------------------------------

### Invalid Tuple Configurations

Source: https://www.dynamodbtoolbox.com/docs/schemas/tuple

Examples of configurations that are not permitted for tuple elements.

```typescript
// ❌ Raises a type AND a run-time error  
const strTuple = tuple(string().optional())  
const strTuple = tuple(string().hidden())  
const strTuple = tuple(string().key())  
const strTuple = tuple(string().savedAs('foo'))
```

--------------------------------

### Searching a Schema with Finder

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/finder

Demonstrates initializing the Finder action and searching for a specific subschema using a path string.

```typescript
import { Finder } from 'dynamodb-toolbox/schema/actions/finder'  
  
const pokemonSchema = item({  
  evolutions: list(map({ level: number() })).savedAs('_e'),  
  ...  
})  
  
const finder = pokemonSchema.build(Finder)  
const subschemas = finder.search('evolutions[1].level')  
  
const [levelSubSchema] = subschemas
```

--------------------------------

### Registering Entities and AccessPatterns with Registry

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/registry

This snippet demonstrates how to initialize a Registry with a Table, register multiple entities and access patterns, and then access them.

```typescript
import { Registry } from 'dynamodb-toolbox/table/actions/registry'  
  
const PokeRegistry = PokeTable.build(Registry)  
  .registerEntities(PokemonEntity, TrainerEntity, ...)  
  .registerAccessPatterns({ trainers, pokemonsByTrainerId })  
  
// Get an Entity by `entityName`  
PokeRegistry.entities.pokemon  
  
// Get an AccessPattern by key  
PokeRegistry.accessPatterns.trainers.query(...)  
  
// Or use the `.query` shorthand  
PokeRegistry.query.trainers(...)  
```

--------------------------------

### Install Zod dependency

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/zod-schemer

ZodSchemer requires Zod v3 as a peer dependency.

```bash
npm install zod@v3
```

--------------------------------

### transactGet

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/repository

Builds a transaction to get an entity item for use in TransactGetItems operations.

```APIDOC
## `transactGet`

### Description
Builds a transaction to get an entity item, to be used within `TransactGetItems` operations.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key** (KeyInputItem<ENTITY>) - Required - The key of the entity item to retrieve.
- **opt** (OPTIONS) - Optional - Options for the transaction.

### Request Example
```javascript
const transaction = pokemonRepository.transactGet({
  pokemonId: 'pikachu1'
});

const transactionWithOptions = pokemonRepository.transactGet(
  { pokemonId: 'pikachu1' },
  { attributes: ['name', 'level'] }
);
```

### Response
#### Success Response (200)
- **GetTransaction<ENTITY, OPTIONS>** - An object representing the get transaction.

#### Response Example
```json
{
  "type": "Get",
  "key": {
    "pokemonId": "pikachu1"
  },
  "options": {
    "attributes": ["name", "level"]
  }
}
```
```

--------------------------------

### Basic Execution

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/transact-get

Import and execute the TransactGet action.

```typescript
import { execute } from 'dynamodb-toolbox/entity/actions/transactGet'  
  
await execute(...getTransactions)
```

--------------------------------

### batchGet

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/repository

Builds a request to get an entity item, to be used within BatchGetCommands.

```APIDOC
## batchGet

### Description
Builds a request to get an entity item, to be used within `BatchGetCommands`. See `BatchGetRequest` for more details.

### Method
`batchGet(key: KeyInputItem<ENTITY>) => BatchGetRequest<ENTITY>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key** (KeyInputItem<ENTITY>) - Required - The key of the item to get.

### Request Example
```javascript
const request = pokemonRepository.batchGet({
  pokemonId: 'pikachu1'
});
```

### Response
#### Success Response (200)
- **BatchGetRequest** (BatchGetRequest<ENTITY>) - A request object for batch get operations.

#### Response Example
```json
{
  "Keys": [
    {
      "pokemonId": "pikachu1"
    }
  ]
}
```
```

--------------------------------

### PutItemCommand Usage

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/put-item

Demonstrates how to build and send a PutItemCommand using an Entity, including accessing the returned ToolboxItem.

```APIDOC
## PutItemCommand

### Description
Persists an item to DynamoDB using the defined Entity. The response includes the standard DynamoDB PutItem response plus a `ToolboxItem` property.

### Methods
- `.item(item)`: Defines the item to be persisted.
- `.options(options)`: Configures command options such as conditions.
- `.send()`: Executes the command.

### Example
```javascript
const { ToolboxItem: generatedPokemon } =  
  await PokemonEntity.build(PutItemCommand)  
    .item({ ... })  
    .send()  
```
```

--------------------------------

### Retrieve All Items

Source: https://www.dynamodbtoolbox.com/docs/tables/actions/query

Fetch all items from a partition by setting maxPages to Infinity. Use with caution to avoid RAM issues.

```typescript
const { Items } = await PokeTable.build(QueryCommand)  
  .query({ partition: 'ashKetchum' })  
  // Retrieve all items from the partition (beware of RAM issues!)  
  .options({ maxPages: Infinity })  
  .send()
```

--------------------------------

### Extended Syntax: $subtract

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/update-item

Example of the $subtract symbol and its corresponding type guard.

```typescript
import {  
  $subtract,  
  $SUBTRACT,  
  $IS_EXTENSION,  
  isSubtraction  
} from 'dynamodb-toolbox/entity/actions/update/symbols'  
  
const subtraction = $subtract(1, 2)  
  
// 👇 Equivalent to  
const subtraction = {  
  [$SUBTRACT]: [1, 2],  
  [$IS_EXTENSION]: true  
}  
  
const link = (input: UpdateItemInput) => {  
  if (isSubtraction(input)) {  
    input[$SUBTRACT] // => [1, 2]  
  }  
}  
```

--------------------------------

### Extended Syntax: $sum

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/update-item

Example of the $sum symbol and its corresponding type guard.

```typescript
import {  
  $sum,  
  $SUM,  
  $IS_EXTENSION,  
  isSum  
} from 'dynamodb-toolbox/entity/actions/update/symbols'  
  
const sum = $sum(1, 2)  
  
// 👇 Equivalent to  
const sum = {  
  [$SUM]: [1, 2],  
  [$IS_EXTENSION]: true  
}  
  
const link = (input: UpdateItemInput) => {  
  if (isSum(input)) {  
    input[$SUM] // => [1, 2]  
  }  
}  
```

--------------------------------

### Basic Parser Usage

Source: https://www.dynamodbtoolbox.com/docs/schemas/actions/parse

Demonstrates how to import and use the Parser action to validate an item against a schema.

```typescript
import { Parser } from 'dynamodb-toolbox/schema/actions/parse'  
  
const validPokemon = pokemonSchema  
  .build(Parser)  
  .parse(pokemon)  
```

```typescript
const validKey = pokemonSchema.build(Parser).parse(  
  key,  
  // Additional options  
  { mode: 'key' }  
)  
```

--------------------------------

### Extended Syntax: $remove

Source: https://www.dynamodbtoolbox.com/docs/entities/actions/update-item

Example of the $remove symbol and its corresponding type guard.

```typescript
import {  
  $remove,  
  $REMOVE,  
  $IS_EXTENSION,  
  isRemoval  
} from 'dynamodb-toolbox/entity/actions/update/symbols'  
  
const removal = $remove()  
  
// 👇 Equivalent to  
const removal = {  
  [$REMOVE]: true,  
  [$IS_EXTENSION]: true  
}  
  
const link = (input: UpdateItemInput) => {  
  if (isRemoval(input)) {  
    input[$REMOVE] // => true  
  }  
}  
```
Tokens:
Raw