Skip to content

execute008/goelectrodb

Repository files navigation

ElectroDB - Go Implementation

Go Tests Go Version License

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":  "[email protected]",
    }).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": "[email protected]"}).
        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

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": "[email protected]"},
        {"userId": "user-5", "email": "[email protected]"},
    }).
    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

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors

Languages