DynamoDB Provider

class DynamoDBProvider extends BaseProvider {
  constructor(config: DynamoDBProviderOptions);
  get<T>(name: string, options?: DynamoDBGetOptions): Promise<T | undefined>;
  getMultiple<T>(path: string, options?: DynamoDBGetMultipleOptions): Promise<Record<string, T> | undefined>;
}

interface DynamoDBProviderOptions {
  tableName: string;
  keyAttr?: string;      // Default: 'id'
  sortAttr?: string;     // Default: 'sk'
  valueAttr?: string;    // Default: 'value'
  clientConfig?: DynamoDBClientConfig;
  awsSdkV3Client?: DynamoDBClient;
}

interface DynamoDBGetOptions {
  maxAge?: number;
  forceFetch?: boolean;
  transform?: 'json' | 'binary';
  sdkOptions?: Omit<Partial<GetItemCommandInput>, 'Key' | 'TableName' | 'ProjectionExpression'>;
}

interface DynamoDBGetMultipleOptions {
  maxAge?: number;
  forceFetch?: boolean;
  transform?: 'json' | 'binary' | 'auto';
  sdkOptions?: Partial<QueryCommandInput>;
  throwOnTransformError?: boolean;
}

import { DynamoDBProvider } from '@aws-lambda-powertools/parameters/dynamodb';

// Default attribute names
const provider = new DynamoDBProvider({ tableName: 'parameters-table' });

// Get by partition key
const value = await provider.get('my-parameter');

// With transform
const config = await provider.get('app-config', { transform: 'json' });

// Custom cache and force fetch
const fresh = await provider.get('my-param', { maxAge: 300, forceFetch: true });

// Query all items with partition key
const params = await provider.getMultiple('my-app-config');
for (const [key, value] of Object.entries(params || {})) {
  console.log(`${key}: ${value}`);
}

// Auto-transform (detects .json suffix on sort key)
const configs = await provider.getMultiple('my-app', { transform: 'auto' });

// Graceful error handling
const p = await provider.getMultiple('my-app', {
  transform: 'auto',
  throwOnTransformError: false
});

// Custom schema
const customProvider = new DynamoDBProvider({
  tableName: 'config-table',
  keyAttr: 'configId',      // Partition key
  sortAttr: 'configKey',    // Sort key
  valueAttr: 'configValue'  // Value attribute
});

const value = await customProvider.get('app-123');
const values = await customProvider.getMultiple('app-123');

import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

// With client config
const provider1 = new DynamoDBProvider({
  tableName: 'params',
  clientConfig: { region: 'us-west-2', maxAttempts: 3 }
});

// With custom client instance
const client = new DynamoDBClient({ region: 'eu-west-1' });
const provider2 = new DynamoDBProvider({
  tableName: 'params',
  awsSdkV3Client: client
});

// Consistent read
const value = await provider.get('my-param', {
  sdkOptions: { ConsistentRead: true }
});

// Query with filter
const filtered = await provider.getMultiple('my-app', {
  sdkOptions: {
    FilterExpression: 'attribute_exists(#val)',
    ExpressionAttributeNames: { '#val': 'value' }
  }
});

// Query with limit
const limited = await provider.getMultiple('my-app', {
  sdkOptions: { Limit: 10 }
});

Partition Key: id (String)
Attributes: value (String)

Item: { "id": "api-url", "value": "https://api.example.com" }

Partition Key: id (String)
Sort Key: sk (String)
Attributes: value (String)

Items:
{ "id": "my-app", "sk": "database.host", "value": "db.example.com" }
{ "id": "my-app", "sk": "database.port", "value": "5432" }
{ "id": "my-app", "sk": "features.json", "value": "{\"enableNewUI\": true}" }

Partition Key: id (String) = environment name
Sort Key: sk (String) = config key
Attributes: value (String)

Items:
{ "id": "prod", "sk": "api-key", "value": "prod-key-12345" }
{ "id": "prod", "sk": "db-connection", "value": "{\"host\": \"prod.db.com\"}" }
{ "id": "dev", "sk": "api-key", "value": "dev-key-67890" }

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["dynamodb:GetItem", "dynamodb:Query"],
      "Resource": ["arn:aws:dynamodb:region:account-id:table/table-name"]
    }
  ]
}