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