typeddb

Documentation

Index

• func MustGet(s Snapshot, id any, ptr any)
• func SetMany(txn Transaction, objs ...any)
• func TransactMany(db *TypedDB, objs ...any)
• type Change
• type EID
  • func (eid EID) String() string
• type Iterator
• type Kind
  • func KindOf(example any, indexDefs ...indices.Definition) *Kind
• type Snapshot
• type Transaction
• type TransactionControl
  • func (tc TransactionControl) Annotations() map[string]string
  • func (tc TransactionControl) Cancel()
  • func (tc TransactionControl) Changes() map[EID]Change
  • func (tc TransactionControl) Commit()
  • func (tc TransactionControl) GetBeforeByEID(eid EID) any
  • func (tc TransactionControl) GetByEID(eid EID) any
  • func (tc TransactionControl) Prune(eid EID)
  • func (tc TransactionControl) Reset()
  • func (tc TransactionControl) SetByEID(eid EID, obj any)
• type TypedDB
  • func New(kinds []*Kind) *TypedDB
  • func (tdb *TypedDB) EIDOf(obj any) EID
  • func (tdb *TypedDB) Snapshot() Snapshot
  • func (tdb *TypedDB) Transaction() (Transaction, TransactionControl)
  • func (tdb *TypedDB) TransactionBackdated(ts time.Time) (Transaction, TransactionControl)

Functions

func MustGet

func MustGet(s Snapshot, id any, ptr any)

MustGet returns an object from the database like Snapshot.Get, panic()ing if the object is not found

func SetMany

func SetMany(txn Transaction, objs ...any)

SetMany is a convenience function that puts all passed objects into the transaction. If a parameter is a slice, every slice element is separately put into the transaction.

func TransactMany

func TransactMany(db *TypedDB, objs ...any)

TransactMany is a convenience function that creates a transaction, puts all passed objects into it like SetMany and commits it.

Types

type Change

type Change struct {
	Before any
	After  any
}

Change is a single change done in a transaction

type EID

type EID struct {
	Kind *Kind
	ID   string
}

EID is an entity ID

func (EID) String

func (eid EID) String() string

type Iterator

type Iterator = func(ptr any) bool

Iterator is an iterator over the results of a query. Every call fills in another object into ptr argument. Returns false when the end of dataset is reached (data at ptr won't be modified in this call).

Iterators accept nil instead of a pointer. When the argument is nil, an iterator discards one item. The calling code can use this to skip sequence items.

Do not use a signle iterator concurrently.

type Kind

type Kind struct {
	meta.Struct
	Indices map[string]indices.Definition
	// contains filtered or unexported fields
}

Kind describes a particular type of objects handled by the framework. All fields are read-only.

func KindOf

func KindOf(example any, indexDefs ...indices.Definition) *Kind

KindOf creates a Kind for a given object example and index definitions. See package documentation for lib/limestone/indices.

type Snapshot

type Snapshot interface {
	// Time returns the time when the snapshot was taken.
	Time() time.Time
	// Get copies a value of an object of a kind determined by a type of ptr
	// with a specified id. Returns false if the entity does not exist.
	//
	// id should be a string or a type based on string.
	Get(id any, ptr any) bool
	// All returns an iterator over all the entities of a specific kind.
	All(kind *Kind) Iterator
	// Search returns an iterator over all entities using an index.
	Search(kind *Kind, index indices.Definition, args ...any) Iterator
}

Snapshot is a read-only view of the local database at point in time it was created. Safe for concurrent use.

type Transaction

type Transaction interface {
	Snapshot
	// Set sets the value of the entity in the database using obj type and ID field for addressing.
	// It's safe and cheap to call it without making any changes to the entity.
	Set(obj any)
	// Before returns a state of database at the time of the transaction start
	Before() Snapshot
	// Snapshot returns a read-only snapshot that includes any uncommitted changes made so far.
	// This snapshot will survive the transaction and is safe to use concurrently.
	// The snapshot inherits the transaction's timestamp.
	Snapshot() Snapshot
	// Annotate leaves an audit trail, attaching a key-value pair to the
	// transaction. The meaning of particular keys and values is
	// application-defined. The pairs are stored unordered. A later annotation
	// with the same key panics unless the value is also the same.
	Annotate(key, value string)
}

Transaction is a read-write view of the database. Do not use concurrently.

type TransactionControl

type TransactionControl struct {
	// contains filtered or unexported fields
}

TransactionControl is an extended manager for transaction, available only from the transaction constructor.

func (TransactionControl) Annotations

func (tc TransactionControl) Annotations() map[string]string

Annotations returns the map of annotations added to the transaction. Don't change it. Adding more annotations to the transaction affects the map returned by Annotations.

func (TransactionControl) Cancel

func (tc TransactionControl) Cancel()

Cancel cancels the corresponding transaction. Safe to use on a transaction that has already been committed or canceled. Do not use the transaction after it's been canceled.

func (TransactionControl) Changes

func (tc TransactionControl) Changes() map[EID]Change

Changes returns a list of changes accumulated in transaction

func (TransactionControl) Commit

func (tc TransactionControl) Commit()

Commit commits the corresponding transaction. Do not use the transaction after it's been committed.

func (TransactionControl) GetBeforeByEID

func (tc TransactionControl) GetBeforeByEID(eid EID) any

GetBeforeByEID returns the pre-transaction state of an element from the database using eid to lookup. Returns nil if object is not found.

func (TransactionControl) GetByEID

func (tc TransactionControl) GetByEID(eid EID) any

GetByEID returns an element from the database using eid to lookup. Returns nil if object is not found.

func (TransactionControl) Prune

func (tc TransactionControl) Prune(eid EID)

Prune removes an element from the in-memory DB

func (TransactionControl) Reset

func (tc TransactionControl) Reset()

Reset makes it look as if the transaction was opened just now: 1. Clears a list of changes that already happened in the transaction. 2. Sets the time that will be returned by `txn.Time()` to the current time.

func (TransactionControl) SetByEID

func (tc TransactionControl) SetByEID(eid EID, obj any)

SetByEID sets the value of the entity in the database using eid for addressing

type TypedDB

type TypedDB struct {
	// contains filtered or unexported fields
}

TypedDB is a typed wrapper around MemDB

func New

func New(kinds []*Kind) *TypedDB

New creates a new typed wrapper over MemDB

func (*TypedDB) EIDOf

func (tdb *TypedDB) EIDOf(obj any) EID

EIDOf returns the EID for an entity structure given by value or pointer. The entity need not be present in the database.

func (*TypedDB) Snapshot

func (tdb *TypedDB) Snapshot() Snapshot

Snapshot returns a new r/o snapshot of the database.

func (*TypedDB) Transaction

func (tdb *TypedDB) Transaction() (Transaction, TransactionControl)

Transaction returns a writable transaction over the DB, along with the control interface

func (*TypedDB) TransactionBackdated

func (tdb *TypedDB) TransactionBackdated(ts time.Time) (Transaction, TransactionControl)

TransactionBackdated is a version of Transaction that allows the caller to override the transaction timestamp that's made visible as `txn.Time()`.

Useful for history-analyzing applications.