leafdb

README

LeafDB is an embedded database for Golang that uses LMDB underneath but allows for seamless encoding and decoding of entities of various sorts and on-the-fly creation of arbitrary indexes.

Documentation

Index

• Variables
• type DB
  • func New[V Type](path string, options Options[V]) (*DB[V], error)
  • func (db *DB[V]) AddOrReplace(indexName string, t DataType, newValue V) (id uint32, err error)
  • func (db *DB[V]) Close() error
  • func (db *DB[V]) Create(t DataType, value ...V) (lastId uint32, err error)
  • func (db *DB[V]) Delete(id uint32) (err error)
  • func (db *DB[V]) DeleteQuery(params QueryParams) (ids []QueryResult[V], err error)
  • func (db *DB[V]) Get(id uint32) (t DataType, value V, err error)
  • func (db *DB[V]) ListAllKeys() iter.Seq[[]byte]
  • func (db *DB[V]) Query(params QueryParams) iter.Seq[V]
  • func (db *DB[V]) QueryComplete(params QueryParams) iter.Seq2[DataType, QueryResult[V]]
  • func (db *DB[V]) Update(id uint32, modify func(t DataType, newValue V) (V, error)) (err error)
  • func (db *DB[V]) UpdateQuery(params QueryParams, modify func(t DataType, newValue V) (V, error)) (err error)
  • func (db *DB[V]) Upsert(indexName string, indexKey []byte, t DataType, ...) (id uint32, err error)
  • func (db *DB[V]) View(params QueryParams) iter.Seq[V]
  • func (db *DB[V]) ViewWithKeys(params QueryParams) iter.Seq2[[]byte, V]
• type DataType
• type IndexDefinition
• type Options
• type QueryParams
  • func AnyQuery(index string) QueryParams
  • func ExactQuery(index string, indexKey []byte) QueryParams
  • func PrefixQuery(index string, prefix []byte) QueryParams
• type QueryResult
• type Type
• type ViewDefinition

Variables

var ErrNotFound = fmt.Errorf("not found")

Types

type DB

type DB[V Type] struct {
	Logger *log.Logger

	Options[V]
	// contains filtered or unexported fields
}

func New

func New[V Type](path string, options Options[V]) (*DB[V], error)

func (*DB[V]) AddOrReplace

func (db *DB[V]) AddOrReplace(indexName string, t DataType, newValue V) (id uint32, err error)

func (*DB[V]) Close

func (db *DB[V]) Close() error

func (*DB[V]) Create

func (db *DB[V]) Create(t DataType, value ...V) (lastId uint32, err error)

func (*DB[V]) Delete

func (db *DB[V]) Delete(id uint32) (err error)

Delete deletes a record by absolute id.

func (*DB[V]) DeleteQuery

func (db *DB[V]) DeleteQuery(params QueryParams) (ids []QueryResult[V], err error)

DeleteQuery deletes everything that matches the query in a single transaction.

func (*DB[V]) Get

func (db *DB[V]) Get(id uint32) (t DataType, value V, err error)

func (*DB[V]) ListAllKeys

func (db *DB[V]) ListAllKeys() iter.Seq[[]byte]

ListAllKeys exists mostly for debugging purposes.

func (*DB[V]) Query

func (db *DB[V]) Query(params QueryParams) iter.Seq[V]

func (*DB[V]) QueryComplete

func (db *DB[V]) QueryComplete(params QueryParams) iter.Seq2[DataType, QueryResult[V]]

func (*DB[V]) Update

func (db *DB[V]) Update(id uint32, modify func(t DataType, newValue V) (V, error)) (err error)

func (*DB[V]) UpdateQuery

func (db *DB[V]) UpdateQuery(params QueryParams, modify func(t DataType, newValue V) (V, error)) (err error)

func (*DB[V]) Upsert

func (db *DB[V]) Upsert(
	indexName string,
	indexKey []byte,
	t DataType,
	modifyOrInsert func(t DataType, value V) (V, error),
) (id uint32, err error)

func (*DB[V]) View

func (db *DB[V]) View(params QueryParams) iter.Seq[V]

func (*DB[V]) ViewWithKeys

func (db *DB[V]) ViewWithKeys(params QueryParams) iter.Seq2[[]byte, V]

type DataType

type DataType uint8 // this is a user-defined type identifier that will be stored to facilitate decoding

type IndexDefinition

type IndexDefinition[V any] struct {
	// Version should start at 1, increase by 1 on every modification
	Version int

	// The DataTypes this index will be applied to, if nil it will apply to all
	Types []DataType

	// Function that emits keys to build the index
	Emit func(t DataType, value V, emit func([]byte)) `json:"-"`

	// When this index is not used anymore
	Deleted bool
	// contains filtered or unexported fields
}

type Options

type Options[V Type] struct {
	Indexes map[string]IndexDefinition[V]
	Views   map[string]ViewDefinition[V]
	Encode  func(t DataType, value V) ([]byte, error)
	Decode  func(t DataType, data []byte) (V, error)
}

type QueryParams

type QueryParams struct {
	Index    string
	StartKey []byte
	EndKey   []byte
	Skip     int
	Limit    int
}

func AnyQuery

func AnyQuery(index string) QueryParams

func ExactQuery

func ExactQuery(index string, indexKey []byte) QueryParams

func PrefixQuery

func PrefixQuery(index string, prefix []byte) QueryParams

type QueryResult

type QueryResult[V any] struct {
	DataType DataType
	ID       uint32
	Value    V
	Error    error
}

type Type

type Type any // the type this database will encode/decode to

type ViewDefinition

type ViewDefinition[V any] struct {
	// Version should start at 1, increase by 1 on every modification
	Version int

	// The DataTypes this index will be applied to, if nil it will apply to all
	Types []DataType

	// Function that emits keys and values to build the view
	Emit func(t DataType, value V, emit func(idxkey []byte, t DataType, value V)) `json:"-"`

	// When this index is not used anymore
	Deleted bool
	// contains filtered or unexported fields
}