tcp.direct
/
database
16
2
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Docs: refresh markdown

This commit is contained in:
kayos@tcp.direct 2022-07-25 21:57:01 -07:00
parent 73e2b6a7a6
commit f045593496
Signed by: kayos
GPG Key ID: 4B841471B4BEE979
3 changed files with 183 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
README.md
View File

@ -12,6 +12,9 @@
```go
type Filer interface {
// Backend returns the underlying key/value store.
Backend() any
// Has should return true if the given key has an associated value.
Has(key []byte) bool
// Get should retrieve the byte slice corresponding to the given key, and any associated errors upon failure.
@ -20,6 +23,10 @@ type Filer interface {
Put(key []byte, value []byte) error
// Delete should delete the key and the value associated with the given key, and return an error upon failure.
Delete(key []byte) error
// Close should safely end any Filer operations of the given dataStore and close any relevant handlers.
Close() error
// Sync should take any volatile data and solidify it somehow if relevant. (ram to disk in most cases)
Sync() error
}
```
@ -39,13 +46,11 @@ type Keeper interface {
// Path should return the base path where all stores should be stored under. (likely as subdirectories)
Path() string
// Init should initialize our Filer at the given path, to be referenced and called by dataStore.
Init(dataStore []byte) error
Init(name string, options ...any) error
// With provides access to the given dataStore by providing a pointer to the related Filer.
With(dataStore []byte) Filer
// Close should safely end any Filer operations of the given dataStore and close any relevant handlers.
Close(dataStore []byte) error
// Sync should take any volatile data and solidify it somehow if relevant. (ram to disk in most cases)
Sync(dataStore []byte) error
With(name string) Store
AllStores() []Filer
CloseAll() error
SyncAll() error
@ -56,28 +61,16 @@ Keeper will be in charge of the more meta operations involving Filers. This
includes operations like initialization, syncing to disk if applicable, and
backing up.
#### type Key
```go
type Key interface {
Bytes() []byte
String() string
Equal(Key) bool
}
```
Key represents a key in a key/value Filer.
#### type Searcher
```go
type Searcher interface {
// AllKeys must retrieve all keys in the datastore with the given storeName.
AllKeys() []string
// PrefixScan must return all keys that begin with the given prefix.
PrefixScan(prefix string) map[string]interface{}
// Search must be able to search through the contents of our database and return a map of results.
Search(query string) map[string]interface{}
AllKeys() [][]byte
// PrefixScan must retrieve all keys in the datastore and stream them to the given channel.
PrefixScan(prefix string) (<-chan *kv.KeyValue, chan error)
// Search must be able to search through the value contents of our database and stream the results to the given channel.
Search(query string) (<-chan *kv.KeyValue, chan error)
// ValueExists searches for an exact match of the given value and returns the key that contains it.
ValueExists(value []byte) (key []byte, ok bool)
}
@ -85,15 +78,11 @@ type Searcher interface {
Searcher must be able to search through our datastore(s) with strings.
#### type Value
#### type Store
```go
type Value interface {
Bytes() []byte
String() string
Equal(Value) bool
type Store interface {
Filer
Searcher
}
```
Value represents a value in a key/value Filer.

130
bitcask/README.md
View File

@ -4,10 +4,40 @@
## Documentation
#### func SetDefaultBitcaskOptions
```go
func SetDefaultBitcaskOptions(bitcaskopts ...bitcask.Option)
```
SetDefaultBitcaskOptions options will set the options used for all subsequent
bitcask stores that are initialized.
#### func WithMaxDatafileSize
```go
func WithMaxDatafileSize(size int) bitcask.Option
```
WithMaxDatafileSize is a shim for bitcask's WithMaxDataFileSize function.
#### func WithMaxKeySize
```go
func WithMaxKeySize(size uint32) bitcask.Option
```
WithMaxKeySize is a shim for bitcask's WithMaxKeySize function.
#### func WithMaxValueSize
```go
func WithMaxValueSize(size uint64) bitcask.Option
```
WithMaxValueSize is a shim for bitcask's WithMaxValueSize function.
#### type DB
```go
type DB struct {}
type DB struct {
}
```
DB is a mapper of a Filer and Searcher implementation using Bitcask.
@ -20,6 +50,13 @@ func OpenDB(path string) *DB
OpenDB will either open an existing set of bitcask datastores at the given
directory, or it will create a new one.
#### func (*DB) AllStores
```go
func (db *DB) AllStores() []database.Filer
```
AllStores returns a list of all bitcask datastores.
#### func (*DB) Close
```go
@ -37,7 +74,7 @@ CloseAll closes all bitcask datastores.
#### func (*DB) Init
```go
func (db *DB) Init(storeName string, bitcaskopts ...bitcask.Option) error
func (db *DB) Init(storeName string, opts ...any) error
```
Init opens a bitcask store at the given path to be referenced by storeName.
@ -67,56 +104,23 @@ SyncAll syncs all bitcask datastores.
```go
func (db *DB) SyncAndCloseAll() error
```
SyncAndCloseAll implements the method from Keeper.
SyncAndCloseAll implements the method from Keeper to sync and close all bitcask
stores.
#### func (*DB) With
```go
func (db *DB) With(storeName string) Store
func (db *DB) With(storeName string) database.Store
```
With calls the given underlying bitcask instance.
#### type Key
#### func (*DB) WithNew
```go
type Key struct {
database.Key
}
func (db *DB) WithNew(storeName string) database.Filer
```
Key represents a key in a key/value store.
#### func (Key) Bytes
```go
func (k Key) Bytes() []byte
```
Bytes returns the raw byte slice form of the Key.
#### func (Key) Equal
```go
func (k Key) Equal(k2 Key) bool
```
Equal determines if two keys are equal.
#### func (Key) String
```go
func (k Key) String() string
```
String returns the string slice form of the Key.
#### type KeyValue
```go
type KeyValue struct {
Key Key
Value Value
}
```
KeyValue represents a key and a value from a key/value store.
WithNew calls the given underlying bitcask instance, if it doesn't exist, it
creates it.
#### type Store
@ -136,10 +140,17 @@ func (s Store) AllKeys() (keys [][]byte)
```
AllKeys will return all keys in the database as a slice of byte slices.
#### func (Store) Backend
```go
func (s Store) Backend() any
```
Backend returns the underlying bitcask instance.
#### func (Store) PrefixScan
```go
func (s Store) PrefixScan(prefix string) ([]KeyValue, error)
func (s Store) PrefixScan(prefix string) (<-chan *kv.KeyValue, chan error)
```
PrefixScan will scan a Store for all keys that have a matching prefix of the
given string and return a map of keys and values. (map[Key]Value)
@ -147,7 +158,7 @@ given string and return a map of keys and values. (map[Key]Value)
#### func (Store) Search
```go
func (s Store) Search(query string) ([]KeyValue, error)
func (s Store) Search(query string) (<-chan *kv.KeyValue, chan error)
```
Search will search for a given string within all values inside of a Store. Note,
type casting will be necessary. (e.g: []byte or string)
@ -159,34 +170,3 @@ func (s Store) ValueExists(value []byte) (key []byte, ok bool)
```
ValueExists will check for the existence of a Value anywhere within the
keyspace, returning the Key and true if found, or nil and false if not found.
#### type Value
```go
type Value struct {
database.Value
}
```
Value represents a value in a key/value store.
#### func (Value) Bytes
```go
func (v Value) Bytes() []byte
```
Bytes returns the raw byte slice form of the Value.
#### func (Value) Equal
```go
func (v Value) Equal(v2 Value) bool
```
Equal determines if two values are equal.
#### func (Value) String
```go
func (v Value) String() string
```
String returns the string slice form of the Value.

108
kv/README.md Normal file
View File

@ -0,0 +1,108 @@
# kv
`import "git.tcp.direct/tcp.direct/database/kv"`
## Documentation
#### type Key
```go
type Key struct {}
```
Key represents a key in a key/value store.
#### func NewKey
```go
func NewKey(data []byte) *Key
```
NewKey creates a new Key from a byte slice.
#### func (*Key) Bytes
```go
func (k *Key) Bytes() []byte
```
Bytes returns the raw byte slice form of the Key.
#### func (*Key) Equal
```go
func (k *Key) Equal(k2 *Key) bool
```
Equal determines if two keys are equal.
#### func (*Key) String
```go
func (k *Key) String() string
```
String returns the string slice form of the Key.
#### type KeyValue
```go
type KeyValue struct {
Key *Key
Value *Value
}
```
KeyValue represents a key and a value from a key/value store.
#### func NewKeyValue
```go
func NewKeyValue(k *Key, v *Value) *KeyValue
```
NewKeyValue creates a new KeyValue from a key and value.
#### func (*KeyValue) Equal
```go
func (kv *KeyValue) Equal(kv2 *KeyValue) bool
```
Equal determines if two key/value pairs are equal.
#### func (*KeyValue) String
```go
func (kv *KeyValue) String() string
```
#### type Value
```go
type Value struct {}
```
Value represents a value in a key/value store.
#### func NewValue
```go
func NewValue(data []byte) *Value
```
NewValue creates a new Value from a byte slice.
#### func (*Value) Bytes
```go
func (v *Value) Bytes() []byte
```
Bytes returns the raw byte slice form of the Value.
#### func (*Value) Equal
```go
func (v *Value) Equal(v2 *Value) bool
```
Equal determines if two values are equal.
#### func (*Value) String
```go
func (v *Value) String() string
```
String returns the string slice form of the Value.