behold

package module
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Apr 5, 2025 License: MIT Imports: 5 Imported by: 0

README

behold

Go Reference Go Report Card

behold is a generic key-value store with versioning and transactional capabilities. It's designed to offer a flexible interface for managing data with type safety using Go's generics.

Overview

The behold package provides:

  • Generic key-value storage with strong type safety
  • Transaction support for both read-only and read-write operations
  • Built-in versioning of data
  • Comprehensive matching capabilities
  • Flexible synchronization mechanisms

Installation

go get github.com/amery/behold

Key Features

Type-Safe Generic Store

The package uses Go generics to provide a type-safe key-value store interface that works with any comparable key type and any value type.

Transactional Operations

behold offers both read-only (View) and read-write (Update) transactions, with optional mutex locking for concurrent access control.

Matching System

A powerful matching system allows filtering data with logical operations:

  • Combine predicates with AND and OR operations
  • Match values against complex conditions
  • Create custom matching functions for specific filtering needs
Comparison Utilities

Built-in comparison functions that work with both standard comparable types and custom types with user-defined comparison logic.

API Reference

Core Interfaces
Store
type Store[K comparable, V any] interface {
    Version() uint64
    Now() time.Time
    View(ctx context.Context, fn func(Tx[K, V]) error, locks ...Mutex) error
    Update(ctx context.Context, fn func(Tx[K, V]) error, locks ...Mutex) error
    Close() error
}

The main interface for the key-value store that handles transactions and versioning.

Transaction
type Tx[K comparable, V any] interface {
    Context() context.Context
    Version() uint64
    Now() time.Time
    ForEach(fn func(key K, value V) bool, ors ...Matcher[any]) error
    Get(key K) (value V, err error)
    Set(key K, value V) error
    Append(key K, value V) error
    Delete(key K) error
    Commit() error
    Close() error
}

Interface for operations within a transaction context.

Matcher
type Matcher[T any] interface {
    And(...Matcher[T]) Matcher[T]
    Or(...Matcher[T]) Matcher[T]
    Match(T) bool
}

Generic interface for filtering data with logical operations.

Synchronization

behold provides flexible synchronization mechanisms:

type Mutex interface {
    Lock()
    TryLock() bool
    Unlock()
}

type RWMutex interface {
    Mutex
    RLock()
    RUnlock()
    TryRLock() bool
}

Standard Go mutex types (sync.Mutex and sync.RWMutex) implement these interfaces.

Usage Example

package main

import (
    "context"
    "fmt"
    "log"
    
    "github.com/amery/behold"
    // Assuming an implementation exists:
    "github.com/amery/behold/implementation"
)

func main() {
    // Create a new store with string keys and int values
    store := implementation.NewStore[string, int]()
    defer store.Close()
    
    // Write data in a transaction
    err := store.Update(context.Background(), func(tx behold.Tx[string, int]) error {
        if err := tx.Set("one", 1); err != nil {
            return err
        }
        if err := tx.Set("two", 2); err != nil {
            return err
        }
        if err := tx.Set("three", 3); err != nil {
            return err
        }

        return tx.Commit()
    })
    
    if err != nil {
        log.Fatalf("Failed to update: %v", err)
    }
    
    // Read data in a read-only transaction
    err = store.View(context.Background(), func(tx behold.Tx[string, int]) error {
        // Print all key-value pairs where value > 1
        return tx.ForEach(func(key string, value int) bool {
            fmt.Printf("%s: %d\n", key, value)
            return true // continue iteration
        }, behold.MatchGt(1))
    })
    
    if err != nil {
        log.Fatalf("Failed to view: %v", err)
    }
}

See others

License

This project is licensed under the MIT License.

Documentation

Overview

Package behold provides a generic key-value store with versioning and transactional capabilities. It's designed to offer a flexible interface for managing data with type safety using Go's generics.

Index

Constants

This section is empty.

Variables

View Source 
var ErrClosed = errors.New("closed")

ErrClosed is an error indicating that an object or resource is closed and cannot be used

View Source 
var ErrInvalid = core.ErrInvalid

ErrInvalid is an error indicating an invalid state or argument

View Source 
var ErrNilReceiver = core.ErrNilReceiver

ErrNilReceiver is an error indicating a nil receiver was passed to a method

View Source 
var ErrReadOnlyTx = errors.New("read-only transaction")

ErrReadOnlyTx is an error indicating an attempt to modify a read-only transaction

Functions

func Eq 

func Eq[T comparable](a, b T) bool

Eq returns true if a is equal to b for comparable types.

func EqFn 

func EqFn[T any](a, b T, cmp CompFunc[T]) bool

EqFn returns true if a is equal to b using a custom comparison function. It panics if the provided comparison function is nil.

func EqFn2 added in v0.0.2 

func EqFn2[T any](a, b T, eq CondFunc[T]) bool

EqFn2 returns true if a is equal to b using a custom equality function. It panics if the provided equality function is nil.

func Gt 

func Gt[T core.Ordered](a, b T) bool

Gt returns true if a is greater than b for ordered types.

func GtEq 

func GtEq[T core.Ordered](a, b T) bool

GtEq returns true if a is greater than or equal to b for ordered types.

func GtEqFn 

func GtEqFn[T any](a, b T, cmp CompFunc[T]) bool

GtEqFn returns true if a is greater than or equal to b using a custom comparison function. It panics if the provided comparison function is nil.

func GtEqFn2 added in v0.0.2 

func GtEqFn2[T any](a, b T, less CondFunc[T]) bool

GtEqFn2 returns true if a is greater than or equal to b using a custom less-than condition function. It panics if the provided less-than condition function is nil.

func GtFn 

func GtFn[T any](a, b T, cmp CompFunc[T]) bool

GtFn returns true if a is greater than b using a custom comparison function. It panics if the provided comparison function is nil.

func Lt 

func Lt[T core.Ordered](a, b T) bool

Lt returns true if a is less than b for ordered types.

func LtEq 

func LtEq[T core.Ordered](a, b T) bool

LtEq returns true if a is less than or equal to b for ordered types.

func LtEqFn 

func LtEqFn[T any](a, b T, cmp CompFunc[T]) bool

LtEqFn returns true if a is less than or equal to b using a custom comparison function. It panics if the provided comparison function is nil.

func LtEqFn2 added in v0.0.3 

func LtEqFn2[T any](a, b T, less CondFunc[T]) bool

LtEqFn2 returns true if a is less than or equal to b using a custom less-than condition function. It panics if the provided less-than condition function is nil.

func LtFn 

func LtFn[T any](a, b T, cmp CompFunc[T]) bool

LtFn returns true if a is less than b using a custom comparison function. It panics if the provided comparison function is nil.

func LtFn2 added in v0.0.2 

func LtFn2[T any](a, b T, less CondFunc[T]) bool

LtFn2 returns true if a is less than b using a custom less-than condition function. It panics if the provided less-than condition function is nil.

func NotEq 

func NotEq[T comparable](a, b T) bool

NotEq returns true if a is not equal to b for comparable types.

func NotEqFn 

func NotEqFn[T any](a, b T, cmp CompFunc[T]) bool

NotEqFn returns true if a is not equal to b using a custom comparison function. It panics if the provided comparison function is nil.

func NotEqFn2 added in v0.0.2 

func NotEqFn2[T any](a, b T, eq CondFunc[T]) bool

NotEqFn2 returns true if a is not equal to b using a custom equality function. It panics if the provided equality function is nil.

Types

type CompFunc 

type CompFunc[T any] func(a, b T) int

CompFunc is a generic comparison function that takes two values of type T and returns an integer. The return value follows the standard comparison convention: - Negative value if a < b - Zero if a == b - Positive value if a > b

func Reverse 

func Reverse[T any](cmp CompFunc[T]) CompFunc[T]

Reverse returns a new CompFunc that inverts the comparison result of the given CompFunc. It returns a function that negates the original comparison, effectively reversing the order. It panics if the provided comparison function is nil.

type CondFunc added in v0.0.2 

type CondFunc[T any] func(a, b T) bool

CondFunc is a generic condition function that takes two values of type T and returns a boolean. The return value indicates whether the condition is true or false for the given pair of values.

func AsEqual added in v0.0.2 

func AsEqual[T any](cmp CompFunc[T]) CondFunc[T]

AsEqual converts a CompFunc into an equality condition function. It returns a function that returns true if the first argument is equal to the second argument. It panics if the provided comparison function is nil.

func AsLess 

func AsLess[T any](cmp CompFunc[T]) CondFunc[T]

AsLess converts a CompFunc into a less-than condition function. It returns a function that returns true if the first argument is less than the second argument. It panics if the provided comparison function is nil.

type MatchFunc added in v0.0.3 

type MatchFunc[T any] func(T) bool

MatchFunc is a function type that implements the Matcher interface. It allows simple functions to be used as matchers.

func (MatchFunc[T]) And added in v0.0.3 

func (fn MatchFunc[T]) And(others ...Matcher[T]) Matcher[T]

And combines this query function with others using logical AND.

func (MatchFunc[T]) Match added in v0.0.3 

func (fn MatchFunc[T]) Match(value T) bool

Match calls the query function with the provided value. If the function is nil, it returns true (matches everything).

func (MatchFunc[T]) Or added in v0.0.3 

func (fn MatchFunc[T]) Or(others ...Matcher[T]) Matcher[T]

Or combines this query function with others using logical OR.

type Matcher added in v0.0.3 

type Matcher[T any] interface {
	// And combines this query with others using logical AND.
	// All conditions must match for the combined query to match.
	And(...Matcher[T]) Matcher[T]

	// Or combines this query with others using logical OR.
	// At least one condition must match for the combined query to match.
	Or(...Matcher[T]) Matcher[T]

	// Match tests if the given value satisfies this query's conditions.
	Match(T) bool
}

Matcher is a generic interface for filtering and combining predicates of type T. It allows logical AND and OR operations between conditions, and matching against a value.

func ComposeMatch added in v0.0.3 

func ComposeMatch[T any, V any](fn func(T) (V, bool), match Matcher[V]) Matcher[T]

ComposeMatch creates a new Matcher by applying an accessor function to transform input values before matching against an existing matcher. It allows composing matchers on different types by first extracting a specific field or transforming the input. Panics if the accessor function or the base query is nil.

func MatchAll 

func MatchAll[T any](queries ...Matcher[T]) Matcher[T]

MatchAll returns a query that matches if all of the provided queries match. If no queries are provided, the result will match everything (return true). Nil queries in the provided list are ignored during matching.

func MatchAny 

func MatchAny[T any](queries ...Matcher[T]) Matcher[T]

MatchAny returns a query that matches if any of the provided queries match. If no queries are provided, the result will match nothing (return false). Nil queries in the provided list are ignored during matching.

func MatchEq added in v0.0.3 

func MatchEq[T comparable](v T) Matcher[T]

MatchEq creates a Matcher that checks for equality with the given value. It returns a function that returns true if the input is equal to the specified value.

func MatchEqFn added in v0.0.3 

func MatchEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]

MatchEqFn creates a Matcher that checks for equality using a custom comparison function. It returns a function that returns true if the input is equal to the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchEqFn2 added in v0.0.3 

func MatchEqFn2[T any](v T, eq CondFunc[T]) Matcher[T]

MatchEqFn2 creates a Matcher that checks for equality using a custom equality function. It returns a function that returns true if the input is equal to the specified value according to the provided equality function. Panics if the equality function is nil.

func MatchGt added in v0.0.3 

func MatchGt[T core.Ordered](v T) Matcher[T]

MatchGt creates a Matcher that checks if a value is strictly greater than the given value. It returns a function that returns true if the input is greater than the specified value.

func MatchGtEq added in v0.0.3 

func MatchGtEq[T core.Ordered](v T) Matcher[T]

MatchGtEq creates a Matcher that checks if a value is greater than or equal to the given value. It returns a function that returns true if the input is greater than or equal to the specified value.

func MatchGtEqFn added in v0.0.3 

func MatchGtEqFn[T core.Ordered](v T, cmp CompFunc[T]) Matcher[T]

MatchGtEqFn creates a Matcher that checks if a value is greater than or equal to the given value using a custom comparison function. It returns a function that returns true if the input is greater than or equal to the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchGtEqFn2 added in v0.0.3 

func MatchGtEqFn2[T core.Ordered](v T, less CondFunc[T]) Matcher[T]

MatchGtEqFn2 creates a Matcher that checks if a value is greater than or equal to the given value using a custom condition function. It returns a function that returns true if the input is greater than or equal to the specified value according to the provided condition function. Panics if the condition function is nil.

func MatchGtFn added in v0.0.3 

func MatchGtFn[T core.Ordered](v T, cmp CompFunc[T]) Matcher[T]

MatchGtFn creates a Matcher that checks if a value is strictly greater than the given value using a custom comparison function. It returns a function that returns true if the input is greater than the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchLt added in v0.0.3 

func MatchLt[T core.Ordered](v T) Matcher[T]

MatchLt creates a Matcher that checks if a value is strictly less than the given value. It returns a function that returns true if the input is less than the specified value.

func MatchLtEq added in v0.0.3 

func MatchLtEq[T core.Ordered](v T) Matcher[T]

MatchLtEq creates a Matcher that checks if a value is less than or equal to the given value. It returns a function that returns true if the input is less than or equal to the specified value.

func MatchLtEqFn added in v0.0.3 

func MatchLtEqFn[T core.Ordered](v T, cmp CompFunc[T]) Matcher[T]

MatchLtEqFn creates a Matcher that checks if a value is less than or equal to the given value using a custom comparison function. It returns a function that returns true if the input is less than or equal to the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchLtEqFn2 added in v0.0.3 

func MatchLtEqFn2[T any](v T, less CondFunc[T]) Matcher[T]

MatchLtEqFn2 creates a Matcher that checks if a value is less than or equal to the given value using a custom condition function. It returns a function that returns true if the input is less than or equal to the specified value according to the provided condition function. Panics if the condition function is nil.

func MatchLtFn added in v0.0.3 

func MatchLtFn[T core.Ordered](v T, cmp CompFunc[T]) Matcher[T]

MatchLtFn creates a Matcher that checks if a value is strictly less than the given value using a custom comparison function. It returns a function that returns true if the input is less than the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchLtFn2 added in v0.0.3 

func MatchLtFn2[T core.Ordered](v T, less CondFunc[T]) Matcher[T]

MatchLtFn2 creates a Matcher that checks if a value is strictly less than the given value using a custom condition function. It returns a function that returns true if the input is less than the specified value according to the provided condition function. Panics if the condition function is nil.

func MatchNotEq added in v0.0.3 

func MatchNotEq[T comparable](v T) Matcher[T]

MatchNotEq creates a Matcher that checks for inequality with the given value. It returns a function that returns true if the input is not equal to the specified value.

func MatchNotEqFn added in v0.0.3 

func MatchNotEqFn[T any](v T, cmp CompFunc[T]) Matcher[T]

MatchNotEqFn creates a Matcher that checks for inequality using a custom comparison function. It returns a function that returns true if the input is not equal to the specified value according to the provided comparison function. Panics if the comparison function is nil.

func MatchNotEqFn2 added in v0.0.3 

func MatchNotEqFn2[T any](v T, eq CondFunc[T]) Matcher[T]

MatchNotEqFn2 creates a Matcher that checks for inequality using a custom equality function. It returns a function that returns true if the input is not equal to the specified value according to the provided equality function. Panics if the equality function is nil.

type Mutex 

type Mutex interface {
	Lock()
	TryLock() bool
	Unlock()
}

Mutex defines a standard interface for mutual exclusion locking mechanisms that support basic locking, unlocking, and non-blocking lock attempts.

func ROMutex 

func ROMutex(m RWMutex) Mutex

ROMutex converts an RWMutex to a read-only Mutex, allowing only read locking operations. If the input mutex is nil, it returns nil.

type RWMutex 

type RWMutex interface {
	Mutex

	RLock()
	RUnlock()
	TryRLock() bool
}

RWMutex extends the Mutex interface with read-locking capabilities, allowing multiple readers or a single writer to access a shared resource.

type Store 

type Store[K comparable, V any] interface {
	// Version returns the current version of the data in the Store.
	Version() uint64

	// Now returns the store's current time reference
	Now() time.Time

	// View executes a read-only transaction with optional mutex locks
	// The provided function will be called with a transaction object that
	// can be used to access data in the store
	View(ctx context.Context, fn func(Tx[K, V]) error, locks ...Mutex) error

	// Update executes a read-write transaction with optional mutex locks
	// The provided function will be called with a transaction object that
	// can be used to access and modify data in the store
	Update(ctx context.Context, fn func(Tx[K, V]) error, locks ...Mutex) error

	// Close closes the store and releases its resources
	Close() error
}

Store represents a generic key-value store with versioning and transaction support. It provides a clean interface for working with data in a consistent manner.

Type Parameters:

  • K comparable: The key type, which must be comparable (supports == and != operators)
  • V any: The value type, which can be any type

type Tx 

type Tx[K comparable, V any] interface {
	// Context returns the transaction's context
	Context() context.Context

	// Version returns the data version accessed by this transaction.
	Version() uint64

	// Now returns the transaction's time reference
	Now() time.Time

	// ForEach iterates through key-value pairs matching optional queries
	// The provided function is called for entries matching any of the queries,
	// or for every entry if no queries are provided.
	// Iteration can be ended early by returning false from the callback.
	ForEach(fn func(key K, value V) bool, ors ...Matcher[any]) error

	// Get retrieves a value by key
	Get(key K) (value V, err error)

	// Set associates a value with a key
	Set(key K, value V) error

	// Append adds a value to an existing key (implementation depends on value type)
	Append(key K, value V) error

	// Delete removes a key-value pair
	Delete(key K) error

	// Commit persists changes made within the transaction
	Commit() error

	// Close aborts the transaction if not already committed
	Close() error
}

Tx represents a transaction within the key-value store. It provides methods for reading, writing, and managing data within a transactional context.

Type Parameters:

  • K comparable: The key type, matching the store's key type
  • V any: The value type, matching the store's value type

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.