ddb

Documentation

Index

• func Decode(av types.AttributeValue, val interface{}, coder ...Coder) (err error)
• func Encode(val interface{}, coder ...Coder) (types.AttributeValue, error)
• type CodecOf
  • func Codec[T dynamo.Thing, A any](a string) CodecOf[T, A]
• type Coder
• type Constraint
  • func (Constraint[T]) Constraint(T)
• type Constraints
  • func Schema[T dynamo.Thing, A any](a string) Constraints[T, A]
  • func (eff Constraints[T, A]) Eq(val A) Constraint[T]
  • func (eff Constraints[T, A]) Exists() Constraint[T]
  • func (eff Constraints[T, A]) Ge(val A) Constraint[T]
  • func (eff Constraints[T, A]) Gt(val A) Constraint[T]
  • func (eff Constraints[T, A]) Is(val string) Constraint[T]
  • func (eff Constraints[T, A]) Le(val A) Constraint[T]
  • func (eff Constraints[T, A]) Lt(val A) Constraint[T]
  • func (eff Constraints[T, A]) Ne(val A) Constraint[T]
  • func (eff Constraints[T, A]) NotExists() Constraint[T]
• type DynamoDB
• type Storage
  • func Must[T dynamo.Thing](keyval *Storage[T], err error) *Storage[T]
  • func New[T dynamo.Thing](connector string, opts ...dynamo.Option) (*Storage[T], error)
  • func (db *Storage[T]) Get(ctx context.Context, key T) (T, error)
  • func (db *Storage[T]) Match(ctx context.Context, key T, opts ...interface{ MatchOpt() }) ([]T, error)
  • func (db *Storage[T]) Put(ctx context.Context, entity T, config ...interface{ Constraint(T) }) error
  • func (db *Storage[T]) Remove(ctx context.Context, key T, config ...interface{ Constraint(T) }) (T, error)
  • func (db *Storage[T]) Update(ctx context.Context, entity T, config ...interface{ Constraint(T) }) (T, error)

Functions

func Decode

func Decode(av types.AttributeValue, val interface{}, coder ...Coder) (err error)

Decode is a helper function to decode core domain types from Dynamo DB format. The helper ensures compact URI de-serialization from DynamoDB schema.

  type MyType struct {
    ID   MyComplexType
    Name MyComplexType
  }
  var ID, Name = dynamo.Codec2[MyType, MyDynamoType, MyDynamoType]("ID", "Name")

  func (x *MyType) UnmarshalDynamoDBAttributeValue(av types.AttributeValue) error {
    type tStruct *MyType
    return dynamo.Decode(av, tStruct(x),
      ID.Decode((*MyDynamoType)(&x.ID)),
			Name.Decode((*MyDynamoType)(&x.Name)),
    )
  }

func Encode

func Encode(val interface{}, coder ...Coder) (types.AttributeValue, error)

Encode is a helper function to encode core domain types into struct. The helper ensures compact URI serialization into DynamoDB schema.

  type MyType struct {
    ID   MyComplexType
    Name MyComplexType
  }
  var ID, Name = dynamo.Codec2[MyType, MyDynamoType, MyDynamoType]("ID", "Name")

  func (x MyType) MarshalDynamoDBAttributeValue() (types.AttributeValue, error) {
    type tStruct MyType
    return dynamo.Encode(av, tStruct(x),
      ID.Encode(MyDynamoType(x.ID)),
			Name.Encode(MyDynamoType(x.Name)),
    )
  }

Types

type CodecOf

type CodecOf[T dynamo.Thing, A any] interface {
	Decode(*A) Coder
	Encode(A) Coder
}

CodecOf for struct fields, the type implement Encode/Decode primitives. Codec helps to implement semi-automated encoding/decoding algebraic data type into the format compatible with storage.

Let's consider scenario were application uses complex types that skips implementation of marshal/unmarshal protocols. Here the type MyComplexType needs to be casted to MyDynamoType that knows how to marshal/unmarshal the type.

type MyType struct {
  ID   MyComplexType
  Name MyComplexType
}
var (
  ID   = dynamo.Codec[MyType, MyDynamoType]("ID")
  Name = dynamo.Codec[MyType, MyDynamoType]("Name")
)

func (t MyType) MarshalDynamoDBAttributeValue() (*dynamodb.AttributeValue, error) {
  type tStruct MyType
  return dynamo.Encode(tStruct(p),
    ID.Encode(MyDynamoType(t.ID)),
    Name.Encode(MyDynamoType(t.Name)),
  )
}

func Codec

func Codec[T dynamo.Thing, A any](a string) CodecOf[T, A]

Build field codec for attribute

type Coder

type Coder func(map[string]types.AttributeValue) (map[string]types.AttributeValue, error)

Coder is a function, applies transformation of generic dynamodb AttributeValue

type Constraint

type Constraint[T any] struct {
	// contains filtered or unexported fields
}

Constraint is a function that applies conditional expression to storage request. Each storage implements own constrains protocols. The module here defines a few constrain protocol. The structure of the constrain is abstracted away from the client.

func (Constraint[T]) Constraint

func (Constraint[T]) Constraint(T)

type Constraints

type Constraints[T dynamo.Thing, A any] struct {
	// contains filtered or unexported fields
}

Internal implementation of Constrain effects for storage

func Schema

func Schema[T dynamo.Thing, A any](a string) Constraints[T, A]

Schema declares type descriptor to express Storage I/O Constrains.

Let's consider a following example:

type Person struct {
  curie.ID
  Name    string `dynamodbav:"anothername,omitempty"`
}

How to define a condition expression on the field Name? Golang struct defines and refers the field by `Name` but DynamoDB stores it under the attribute `anothername`. Struct field dynamodbav tag specifies serialization rules. Golang does not support a typesafe approach to build a correspondence between `Name` ⟷ `anothername`. Developers have to utilize dynamodb attribute name(s) in conditional expression and Golang struct name in rest of the code. It becomes confusing and hard to maintain.

The types Effect and Schema are helpers to declare builders for conditional expressions. Just declare a global variables next to type definition and use them across the application.

var name = dynamo.Schema[Person, string]("Name")

name.Eq("Joe Doe")
name.NotExists()

func (Constraints[T, A]) Eq

func (eff Constraints[T, A]) Eq(val A) Constraint[T]

Eq is equal constrain

name.Eq(x) ⟼ Field = :value

func (Constraints[T, A]) Exists

func (eff Constraints[T, A]) Exists() Constraint[T]

Exists attribute constrain

name.Exists(x) ⟼ attribute_exists(name)

func (Constraints[T, A]) Ge

func (eff Constraints[T, A]) Ge(val A) Constraint[T]

Ge is greater or equal constrain

name.Le(x) ⟼ Field >= :value

func (Constraints[T, A]) Gt

func (eff Constraints[T, A]) Gt(val A) Constraint[T]

Gt is greater than constrain

name.Le(x) ⟼ Field > :value

func (Constraints[T, A]) Is

func (eff Constraints[T, A]) Is(val string) Constraint[T]

Is matches either Eq or NotExists if value is not defined

func (Constraints[T, A]) Le

func (eff Constraints[T, A]) Le(val A) Constraint[T]

Le is less or equal constain

name.Le(x) ⟼ Field <= :value

func (Constraints[T, A]) Lt

func (eff Constraints[T, A]) Lt(val A) Constraint[T]

Lt is less than constraint

name.Lt(x) ⟼ Field < :value

func (Constraints[T, A]) Ne

func (eff Constraints[T, A]) Ne(val A) Constraint[T]

Ne is non equal constraint

name.Ne(x) ⟼ Field <> :value

func (Constraints[T, A]) NotExists

func (eff Constraints[T, A]) NotExists() Constraint[T]

NotExists attribute constrain

name.NotExists(x) ⟼ attribute_not_exists(name)

type DynamoDB

type DynamoDB interface {
	GetItem(context.Context, *dynamodb.GetItemInput, ...func(*dynamodb.Options)) (*dynamodb.GetItemOutput, error)
	PutItem(context.Context, *dynamodb.PutItemInput, ...func(*dynamodb.Options)) (*dynamodb.PutItemOutput, error)
	DeleteItem(context.Context, *dynamodb.DeleteItemInput, ...func(*dynamodb.Options)) (*dynamodb.DeleteItemOutput, error)
	UpdateItem(context.Context, *dynamodb.UpdateItemInput, ...func(*dynamodb.Options)) (*dynamodb.UpdateItemOutput, error)
	Query(context.Context, *dynamodb.QueryInput, ...func(*dynamodb.Options)) (*dynamodb.QueryOutput, error)
}

DynamoDB declares interface of original AWS DynamoDB API used by the library

type Storage

type Storage[T dynamo.Thing] struct {
	// contains filtered or unexported fields
}

Storage type

func Must

func Must[T dynamo.Thing](keyval *Storage[T], err error) *Storage[T]

func New

func New[T dynamo.Thing](connector string, opts ...dynamo.Option) (*Storage[T], error)

New creates instance of DynamoDB api

func (*Storage[T]) Get

func (db *Storage[T]) Get(ctx context.Context, key T) (T, error)

Get item from storage

func (*Storage[T]) Match

func (db *Storage[T]) Match(ctx context.Context, key T, opts ...interface{ MatchOpt() }) ([]T, error)

Match applies a pattern matching to elements in the table

func (*Storage[T]) Put

func (db *Storage[T]) Put(ctx context.Context, entity T, config ...interface{ Constraint(T) }) error

Put writes entity

func (*Storage[T]) Remove

func (db *Storage[T]) Remove(ctx context.Context, key T, config ...interface{ Constraint(T) }) (T, error)

Remove discards the entity from the table

func (*Storage[T]) Update

func (db *Storage[T]) Update(ctx context.Context, entity T, config ...interface{ Constraint(T) }) (T, error)

Update applies a partial patch to entity and returns new values