@xcelsior/aws

AWS service utilities for serverless applications in the Xcelsior ecosystem.

Installation

pnpm add @xcelsior/aws

Features

DynamoDB Client

Type-safe DynamoDB operations:

import { DynamoDBClient } from '@xcelsior/aws';

const client = new DynamoDBClient();

// Get item
const item = await client.get({
  TableName: 'Users',
  Key: { id: 'user123' },
});

// Put item
await client.put({
  TableName: 'Users',
  Item: {
    id: 'user123',
    name: 'John Doe',
    email: '[email protected]',
  },
});

// Query
const results = await client.query({
  TableName: 'Users',
  KeyConditionExpression: 'pk = :pk',
  ExpressionAttributeValues: {
    ':pk': 'USER#123',
  },
});

S3 Client

Simplified S3 operations:

import { S3Client } from '@xcelsior/aws';

const client = new S3Client();

// Upload file
await client.upload({
  Bucket: 'my-bucket',
  Key: 'path/to/file.txt',
  Body: 'Hello World',
});

// Get file
const file = await client.get({
  Bucket: 'my-bucket',
  Key: 'path/to/file.txt',
});

// Delete file
await client.delete({
  Bucket: 'my-bucket',
  Key: 'path/to/file.txt',
});

EventBridge Client

Event publishing and pattern matching:

import { EventBridgeClient } from '@xcelsior/aws';

const client = new EventBridgeClient();

// Publish event
await client.putEvents({
  Entries: [{
    Source: 'my-service',
    DetailType: 'UserCreated',
    Detail: JSON.stringify({ userId: '123' }),
  }],
});

// Create rule
await client.putRule({
  Name: 'user-created-rule',
  EventPattern: {
    source: ['my-service'],
    detailType: ['UserCreated'],
  },
});

Configuration

Client Options

export interface AWSClientOptions {
  region?: string;
  endpoint?: string;
  credentials?: {
    accessKeyId: string;
    secretAccessKey: string;
  };
}

Environment Variables

The clients will automatically use these environment variables if set:

• AWS_REGION
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_ENDPOINT_URL

Error Handling

All clients include built-in error handling and retries:

try {
  await client.operation();
} catch (error) {
  if (error.name === 'ConditionalCheckFailedException') {
    // Handle condition failure
  }
  if (error.name === 'ResourceNotFoundException') {
    // Handle not found
  }
  throw error;
}

License

MIT