Add memkv module

.github/workflows/memkv.yml

@@ -0,0 +1,134 @@
+name: check-memkv
+
+on:
+  push:
+    branches:
+      - "main"
+    paths:
+      - "memkv/**"
+      - ".github/workflows/memkv.yml"
+  pull_request:
+    branches:
+      - "*"
+    paths:
+      - "memkv/**"
+      - ".github/workflows/memkv.yml"
+
+jobs:
+
+  clean:
+    name: clean
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    strategy:
+      matrix:
+        go: [stable]
+      fail-fast: true
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+      - name: Run go mod tidy
+        working-directory: memkv
+        run: go mod tidy && git diff --exit-code
+      - name: Run go mod verify
+        working-directory: memkv
+        run: go mod verify
+      - name: Run formatting
+        working-directory: memkv
+        run: go run golang.org/x/tools/cmd/goimports@latest -w . && git diff --exit-code
+
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 4
+    strategy:
+      matrix:
+        go: [stable]
+      fail-fast: true
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+      - name: Run go linting
+        uses: golangci/golangci-lint-action@v4
+        with:
+          version: latest
+          args: --timeout=4m
+          working-directory: memkv
+
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    strategy:
+      matrix:
+        go: [stable]
+      fail-fast: true
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+      - name: Run tests
+        working-directory: memkv
+        run: go test -shuffle=on -v -count=1 -race -failfast -timeout=30s -covermode=atomic -coverprofile=coverage.out ./...
+      - name: Codecov Coverage
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          working-directory: memkv
+
+  benchmark:
+    name: benchmark
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    strategy:
+      matrix:
+        go: [stable]
+      fail-fast: true
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+      - name: Run benchmarks
+        working-directory: memkv
+        run: go test -v -shuffle=on -run=- -bench=. -benchtime=1x -timeout=10s ./...
+
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 4
+    strategy:
+      matrix:
+        go: [stable]
+      fail-fast: true
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go }}
+          cache: true
+      - name: Run go generate
+        working-directory: memkv
+        run: go generate ./... && git diff --exit-code
+      - name: Run go build
+        working-directory: memkv
+        run: go build -o /dev/null ./...

memkv/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ben Wakeford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memkv/README.md

@@ -0,0 +1,3 @@
+# memkv
+[![go reference](https://pkg.go.dev/badge/github.com/wafer-bw/go-toolbox/memkv.svg)](https://pkg.go.dev/github.com/wafer-bw/go-toolbox/memkv)
+[![Go Report Card](https://goreportcard.com/badge/github.com/wafer-bw/go-toolbox/memkv)](https://goreportcard.com/report/github.com/wafer-bw/go-toolbox/memkv)

memkv/go.mod

@@ -0,0 +1,11 @@
+module github.com/wafer-bw/go-toolbox/memkv
+
+go 1.22.4
+
+require github.com/stretchr/testify v1.9.0
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

memkv/go.sum

@@ -0,0 +1,10 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

memkv/internal/underlying/underlying.go

@@ -0,0 +1,15 @@
+// Package underlying provides the underlying data structures for the key-value
+// store.
+package underlying
+
+// Item is a wrapper around the instances of data to be stored allowing for
+// extensions in the future.
+type Item[K comparable, V any] struct {
+	Value V
+}
+
+// Data is a wrapper around any data types used to store data in the store
+// allowing for extensions in the future.
+type Data[K comparable, V any] struct {
+	Items map[K]Item[K, V]
+}

memkv/memkv.go

@@ -0,0 +1,116 @@
+package memkv
+
+import (
+	"sync"
+
+	"github.com/wafer-bw/go-toolbox/memkv/internal/underlying"
+)
+
+type Store[K comparable, V any] struct { // TODO: docstring.
+	mu       *sync.RWMutex
+	capacity int
+	data     *underlying.Data[K, V]
+}
+
+func New[K comparable, V any](capacity int) *Store[K, V] { // TODO: docstring.
+	if capacity < 0 {
+		capacity = 0
+	}
+
+	return &Store[K, V]{
+		mu:       &sync.RWMutex{},
+		capacity: capacity,
+		data: &underlying.Data[K, V]{
+			Items: make(map[K]underlying.Item[K, V], capacity),
+		},
+	}
+}
+
+func (s Store[K, V]) Set(key K, val V) error { // TODO: docstring.
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if _, ok := s.data.Items[key]; !ok && s.capacity > 0 && len(s.data.Items) >= s.capacity {
+		return &AtCapacityError{}
+	}
+
+	s.data.Items[key] = underlying.Item[K, V]{Value: val}
+
+	return nil
+}
+
+func (s Store[K, V]) Get(key K) (V, bool) { // TODO: docstring.
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	item, ok := s.data.Items[key]
+
+	return item.Value, ok
+}
+
+func (s Store[K, V]) Delete(keys ...K) { // TODO: docstring.
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	for _, key := range keys {
+		delete(s.data.Items, key)
+	}
+}
+
+func (s Store[K, V]) Flush() { // TODO: docstring.
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	clear(s.data.Items)
+}
+
+func (s Store[K, V]) Len() int { // TODO: docstring.
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	return len(s.data.Items)
+}
+
+func (s Store[K, V]) Items() map[K]V { // TODO: docstring.
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	items := make(map[K]V, len(s.data.Items))
+	for key, item := range s.data.Items {
+		items[key] = item.Value
+	}
+
+	return items
+}
+
+func (s Store[K, V]) Keys() []K { // TODO: docstring.
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	keys := make([]K, 0, len(s.data.Items))
+	for key := range s.data.Items {
+		keys = append(keys, key)
+	}
+
+	return keys
+}
+
+func (s Store[K, V]) Values() []V { // TODO: docstring.
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	values := make([]V, 0, len(s.data.Items))
+	for _, item := range s.data.Items {
+		values = append(values, item.Value)
+	}
+
+	return values
+}
+
+// AtCapcityError occurs when the [Store] is at capacity and new items cannot be
+// added.
+type AtCapacityError struct{}
+
+func (e *AtCapacityError) Error() string {
+	return "store is at capacity"
+}