initial commit

Author: Code-Hex

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 codehex
+
+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.

README.md

@@ -0,0 +1,76 @@
+# go-generics-cache
+
+go-generics-cache is an in-memory key:value store/cache that is suitable for applications running on a single machine. This in-memory cache uses [Go Generics](https://go.dev/blog/generics-proposal) which will be introduced in 1.18.
+
+- implemented with [Go Generics](https://go.dev/blog/generics-proposal)
+- a thread-safe `map[string]interface{}` with expiration times
+
+## Requirements
+
+Go 1.18 or later.
+
+If Go 1.18 has not been released but you want to try this package, you can easily do so by using the [`gotip`](https://pkg.go.dev/golang.org/dl/gotip) command.
+
+```sh
+$ go install golang.org/dl/gotip@latest
+$ gotip download # latest commit
+$ gotip version
+go version devel go1.18-c2397905e0 Sat Nov 13 03:33:55 2021 +0000 darwin/arm64
+```
+
+## Install
+
+   go get github.com/Code-Hex/go-generics-cache
+
+## Usage
+
+See also [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/example_test.go)
+
+```go
+package main
+
+import (
+	"fmt"
+
+	cache "github.com/Code-Hex/go-generics-cache"
+)
+
+func main() {
+    // Create a cache. key as string, value as int.
+    c1 := cache.New[string, int]()
+
+    // Sets the value of int. you can set with expiration option.
+    c1.Set("foo", 1, cache.WithExpiration(time.Hour))
+
+    // the value never expires.
+    c1.Set("bar", 2)
+
+    foo, ok := c.Get("foo")
+	if ok {
+		fmt.Println(foo) // 1
+	}
+
+    fmt.Println(c.Keys()) // outputs "foo" "bar" may random
+
+    // Create a cache. key as int, value as string.
+    c2 := cache.New[int, string]()
+    c2.Set(1, "baz")
+    baz, ok := c.Get(1)
+	if ok {
+		fmt.Println(baz) // "baz"
+	}
+
+	// Create a cache for Number constraint.. key as string, value as int.
+	nc := cache.NewNumber[string, int]()
+    nc.Set("age", 26)
+
+    // This will be compile error, because string is not satisfied cache.Number constraint.
+    // nc := cache.NewNumber[string, string]()
+
+    incremented, _ := nc.Increment("age", 1)
+    fmt.Println(incremented) // 27
+
+    decremented, _ := nc.Decrement("age", 1)
+    fmt.Println(decremented) // 26
+}
+```

cache.go

@@ -0,0 +1,164 @@
+package cache
+
+import (
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+)
+
+var (
+	// ErrNotFound is an error which indicate an item is not found.
+	ErrNotFound = errors.New("not found item")
+
+	// ErrExpired is an error which indicate an item is expired.
+	ErrExpired = errors.New("expired item")
+)
+
+// Item is an item
+type Item[T any] struct {
+	Value      T
+	Expiration time.Duration
+	CreatedAt  time.Time
+}
+
+var nowFunc = time.Now
+
+// HasExpired returns true if the item has expired.
+// If the item's expiration is zero value, returns false.
+func (i Item[T]) HasExpired() bool {
+	if i.Expiration <= 0 {
+		return false
+	}
+	return i.CreatedAt.Add(i.Expiration).Before(nowFunc())
+}
+
+// Cache is a base struct for creating in-memory cache.
+type Cache[K comparable, V any] struct {
+	items map[K]Item[V]
+	mu    sync.RWMutex
+}
+
+// New creates a new cache.
+func New[K comparable, V any]() *Cache[K, V] {
+	return &Cache[K, V]{
+		items: make(map[K]Item[V]),
+	}
+}
+
+// ItemOption is an option for cache item.
+type ItemOption func(o *options)
+
+type options struct {
+	expiration time.Duration // default none
+}
+
+// WithExpiration is an option to set expiration time for any items.
+func WithExpiration(exp time.Duration) ItemOption {
+	return func(o *options) {
+		o.expiration = exp
+	}
+}
+
+// Set sets any item to the cache. replacing any existing item.
+// The default item never expires.
+func (c *Cache[K, V]) Set(k K, v V, opts ...ItemOption) {
+	o := new(options)
+	for _, optFunc := range opts {
+		optFunc(o)
+	}
+	item := Item[V]{
+		Value:      v,
+		Expiration: o.expiration,
+		CreatedAt:  nowFunc(),
+	}
+	c.SetItem(k, item)
+}
+
+// SetItem sets any item to the cache. replacing any existing item.
+// The default item never expires.
+func (c *Cache[K, V]) SetItem(k K, v Item[V]) {
+	c.mu.Lock()
+	c.items[k] = v
+	c.mu.Unlock()
+}
+
+// Get gets an item from the cache.
+// Returns the item or zero value, and a bool indicating whether the key was found.
+func (c *Cache[K, V]) Get(k K) (val V, ok bool) {
+	item, err := c.GetItem(k)
+	if err != nil {
+		return
+	}
+	return item.Value, true
+}
+
+// GetItem gets an item from the cache.
+// Returns an error if the item was not found or expired. If there is no error, the
+// incremented value is returned.
+func (c *Cache[K, V]) GetItem(k K) (val Item[V], _ error) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	got, found := c.items[k]
+	if !found {
+		return val, fmt.Errorf("key[%v]: %w", k, ErrNotFound)
+	}
+	if got.HasExpired() {
+		return val, fmt.Errorf("key[%v]: %w", k, ErrExpired)
+	}
+	return got, nil
+}
+
+// Keys returns cache keys. the order is random.
+func (c *Cache[K, _]) Keys() []K {
+	ret := make([]K, 0, len(c.items))
+	for key := range c.items {
+		ret = append(ret, key)
+	}
+	return ret
+}
+
+// NumberCache is a in-memory cache which is able to store only Number constraint.
+type NumberCache[K comparable, V Number] struct {
+	*Cache[K, V]
+}
+
+// NewNumber creates a new cache for Number constraint.
+func NewNumber[K comparable, V Number]() *NumberCache[K, V] {
+	return &NumberCache[K, V]{
+		Cache: New[K, V](),
+	}
+}
+
+// Increment an item of type Number constraint by n.
+// Returns an error if the item was not found or expired. If there is no error, the
+// incremented value is returned.
+func (nc *NumberCache[K, V]) Increment(k K, n V) (val V, err error) {
+	got, err := nc.Cache.GetItem(k)
+	if err != nil {
+		return val, err
+	}
+
+	nv := got.Value + n
+	got.Value = nv
+	nc.Cache.SetItem(k, got)
+
+	return nv, nil
+}
+
+// Decrement an item of type Number constraint by n.
+// Returns an error if the item was not found or expired. If there is no error, the
+// decremented value is returned.
+func (nc *NumberCache[K, V]) Decrement(k K, n V) (val V, err error) {
+	got, err := nc.Cache.GetItem(k)
+	if err != nil {
+		return val, err
+	}
+
+	nv := got.Value - n
+	got.Value = nv
+	nc.Cache.SetItem(k, got)
+
+	return nv, nil
+}

cache_test.go

@@ -0,0 +1,84 @@
+package cache
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestHasExpired(t *testing.T) {
+	cases := []struct {
+		name      string
+		exp       time.Duration
+		createdAt time.Time
+		current   time.Time
+		want      bool
+	}{
+		// expiration == createdAt + exp
+		{
+			name: "item expiration is zero",
+			want: false,
+		},
+		{
+			name:      "item expiration > current time",
+			exp:       time.Hour * 24,
+			createdAt: time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC),
+			current:   time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC),
+			want:      false,
+		},
+		{
+			name:      "item expiration < current time",
+			exp:       time.Hour * 24,
+			createdAt: time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC),
+			current:   time.Date(2009, time.November, 12, 23, 0, 0, 0, time.UTC),
+			want:      true,
+		},
+		{
+			name:      "item expiration == current time",
+			exp:       time.Second,
+			createdAt: time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC),
+			current:   time.Date(2009, time.November, 10, 23, 0, 1, 0, time.UTC),
+			want:      false,
+		},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			backup := nowFunc
+			nowFunc = func() time.Time { return tc.current }
+			defer func() { nowFunc = backup }()
+
+			it := Item[int]{
+				Expiration: tc.exp,
+				CreatedAt:  tc.createdAt,
+			}
+			if got := it.HasExpired(); tc.want != got {
+				t.Fatalf("want %v, but got %v", tc.want, got)
+			}
+		})
+	}
+}
+
+func TestGetItemExpired(t *testing.T) {
+	c := New[struct{}, int]()
+	c.SetItem(struct{}{}, Item[int]{
+		Value:      1,
+		Expiration: time.Hour * 24,
+		CreatedAt:  time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC),
+	})
+
+	backup := nowFunc
+	nowFunc = func() time.Time {
+		return time.Date(2009, time.November, 12, 23, 0, 0, 0, time.UTC)
+	}
+	defer func() { nowFunc = backup }()
+
+	v, err := c.GetItem(struct{}{})
+	if !errors.Is(err, ErrExpired) {
+		t.Errorf("want error %v but got %v", ErrExpired, err)
+	}
+	zeroValItem := Item[int]{}
+	if zeroValItem != v {
+		t.Errorf("want %v but got %v", zeroValItem, v)
+	}
+
+}

constraint.go

@@ -0,0 +1,8 @@
+package cache
+
+import "constraints"
+
+// Number is a constraint that permits any numeric types.
+type Number interface {
+	constraints.Integer | constraints.Float | constraints.Complex
+}