dokvs

README

dokvs - Documents Over KV Stores

This project aims to provide document-store capabilities, built over key-value persisted backends. It is built in Go using the new generics features to expose a friendly, type-safe API.

This is mostly a personal exercise for getting used to the new generics features of Go. By means of applying them to a problem I am familiar with.

Requirements

1. Go at >=1.18beta1

Backends

• BoltDB
• Etcd

Inspirations

dokvs is heavily inspired by my day to day work @InfluxData.

However, it is also inspired by lots of projects in the world of Go. Including but not limited to:

• InfluxDBs KV Store Abstractions
• ETCD
• BoltDB
• Kubernetes client-go

Documentation

Index

• Variables
• func ApplyAll[T any](t *T, opts ...func(*T))
• func WithSerializer[D any, K AnyBytes](serializer Serializer[D]) func(*Collection[D, K])
• type AnyBytes
• type Collection
  • func NewCollection[D any, K AnyBytes](schema CollectionSchema[D], opts ...func(*Collection[D, K])) Collection[D, K]
  • func (c Collection[D, K]) Init(update kv.Update) error
  • func (c Collection[D, K]) Update(update kv.Update) (cu CollectionUpdate[D, K], err error)
  • func (c Collection[D, K]) View(view kv.View) (cv CollectionView[D, K], err error)
• type CollectionSchema
  • func NewSchema[D any](name string, primaryKeyFn func(D) []byte) CollectionSchema[D]
• type CollectionUpdate
  • func (c CollectionUpdate[D, K]) Delete(ctx context.Context, doc D) error
  • func (c CollectionUpdate[D, K]) Fetch(ctx context.Context, key K) (d D, err error)
  • func (c CollectionUpdate[D, K]) List(ctx context.Context, pred ListPredicate) ([]D, error)
  • func (c CollectionUpdate[D, K]) Put(ctx context.Context, doc D) error
• type CollectionView
  • func (c CollectionView[D, K]) Fetch(ctx context.Context, key K) (d D, err error)
  • func (c CollectionView[D, K]) List(ctx context.Context, pred ListPredicate) (ds []D, err error)
• type JSONSerializer
  • func (d JSONSerializer[T]) Deserialize(v []byte, t *T) error
  • func (s JSONSerializer[T]) Serialize(t T) ([]byte, error)
• type ListPredicate
• type Options
  • func (o Options[T]) Apply(t *T)
• type Schema
  • func (s Schema[D]) Collection() []byte
  • func (s Schema[D]) PrimaryKey(d D) []byte
• type Serializer

Examples

• Collection

Variables

var ErrNotFound = errors.New("document not found")

Functions

func ApplyAll

func ApplyAll[T any](t *T, opts ...func(*T))

func WithSerializer

func WithSerializer[D any, K AnyBytes](serializer Serializer[D]) func(*Collection[D, K])

Types

type AnyBytes

type AnyBytes interface {
	~[]byte | ~string
}

type Collection

type Collection[D any, K AnyBytes] struct {
	// contains filtered or unexported fields
}

Example

package main

import (
	"context"

	"github.com/georgemac/dokvs/pkg/kv"
)

type ID string

var (
	schema = NewSchema("recipes", func(r Recipe) []byte {
		return []byte(r.ID)
	})

	serializer Serializer[Recipe] = (JSONSerializer[Recipe]{})
)

type Recipe struct {
	ID ID
}

func main() {
	recipes := NewCollection[Recipe, ID](schema, WithSerializer[Recipe, ID](serializer))

	ctx := context.Background()

	var update kv.Update
	recipesUpdate, _ := recipes.Update(update)
	_ = recipesUpdate.Put(ctx, Recipe{ID: "my_recipe"})

	var view kv.View
	recipesView, _ := recipes.View(view)
	_, _ = recipesView.Fetch(ctx, ID("my_recipe"))
}

func NewCollection

func NewCollection[D any, K AnyBytes](schema CollectionSchema[D], opts ...func(*Collection[D, K])) Collection[D, K]

func (Collection[D, K]) Init

func (c Collection[D, K]) Init(update kv.Update) error

func (Collection[D, K]) Update

func (c Collection[D, K]) Update(update kv.Update) (cu CollectionUpdate[D, K], err error)

func (Collection[D, K]) View

func (c Collection[D, K]) View(view kv.View) (cv CollectionView[D, K], err error)

type CollectionSchema

type CollectionSchema[D any] interface {
	Collection() []byte
	PrimaryKey(D) []byte
}

func NewSchema

func NewSchema[D any](name string, primaryKeyFn func(D) []byte) CollectionSchema[D]

type CollectionUpdate

type CollectionUpdate[D any, K AnyBytes] struct {
	CollectionView[D, K]
	// contains filtered or unexported fields
}

func (CollectionUpdate[D, K]) Delete

func (c CollectionUpdate[D, K]) Delete(ctx context.Context, doc D) error

func (CollectionUpdate[D, K]) Fetch

func (c CollectionUpdate[D, K]) Fetch(ctx context.Context, key K) (d D, err error)

func (CollectionUpdate[D, K]) List

func (c CollectionUpdate[D, K]) List(ctx context.Context, pred ListPredicate) ([]D, error)

func (CollectionUpdate[D, K]) Put

func (c CollectionUpdate[D, K]) Put(ctx context.Context, doc D) error

type CollectionView

type CollectionView[D any, K AnyBytes] struct {
	Collection[D, K]
	// contains filtered or unexported fields
}

func (CollectionView[D, K]) Fetch

func (c CollectionView[D, K]) Fetch(ctx context.Context, key K) (d D, err error)

func (CollectionView[D, K]) List

func (c CollectionView[D, K]) List(ctx context.Context, pred ListPredicate) (ds []D, err error)

type JSONSerializer

type JSONSerializer[T any] struct{}

func (JSONSerializer[T]) Deserialize

func (d JSONSerializer[T]) Deserialize(v []byte, t *T) error

func (JSONSerializer[T]) Serialize

func (s JSONSerializer[T]) Serialize(t T) ([]byte, error)

type ListPredicate

type ListPredicate struct {
	Offset []byte
	Limit  int
}

type Options

type Options[T any] []func(*T)

func (Options[T]) Apply

func (o Options[T]) Apply(t *T)

type Schema

type Schema[D any] struct {
	// contains filtered or unexported fields
}

func (Schema[D]) Collection

func (s Schema[D]) Collection() []byte

func (Schema[D]) PrimaryKey

func (s Schema[D]) PrimaryKey(d D) []byte

type Serializer

type Serializer[T any] interface {
	Serialize(T) ([]byte, error)
	Deserialize([]byte, *T) error
}