kv

README

KV

This library provides a simple and flexible key-value store abstraction with support for CRUD operations, batch writes, range queries, and efficient enumeration.

The KV interface allows you to interact with different backends (e.g., Pebble, etc) seamlessly.

---

🚀 Features

• 🔑 Basic CRUD operations (Get, Put, Remove)
• ⚡ Batch operations with deduplication support
• 🔍 Range and prefix queries
• 🔄 Efficient item enumeration
• 🛠️ Support for custom query operators (e.g., GreaterThan, Between, StartsWith)

---

📦 Installation

go get github.com/fgrzl/kv

Documentation

Index

• func ReverseItems(items []*Item)
• func SortItems(items []*Item, direction SortDirection)
• type BatchItem
• type BatchOp
• type Item
• type KV
• type QueryArgs
• type QueryOperator
• type Queue
  • func NewQueue[T any](capacity int) *Queue[T]
  • func (q *Queue[T]) Dequeue() (T, bool)
  • func (q *Queue[T]) Enqueue(item T)
  • func (q *Queue[T]) IsEmpty() bool
  • func (q *Queue[T]) Length() int
  • func (q *Queue[T]) Reset()
• type SortDirection

Functions

func ReverseItems

func ReverseItems(items []*Item)

ReverseItems reverses a slice of Item pointers in place.

func SortItems

func SortItems(items []*Item, direction SortDirection)

SortItems sorts []*kv.Item by PartitionKey and RowKey in ascending or descending order.

Types

type BatchItem

type BatchItem struct {
	Op    BatchOp
	PK    lexkey.PrimaryKey
	Value []byte
}

BatchItem represents an operation to perform in a batch.

type BatchOp

type BatchOp int

BatchOp defines the type of batch operation.

const (
	NoOp BatchOp = iota
	Put
	Delete
)

type Item

type Item struct {
	PK    lexkey.PrimaryKey
	Value []byte
}

Item represents a key-value pair stored in the KV store.

type KV

type KV interface {
	Get(ctx context.Context, pk lexkey.PrimaryKey) (*Item, error)
	GetBatch(ctx context.Context, keys ...lexkey.PrimaryKey) ([]*Item, error)
	Put(ctx context.Context, item *Item) error
	Remove(ctx context.Context, pk lexkey.PrimaryKey) error
	RemoveBatch(ctx context.Context, keys ...lexkey.PrimaryKey) error
	RemoveRange(ctx context.Context, rangeKey lexkey.RangeKey) error
	Query(ctx context.Context, queryArgs QueryArgs, sort SortDirection) ([]*Item, error)
	Enumerate(ctx context.Context, queryArgs QueryArgs) enumerators.Enumerator[*Item]
	Batch(ctx context.Context, items []*BatchItem) error
	BatchChunks(ctx context.Context, items enumerators.Enumerator[*BatchItem], chunkSize int) error
	Close() error
}

KV defines the interface for a key-value store.

type QueryArgs

type QueryArgs struct {
	PartitionKey lexkey.LexKey
	StartRowKey  lexkey.LexKey
	EndRowKey    lexkey.LexKey
	Operator     QueryOperator
	Limit        int
}

QueryArgs defines parameters for querying the KV store.

type QueryOperator

type QueryOperator int

QueryOperator defines the type of query operation.

const (
	Scan QueryOperator = iota
	Equal
	GreaterThan
	GreaterThanOrEqual
	LessThan
	LessThanOrEqual
	Between
	StartsWith
)

type Queue

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

Queue is an optimized FIFO queue with preallocation and efficient memory management.

func NewQueue

func NewQueue[T any](capacity int) *Queue[T]

NewQueue initializes a queue with a preallocated capacity.

func (*Queue[T]) Dequeue

func (q *Queue[T]) Dequeue() (T, bool)

Dequeue removes and returns the first item in the queue.

func (*Queue[T]) Enqueue

func (q *Queue[T]) Enqueue(item T)

Enqueue adds an item efficiently to the end of the queue.

func (*Queue[T]) IsEmpty

func (q *Queue[T]) IsEmpty() bool

IsEmpty checks if the queue has no items left.

func (*Queue[T]) Length

func (q *Queue[T]) Length() int

Length returns the number of remaining items.

func (*Queue[T]) Reset

func (q *Queue[T]) Reset()

Reset clears the queue while preserving allocated capacity.

type SortDirection

type SortDirection int

SortDirection defines the sorting order for query results.

const (
	Ascending SortDirection = iota
	Descending
)