DynamoDB Helper

A production-ready TypeScript library that provides a high-level, efficient interface for AWS DynamoDB operations using the AWS SDK v3.

This library offers enhanced type safety, automatic retries, batch processing, and comprehensive error handling.

Features

• ✅ Complete DynamoDB Operations: All major DynamoDB commands supported
• ✅ Type Safety: Full TypeScript support with strict typing
• ✅ Automatic Retries: Exponential backoff with configurable retry logic
• ✅ Batch Processing: Automatic chunking and retry for batch operations
• ✅ Error Handling: Comprehensive error handling with custom error types
• ✅ Performance: Optimized for production use with efficient resource management
• ✅ Pagination: Built-in support for automatic pagination
• ✅ Capacity Metrics: Enhanced capacity tracking and monitoring with detailed metrics
• ✅ Metrics Aggregation: Automatic aggregation of capacity metrics across operations

Supported Operations

Operation	Method	Description
GetCommand	get()	Retrieve a single item
PutCommand	put()	Create or replace an item
UpdateCommand	update()	Update an existing item
DeleteCommand	delete()	Delete an item
BatchGetCommand	batchGet()	Retrieve multiple items
BatchWriteCommand	batchWrite()	Write/delete multiple items
TransactWriteCommand	transactWrite()	Atomic write transactions
TransactGetCommand	transactGet()	Atomic read transactions
QueryCommand	query()	Query items with partition key
ScanCommand	scan()	Scan table or index

Installation

npm install @nicknaddaf/dynamodb-helper

Peer Dependencies

npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

Quick Start

import { DynamoDBHelper } from '@nicknaddaf/dynamodb-helper';

// Initialize the helper
const dynamoHelper = new DynamoDBHelper({
    region: 'us-east-1',
});

// Create an item
const result = await dynamoHelper.put({
    tableName: 'Users',
    Item: {
        userId: '123',
        name: 'John Doe',
        email: '[email protected]',
    },
});

if (result.success) {
    console.log('Item created successfully');
} else {
    console.error('Error:', result.error?.message);
}

Configuration

const dynamoHelper = new DynamoDBHelper({
    region: 'us-east-1',
    endpoint: 'http://localhost:8000', // For local DynamoDB
    credentials: {
        accessKeyId: 'your-access-key',
        secretAccessKey: 'your-secret-key',
    },
    maxRetries: 3,
});

or you can accept the default values:

const dynamoHelper = new DynamoDBHelper({});

Contributing

Contributions are welcome! Please submit pull requests or open issues on GitHub.

License

MIT License - See LICENSE file for details.

Changelog

v1.0.0

• Initial release
• Support for all major DynamoDB operations
• TypeScript support with strict typing
• Automatic retries with exponential backoff
• Comprehensive error handling
• Batch operation support with automatic chunking
• Transaction support
• Pagination helpers
• Production-ready with extensive testing