boltron

package module
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Feb 14, 2024 License: BSD-3-Clause Imports: 11 Imported by: 0

README

BoltDB data containers

Go PkgGoDev NewReleases

Package boltron provides type safe generic constructs to design data models using BoltDB embedded key value store.

Definitions statically define encodings and options for other types to be serialized and they provide methods to access and modify serialized data within bolt transactions.

There are three basic types with their definitions:

  • Collection
  • Association
  • List

One complex types provides methods to manage sets of basic types:

  • Collections
  • Associations
  • Lists

Installation

Run go get -u resenje.org/boltron from command line.

Boltron uses Type Parameters (Generics) introduced in Go 1.18.

Collection

Collections is the most basic key value relation where key is an unique identifier. The whole collection can be iterated by the order of keys.

Define the Collection of Records:

type Record struct {
	Message string
}

var recordsDefinition = boltron.NewCollectionDefinition(
	"records",
	boltron.Uint64BinaryEncoding,       // records are identified by their integer values
	boltron.NewJSONEncoding[*Record](), // JSON encoding of the Record type,
	nil,
)

Use it in transaction:

db.Update(func(tx *bolt.Tx) error {
	records := recordsDefinition.Collection(tx)
	_, err := records.Save(42, &Record{
		Message: "Hello",
	}, false)
	return err
})

Association

Association represents a simple one-to-one relation. It is useful to associate identifiers and quickly lookup relations from either lef ot right side, as well to iterate over them and paginate.

List

List is a list of values, ordered by the provided order type. List values are unique, but the order by values are not. If the order is defined by the values encoding, or it is not important, order by encoding should be set to NullEncoding.

Collections

Collections is a set of Collections, each identified by an unique collection key. All collections have the same key and value encodings.

Collections provide methods to access individual Collection by its collection key, as well methods to get information about all keys and remove a key from all Collections.

Associations

Associations is a set of Associations, each identified by an unique key. All associations have the same left and right value encodings.

Associations provide methods to get individual Associations to manage relations by their Left values.

Lists

Lists is a set of Lists, each identified by an unique key. All lists have the same value and order by encodings.

Lists provide methods to get individual lists by their keys and to manage values from all of them.

License

This application is distributed under the BSD-style license found in the LICENSE file.

Documentation

Overview

Package boltron provides type safe generic constructs to design data models using BoltDB embedded key value store.

Definitions statically define encodings and options for other types to be serialized and they provide methods to access and modify serialized data within bolt transactions.

There are three basic types with their definitions: Collection, Association and List.

One complex types Collections, Associations and Lists provides methods to manage dynamically created collections and lists.

Index

Constants

View Source 
const TimeEncodingLen = 9

TimeEncodingLen is the length of byte slice time representation returned by EncodeTime.

Variables

View Source 
var (
	// ErrLeftNotFound is the default error if requested left value in Association does not
	// exist.
	ErrLeftNotFound = errors.New("boltron: left value not found")
	// ErrRightNotFound is the default error if requested right value in Association does not
	// exist.
	ErrRightNotFound = errors.New("boltron: right value not found")
	// ErrLeftExists is the default error if the left value already exists in
	// the Association.
	ErrLeftExists = errors.New("boltron: left value exists")
	// ErrRightExists is the default error if the right value already exists in
	// the Association.
	ErrRightExists = errors.New("boltron: right value exists")
)
View Source 
var (
	// StringEncoding encodes string by a simple type conversion to byte slice.
	StringEncoding = NewEncoding(
		func(v string) ([]byte, error) {
			return []byte(v), nil
		},
		func(b []byte) (string, error) {
			return string(b), nil
		},
	)

	// StringNaturalOrderEncoding encodes string to be case insensitive and
	// numerically sorted. It takes more than a double space to store the value
	// as it keeps it in the original form in bas64 encoding alongside the
	// encoded form.
	StringNaturalOrderEncoding = NewEncoding(
		func(v string) ([]byte, error) {
			return encodeNatural(v), nil
		},
		func(b []byte) (string, error) {
			return decodeNatural(b)
		},
	)

	// Uint64BinaryEncoding encodes uint64 number as big endian 8 byte array. It
	// is suitable to be used as OrderBy encoding in lists.
	Uint64BinaryEncoding = NewEncoding(
		func(v uint64) ([]byte, error) {
			b := make([]byte, 8)
			binary.BigEndian.PutUint64(b, v)
			return b, nil
		},
		func(b []byte) (uint64, error) {
			if l := len(b); l != 8 {
				return 0, fmt.Errorf("invalid encoded value length %v", l)
			}
			return binary.BigEndian.Uint64(b), nil
		},
	)

	// IntBase10Encoding encodes integer using strconv.Itoa and strconv.Atoi
	// functions.
	IntBase10Encoding = NewEncoding(
		func(i int) ([]byte, error) {
			return []byte(strconv.Itoa(i)), nil
		},
		func(b []byte) (int, error) {
			return strconv.Atoi(string(b))
		},
	)

	// Int64Base36Encoding encodes int64 using strconv.FormatInt with 36 base
	// string representation.
	Int64Base36Encoding = NewEncoding(
		func(i int64) ([]byte, error) {
			return []byte(strconv.FormatInt(i, 36)), nil
		},
		func(b []byte) (int64, error) {
			return strconv.ParseInt(string(b), 36, 64)
		},
	)

	// Uint64Base36Encoding encodes uint64 using strconv.FormatInt with 36 base
	// string representation.
	Uint64Base36Encoding = NewEncoding(
		func(i uint64) ([]byte, error) {
			return []byte(strconv.FormatUint(i, 36)), nil
		},
		func(b []byte) (uint64, error) {
			return strconv.ParseUint(string(b), 36, 64)
		},
	)

	// TimeEncoding encodes time using EncodeTime and DecodeTime functions. It
	// is suitable to be used as OrderBy encoding in lists.
	TimeEncoding = NewEncoding(
		func(v time.Time) ([]byte, error) {
			return EncodeTime(v), nil
		},
		func(b []byte) (time.Time, error) {
			return DecodeTime(b)
		},
	)

	// NullEncoding always produces a nil byte slice and nul Null value. It is
	// suitable to be used as OrderBy encoding in lists if order is determined
	// by list's values encoding.
	NullEncoding = NewEncoding(
		func(*struct{}) ([]byte, error) {
			return nil, nil
		},
		func([]byte) (*struct{}, error) {
			return nil, nil
		},
	)
)
View Source 
var (
	// ErrNotFound is the default error if requested key or value does not
	// exist.
	ErrNotFound = errors.New("boltron: not found")
	// ErrKeyExists is the default error if the key already exists.
	ErrKeyExists = errors.New("boltron: key exists")
	// ErrKeyExists is the default error if the value already exists.
	ErrValueExists = errors.New("boltron: value exists")
	// ErrInvalidPageNumber is returned on on pagination methods where page
	// number is less than 1.
	ErrInvalidPageNumber = errors.New("boltron: invalid page number")
)

Functions

func DecodeTime 

func DecodeTime(b []byte) (t time.Time, err error)

DecodeTime converts slice of bytes as described in encodeTime to time.Time.

func EncodeTime 

func EncodeTime(t time.Time) (b []byte)

EncodeTime returns slice of bytes that represent provided time in UTC. Slice length is always 9, where first 2 bytes represent the year and the rest 7 bytes nanoseconds since the beginning the year. This representation is compact, can represent year range from -math.MaxInt16 to math.MaxInt16 and is sortable. Even it is not related to Bolt, it can be used to sort keys by timestamp in a compact representation.

func MarshalTime 

func MarshalTime(b []byte, t time.Time)

MarshalTime puts bytes representation if provided time to provide slice. The slice must have length of 9 bytes.

Types

type Association 

type Association[L, R any] struct {
	// contains filtered or unexported fields
}

Association provides methods to access and change relations.

func (*Association[L, R]) DeleteByLeft 

func (a *Association[L, R]) DeleteByLeft(left L, ensure bool) error

DeleteByLeft removes the relation that contains the provided left value. If ensure flag is set to true and the value does not exist, configured ErrNotFound is returned.

func (*Association[L, R]) DeleteByRight 

func (a *Association[L, R]) DeleteByRight(right R, ensure bool) error

DeleteByRight removes the relation that contains the provided right value. If ensure flag is set to true and the value does not exist, ErrNotFound is returned.

func (*Association[L, R]) HasLeft 

func (a *Association[L, R]) HasLeft(left L) (bool, error)

HasLeft returns true if the left already exists in the database.

func (*Association[L, R]) HasRight 

func (a *Association[L, R]) HasRight(right R) (bool, error)

HasRight returns true if the right value already exists in the database.

func (*Association[L, R]) Iterate 

func (a *Association[L, R]) Iterate(start *L, reverse bool, f func(L, R) (bool, error)) (next *L, err error)

Iterate iterates over associations in the lexicographical order of left values. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Association[L, R]) IterateLeftValues 

func (a *Association[L, R]) IterateLeftValues(start *L, reverse bool, f func(L) (bool, error)) (next *L, err error)

IterateLeftValues iterates over left values in the lexicographical order of left values. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Association[L, R]) IterateRightValues 

func (a *Association[L, R]) IterateRightValues(start *R, reverse bool, f func(R) (bool, error)) (next *R, err error)

IterateRightValues iterates over right values in the lexicographical order of right values. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Association[L, R]) Left 

func (a *Association[L, R]) Left(right R) (left L, err error)

Left returns left value associated with the given right value. If value does not exist, ErrNotFound is returned.

func (*Association[L, R]) Page 

func (a *Association[L, R]) Page(number, limit int, reverse bool) (s []AssociationElement[L, R], totalElements, pages int, err error)

Page returns at most a limit of elements of associations at the provided page number.

func (*Association[L, R]) PageOfLeftValues 

func (a *Association[L, R]) PageOfLeftValues(number, limit int, reverse bool) (s []L, totalElements, pages int, err error)

PageOfLeftValues returns at most a limit of left values at the provided page number.

func (*Association[L, R]) PageOfRightValues 

func (a *Association[L, R]) PageOfRightValues(number, limit int, reverse bool) (s []R, totalElements, pages int, err error)

PageOfRightValues returns at most a limit of right values at the provided page number.

func (*Association[L, R]) Right 

func (a *Association[L, R]) Right(left L) (right R, err error)

Right returns right value associated with the given left value. If value does not exist, ErrNotFound is returned.

func (*Association[L, R]) Set 

func (a *Association[L, R]) Set(left L, right R) error

Set saves the relation between the left and right values. If left value already exists, configured ErrLeftExists is returned, if right value exists, configured ErrValueExists is returned.

func (*Association[L, R]) Size added in v0.1.2 

func (a *Association[L, R]) Size() (int, error)

Size returns the number of associations.

type AssociationDefinition 

type AssociationDefinition[L, R any] struct {
	// contains filtered or unexported fields
}

AssociationDefinition defines one-to-one relation between values named left and right. The relation is unique.

func NewAssociationDefinition 

func NewAssociationDefinition[L, R any](
	name string,
	leftEncoding Encoding[L],
	rightEncoding Encoding[R],
	o *AssociationOptions,
) *AssociationDefinition[L, R]

NewAssociationDefinition constructs a new AssociationDefinition with a unique name and left and right values encodings.

func (*AssociationDefinition[L, R]) Association 

func (d *AssociationDefinition[L, R]) Association(tx *bolt.Tx) *Association[L, R]

Association returns an Association that has access to the stored data through the bolt transaction.

type AssociationElement 

type AssociationElement[L, R any] struct {
	Left  L
	Right R
}

AssociationElement is the type returned by pagination methods as slice elements that contain both key and value.

type AssociationOptions 

type AssociationOptions struct {
	// ErrLeftNotFound is returned if the left value is not found.
	ErrLeftNotFound error
	// ErrRightNotFound is returned if the right value is not found.
	ErrRightNotFound error
	// ErrLeftExists is returned if the left value in relation already exists.
	ErrLeftExists error
	// ErrRightExists is returned if the right value in relation already exists.
	ErrRightExists error
}

AssociationOptions provides additional configuration for an Association.

type Associations 

type Associations[A, L, R any] struct {
	// contains filtered or unexported fields
}

Associations provides methods to access and change a set of Associations.

func (*Associations[A, L, R]) Association 

func (a *Associations[A, L, R]) Association(key A) (association *Association[L, R], exists bool, err error)

Association returns an Association instance that is associated with the provided association key. If the returned value of exists is false, the association still does not exist but it will be created if a value is added to it.

func (*Associations[A, L, R]) DeleteAssociation 

func (a *Associations[A, L, R]) DeleteAssociation(key A, ensure bool) error

DeleteAssociation removes the association from the database. If ensure flag is set to true and the key does not exist, configured ErrAssociationNotFound is returned.

func (*Associations[A, L, R]) DeleteLeft 

func (a *Associations[A, L, R]) DeleteLeft(left L, ensure bool) error

DeleteLeft removes the left value from all associations that contain it. If ensure flag is set to true and the left value does not exist, configured ErrNotFound is returned.

func (*Associations[A, L, R]) HasAssociation 

func (a *Associations[A, L, R]) HasAssociation(key A) (bool, error)

HasAssociation returns true if the Association associated with the association key already exists in the database.

func (*Associations[A, L, R]) HasLeft 

func (a *Associations[A, L, R]) HasLeft(left L) (bool, error)

HasLeft returns true if the left value already exists in any Association.

func (*Associations[A, L, R]) IterateAssociations 

func (a *Associations[A, L, R]) IterateAssociations(start *A, reverse bool, f func(A) (bool, error)) (next *A, err error)

IterateAssociations iterates over Association keys in the lexicographical order of keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Associations[A, L, R]) IterateAssociationsWithLeftValue 

func (a *Associations[A, L, R]) IterateAssociationsWithLeftValue(left L, start *A, reverse bool, f func(A) (bool, error)) (next *A, err error)

IterateAssociationsWithLeftValue iterates over Association keys that contain the provided left value in the lexicographical order of keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Associations[A, L, R]) IterateLeftValues 

func (a *Associations[A, L, R]) IterateLeftValues(start *L, reverse bool, f func(L) (bool, error)) (next *L, err error)

IterateLeftValues iterates over all left values in the lexicographical order of left values. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Associations[A, L, R]) PageOfAssociations 

func (a *Associations[A, L, R]) PageOfAssociations(number, limit int, reverse bool) (s []A, totalElements, pages int, err error)

PageOfAssociations returns at most a limit of Association keys at the provided page number.

func (*Associations[A, L, R]) PageOfAssociationsWithLeftValue 

func (a *Associations[A, L, R]) PageOfAssociationsWithLeftValue(left L, number, limit int, reverse bool) (s []A, totalElements, pages int, err error)

PageOfAssociationsWithLeftValue returns at most a limit of Association keys that contain the provided left value at the provided page number.

func (*Associations[A, L, R]) PageOfLeftValues 

func (a *Associations[A, L, R]) PageOfLeftValues(number, limit int, reverse bool) (s []L, totalElements, pages int, err error)

PageOfLeftValues returns at most a limit of left values at the provided page number.

func (*Associations[A, L, R]) Size added in v0.1.2 

func (a *Associations[A, L, R]) Size() (int, error)

Size returns the number of associations.

type AssociationsDefinition 

type AssociationsDefinition[A, L, R any] struct {
	// contains filtered or unexported fields
}

AssociationsDefinition defines a set of Associations, each identified by an unique key. All associations have the same left and right value encodings.

func NewAssociationsDefinition 

func NewAssociationsDefinition[A, L, R any](
	name string,
	associationKeyEncoding Encoding[A],
	leftEncoding Encoding[L],
	rightEncoding Encoding[R],
	o *AssociationsOptions,
) *AssociationsDefinition[A, L, R]

NewAssociationsDefinition constructs a new AssociationsDefinition with a unique name and association key, left and right value encodings.

func (*AssociationsDefinition[A, L, R]) Associations 

func (d *AssociationsDefinition[A, L, R]) Associations(tx *bolt.Tx) *Associations[A, L, R]

Associations returns an Associations instance that has access to the stored data through the bolt transaction.

type AssociationsOptions 

type AssociationsOptions struct {
	// UniqueLeftValues marks if left value can be added only to a single
	// association.
	UniqueLeftValues bool
	// ErrAssociationNotFound is returned if the association identified by the
	// key is not found.
	ErrAssociationNotFound error
	// ErrLeftNotFound is returned if left value is not found in the same
	// Association.
	ErrLeftNotFound error
	// ErrRightNotFound is returned if right value is not found in the same
	// Association.
	ErrRightNotFound error
	// ErrLeftExists is returned if UniqueValues option is set to true and the
	// left value already exists in another association. Also if the left value
	// exists in the same association.
	ErrLeftExists error
	// ErrRightExists is returned if the right value in relation already exists.
	ErrRightExists error
}

AssociationsOptions provides additional configuration for an Association instance.

type Collection 

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

Collection provides methods to access and change key/value pairs.

func (*Collection[K, V]) Delete 

func (c *Collection[K, V]) Delete(key K, ensure bool) error

Delete removes the key and its associated value from the database. If ensure flag is set to true and the key does not exist, configured ErrNotFound is returned.

func (*Collection[K, V]) Get 

func (c *Collection[K, V]) Get(key K) (value V, err error)

Get returns a value associated with the given key. If key does not exist, ErrNotFound is returned.

func (*Collection[K, V]) Has 

func (c *Collection[K, V]) Has(key K) (bool, error)

Has returns true if the key already exists in the database.

func (*Collection[K, V]) Iterate 

func (c *Collection[K, V]) Iterate(start *K, reverse bool, f func(K, V) (bool, error)) (next *K, err error)

Iterate iterates over keys and values in the lexicographical order of keys.

func (*Collection[K, V]) IterateKeys 

func (c *Collection[K, V]) IterateKeys(start *K, reverse bool, f func(K) (bool, error)) (next *K, err error)

IterateKeys iterates over keys in the lexicographical order of keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Collection[K, V]) IterateValues 

func (c *Collection[K, V]) IterateValues(start *K, reverse bool, f func(V) (bool, error)) (next *K, err error)

IterateValues iterates over values in the lexicographical order of keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Collection[K, V]) Page 

func (c *Collection[K, V]) Page(number, limit int, reverse bool) (s []CollectionElement[K, V], totalElements, pages int, err error)

Page returns at most a limit of elements of key/value pairs at the provided page number.

func (*Collection[K, V]) PageOfKeys 

func (c *Collection[K, V]) PageOfKeys(number, limit int, reverse bool) (s []K, totalElements, pages int, err error)

PageOfKeys returns at most a limit of keys at the provided page number.

func (*Collection[K, V]) PageOfValues 

func (c *Collection[K, V]) PageOfValues(number, limit int, reverse bool) (s []V, totalElements, pages int, err error)

PageOfValues returns at most a limit of values at the provided page number.

func (*Collection[K, V]) Save 

func (c *Collection[K, V]) Save(key K, value V, overwrite bool) (overwritten bool, err error)

Save saves the key/value pair. If the overwrite flag is set to false and key already exists, configured ErrKeyExists is returned.

func (*Collection[K, V]) Size added in v0.1.2 

func (c *Collection[K, V]) Size() (int, error)

Size returns the number of collection elements.

type CollectionDefinition 

type CollectionDefinition[K, V any] struct {
	// contains filtered or unexported fields
}

CollectionDefinition defines the most basic data model which is a Collection of keys and values. Each key is a unique within a Collection.

func NewCollectionDefinition 

func NewCollectionDefinition[K, V any](
	name string,
	keyEncoding Encoding[K],
	valueEncoding Encoding[V],
	o *CollectionOptions,
) *CollectionDefinition[K, V]

NewCollectionDefinition constructs a new CollectionDefinition with a unique name and key and value encodings.

func (*CollectionDefinition[K, V]) Collection 

func (d *CollectionDefinition[K, V]) Collection(tx *bolt.Tx) *Collection[K, V]

Collection returns a Collection that has access to the stored data through the bolt transaction.

type CollectionElement 

type CollectionElement[K, V any] struct {
	Key   K
	Value V
}

CollectionElement is the type returned by pagination methods as slice elements that contain both key and value.

type CollectionOptions 

type CollectionOptions struct {
	// FillPercent is the value for the bolt bucket fill percent.
	FillPercent float64
	// ErrNotFound is returned if the key is not found.
	ErrNotFound error
	// ErrKeyExists is returned if the key already exists and its value is not
	// allowed to be overwritten.
	ErrKeyExists error
}

CollectionOptions provides additional configuration for a Collection.

type Collections 

type Collections[C, K, V any] struct {
	// contains filtered or unexported fields
}

Collections provides methods to access and change a set of Collections.

func (*Collections[C, K, V]) Collection 

func (c *Collections[C, K, V]) Collection(key C) (collection *Collection[K, V], exists bool, err error)

Collections returns a Collections instance that is associated with the provided collection key. If the returned value of exists is false, the collection still does not exist but it will be created if a key/value pair is saved to it.

func (*Collections[C, K, V]) DeleteCollection 

func (c *Collections[C, K, V]) DeleteCollection(key C, ensure bool) error

DeleteCollection removes the collection from the database. If ensure flag is set to true and the value does not exist, configured ErrCollectionNotFound is returned.

func (*Collections[C, K, V]) DeleteKey 

func (c *Collections[C, K, V]) DeleteKey(key K, ensure bool) error

DeleteKey removes the key from all collections that contain it. If ensure flag is set to true and the key does not exist, configured ErrKeyNotFound is returned.

func (*Collections[C, K, V]) HasCollection 

func (c *Collections[C, K, V]) HasCollection(key C) (bool, error)

HasCollection returns true if the Collection associated with the collection key already exists in the database.

func (*Collections[C, K, V]) HasKey 

func (c *Collections[C, K, V]) HasKey(key K) (bool, error)

HasKey returns true if the key already exists in any Collection.

func (*Collections[C, K, V]) IterateCollections 

func (c *Collections[C, K, V]) IterateCollections(start *C, reverse bool, f func(C) (bool, error)) (next *C, err error)

IterateCollections iterates over collection keys in the lexicographical order of keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Collections[C, K, V]) IterateCollectionsWithKey 

func (c *Collections[C, K, V]) IterateCollectionsWithKey(key K, start *C, reverse bool, f func(C) (bool, error)) (next *C, err error)

IterateCollectionsWithKey iterates over collection keys that contain the provided key in the lexicographical order of collection keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Collections[C, K, V]) IterateKeys 

func (c *Collections[C, K, V]) IterateKeys(start *K, reverse bool, f func(K) (bool, error)) (next *K, err error)

IterateKeys iterates over all keys in the lexicographical order of keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Collections[C, K, V]) PageOfCollections 

func (c *Collections[C, K, V]) PageOfCollections(number, limit int, reverse bool) (s []C, totalElements, pages int, err error)

PageOfCollections returns at most a limit of collection keys at the provided page number.

func (*Collections[C, K, V]) PageOfCollectionsWithKey 

func (c *Collections[C, K, V]) PageOfCollectionsWithKey(key K, number, limit int, reverse bool) (s []C, totalElements, pages int, err error)

PageOfCollectionsWithKey returns at most a limit of collection keys that contain the provided key at the provided page number.

func (*Collections[C, K, V]) PageOfKeys 

func (c *Collections[C, K, V]) PageOfKeys(number, limit int, reverse bool) (s []K, totalElements, pages int, err error)

PageOfKeys returns at most a limit of keys at the provided page number.

func (*Collections[C, K, V]) Size added in v0.1.2 

func (c *Collections[C, K, V]) Size() (int, error)

Size returns the number of collections.

type CollectionsDefinition 

type CollectionsDefinition[C, K, V any] struct {
	// contains filtered or unexported fields
}

CollectionsDefinition defines a set of Collections, each identified by an unique collection key. All collections have the same key and value encodings.

func NewCollectionsDefinition 

func NewCollectionsDefinition[C, K, V any](
	name string,
	collectionKeyEncoding Encoding[C],
	keyEncoding Encoding[K],
	valueEncoding Encoding[V],
	o *CollectionsOptions,
) *CollectionsDefinition[C, K, V]

NewCollectionsDefinition constructs a new CollectionsDefinition with a unique name and collection key, key and value encodings.

func (*CollectionsDefinition[C, K, V]) Collections 

func (d *CollectionsDefinition[C, K, V]) Collections(tx *bolt.Tx) *Collections[C, K, V]

Collections returns a Collections instance that has access to the stored data through the bolt transaction.

type CollectionsOptions 

type CollectionsOptions struct {
	// FillPercent is the value for the bolt bucket fill percent for every
	// collection.
	FillPercent float64
	// UniqueKeys marks if a key can be added only to a single collection.
	UniqueKeys bool
	// ErrCollectionNotFound is returned if the collection identified by its key
	// is not found.
	ErrCollectionNotFound error
	// ErrKeyNotFound is returned if the key is not found.
	ErrKeyNotFound error
	// ErrKeyExists is returned if UniqueValues option is set to true and the
	// key already exists in another collection.
	ErrKeyExists error
}

CollectionsOptions provides additional configuration for a Collections instance.

type Encoding 

type Encoding[T any] interface {
	Encode(T) ([]byte, error)
	Decode([]byte) (T, error)
}

Encoding defines serialization of any type to and from bytes representation.

func NewEncoding 

func NewEncoding[T any](
	encode func(T) ([]byte, error),
	decode func([]byte) (T, error),
) Encoding[T]

NewEncoding returns Encoding from two functions that define it.

func NewJSONEncoding 

func NewJSONEncoding[T any]() Encoding[T]

NewJSONEncoding uses JSON to encode any JSON-serializable type.

func NewProxiedJSONEncoding 

func NewProxiedJSONEncoding[T, P any](
	proxyFunc func(T) P,
	typeFunc func(P) T,
) Encoding[T]

NewProxiedJSONEncoding JSON encodes a type by serializing it to a proxy type. This encoding provies flexibility to adjust json struct tags or type T fields by converting it to and from a proxy type P.

type EncodingFunc 

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

EncodingFunc is a helper type to construct Encoding from two existing functions.

func (*EncodingFunc[T]) Decode 

func (e *EncodingFunc[T]) Decode(b []byte) (T, error)

Decode deserializes a slice of bytes into an instance of a specific type.

func (*EncodingFunc[T]) Encode 

func (e *EncodingFunc[T]) Encode(t T) ([]byte, error)

Encode serializes an instance of certain type to its bytes representation.

type List 

type List[V, O any] struct {
	// contains filtered or unexported fields
}

List provides methods to access and change ordered list of values.

func (*List[V, O]) Add 

func (l *List[V, O]) Add(value V, orderBy O) error

Add adds a value to the list with an order by instance.

func (*List[V, O]) Has 

func (o *List[V, O]) Has(value V) (bool, error)

Has returns true if the value already exists in the database.

func (*List[V, O]) Iterate 

func (l *List[V, O]) Iterate(start *ListElement[V, O], reverse bool, f func(V, O) (bool, error)) (next *ListElement[V, O], err error)

Iterate iterates over keys and values in the lexicographical order of keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*List[V, O]) IterateValues 

func (l *List[V, O]) IterateValues(start *ListElement[V, O], reverse bool, f func(V) (bool, error)) (next *ListElement[V, O], err error)

IterateValues iterates over values in the lexicographical order of order by. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*List[V, O]) OrderBy 

func (l *List[V, O]) OrderBy(value V) (orderBy O, err error)

OrderBy returns the saved order by instance for the provided value.

func (*List[V, O]) Page 

func (l *List[V, O]) Page(number, limit int, reverse bool) (s []ListElement[V, O], totalElements, pages int, err error)

Page returns at most a limit of elements of values and order by instances at the provided page number.

func (*List[V, O]) PageOfValues 

func (l *List[V, O]) PageOfValues(number, limit int, reverse bool) (s []V, totalElements, pages int, err error)

PageOfValues returns at most a limit of elements of values at the provided page number.

func (*List[V, O]) Remove 

func (l *List[V, O]) Remove(value V, ensure bool) error

Remove removes the value and its associated order by from the database. If ensure flag is set to true and the value does not exist, ErrNotFound is returned.

func (*List[V, O]) Size added in v0.1.2 

func (l *List[V, O]) Size() (int, error)

Size returns the number of list elements.

type ListDefinition 

type ListDefinition[V, O any] struct {
	// contains filtered or unexported fields
}

ListDefinition defines a list of values, ordered by the provided order type. List values are unique, but the order by values are not. If the order is defined by the values encoding, or it is not important, order by encoding should be set to NullEncoding.

func NewListDefinition 

func NewListDefinition[V, O any](
	name string,
	valueEncoding Encoding[V],
	orderByEncoding Encoding[O],
	o *ListOptions,
) *ListDefinition[V, O]

NewListDefinition constructs a new ListDefinition with a unique name and key and order by encodings.

func (*ListDefinition[V, O]) List 

func (d *ListDefinition[V, O]) List(tx *bolt.Tx) *List[V, O]

List returns a List that has access to the stored data through the bolt transaction.

type ListElement 

type ListElement[V, O any] struct {
	Value   V
	OrderBy O
}

ListElement is the type returned by List pagination methods as slice elements that contain both value and order by.

type ListOptions 

type ListOptions struct {
	// ErrValueNotFound is returned if the value is not found.
	ErrValueNotFound error
}

ListOptions provides additional configuration for a List.

type Lists 

type Lists[K, V, O any] struct {
	// contains filtered or unexported fields
}

Lists provides methods to access and change a set of Lists.

func (*Lists[K, V, O]) DeleteList 

func (l *Lists[K, V, O]) DeleteList(key K, ensure bool) error

DeleteList removes the list from the database. If ensure flag is set to true and the value does not exist, configured ErrListNotFound is returned.

func (*Lists[K, V, O]) DeleteValue 

func (l *Lists[K, V, O]) DeleteValue(value V, ensure bool) error

DeleteValue removes the value from all lists that contain it. If ensure flag is set to true and the value does not exist, configured ErrValueNotFound is returned.

func (*Lists[K, V, O]) HasList 

func (l *Lists[K, V, O]) HasList(key K) (bool, error)

HasList returns true if the List associated with the key already exists in the database.

func (*Lists[K, V, O]) HasValue 

func (l *Lists[K, V, O]) HasValue(value V) (bool, error)

HasValue returns true if the value already exists in any List.

func (*Lists[K, V, O]) IterateLists 

func (l *Lists[K, V, O]) IterateLists(start *K, reverse bool, f func(K) (bool, error)) (next *K, err error)

IterateLists iterates over List keys in the lexicographical order of keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Lists[K, V, O]) IterateListsWithValue 

func (l *Lists[K, V, O]) IterateListsWithValue(value V, start *K, reverse bool, f func(K, O) (bool, error)) (next *K, err error)

IterateListsWithValue iterates over List keys that contain the provided value in the lexicographical order of keys. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Lists[K, V, O]) IterateValues 

func (l *Lists[K, V, O]) IterateValues(start *V, reverse bool, f func(V) (bool, error)) (next *V, err error)

IterateValues iterates over all values in the lexicographical order of values. If the callback function f returns false, the iteration stops and the next can be used to continue the iteration.

func (*Lists[K, V, O]) List 

func (l *Lists[K, V, O]) List(key K) (list *List[V, O], exists bool, err error)

List returns a List instance that is associated with the provided key. If the returned value of exists is false, the list still does not exist but it will be created if a value is added to it.

func (*Lists[K, V, O]) PageOfLists 

func (l *Lists[K, V, O]) PageOfLists(number, limit int, reverse bool) (s []K, totalElements, pages int, err error)

PageOfLists returns at most a limit of List keys at the provided page number.

func (*Lists[K, V, O]) PageOfListsWithValue 

func (l *Lists[K, V, O]) PageOfListsWithValue(value V, number, limit int, reverse bool) (s []ListsElement[K, O], totalElements, pages int, err error)

PageOfListsWithValue returns at most a limit of List keys and associate order by values that contain the provided value at the provided page number.

func (*Lists[K, V, O]) PageOfValues 

func (l *Lists[K, V, O]) PageOfValues(number, limit int, reverse bool) (s []V, totalElements, pages int, err error)

PageOfValues returns at most a limit of values at the provided page number.

func (*Lists[K, V, O]) Size added in v0.1.2 

func (l *Lists[K, V, O]) Size() (int, error)

Size returns the number of lists.

type ListsDefinition 

type ListsDefinition[K, V, O any] struct {
	// contains filtered or unexported fields
}

ListsDefinition defines a set of Lists, each identified by an unique key. All lists have the same value and order by encodings.

func NewListsDefinition 

func NewListsDefinition[K, V, O any](
	name string,
	keyEncoding Encoding[K],
	valueEncoding Encoding[V],
	orderByEncoding Encoding[O],
	o *ListsOptions,
) *ListsDefinition[K, V, O]

NewListsDefinition constructs a new ListsDefinition with a unique name and key, value and order by encodings.

func (*ListsDefinition[K, V, O]) Lists 

func (d *ListsDefinition[K, V, O]) Lists(tx *bolt.Tx) *Lists[K, V, O]

Lists returns a Lists instance that has access to the stored data through the bolt transaction.

type ListsElement 

type ListsElement[K, O any] struct {
	Key     K
	OrderBy O
}

ListsElement is the type returned by Lists pagination methods as slice elements that contain both list key and the order by value of the value in that list.

type ListsOptions 

type ListsOptions struct {
	// UniqueValues marks if a value can be added only to a single list.
	UniqueValues bool
	// ErrListNotFound is returned if the list identified by the key is not
	// found.
	ErrListNotFound error
	// ErrValueNotFound is returned if the value is not found.
	ErrValueNotFound error
	// ErrValueExists is returned if UniqueValues option is set to true and the
	// value already exists in another list.
	ErrValueExists error
}

ListsOptions provides additional configuration for a Lists instance.

Source Files

View all Source files

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.