ecache

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

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

func DelCachedEntity(ctx context.Context, cache Cache, key string) (affected int64, err error)

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)