Documentation
¶
Index ¶
- Variables
- func DelCachedEntity(ctx context.Context, cache Cache, key string) (affected int64, err error)
- func GetEntitiesByID[T CacheableEntity[INT], INT constraints.Unsigned](ctx context.Context, cache Cache, entityKeyPrefix string, id INT, ...) ([]*T, error)
- func GetEntityByID[T CacheableEntity[INT], INT constraints.Unsigned](ctx context.Context, cache Cache, entityKeyPrefix string, id INT, ...) (*T, error)
- func GetEntityByUniqueKey[T CacheableEntity[INT], INT constraints.Unsigned, UK UniqueKey](ctx context.Context, cache Cache, entityKeyPrefix string, ukKeyPrefix string, ...) (*T, error)
- type Cache
- type CacheableEntity
- type UniqueKey
Constants ¶
This section is empty.
Variables ¶
var ( // Marshal specifies the default serialization function for cache values Marshal func(v any) ([]byte, error) = json.Marshal // Unmarshal specifies the default deserialization function for cached data Unmarshal func(data []byte, v any) error = json.Unmarshal // DefaultExpiration defines the default time-to-live for cache entries DefaultExpiration time.Duration = 0 // no expiration // Disabled globally turns off caching when true Disabled bool // Delimiter separates components in cache key strings Delimiter = ':' )
Functions ¶
func DelCachedEntity ¶
DelCachedEntity deletes cached data for specified key
func GetEntitiesByID ¶
func GetEntitiesByID[T CacheableEntity[INT], INT constraints.Unsigned]( ctx context.Context, cache Cache, entityKeyPrefix string, id INT, getEntitiesByID func(context.Context, INT) ([]*T, error), ) ([]*T, error)
GetEntitiesByID retrieves entity list with cache-aside pattern Implements: 1. Batch cache lookup with singleflight deduplication 2. Database fallback on cache miss 3. Cache population with serialized results
func GetEntityByID ¶
func GetEntityByID[T CacheableEntity[INT], INT constraints.Unsigned]( ctx context.Context, cache Cache, entityKeyPrefix string, id INT, getEntityByID func(context.Context, INT) (*T, error), ) (*T, error)
GetEntityByID implements a dual-check mechanism: 1. Check cache first with singleflight deduplication 2. Fallback to database on cache miss 3. Repopulate cache with database result
The cache-aside pattern prevents stale cache returns while singleflight prevents cache stampede
func GetEntityByUniqueKey ¶
func GetEntityByUniqueKey[T CacheableEntity[INT], INT constraints.Unsigned, UK UniqueKey]( ctx context.Context, cache Cache, entityKeyPrefix string, ukKeyPrefix string, ukVal UK, getIDByUK func(context.Context, UK) (INT, error), getEntityByID func(context.Context, INT) (*T, error), ) (*T, error)
GetEntityByUniqueKey implements two-level cache resolution: 1. UK -> PK lookup cache 2. PK -> Entity cache Features: - Prevents cache stampede with singleflight - Automatic cache population for both UK-PK and PK-Entity mappings Limitations: - Composite unique keys not supported - Fixed cache key format
Types ¶
type Cache ¶
type Cache interface {
// Del removes multiple entries from cache.
//
// Args:
// ctx: Context for request cancellation/timeout
// keys: Cache keys to delete
//
// Returns:
// affected: Number of successfully deleted entries
// err: Storage errors (e.g. connection issues), nil on success
Del(ctx context.Context, keys ...string) (affected int64, err error)
// Get retrieves raw byte slice from cache.
//
// Args:
// ctx: Context for request cancellation/timeout
// key: Cache entry identifier
//
// Returns:
// val: Cached byte slice (nil on cache miss)
// err: Storage errors or nil. Use IsKeyNotFound() to detect cache misses
Get(ctx context.Context, key string) (val []byte, err error)
// Set stores byte slice in cache with expiration.
//
// Args:
// ctx: Context for request cancellation/timeout
// key: Cache entry identifier
// val: Data to store (nil allowed for cache deletion)
// expire: TTL duration (<=0 means no expiration)
//
// Returns:
// error: Storage errors, nil on success
Set(ctx context.Context, key string, val []byte, expire time.Duration) error
// GetAsUint64 retrieves and converts cached value to unsigned integer.
//
// Performs strict conversion:
// - Returns error if value is not 8-byte little-endian format
// - Returns error if value exceeds uint64 range
//
// Args:
// key: Cache entry identifier
//
// Returns:
// val: Converted unsigned integer value
// err: Conversion errors or storage errors
GetAsUint64(ctx context.Context, key string) (val uint64, err error)
// SetUint64 stores unsigned integer in 8-byte little-endian format.
//
// Args:
// key: Cache entry identifier
// val: Unsigned integer to store
// expire: TTL duration (<=0 uses default expiration)
//
// Returns:
// error: Storage errors, nil on success
SetUint64(ctx context.Context, key string, val uint64, expire time.Duration) error
// IsKeyNotFound checks if error represents cache miss (key not exists).
//
// Implementation should return true for:
// - Cache storage-specific "not found" errors
// - Wrapped versions of these errors
//
// This enables reliable cache miss detection across implementations
IsKeyNotFound(err error) bool
}
type CacheableEntity ¶
type CacheableEntity[INT constraints.Unsigned] interface { ID() INT }
CacheableEntity defines the contract for cacheable domain entities Used to enforce ID-based caching constraints Implementations should: - Use unsigned integer types for identifiers - Maintain immutable ID properties
type UniqueKey ¶
type UniqueKey interface {
~string | constraints.Unsigned
}
UniqueKey defines constraints for database unique keys Used in GetEntityByUniqueKey to enforce: - String or unsigned integer types - Single-field uniqueness (composite keys not supported)
Source Files
Directories