electrodb

package
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 26, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package electrodb provides a Go implementation of ElectroDB, a DynamoDB library that simplifies working with single-table design patterns.

GoElectroDB brings the power of ElectroDB's JavaScript library to Go developers, offering a fluent API for defining entities, building queries, and managing complex access patterns in DynamoDB.

Key Features

  • Single-table design support with automatic key composition
  • Fluent query builder with type-safe operations
  • Batch operations (BatchGet, BatchWrite)
  • Transaction support (TransactWrite, TransactGet)
  • Automatic pagination with cursor-based navigation
  • Filter expressions with named filters
  • Condition expressions for conditional mutations
  • Automatic timestamps (createdAt, updatedAt)
  • Attribute validation and transformation
  • TTL (Time-To-Live) support

Quick Start

Define an entity 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},
		"name":      {Type: electrodb.AttributeTypeString},
		"createdAt": {Type: electrodb.AttributeTypeString},
	},
	Indexes: map[string]*electrodb.IndexDefinition{
		"primary": {
			PK: electrodb.FacetDefinition{Field: "pk", Facets: []string{"userId"}},
			SK: &electrodb.FacetDefinition{Field: "sk", Facets: []string{"email"}},
		},
	},
}

Create an entity and perform operations: 

entity := electrodb.NewEntity(schema, &electrodb.Config{
	Client: dynamoClient,
})

// Create an item
resp, err := entity.Put(electrodb.Item{
	"userId": "user-123",
	"email":  "user@example.com",
	"name":   "John Doe",
}).Go()

// Query items
results, err := entity.Query().Primary(electrodb.Keys{
	"userId": "user-123",
}).Go()

Error Handling

All operations return an *ElectroError on failure. Use the Code field to programmatically handle specific error types: 

resp, err := entity.Get(keys).Go()
if err != nil {
	var electroErr *electrodb.ElectroError
	if errors.As(err, &electroErr) {
		switch electroErr.Code {
		case electrodb.ErrNoClientProvided:
			// Handle missing client
		case electrodb.ErrDynamoDB:
			// Handle DynamoDB errors
		}
	}
}

Services and Collections

Group related entities into services for collection queries: 

service := electrodb.NewService(&electrodb.ServiceConfig{
	Table:  "my-table",
	Client: dynamoClient,
})
service.AddEntity("user", userEntity)
service.AddEntity("order", orderEntity)

// Query a collection across entities
results, err := service.Collection("orders_by_user").
	Query(electrodb.Keys{"userId": "user-123"}).Go()

For more information, see the README and examples in the repository.

Index

Constants

View Source 
const (
	// MaxBatchGetItems is the maximum number of items in a batch get request
	MaxBatchGetItems = 100
	// MaxBatchWriteItems is the maximum number of items in a batch write request
	MaxBatchWriteItems = 25
)
View Source 
const (
	ErrBatchTooLarge       = "BatchTooLarge"
	ErrCollectionNotFound  = "CollectionNotFound"
	ErrCursorDecoding      = "CursorDecodingError"
	ErrCursorEncoding      = "CursorEncodingError"
	ErrDuplicateEntity     = "DuplicateEntity"
	ErrDynamoDB            = "DynamoDBError"
	ErrEntityNotFound      = "EntityNotFound"
	ErrInvalidEntity       = "InvalidEntity"
	ErrInvalidEnumValue    = "InvalidEnumValue"
	ErrInvalidIndex        = "InvalidIndex"
	ErrInvalidKeys         = "InvalidKeys"
	ErrInvalidOperation    = "InvalidOperation"
	ErrInvalidSchema       = "InvalidSchema"
	ErrMarshal             = "MarshalError"
	ErrMissingAttribute    = "MissingAttribute"
	ErrNoClientProvided    = "NoClientProvided"
	ErrReadOnlyViolation   = "ReadOnlyViolation"
	ErrTransactionCanceled = "TransactionCanceled"
	ErrTransaction         = "TransactionError"
	ErrUnmarshal           = "UnmarshalError"
	ErrValidation          = "ValidationError"
)

Error codes returned by ElectroDB operations

View Source 
const Version = "1.1.1"

Version is the current version of the goelectrodb library.

Variables

This section is empty.

Functions

func ApplyUpdateTimestamps 

func ApplyUpdateTimestamps(setOps map[string]interface{}, schema *Schema) map[string]interface{}

ApplyUpdateTimestamps applies automatic timestamps to update operations This adds updatedAt to SET operations

func IsTTLExpired 

func IsTTLExpired(ttl int64) bool

IsTTLExpired checks if a TTL timestamp has expired

func MergeExpressionAttributes 

func MergeExpressionAttributes(
	existingNames map[string]string,
	existingValues map[string]types.AttributeValue,
	newNames map[string]string,
	newValues map[string]types.AttributeValue,
) (map[string]string, map[string]types.AttributeValue)

Merge merges expression names and values into existing maps

func TTLFromNow 

func TTLFromNow(duration time.Duration) int64

TTLFromNow calculates a TTL timestamp from the current time plus duration

func TTLFromTime 

func TTLFromTime(t time.Time) int64

TTLFromTime calculates a TTL timestamp from a specific time

func TimeUntilTTL 

func TimeUntilTTL(ttl int64) time.Duration

TimeUntilTTL returns the duration until the TTL expires

Types

type AttributeDefinition 

type AttributeDefinition struct {
	Type       AttributeType
	Required   bool
	Default    DefaultFunc
	Validate   ValidationFunc
	Field      string // DynamoDB field name (if different from attribute name)
	Get        GetFunc
	Set        SetFunc
	ReadOnly   bool
	Watch      []string // Attributes to watch for changes
	Label      string
	Cast       string
	Padding    *PaddingConfig
	Hidden     bool
	EnumValues []interface{} // For enum type
}

AttributeDefinition defines a single attribute in the schema

type AttributeOperations 

type AttributeOperations map[string]*AttributeOperator

AttributeOperations provides operations for filter building

type AttributeOperator 

type AttributeOperator struct {
	// contains filtered or unexported fields
}

AttributeOperator provides comparison operations for an attribute

func (*AttributeOperator) Begins 

func (a *AttributeOperator) Begins(value interface{}) string

Begins generates a begins_with filter expression

func (*AttributeOperator) Between 

func (a *AttributeOperator) Between(low, high interface{}) string

Between generates a BETWEEN filter expression

func (*AttributeOperator) Contains 

func (a *AttributeOperator) Contains(value interface{}) string

Contains generates a contains filter expression

func (*AttributeOperator) Eq 

func (a *AttributeOperator) Eq(value interface{}) string

Eq generates an equals filter expression

func (*AttributeOperator) Gt 

func (a *AttributeOperator) Gt(value interface{}) string

Gt generates a greater-than filter expression

func (*AttributeOperator) Gte 

func (a *AttributeOperator) Gte(value interface{}) string

Gte generates a greater-than-or-equal filter expression

func (*AttributeOperator) Lt 

func (a *AttributeOperator) Lt(value interface{}) string

Lt generates a less-than filter expression

func (*AttributeOperator) Lte 

func (a *AttributeOperator) Lte(value interface{}) string

Lte generates a less-than-or-equal filter expression

func (*AttributeOperator) Ne 

func (a *AttributeOperator) Ne(value interface{}) string

Ne generates a not-equals filter expression

type AttributeRef 

type AttributeRef struct {
	// contains filtered or unexported fields
}

AttributeRef represents a reference to an attribute in an expression

func (*AttributeRef) Begins 

func (ar *AttributeRef) Begins(value interface{}) string

Begins creates a begins_with condition

func (*AttributeRef) Between 

func (ar *AttributeRef) Between(start, end interface{}) string

Between creates a between condition

func (*AttributeRef) Contains 

func (ar *AttributeRef) Contains(value interface{}) string

Contains creates a contains condition

func (*AttributeRef) Eq 

func (ar *AttributeRef) Eq(value interface{}) string

Eq creates an equals condition

func (*AttributeRef) Gt 

func (ar *AttributeRef) Gt(value interface{}) string

Gt creates a greater-than condition

func (*AttributeRef) Gte 

func (ar *AttributeRef) Gte(value interface{}) string

Gte creates a greater-than-or-equal condition

func (*AttributeRef) Lt 

func (ar *AttributeRef) Lt(value interface{}) string

Lt creates a less-than condition

func (*AttributeRef) Lte 

func (ar *AttributeRef) Lte(value interface{}) string

Lte creates a less-than-or-equal condition

func (*AttributeRef) Ne 

func (ar *AttributeRef) Ne(value interface{}) string

Ne creates a not-equals condition

type AttributeType 

type AttributeType string

AttributeType represents the type of an attribute 

const (
	AttributeTypeString  AttributeType = "string"
	AttributeTypeNumber  AttributeType = "number"
	AttributeTypeBoolean AttributeType = "boolean"
	AttributeTypeEnum    AttributeType = "enum"
	AttributeTypeAny     AttributeType = "any"
	AttributeTypeList    AttributeType = "list"
	AttributeTypeMap     AttributeType = "map"
	AttributeTypeSet     AttributeType = "set"
)

type BatchGetRequest 

type BatchGetRequest struct {
	// contains filtered or unexported fields
}

BatchGetRequest represents a batch get request

func (*BatchGetRequest) Go 

func (bgr *BatchGetRequest) Go() (*BatchGetResponse, error)

Go executes the batch get operation

type BatchGetResponse 

type BatchGetResponse struct {
	Data        []map[string]interface{}
	Unprocessed []Keys
}

BatchGetResponse represents a batch get response

type BatchGetService 

type BatchGetService struct {
	// contains filtered or unexported fields
}

BatchGetService creates a batch get request across multiple entities in a service

func (*BatchGetService) Get 

func (bgs *BatchGetService) Get(entityName string, keys []Keys) *BatchGetService

Get adds get requests for a specific entity

func (*BatchGetService) Go 

func (bgs *BatchGetService) Go() (*BatchGetServiceResponse, error)

Go executes the batch get operation across entities

type BatchGetServiceResponse 

type BatchGetServiceResponse struct {
	Data        map[string][]map[string]interface{}
	Unprocessed map[string][]Keys
}

BatchGetServiceResponse represents a batch get service response

type BatchWriteRequest 

type BatchWriteRequest struct {
	// contains filtered or unexported fields
}

BatchWriteRequest represents a batch write request

func (*BatchWriteRequest) Delete 

func (bwr *BatchWriteRequest) Delete(keys []Keys) *BatchWriteRequest

Delete adds delete operations to the batch

func (*BatchWriteRequest) Go 

func (bwr *BatchWriteRequest) Go() (*BatchWriteResponse, error)

Go executes the batch write operation

func (*BatchWriteRequest) Put 

func (bwr *BatchWriteRequest) Put(items []Item) *BatchWriteRequest

Put adds put operations to the batch

type BatchWriteResponse 

type BatchWriteResponse struct {
	Unprocessed struct {
		Puts    []Item
		Deletes []Keys
	}
}

BatchWriteResponse represents a batch write response

type BatchWriteService 

type BatchWriteService struct {
	// contains filtered or unexported fields
}

BatchWriteService creates a batch write request across multiple entities in a service

func (*BatchWriteService) Delete 

func (bws *BatchWriteService) Delete(entityName string, keys []Keys) *BatchWriteService

Delete adds delete operations for a specific entity

func (*BatchWriteService) Go 

func (bws *BatchWriteService) Go() (*BatchWriteServiceResponse, error)

Go executes the batch write operation across entities

func (*BatchWriteService) Put 

func (bws *BatchWriteService) Put(entityName string, items []Item) *BatchWriteService

Put adds put operations for a specific entity

type BatchWriteServiceResponse 

type BatchWriteServiceResponse struct {
	Unprocessed map[string]struct {
		Puts    []Item
		Deletes []Keys
	}
}

BatchWriteServiceResponse represents a batch write service response

type Collection 

type Collection struct {
	// contains filtered or unexported fields
}

Collection represents a cross-entity query collection

func (*Collection) Query 

func (c *Collection) Query(facets ...interface{}) *CollectionQuery

Query starts a collection query

type CollectionQuery 

type CollectionQuery struct {
	// contains filtered or unexported fields
}

CollectionQuery represents a query across multiple entities in a collection

func (*CollectionQuery) Begins 

func (cq *CollectionQuery) Begins(value interface{}) *CollectionQuery

Begins adds a begins-with condition on the sort key

func (*CollectionQuery) Between 

func (cq *CollectionQuery) Between(start, end interface{}) *CollectionQuery

Between adds a between condition on the sort key

func (*CollectionQuery) Eq 

func (cq *CollectionQuery) Eq(value interface{}) *CollectionQuery

Eq adds an equals condition on the sort key

func (*CollectionQuery) Go 

func (cq *CollectionQuery) Go() (*CollectionQueryResponse, error)

Go executes the collection query

func (*CollectionQuery) Gt 

func (cq *CollectionQuery) Gt(value interface{}) *CollectionQuery

Gt adds a greater-than condition on the sort key

func (*CollectionQuery) Gte 

func (cq *CollectionQuery) Gte(value interface{}) *CollectionQuery

Gte adds a greater-than-or-equal condition on the sort key

func (*CollectionQuery) Lt 

func (cq *CollectionQuery) Lt(value interface{}) *CollectionQuery

Lt adds a less-than condition on the sort key

func (*CollectionQuery) Lte 

func (cq *CollectionQuery) Lte(value interface{}) *CollectionQuery

Lte adds a less-than-or-equal condition on the sort key

func (*CollectionQuery) Options 

func (cq *CollectionQuery) Options(opts *QueryOptions) *CollectionQuery

Options sets query options

func (*CollectionQuery) Params 

func (cq *CollectionQuery) Params() (map[string]interface{}, error)

Params returns the DynamoDB parameters for the collection query

type CollectionQueryResponse 

type CollectionQueryResponse struct {
	Data   map[string][]map[string]interface{}
	Cursor *string
}

CollectionQueryResponse represents a collection query response

type ConditionBuilder 

type ConditionBuilder struct {
	// contains filtered or unexported fields
}

ConditionBuilder adds condition expression support

func NewConditionBuilder 

func NewConditionBuilder(attributes map[string]*AttributeDefinition) *ConditionBuilder

NewConditionBuilder creates a new condition builder

func (*ConditionBuilder) Build 

func (cb *ConditionBuilder) Build() (string, map[string]string, map[string]types.AttributeValue)

Build returns the condition expression and attributes

func (*ConditionBuilder) Where 

func (cb *ConditionBuilder) Where(callback WhereCallback) error

Where adds a condition expression

type Config 

type Config struct {
	Client      DynamoDBClient
	Table       *string
	Listeners   []EventListener
	Logger      Logger
	Identifiers *IdentifierConfig
}

Config holds entity configuration

type DefaultFunc 

type DefaultFunc func() interface{}

DefaultFunc is a function that returns a default value for an attribute

type DeleteOperation 

type DeleteOperation struct {
	// contains filtered or unexported fields
}

DeleteOperation represents a delete operation

func (*DeleteOperation) Commit 

func (d *DeleteOperation) Commit() TransactionItem

Commit prepares a delete operation for a transaction

func (*DeleteOperation) Condition 

func (d *DeleteOperation) Condition(callback WhereCallback) *DeleteOperation

Condition adds a condition expression to the delete operation

func (*DeleteOperation) Go 

func (d *DeleteOperation) Go() (*DeleteResponse, error)

Go executes the delete operation

func (*DeleteOperation) Params 

func (d *DeleteOperation) Params() (map[string]interface{}, error)

Params returns the DynamoDB parameters without executing

type DeleteOptions 

type DeleteOptions struct {
	Response   *string
	Attributes []string
	Raw        bool
}

DeleteOptions defines options for delete operations

type DeleteResponse 

type DeleteResponse struct {
	Data map[string]interface{}
}

DeleteResponse represents a delete response

type DynamoDBClient 

type DynamoDBClient interface {
	GetItem(ctx context.Context, params *dynamodb.GetItemInput, optFns ...func(*dynamodb.Options)) (*dynamodb.GetItemOutput, error)
	PutItem(ctx context.Context, params *dynamodb.PutItemInput, optFns ...func(*dynamodb.Options)) (*dynamodb.PutItemOutput, error)
	UpdateItem(ctx context.Context, params *dynamodb.UpdateItemInput, optFns ...func(*dynamodb.Options)) (*dynamodb.UpdateItemOutput, error)
	DeleteItem(ctx context.Context, params *dynamodb.DeleteItemInput, optFns ...func(*dynamodb.Options)) (*dynamodb.DeleteItemOutput, error)
	Query(ctx context.Context, params *dynamodb.QueryInput, optFns ...func(*dynamodb.Options)) (*dynamodb.QueryOutput, error)
	Scan(ctx context.Context, params *dynamodb.ScanInput, optFns ...func(*dynamodb.Options)) (*dynamodb.ScanOutput, error)
	BatchGetItem(ctx context.Context, params *dynamodb.BatchGetItemInput, optFns ...func(*dynamodb.Options)) (*dynamodb.BatchGetItemOutput, error)
	BatchWriteItem(ctx context.Context, params *dynamodb.BatchWriteItemInput, optFns ...func(*dynamodb.Options)) (*dynamodb.BatchWriteItemOutput, error)
	TransactWriteItems(ctx context.Context, params *dynamodb.TransactWriteItemsInput, optFns ...func(*dynamodb.Options)) (*dynamodb.TransactWriteItemsOutput, error)
	TransactGetItems(ctx context.Context, params *dynamodb.TransactGetItemsInput, optFns ...func(*dynamodb.Options)) (*dynamodb.TransactGetItemsOutput, error)
}

DynamoDBClient is an interface for DynamoDB operations

type ElectroError 

type ElectroError struct {
	Code    string
	Message string
	Cause   error
	Time    time.Time
}

ElectroError represents an error from ElectroDB

func NewElectroError 

func NewElectroError(code, message string, cause error) *ElectroError

NewElectroError creates a new ElectroError

func (*ElectroError) Error 

func (e *ElectroError) Error() string

type Entity 

type Entity struct {
	// contains filtered or unexported fields
}

Entity represents a DynamoDB entity with schema and operations

func NewEntity 

func NewEntity(schema *Schema, config *Config) (*Entity, error)

NewEntity creates a new Entity instance

func (*Entity) BatchGet 

func (e *Entity) BatchGet(keys []Keys) *BatchGetRequest

BatchGet creates a new batch get request

func (*Entity) BatchWrite 

func (e *Entity) BatchWrite() *BatchWriteRequest

BatchWrite creates a new batch write request

func (*Entity) Create 

func (e *Entity) Create(item Item) *PutOperation

Create creates a new item (fails if exists)

func (*Entity) Delete 

func (e *Entity) Delete(keys Keys) *DeleteOperation

Delete deletes an item

func (*Entity) Get 

func (e *Entity) Get(keys Keys) *GetOperation

Get retrieves an item by its key

func (*Entity) Patch 

func (e *Entity) Patch(keys Keys) *UpdateOperation

Patch partially updates an item

func (*Entity) Put 

func (e *Entity) Put(item Item) *PutOperation

Put creates or replaces an item

func (*Entity) Query 

func (e *Entity) Query(accessPattern string) QueryBuilder

Query returns a query builder for the specified access pattern

func (*Entity) Remove 

func (e *Entity) Remove(keys Keys) *DeleteOperation

Remove is an alias for Delete

func (*Entity) Scan 

func (e *Entity) Scan() *ScanOperation

Scan performs a table scan

func (*Entity) Schema 

func (e *Entity) Schema() *Schema

Schema returns the entity schema

func (*Entity) Update 

func (e *Entity) Update(keys Keys) *UpdateOperation

Update updates an existing item

func (*Entity) Upsert 

func (e *Entity) Upsert(item Item) *PutOperation

Upsert creates a new item or updates an existing one This is an alias for Put, which naturally upserts in DynamoDB

func (*Entity) UpsertUpdate 

func (e *Entity) UpsertUpdate(keys Keys) *UpdateOperation

Upsert creates or updates an item using UpdateItem Unlike Upsert(), which uses Put, this uses Update which allows partial updates This will create the item if it doesn't exist, or update specific attributes if it does

type EventListener 

type EventListener interface {
	OnQuery(params map[string]interface{})
	OnResults(results interface{})
}

EventListener is an interface for event listeners

type ExecutionHelper 

type ExecutionHelper struct {
	// contains filtered or unexported fields
}

ExecutionHelper helps execute DynamoDB operations

func NewExecutionHelper 

func NewExecutionHelper(entity *Entity) *ExecutionHelper

NewExecutionHelper creates a new ExecutionHelper

func (*ExecutionHelper) ExecuteDeleteItem 

func (eh *ExecutionHelper) ExecuteDeleteItem(ctx context.Context, keys Keys, options *DeleteOptions) (*DeleteResponse, error)

ExecuteDeleteItem executes a DeleteItem operation

func (*ExecutionHelper) ExecuteGetItem 

func (eh *ExecutionHelper) ExecuteGetItem(ctx context.Context, keys Keys, options *GetOptions) (*GetResponse, error)

ExecuteGetItem executes a GetItem operation

func (*ExecutionHelper) ExecutePutItem 

func (eh *ExecutionHelper) ExecutePutItem(ctx context.Context, item Item, options *PutOptions) (*PutResponse, error)

ExecutePutItem executes a PutItem operation

func (*ExecutionHelper) ExecuteQuery 

func (eh *ExecutionHelper) ExecuteQuery(
	ctx context.Context,
	indexName string,
	pkFacets []interface{},
	skFacets []interface{},
	skCondition *sortKeyCondition,
	options *QueryOptions,
	filterBuilder *FilterBuilder,
) (*QueryResponse, error)

ExecuteQuery executes a Query operation

func (*ExecutionHelper) ExecuteScan 

func (eh *ExecutionHelper) ExecuteScan(ctx context.Context, options *QueryOptions) (*ScanResponse, error)

ExecuteScan executes a Scan operation

func (*ExecutionHelper) ExecuteUpdateItem 

func (eh *ExecutionHelper) ExecuteUpdateItem(
	ctx context.Context,
	keys Keys,
	setOps map[string]interface{},
	addOps map[string]interface{},
	delOps map[string]interface{},
	remOps []string,
	appendOps map[string]interface{},
	prependOps map[string]interface{},
	subtractOps map[string]interface{},
	dataOps map[string]interface{},
	options *UpdateOptions,
) (*UpdateResponse, error)

ExecuteUpdateItem executes an UpdateItem operation

type ExpressionBuilder 

type ExpressionBuilder struct {
	// contains filtered or unexported fields
}

ExpressionBuilder builds DynamoDB filter and condition expressions

func NewExpressionBuilder 

func NewExpressionBuilder(attributes map[string]*AttributeDefinition) *ExpressionBuilder

NewExpressionBuilder creates a new expression builder

func (*ExpressionBuilder) AddExpression 

func (eb *ExpressionBuilder) AddExpression(expr string)

AddExpression adds an expression to the builder

func (*ExpressionBuilder) Build 

func (eb *ExpressionBuilder) Build() (string, map[string]string, map[string]types.AttributeValue)

Build returns the built expression and attributes

func (*ExpressionBuilder) BuildWhereExpression 

func (eb *ExpressionBuilder) BuildWhereExpression(callback WhereCallback) error

BuildWhereExpression builds an expression from a where callback

func (*ExpressionBuilder) GetExpression 

func (eb *ExpressionBuilder) GetExpression() string

GetExpression returns just the expression string

type FacetDefinition 

type FacetDefinition struct {
	Field    string
	Facets   []string
	Casing   *string // optional: "upper", "lower", "none", "default"
	Template *string
}

FacetDefinition defines partition or sort key facets

type FilterBuilder 

type FilterBuilder struct {
	// contains filtered or unexported fields
}

FilterBuilder adds filter expression support to operations

func NewFilterBuilder 

func NewFilterBuilder(attributes map[string]*AttributeDefinition) *FilterBuilder

NewFilterBuilder creates a new filter builder

func NewFilterBuilderFromBuilder added in v1.1.1 

func NewFilterBuilderFromBuilder(eb *ExpressionBuilder) *FilterBuilder

NewFilterBuilderFromBuilder creates a FilterBuilder that reuses an existing ExpressionBuilder, preserving its name/value counters and accumulated state.

This is used when chaining multiple Where()/Filter() calls so that placeholder indices (#attr0, #attr1, ..., :val0, :val1, ...) remain monotonic across clauses. Constructing a fresh ExpressionBuilder per chained call would reset the counters and silently overwrite earlier bindings during merge.

func (*FilterBuilder) Build 

func (fb *FilterBuilder) Build() (string, map[string]string, map[string]types.AttributeValue)

Build returns the filter expression and attributes

func (*FilterBuilder) Where 

func (fb *FilterBuilder) Where(callback WhereCallback) error

Where adds a where clause

type FilterFunc 

type FilterFunc func(attr AttributeOperations, params map[string]interface{}) string

FilterFunc is a custom filter function

type GetFunc 

type GetFunc func(value interface{}) interface{}

GetFunc is a function that transforms a value when reading from DynamoDB

type GetOperation 

type GetOperation struct {
	// contains filtered or unexported fields
}

GetOperation represents a get operation

func (*GetOperation) Commit 

func (g *GetOperation) Commit() TransactionItem

Commit prepares a get operation for a transaction

func (*GetOperation) Go 

func (g *GetOperation) Go() (*GetResponse, error)

Go executes the get operation

func (*GetOperation) Params 

func (g *GetOperation) Params() (map[string]interface{}, error)

Params returns the DynamoDB parameters without executing

type GetOptions 

type GetOptions struct {
	Attributes []string
	Raw        bool
}

GetOptions defines options for get operations

type GetResponse 

type GetResponse struct {
	Data map[string]interface{}
}

GetResponse represents a get response

type IdentifierConfig 

type IdentifierConfig struct {
	Entity  string
	Version string
}

IdentifierConfig defines entity identifiers

type IndexDefinition 

type IndexDefinition struct {
	Index      *string          // GSI name (nil for primary index)
	PK         FacetDefinition  `json:"pk"`
	SK         *FacetDefinition `json:"sk,omitempty"`
	Collection *string          // Collection name for this index
	Type       *string          // "isolated" or "clustered"
}

IndexDefinition defines a primary or secondary index

type Item 

type Item map[string]interface{}

Item represents a DynamoDB item

func ApplyPadding 

func ApplyPadding(item Item, schema *Schema) Item

ApplyPadding applies padding to attributes that have PaddingConfig This is used to zero-pad numbers for proper string sorting

func ApplyTimestamps 

func ApplyTimestamps(item Item, schema *Schema, isUpdate bool) Item

ApplyTimestamps applies automatic timestamps to an item This is called during Put/Create operations

func RemovePadding 

func RemovePadding(item Item, schema *Schema) Item

RemovePadding removes padding from attributes that have PaddingConfig This is used when reading from DynamoDB

type Keys 

type Keys map[string]interface{}

Keys represents the keys for a DynamoDB item

type Logger 

type Logger interface {
	Info(message string, data map[string]interface{})
	Warn(message string, data map[string]interface{})
	Error(message string, data map[string]interface{})
}

Logger is an interface for logging

type OperationBuilder 

type OperationBuilder struct {
	// contains filtered or unexported fields
}

OperationBuilder provides filter operation methods

func (*OperationBuilder) AttributeType 

func (ob *OperationBuilder) AttributeType(attr *AttributeRef, typeName string) string

AttributeType checks the type of an attribute

func (*OperationBuilder) Exists 

func (ob *OperationBuilder) Exists(attr *AttributeRef) string

Exists creates an attribute_exists condition

func (*OperationBuilder) NotExists 

func (ob *OperationBuilder) NotExists(attr *AttributeRef) string

NotExists creates an attribute_not_exists condition

func (*OperationBuilder) Size 

func (ob *OperationBuilder) Size(attr *AttributeRef) string

Size returns the size of an attribute

type PaddingConfig 

type PaddingConfig struct {
	Length int
	Char   string
}

PaddingConfig defines padding configuration for attributes

type Page 

type Page struct {
	Data   []map[string]interface{}
	Cursor *string
}

Page represents a single page of query results

type PagesIterator 

type PagesIterator struct {
	// contains filtered or unexported fields
}

PagesIterator provides an iterator interface for paginating through results

func (*PagesIterator) Next 

func (pi *PagesIterator) Next() (*Page, bool, error)

Next retrieves the next page of results Returns (page, hasMore, error)

type PagesOptions 

type PagesOptions struct {
	MaxPages int   // Maximum number of pages to retrieve
	Limit    int32 // Items per page
}

PagesOptions configures pagination behavior

type ParamsBuilder 

type ParamsBuilder struct {
	// contains filtered or unexported fields
}

ParamsBuilder builds DynamoDB operation parameters

func NewParamsBuilder 

func NewParamsBuilder(entity *Entity) *ParamsBuilder

NewParamsBuilder creates a new ParamsBuilder

func (*ParamsBuilder) BuildDeleteItemParams 

func (pb *ParamsBuilder) BuildDeleteItemParams(keys Keys, options *DeleteOptions) (map[string]interface{}, error)

BuildDeleteItemParams builds parameters for DeleteItem operation

func (*ParamsBuilder) BuildGetItemParams 

func (pb *ParamsBuilder) BuildGetItemParams(keys Keys, options *GetOptions) (map[string]interface{}, error)

BuildGetItemParams builds parameters for GetItem operation

func (*ParamsBuilder) BuildPutItemParams 

func (pb *ParamsBuilder) BuildPutItemParams(item Item, options *PutOptions) (map[string]interface{}, error)

BuildPutItemParams builds parameters for PutItem operation

func (*ParamsBuilder) BuildQueryParams 

func (pb *ParamsBuilder) BuildQueryParams(
	indexName string,
	pkFacets []interface{},
	skFacets []interface{},
	skCondition *sortKeyCondition,
	options *QueryOptions,
	filterBuilder *FilterBuilder,
) (map[string]interface{}, error)

BuildQueryParams builds parameters for Query operation

func (*ParamsBuilder) BuildUpdateItemParams 

func (pb *ParamsBuilder) BuildUpdateItemParams(
	keys Keys,
	setOps map[string]interface{},
	addOps map[string]interface{},
	delOps map[string]interface{},
	remOps []string,
	appendOps map[string]interface{},
	prependOps map[string]interface{},
	subtractOps map[string]interface{},
	dataOps map[string]interface{},
	options *UpdateOptions,
) (map[string]interface{}, error)

BuildUpdateItemParams builds parameters for UpdateItem operation

type PutOperation 

type PutOperation struct {
	// contains filtered or unexported fields
}

PutOperation represents a put operation

func (*PutOperation) Commit 

func (p *PutOperation) Commit() TransactionItem

Commit prepares a put operation for a transaction

func (*PutOperation) Condition 

func (p *PutOperation) Condition(callback WhereCallback) *PutOperation

Condition adds a condition expression to the put operation

func (*PutOperation) Go 

func (p *PutOperation) Go() (*PutResponse, error)

Go executes the put operation

func (*PutOperation) Params 

func (p *PutOperation) Params() (map[string]interface{}, error)

Params returns the DynamoDB parameters without executing

func (*PutOperation) WithTTL 

func (p *PutOperation) WithTTL(duration time.Duration) *PutOperation

WithTTL sets a TTL (Time-To-Live) on a put operation The item will automatically be deleted by DynamoDB after the specified duration

func (*PutOperation) WithTTLTimestamp 

func (p *PutOperation) WithTTLTimestamp(timestamp int64) *PutOperation

WithTTLTimestamp sets a TTL using an explicit Unix timestamp

type PutOptions 

type PutOptions struct {
	Response   *string // "none", "all_old", "all_new"
	Attributes []string
	Raw        bool
}

PutOptions defines options for put operations

type PutResponse 

type PutResponse struct {
	Data map[string]interface{}
}

PutResponse represents a put response

type QueryBuilder 

type QueryBuilder interface {
	// Query starts a query with partition key facets
	Query(facets ...interface{}) *QueryChain
}

QueryBuilder is an interface for building queries

type QueryChain 

type QueryChain struct {
	// contains filtered or unexported fields
}

QueryChain represents a chainable query

func (*QueryChain) Begins 

func (qc *QueryChain) Begins(value interface{}) *QueryChain

Begins adds a begins-with condition on the sort key

func (*QueryChain) Between 

func (qc *QueryChain) Between(start, end interface{}) *QueryChain

Between adds a between condition on the sort key

func (*QueryChain) Eq 

func (qc *QueryChain) Eq(value interface{}) *QueryChain

Eq adds an equals condition on the sort key

func (*QueryChain) Filter 

func (qc *QueryChain) Filter(filterName string, params map[string]interface{}) *QueryChain

Filter adds a filter using a named filter from schema

When chained, Filter() reuses the underlying ExpressionBuilder of the QueryChain's existing filterBuilder so that placeholder counters remain monotonic across chained Where()/Filter() calls. See Where() for details on the placeholder-collision security hazard this avoids.

func (*QueryChain) Go 

func (qc *QueryChain) Go() (*QueryResponse, error)

Go executes the query

func (*QueryChain) Gt 

func (qc *QueryChain) Gt(value interface{}) *QueryChain

Gt adds a greater-than condition on the sort key

func (*QueryChain) Gte 

func (qc *QueryChain) Gte(value interface{}) *QueryChain

Gte adds a greater-than-or-equal condition on the sort key

func (*QueryChain) Lt 

func (qc *QueryChain) Lt(value interface{}) *QueryChain

Lt adds a less-than condition on the sort key

func (*QueryChain) Lte 

func (qc *QueryChain) Lte(value interface{}) *QueryChain

Lte adds a less-than-or-equal condition on the sort key

func (*QueryChain) Options 

func (qc *QueryChain) Options(opts *QueryOptions) *QueryChain

Options sets query options

func (*QueryChain) Page 

func (qc *QueryChain) Page(opts ...PagesOptions) *PagesIterator

Page returns an iterator for manually controlling pagination

func (*QueryChain) Pages 

func (qc *QueryChain) Pages(opts ...PagesOptions) ([]map[string]interface{}, error)

Pages returns all pages of results by automatically following cursors This is a convenience method that handles pagination automatically

func (*QueryChain) Params 

func (qc *QueryChain) Params() (map[string]interface{}, error)

Params returns the DynamoDB parameters without executing

func (*QueryChain) Where 

func (qc *QueryChain) Where(callback WhereCallback) *QueryChain

Where adds a custom filter expression

When chained, each Where() call reuses the underlying ExpressionBuilder of the QueryChain's existing filterBuilder so that placeholder counters (#attr0/#attr1/..., :val0/:val1/...) remain monotonic. Otherwise, every chained Where() would emit colliding placeholders that overwrite earlier bindings during merge -- a security hazard for tenant-isolation guards.

type QueryOptions 

type QueryOptions struct {
	Limit        *int32
	Pages        *int
	Cursor       *string
	Raw          bool
	Attributes   []string
	Order        *string // "asc" or "desc"
	Concurrent   *int
	IgnoreCursor bool
}

QueryOptions defines options for query execution

type QueryResponse 

type QueryResponse struct {
	Data   []map[string]interface{}
	Cursor *string
}

QueryResponse represents a query response

type ScanOperation 

type ScanOperation struct {
	// contains filtered or unexported fields
}

ScanOperation represents a scan operation

func (*ScanOperation) Go 

func (s *ScanOperation) Go() (*ScanResponse, error)

Go executes the scan operation

func (*ScanOperation) Page 

func (s *ScanOperation) Page(opts ...PagesOptions) *ScanPagesIterator

Page returns an iterator for manually controlling scan pagination

func (*ScanOperation) Pages 

func (s *ScanOperation) Pages(opts ...PagesOptions) ([]map[string]interface{}, error)

ScanPages returns all pages of scan results

func (*ScanOperation) Params 

func (s *ScanOperation) Params() (map[string]interface{}, error)

Params returns the DynamoDB parameters without executing

type ScanPagesIterator 

type ScanPagesIterator struct {
	// contains filtered or unexported fields
}

ScanPagesIterator provides an iterator interface for scan pagination

func (*ScanPagesIterator) Next 

func (spi *ScanPagesIterator) Next() (*Page, bool, error)

Next retrieves the next page of scan results

type ScanResponse 

type ScanResponse struct {
	Data   []map[string]interface{}
	Cursor *string
}

ScanResponse represents a scan response

type Schema 

type Schema struct {
	Service    string
	Entity     string
	Table      string
	Version    string
	Attributes map[string]*AttributeDefinition
	Indexes    map[string]*IndexDefinition
	Filters    map[string]FilterFunc
	TTL        *TTLConfig        // Time-To-Live configuration
	Timestamps *TimestampsConfig // Automatic timestamp management
}

Schema defines the entity schema

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service manages multiple entities in a single table

func NewService 

func NewService(name string, config *ServiceConfig) *Service

NewService creates a new Service instance

func (*Service) BatchGet 

func (s *Service) BatchGet() *BatchGetService

BatchGet creates a new batch get request for the service

func (*Service) BatchWrite 

func (s *Service) BatchWrite() *BatchWriteService

BatchWrite creates a new batch write request for the service

func (*Service) Collection 

func (s *Service) Collection(name string) (*Collection, error)

Collection returns a specific collection by name

func (*Service) Collections 

func (s *Service) Collections() map[string]*Collection

Collections returns all collections in the service

func (*Service) Entities 

func (s *Service) Entities() map[string]*Entity

Entities returns all entities in the service

func (*Service) Entity 

func (s *Service) Entity(name string) (*Entity, error)

Entity returns a specific entity by name

func (*Service) Join 

func (s *Service) Join(entity *Entity) error

Join adds an entity to the service

func (*Service) TransactGet 

func (s *Service) TransactGet(fn func(entities map[string]*Entity) []TransactionItem) *TransactGetBuilder

TransactGet creates a new transaction get builder

func (*Service) TransactWrite 

func (s *Service) TransactWrite(fn func(entities map[string]*Entity) []TransactionItem) *TransactWriteBuilder

TransactWrite creates a new transaction write builder

type ServiceConfig 

type ServiceConfig struct {
	Client DynamoDBClient
	Table  *string
}

ServiceConfig holds configuration for a service

type SetFunc 

type SetFunc func(value interface{}) interface{}

SetFunc is a function that transforms a value when writing to DynamoDB

type TTLConfig 

type TTLConfig struct {
	Attribute string // Name of the attribute that stores the TTL timestamp (Unix epoch in seconds)
}

TTLConfig configures TTL (Time-To-Live) for automatic item expiration

type TimestampsConfig 

type TimestampsConfig struct {
	CreatedAt string // Attribute name for creation timestamp (set on Put/Create)
	UpdatedAt string // Attribute name for update timestamp (set on Put/Create/Update)
}

TimestampsConfig configures automatic timestamp management

type TransactDeleteItem 

type TransactDeleteItem struct {
	// contains filtered or unexported fields
}

TransactDeleteItem wraps a delete operation for transactions

func (*TransactDeleteItem) BuildTransactGetItem 

func (tdi *TransactDeleteItem) BuildTransactGetItem() (types.TransactGetItem, error)

BuildTransactGetItem is not supported for delete operations

func (*TransactDeleteItem) BuildTransactItem 

func (tdi *TransactDeleteItem) BuildTransactItem() (types.TransactWriteItem, error)

BuildTransactItem builds the transaction write item

type TransactGetBuilder 

type TransactGetBuilder struct {
	// contains filtered or unexported fields
}

TransactGetBuilder builds a transaction get request

func (*TransactGetBuilder) Go 

func (tgb *TransactGetBuilder) Go() (*TransactGetResponse, error)

Go executes the transaction get

func (*TransactGetBuilder) GoWithContext 

func (tgb *TransactGetBuilder) GoWithContext(ctx context.Context) (*TransactGetResponse, error)

GoWithContext executes the transaction get with a context

func (*TransactGetBuilder) Params 

func (tgb *TransactGetBuilder) Params() (map[string]interface{}, error)

Params returns the DynamoDB parameters without executing

type TransactGetItem 

type TransactGetItem struct {
	// contains filtered or unexported fields
}

TransactGetItem wraps a get operation for transactions

func (*TransactGetItem) BuildTransactGetItem 

func (tgi *TransactGetItem) BuildTransactGetItem() (types.TransactGetItem, error)

BuildTransactGetItem builds the transaction get item

func (*TransactGetItem) BuildTransactItem 

func (tgi *TransactGetItem) BuildTransactItem() (types.TransactWriteItem, error)

BuildTransactItem is not supported for get operations

type TransactGetResponse 

type TransactGetResponse struct {
	Canceled bool
	Data     []TransactResult
}

TransactGetResponse represents a transaction get response

type TransactPutItem 

type TransactPutItem struct {
	// contains filtered or unexported fields
}

TransactPutItem wraps a put operation for transactions

func (*TransactPutItem) BuildTransactGetItem 

func (tpi *TransactPutItem) BuildTransactGetItem() (types.TransactGetItem, error)

BuildTransactGetItem is not supported for put operations

func (*TransactPutItem) BuildTransactItem 

func (tpi *TransactPutItem) BuildTransactItem() (types.TransactWriteItem, error)

BuildTransactItem builds the transaction write item

type TransactResult 

type TransactResult struct {
	Rejected bool
	Code     string
	Message  string
	Item     map[string]interface{}
}

TransactResult represents a single transaction result

type TransactUpdateItem 

type TransactUpdateItem struct {
	// contains filtered or unexported fields
}

TransactUpdateItem wraps an update operation for transactions

func (*TransactUpdateItem) BuildTransactGetItem 

func (tui *TransactUpdateItem) BuildTransactGetItem() (types.TransactGetItem, error)

BuildTransactGetItem is not supported for update operations

func (*TransactUpdateItem) BuildTransactItem 

func (tui *TransactUpdateItem) BuildTransactItem() (types.TransactWriteItem, error)

BuildTransactItem builds the transaction write item

type TransactWriteBuilder 

type TransactWriteBuilder struct {
	// contains filtered or unexported fields
}

TransactWriteBuilder builds a transaction write request

func (*TransactWriteBuilder) Go 

func (twb *TransactWriteBuilder) Go() (*TransactWriteResponse, error)

Go executes the transaction write

func (*TransactWriteBuilder) GoWithContext 

func (twb *TransactWriteBuilder) GoWithContext(ctx context.Context) (*TransactWriteResponse, error)

GoWithContext executes the transaction write with a context

func (*TransactWriteBuilder) Params 

func (twb *TransactWriteBuilder) Params() (map[string]interface{}, error)

Params returns the DynamoDB parameters without executing

type TransactWriteResponse 

type TransactWriteResponse struct {
	Canceled bool
	Data     []TransactResult
}

TransactWriteResponse represents a transaction write response

type TransactionItem 

type TransactionItem interface {
	// BuildTransactItem builds the DynamoDB transaction item
	BuildTransactItem() (types.TransactWriteItem, error)
	// BuildTransactGetItem builds the DynamoDB transaction get item
	BuildTransactGetItem() (types.TransactGetItem, error)
}

TransactionItem represents a single transaction operation

type TransactionResponse 

type TransactionResponse struct {
	Data []map[string]interface{}
}

TransactionResponse represents a transaction response

type UpdateData 

type UpdateData map[string]interface{}

UpdateData represents update data

type UpdateOperation 

type UpdateOperation struct {
	// contains filtered or unexported fields
}

UpdateOperation represents an update operation

func (*UpdateOperation) Add 

func (u *UpdateOperation) Add(updates map[string]interface{}) *UpdateOperation

Add adds to an attribute (for numbers and sets)

func (*UpdateOperation) AddToSet 

func (u *UpdateOperation) AddToSet(attribute string, values interface{}) *UpdateOperation

AddToSet adds values to a set attribute This is a convenience method that wraps Add for clarity Works with String Sets (SS), Number Sets (NS), and Binary Sets (BS)

func (*UpdateOperation) Append 

func (u *UpdateOperation) Append(updates map[string]interface{}) *UpdateOperation

Append appends values to a list attribute Uses DynamoDB's list_append function

func (*UpdateOperation) Commit 

func (u *UpdateOperation) Commit() TransactionItem

Commit prepares an update operation for a transaction

func (*UpdateOperation) Condition 

func (u *UpdateOperation) Condition(callback WhereCallback) *UpdateOperation

Condition adds a condition expression to the update operation

func (*UpdateOperation) Data 

func (u *UpdateOperation) Data(updates map[string]interface{}) *UpdateOperation

Data removes specific elements from a list by index In DynamoDB, this uses REMOVE with list indices

func (*UpdateOperation) DeleteFromSet 

func (u *UpdateOperation) DeleteFromSet(attribute string, values interface{}) *UpdateOperation

DeleteFromSet removes values from a set attribute Works with String Sets (SS), Number Sets (NS), and Binary Sets (BS)

func (*UpdateOperation) Go 

func (u *UpdateOperation) Go() (*UpdateResponse, error)

Go executes the update operation

func (*UpdateOperation) Params 

func (u *UpdateOperation) Params() (map[string]interface{}, error)

Params returns the DynamoDB parameters without executing

func (*UpdateOperation) Prepend 

func (u *UpdateOperation) Prepend(updates map[string]interface{}) *UpdateOperation

Prepend prepends values to a list attribute Uses DynamoDB's list_append function with reversed order

func (*UpdateOperation) Remove 

func (u *UpdateOperation) Remove(attributes []string) *UpdateOperation

Remove removes attributes entirely

func (*UpdateOperation) RemoveTTL 

func (u *UpdateOperation) RemoveTTL() *UpdateOperation

RemoveTTL removes the TTL from an item (prevents auto-deletion)

func (*UpdateOperation) Set 

func (u *UpdateOperation) Set(updates map[string]interface{}) *UpdateOperation

Set sets an attribute value

func (*UpdateOperation) Subtract 

func (u *UpdateOperation) Subtract(updates map[string]interface{}) *UpdateOperation

Subtract subtracts a value from a number attribute This is the opposite of Add

func (*UpdateOperation) WithTTL 

func (u *UpdateOperation) WithTTL(duration time.Duration) *UpdateOperation

WithTTL sets a TTL (Time-To-Live) on an update operation The item will automatically be deleted by DynamoDB after the specified duration

func (*UpdateOperation) WithTTLTimestamp 

func (u *UpdateOperation) WithTTLTimestamp(timestamp int64) *UpdateOperation

WithTTLTimestamp sets a TTL using an explicit Unix timestamp

type UpdateOptions 

type UpdateOptions struct {
	Response   *string
	Attributes []string
	Raw        bool
}

UpdateOptions defines options for update operations

type UpdateResponse 

type UpdateResponse struct {
	Data map[string]interface{}
}

UpdateResponse represents an update response

type ValidationFunc 

type ValidationFunc func(value interface{}) error

ValidationFunc is a function that validates an attribute value

type Validator 

type Validator struct {
	// contains filtered or unexported fields
}

Validator handles attribute validation and transformation

func NewValidator 

func NewValidator(entity *Entity) *Validator

NewValidator creates a new Validator

func (*Validator) ApplySetTransformations 

func (v *Validator) ApplySetTransformations(
	setOps map[string]interface{},
	addOps map[string]interface{},
	delOps map[string]interface{},
) (map[string]interface{}, map[string]interface{}, map[string]interface{}, error)

ApplySetTransformations applies Set transformations to update operations. It also enforces enum membership and any custom Validate callback for SET operations. Errors from those checks are propagated to the caller so the Update/Patch path matches the contract honoured on Put.

func (*Validator) TransformForRead 

func (v *Validator) TransformForRead(item Item) Item

TransformForRead applies Get transformations and filters hidden attributes when reading from DynamoDB

func (*Validator) ValidateAndTransformForWrite 

func (v *Validator) ValidateAndTransformForWrite(item Item, isUpdate bool) (Item, error)

ValidateAndTransformForWrite validates and transforms an item before writing to DynamoDB This applies: validation, enum checks, Set transformations, readonly checks

func (*Validator) ValidateUpdateOperations 

func (v *Validator) ValidateUpdateOperations(
	setOps map[string]interface{},
	addOps map[string]interface{},
	delOps map[string]interface{},
	remOps []string,
	appendOps map[string]interface{},
	prependOps map[string]interface{},
	subtractOps map[string]interface{},
	dataOps map[string]interface{},
) error

ValidateUpdateOperations validates operations for update (SET, ADD, DELETE, REMOVE, APPEND, PREPEND, SUBTRACT, DATA). Each operation map / slice is inspected for ReadOnly attributes; the first violation surfaces as a ReadOnlyViolation ElectroError. APPEND/PREPEND/SUBTRACT/DATA were previously ignored, which let callers mutate ReadOnly attributes by routing through those helpers — extend the signature so every write path is covered.

type WhereCallback 

type WhereCallback func(attrs map[string]*AttributeRef, ops *OperationBuilder) string

WhereCallback is a function that builds a where clause

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.