Cache API

Piko's cache provides in-memory, distributed, and multilevel caching with optional compression, encryption, and full-text search. Each cache instance carries generic key and value parameters and sits inside a namespace. For the design rationale see about caching. For task recipes see how to cache. Source file: wdk/cache/facade.go.

Service

Cache construction

func CreateNamespace[K comparable, V any](ctx context.Context, service Service, providerName, namespace string, options Options[K, V]) (Cache[K, V], error)
func NewCache[K comparable, V any](service Service, options Options[K, V]) (Cache[K, V], error)
func NewCacheFromDefault[K comparable, V any](options Options[K, V]) (Cache[K, V], error)
func NewCacheBuilder[K comparable, V any](service Service) (*Builder[K, V], error)
func NewCacheBuilderFromDefault[K comparable, V any]() (*Builder[K, V], error)

CreateNamespace is the recommended entry point. It maps one namespace per value type, which isolates entries and keeps key spaces from colliding. NewCacheBuilderFromDefault is the fluent shortcut when Piko is already bootstrapped.

Note: Treat one namespace as one value type. Sharing a namespace across User and Product causes their key spaces to overlap, so a User{ID:42} collides with a Product{ID:42}.

Builder fluent API

The builder returned from NewCacheBuilder chains configuration before Build(ctx). Method names have no With prefix:

myCache, err := builder.
    Provider("otter").
    Namespace("products").
    MaximumSize(10000).
    Compression().
    Build(ctx)

Builder method groups:

Build(ctx) is the terminus.

Expiration is a convenience for WriteExpiration (a fixed TTL applied on creation and updates only). AccessExpiration sets a sliding TTL that resets on every access (read, write, compute).

The Cache interface

Cache[K, V] mirrors the maypok86/otter v2 API. Methods grouped by purpose:

Read

Write

Invalidate

Refresh

Time

Capacity / stats / lifecycle

Search

Cache[K, V] also exposes search when you configure the cache with a SearchSchema:

Search and Query return ErrSearchNotSupported on providers without search support.

Transactional providers

Providers that support multi-operation rollback (data access layer (DAL) transactions) implement the Transactional[K, V] interface in addition to Cache[K, V]:

type Transactional[K, V] interface {
    BeginTransaction(ctx context.Context) TransactionCache[K, V]
}

TransactionCache[K, V] embeds the cache plus Commit(ctx) error and Rollback(ctx) error. Providers that do not implement Transactional still participate in transactions via Piko's generic journal-based fallback.

Deletion-event hook

Use the builder's OnDeletion(func(DeletionEvent[K, V])) (or OnAtomicDeletion(...) for stricter ordering guarantees) to observe cache evictions, replacements, and explicit invalidations. The event's Cause field is one of the Cause* constants below.

Options and builders

Search

Callers declare searchable fields with SearchSchema and FieldSchema, attach the schema to a cache (via builder option or provider config), and query with SearchOptions or QueryOptions.

schema := cache.NewSearchSchema(
    cache.TextField("title"),
    cache.TagField("category"),
    cache.SortableNumericField("price"),
)

Field constructors

Field type constants

FieldTypeText, FieldTypeTag, FieldTypeNumeric, FieldTypeGeo, FieldTypeVector.

Filter constructors

Filter op constants

FilterOpEq, FilterOpNe, FilterOpGt, FilterOpGe, FilterOpLt, FilterOpLe, FilterOpIn, FilterOpBetween, FilterOpPrefix.

Sort order

SortAsc, SortDesc.

Search types

ErrSearchNotSupported surfaces when a provider does not ship search.

Transformers

Transformers apply compression or encryption to cached values. They chain, so the cache can compress a value then encrypt it before storage.

Shipped implementations:

Chain order: Compression().Encryption() compresses first, then encrypts.

Deletion causes and compute actions

Providers

Encoding

Some providers (Redis, Valkey) need values serialised. The encoding registry accepts a default encoder and type-specific overrides:

registry := cache.NewEncodingRegistry(defaultEncoder)

Types: EncoderPort[V], AnyEncoder, EncodingRegistry.

Bootstrap options

Errors

A Loader returns ErrNotFound when a value is missing from the data source. Cache instances return ErrSearchNotSupported on providers without search.

See also

• About caching for stampede protection, tiered caching, and transformer chain rationale.
• How to cache for adapter swapping, tag-based invalidation, search, and transformer recipes.
• Scenario 016: cached API for an action-level cache example.