refactor: restructure cache types into pkg/cache package

Move cache-related types and utilities from scattered locations into a
centralized pkg/cache package structure following Go package conventions.

Package changes:
- Move types/item.go to pkg/cache/item.go
- Move cache/cmap.go to pkg/cache/cmap.go
- Move cache/v4/cmap.go to pkg/cache/v4/cmap.go

Type updates:
- types.Item → cache.Item
- types.ItemPoolManager → cache.ItemPoolManager
- Update all imports and references throughout codebase

This reorganization improves package clarity by grouping all cache-related
types under a single, well-defined package hierarchy. The pkg/ directory
follows Go conventions for reusable packages, while maintaining all
existing functionality and APIs.

Affected components: backends, eviction algorithms, middleware, examples,
and tests - all updated to use the new package structure.

Author: hyp3rd

backend/backend.go

@@ -3,7 +3,7 @@ package backend
 import (
 	"context"
 
-	"github.com/hyp3rd/hypercache/types"
+	"github.com/hyp3rd/hypercache/pkg/cache"
 )
 
 // IBackendConstrain is the interface that defines the constrain type implemented by cache backends.
@@ -15,9 +15,9 @@ 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(ctx context.Context, key string) (item *types.Item, ok bool)
+	Get(ctx context.Context, key string) (item *cache.Item, ok bool)
 	// Set adds a new item to the cache.
-	Set(ctx context.Context, item *types.Item) error
+	Set(ctx context.Context, item *cache.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.
@@ -27,7 +27,7 @@ type IBackend[T IBackendConstrain] interface {
 	// 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.
-	List(ctx context.Context, filters ...IFilter) (items []*types.Item, err error)
+	List(ctx context.Context, filters ...IFilter) (items []*cache.Item, err error)
 	// Clear removes all items from the cache.
 	Clear(ctx context.Context) error
 }

backend/filters.go

@@ -5,13 +5,14 @@ import (
 
 	"github.com/hyp3rd/ewrap"
 
+	"github.com/hyp3rd/hypercache/pkg/cache"
 	"github.com/hyp3rd/hypercache/types"
 )
 
 // itemSorter is a custom sorter for the items.
 type itemSorter struct {
-	items []*types.Item
-	less  func(i, j *types.Item) bool
+	items []*cache.Item
+	less  func(i, j *cache.Item) bool
 }
 
 func (s *itemSorter) Len() int           { return len(s.items) }
@@ -20,7 +21,7 @@ func (s *itemSorter) Less(i, j int) bool { return s.less(s.items[i], s.items[j])
 
 // IFilter is a backend agnostic interface for a filter that can be applied to a list of items.
 type IFilter interface {
-	ApplyFilter(backendType string, items []*types.Item) ([]*types.Item, error)
+	ApplyFilter(backendType string, items []*cache.Item) ([]*cache.Item, error)
 }
 
 // sortByFilter is a filter that sorts the items by a given field.
@@ -35,7 +36,7 @@ type SortOrderFilter struct {
 
 // filterFunc is a filter that filters the items by a given field's value.
 type filterFunc struct {
-	fn func(item *types.Item) bool
+	fn func(item *cache.Item) bool
 }
 
 // WithSortBy returns a filter that sorts the items by a given field.
@@ -49,40 +50,40 @@ func WithSortOrderAsc(ascending bool) SortOrderFilter {
 }
 
 // WithFilterFunc returns a filter that filters the items by a given field's value.
-func WithFilterFunc(fn func(item *types.Item) bool) IFilter {
+func WithFilterFunc(fn func(item *cache.Item) bool) IFilter {
 	return filterFunc{fn: fn}
 }
 
 // ApplyFilter applies the sort by filter to the given list of items.
-func (f sortByFilter) ApplyFilter(_ string, items []*types.Item) ([]*types.Item, error) {
+func (f sortByFilter) ApplyFilter(_ string, items []*cache.Item) ([]*cache.Item, error) {
 	var sorter *itemSorter
 
 	switch f.field {
 	case types.SortByKey.String():
 		sorter = &itemSorter{
 			items: items,
-			less: func(i, j *types.Item) bool {
+			less: func(i, j *cache.Item) bool {
 				return i.Key < j.Key
 			},
 		}
 	case types.SortByLastAccess.String():
 		sorter = &itemSorter{
 			items: items,
-			less: func(i, j *types.Item) bool {
+			less: func(i, j *cache.Item) bool {
 				return i.LastAccess.UnixNano() < j.LastAccess.UnixNano()
 			},
 		}
 	case types.SortByAccessCount.String():
 		sorter = &itemSorter{
 			items: items,
-			less: func(i, j *types.Item) bool {
+			less: func(i, j *cache.Item) bool {
 				return i.AccessCount < j.AccessCount
 			},
 		}
 	case types.SortByExpiration.String():
 		sorter = &itemSorter{
 			items: items,
-			less: func(i, j *types.Item) bool {
+			less: func(i, j *cache.Item) bool {
 				return i.Expiration < j.Expiration
 			},
 		}
@@ -96,7 +97,7 @@ func (f sortByFilter) ApplyFilter(_ string, items []*types.Item) ([]*types.Item,
 }
 
 // ApplyFilter applies the sort order filter to the given list of items.
-func (f SortOrderFilter) ApplyFilter(_ string, items []*types.Item) ([]*types.Item, error) {
+func (f SortOrderFilter) ApplyFilter(_ string, items []*cache.Item) ([]*cache.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,8 +108,8 @@ func (f SortOrderFilter) ApplyFilter(_ string, items []*types.Item) ([]*types.It
 }
 
 // ApplyFilter applies the filter function to the given list of items.
-func (f filterFunc) ApplyFilter(_ string, items []*types.Item) ([]*types.Item, error) {
-	filteredItems := make([]*types.Item, 0)
+func (f filterFunc) ApplyFilter(_ string, items []*cache.Item) ([]*cache.Item, error) {
+	filteredItems := make([]*cache.Item, 0)
 
 	for _, item := range items {
 		if f.fn(item) {

backend/inmemory.go

@@ -4,26 +4,26 @@ import (
 	"context"
 	"sync"
 
-	cache "github.com/hyp3rd/hypercache/cache/v4"
 	"github.com/hyp3rd/hypercache/internal/constants"
 	"github.com/hyp3rd/hypercache/internal/sentinel"
-	"github.com/hyp3rd/hypercache/types"
+	"github.com/hyp3rd/hypercache/pkg/cache"
+	cachev4 "github.com/hyp3rd/hypercache/pkg/cache/v4"
 )
 
 // 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           cache.ConcurrentMap    // map to store the items in the cache
-	itemPoolManager *types.ItemPoolManager // item pool manager to manage the item pool
+	items           cachev4.ConcurrentMap  // map to store the items in the cache
+	itemPoolManager *cache.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]) (IBackend[InMemory], error) {
 	InMemory := &InMemory{
-		items:           cache.New(),
-		itemPoolManager: types.NewItemPoolManager(),
+		items:           cachev4.New(),
+		itemPoolManager: cache.NewItemPoolManager(),
 	}
 	// Apply the backend options
 	ApplyOptions(InMemory, opts...)
@@ -55,7 +55,7 @@ func (cacheBackend *InMemory) Count(_ context.Context) int {
 }
 
 // Get retrieves the item with the given key from the cacheBackend. If the item is not found, it returns nil.
-func (cacheBackend *InMemory) Get(_ context.Context, key string) (*types.Item, bool) {
+func (cacheBackend *InMemory) Get(_ context.Context, key string) (*cache.Item, bool) {
 	item, ok := cacheBackend.items.Get(key)
 	if !ok {
 		return nil, false
@@ -65,7 +65,7 @@ func (cacheBackend *InMemory) Get(_ context.Context, key string) (*types.Item, b
 }
 
 // Set adds a Item to the cache.
-func (cacheBackend *InMemory) Set(_ context.Context, item *types.Item) error {
+func (cacheBackend *InMemory) Set(_ context.Context, item *cache.Item) error {
 	// Check for invalid key, value, or duration
 	err := item.Valid()
 	if err != nil {
@@ -83,14 +83,14 @@ func (cacheBackend *InMemory) Set(_ context.Context, 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(_ context.Context, filters ...IFilter) ([]*types.Item, error) {
+func (cacheBackend *InMemory) List(_ context.Context, filters ...IFilter) ([]*cache.Item, error) {
 	// Apply the filters
 	cacheBackend.RLock()
 	defer cacheBackend.RUnlock()
 
 	var err error
 
-	items := make([]*types.Item, 0, cacheBackend.items.Count())
+	items := make([]*cache.Item, 0, cacheBackend.items.Count())
 
 	for item := range cacheBackend.items.IterBuffered() {
 		cloned := item

backend/redis.go

@@ -12,7 +12,7 @@ import (
 	"github.com/hyp3rd/hypercache/internal/constants"
 	"github.com/hyp3rd/hypercache/internal/sentinel"
 	"github.com/hyp3rd/hypercache/libs/serializer"
-	"github.com/hyp3rd/hypercache/types"
+	"github.com/hyp3rd/hypercache/pkg/cache"
 )
 
 const (
@@ -24,15 +24,15 @@ const (
 type Redis struct {
 	rdb             *redis.Client          // redis client to interact with the redis server
 	capacity        int                    // capacity of the cache, limits the number of items that can be stored in the cache
-	itemPoolManager *types.ItemPoolManager // itemPoolManager is used to manage the item pool for memory efficiency
+	itemPoolManager *cache.ItemPoolManager // itemPoolManager is used to manage the item pool for memory efficiency
 	keysSetName     string                 // keysSetName is the name of the set that holds the keys of the items in the cache
 	Serializer      serializer.ISerializer // Serializer is the serializer used to serialize the items before storing them in the cache
 }
 
 // NewRedis creates a new redis cache with the given options.
 func NewRedis(redisOptions ...Option[Redis]) (IBackend[Redis], error) {
 	rb := &Redis{
-		itemPoolManager: types.NewItemPoolManager(),
+		itemPoolManager: cache.NewItemPoolManager(),
 	}
 	// Apply the backend options
 	ApplyOptions(rb, redisOptions...)
@@ -89,7 +89,7 @@ func (cacheBackend *Redis) Count(ctx context.Context) int {
 }
 
 // Get retrieves the Item with the given key from the cacheBackend. If the item is not found, it returns nil.
-func (cacheBackend *Redis) Get(ctx context.Context, key string) (*types.Item, bool) {
+func (cacheBackend *Redis) Get(ctx context.Context, key string) (*cache.Item, bool) {
 	// Check if the key is in the set of keys
 	isMember, err := cacheBackend.rdb.SIsMember(ctx, cacheBackend.keysSetName, key).Result()
 	if err != nil {
@@ -124,7 +124,7 @@ func (cacheBackend *Redis) Get(ctx context.Context, key string) (*types.Item, bo
 }
 
 // Set stores the Item in the cacheBackend.
-func (cacheBackend *Redis) Set(ctx context.Context, item *types.Item) error {
+func (cacheBackend *Redis) Set(ctx context.Context, item *cache.Item) error {
 	pipe := cacheBackend.rdb.TxPipeline()
 
 	// Check if the item is valid
@@ -167,7 +167,7 @@ func (cacheBackend *Redis) Set(ctx context.Context, item *types.Item) error {
 }
 
 // List returns a list of all the items in the cacheBackend that match the given filter options.
-func (cacheBackend *Redis) List(ctx context.Context, filters ...IFilter) ([]*types.Item, error) {
+func (cacheBackend *Redis) List(ctx context.Context, filters ...IFilter) ([]*cache.Item, error) {
 	// Get the set of keys held in the cacheBackend with the given `keysSetName`
 	keys, err := cacheBackend.rdb.SMembers(ctx, cacheBackend.keysSetName).Result()
 	if err != nil {
@@ -188,7 +188,7 @@ func (cacheBackend *Redis) List(ctx context.Context, filters ...IFilter) ([]*typ
 	}
 
 	// Create a slice to hold the items
-	items := make([]*types.Item, 0, len(keys))
+	items := make([]*cache.Item, 0, len(keys))
 
 	// Deserialize the items and add them to the slice of items to return
 	for _, cmd := range cmds {

cspell.config.yaml

@@ -6,6 +6,7 @@ words:
   - benchmem
   - benchtime
   - cacheerrors
+  - cachev
   - CAWOLFU
   - Cbor
   - chans
@@ -50,6 +51,7 @@ words:
   - staticcheck
   - stdlib
   - strfnv
+  - ugorji
   - varnamelen
   - wrapcheck
   - Wrapf

eviction/arc.go

@@ -10,15 +10,15 @@ import (
 	"sync"
 
 	"github.com/hyp3rd/hypercache/internal/sentinel"
-	"github.com/hyp3rd/hypercache/types"
+	"github.com/hyp3rd/hypercache/pkg/cache"
 )
 
 // ARC is an in-memory cache that uses the Adaptive Replacement Cache (ARC) algorithm to manage its items.
 type ARC struct {
-	itemPoolManager *types.ItemPoolManager // itemPoolManager is used to manage the item pool for memory efficiency
+	itemPoolManager *cache.ItemPoolManager // itemPoolManager is used to manage the item pool for memory efficiency
 	capacity        int                    // capacity is the maximum number of items that can be stored in the cache
-	t1              map[string]*types.Item // t1 is a list of items that have been accessed recently
-	t2              map[string]*types.Item // t2 is a list of items that have been accessed less recently
+	t1              map[string]*cache.Item // t1 is a list of items that have been accessed recently
+	t2              map[string]*cache.Item // t2 is a list of items that have been accessed less recently
 	b1              map[string]bool        // b1 is a list of items that have been evicted from t1
 	b2              map[string]bool        // b2 is a list of items that have been evicted from t2
 	p               int                    // p is the promotion threshold
@@ -34,10 +34,10 @@ func NewARCAlgorithm(capacity int) (*ARC, error) {
 	}
 
 	return &ARC{
-		itemPoolManager: types.NewItemPoolManager(),
+		itemPoolManager: cache.NewItemPoolManager(),
 		capacity:        capacity,
-		t1:              make(map[string]*types.Item, capacity),
-		t2:              make(map[string]*types.Item, capacity),
+		t1:              make(map[string]*cache.Item, capacity),
+		t2:              make(map[string]*cache.Item, capacity),
 		b1:              make(map[string]bool, capacity),
 		b2:              make(map[string]bool, capacity),
 		p:               0,

eviction/cawolfu.go

@@ -5,8 +5,8 @@ package eviction
 import (
 	"sync"
 
-	"github.com/hyp3rd/hypercache/cache"
 	"github.com/hyp3rd/hypercache/internal/sentinel"
+	"github.com/hyp3rd/hypercache/pkg/cache"
 )
 
 // CAWOLFU is an eviction algorithm that uses the Cache-Aware Write-Optimized LFU (CAWOLFU) policy to select items for eviction.

eviction/clock.go

@@ -10,13 +10,13 @@ import (
 	"sync"
 
 	"github.com/hyp3rd/hypercache/internal/sentinel"
-	"github.com/hyp3rd/hypercache/types"
+	"github.com/hyp3rd/hypercache/pkg/cache"
 )
 
 // ClockAlgorithm is an in-memory cache with the Clock algorithm.
 type ClockAlgorithm struct {
-	items           []*types.Item
-	itemPoolManager *types.ItemPoolManager
+	items           []*cache.Item
+	itemPoolManager *cache.ItemPoolManager
 	keys            map[string]int
 	mutex           sync.RWMutex
 	evictMutex      sync.Mutex
@@ -31,8 +31,8 @@ func NewClockAlgorithm(capacity int) (*ClockAlgorithm, error) {
 	}
 
 	return &ClockAlgorithm{
-		items:           make([]*types.Item, capacity),
-		itemPoolManager: types.NewItemPoolManager(),
+		items:           make([]*cache.Item, capacity),
+		itemPoolManager: cache.NewItemPoolManager(),
 		keys:            make(map[string]int, capacity),
 		capacity:        capacity,
 		hand:            0,

examples/list/list.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/hyp3rd/hypercache"
 	"github.com/hyp3rd/hypercache/backend"
+	"github.com/hyp3rd/hypercache/pkg/cache"
 	"github.com/hyp3rd/hypercache/types"
 )
 
@@ -47,7 +48,7 @@ func main() {
 
 	// Apply filters
 	// Define a filter function
-	itemsFilterFunc := func(item *types.Item) bool {
+	itemsFilterFunc := func(item *cache.Item) bool {
 		// return time.Since(item.LastAccess) > 1*time.Microsecond
 		return item.Value != "val8"
 	}

examples/redis/redis.go

@@ -10,6 +10,7 @@ import (
 	"github.com/hyp3rd/hypercache/backend"
 	"github.com/hyp3rd/hypercache/backend/redis"
 	"github.com/hyp3rd/hypercache/internal/constants"
+	"github.com/hyp3rd/hypercache/pkg/cache"
 	"github.com/hyp3rd/hypercache/types"
 )
 
@@ -62,7 +63,7 @@ func main() {
 
 	// Apply filters
 	// Define a filter function
-	itemsFilterFunc := func(item *types.Item) bool {
+	itemsFilterFunc := func(item *cache.Item) bool {
 		// return time.Since(item.LastAccess) > 1*time.Microsecond
 		return item.Value != "value-16"
 	}