Skip to content

title: @ddb-lib/client API description: High-level DynamoDB client with simplified operations

@ddb-lib/client API reference

High-level DynamoDB client providing simplified, type-safe operations with automatic retry logic and statistics collection.

Installation

npm install @ddb-lib/client @ddb-lib/core

Quick start

import { TableClient } from '@ddb-lib/client'

const table = new TableClient({
  tableName: 'MyTable',
  region: 'us-east-1'
})

// CRUD operations
await table.put({ pk: 'USER#123', sk: 'PROFILE', name: 'John' })
const user = await table.get({ pk: 'USER#123', sk: 'PROFILE' })
await table.update({ pk: 'USER#123', sk: 'PROFILE', updates: { name: 'Jane' } })
await table.delete({ pk: 'USER#123', sk: 'PROFILE' })

// Query operations
const results = await table.query({
  keyCondition: { pk: 'USER#123', sk: { beginsWith: 'ORDER#' } }
})

// Batch operations
await table.batchGet({ keys: [{ pk: 'USER#1', sk: 'PROFILE' }, { pk: 'USER#2', sk: 'PROFILE' }] })
await table.batchWrite({ puts: [{ pk: 'USER#3', sk: 'PROFILE', name: 'Bob' }] })

// Transactions
await table.transactWrite([
  { put: { pk: 'USER#4', sk: 'PROFILE', name: 'Alice' } },
  { update: { pk: 'USER#5', sk: 'PROFILE', updates: { loginCount: { increment: 1 } } } }
])

TableClient class

Main client for all DynamoDB operations.

Constructor

new TableClient(config: TableClientConfig)

Configuration: - tableName: string - DynamoDB table name (required) - region?: string - AWS region - client?: DynamoDBClient - Custom DynamoDB client - retryConfig?: RetryConfig - Retry configuration - statsCollector?: StatsCollector - Statistics collector

CRUD operations

Get()

Retrieve a single item by key.

get(params: GetParams): Promise<GetResult>

Put()

Create or replace an item.

put(params: PutParams): Promise<PutResult>

Update()

Update an existing item.

update(params: UpdateParams): Promise<UpdateResult>

Delete()

Delete an item.

delete(params: DeleteParams): Promise<DeleteResult>

Query operations

Query()

Query items with key condition.

query(params: QueryParams): Promise<QueryResult>

Scan()

Scan table (use sparingly).

scan(params: ScanParams): Promise<ScanResult>

Batch operations

Batchget()

Get multiple items (up to 100).

batchGet(params: BatchGetParams): Promise<BatchGetResult>

Batchwrite()

Put/delete multiple items (up to 25).

batchWrite(params: BatchWriteParams): Promise<BatchWriteResult>

Transaction operations

Transactwrite()

Execute multiple operations atomically.

transactWrite(items: TransactWriteItem[]): Promise<TransactWriteResult>

Transactget()

Get multiple items atomically.

transactGet(keys: Key[]): Promise<TransactGetResult>