memoize

memoize

memoize is a small, type-safe, in-process operation cache for Go services. It requires Go 1.27 or later and uses only the standard library.

Warning: This project is in early development.

Usage

type Service struct {
	findUser memoize.Func2[string, string, User]
}

func NewService(repository Repository) *Service {
	memo := memoize.MustNew(memoize.Policy{
		TTL:      30 * time.Second,
		Capacity: 10_000,
		Jitter:   3 * time.Second,
	})

	return &Service{
		findUser: memo.Func2(
			repository.FindUser,
			memoize.Named("users.find"), // optional
		),
	}
}

func (s *Service) User(ctx context.Context, tenantID, userID string) (User, error) {
	return s.findUser.Call(ctx, tenantID, userID)
}

func (s *Service) UserChanged(tenantID, userID string) {
	s.findUser.Forget(tenantID, userID)
}

Once, Func, Func2, Func3, and Func4 accept ordinary context-aware functions. Go infers their argument and result types. Operations provide Call, Refresh, Clear, Stats, and Name; keyed operations also provide Forget. A Call method value is an ordinary function value suitable for dependency injection.

Names are inferred once from the loader's runtime symbol. Use Named for a stable telemetry name. The inferred or overridden name is only a display name; it never determines operation identity or cache correctness. Statistics are reported per operation. A Memoizer must be constructed with New or MustNew; constructed values are immutable and safe to copy.

Custom keys

The default methods use static comparable tuple keys. Use the corresponding By method when arguments are not comparable or Go equality is not the right semantic equality:

search := memo.Func2By(
	client.Search,
	func(tenant string, request SearchRequest) searchKey {
		return searchKey{
			Tenant: tenant,
			Query:  request.Query,
			Page:   request.Page,
		}
	},
)

The key function is applied consistently by Call, Refresh, and Forget.

Error policies

Successful values are cached by default. Selected negative caching and stale-if-error are opt-in operation options:

find := memo.Func(
	repository.Find,
	memoize.StaleIfError(2*time.Minute),
	memoize.CacheErrorsFor(5*time.Second, func(err error) bool {
		return errors.Is(err, repository.ErrNotFound)
	}),
)

Selected errors cache the exact value/error pair. context.Canceled, context.DeadlineExceeded, ErrRecursiveLoad, ErrLoaderGoexit, and *PanicError are never negative-cached.

After the normal TTL, a successful value may remain eligible for stale fallback for the configured duration. An ordinary Call can return it when a new load fails with an unselected error; eligibility is rechecked when that load finishes. Refresh bypasses a fresh result, coalesces with another load for the key, publishes successful and selected-error results, and always returns the actual loader error instead of stale data.

Behavior

Each operation has an independent TTL, exact LRU capacity, and statistics. Expiration is lazy. Concurrent misses for one key coalesce, while callers cancel independently. Forget and Clear prevent an older in-progress load from repopulating the cache.

Keys use Go equality and must be comparable and reflexive. Context-derived inputs that affect results belong in the key. Cached reference-bearing values are shared and should be treated as immutable.

See DESIGN.md for detailed concurrency, invalidation, expiration, recursion, and accounting semantics.