jsondb

package module
v0.0.0-...-6a25a8b Latest Latest
Warning

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

 Go to latest Published: Jul 16, 2026 License: MIT Imports: 11 Imported by: 2

Documentation

Overview

Package jsondb provides thin wrappers for storing JSON-serializable values in a SOP B-Tree with helpers for paging and convenience CRUD operations.

Note: This package offers similar performance to the native Go implementation because SOP efficiently serializes entire B-Tree nodes and value segments, minimizing JSON overhead.

Index

Constants

View Source 
const (
	// Forward iterates from low to high.
	Forward = iota
	// Backward iterates from high to low.
	Backward
)

Variables

This section is empty.

Functions

This section is empty.

Types

type IndexFieldSpecification 

type IndexFieldSpecification struct {
	FieldName string `json:"field_name"`
	// AscendingSortOrder chooses ascending (true) or descending (false) order.
	AscendingSortOrder bool `json:"ascending_sort_order"`
	// contains filtered or unexported fields
}

IndexFieldSpecification declares a field and its sort order in the composite index.

type IndexSpecification 

type IndexSpecification struct {
	// IndexFields contains the ordered list of fields participating in the index.
	IndexFields []IndexFieldSpecification `json:"index_fields"`
}

IndexSpecification defines the B-Tree key index configuration.

func NewIndexSpecification 

func NewIndexSpecification(indexFields []IndexFieldSpecification) *IndexSpecification

NewIndexSpecification constructs an IndexSpecification with the provided fields.

func (*IndexSpecification) Comparer 

func (idx *IndexSpecification) Comparer(x map[string]any, y map[string]any) int

Comparer compares two map keys using the configured field list and sort order.

type Item 

type Item[TK btree.Ordered, TV any] struct {
	Key   TK        `json:"key"`
	Value *TV       `json:"value"`
	ID    uuid.UUID `json:"id"`
}

Item contains a Key and Value pair, with a generated UUID for reference.

type JsonDBAnyKey 

type JsonDBAnyKey[TK btree.Ordered, TV any] struct {
	btree.BtreeInterface[TK, TV]
}

JsonDBAnyKey wraps a B-Tree for storing arbitrary JSON-serializable values under an ordered key.

func NewJsonBtree 

func NewJsonBtree[TK btree.Ordered, TV any](ctx context.Context, config sop.DatabaseOptions, so sop.StoreOptions, t sop.Transaction, comparer btree.ComparerFunc[TK]) (*JsonDBAnyKey[TK, TV], error)

NewJsonBtree creates a new JSON-capable B-Tree. Values are marshaled by the caller as needed.

func OpenJsonBtree 

func OpenJsonBtree[TK btree.Ordered, TV any](ctx context.Context, config sop.DatabaseOptions, name string, t sop.Transaction, comparer btree.ComparerFunc[TK]) (*JsonDBAnyKey[TK, TV], error)

OpenJsonBtree opens an existing JSON-capable B-Tree.

func OpenJsonBtreeCursor 

func OpenJsonBtreeCursor[TK btree.Ordered, TV any](ctx context.Context, config sop.DatabaseOptions, name string, t sop.Transaction, comparer btree.ComparerFunc[TK]) (*JsonDBAnyKey[TK, TV], error)

OpenJsonBtreeCursor opens a cursor wrapper for a given Btree. It opens it if it is not yet.

func (*JsonDBAnyKey[TK, TV]) Add 

func (j *JsonDBAnyKey[TK, TV]) Add(ctx context.Context, items []Item[TK, TV]) (bool, error)

Add inserts items without duplicate checks; returns true only if all inserts succeed.

func (*JsonDBAnyKey[TK, TV]) AddIfNotExist 

func (j *JsonDBAnyKey[TK, TV]) AddIfNotExist(ctx context.Context, items []Item[TK, TV]) (bool, error)

AddIfNotExist inserts items only when the key does not already exist.

func (*JsonDBAnyKey[TK, TV]) GetCurrentKey 

func (j *JsonDBAnyKey[TK, TV]) GetCurrentKey() (string, error)

GetCurrentKey returns the current item's key and ID as a JSON string.

func (*JsonDBAnyKey[TK, TV]) GetCurrentValue 

func (j *JsonDBAnyKey[TK, TV]) GetCurrentValue(ctx context.Context) (string, error)

GetCurrentValue returns the current item's value as a JSON string.

func (*JsonDBAnyKey[TK, TV]) GetItems 

func (j *JsonDBAnyKey[TK, TV]) GetItems(ctx context.Context, pagingInfo PagingInfo) (string, error)

GetItems returns a JSON string of items starting from the current cursor and paginated per PagingInfo.

func (*JsonDBAnyKey[TK, TV]) GetKeys 

func (j *JsonDBAnyKey[TK, TV]) GetKeys(ctx context.Context, pagingInfo PagingInfo) (string, error)

GetKeys returns a JSON string of keys starting from the current cursor and paginated per PagingInfo.

func (*JsonDBAnyKey[TK, TV]) GetValues 

func (j *JsonDBAnyKey[TK, TV]) GetValues(ctx context.Context, keys []Item[TK, TV]) (string, error)

GetValues finds items by key (or id) and returns their values as a JSON string.

func (*JsonDBAnyKey[TK, TV]) Remove 

func (j *JsonDBAnyKey[TK, TV]) Remove(ctx context.Context, keys []TK) (bool, error)

Remove deletes items by key; returns true only if all deletions succeed.

func (*JsonDBAnyKey[TK, TV]) Update 

func (j *JsonDBAnyKey[TK, TV]) Update(ctx context.Context, items []Item[TK, TV]) (bool, error)

Update replaces existing values for the provided keys.

func (*JsonDBAnyKey[TK, TV]) UpdateCurrentKey 

func (j *JsonDBAnyKey[TK, TV]) UpdateCurrentKey(ctx context.Context, item Item[TK, TV]) (bool, error)

UpdateCurrentKey updates the key of the currently positioned item.

func (*JsonDBAnyKey[TK, TV]) UpdateKey 

func (j *JsonDBAnyKey[TK, TV]) UpdateKey(ctx context.Context, items []Item[TK, TV]) (bool, error)

UpdateKey updates the key of the item found by the key in the provided item.

func (*JsonDBAnyKey[TK, TV]) Upsert 

func (j *JsonDBAnyKey[TK, TV]) Upsert(ctx context.Context, items []Item[TK, TV]) (bool, error)

Upsert adds new items or updates existing ones based on key existence.

type JsonDBMapKey 

type JsonDBMapKey struct {
	*JsonDBAnyKey[map[string]any, any]
	// contains filtered or unexported fields
}

JsonDBMapKey wraps JsonDBAnyKey to support map[string]any keys with configurable index specifications.

func NewJsonBtreeMapKey 

func NewJsonBtreeMapKey(ctx context.Context, config sop.DatabaseOptions, so sop.StoreOptions, t sop.Transaction, indexSpecification string) (*JsonDBMapKey, error)

NewJsonBtreeMapKey creates a schema-less JSON B-Tree using map[string]any keys and optional index spec. This function is fully interoperable with other language bindings and offers high performance.

func OpenJsonBtreeMapKey 

func OpenJsonBtreeMapKey(ctx context.Context, config sop.DatabaseOptions, name string, t sop.Transaction) (*JsonDBMapKey, error)

OpenJsonBtreeMapKey opens an existing schema-less JSON B-Tree and reconstructs its index specification.

func OpenJsonBtreeMapKeyCursor 

func OpenJsonBtreeMapKeyCursor(ctx context.Context, config sop.DatabaseOptions, name string, t sop.Transaction) (*JsonDBMapKey, error)

OpenJsonBtreeMapKeyCursor opens a cursor wrapper for a given Btree. It opens it if it is not yet.

type JsonDBStructKey 

type JsonDBStructKey[TK any, TV any] struct {
	*JsonDBMapKey
}

JsonDBStructKey wraps JsonDBMapKey to support Go struct keys with configurable index specifications. It automatically converts struct keys to map[string]any for storage and indexing.

func NewJsonBtreeStructKey 

func NewJsonBtreeStructKey[TK any, TV any](ctx context.Context, config sop.DatabaseOptions, so sop.StoreOptions, t sop.Transaction, indexSpecification *IndexSpecification) (*JsonDBStructKey[TK, TV], error)

NewJsonBtreeStructKey creates a new B-Tree that uses a struct as the Key. The struct is converted to a map internally to support the IndexSpecification.

func OpenJsonBtreeStructKey 

func OpenJsonBtreeStructKey[TK any, TV any](ctx context.Context, config sop.DatabaseOptions, name string, t sop.Transaction) (*JsonDBStructKey[TK, TV], error)

OpenJsonBtreeStructKey opens an existing B-Tree that uses a struct as the Key.

func (*JsonDBStructKey[TK, TV]) Add 

func (j *JsonDBStructKey[TK, TV]) Add(ctx context.Context, items []Item[TK, TV]) (bool, error)

Add adds items to the store.

func (*JsonDBStructKey[TK, TV]) Find 

func (j *JsonDBStructKey[TK, TV]) Find(ctx context.Context, key TK, autoScroll bool) (bool, error)

Find finds an item by key.

func (*JsonDBStructKey[TK, TV]) GetCurrentKey 

func (j *JsonDBStructKey[TK, TV]) GetCurrentKey() TK

GetCurrentKey returns the current key as the struct type TK.

func (*JsonDBStructKey[TK, TV]) GetCurrentValue 

func (j *JsonDBStructKey[TK, TV]) GetCurrentValue(ctx context.Context) (TV, error)

GetCurrentValue returns the current value as the struct type TV.

func (*JsonDBStructKey[TK, TV]) Remove 

func (j *JsonDBStructKey[TK, TV]) Remove(ctx context.Context, keys []TK) (bool, error)

Remove removes items by key.

func (*JsonDBStructKey[TK, TV]) Update 

func (j *JsonDBStructKey[TK, TV]) Update(ctx context.Context, items []Item[TK, TV]) (bool, error)

Update updates items in the store.

type PagingDirection 

type PagingDirection int

type PagingInfo 

type PagingInfo struct {
	// PageOffset is the page index to move to before fetching (0 to start from current).
	PageOffset int `json:"page_offset"`
	// PageSize is the number of elements per page.
	PageSize int `json:"page_size"`
	// FetchCount overrides PageSize when > 0 to fetch an exact number of elements.
	FetchCount int `json:"fetch_count"`
	// Direction selects forward or backward iteration.
	Direction PagingDirection `json:"direction"`
}

PagingInfo specifies pagination when reading keys or items.

type StoreAccessor 

type StoreAccessor interface {
	First(ctx context.Context) (bool, error)
	Last(ctx context.Context) (bool, error)
	Next(ctx context.Context) (bool, error)
	Previous(ctx context.Context) (bool, error)
	FindOne(ctx context.Context, key any, first bool) (bool, error)
	FindInDescendingOrder(ctx context.Context, key any) (bool, error)
	GetCurrentKey() any
	GetCurrentValue(ctx context.Context) (any, error)
	GetCurrentValueNoLock(ctx context.Context) (any, error)
	RLockCurrentItem(ctx context.Context) error
	Add(ctx context.Context, key any, value any) (bool, error)
	Update(ctx context.Context, key any, value any) (bool, error)
	Remove(ctx context.Context, key any) (bool, error)
	GetStoreInfo() sop.StoreInfo
}

StoreAccessor provides a unified interface for accessing both primitive and JSON B-Trees.

func CreateObjectStore 

func CreateObjectStore(ctx context.Context, dbOpts sop.DatabaseOptions, storeName string, tx sop.Transaction) (StoreAccessor, error)

CreateObjectStore creates a new B-Tree store with default generic Key and Value types.

func OpenStore 

func OpenStore(ctx context.Context, dbOpts sop.DatabaseOptions, storeName string, tx sop.Transaction) (StoreAccessor, error)

OpenStore opens a B-Tree store, automatically detecting if it's a primitive or JSON store.

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.