cache

README

Package cache

The cache package will supply you with caching solutions for your crud port-based resources.

You can swap cache.Cache with the resource you wish to cache, and just set your original resource as the Cache.Source. It is advised that your domain logic will be unaware of the caching value type.

package main

import (
	"context"
	"domainpkg"
	"adapters/slowsolution"
	"adapters/fastsolution"
)

func main() {
	var repo domainpkg.XYRepository
	repo = slowsolution.NewXYRepository()
	repo = cache.New(repo, fastsolution.NewCacheRepository())
	bl := domainpkg.NewBusinessLogic(repo)
	_ = bl.Do(context.Background())
}

Documentation

Overview

Package cache will supply caching solutions for your crud port compatible resources.

Index

• Constants
• type Cache
  • func New[Entity any, ID comparable](source Source[Entity, ID], cacheRepo Repository[Entity, ID]) *Cache[Entity, ID]
  • func (m *Cache[Entity, ID]) CachedQueryMany(ctx context.Context, queryKey string, query QueryManyFunc[Entity]) iterators.Iterator[Entity]
  • func (m *Cache[Entity, ID]) CachedQueryOne(ctx context.Context, queryKey string, query QueryOneFunc[Entity]) (_ent Entity, _found bool, _err error)
  • func (m *Cache[Entity, ID]) Create(ctx context.Context, ptr *Entity) error
  • func (m *Cache[Entity, ID]) DeleteAll(ctx context.Context) error
  • func (m *Cache[Entity, ID]) DeleteByID(ctx context.Context, id ID) (rErr error)
  • func (m *Cache[Entity, ID]) DropCachedValues(ctx context.Context) error
  • func (m *Cache[Entity, ID]) FindAll(ctx context.Context) iterators.Iterator[Entity]
  • func (m *Cache[Entity, ID]) FindByID(ctx context.Context, id ID) (Entity, bool, error)
  • func (m *Cache[Entity, ID]) InvalidateByID(ctx context.Context, id ID) (rErr error)
  • func (m *Cache[Entity, ID]) InvalidateCachedQuery(ctx context.Context, queryKey HitID) (rErr error)
  • func (m *Cache[Entity, ID]) Update(ctx context.Context, ptr *Entity) error
• type CachedQueryInvalidator
• type EntityRepository
• type Hit
• type HitID
• type HitRepository
• type Interface
• type QueryKey
  • func (qk QueryKey) Encode() HitID
• type QueryManyFunc
• type QueryOneFunc
• type Repository
• type Source

Constants

const ErrNotImplementedBySource errorkit.Error = "the method is not implemented by the cache source"

Types

type Cache

type Cache[Entity any, ID comparable] struct {
	// Source is the location of the original data
	Source Source[Entity, ID]
	// Repository is the resource that keeps the cached data.
	Repository Repository[Entity, ID]

	CachedQueryInvalidators []CachedQueryInvalidator[Entity, ID]
}

Cache supplies Read/Write-Through caching to CRUD resources.

func New

func New[Entity any, ID comparable](
	source Source[Entity, ID],
	cacheRepo Repository[Entity, ID],
) *Cache[Entity, ID]

func (*Cache[Entity, ID]) CachedQueryMany

func (m *Cache[Entity, ID]) CachedQueryMany(
	ctx context.Context,
	queryKey string,
	query QueryManyFunc[Entity],
) iterators.Iterator[Entity]

func (*Cache[Entity, ID]) CachedQueryOne

func (m *Cache[Entity, ID]) CachedQueryOne(
	ctx context.Context,
	queryKey string,
	query QueryOneFunc[Entity],
) (_ent Entity, _found bool, _err error)

func (*Cache[Entity, ID]) Create

func (m *Cache[Entity, ID]) Create(ctx context.Context, ptr *Entity) error

func (*Cache[Entity, ID]) DeleteAll

func (m *Cache[Entity, ID]) DeleteAll(ctx context.Context) error

func (*Cache[Entity, ID]) DeleteByID

func (m *Cache[Entity, ID]) DeleteByID(ctx context.Context, id ID) (rErr error)

func (*Cache[Entity, ID]) DropCachedValues

func (m *Cache[Entity, ID]) DropCachedValues(ctx context.Context) error

func (*Cache[Entity, ID]) FindAll

func (m *Cache[Entity, ID]) FindAll(ctx context.Context) iterators.Iterator[Entity]

func (*Cache[Entity, ID]) FindByID

func (m *Cache[Entity, ID]) FindByID(ctx context.Context, id ID) (Entity, bool, error)

func (*Cache[Entity, ID]) InvalidateByID

func (m *Cache[Entity, ID]) InvalidateByID(ctx context.Context, id ID) (rErr error)

InvalidateByID will as the name suggest, invalidate an entity from the cache.

If you have CachedQueryMany and CachedQueryOne usage, then you must use InvalidateCachedQuery instead of this. This is requires because if absence of an entity is cached in the HitRepository, then it is impossible to determine how to invalidate those queries using an Entity ID.

func (*Cache[Entity, ID]) InvalidateCachedQuery

func (m *Cache[Entity, ID]) InvalidateCachedQuery(ctx context.Context, queryKey HitID) (rErr error)

func (*Cache[Entity, ID]) Update

func (m *Cache[Entity, ID]) Update(ctx context.Context, ptr *Entity) error

type CachedQueryInvalidator

type CachedQueryInvalidator[Entity, ID any] struct {
	// CheckEntity checks an entity which is being invalidated, and using its properties,
	// you can construct the entity values
	CheckEntity func(ent Entity) []HitID
	// CheckHit meant to check a Hit to decide if it needs to be invalidated.
	// If CheckHit returns with true, then the hit will be invalidated.
	CheckHit func(hit Hit[ID]) bool
}

type EntityRepository

type EntityRepository[Entity, ID any] interface {
	crud.Creator[Entity]
	crud.Updater[Entity]
	crud.Finder[Entity, ID]
	crud.Deleter[ID]
	FindByIDs(ctx context.Context, ids ...ID) iterators.Iterator[Entity]
	Upsert(ctx context.Context, ptrs ...*Entity) error // TODO: replace Upsert with crud.Saver
}

type Hit

type Hit[ID any] struct {
	QueryID   HitID `ext:"id"`
	EntityIDs []ID
	Timestamp time.Time
}

type HitID

type HitID = string

type HitRepository

type HitRepository[EntID any] interface {
	crud.Creator[Hit[EntID]]
	crud.Updater[Hit[EntID]]
	crud.Finder[Hit[EntID], HitID]
	crud.Deleter[HitID]
}

HitRepository is the query hit result repository.

type Interface

type Interface[Entity, ID any] interface {
	CachedQueryOne(ctx context.Context, queryKey HitID, query QueryOneFunc[Entity]) (_ent Entity, _found bool, _err error)
	CachedQueryMany(ctx context.Context, queryKey HitID, query QueryManyFunc[Entity]) iterators.Iterator[Entity]
	InvalidateCachedQuery(ctx context.Context, queryKey HitID) error
	InvalidateByID(ctx context.Context, id ID) (rErr error)
	DropCachedValues(ctx context.Context) error
}

type QueryKey

type QueryKey struct {
	// ID is the unique identifier to know what query is being cached.
	// A method name or any unique name could work.
	ID string
	// ARGS contain parameters to the query that can affect the query result.
	// Supplying the ARGS ensures that a query call with different arguments cached individually.
	ARGS map[string]any

	Version int
}

QueryKey is a helper function that allows you to create QueryManyFunc Keys

func (QueryKey) Encode

func (qk QueryKey) Encode() HitID

type QueryManyFunc

type QueryManyFunc[Entity any] func() iterators.Iterator[Entity]

type QueryOneFunc

type QueryOneFunc[Entity any] func() (ent Entity, found bool, err error)

type Repository

type Repository[Entity, ID any] interface {
	comproto.OnePhaseCommitProtocol
	Entities() EntityRepository[Entity, ID]
	Hits() HitRepository[ID]
}

type Source

type Source[Entity, ID any] interface {
	crud.ByIDFinder[Entity, ID]
}

Source is the minimum expected interface that is expected from a Source resources that needs caching. On top of this, cache.Cache also supports Updater, CreatorPublisher, UpdaterPublisher and DeleterPublisher.