npm package: @nicknaddaf/dynamodb-helper
Description: A production-ready TypeScript library that provides a high-level, efficient interface for AWS DynamoDB operations using the AWS SDK v3.
Author: nicknaddaf
Latest version: 1.0.0

# 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.

[![npm version](https://img.shields.io/npm/v/@nicknaddaf/dynamodb-helper.svg)](https://www.npmjs.com/package/@nicknaddaf/dynamodb-helper)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

```bash
npm install @nicknaddaf/dynamodb-helper
```

### Peer Dependencies

```bash
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```

## Quick Start

```typescript
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: 'john@example.com',
    },
});

if (result.success) {
    console.log('Item created successfully');
} else {
    console.error('Error:', result.error?.message);
}
```

## Configuration

```typescript
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:

```typescript
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