feat: Add protected setDocClient method to DynamoDbChatStorage

[yilinglu]

Issue Link (REQUIRED)

Fixes #368

Summary

Changes

Added a protected setDocClient method to the DynamoDbChatStorage class, allowing subclasses to customize the DynamoDB Document Client configuration. This enhancement enables common use cases without requiring code duplication.

Key benefit: This change enables developers to use DynamoDB Local in Docker containers for local development, eliminating the need for AWS credentials and costs during development.

User experience

Before: Users had to duplicate the entire DynamoDbChatStorage class (~200+ lines) or use type casting hacks to customize the DynamoDB client for local development or testing.

After: Users can cleanly extend DynamoDbChatStorage with minimal code:

Example: Local Development with DynamoDB in Docker

// Start DynamoDB Local in Docker:
// docker run -p 8000:8000 amazon/dynamodb-local

class LocalDynamoDbChatStorage extends DynamoDbChatStorage {
  constructor(tableName: string, region: string, endpoint: string) {
    super(tableName, region);
    
    const client = new DynamoDBClient({
      region,
      endpoint,  // e.g., 'http://localhost:8000'
      credentials: { accessKeyId: 'dummy', secretAccessKey: 'dummy' }
    });
    
    this.setDocClient(DynamoDBDocumentClient.from(client));
  }
}

// Usage
const storage = new LocalDynamoDbChatStorage(
  'conversations-table',
  'us-east-1',
  'http://localhost:8000'  // Points to Docker container
);

Checklist

• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• I have linked this PR to an existing issue (required)

Is this a breaking change?

No, this is a non-breaking change. The new protected method is additive and all existing code continues to work unchanged.

RFC issue number: N/A

Checklist:

• Migration process documented (N/A - non-breaking)
• Implement warnings (N/A - non-breaking)

Testing

• Added comprehensive unit tests for the new method
• All existing tests continue to pass
• Tested with local DynamoDB setup in Docker container
• Verified the following Docker setup works:

  # Start DynamoDB Local
  docker run -d -p 8000:8000 amazon/dynamodb-local
  
  # Create table
  aws dynamodb create-table \
    --table-name conversations-table \
    --attribute-definitions \
      AttributeName=PK,AttributeType=S \
      AttributeName=SK,AttributeType=S \
    --key-schema \
      AttributeName=PK,KeyType=HASH \
      AttributeName=SK,KeyType=RANGE \
    --billing-mode PAY_PER_REQUEST \
    --endpoint-url http://localhost:8000

Documentation

Added JSDoc documentation for the new method explaining its purpose and usage.

Real-World Benefits

This change significantly improves the developer experience by enabling:

1. Cost-free local development - No AWS charges during development
2. Offline development - Works without internet connection
3. Faster iteration - No network latency to AWS
4. CI/CD testing - Easy integration testing with DynamoDB Local in Docker
5. Docker Compose workflows - Seamless integration with containerized development environments

Example docker-compose.yml:

services:
  dynamodb-local:
    image: amazon/dynamodb-local
    ports:
      - "8000:8000"
  
  app:
    build: .
    environment:
      DYNAMODB_ENDPOINT: http://dynamodb-local:8000
    depends_on:
      - dynamodb-local

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[brnaba-aws]

Hi,
thanks for your PR. Instead of creating another class, I would add a new param in DynamoDbChatStorage: endpoint. That endpoint can be pointing to your local DDB.

[brnaba-aws]

just add an endpoint parameter to avoid such method

[brnaba-aws]

Please, add a new parameter: endpoint