✨ Features

📦 Installation

# npm
npm install @exabugs/dynamodb-client

# pnpm (recommended)
pnpm add @exabugs/dynamodb-client

# yarn
yarn add @exabugs/dynamodb-client

🏗️ Architecture

graph TB
    subgraph "Client Applications"
        A[React Admin]
        B[Mobile App]
        C[Custom App]
    end

    subgraph "AWS Lambda"
        D[Lambda Function<br/>Function URL]
    end

    subgraph "AWS DynamoDB"
        E[(DynamoDB<br/>Single Table)]
    end

    A -->|HTTPS| D
    B -->|HTTPS| D
    C -->|HTTPS| D
    D -->|AWS SDK| E

    style A fill:#61dafb,stroke:#333,stroke-width:2px
    style B fill:#61dafb,stroke:#333,stroke-width:2px
    style C fill:#61dafb,stroke:#333,stroke-width:2px
    style D fill:#ff9900,stroke:#333,stroke-width:2px
    style E fill:#527fff,stroke:#333,stroke-width:2px

🚀 Quick Start & Examples

Get started in 3 steps: Schema Definition → Deploy Infrastructure → Use Client

Complete Example Project

We provide a complete, working example project that demonstrates all features:

👉 dynamodb-client-example - Full-stack example with React Admin

This example includes:

• ✅ Complete TypeScript schemas (Articles, Tasks)
• ✅ Terraform infrastructure (DynamoDB, Lambda, Cognito)
• ✅ React Admin UI with authentication
• ✅ Shadow Records for efficient sorting
• ✅ Production-ready configuration
• ✅ Step-by-step QUICKSTART guide

Use it as a template for your own projects!

Quick Example

// 1. Define schema
export const MySchema: SchemaRegistryConfig = {
  database: {
    name: 'myapp',
    timestamps: {
      createdAt: 'createdAt',
      updatedAt: 'updatedAt',
    },
  },
  resources: {
    articles: {
      resource: 'articles',
      type: {} as Article,
      shadows: { sortableFields: { title: { type: 'string' } } },
    },
  },
};

// 2. Deploy with Terraform (see dynamodb-client-example)
// terraform apply

// 3. Use the client
const client = new DynamoClient(FUNCTION_URL);
const articles = client.db().collection('articles');

await articles.insertOne({ title: 'Hello DynamoDB' });
const article = await articles.findOne({ title: 'Hello DynamoDB' });

📚 Getting Started

1. Clone the example project: git clone https://github.com/exabugs/dynamodb-client-example.git
2. Follow the QUICKSTART guide: See QUICKSTART.md
3. Customize for your needs: Modify schemas, add resources, deploy to AWS

📚 Documentation

Available Documentation

• Architecture - System architecture and design
• Client Usage - Client-side API guide
• React Admin Integration - Admin UI setup
• Deployment - Production deployment guide
• Terraform Modules - Infrastructure as Code

GitHub Actions

• GitHub Actions Setup - CI/CD configuration
• Troubleshooting - Common issues and solutions

🛠️ Development

Prerequisites

• Node.js >= 18.0.0
• npm, pnpm, or yarn
• AWS Account (for deployment)

Setup

# Clone repository
git clone https://github.com/exabugs/dynamodb-client.git
cd dynamodb-client

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

Available Commands

npm test              # Run tests
npm run test:coverage # Run tests with coverage
npm run lint          # Lint code
npm run format        # Format code
npm run build         # Build package
npm run clean         # Clean build artifacts

🚢 Deployment

Using the Example Project

The easiest way to deploy is using the dynamodb-client-example project:

# Clone the example
git clone https://github.com/exabugs/dynamodb-client-example.git
cd dynamodb-client-example

# Deploy to dev environment
make deploy-dev

# Deploy to other environments
make deploy-stg    # Staging
make deploy-prd    # Production

See the example project's documentation for detailed deployment instructions.

🔧 Shadow Configuration

Overview

The shadow feature automatically makes all fields sortable without requiring JSON configuration files. Configuration is managed entirely through environment variables.

Environment Variables

Supported Types

• string: Strings (truncated at 100 bytes)
• number: Numbers (offset method, range: -10^15 to +10^15)
• boolean: Booleans (true=1, false=0)
• datetime: ISO 8601 datetime strings
• array: Arrays (JSON stringified, truncated at 200 bytes)
• object: Objects (JSON stringified, truncated at 200 bytes)

Automatic Shadow Generation

Only fields that exist in each record are automatically shadowed:

const record = {
  id: '01HQXYZ123',
  title: 'Article',
  viewCount: 123,
  published: true,
  tags: ['tech', 'aws'],
  metadata: { category: 'tech' }
};

// Automatically generates shadow records:
// - id#01HQXYZ123#id#01HQXYZ123
// - title#Article#id#01HQXYZ123
// - viewCount#1000000000000123#id#01HQXYZ123
// - published#1#id#01HQXYZ123
// - tags#["aws","tech"]#id#01HQXYZ123
// - metadata#{"category":"tech"}#id#01HQXYZ123

Exclusion Rules

• Fields starting with __ are excluded (internal metadata)
• null or undefined values are excluded

Important Notes

• Records without a specific field won't appear in sort results for that field
• Primitive types are truncated at 100 bytes, complex types at 200 bytes
• Number range is -10^15 to +10^15 (within JavaScript's safe integer range)

🤝 Contributing

We welcome contributions!

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Guidelines

• Follow the existing code style
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with AWS SDK for JavaScript
• Inspired by MongoDB API design
• Powered by TypeScript