{"id":22196668,"url":"https://github.com/parmaster/mcache","last_synced_at":"2025-03-24T22:40:23.094Z","repository":{"id":180136134,"uuid":"664620204","full_name":"parMaster/mcache","owner":"parMaster","description":"Simple, fast, thread-safe in-memory cache with by-key TTL and generic value types","archived":false,"fork":false,"pushed_at":"2024-12-18T13:25:21.000Z","size":207,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-30T02:14:13.741Z","etag":null,"topics":["cache","generics","golang-package","in-memory-caching","memcached","thread-safe","ttl-cache"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parMaster.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-07-10T11:33:08.000Z","updated_at":"2024-12-18T13:25:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"dfe7dc32-7386-434d-aee7-d7bc95ba22c0","html_url":"https://github.com/parMaster/mcache","commit_stats":null,"previous_names":["parmaster/mcache"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parMaster%2Fmcache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parMaster%2Fmcache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parMaster%2Fmcache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parMaster%2Fmcache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parMaster","download_url":"https://codeload.github.com/parMaster/mcache/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245366207,"owners_count":20603438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","generics","golang-package","in-memory-caching","memcached","thread-safe","ttl-cache"],"created_at":"2024-12-02T14:16:01.717Z","updated_at":"2025-03-24T22:40:23.073Z","avatar_url":"https://github.com/parMaster.png","language":"Go","readme":"# mcache [![codecov](https://codecov.io/gh/parMaster/mcache/branch/main/graph/badge.svg?token=K6685ZN3YS)](https://codecov.io/gh/parMaster/mcache) ![GitHub](https://img.shields.io/github/license/parMaster/mcache) [![Go Report Card](https://goreportcard.com/badge/github.com/parMaster/mcache)](https://goreportcard.com/report/github.com/parMaster/mcache) [![Go](https://github.com/parMaster/zoomrs/actions/workflows/go.yml/badge.svg)](https://github.com/parMaster/zoomrs/actions/workflows/go.yml)\n\n`mcache` is a simple, fast, thread-safe in-memory cache library with by-key TTL written in Go.\n\n## Features\n\n- Thread-safe cache operations\n- Set key-value pairs with optional expiration time\n- Get values by key\n- Check if a key exists\n- Delete key-value pairs\n- Clear the entire cache\n- Cleanup expired key-value pairs\n- Generic type support\n\n## Installation\n\nUse `go get` to install the package:\n\n```shell\ngo get github.com/parMaster/mcache\n```\n\n## Usage\n\nImport the `mcache` package in your Go code:\n\n```go\nimport \"github.com/parMaster/mcache\"\n```\n\nCreate a new cache instance using the `NewCache` constructor, and use it to perform cache operations:\n\n```go\ncache := mcache.NewCache[string]()\ndata, err := cache.Get(\"key\")\nif err == nil {\n\treturn data\n}\ndata = ExpensiveFunctionCall()\ncache.Set(\"key\", data, 5*time.Minute) // cache data for 5 minutes\n```\n## Examples\n\nSee the [examples](https://github.com/parMaster/mcache/tree/main/examples) directory for more examples.\n\n## API Reference\n\n### Interface\n\nThe `Cacher` interface is used to define the cache operations:\n```go\ntype Cacher[T any] interface {\n\tSet(key string, value T, ttl time.Duration) bool\n\tGet(key string) (T, error)\n\tHas(key string) (bool, error)\n\tDel(key string) error\n\tCleanup()\n\tClear() error\n}\n```\n\n### Set\n\nSet a key-value pair in the cache. The key must be a `string`, value type defined during cache creation, `ttl` is `time.Duration` type. If `ttl` is 0, the key-value pair will not expire.:\n\n```go\ncache.Set(\"key\", \"value\", time.Duration(0))\n```\n\nIf the key already exists and is not expired, `false` will be returned. If the key exists but is expired, the value will be updated.\n\nYou can also set a key-value pair with an expiration time (in seconds):\n\n```go\ncache.Set(\"key\", \"value\", time.Minute)\n```\n\nThe value will automatically expire after the specified duration.\n\n### Get\n\nRetrieve a value from the cache by key:\n\n```go\nvalue, err := cache.Get(\"key\")\nif err != nil {\n    // handle error\n}\n```\n\nIf the key does not exist, an error `mcache.ErrKeyNotFound` will be returned. If the key exists but is expired, an error `mcache.ErrExpired` will be returned, and the key-value pair will be deleted.\n\nEither error or value could be checked to determine if the key exists. Error is easier to check when the value is a zero value.\n\n### Has\n\nCheck if a key exists in the cache:\n\n```go\nexists, err := cache.Has(\"key\")\nif err != nil {\n    // handle error\n}\n\nif exists {\n    // key exists\n} else {\n    // key does not exist\n}\n```\n\nIf the key exists but is expired, an error `mcache.ErrExpired` will be returned, and the key-value pair will be deleted.\n\n### Delete\n\nDelete a key-value pair from the cache:\n\n```go\nerr := cache.Del(\"key\")\nif err != nil {\n    // handle error\n}\n```\n\n### Clear\n\nClear the entire cache:\n\n```go\nerr := cache.Clear()\nif err != nil {\n    // handle error\n}\n```\n\n### Cleanup\n\nCleanup expired key-value pairs in the cache. You can call this method periodically to remove expired key-value pairs from the cache:\n\n```go\ncache.Cleanup()\n```\n\n`WithCleanup` is a functional option to the `NewCache` constructor that allows you to specify a cleanup interval:\n\n```go\ncache := mcache.NewCache(mcache.WithCleanup[string](time.Minute)) // cleanup every 60 seconds\n```\nIt will basically run a `Cleanup` method in a goroutine with a time interval.\n\n## Tests and Benchmarks\n\n100% test coverage:\n\n```shell\n$ go test -cover -race -cpu 24 .\n\nok      github.com/parMaster/mcache     8.239s  coverage: 100.0% of statements\n```\nBlinding fast and efficient:\n\n```shell\n$ go test -bench . -benchmem\ngoos: darwin\ngoarch: amd64\npkg: github.com/parMaster/mcache\ncpu: Intel(R) Core(TM) i5-5257U CPU @ 2.70GHz\nBenchmarkWrite-4           \t 1811689\t       928.3 ns/op\t     279 B/op\t       2 allocs/op\nBenchmarkRead-4            \t 2925553\t       445.8 ns/op\t      15 B/op\t       1 allocs/op\nBenchmarkRWD-4             \t 1351506\t       881.6 ns/op\t      47 B/op\t       5 allocs/op\nBenchmarkConcurrentRWD-4   \t  452916\t      2766 ns/op\t     195 B/op\t      16 allocs/op\nPASS\nok  \tgithub.com/parMaster/mcache\t19.769s\n```\n\n## Contributing\n\nContributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.\n\n## License\n\nThis project is licensed under the [MIT](https://choosealicense.com/licenses/mit/) license.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparmaster%2Fmcache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparmaster%2Fmcache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparmaster%2Fmcache/lists"}