cachekeybind

Documentation

Overview

Package cachekeybind provides typed, reflection-free cache key generation.

A struct marks the fields a cached result depends on, tinybind-gen emits the key method, and no call site concatenates anything by hand:

type UserSummary struct {
	UserID string `cache:"key"`
	Page   int    `cache:"key"`
	Name   string
	Total  int
}

summary, err := memo(ctx, store, key, fetch) // key.CacheKey() is generated

Marking is opt-in because the struct passed to a cache is often a storage entity rather than a purpose-built key: most of its fields are the result rather than the query, and keying on those would mean building the key from the value the lookup exists to avoid fetching.

One struct yields one key. An entity wanted in a second cache store gets a second struct, which keeps the identity below derivable from the type alone.

What generation does and does not guarantee

It guarantees the identity prefix is present and the framing cannot alias, so two key types holding equal field values never reach one entry. It does not guarantee completeness: a dependency the author never marks is absent from the key, and no compiler can see that requirement. What it removes is every failure that survives a correct dependency set.

Index

• func AppendKeyArray[T any](dst []byte, values []T, encode func([]byte, T) []byte) []byte
• func AppendKeyBool[T ~bool](dst []byte, value T) []byte
• func AppendKeyBytes(dst []byte, value []byte) []byte
• func AppendKeyFloat[T ~float32 | ~float64](dst []byte, value T) []byte
• func AppendKeyInt[T ~int | ~int8 | ~int16 | ~int32 | ~int64](dst []byte, value T) []byte
• func AppendKeyOptional[T any](dst []byte, value *T, encode func([]byte, T) []byte) []byte
• func AppendKeyString[T ~string](dst []byte, value T) []byte
• func AppendKeyTime(dst []byte, value time.Time) []byte
• func AppendKeyUint[T ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr](dst []byte, value T) []byte
• func KeyArray[T any](values []T, encode func(T) string) string
• func KeyBool[T ~bool](value T) string
• func KeyBytes(value []byte) string
• func KeyFloat[T ~float32 | ~float64](value T) string
• func KeyInt[T ~int | ~int8 | ~int16 | ~int32 | ~int64](value T) string
• func KeyOptional[T any](value *T, encode func(T) string) string
• func KeyString[T ~string](value T) string
• func KeyTime(value time.Time) string
• func KeyUint[T ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr](value T) string
• type CacheKey
• type SizeHint
  • func (h *SizeHint) Buffer() []byte
  • func (h *SizeHint) Finish(key []byte) string

Functions

func AppendKeyArray

func AppendKeyArray[T any](dst []byte, values []T, encode func([]byte, T) []byte) []byte

AppendKeyArray frames a slice onto dst as its element count followed by its framed elements, under KeyArray's rules.

func AppendKeyBool

func AppendKeyBool[T ~bool](dst []byte, value T) []byte

AppendKeyBool frames a bool onto dst.

func AppendKeyBytes

func AppendKeyBytes(dst []byte, value []byte) []byte

AppendKeyBytes frames a byte slice onto dst.

func AppendKeyFloat

func AppendKeyFloat[T ~float32 | ~float64](dst []byte, value T) []byte

AppendKeyFloat frames a float onto dst, under KeyFloat's rules.

func AppendKeyInt

func AppendKeyInt[T ~int | ~int8 | ~int16 | ~int32 | ~int64](dst []byte, value T) []byte

AppendKeyInt frames any signed integer onto dst.

func AppendKeyOptional

func AppendKeyOptional[T any](dst []byte, value *T, encode func([]byte, T) []byte) []byte

AppendKeyOptional frames a pointer onto dst, distinguishing absence from any present value.

func AppendKeyString

func AppendKeyString[T ~string](dst []byte, value T) []byte

AppendKeyString frames a string onto dst.

func AppendKeyTime

func AppendKeyTime(dst []byte, value time.Time) []byte

AppendKeyTime frames a time onto dst, under KeyTime's rules.

func AppendKeyUint

func AppendKeyUint[T ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr](dst []byte, value T) []byte

AppendKeyUint frames any unsigned integer onto dst.

func KeyArray

func KeyArray[T any](values []T, encode func(T) string) string

KeyArray frames a slice as its element count followed by its framed elements, so a slice of one two-element string cannot collide with two one-element ones.

A nil slice and an empty slice frame identically. They are equal as inputs to a fetch, and distinguishing them would key on a distinction the caller did not make.

func KeyBool

func KeyBool[T ~bool](value T) string

KeyBool frames a bool.

func KeyBytes

func KeyBytes(value []byte) string

KeyBytes frames a byte slice.

func KeyFloat

func KeyFloat[T ~float32 | ~float64](value T) string

KeyFloat frames a float. A float32 is widened first, which is exact, so two distinct float32 values still frame distinctly.

Negative zero frames differently from positive zero even though the two compare equal. That costs a miss rather than a wrong answer, and the alternative is normalizing a value the author chose to key on.

func KeyInt

func KeyInt[T ~int | ~int8 | ~int16 | ~int32 | ~int64](value T) string

KeyInt frames any signed integer. It is generic over every width so a named int type or an int64 needs no conversion, which is where htmlbind's own KeyInt stops.

func KeyOptional

func KeyOptional[T any](value *T, encode func(T) string) string

KeyOptional frames a pointer, distinguishing absence from any present value.

func KeyString

func KeyString[T ~string](value T) string

KeyString frames a string. It is generic over ~string so a generated enum or named string type needs no conversion at the call site.

func KeyTime

func KeyTime(value time.Time) string

KeyTime frames a time. It uses a fixed layout with nanosecond precision in UTC, so two equal instants in different locations encode identically and a monotonic reading never reaches the key.

func KeyUint

func KeyUint[T ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr](value T) string

KeyUint frames any unsigned integer.

Types

type CacheKey

type CacheKey interface {
	CacheKey() string
}

CacheKey reports the cache key of a value. Generated code implements it on the value receiver.

The returned string carries the type's identity followed by the framed encoding of every marked field, so it is safe to concatenate with a scope prefix but must never reach a browser: it holds field values in plaintext.

type SizeHint

type SizeHint struct {
	// contains filtered or unexported fields
}

SizeHint remembers how long a type's keys have been, so a generated CacheKey allocates its buffer once at that size. The zero value is ready to use and safe for concurrent use.

func (*SizeHint) Buffer

func (h *SizeHint) Buffer() []byte

Buffer returns an empty buffer sized for the longest key recorded so far, plus an eighth; before anything is recorded it is sized for a short key.

func (*SizeHint) Finish

func (h *SizeHint) Finish(key []byte) string

Finish records the length of a finished key and returns it as a string.