Version: v2

EntityRepository

A utility action that exposes all entity actions as methods. Using it leads to heavier bundles (as it necessarily imports all of their code) but provides a more concise syntax:

import { EntityRepository } from 'dynamodb-toolbox/entity/actions/repository'

const pokemonRepository = PokemonEntity.build(
  EntityRepository
)

// 👇 Sends a `PutItemCommand`
await pokemonRepository.put(pokemon)

note

Note that Spies can still be used in cunjunction with Repositories as commands are still sent under the hood.

Methods

`get(...)`

(key: KeyInputItem<ENTITY>, opt?: OPTIONS) => GetItemResponse<ENTITY, OPTIONS>

Performs a GetItem Operation. See GetItemCommand for more details:

Examples

Usage
Options

const { Item } = await pokemonRepository.get({
  pokemonId: 'pikachu1'
})

const { Item } = await pokemonRepository.get(
  { pokemonId: 'pikachu1' },
  { consistent: true }
)

`put(...)`

(item: PutItemInput<ENTITY>, opt?: OPTIONS) => PutItemResponse<ENTITY, OPTIONS>

Performs a PutItem Operation. See PutItemCommand for more details:

Examples

Usage
Options

await pokemonRepository.put({
  pokemonId: 'pikachu1',
  name: 'Pikachu',
  pokeType: 'electric',
  level: 50
  ...
})

await pokemonRepository.put(
  {
    pokemonId: 'pikachu1',
    name: 'Pikachu',
    pokeType: 'electric',
    level: 50
    ...
  },
  { returnValues: 'ALL_OLD' }
)

`update(...)`

(item: UpdateItemInput<ENTITY>, opt?: OPTIONS) => UpdateItemResponse<ENTITY, OPTIONS>

Performs an UpdateItem Operation. See UpdateItemCommand for more details:

Examples

Usage
Options

await pokemonRepository.update({
  pokemonId: 'pikachu1',
  level: $add(1)
  ...
})

await pokemonRepository.update(
  {
    pokemonId: 'pikachu1',
    level: $add(1)
    ...
  },
  { returnValues: 'UPDATED_OLD' }
)

`updateAttributes(...)`

(item: UpdateAttributesInput<ENTITY>, opt?: OPTIONS) => UpdateAttributesResponse<ENTITY, OPTIONS>

Performs an UpdateAttributes Operation (similar to UpdateItemCommand except than deep attribute updates are non-partial). See UpdateAttributesCommand for more details:

Examples

Usage
Options

await pokemonRepository.updateAttributes({
  pokemonId: 'pikachu1',
  level: 12
  ...
})

await pokemonRepository.updateAttributes(
  {
    pokemonId: 'pikachu1',
    level: 12
    ...
  },
  { returnValues: 'UPDATED_OLD' }
)

`delete(...)`

(item: KeyInputItem<ENTITY>, opt?: OPTIONS) => DeleteItemResponse<ENTITY, OPTIONS>

Performs a DeleteItem Operation. See DeleteItemCommand for more details:

Examples

Usage
Options

await pokemonRepository.delete({ pokemonId: 'pikachu1' })

await pokemonRepository.delete(
  { pokemonId: 'pikachu1' },
  { returnValues: 'ALL_OLD' }
)

`scan(...)`

(opt?: OPTIONS) => ScanResponse<ENTITY['table'], [ENTITY], OPTIONS>

Performs a Scan Operation on the Entity table. See ScanCommand for more details:

Examples

Usage
Options

const { Items } = await pokemonRepository.scan()

const { Items } = await pokemonRepository.scan({
  consistent: true,
  limit: 10
})

`query(...)`

(query: QUERY, options?: OPTIONS) => QueryResponse<ENTITY['table'], QUERY, [ENTITY], OPTIONS>

Performs a Query Operation on the Entity table. See QueryCommand for more details:

Examples

Usage
Index
Options

// Get 'ashKetchum' pokemons
const { Items } = await pokemonRepository.query({
  partition: 'ashKetchum'
})

// Get 'ashKetchum1' pokemons with a level ≥ 50
const { Items } = await pokemonRepository.query({
  partition: 'ashKetchum1',
  index: 'byTrainerId',
  range: { gte: 50 }
})

// Consistently get less than 10 'ashKetchum' pokemons
const { Items } = await pokemonRepository.query(
  { partition: 'ashKetchum' },
  { consistent: true, limit: 10 }
)

Batching

`batchGet(...)`

(key: KeyInputItem<ENTITY>) => BatchGetRequest<ENTITY>

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

Examples

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

`batchPut(...)`

(item: PutItemInput<ENTITY>) => BatchPutRequest<ENTITY>

Builds a request to put an entity item, to be used within BatchWriteCommands. See BatchPutRequest for more details:

Examples

const request = pokemonRepository.batchPut({
  pokemonId: 'pikachu1',
  name: 'Pikachu',
  pokeType: 'electric',
  level: 50,
  ...
})

`batchDelete(...)`

(key: KeyInputItem<ENTITY>) => BatchDeleteRequest<ENTITY>

Builds a request to delete an entity item, to be used within BatchWriteCommands. See BatchDeleteRequest for more details:

Examples

const request = pokemonRepository.batchDelete({
  pokemonId: 'pikachu1'
})

Transactions

`transactGet(...)`

(key: KeyInputItem<ENTITY>, opt?: OPTIONS) => GetTransaction<ENTITY, OPTIONS>

Builds a transaction to get an entity item, to be used within TransactGetItems operations. See GetTransaction for more details:

Examples

Usage
Options

const transaction = pokemonRepository.transactGet({
  pokemonId: 'pikachu1'
})

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

`executeTransactGet(...)`

static (opt?: OPTIONS, ...transac: TRANSACTIONS) => ExecuteTransactGetResponses<TRANSACTIONS>

The TransactGet executor exposed as a static method:

Examples

Usage
Options

const { Responses } = await EntityRepository.executeTransactGet(
  pokemonRepository.transactGet(...),
  pokemonRepository.transactGet(...),
)

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

`transactPut(...)`

(item: PutItemInput<ENTITY>, opt?: OPTIONS) => PutTransaction<ENTITY, OPTIONS>

Builds a transaction to put an entity item, to be used within TransactWriteItems operations. See PutTransaction for more details:

Examples

Usage
Options

const transaction = pokemonRepository.transactPut({
  pokemonId: 'pikachu1',
  name: 'Pikachu',
  pokeType: 'electric',
  level: 50
  ...
})

const transaction = pokemonRepository.transactPut(
  {
    pokemonId: 'pikachu1',
    name: 'Pikachu',
    pokeType: 'electric',
    level: 50
    ...
  },
  { condition: { attr: 'pokemonId', exists: false } }
)

`transactUpdate(...)`

(item: UpdateItemInput<ENTITY>, opt?: OPTIONS) => UpdateTransaction<ENTITY, OPTIONS>

Builds a transaction to update an entity item, to be used within TransactWriteItems operations. See UpdateTransaction for more details:

Examples

Usage
Options

const transaction = pokemonRepository.transactUpdate({
  pokemonId: 'pikachu1',
  level: $add(1)
  ...
})

const transaction = pokemonRepository.transactUpdate(
  {
    pokemonId: 'pikachu1',
    level: $add(1)
    ...
  },
  { condition: { attr: 'level', lt: 99 } }
)

`transactDelete(...)`

(key: KeyInputItem<ENTITY>, opt?: OPTIONS) => DeleteTransaction<ENTITY, OPTIONS>

Builds a transaction to delete an entity item, to be used within TransactWriteItems operations. See DeleteTransaction for more details:

Examples

Usage
Options

const transaction = pokemonRepository.transactDelete({
  pokemonId: 'pikachu1'
})

const transaction = pokemonRepository.transactDelete(
  { pokemonId: 'pikachu1' },
  { condition: { attr: 'archived', eq: true } }
)

`transactCheck(...)`

(key: KeyInputItem<ENTITY>, cond: Condition<ENTITY>, opt?: OPTIONS) => ConditionCheck<ENTITY>

Builds a condition to check against an entity item for the transaction to succeed, to be used within TransactWriteItems operations. See ConditionCheck for more details:

Examples

Usage
Options

const transaction = pokemonRepository.transactCheck(
  { pokemonId: 'pikachu1' },
  { attr: 'level', gte: 50 }
)

const transaction = pokemonRepository.transactCheck(
  { pokemonId: 'pikachu1' },
  { attr: 'level', gte: 50 },
  { tableName: `tenant-${tenantId}-pokemons` }
)

`executeTransactWrite(...)`

static (opt?: OPTIONS, ...transac: TRANSACTIONS) => ExecuteTransactWriteResponses<TRANSACTIONS>

The TransactGet executor exposed as a static method:

Examples

Usage
Options

const { Responses } = await EntityRepository.executeTransactGet(
  pokemonRepository.transactGet(...),
  pokemonRepository.transactGet(...),
)

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

Utils

`accessPattern(...)`

(sch: SCHEMA, ptrn: Pattern<SCHEMA, QUERY>, opt?: OPTIONS) => AccessPattern<TABLE, SCHEMA, QUERY, OPTIONS>

Creates an AccessPattern. See AccessPattern for more details:

const accessPattern = pokemonRepository.accessPattern(
  map({ trainerId: string() }),
  ({ trainerId }) => ({ partition: trainerId }),
  { attributes: ['name', 'level'] }
)

const { Items } = await accessPattern
  .query({ trainerId: '123' })
  .send()

`parse(...)`

(input: unknown, opt?: OPTIONS) => ParserOutput<ENTITY, OPTIONS>

Given an input of any type and a mode, validates that it respects the schema of the Entity and applies transformations. See EntityParser for more details:

Examples

Usage
Options

// 👇 Parsed item + Primary key
const { item, key } = pokemonRepository.parse(input)

// 👇 Primary key
const { key } = pokemonRepository.parse(input, {
  mode: 'key'
})

`parseCondition(...)`

(condition: Condition<ENTITY>) => ConditionExpression

Builds a Condition Expression that can be used to condition write operations, or filter the results of a Query or a Scan. See ConditionParser for more details:

Examples

// 👇 To be used in DynamoDB commands
const {
  ConditionExpression,
  ExpressionAttributeNames,
  ExpressionAttributeValues
} = pokemonRepository.parseCondition({
  // Pokemons with levels ≥ 50
  attr: 'level',
  gte: 50
})

`parsePaths(...)`

(paths: Path<ENTITY>[]) => ProjectionExpression

Builds a Projection Expression that can be used to filter the returned attributes of a read operation like a GetItem, Query or Scan. See PathParser for more details:

Examples

// 👇 To be used in DynamoDB commands
const { ProjectionExpression, ExpressionAttributeNames } =
  pokemonRepository.parsePaths(['name', 'level'])

`format(...)`

(item: unknown, opt?: OPTIONS) => FormattedItem<ENTITY, OPTIONS>

Given a transformed item, validates that it respects the schema of the Entity, applies transformations backward and hide hidden attributes. See EntityFormatter for more details:

Examples

Usage
Options

const formattedPikachu = pokemonRepository.format(
  transformedPikachu
)

const partialPikachu = pokemonRepository.format(
  transformedPikachu,
  { partial: true }
)

Methods​

get(...)​

put(...)​

update(...)​

updateAttributes(...)​

delete(...)​

scan(...)​

query(...)​

Batching​

batchGet(...)​

batchPut(...)​

batchDelete(...)​

Transactions​

transactGet(...)​

executeTransactGet(...)​

transactPut(...)​

transactUpdate(...)​

transactDelete(...)​

transactCheck(...)​

executeTransactWrite(...)​

Utils​

accessPattern(...)​

parse(...)​

parseCondition(...)​

parsePaths(...)​

format(...)​

Methods

`get(...)`

`put(...)`

`update(...)`

`updateAttributes(...)`

`delete(...)`

`scan(...)`

`query(...)`

Batching

`batchGet(...)`

`batchPut(...)`

`batchDelete(...)`

Transactions

`transactGet(...)`

`executeTransactGet(...)`

`transactPut(...)`

`transactUpdate(...)`

`transactDelete(...)`

`transactCheck(...)`

`executeTransactWrite(...)`

Utils

`accessPattern(...)`

`parse(...)`

`parseCondition(...)`

`parsePaths(...)`

`format(...)`