katalis

README

katalis

Katalis is a Go package that wraps the Pogreb key-value store, enhancing it with Go generics to provide type-safe operations. This package allows developers to leverage the efficiency of Pogreb while ensuring both compile-time type safety for their data and ease of use.

Features

• Type-Safe Operations: Use Go generics to enforce type safety for key-value pairs.
• High Performance: Built on top of Pogreb, known for its fast and efficient storage capabilities.
• Simple API: Easy-to-use interface that integrates seamlessly with Go's type system.

Installation

go get github.com/NicoNex/katalis@latest

Usage

Here's a quick example on how to use katalis to store a key of type string and a value of type User:

package main

import (
  "fmt"

  "github.com/NicoNex/katalis"
)

type User struct {
  Name    string
  Age     int
  Country string
}

func main() {
  // Create a custom gob codec for the User struct using the provided katalis.GobCodec.
  var userCodec = katalis.GobCodec[User]{}

  // Get the instance to the existing or newly created DB passing katalis.StringCodec as the
  // codec for the key, and our custom userCodec for the value.
  db, err := katalis.Open("path/to/db", katalis.StringCodec, userCodec)
  if err != nil {
    panic(err)
  }
  defer db.Close()

  // Easily store the string-User key value pair without dealing with the conversion to []byte.
  err := db.Put("alice-id", User{Name: "Alice", Age: 20, Country: "Italy"})
  if err != nil {
    panic(err)
  }

  // The variable alice here will be of type User.
  alice, err := db.Get("alice-id")
  if err != nil {
    panic(err)
  }

  fmt.Println(alice)
}

Documentation

Index

• Variables
• type Codec
• type DB
  • func Open[KT, VT any](path string, keyCodec Codec[KT], valCodec Codec[VT]) (db DB[KT, VT], err error)
  • func OpenOptions[KT, VT any](path string, keyCodec Codec[KT], valCodec Codec[VT], opts *Options) (db DB[KT, VT], err error)
  • func (db DB[KT, VT]) Del(key KT) error
  • func (db DB[KT, VT]) Fold(fn func(key KT, val VT, err error) error) (err error)
  • func (db DB[KT, VT]) Get(key KT) (res VT, err error)
  • func (db DB[KT, VT]) Has(key KT) (bool, error)
  • func (db DB[KT, VT]) Put(key KT, val VT) error
• type GobCodec
  • func (pc GobCodec[T]) Decode(b []byte) (t T, err error)
  • func (pc GobCodec[T]) Encode(a T) ([]byte, error)
• type Options

Variables

var (
	Uint64Codec  = uint64Codec{}
	Int64Codec   = int64Codec{}
	Float64Codec = float64Codec{}
	StringCodec  = stringCodec{}
	BytesCodec   = bytesCodec{}
)

var ErrIterationDone = pogreb.ErrIterationDone

Types

type Codec

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

type DB

type DB[KT, VT any] struct {
	*pogreb.DB
	// contains filtered or unexported fields
}

func Open

func Open[KT, VT any](path string, keyCodec Codec[KT], valCodec Codec[VT]) (db DB[KT, VT], err error)

Open opens or creates a new DB. The DB must be closed after use, by calling Close method.

func OpenOptions

func OpenOptions[KT, VT any](path string, keyCodec Codec[KT], valCodec Codec[VT], opts *Options) (db DB[KT, VT], err error)

OpenOptions is like Open but accepts an Options struct.

func (DB[KT, VT]) Del

func (db DB[KT, VT]) Del(key KT) error

func (DB[KT, VT]) Fold

func (db DB[KT, VT]) Fold(fn func(key KT, val VT, err error) error) (err error)

Fold iterates over all keys in the database calling the function `fn` for each key. If the function returns an error, no further keys are processed and the error returned.

func (DB[KT, VT]) Get

func (db DB[KT, VT]) Get(key KT) (res VT, err error)

Get returns the value for the given key stored in the DB or an empty value if the key doesn't exist.

func (DB[KT, VT]) Has

func (db DB[KT, VT]) Has(key KT) (bool, error)

Has returns true if the DB contains the given key.

func (DB[KT, VT]) Put

func (db DB[KT, VT]) Put(key KT, val VT) error

Put sets the value for the given key. It updates the value for the existing key.

type GobCodec

type GobCodec[T any] struct{}

func (GobCodec[T]) Decode

func (pc GobCodec[T]) Decode(b []byte) (t T, err error)

func (GobCodec[T]) Encode

func (pc GobCodec[T]) Encode(a T) ([]byte, error)

type Options

type Options = pogreb.Options