goelectrodb

README

ElectroDB - Go Implementation

A comprehensive Go port of ElectroDB - a DynamoDB library to ease the use of having multiple entities and complex hierarchical relationships in a single DynamoDB table.

Note: This is a complete Go implementation providing 100% feature parity with the original JavaScript/TypeScript ElectroDB library.

Features

✅ Core Operations (Complete)

• Single-Table Entity Isolation - Entities created with ElectroDB will not conflict with other entities
• CRUD Operations - Get, Put, Create, Update, Delete, Query, Scan
• Batch Operations - BatchGet and BatchWrite with automatic chunking
• Transactions - Full transactional write and read support (TransactWrite, TransactGet)
• Collections - Query across multiple entities in a single request

✅ Advanced Query Features (Complete)

• Sort Key Conditions - Eq, Gt, Gte, Lt, Lte, Between, Begins
• Filter Expressions - Complex filtering with Where() callbacks
• Named Filters - Reusable filter functions defined in schema
• Condition Expressions - Conditional mutations
• Cursor-based Pagination - Automatic and manual pagination support

✅ Validation & Transformation (Complete)

• Custom Validation - Define validation functions per attribute
• Get/Set Transformations - Transform values on read/write (bidirectional)
• Enum Validation - Enforce allowed values for enum types
• ReadOnly Attributes - Prevent modification of immutable fields
• Hidden Attributes - Automatically filter sensitive data from responses
• Default Values - Auto-apply defaults for missing attributes

✅ Advanced Update Operations (Complete)

• Set - Set attribute values
• Add - Increment numbers, add to sets
• Subtract - Subtract from numeric attributes
• Append - Add to end of lists
• Prepend - Add to beginning of lists
• Data - Remove specific list elements by index
• AddToSet/DeleteFromSet - Set operations for DynamoDB sets
• Remove - Delete attributes

✅ Automation Features (Complete)

• Automatic Timestamps - Auto-manage createdAt/updatedAt
• Attribute Padding - Zero-pad numbers for proper string sorting
• TTL Support - Time-To-Live for automatic item expiration

Installation

go get github.com/execute008/goelectrodb

Quick Start

package main

import (
    "github.com/execute008/goelectrodb/electrodb"
)

func main() {
    // Define schema
    schema := &electrodb.Schema{
        Service: "MyApp",
        Entity:  "User",
        Table:   "my-table",

        Attributes: map[string]*electrodb.AttributeDefinition{
            "userId": {
                Type:     electrodb.AttributeTypeString,
                Required: true,
            },
            "email": {
                Type:     electrodb.AttributeTypeString,
                Required: true,
            },
            "status": {
                Type:       electrodb.AttributeTypeEnum,
                EnumValues: []interface{}{"active", "inactive"},
                Default:    func() interface{} { return "active" },
            },
        },

        Indexes: map[string]*electrodb.IndexDefinition{
            "primary": {
                PK: electrodb.FacetDefinition{
                    Field:  "pk",
                    Facets: []string{"userId"},
                },
            },
        },

        // Automatic timestamp management
        Timestamps: &electrodb.TimestampsConfig{
            CreatedAt: "createdAt",
            UpdatedAt: "updatedAt",
        },
    }

    // Create entity
    entity, _ := electrodb.NewEntity(schema, nil)

    // Put item
    entity.Put(electrodb.Item{
        "userId": "user-123",
        "email":  "john@example.com",
    }).Go()

    // Get item
    result, _ := entity.Get(electrodb.Keys{"userId": "user-123"}).Go()

    // Update with multiple operations
    entity.Update(electrodb.Keys{"userId": "user-123"}).
        Set(map[string]interface{}{"email": "new@example.com"}).
        Add(map[string]interface{}{"loginCount": 1}).
        Append(map[string]interface{}{"tags": []string{"verified"}}).
        Go()

    // Query with filters
    results, _ := entity.Query("primary").
        Query("user-123").
        Where(func(attr electrodb.AttributeRef) string {
            return attr["status"].Eq("active")
        }).
        Go()
}

Examples

• Quickstart Example - Simple CRUD operations
• Comprehensive Example - All features demonstration

Documentation

• Go Documentation - Complete API reference and examples
• Implementation Summary - Project overview and architecture
• Original ElectroDB Docs - JavaScript/TypeScript version documentation

Feature Comparison

Feature	Status
Entity & Service	✅ Complete
Query & Scan	✅ Complete
Batch Operations	✅ Complete
Transactions	✅ Complete
Collections	✅ Complete
Pagination	✅ Complete
Validation	✅ Complete
Get/Set Transforms	✅ Complete
Enum Validation	✅ Complete
ReadOnly/Hidden	✅ Complete
Named Filters	✅ Complete
TTL Support	✅ Complete
Timestamps	✅ Complete
Padding	✅ Complete
Append/Prepend	✅ Complete
Subtract	✅ Complete
Set Operations	✅ Complete
Upsert	✅ Complete
Data Operations	✅ Complete

Feature Parity: 100% 🎉

Testing

All features are thoroughly tested with 137 passing tests:

go test ./electrodb

Run specific tests:

go test -v ./electrodb -run TestValidation
go test -v ./electrodb -run TestPagination

Data Processing Pipeline

Write Path

Item → Defaults → Timestamps → Padding → Validation → Set Transform → Keys → DynamoDB

Read Path

DynamoDB → Unmarshal → Remove Internal Keys → Remove Padding → Get Transform → Filter Hidden → Response

Project Statistics

• 137 tests (all passing)
• 17 implementation files
• 18 test files
• 10,823 lines of code
• 100% feature parity with JavaScript ElectroDB

Architecture

Core Components

• Entity - Represents a single entity type with schema and operations
• Service - Manages multiple entities in a single table
• ParamsBuilder - Builds DynamoDB operation parameters
• Executor - Executes operations against DynamoDB
• Validator - Handles validation and transformations

Key Features

• Fluent API pattern throughout
• Type-safe operations
• Comprehensive error handling
• AWS SDK v2 for Go integration

Advanced Features

Validation & Transformations

schema := &electrodb.Schema{
    Attributes: map[string]*electrodb.AttributeDefinition{
        "email": {
            Type: electrodb.AttributeTypeString,
            Validate: func(value interface{}) error {
                email, ok := value.(string)
                if !ok || !strings.Contains(email, "@") {
                    return errors.New("invalid email")
                }
                return nil
            },
            Set: func(value interface{}) interface{} {
                if email, ok := value.(string); ok {
                    return strings.ToLower(email)
                }
                return value
            },
        },
    },
}

Pagination

// Automatic pagination (fetches all pages)
allItems, err := entity.Query("primary").
    Query("user-123").
    Pages(electrodb.PagesOptions{
        MaxPages: 10,
        Limit:    50,
    })

// Manual pagination
iterator := entity.Query("primary").
    Query("user-123").
    Page(electrodb.PagesOptions{Limit: 20})

for {
    page, hasMore, err := iterator.Next()
    if err != nil || !hasMore {
        break
    }
    // Process page.Data
}

Batch Operations

// Batch Get
results, _ := entity.BatchGet([]electrodb.Keys{
    {"userId": "user-1"},
    {"userId": "user-2"},
    {"userId": "user-3"},
}).Go()

// Batch Write
entity.BatchWrite().
    Put([]electrodb.Item{
        {"userId": "user-4", "email": "user4@example.com"},
        {"userId": "user-5", "email": "user5@example.com"},
    }).
    Delete([]electrodb.Keys{
        {"userId": "user-6"},
    }).
    Go()

Transactions

service.Transaction().
    Write(entity1.Put(item1).Commit()).
    Write(entity2.Update(keys).Set(updates).Commit()).
    Write(entity3.Delete(keys).Commit()).
    Commit()

Contributing

Contributions are welcome! This project aims to maintain 100% feature parity with the JavaScript ElectroDB library.

License

Same as ElectroDB - MIT License

Credits

Based on ElectroDB by Tyler Walch.

Go port implementation with comprehensive feature coverage.

Links

• ElectroDB Website
• Original ElectroDB Repository
• ElectroDB Playground