codec

Documentation

Overview

Package codec defines the Codec interface used by bw to serialize and deserialize records stored in BadgerDB, plus the default implementations.

Index

• Variables
• type Codec
  • func JSON() Codec
  • func MsgPack() Codec
• type LazyCodec

Variables

var ErrMissingMsgpMethods = errors.New("bw codec: legacy sentinel — no longer used (msgp codegen requirement removed)")

Sentinel kept for callers that previously imported it.

Types

type Codec

type Codec interface {
	// Name returns a stable identifier (e.g. "msgpack", "json").
	Name() string
	// Marshal serializes v into bytes.
	Marshal(v any) ([]byte, error)
	// Unmarshal deserializes data into v (typically a *T).
	Unmarshal(data []byte, v any) error
	// UnmarshalMap deserializes data into a map[string]any using the same
	// field-name semantics as Unmarshal. This is used by the query
	// evaluator for dynamic dot-path lookups.
	UnmarshalMap(data []byte) (map[string]any, error)
}

Codec is the interface for marshalling and unmarshalling records to and from raw bytes. It is also responsible for decoding into a generic map[string]any used by the query engine for filter evaluation.

func JSON

func JSON() Codec

JSON returns a JSON codec backed by encoding/json.

JSON honours the standard `json:"..."` struct tag. The bw schema layer is independent and parses the `bw` tag for keys/indexes; the codec is only responsible for value encoding, so users who pick the JSON codec should typically tag fields with both `bw:"name,pk"` and `json:"name"`.

func MsgPack

func MsgPack() Codec

MsgPack returns the default msgpack codec, backed by vmihailenco/msgpack/v5. It is reflect-based, so record types do not need any code generation: bw.RegisterBucket[T] just works on any struct.

The codec honours the `bw:"…"` struct tag bw already uses for the schema layer (pk/index/unique flags + field name). The first comma-separated segment of the tag is the on-wire key; "-" skips the field. This means no second `msgpack:"…"` tag is needed.

Lazy decode is implemented by walking the encoded msgpack map token-by-token, decoding only the values whose top-level key the residual filter referenced and Skip()-ping every other length-prefixed value.

type LazyCodec

type LazyCodec interface {
	Codec
	// UnmarshalFields decodes data and returns a map containing only
	// the supplied top-level keys (and any whose first dot-path segment
	// matches an entry). Keys not present in data are simply absent
	// from the returned map. If fields is empty the codec may return an
	// empty map without doing any decoding.
	UnmarshalFields(data []byte, fields []string) (map[string]any, error)
}

LazyCodec is an optional fast-path interface a Codec may implement to support partial decoding. When the query engine needs only a handful of fields (the residual filter's referenced top-level keys), it calls UnmarshalFields instead of UnmarshalMap and the codec returns a map containing only the requested top-level keys.

Codecs are free to ignore the hint — the default behaviour is to fall back to UnmarshalMap. Implementors that decode token-by-token (like msgpack v5) can stop early once every requested key has been seen.