rivia-dynamodb v2.2.2

DynamoDB Wrapper

A simple and efficient wrapper for AWS DynamoDB operations.

Features

• Simplified CRUD operations
• Support for consistent reads
• Batch operations
• Query and scan operations with pagination
• Filter expressions
• Sort key prefix queries
• Sort key range queries (between)
• Consumed capacity tracking
• Configurable primary and sort key field names

Installation

npm install @rivia/dynamo

Configuration

The wrapper can be configured through environment variables or programmatically:

Environment Variables

REGION=us-east-1
TABLE_NAME=your-table-name
DYNAMODB_PK_FIELD_NAME=pk
DYNAMODB_SK_FIELD_NAME=sk
DYNAMODB_CONSISTENT_READ=false
DYNAMODB_RETURN_CONSUMED_CAPACITY=false

Programmatic Configuration

const Dynamo = require('@rivia/dynamo');

const dynamo = new Dynamo();
dynamo.set({
    region: 'us-east-1',
    tableName: 'your-table-name',
    pkField: 'pk',
    skField: 'sk',
    consistentRead: true,
    returnConsumedCapacity: true
});

Usage

Basic Operations

// Insert
await dynamo.insert({ pk: 'user#1', sk: 'profile', name: 'John' });

// Find
const { item, consumedCapacity } = await dynamo.find('user#1', 'profile');

// Update
await dynamo.update('user#1', 'profile', { name: 'John Doe' });

// Remove
await dynamo.remove('user#1', 'profile');

Query Operations

// Query with filters
const { items, count, nextPageId, consumedCapacity } = await dynamo.query(
    'user#1',
    [{ name: 'status', value: 'active' }],
    null,
    10,
    { consistentRead: true }
);

// Query by prefix
const { items } = await dynamo.findByPrefix(
    'user#1',
    'order#',
    [{ name: 'status', value: 'pending' }]
);

// Query by range (between)
const { items } = await dynamo.findByBetween(
    'user#1',
    'order#2023-01-01',
    'order#2023-12-31',
    [{ name: 'status', value: 'completed' }]
);

// Get all items
const { items, count } = await dynamo.getAll('user#1');

Batch Operations

// Batch insert
await dynamo.batchInsert([
    { pk: 'user#1', sk: 'order#1', status: 'pending' },
    { pk: 'user#1', sk: 'order#2', status: 'completed' }
]);

Scan Operations

// Scan with attributes
const { items, consumedCapacity } = await dynamo.scanTable(
    10,
    ['pk', 'sk', 'status'],
    { consistentRead: true }
);

Consistency and Performance

Consistent Reads

By default, DynamoDB uses eventually consistent reads for better performance. However, you can enable strongly consistent reads when needed:

1. Globally through configuration:

dynamo.set({ consistentRead: true });

2. Per-operation through options:

const { item } = await dynamo.find('user#1', 'profile', { consistentRead: true });

Consumed Capacity

You can track the consumed capacity of DynamoDB operations:

1. Globally through configuration:

dynamo.set({ returnConsumedCapacity: true });

2. The consumed capacity will be returned in the operation results:

const { item, consumedCapacity } = await dynamo.find('user#1', 'profile');
console.log('Consumed capacity:', consumedCapacity);

Filter Expressions

The wrapper supports various filter expressions:

// Equality
{ name: 'status', value: 'active' }

// Contains
{ name: 'tags', value: 'important', operator: 'contains' }

// Custom operators
{ name: 'age', value: 18, operator: '>' }

Error Handling

The wrapper throws errors for:

• Invalid value types
• Missing required parameters
• DynamoDB operation failures

try {
    await dynamo.insert({ pk: 'user#1' }); // Missing sk
} catch (error) {
    console.error('Operation failed:', error);
}

License

MIT