{"id":49399423,"url":"https://github.com/gozephyr/gencache","last_synced_at":"2026-04-28T17:06:26.664Z","repository":{"id":294030231,"uuid":"979901910","full_name":"gozephyr/gencache","owner":"gozephyr","description":"🔐 Generic caching library for Go | Extensible storage backends | Multiple eviction policies | Memory tracking | TTL support","archived":false,"fork":false,"pushed_at":"2025-12-17T05:36:10.000Z","size":113,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-20T18:59:17.668Z","etag":null,"topics":["cache","eviction-cache","eviction-policy","fifo-cache","file-caching","go","golang","in-memory","in-memory-caching","lfu-cache","lru-cache","metrics"],"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/gozephyr.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-08T08:48:46.000Z","updated_at":"2025-12-17T05:36:07.000Z","dependencies_parsed_at":null,"dependency_job_id":"2433ed41-bfad-466e-948b-1c93e12d4a4b","html_url":"https://github.com/gozephyr/gencache","commit_stats":null,"previous_names":["gozephyr/gencache"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gozephyr/gencache","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gozephyr%2Fgencache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gozephyr%2Fgencache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gozephyr%2Fgencache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gozephyr%2Fgencache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gozephyr","download_url":"https://codeload.github.com/gozephyr/gencache/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gozephyr%2Fgencache/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32390155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T14:34:11.604Z","status":"ssl_error","status_checked_at":"2026-04-28T14:32:37.009Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","eviction-cache","eviction-policy","fifo-cache","file-caching","go","golang","in-memory","in-memory-caching","lfu-cache","lru-cache","metrics"],"created_at":"2026-04-28T17:06:25.887Z","updated_at":"2026-04-28T17:06:26.659Z","avatar_url":"https://github.com/gozephyr.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GenCache\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/gozephyr/gencache)](https://goreportcard.com/report/github.com/gozephyr/gencache)\n[![GoDoc](https://godoc.org/github.com/gozephyr/gencache?status.svg)](https://godoc.org/github.com/gozephyr/gencache)\n[![License](https://img.shields.io/github/license/gozephyr/gencache)](https://github.com/gozephyr/gencache/blob/main/LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-1.18%2B-blue)](https://golang.org)\n[![Build Status](https://github.com/gozephyr/gencache/actions/workflows/ci.yml/badge.svg)](https://github.com/gozephyr/gencache/actions/workflows/ci.yml)\n[![Coverage](https://codecov.io/gh/gozephyr/gencache/branch/main/graph/badge.svg)](https://codecov.io/gh/gozephyr/gencache)\n[![Release](https://img.shields.io/github/v/release/gozephyr/gencache?include_prereleases)](https://github.com/gozephyr/gencache/releases)\n\nA high-performance, generic caching library with support for multiple storage backends, batch operations, compression, and object pooling.\n\n## Summary\n\nGenCache is a robust, thread-safe caching library designed for high-performance applications. It provides a unified interface for caching with support for in-memory and file-based storage, batch operations, compression, and object pooling. Built with Go's generics, it offers type safety and flexibility for various use cases.\n\n## Features\n\n- **Generic Caching**: Type-safe caching with Go generics.\n- **Multiple Storage Backends**:\n  - In-memory store for fastest access.\n  - File-based store for persistence.\n- **Batch Operations**: Efficient bulk processing for high throughput.\n- **Compression Support**: Memory optimization with configurable compression levels.\n- **Object Pooling**: Reduced GC pressure and improved performance.\n- **Unified Metrics and Monitoring**: Track hit/miss rates, memory usage, and operation latencies. See [Metrics Guide](metrics/METRICS.md) for detailed usage.\n- **Resource Coordination and Cleanup**: Automatic cleanup of expired items and resources.\n- **Configurable Components**: Tune cleanup intervals, size limits, and compression settings.\n- **TTL (Time-To-Live) Support**: Automatic expiration of cached items.\n- **Thread-Safe Operations**: Concurrent access without data races.\n\n## Installation\n\n```bash\ngo get github.com/gozephyr/gencache\n```\n\n## Basic Usage\n\n### Memory Store Example\n\n```go\nimport (\n    \"context\"\n    \"time\"\n    \"github.com/gozephyr/gencache\"\n    \"github.com/gozephyr/gencache/store\"\n    \"github.com/gozephyr/gencache/ttl\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    // Create a memory store\n    memStore, err := store.NewMemoryStore[string, string](ctx)\n    if err != nil {\n        // Handle error\n    }\n    defer memStore.Close(ctx)\n\n    // Create a cache with memory store\n    cache := gencache.New[string, string](\n        gencache.WithStore[string, string](memStore),\n        gencache.WithTTLConfig[string, string](ttl.DefaultConfig()),\n    )\n    defer cache.Close()\n\n    // Set and get values\n    err = cache.Set(\"key\", \"value\", time.Minute)\n    if err != nil {\n        // Handle error\n    }\n\n    value, err := cache.Get(\"key\")\n    if err != nil {\n        // Handle error\n    }\n}\n```\n\n### Memory Store Capabilities\n\n- Fastest access with in-memory storage.\n- Configurable size limits.\n- Automatic cleanup of expired items.\n- Thread-safe operations.\n- Memory usage tracking.\n\n### Memory Store Performance\n\n1. **Memory Usage**:\n   - Proportional to number of items.\n   - Each item stores key, value, and metadata.\n   - Overhead: ~100 bytes per item.\n\n2. **CPU Usage**:\n   - Minimal overhead for operations.\n   - Fast access and updates.\n   - Efficient cleanup of expired items.\n\n### File Store\n\n```go\nimport (\n    \"context\"\n    \"time\"\n    \"github.com/gozephyr/gencache\"\n    \"github.com/gozephyr/gencache/store\"\n    \"github.com/gozephyr/gencache/ttl\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    // Create a file store\n    fileStore, err := store.NewFileStore[string, string](ctx, \u0026store.FileConfig{\n        Directory:          \"/tmp/cache\",\n        FileExtension:      \".cache\",\n        CompressionEnabled: true,\n        CompressionLevel:   6,\n        CleanupInterval:    time.Hour,\n    })\n    if err != nil {\n        // Handle error\n    }\n    defer fileStore.Close(ctx)\n\n    // Create a cache with file store\n    cache := gencache.New[string, string](\n        gencache.WithStore[string, string](fileStore),\n        gencache.WithTTLConfig[string, string](ttl.DefaultConfig()),\n    )\n    defer cache.Close()\n\n    // Set and get values\n    err = cache.Set(\"key\", \"value\", time.Minute)\n    if err != nil {\n        // Handle error\n    }\n\n    value, err := cache.Get(\"key\")\n    if err != nil {\n        // Handle error\n    }\n}\n```\n\n## Advanced Features\n\n### Batch Operations\n\n```go\nimport (\n    \"context\"\n    \"time\"\n    \"github.com/gozephyr/gencache\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    // Create a cache with batch operations\n    cache := gencache.New[string, string](\n        gencache.WithBatchConfig[string, string](gencache.BatchConfig{\n            MaxBatchSize:     1000,\n            OperationTimeout: 5 * time.Second,\n            MaxConcurrent:    10,\n        }),\n    )\n    defer cache.Close()\n\n    // Create batch cache\n    batchCache := gencache.NewBatchCache(cache, gencache.DefaultBatchConfig())\n\n    // Batch get operation\n    values := batchCache.GetMany(ctx, []string{\"key1\", \"key2\", \"key3\"})\n\n    // Batch set operation\n    err := batchCache.SetMany(ctx, map[string]string{\n        \"key1\": \"value1\",\n        \"key2\": \"value2\",\n        \"key3\": \"value3\",\n    }, time.Minute)\n    if err != nil {\n        // Handle error\n    }\n}\n```\n\n### Object Pooling\n\n```go\nimport (\n    \"context\"\n    \"time\"\n    \"github.com/gozephyr/gencache\"\n)\n\ntype MyStruct struct {\n    ID   int\n    Name string\n}\n\nfunc main() {\n    ctx := context.Background()\n\n    // Create a cache with object pooling\n    cache := gencache.New[string, *MyStruct](\n        gencache.WithPoolConfig[string, *MyStruct](gencache.PoolConfig{\n            MaxSize:       1000,\n            MinSize:       10,\n            CleanupPeriod: 5 * time.Minute,\n            MaxIdleTime:   10 * time.Minute,\n        }),\n    )\n    defer cache.Close()\n\n    // Create pooled cache\n    pooledCache := gencache.NewPooledCache(cache, gencache.DefaultPoolConfig())\n\n    // Use pooled objects\n    obj := \u0026MyStruct{ID: 1, Name: \"test\"}\n    err := pooledCache.Set(\"key\", obj, time.Minute)\n    if err != nil {\n        // Handle error\n    }\n\n    value, err := pooledCache.Get(\"key\")\n    if err != nil {\n        // Handle error\n    }\n}\n```\n\n## Storage Backends\n\n### Memory Store\n\n- Fastest access with in-memory storage.\n- Configurable size limits.\n- Automatic cleanup of expired items.\n- Thread-safe operations.\n- Memory usage tracking.\n\n### File Store Overview\n\n- Persistent storage using filesystem.\n- Configurable directory and file extension.\n- Automatic cleanup of expired files.\n- Compression support.\n- Thread-safe operations.\n- File-based locking.\n\n## Performance Considerations\n\n### Memory Store Metrics\n\n1. **Memory Usage**:\n   - Proportional to number of items.\n   - Each item stores key, value, and metadata.\n   - Overhead: ~100 bytes per item.\n\n2. **CPU Usage**:\n   - Minimal overhead for operations.\n   - Fast access and updates.\n   - Efficient cleanup of expired items.\n\n### File Store Performance\n\n1. **Memory Usage**:\n   - Minimal memory overhead.\n   - Values stored on disk.\n   - Memory usage for file handles and buffers.\n\n2. **CPU Usage**:\n   - File I/O operations.\n   - Compression/decompression overhead.\n   - Periodic cleanup of expired files.\n\n3. **Disk Usage**:\n   - Proportional to stored data size.\n   - Additional space for metadata.\n   - Compression can reduce disk usage.\n\n## Benchmarks\n\n- **Memory Store**: ~100,000 operations per second for small values.\n- **File Store**: ~10,000 operations per second for small values, depending on disk speed and compression settings.\n\n## Best Practices\n\n1. **Storage Selection**:\n   - Use memory store for fastest access.\n   - Use file store for persistence.\n   - Consider data size and access patterns.\n\n2. **Configuration**:\n   - Tune cleanup intervals.\n   - Set appropriate size limits.\n   - Configure compression settings.\n\n3. **Error Handling**:\n   - Handle storage errors.\n   - Implement retry logic.\n   - Monitor error rates.\n\n4. **Monitoring**:\n   - Track hit/miss rates.\n   - Monitor memory usage.\n   - Watch disk usage (file store).\n   - Track operation latencies.\n\n## Error Handling\n\nThe library provides comprehensive error handling:\n\n```go\nif err := cache.Set(\"key\", \"value\", time.Minute); err != nil {\n    switch {\n    case errors.Is(err, errors.ErrKeyNotFound):\n        // Handle key not found\n    case errors.Is(err, errors.ErrCapacityLimit):\n        // Handle capacity limit\n    case errors.Is(err, errors.ErrContextCanceled):\n        // Handle context cancellation\n    default:\n        // Handle other errors\n    }\n}\n```\n\n## Metrics Example\n\nFor detailed metrics usage and examples, please refer to the [Metrics Guide](metrics/METRICS.md).\n\n## Eviction Policies\n\nGenCache supports pluggable cache eviction policies via the `policy` package. You can choose from several built-in policies:\n\n- **LRU (Least Recently Used)**: Evicts the least recently accessed items first.\n- **LFU (Least Frequently Used)**: Evicts the least frequently accessed items first.\n- **FIFO (First In First Out)**: Evicts the oldest items first.\n\n### Policy Package\n\nThe `policy` package provides a flexible framework for implementing custom cache eviction policies. It defines a generic `Policy` interface that can be implemented for any key-value type combination.\n\n#### Policy Interface\n\n```go\ntype Policy[K comparable, V any] interface {\n    // OnGet is called when an item is retrieved from the cache\n    OnGet(key K, value V)\n\n    // OnSet is called when an item is added to the cache\n    OnSet(key K, value V, ttl time.Duration)\n\n    // OnDelete is called when an item is removed from the cache\n    OnDelete(key K)\n\n    // OnClear is called when the cache is cleared\n    OnClear()\n\n    // Evict returns the next key to be evicted from the cache\n    Evict() (K, bool)\n\n    // Size returns the number of items in the policy\n    Size() int\n\n    // Capacity returns the maximum number of items the policy can hold\n    Capacity() int\n}\n```\n\n#### Entry Metadata\n\nEach cache entry maintains metadata to help with policy decisions:\n\n```go\ntype Entry[V any] struct {\n    Value       V         // The cached value\n    Expires     time.Time // When the entry expires\n    CreatedAt   time.Time // When the entry was created\n    LastAccess  time.Time // When the entry was last accessed\n    AccessCount int64     // Number of times the entry was accessed\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgozephyr%2Fgencache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgozephyr%2Fgencache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgozephyr%2Fgencache/lists"}