dynamo

README

dynamo

The library implements a simple key-value abstraction to store algebraic, linked-data data types at AWS storage services: AWS DynamoDB and AWS S3.

Inspiration

The library encourages developers to use Golang struct to define domain models, write correct, maintainable code. Using this library, the application can achieve the ideal data model that would require a single request to DynamoDB and model one-to-one, one-to-many and even many-to-many relations. The library uses generic programming style to implement actual storage I/O, while expose external domain object as [T dynamo.Thing] with implicit conversion back and forth between a concrete struct(s). The library uses AWS Golang SDK v2 under the hood.

Essentially, the library implement a following generic key-value trait to access domain objects.

type KeyVal[T dynamo.Thing] interface {
  Put(T) error
  Get(T) (T, error)
  Remove(T) error
  Update(T) (T, error)
  Match(T) Seq[T]
}

The library philosophy and use-cases are covered in depth at the post How To Model Any Relational Data in DynamoDB With dynamo library or continue reading the Getting started section.

Getting started

The library requires Go 1.18 or later due to usage of generics.

The latest version of the library is available at its main branch. All development, including new features and bug fixes, take place on the main branch using forking and pull requests as described in contribution guidelines. The stable version is available via Golang modules.

• Getting Started
  • Data types definition
  • DynamoDB IO
  • Error Handling
  • Hierarchical structures
  • Sequences and Pagination
  • Linked data
  • Type projections
  • Custom codecs for core domain types
  • Optimistic Locking
  • Configure DynamoDB
  • AWS S3 Support

Data types definition

Data types definition is an essential part of development with dynamo library. Golang structs declares domain of your application. Public fields are serialized into DynamoDB attributes, the field tag dynamodbav controls marshal/unmarshal processes.

The library demands from each structure implementation of Thing interface. This type acts as struct annotation -- Golang compiler raises an error at compile time if other data type is supplied to the dynamo library. Secondly, each structure defines unique "composite primary key". The library encourages definition of both partition and sort keys using a special data type curie.IRI. This type is a synonym to compact Internationalized Resource Identifiers, which facilitates linked-data, hierarchical structures and cheap relations between data items. curie.IRI is a synonym to the built-in string type so that anything castable to string suite to model the keys as alternative solution.

type Person struct {
  Org     curie.IRI `dynamodbav:"prefix,omitempty"`
  ID      curie.IRI `dynamodbav:"suffix,omitempty"`
  Name    string    `dynamodbav:"name,omitempty"`
  Age     int       `dynamodbav:"age,omitempty"`
  Address string    `dynamodbav:"address,omitempty"`
}

//
// Identity implements thing interface
func (p Person) HashKey() curie.IRI { return p.Org }
func (p Person) SortKey() curie.IRI { return p.ID }

//
// this data type is a normal Golang struct
// just create an instance, fill required fields
var person := Person{
  Org:     curie.IRI("University:Kiel"),
  ID:      curie.IRI("Professor:8980789222"),
  Name:    "Verner Pleishner",
  Age:     64,
  Address: "Blumenstrasse 14, Berne, 3013",
}

This is it! Your application is ready to read/write data to/form DynamoDB tables.

DynamoDB I/O

Please see and try examples. Its cover all basic use-cases with runnable code snippets, check the post How To Model Any Relational Data in DynamoDB With dynamo library for deep-dive into library philosophy.

go run examples/keyval/main.go ddb:///my-table

The following code snippet shows a typical I/O patterns

import (
  "github.com/fogfish/dynamo/v2/service/ddb"
)

//
// Create dynamodb client and bind it with the table.
// The client is type-safe and support I/O with a single type (e.g. Person).
// Use URI notation to specify the diver (ddb://) and the table (/my-table).
db := ddb.Must(ddb.New[Person]("ddb:///my-table"))

//
// Write the struct with Put
if err := db.Put(context.TODO(), person); err != nil {
}

//
// Lookup the struct using Get. This function takes input structure as key
// and return a new copy upon the completion. The only requirement - ID has to
// be defined.
val, err := db.Get(context.TODO(),
  Person{
    Org: curie.IRI("University:Kiel"),
    ID:  curie.IRI("Professor:8980789222"),
  },
)

switch {
case nil:
  // success
case recoverNotFound(err):
  // not found
default:
  // other i/o error
}

//
// Apply a partial update using Update function. This function takes 
// a partially defined structure, patches the instance at storage and 
// returns remaining attributes.
val, err := db.Update(context.TODO(),
  Person{
    Org:     curie.IRI("University:Kiel"),
    ID:      curie.IRI("Professor:8980789222"),
    Address: "Viktoriastrasse 37, Berne, 3013",
  }
)

if err != nil { /* ... */ }

//
// Remove the struct using Remove give partially defined struct with ID
err := db.Remove(context.TODO(),
  Person{
    Org: curie.IRI("University:Kiel"),
    ID:  curie.IRI("Professor:8980789222"),
  }
)

if err != nil { /* ... */ }

Error Handling

The library enforces for "assert errors for behavior, not type" as the error handling strategy, see the post for details.

Use following behaviors to recover from errors:

type ErrorCode interface{ ErrorCode() string }

type NotFound interface { NotFound() string }

type PreConditionFailed interface { PreConditionFailed() bool }

type Conflict interface { Conflict() bool }

type Gone interface { Gone() bool }

Hierarchical structures

The library support definition of A ⟼ B relation for data elements. Let's consider message threads as a classical examples for such hierarchies:

A
├ B
├ C
│ ├ D  
│ └ E
│   └ F
└ G

Composite sort key is core concept to organize hierarchies. It facilitates linked-data, hierarchical structures and cheap relations between data items. An application declares node path using composite sort key design pattern. For example, the root is thread:A, 2nd rank node ⟨thread:A, B⟩, 3rd rank node ⟨thread:A, C/D⟩ and so on ⟨thread:A, C/E/F⟩. Each id declares partition and sub nodes. The library implement a Match function, supply the node identity and it returns sequence of child elements.

//
// Match uses partition key to match DynamoDB entries. It returns a sequence of 
// data type instances. FMap is an utility it takes a closure function. 
db.Match(context.TODO(), Message{Thread: "thread:A"}).FMap(/* ... */)

//
// Match uses partition key and partial sort key to match DynamoDB entries. 
db.Match(context.TODO(), Message{Thread: "thread:A", ID: "C"}).FMap(/* ... */)


//
// Type aliases is the best approach to lift generic sequence in type safe one.
type Messages []Message

// Join is a monoid to append generic element into sequence 
func (seq *Messages) Join(val *Message) error {
  *seq = append(*seq, *val)
  return nil
}

// and final magic to discover hierarchy of elements
seq := Messages{}
db.Match(context.TODO(), Message{Thread: "thread:A", ID: "C/E"}).FMap(seq.Join)

See advanced example for details on managing linked-data.

Sequences and Pagination

Hierarchical structures is the way to organize collections, lists, sets, etc. The Match returns a lazy Sequence that represents your entire collection. Sometimes, your need to split the collection into sequence of pages.

// 1. Set the limit on the stream 
seq := db.Match(context.TODO(), Message{Thread: "thread:A", ID: "C"}).Limit(25)
// 2. Consume the stream
seq.FMap(persons.Join)
// 3. Read cursor value
cursor := seq.Cursor()


// 4. Continue I/O with a new stream, supply the cursor
seq := db.Match(context.TODO(), Message{Thread: "thread:A", ID: "C"}).
  Limit(25).
  Continue(cursor)

Linked data

Cross-linking of structured data is an essential part of type safe domain driven design. The library helps developers to model relations between data instances using familiar data type.

type Person struct {
  Org     curie.IRI  `dynamodbav:"prefix,omitempty"`
  ID      curie.IRI  `dynamodbav:"suffix,omitempty"`
  Leader  *curie.IRI `dynamodbav:"leader,omitempty"`
}

ID and Leader are sibling, equivalent data types. ID is only used as primary identity, Leader is a "pointer" to linked-data. The library advices usage of compact Internationalized Resource Identifiers (curie.IRI) for this purpose. Semantic Web publishes structured data using this type so that it can be interlinked by applications.

Type projections

Often, there is an established system of the types in the application. It is not convenient to inject dependencies to the dynamo library. Also, the usage of secondary indexes requires multiple projections of core type.

// 
// original core type
type Person struct {
  Org     string `dynamodbav:"prefix,omitempty"`
  ID      string `dynamodbav:"suffix,omitempty"`
  Name    string `dynamodbav:"name,omitempty"`
  Age     int    `dynamodbav:"age,omitempty"`
  Country string `dynamodbav:"country,omitempty"`
}

//
// the core type projection that uses ⟨Org, ID⟩ as composite key
// e.g. this projection supports writes to DynamoDB table
type dbPerson Person

func (p dbPerson) HashKey() curie.IRI { return curie.IRI(p.Org) }
func (p dbPerson) SortKey() curie.IRI { return curie.IRI(p.ID) }

//
// the core type projection that uses ⟨Org, Name⟩ as composite key
// e.g. the projection support lookup of employer
type dbNamedPerson Person

func (p dbNamedPerson) HashKey() curie.IRI { return curie.IRI(p.Org) }
func (p dbNamedPerson) SortKey() curie.IRI { return curie.IRI(p.Name) }

//
// the core type projection that uses ⟨Country, Name⟩ as composite key
type dbCitizen Person

func (p dbCitizen) HashKey() curie.IRI { return curie.IRI(p.Country) }
func (p dbCitizen) SortKey() curie.IRI { return curie.IRI(p.Name) }

Custom codecs for core domain types

Development of complex Golang application might lead developers towards Standard Package Layout. It becomes extremely difficult to isolate dependencies from core data types to this library and AWS SDK. The library support serialization of core type to dynamo using custom codecs

/*** core.go ***/

// 1. complex domain type is defined
type ID struct {/* ... */}

// 2. structure with core types is defined, no deps to dynamo library
type Person struct {
  Org      ID  `dynamodbav:"prefix,omitempty"`
  ID       ID  `dynamodbav:"suffix,omitempty"`
}

/*** aws/ddb/ddb.go ***/

import (
  "github.com/fogfish/dynamo/service/ddb"
)

// 3. declare codecs for complex core domain type 
type id core.ID

func (id) MarshalDynamoDBAttributeValue() (types.AttributeValue, error) {/* ...*/}
func (*id) UnmarshalDynamoDBAttributeValue(types.AttributeValue) error {/* ...*/}

// aws/ddb/ddb.go
// 2. type alias to core type implements dynamo custom codec
type dbPerson Person

// 3. custom codec for structure field is defined 
var codecHashKey, codecSortKey = ddb.Codec2[dbPerson, id, id]("Org", "ID")

// 4. use custom codec
func (p dbPerson) MarshalDynamoDBAttributeValue() (types.AttributeValue, error) {
  type tStruct dbPerson
  return ddb.Encode(av, tStruct(p),
    codecHashKey.Encode(id(p.Org)),
    codecSortKey.Encode(id(p.ID))),
  )
}

func (x *dbPerson) UnmarshalDynamoDBAttributeValue(av types.AttributeValue) error {
  type tStruct *dbPerson
  return ddb.Decode(av, tStruct(x),
    codecHashKey.Decode((*id)(&x.Org)),
    codecSortKey.Decode((*id)(&x.ID))),
  )
}

Optimistic Locking

Optimistic Locking is a lightweight approach to ensure causal ordering of read, write operations to database. AWS made a great post about Optimistic Locking with Version Number.

The dynamo library implements type safe conditional expressions to achieve optimistic locking. This feature is vital when your serverless application concurrently updates same entity in the database.

Let's consider a following example.

type Person struct {
  Org     string `dynamodbav:"prefix,omitempty"`
  ID      string `dynamodbav:"suffix,omitempty"`
  Name    string `dynamodbav:"anothername,omitempty"`
}

An optimistic locking on this structure is straightforward from DynamoDB perspective. Just make a request with conditional expression:

&dynamodb.UpdateItemInput{
  ConditionExpression: "anothername = :anothername",
  ExpressionAttributeValues: /* ":anothername" : {S: "Verner Pleishner"} */
}

However, the application operates with struct types. 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 library defines set of helper types and functions to declare and use conditional expression in type safe manner:

type Person struct {
  Org     string `dynamodbav:"prefix,omitempty"`
  ID      string `dynamodbav:"suffix,omitempty"`
  Name    string `dynamodbav:"anothername,omitempty"`
}
var Name = dynamo.Schema1[Person, string]("Name")

val, err := db.Update(context.TODO(), &person, Name.Eq("Verner Pleishner"))
switch err.(type) {
case nil:
  // success
case dynamo.PreConditionFailed:
  // not found
default:
  // other i/o error
}

See the go doc for all supported constraints.

Configure DynamoDB

The dynamo library is optimized to operate with generic Dynamo DB that declares both partition and sort keys with fixed names. Use the following schema:

const Schema = (): ddb.TableProps => ({
  tableName: 'my-table',
  partitionKey: {type: ddb.AttributeType.STRING, name: 'prefix'},
  sortKey: {type: ddb.AttributeType.STRING, name: 'suffix'},
})

If table uses other names for partitionKey and sortKey then connect URI allows to re-declare them

//
// Create client and bind it with DynamoDB the table
db := keyval.Must(
  keyval.New[Person]("ddb:///my-table?prefix=someHashKey&suffix=someSortKey", nil, nil),
)

The following post discusses in depth and shows example DynamoDB table configuration and covers aspect of secondary indexes.

AWS S3 Support

The library advances its simple I/O interface to AWS S3 bucket, allowing to persist data types to multiple storage simultaneously.

import (
  "github.com/fogfish/dynamo/v2/service/ddb"
  "github.com/fogfish/dynamo/v2/service/s3"
)


//
// Create client and bind it with DynamoDB the table
db := ddb.Must(ddb.New("ddb:///my-table", nil, nil))

//
// Create client and bind it with S3 bucket
db := s3.Must(s3.New("s3:///my-bucket", nil, nil))

There are few fundamental differences about AWS S3 bucket

• use s3 schema of connection URI;
• compose primary key is serialized to S3 bucket path. (e.g. ⟨thread:A, C/E/F⟩ ⟼ thread/A/_/C/E/F);
• storage persists struct to JSON, use json field tags to specify serialization rules;
• optimistic locking is not supported yet, any conditional expression is silently ignored;
• Update is not thread safe.

How To Contribute

The library is MIT licensed and accepts contributions via GitHub pull requests:

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

The build and testing process requires Go version 1.13 or later.

build and test library.

git clone https://github.com/fogfish/dynamo
cd dynamo
go test

commit message

The commit message helps us to write a good release note, speed-up review process. The message should address two question what changed and why. The project follows the template defined by chapter Contributing to a Project of Git book.

bugs

If you experience any issues with the library, please let us know via GitHub issues. We appreciate detailed and accurate reports that help us to identity and replicate the issue.

License

Documentation

Overview

Package dynamo implements a simple key-value abstraction to store algebraic data types with AWS services:

↣ AWS DynamoDB

↣ AWS S3

Inspiration

The library encourages developers to use Golang struct to define domain models, write correct, maintainable code. Using the library, the application can achieve the ideal data model that would require a single request to DynamoDB and model one-to-one, one-to-many and even many-to-many relations. The library uses generic programming style to implement actual storage I/O, while expose external domain object as `[T dynamo.Thing]` with implicit conversion back and forth between a concrete struct(s).

Essentially, it implement a following generic key-value trait to access domain objects. The library AWS Go SDK under the hood

type KeyVal[T any] interface {
  Put(T) error
  Get(T) (*T, error)
  Remove(T) error
  Update(T): (*T, error)
  Match(T): Seq[T]
}

Getting started

Define an application domain model using product types, which are strongly expressed by struct in Go.

type Person struct {
  Org     curie.IRI `dynamodbav:"prefix,omitempty"`
  ID      curie.IRI `dynamodbav:"suffix,omitempty"`
  Name    string    `dynamodbav:"name,omitempty"`
  Age     int       `dynamodbav:"age,omitempty"`
  Address string    `dynamodbav:"address,omitempty"`
}

Make sure that defined type implements dynamo.Thing interface for identity

func (p Person) HashKey() curie.IRI { return p.Org }
func (p Person) SortKey() curie.IRI { return p.ID }

Use DynamoDB attributes from AWS Go SDK to specify marshalling rules https://docs.aws.amazon.com/sdk-for-go/api/service/dynamodb/dynamodbattribute.

Create an implicit I/O endpoint to Dynamo DB table

db := keyval.New[Person](dynamo.WithURI("ddb:///my-table"))

Creates a new entity, or replaces an old entity with a new value.

err := db.Put(
  Person{
    Org:      curie.IRI("test"),
    ID:       curie.IRI("8980789222"),
    Name:     "Verner Pleishner",
    Age:      64,
    Address:  "Blumenstrasse 14, Berne, 3013",
  }
)

Lookup the struct using Get. This function takes input structure as key and return a new copy upon the completion. The only requirement - ID has to be defined.

val, err := db.Get(Person{Org: curie.IRI("test"), ID: curie.IRI("8980789222")})
switch err.(type) {
case nil:
  // success
case dynamo.NotFound:
  // not found
default:
  // other i/o error
}

Remove the entity

err := db.Remove(Person{Org: curie.IRI("test"), ID: curie.IRI("8980789222")})

Apply a partial update using Update function. This function takes a partially defined structure, patches the instance at storage and returns remaining attributes.

person := Person{
  Org:     "test",
  ID:      "8980789222"
  Address: "Viktoriastrasse 37, Berne, 3013",
}
val, err := db.Update(person)
if err != nil { ... }

Use following DynamoDB schema:

  const Schema = (): ddb.TableProps => ({
	   partitionKey: {type: ddb.AttributeType.STRING, name: 'prefix'},
	   sortKey: {type: ddb.AttributeType.STRING, name: 'suffix'},
	   tableName: 'my-table',
	   readCapacity: 1,
	   writeCapacity: 1,
  })

See README at https://github.com/fogfish/dynamo

Index

• func Schema10[T Thing, A, B, C, D, E, F, G, H, I, J any](a, b, c, d, e, f, g, h, i, j string) (TypeOf[T, A], TypeOf[T, B], TypeOf[T, C], TypeOf[T, D], TypeOf[T, E], ...)
• func Schema2[T Thing, A, B any](a, b string) (TypeOf[T, A], TypeOf[T, B])
• func Schema3[T Thing, A, B, C any](a, b, c string) (TypeOf[T, A], TypeOf[T, B], TypeOf[T, C])
• func Schema4[T Thing, A, B, C, D any](a, b, c, d string) (TypeOf[T, A], TypeOf[T, B], TypeOf[T, C], TypeOf[T, D])
• func Schema5[T Thing, A, B, C, D, E any](a, b, c, d, e string) (TypeOf[T, A], TypeOf[T, B], TypeOf[T, C], TypeOf[T, D], TypeOf[T, E])
• func Schema6[T Thing, A, B, C, D, E, F any](a, b, c, d, e, f string) (TypeOf[T, A], TypeOf[T, B], TypeOf[T, C], TypeOf[T, D], TypeOf[T, E], ...)
• func Schema7[T Thing, A, B, C, D, E, F, G any](a, b, c, d, e, f, g string) (TypeOf[T, A], TypeOf[T, B], TypeOf[T, C], TypeOf[T, D], TypeOf[T, E], ...)
• func Schema8[T Thing, A, B, C, D, E, F, G, H any](a, b, c, d, e, f, g, h string) (TypeOf[T, A], TypeOf[T, B], TypeOf[T, C], TypeOf[T, D], TypeOf[T, E], ...)
• func Schema9[T Thing, A, B, C, D, E, F, G, H, I any](a, b, c, d, e, f, g, h, i string) (TypeOf[T, A], TypeOf[T, B], TypeOf[T, C], TypeOf[T, D], TypeOf[T, E], ...)
• type Config
  • func NewConfig() Config
• type Constraint
• type DynamoDB
• type KeyVal
• type KeyValGetter
• type KeyValPattern
• type KeyValReader
• type KeyValWriter
• type Option
  • func WithPrefixes(prefixes curie.Prefixes) Option
  • func WithService(service any) Option
• type S3
• type Seq
• type SeqConfig
• type SeqLazy
• type Thing
• type Things
  • func (seq *Things[T]) Join(t T) error
• type TypeOf
  • func Schema1[T Thing, A any](a string) TypeOf[T, A]
• type URL
  • func (uri *URL) Query(key, def string) string
  • func (uri *URL) Segments() []string
  • func (uri *URL) String() string

Functions

func Schema10

func Schema10[T Thing, A, B, C, D, E, F, G, H, I, J any](a, b, c, d, e, f, g, h, i, j string) (
	TypeOf[T, A],
	TypeOf[T, B],
	TypeOf[T, C],
	TypeOf[T, D],
	TypeOf[T, E],
	TypeOf[T, F],
	TypeOf[T, G],
	TypeOf[T, H],
	TypeOf[T, I],
	TypeOf[T, J],
)

Schema10 builds Constrain builder for product type of arity 10

func Schema2

func Schema2[T Thing, A, B any](a, b string) (
	TypeOf[T, A],
	TypeOf[T, B],
)

Schema2 builds Constrain builder for product type of arity 2

func Schema3

func Schema3[T Thing, A, B, C any](a, b, c string) (
	TypeOf[T, A],
	TypeOf[T, B],
	TypeOf[T, C],
)

Schema3 builds Constrain builder for product type of arity 3

func Schema4

func Schema4[T Thing, A, B, C, D any](a, b, c, d string) (
	TypeOf[T, A],
	TypeOf[T, B],
	TypeOf[T, C],
	TypeOf[T, D],
)

Schema4 builds Constrain builder for product type of arity 4

func Schema5

func Schema5[T Thing, A, B, C, D, E any](a, b, c, d, e string) (
	TypeOf[T, A],
	TypeOf[T, B],
	TypeOf[T, C],
	TypeOf[T, D],
	TypeOf[T, E],
)

Schema5 builds Constrain builder for product type of arity 5

func Schema6

func Schema6[T Thing, A, B, C, D, E, F any](a, b, c, d, e, f string) (
	TypeOf[T, A],
	TypeOf[T, B],
	TypeOf[T, C],
	TypeOf[T, D],
	TypeOf[T, E],
	TypeOf[T, F],
)

Schema6 builds Constrain builder for product type of arity 6

func Schema7

func Schema7[T Thing, A, B, C, D, E, F, G any](a, b, c, d, e, f, g string) (
	TypeOf[T, A],
	TypeOf[T, B],
	TypeOf[T, C],
	TypeOf[T, D],
	TypeOf[T, E],
	TypeOf[T, F],
	TypeOf[T, G],
)

Schema7 builds Constrain builder for product type of arity 7

func Schema8

func Schema8[T Thing, A, B, C, D, E, F, G, H any](a, b, c, d, e, f, g, h string) (
	TypeOf[T, A],
	TypeOf[T, B],
	TypeOf[T, C],
	TypeOf[T, D],
	TypeOf[T, E],
	TypeOf[T, F],
	TypeOf[T, G],
	TypeOf[T, H],
)

Schema8 builds Constrain builder for product type of arity 8

func Schema9

func Schema9[T Thing, A, B, C, D, E, F, G, H, I any](a, b, c, d, e, f, g, h, i string) (
	TypeOf[T, A],
	TypeOf[T, B],
	TypeOf[T, C],
	TypeOf[T, D],
	TypeOf[T, E],
	TypeOf[T, F],
	TypeOf[T, G],
	TypeOf[T, H],
	TypeOf[T, I],
)

Schema9 builds Constrain builder for product type of arity 9

Types

type Config

type Config struct {
	Service  any
	Prefixes curie.Prefixes
}

Config options for the client

func NewConfig

func NewConfig() Config

type Constraint

type Constraint[T Thing] interface{ TypeOf(T) }

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.

See internal/constrain package to see details about its implementation

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 KeyVal

type KeyVal[T Thing] interface {
	KeyValReader[T]
	KeyValWriter[T]
}

KeyVal is a generic key-value trait to access domain objects.

type KeyValGetter

type KeyValGetter[T Thing] interface {
	Get(context.Context, T) (T, error)
}

KeyValGetter defines read by key notation

type KeyValPattern

type KeyValPattern[T Thing] interface {
	Match(context.Context, T) Seq[T]
}

KeyValPattern defines simple pattern matching lookup I/O

type KeyValReader

type KeyValReader[T Thing] interface {
	KeyValGetter[T]
	KeyValPattern[T]
}

KeyValReader a generic key-value trait to read domain objects

type KeyValWriter

type KeyValWriter[T Thing] interface {
	Put(context.Context, T, ...Constraint[T]) error
	Remove(context.Context, T, ...Constraint[T]) error
	Update(context.Context, T, ...Constraint[T]) (T, error)
}

KeyValWriter defines a generic key-value writer

type Option

type Option func(cfg *Config)

Option type to configure the connection

func WithPrefixes

func WithPrefixes(prefixes curie.Prefixes) Option

WithPrefixes defines prefixes for CURIEs

func WithService

func WithService(service any) Option

Configure AWS Service for the client

type S3

type S3 interface {
	GetObject(context.Context, *s3.GetObjectInput, ...func(*s3.Options)) (*s3.GetObjectOutput, error)
	PutObject(context.Context, *s3.PutObjectInput, ...func(*s3.Options)) (*s3.PutObjectOutput, error)
	DeleteObject(context.Context, *s3.DeleteObjectInput, ...func(*s3.Options)) (*s3.DeleteObjectOutput, error)
	ListObjectsV2(context.Context, *s3.ListObjectsV2Input, ...func(*s3.Options)) (*s3.ListObjectsV2Output, error)
}

S3 declares AWS API used by the library

type Seq

type Seq[T Thing] interface {
	SeqLazy[T]
	SeqConfig[T]

	// Sequence transformer
	FMap(func(T) error) error
}

Seq is an interface to transform collection of objects

db.Match(dynamo.NewID("users")).FMap(func(x *T) error { ... })

type SeqConfig

type SeqConfig[T Thing] interface {
	// Limit sequence size to N elements (pagination)
	Limit(int) Seq[T]
	// Continue limited sequence from the cursor
	Continue(Thing) Seq[T]
	// Reverse order of sequence
	Reverse() Seq[T]
}

SeqConfig configures optional sequence behavior

type SeqLazy

type SeqLazy[T Thing] interface {
	// Head lifts first element of sequence
	Head() (T, error)
	// Tail evaluates tail of sequence
	Tail() bool
	// Error returns error of stream evaluation
	Error() error
	// Cursor is the global position in the sequence
	Cursor() Thing
}

SeqLazy is an interface to iterate through collection of objects at storage

type Thing

type Thing interface {
	HashKey() curie.IRI
	SortKey() curie.IRI
}

Thing is the most generic item type used by the library to abstract writable/readable items into storage services.

The interfaces declares anything that have a unique identifier. The unique identity is exposed by pair of string: HashKey and SortKey.

type Things

type Things[T Thing] []T

Things is sequence of Thing

func (*Things[T]) Join

func (seq *Things[T]) Join(t T) error

Join lifts sequence of matched objects to seq of IDs

seq := dynamo.Things{}
dynamo.Match(...).FMap(seq.Join)

type TypeOf

type TypeOf[T Thing, A any] interface {
	Eq(A) Constraint[T]
	Ne(A) Constraint[T]
	Lt(A) Constraint[T]
	Le(A) Constraint[T]
	Gt(A) Constraint[T]
	Ge(A) Constraint[T]
	Is(string) Constraint[T]
	Exists() Constraint[T]
	NotExists() Constraint[T]
}

TypeOf 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 TypeOf and SchemaN 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.Schema1[Person, string]("Name")

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

func Schema1

func Schema1[T Thing, A any](a string) TypeOf[T, A]

Schema1 builds Constrain builder for product type of arity 1

type URL

type URL url.URL

URL custom type with helper functions

func (*URL) Query

func (uri *URL) Query(key, def string) string

query parameters

func (*URL) Segments

func (uri *URL) Segments() []string

path segments of length

func (*URL) String

func (uri *URL) String() string