gozeloglu / cache

LRU-based cache package for Go.

cache

cache is LRU-based cache package written in vanilla Go - with no package dependency. LRU stands for Least Recently Used and it is one of the famous cache replacement algorithm. It replaces newly added data with the least recently used one.

• Written in Vanilla Go, with no dependencies.
• Safe for concurrent use.
• Supports any data type for keys and values.
• Supports time expiration.

Installation

go get github.com/gozeloglu/cache

Example

Here, there is an example usage of the package.

You can import like this.

import "github.com/gozeloglu/cache"

Then, you need to create a cache variable with New() function. It takes one parameter to specify cache capacity.

Add new data

cache.Add("foo", "bar", 0) // Without expiration time
cache.Add("key", "value", time.Hour * 2) // With expiration time

Get data

val, found := cache.Get("foo")
if !found {
    fmt.Println("key does not exist. val is nil.")
}
fmt.Println(val)

Get all keys

keys := cache.Keys()
for _, k := range keys {
    fmt.Println(k)
}

Contains, Peek and Remove

found := cache.Contains("foo")
if found {
    val, _ := cache.Peek("foo")
    cache.Remove("foo")
}

Remove Oldest

k, v, ok := cache.RemoveOldest()
if ok {
    fmt.Printf("Oldest key-value pair removed: %s-%s", k, v)
}

Resize

cache.Resize(20) // Capacity will be 20

Update value, update expiration date, and replace

newItem, err := cache.UpdateVal("foo", "foobar") // Cache data order is also updated
if err != nil {
    fmt.Printf("New item key and value is %s-%s", newItem.Key, newItem.Val)
}
newItem, err := c.UpdateExpirationDate("foo", time.Hour * 4) // Cache data order is also updated
if err != nil {
    fmt.Printf("%v", newItem.Expiration)
}

err = c.Replace("foo", "fuzz")  // Change value of the key without updating cache access order
if err != nil {
	fmt.Printf(err.Error())
}

Testing

You can run the tests with the following command.

go test .

Code Coverage

You can get the code coverage information with the following command:

go test -cover

If you want to generate a graphical coverage report, you can run the following command:

go tool cover -html=coverage.out

A browser tab will be opened and you will be able to see the graphical report. It shows not tracked, not covered, and covered line on the source code.

LICENSE

MIT

cache's Issues

Refactor `cache_test.go`

cache_test.go should be refactored to follow Go-style table-driven test.

Why was it written like that?

I was a newbie in Go while I was implementing this package.

Why is it important?

• In the current version, test files are not maintainable and readable. It is really hard to make changes or add new test cases.
• Go has some conventions like writing tests in a table-driven style. It will be better if the test functions are refactored for welcoming new contributors. Go developers are familiar with test style and it makes the project understandable for them.
• It is hard to detect bugs now.

TODOs

• Convert test functions to table-driven tests.
• Keep test coverage rate.

Resources

• https://dave.cheney.net/2019/05/07/prefer-table-driven-tests
• https://go.dev/blog/subtests
• https://semaphoreci.com/blog/table-driven-unit-tests-go
• https://dev.to/boncheff/table-driven-unit-tests-in-go-407b

Update Go version in workflows

The current Go version is 1.18 but the pipeline version is 1.17. It causes the pipeline failure. It should be updated and synced with the Go version we use in the project.

Acceptance criteria

• We need to update the Go version in .github/workflows/go.yml.

Add Makefile

Makefile can be added to the project. It can have some commands that are used commonly.

• test: Runs go test command.
• race: Runs go test with -race command.
• cover: Runs go test with -cover option.
• cover-out: Runs cover command and produce report.
  • go test -coverprofile=coverage.out ./... go tool cover -html=coverage.out command can be used.

Store in map

Keys and values(as an object) can be stored in a map to access in O(1) time complexity. Also, updates can be done faster.