refactor: reorganize package structure following Go conventions

- Move public packages (backend, eviction, stats, middleware) to pkg/ directory
- Move internal packages (serializer, introspect) to internal/ directory
- Consolidate constants and enums into internal/constants package
- Extract CacheBackendChecker to internal/introspect package
- Update all import paths to reflect new package organization
- Add comprehensive package documentation with usage examples
- Extract startBackgroundJobs method to reduce cyclomatic complexity
- Fix type consistency in eviction loop (int64 → uint)
- Add security linting suppressions where appropriate

This restructuring follows Go project layout conventions, improves code
organization, and clearly separates public APIs from internal implementations.
The pkg/ directory contains packages intended for external use while internal/
contains implementation details not meant for external consumption.

Author: hyp3rd

Makefile

@@ -16,7 +16,7 @@ bench:
 
 # run-example runs the example specified in the example variable with the optional arguments specified in the ARGS variable.
 run-example:
-	go run __examples/$(example)/*.go $(ARGS)
+	go run ./__examples/$(example)/*.go $(ARGS)
 
 update-deps:
 	go get -v -u ./...

__examples/eviction/eviction.go

@@ -8,9 +8,8 @@ import (
 	"time"
 
 	"github.com/hyp3rd/hypercache"
-	"github.com/hyp3rd/hypercache/backend"
 	"github.com/hyp3rd/hypercache/internal/constants"
-	"github.com/hyp3rd/hypercache/types"
+	"github.com/hyp3rd/hypercache/pkg/backend"
 )
 
 const cacheCapacity = 10
@@ -68,7 +67,7 @@ func executeExample(evictionInterval time.Duration) {
 	log.Println("listing all items in the cache")
 
 	// Apply filters
-	sortByFilter := backend.WithSortBy(types.SortByKey.String())
+	sortByFilter := backend.WithSortBy(constants.SortByKey.String())
 
 	items, err := cache.List(context.TODO(), sortByFilter)
 	if err != nil {

__examples/list/list.go

@@ -8,9 +8,9 @@ import (
 	"time"
 
 	"github.com/hyp3rd/hypercache"
-	"github.com/hyp3rd/hypercache/backend"
+	"github.com/hyp3rd/hypercache/internal/constants"
+	"github.com/hyp3rd/hypercache/pkg/backend"
 	"github.com/hyp3rd/hypercache/pkg/cache"
-	"github.com/hyp3rd/hypercache/types"
 )
 
 const (
@@ -53,7 +53,7 @@ func main() {
 		return item.Value != "val8"
 	}
 
-	sortByFilter := backend.WithSortBy(types.SortByExpiration.String())
+	sortByFilter := backend.WithSortBy(constants.SortByExpiration.String())
 
 	sortOrder := backend.WithSortOrderAsc(true)
 

__examples/redis/redis.go

@@ -7,11 +7,10 @@ import (
 	"time"
 
 	"github.com/hyp3rd/hypercache"
-	"github.com/hyp3rd/hypercache/backend"
 	"github.com/hyp3rd/hypercache/backend/redis"
 	"github.com/hyp3rd/hypercache/internal/constants"
+	"github.com/hyp3rd/hypercache/pkg/backend"
 	"github.com/hyp3rd/hypercache/pkg/cache"
-	"github.com/hyp3rd/hypercache/types"
 )
 
 const (
@@ -68,7 +67,7 @@ func main() {
 		return item.Value != "value-16"
 	}
 
-	sortByFilter := backend.WithSortBy(types.SortByKey.String())
+	sortByFilter := backend.WithSortBy(constants.SortByKey.String())
 	// sortOrderFilter := backend.WithSortOrderAsc(true)
 
 	// Create a filterFuncFilter with the defined filter function

__examples/service/service.go

@@ -7,7 +7,7 @@ import (
 	"os"
 
 	"github.com/hyp3rd/hypercache"
-	"github.com/hyp3rd/hypercache/middleware"
+	"github.com/hyp3rd/hypercache/pkg/middleware"
 )
 
 const (

__examples/size/size.go

@@ -8,8 +8,8 @@ import (
 	"time"
 
 	"github.com/hyp3rd/hypercache"
-	"github.com/hyp3rd/hypercache/backend"
 	"github.com/hyp3rd/hypercache/internal/constants"
+	"github.com/hyp3rd/hypercache/pkg/backend"
 )
 
 const (

__examples/stats/stats.go

@@ -7,8 +7,8 @@ import (
 	"time"
 
 	"github.com/hyp3rd/hypercache"
-	"github.com/hyp3rd/hypercache/backend"
 	"github.com/hyp3rd/hypercache/internal/constants"
+	"github.com/hyp3rd/hypercache/pkg/backend"
 )
 
 const (

backend/backend.go

@@ -1,11 +1,21 @@
+// Package hypercache provides a high-performance, generic caching library with configurable backends and eviction algorithms.
+// It supports multiple backend types including in-memory and Redis, with various eviction strategies like LRU, LFU, ARC, and more.
+// The package is designed to be flexible and extensible, allowing users to customize cache behavior through configuration options.
+//
+// Example usage:
+//
+//	config := hypercache.NewConfig[string]("inmemory")
+//	cache := hypercache.NewHyperCache[string](config)
+//	cache.Set("key", "value", time.Hour)
+//	value, found := cache.Get("key")
 package hypercache
 
 import (
 	"strings"
 	"time"
 
-	"github.com/hyp3rd/hypercache/backend"
 	"github.com/hyp3rd/hypercache/internal/constants"
+	"github.com/hyp3rd/hypercache/pkg/backend"
 )
 
 // Config is a struct that wraps all the configuration options to setup `HyperCache` and its backend.

config.go

@@ -27,11 +27,13 @@ words:
   - funlen
   - gitversion
   - GITVERSION
+  - goccy
   - GOFILES
   - gofumpt
   - goimports
   - golines
   - GOPATH
+  - gosec
   - honnef
   - ireturn
   - Itemm