Fields Reference

Complete reference for typed keys and fields in github.com/zoobz-io/capitan.

Key Interface

All keys implement this interface:

type Key interface {
    Name() string
    Variant() Variant
}

Built-in Key Constructors

NewStringKey

func NewStringKey(name string) StringKey

Creates a key for string values. Variant: "string".

NewIntKey

func NewIntKey(name string) IntKey

Creates a key for int values. Variant: "int".

NewInt32Key

func NewInt32Key(name string) Int32Key

Creates a key for int32 values. Variant: "int32".

NewInt64Key

func NewInt64Key(name string) Int64Key

Creates a key for int64 values. Variant: "int64".

NewUintKey

func NewUintKey(name string) UintKey

Creates a key for uint values. Variant: "uint".

NewUint32Key

func NewUint32Key(name string) Uint32Key

Creates a key for uint32 values. Variant: "uint32".

NewUint64Key

func NewUint64Key(name string) Uint64Key

Creates a key for uint64 values. Variant: "uint64".

NewFloat32Key

func NewFloat32Key(name string) Float32Key

Creates a key for float32 values. Variant: "float32".

NewFloat64Key

func NewFloat64Key(name string) Float64Key

Creates a key for float64 values. Variant: "float64".

NewBoolKey

func NewBoolKey(name string) BoolKey

Creates a key for bool values. Variant: "bool".

NewTimeKey

func NewTimeKey(name string) TimeKey

Creates a key for time.Time values. Variant: "time.Time".

NewDurationKey

func NewDurationKey(name string) DurationKey

Creates a key for time.Duration values. Variant: "time.Duration".

NewBytesKey

func NewBytesKey(name string) BytesKey

Creates a key for []byte values. Variant: "[]byte".

NewErrorKey

func NewErrorKey(name string) ErrorKey

Creates a key for error values. Variant: "error".

NewKey

func NewKey[T any](name string, variant Variant) GenericKey[T]

Creates a key for custom types. Use namespaced variant strings to avoid collisions:

type Order struct {
    ID    string
    Total float64
}

var orderKey = capitan.NewKey[Order]("order", "myapp.Order")

GenericKeyT

All built-in key types are aliases of GenericKey[T].

Name

func (k GenericKey[T]) Name() string

Returns the key's semantic identifier.

Variant

func (k GenericKey[T]) Variant() Variant

Returns the key's type discriminator.

Field

func (k GenericKey[T]) Field(value T) Field

Creates a field with the given value for use in Emit.

From

func (k GenericKey[T]) From(e *Event) (T, bool)

Extracts the typed value from an event. Returns (zero, false) if the field is missing or has the wrong type.

ExtractFromFields

func (k GenericKey[T]) ExtractFromFields(fields []Field) T

Extracts the typed value from a field slice. Returns the zero value if not found. Useful for testing with captured events.

Usage Pattern

// Define key
orderID := capitan.NewStringKey("order_id")

// Create field for emission
capitan.Emit(ctx, signal, orderID.Field("ORD-123"))

// Extract in listener
capitan.Hook(signal, func(ctx context.Context, e *capitan.Event) {
    id, ok := orderID.From(e)
    if !ok {
        return
    }
    // Use id...
})

Field Interface

Fields are key-value pairs attached to events:

type Field interface {
    Variant() Variant
    Key() Key
    Value() any
}

GenericFieldT

Concrete implementation of Field for typed values.

Variant

func (f GenericField[T]) Variant() Variant

Returns the field's type discriminator.

Key

func (f GenericField[T]) Key() Key

Returns the field's key.

Value

func (f GenericField[T]) Value() any

Returns the value as any.

Get

func (f GenericField[T]) Get() T

Returns the typed value.

Variant Constants

Type discriminators for built-in types:

Custom types should use namespaced variant strings to avoid collisions:

// Good: namespaced
capitan.NewKey[Order]("order", "myapp.Order")
capitan.NewKey[User]("user", "github.com/org/pkg.User")

// Bad: collision risk
capitan.NewKey[Order]("order", "Order")

Extracting from Field Slices

When working with captured events in tests, use ExtractFromFields:

import capitantesting "github.com/zoobz-io/capitan/testing"

capture := capitantesting.NewEventCapture()
c.Hook(signal, capture.Handler())

// ... emit events ...

events := capture.Events()
id := orderID.ExtractFromFields(events[0].Fields)  // Returns zero value if missing

See Testing Guide for more testing patterns.