Back to godoc.org
github.com/sdslabs/kiwi

Package kiwi

v1.0.0
Latest Go to latest

The highest tagged major version is .

Published: Sep 3, 2020 | License: MIT | Module: github.com/sdslabs/kiwi

Overview

Package kiwi implements a minimalistic in-memory key value store.

Each key is thread safe as it is protected by its own mutex, though different keys can be accessed by various threads.

To get started, create a store with the NewStore function and add keys to it using AddKey. Each key is associated with a value which has a specific type. These types are extendible and can be created by implementing the Value interface.

Store can also be initialized with a schema, which is basically a map of keys and value types.

Get Started

Create a store, add key and play with it. It's that easy!

store := kiwi.NewStore()

if err := store.AddKey("my_string", "str"); err != nil {
  // handle error
}

if _, err := store.Do("my_string", "UPDATE", "Hello, World!"); err != nil {
  // handle error
}

v, err := store.Do("my_string", "GET")
if err != nil {
  // handle error
}

fmt.Println(v.(string)) // Hello, World!

For documentation visit https://kiwi.sdslabs.co/docs/

Index

Variables

var (
	ErrKeyExists   = fmt.Errorf("key already exists")
	ErrKeyNotExist = fmt.Errorf("key does not exist")
)

Various errors related to keys.

var (
	ErrValueRegistered    = fmt.Errorf("value already registered")
	ErrValueNotRegistered = fmt.Errorf("value not registered")
)

Errors related to values.

var (
	ErrInvalidAction = fmt.Errorf("invalid action")
)

Errors related to actions.

func ListRegisteredValues

func ListRegisteredValues() []string

ListRegisteredValues lists all the values registered with the package.

func RegisterValue

func RegisterValue(newFn func() Value)

RegisterValue registers a new value type with the package.

It takes in two params: the type of the value and a function to create a new value.

type Action

type Action string

Action is required to invoke (or "Do") an action.

type DoFunc

type DoFunc func(params ...interface{}) (interface{}, error)

DoFunc is a function that can be executed when an action is invoked.

type ImportOpts

type ImportOpts struct {
	// AddKeys specifies whether to add keys that do not exist.
	AddKeys bool

	// UpdateTypes specifies if the type of key in JSON doesn't match the one
	// with already-defined key, should the type of key be updated or not.
	UpdateTypes bool

	// ErrOnInvalidKey specifies whether to throw error if the key in the JSON
	// does not exist in the actual schema of the Store.
	// This option is considered only when `AddKeys` is false.
	ErrOnInvalidKey bool
}

ImportOpts are the options that can be used to configure how to import data into the store from raw JSON.

type Schema

type Schema map[string]ValueType

Schema contains the value types corresponding to their keys.

func (Schema) String

func (s Schema) String() string

String implements the fmt.Stringer interface.

type Store

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

Store is the main element that contains and manages all the key value pairs.

func NewStore

func NewStore() *Store

NewStore creates an empty store without any key value pairs initialized.

func NewStoreFromSchema

func NewStoreFromSchema(schema Schema) (*Store, error)

NewStoreFromSchema creates a new store from the provided schema.

func (*Store) AddKey

func (s *Store) AddKey(key string, typ ValueType) error

AddKey adds a new key to the store. It throws an error if the key already exists.

func (*Store) DeleteKey

func (s *Store) DeleteKey(key string) error

DeleteKey deletes the key if it exists. Throws an error if it doesn't.

func (*Store) Do

func (s *Store) Do(key string, action Action, params ...interface{}) (interface{}, error)

Do executes the action for the value associated with the value.

func (*Store) Export

func (s *Store) Export() (json.RawMessage, error)

Export returns JSON data for the store.

The data is in the format (StoreJSON):

{
	"key_1": {
		"type": "str",
		"data": "hello"
	},
	"key_2": {
		"type": "hash",
		"data": {
			"a": "b",
			"c": "d"
		}
	}
}

func (*Store) FromJSON

func (s *Store) FromJSON(key string, rawmessage json.RawMessage) error

FromJSON takes the raw JSON form of data and loads it into the value.

func (*Store) GetSchema

func (s *Store) GetSchema() Schema

GetSchema returns the schema of the store.

func (*Store) GetValueType

func (s *Store) GetValueType(key string) (ValueType, error)

GetValueType returns the type of value corresponding to the key.

func (*Store) Import

func (s *Store) Import(rawmessage json.RawMessage, opts ImportOpts) error

Import loads store from the data.

The default behavior is that the store takes the data from the JSON and if an unknown key exists, i.e., a key that is not already added to the store, it silently skips the value associated with it. This can be configured using the ImportOpts.

The data is in the format (StoreJSON):

{
	"key_1": {
		"type": "str",
		"data": "hello"
	},
	"key_2": {
		"type": "hash",
		"data": {
			"a": "b",
			"c": "d"
		}
	}
}

func (*Store) KeyExists

func (s *Store) KeyExists(key string) bool

KeyExists tells if the key exists or not.

func (*Store) ToJSON

func (s *Store) ToJSON(key string) (json.RawMessage, error)

ToJSON converts the data associated with the value into JSON format.

func (*Store) UpdateKey

func (s *Store) UpdateKey(key string, typ ValueType) error

UpdateKey updates the key if it exists. Throws an error if it doesn't.

type StoreJSON

type StoreJSON = map[string]ValJSON

StoreJSON is the type which includes all the data for the store.

type ValJSON

type ValJSON struct {
	Type string          `json:"type"`
	Data json.RawMessage `json:"data"`
}

ValJSON is the JSON object for each value.

type Value

type Value interface {
	// Type returns the type of the value.
	Type() ValueType

	// DoMap returns a map which associates actions with a do function.
	DoMap() map[Action]DoFunc

	// ToJSON returns a raw byte array of the data.
	ToJSON() (json.RawMessage, error)

	// FromJSON returns the data in golang from a raw byte array.
	FromJSON(json.RawMessage) error
}

Value is something that can be associated with a "key".

A value implements its own methods and can be accessed by type assertion. To add a value type to the register simply call RegisterValue. All the default values are already registered with the package.

type ValueType

type ValueType string

ValueType is the name of type of value.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier