{"id":16932857,"url":"https://github.com/arp242/zcache","last_synced_at":"2025-06-16T03:33:27.676Z","repository":{"id":49337214,"uuid":"283871433","full_name":"arp242/zcache","owner":"arp242","description":"In-memory key:value store/cache (similar to Memcached) library for Go, suitable for single-machine applications","archived":false,"fork":false,"pushed_at":"2024-01-03T15:53:53.000Z","size":222,"stargazers_count":68,"open_issues_count":2,"forks_count":8,"subscribers_count":4,"default_branch":"v2","last_synced_at":"2025-04-01T16:05:11.729Z","etag":null,"topics":["cache","go"],"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/arp242.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":"arp242"}},"created_at":"2020-07-30T20:34:21.000Z","updated_at":"2025-02-26T17:17:01.000Z","dependencies_parsed_at":"2024-06-18T16:49:30.403Z","dependency_job_id":"e05c13de-67fd-453e-83be-191a5d548d0f","html_url":"https://github.com/arp242/zcache","commit_stats":{"total_commits":205,"total_committers":12,"mean_commits":"17.083333333333332","dds":"0.46341463414634143","last_synced_commit":"4b056ab8a9a74bc7f8d7871d8bec9c202738ec0e"},"previous_names":["zgoat/zcache"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/arp242/zcache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arp242%2Fzcache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arp242%2Fzcache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arp242%2Fzcache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arp242%2Fzcache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arp242","download_url":"https://codeload.github.com/arp242/zcache/tar.gz/refs/heads/v2","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arp242%2Fzcache/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260090551,"owners_count":22957245,"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","go"],"created_at":"2024-10-13T20:47:50.297Z","updated_at":"2025-06-16T03:33:27.656Z","avatar_url":"https://github.com/arp242.png","language":"Go","funding_links":["https://github.com/sponsors/arp242"],"categories":[],"sub_categories":[],"readme":"zcache is an in-memory key:value store/cache with time-based evictions.\n\nIt is suitable for applications running on a single machine. It's essentially a\nthread-safe map with expiration times. Any object can be stored, for a given\nduration or forever, and the cache can be safely used by multiple goroutines.\n\nAlthough zcache isn't meant to be used as a persistent datastore, the contents\ncan be saved to and loaded from a file (using `c.Items()` to retrieve the items\nmap to serialize, and `NewFrom()` to create a cache from a deserialized one) to\nrecover from downtime quickly.\n\nThe canonical import path is `zgo.at/zcache/v2`, or `zgo.at/zcache` for the v1.\nReference docs are at https://godocs.io/zgo.at/zcache/v2 and\nhttps://godocs.io/zgo.at/zcache\n\nThis is a fork of https://github.com/patrickmn/go-cache – which no longer seems\nactively maintained. There are two versions of zcache, both of which are\nmaintained:\n\n- v1 is 100% compatible with go-cache and a drop-in replacement with various\n  enhancements.\n- v2 makes various incompatible changes to the API; some functions calls are\n  improved and it uses generics, which requires Go 1.18.\n\n**This README documents v2; see [README.v1.md](/README.v1.md) for the v1\nREADME.** See the \"changes\" section below for a list of changes.\n\nUsage\n-----\nSome examples from `example_test.go`:\n\n```go\nfunc ExampleSimple() {\n\t// Create a cache with a default expiration time of 5 minutes, and which\n\t// purges expired items every 10 minutes.\n\t//\n\t// This creates a cache with string keys and values, with Go 1.18 type\n\t// parameters.\n\tc := zcache.New[string, string](5*time.Minute, 10*time.Minute)\n\n\t// Set the value of the key \"foo\" to \"bar\", with the default expiration.\n\tc.Set(\"foo\", \"bar\")\n\n\t// Set the value of the key \"baz\" to \"never\", with no expiration time. The\n\t// item won't be removed until it's removed with c.Delete(\"baz\").\n\tc.SetWithExpire(\"baz\", \"never\", zcache.NoExpiration)\n\n\t// Get the value associated with the key \"foo\" from the cache; due to the\n\t// use of type parameters this is a string, and no type assertions are\n\t// needed.\n\tfoo, ok := c.Get(\"foo\")\n\tif ok {\n\t\tfmt.Println(foo)\n\t}\n\n\t// Output: bar\n}\n\nfunc ExampleStruct() {\n\ttype MyStruct struct{ Value string }\n\n\t// Create a new cache that stores a specific struct.\n\tc := zcache.New[string, *MyStruct](zcache.NoExpiration, zcache.NoExpiration)\n\tc.Set(\"cache\", \u0026MyStruct{Value: \"value\"})\n\n\tv, _ := c.Get(\"cache\")\n\tfmt.Printf(\"%#v\\n\", v)\n\n\t// Output: \u0026zcache_test.MyStruct{Value:\"value\"}\n}\n\nfunc ExampleAny() {\n\t// Create a new cache that stores any value, behaving similar to zcache v1\n\t// or go-cache.\n\tc := zcache.New[string, any](zcache.NoExpiration, zcache.NoExpiration)\n\n\tc.Set(\"a\", \"value 1\")\n\tc.Set(\"b\", 42)\n\n\ta, _ := c.Get(\"a\")\n\tb, _ := c.Get(\"b\")\n\n\t// This needs type assertions.\n\tp := func(a string, b int) { fmt.Println(a, b) }\n\tp(a.(string), b.(int))\n\n\t// Output: value 1 42\n}\n\nfunc ExampleProxy() {\n\ttype Site struct {\n\t\tID       int\n\t\tHostname string\n\t}\n\n\tsite := \u0026Site{\n\t\tID:       42,\n\t\tHostname: \"example.com\",\n\t}\n\n\t// Create a new site which caches by site ID (int), and a \"proxy\" which\n\t// caches by the hostname (string).\n\tc := zcache.New[int, *Site](zcache.NoExpiration, zcache.NoExpiration)\n\tp := zcache.NewProxy[string, int, *Site](c)\n\n\tp.Set(42, \"example.com\", site)\n\n\tsiteByID, ok := c.Get(42)\n\tfmt.Printf(\"%v %v\\n\", ok, siteByID)\n\n\tsiteByHost, ok := p.Get(\"example.com\")\n\tfmt.Printf(\"%v %v\\n\", ok, siteByHost)\n\n\t// They're both the same object/pointer.\n\tfmt.Printf(\"%v\\n\", siteByID == siteByHost)\n\n\t// Output:\n\t// true \u0026{42 example.com}\n\t// true \u0026{42 example.com}\n\t// true\n}\n```\n\nChanges\n-------\n### Incompatible changes in v2\n- Use type parameters instead of `map[string]interface{}`; you can get the same\n  as before with `zcache.New[string, any](..)`, but if you know you will only\n  store `MyStruct` you can use `zcache.New[string, *MyStruct](..)` for\n  additional type safety.\n\n- Remove `Save()`, `SaveFile()`, `Load()`, `LoadFile()`; you can still persist\n  stuff to disk by using `Items()` and `NewFrom()`. These methods were already\n  deprecated.\n\n- Rename `Set()` to `SetWithExpire()`, and rename `SetDefault()` to `Set()`.\n  Most of the time you want to use the default expiry time, so make that the\n  easier path.\n\n- The `Increment*` and `Decrement*` functions have been removed; you can replace\n  them with `Modify()`:\n\n      cache := New[string, int](DefaultExpiration, 0)\n      cache.Set(\"one\", 1)\n      cache.Modify(\"one\", func(v int) int { return v + 1 })\n\n  The performance of this is roughly the same as the old Increment, and this is\n  a more generic method that can also be used for other things like appending to\n  a slice.\n\n- Rename `Flush()` to `Reset()`; I think that more clearly conveys what it's\n  intended for as `Flush()` is typically used to flush a buffer or the like.\n\n### Compatible changes from go-cache\nAll these changes are in both v1 and v2:\n\n- Add `Keys()` to list all keys.\n- Add `Touch()` to update the expiry on an item.\n- Add `GetStale()` to get items even after they've expired.\n- Add `Pop()` to get an item and delete it.\n- Add `Modify()` to atomically modify existing cache entries (e.g. lists, maps).\n- Add `DeleteAll()` to remove all items from the cache with onEvicted call.\n- Add `DeleteFunc()` to remove specific items from the cache atomically.\n- Add `Rename()` to rename keys, retaining the value and expiry.\n- Add `Proxy` type, to access cache items under a different key.\n- Various small internal and documentation improvements.\n\nSee [issue-list.markdown](/issue-list.markdown) for a complete run-down of the\nPRs/issues for go-cache and what was and wasn't included.\n\nFAQ\n---\n\n### How can I limit the size of the cache? Is there an option for this?\nNot really; zcache is intended as a thread-safe map with time-based eviction.\nThis keeps it nice and simple. Adding something like a LRU eviction mechanism\nnot only makes the code more complex, it also makes the library worse for cases\nwhere you just want a map since it requires additional memory and makes some\noperations more expensive (unless a new API is added which make the API worse\nfor those use cases).\n\nSo unless I or someone else comes up with a way to do this which doesn't detract\nanything from the simple map use case, I'd rather not add it. Perhaps wrapping\n`zcache.Cache` and overriding some methods could work, but I haven't looked at\nit.\n\ntl;dr: this isn't designed to solve every caching use case. That's a feature.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farp242%2Fzcache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farp242%2Fzcache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farp242%2Fzcache/lists"}