refactor!: eliminate global state and improve architecture

BREAKING CHANGES:
- Move errors package to sentinel with enhanced documentation
- Add context parameter to Get, GetWithInfo, and Count methods
- Change GetMultiple return signature for consistency

Features:
- Extract configuration constants to internal/constants package
- Replace serializer and stats collector global registries with dependency injection
- Add ItemPoolManager for thread-safe memory pool management
- Implement lazy initialization patterns to avoid package-level globals

Performance:
- Replace encoding/json with faster goccy/go-json
- Use slices.Sort instead of sort.Slice for better performance
- Optimize item size calculation with local buffers

Quality:
- Enhance error handling with ewrap throughout codebase
- Add comprehensive documentation to sentinel package
- Improve worker pool error handling
- Standardize interface organization with crud separation

This refactoring eliminates all global variables and init() functions,
improving testability, thread safety, and following Go best practices
while maintaining backward compatibility where possible.

Author: hyp3rd

.golangci.yaml

@@ -99,6 +99,12 @@ linters:
       # Default: 1
       tab-width: 1
 
+    mnd:
+      ignored-numbers:
+        - "0666"
+        - "0755"
+        - "2"
+
     ireturn:
       # ireturn does not allow using `allow` and `reject` settings at the same time.
       # Both settings are lists of the keywords and regular expressions matched to interface or package names.
@@ -174,6 +180,7 @@ linters:
         - r *http.Request
         - w http.ResponseWriter
         - T any
+        - T backend.IBackendConstrain
         - m map[string]int
 
   # Enable only fast linters from enabled linters set (first run won't be fast)

Makefile

@@ -10,6 +10,10 @@ GITVERSION_NOT_INSTALLED = "gitversion is not installed: https://github.com/GitT
 test:
 	go test -v -timeout 5m -cover ./...
 
+# bench runs the benchmark tests in the benchmark subpackage of the tests package.
+bench:
+	cd tests/benchmark && go test -bench=. -benchmem -benchtime=4s . -timeout 30m
+
 benchmark:
 	go test -bench=. -benchmem ./pkg/ewrap
 	go test -bench=Benchmark -benchmem ./test
@@ -87,4 +91,4 @@ help:
 	@echo
 	@echo "For more information, see the project README."
 
-.PHONY: prepare-toolchain test benchmark update-deps lint help
+.PHONY: prepare-toolchain test bench update-deps lint help

README.md

@@ -103,7 +103,7 @@ config.InMemoryOptions = []backend.Option[backend.InMemory]{
 // Create a new HyperCache with a capacity of 10
 cache, err := hypercache.New(config)
 if err != nil {
-    fmt.Println(err)
+    fmt.Fprintln(os.Stderr, err)
     return
 }
 ```

backend/backend.go

@@ -15,15 +15,15 @@ type IBackendConstrain interface {
 type IBackend[T IBackendConstrain] interface {
 	// Get retrieves the item with the given key from the cache.
 	// If the key is not found in the cache, it returns nil.
-	Get(key string) (item *types.Item, ok bool)
+	Get(ctx context.Context, key string) (item *types.Item, ok bool)
 	// Set adds a new item to the cache.
-	Set(item *types.Item) error
+	Set(ctx context.Context, item *types.Item) error
 	// Capacity returns the maximum number of items that can be stored in the cache.
 	Capacity() int
 	// SetCapacity sets the maximum number of items that can be stored in the cache.
 	SetCapacity(capacity int)
 	// Count returns the number of items currently stored in the cache.
-	Count() int
+	Count(ctx context.Context) int
 	// Remove deletes the item with the given key from the cache.
 	Remove(ctx context.Context, keys ...string) error
 	// List the items in the cache that meet the specified criteria.

backend/filters.go

@@ -54,7 +54,7 @@ func WithFilterFunc(fn func(item *types.Item) bool) IFilter {
 }
 
 // ApplyFilter applies the sort by filter to the given list of items.
-func (f sortByFilter) ApplyFilter(backendType string, items []*types.Item) ([]*types.Item, error) {
+func (f sortByFilter) ApplyFilter(_ string, items []*types.Item) ([]*types.Item, error) {
 	var sorter *itemSorter
 
 	switch f.field {
@@ -96,7 +96,7 @@ func (f sortByFilter) ApplyFilter(backendType string, items []*types.Item) ([]*t
 }
 
 // ApplyFilter applies the sort order filter to the given list of items.
-func (f SortOrderFilter) ApplyFilter(backendType string, items []*types.Item) ([]*types.Item, error) {
+func (f SortOrderFilter) ApplyFilter(_ string, items []*types.Item) ([]*types.Item, error) {
 	if !f.ascending {
 		for i, j := 0, len(items)-1; i < j; i, j = i+1, j-1 {
 			items[i], items[j] = items[j], items[i]
@@ -107,7 +107,7 @@ func (f SortOrderFilter) ApplyFilter(backendType string, items []*types.Item) ([
 }
 
 // ApplyFilter applies the filter function to the given list of items.
-func (f filterFunc) ApplyFilter(backendType string, items []*types.Item) ([]*types.Item, error) {
+func (f filterFunc) ApplyFilter(_ string, items []*types.Item) ([]*types.Item, error) {
 	filteredItems := make([]*types.Item, 0)
 
 	for _, item := range items {

backend/inmemory.go

@@ -4,29 +4,32 @@ import (
 	"context"
 	"sync"
 
-	datastructure "github.com/hyp3rd/hypercache/cache/v4"
-	"github.com/hyp3rd/hypercache/errors"
+	cache "github.com/hyp3rd/hypercache/cache/v4"
+	"github.com/hyp3rd/hypercache/internal/constants"
+	"github.com/hyp3rd/hypercache/sentinel"
 	"github.com/hyp3rd/hypercache/types"
 )
 
 // InMemory is a cache backend that stores the items in memory, leveraging a custom `ConcurrentMap`.
 type InMemory struct {
 	sync.RWMutex // mutex to protect the cache from concurrent access
 
-	items    datastructure.ConcurrentMap // map to store the items in the cache
-	capacity int                         // capacity of the cache, limits the number of items that can be stored in the cache
+	items           cache.ConcurrentMap    // map to store the items in the cache
+	itemPoolManager *types.ItemPoolManager // item pool manager to manage the item pool
+	capacity        int                    // capacity of the cache, limits the number of items that can be stored in the cache
 }
 
 // NewInMemory creates a new in-memory cache with the given options.
-func NewInMemory(opts ...Option[InMemory]) (backend IBackend[InMemory], err error) {
+func NewInMemory(opts ...Option[InMemory]) (IBackend[InMemory], error) {
 	InMemory := &InMemory{
-		items: datastructure.New(),
+		items:           cache.New(),
+		itemPoolManager: types.NewItemPoolManager(),
 	}
 	// Apply the backend options
 	ApplyOptions(InMemory, opts...)
 	// Check if the `capacity` is valid
 	if InMemory.capacity < 0 {
-		return nil, errors.ErrInvalidCapacity
+		return nil, sentinel.ErrInvalidCapacity
 	}
 
 	return InMemory, nil
@@ -47,13 +50,13 @@ func (cacheBackend *InMemory) Capacity() int {
 }
 
 // Count returns the number of items in the cache.
-func (cacheBackend *InMemory) Count() int {
+func (cacheBackend *InMemory) Count(_ context.Context) int {
 	return cacheBackend.items.Count()
 }
 
 // Get retrieves the item with the given key from the cacheBackend. If the item is not found, it returns nil.
-func (cacheBackend *InMemory) Get(key string) (item *types.Item, ok bool) {
-	item, ok = cacheBackend.items.Get(key)
+func (cacheBackend *InMemory) Get(_ context.Context, key string) (*types.Item, bool) {
+	item, ok := cacheBackend.items.Get(key)
 	if !ok {
 		return nil, false
 	}
@@ -62,11 +65,11 @@ func (cacheBackend *InMemory) Get(key string) (item *types.Item, ok bool) {
 }
 
 // Set adds a Item to the cache.
-func (cacheBackend *InMemory) Set(item *types.Item) error {
+func (cacheBackend *InMemory) Set(_ context.Context, item *types.Item) error {
 	// Check for invalid key, value, or duration
 	err := item.Valid()
 	if err != nil {
-		types.ItemPool.Put(item)
+		cacheBackend.itemPoolManager.Put(item)
 
 		return err
 	}
@@ -80,30 +83,35 @@ func (cacheBackend *InMemory) Set(item *types.Item) error {
 }
 
 // List returns a list of all items in the cache filtered and ordered by the given options.
-func (cacheBackend *InMemory) List(ctx context.Context, filters ...IFilter) (items []*types.Item, err error) {
+func (cacheBackend *InMemory) List(_ context.Context, filters ...IFilter) ([]*types.Item, error) {
 	// Apply the filters
 	cacheBackend.RLock()
 	defer cacheBackend.RUnlock()
 
-	items = make([]*types.Item, 0, cacheBackend.items.Count())
+	var err error
+
+	items := make([]*types.Item, 0, cacheBackend.items.Count())
 
 	for item := range cacheBackend.items.IterBuffered() {
-		copy := item
-		items = append(items, &copy.Val)
+		cloned := item
+		items = append(items, &cloned.Val)
 	}
 
 	// Apply the filters
 	if len(filters) > 0 {
 		for _, filter := range filters {
-			items, err = filter.ApplyFilter("in-memory", items)
+			items, err = filter.ApplyFilter(constants.InMemoryBackend, items)
+			if err != nil {
+				return nil, err
+			}
 		}
 	}
 
-	return items, err
+	return items, nil
 }
 
 // Remove removes items with the given key from the cacheBackend. If an item is not found, it does nothing.
-func (cacheBackend *InMemory) Remove(ctx context.Context, keys ...string) (err error) {
+func (cacheBackend *InMemory) Remove(ctx context.Context, keys ...string) error {
 	done := make(chan struct{})
 
 	go func() {
@@ -118,7 +126,7 @@ func (cacheBackend *InMemory) Remove(ctx context.Context, keys ...string) (err e
 	case <-done:
 		return nil
 	case <-ctx.Done():
-		return errors.ErrTimeoutOrCanceled
+		return sentinel.ErrTimeoutOrCanceled
 	}
 }
 
@@ -136,6 +144,6 @@ func (cacheBackend *InMemory) Clear(ctx context.Context) error {
 	case <-done:
 		return nil
 	case <-ctx.Done():
-		return errors.ErrTimeoutOrCanceled
+		return sentinel.ErrTimeoutOrCanceled
 	}
 }