Skip to content

2.types.md

Latest commit

 

History

History
216 lines (164 loc) · 4.67 KB

2.types.md

File metadata and controls

216 lines (164 loc) · 4.67 KB
title Types Reference
description Type definitions for vecna
author zoobzio
published 2025-01-01
updated 2025-01-14
tags
vecna
types
reference

Types Reference

Type definitions for vecna. For function documentation, see API Reference.

Builder

type Builder[T any] struct {
    // contains filtered or unexported fields
}

Schema-validated filter factory. Created via New[T]().

Thread-safe after creation. Create once at startup and reuse.

FieldBuilder

type FieldBuilder[T any] struct {
    // contains filtered or unexported fields
}

Constructs conditions for a specific field. Created via Builder.Where().

Filter

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

A filter condition or logical group. Immutable after construction.

Method Returns Description
Op() Op Operator type
Field() string Field name (empty for And/Or)
Value() any Comparison value (nil for And/Or)
Children() []*Filter Child filters (nil for field conditions)
Err() error First error in tree

FilterSpec

type FilterSpec struct {
    Op       string        `json:"op"`
    Field    string        `json:"field,omitempty"`
    Value    any           `json:"value,omitempty"`
    Children []*FilterSpec `json:"children,omitempty"`
}

Serializable filter specification for external construction.

Field Type Description
Op string Operator: "eq", "ne", "gt", "gte", "lt", "lte", "in", "and", "or"
Field string Field name (for comparison operators)
Value any Comparison value (for comparison operators)
Children []*FilterSpec Child specs (for and/or)

Op

type Op uint8

const (
    Eq  Op = iota // Equal
    Ne            // Not equal
    Gt            // Greater than
    Gte           // Greater than or equal
    Lt            // Less than
    Lte           // Less than or equal
    In            // In set
    And           // Logical AND
    Or            // Logical OR
)

Filter operators.

Constant Value Description
Eq 0 Equal (==)
Ne 1 Not equal (!=)
Gt 2 Greater than (>)
Gte 3 Greater than or equal (>=)
Lt 4 Less than (<)
Lte 5 Less than or equal (<=)
In 6 Set membership
And 7 Logical AND
Or 8 Logical OR

Methods:

Method Signature Description
String String() string Returns "eq", "ne", etc.

FieldKind

type FieldKind uint8

const (
    KindString FieldKind = iota
    KindInt
    KindFloat
    KindBool
    KindSlice
    KindUnknown
)

Field type categories for validation.

Constant Description
KindString String fields
KindInt Integer fields (int, int64, uint, etc.)
KindFloat Float fields (float32, float64)
KindBool Boolean fields
KindSlice Slice fields
KindUnknown Unrecognized types

Spec

type Spec struct {
    TypeName string
    Fields   []FieldSpec
}

Schema metadata extracted from T.

Field Type Description
TypeName string Go type name (e.g., "Metadata")
Fields []FieldSpec Filterable field specifications

Methods:

Method Signature Description
Field Field(name string) *FieldSpec Returns FieldSpec by name, or nil

FieldSpec

type FieldSpec struct {
    Name   string    // JSON field name
    GoName string    // Original Go field name
    Kind   FieldKind // Type category
}

Describes a single filterable field.

Field Type Description
Name string Field name used in filters (from json tag or Go name)
GoName string Original Go struct field name
Kind FieldKind Type category for validation

Errors

var (
    ErrNotStruct     = errors.New("vecna: type must be a struct")
    ErrFieldNotFound = errors.New("vecna: field not found")
    ErrInvalidFilter = errors.New("vecna: invalid filter")
)
Error Cause
ErrNotStruct Type parameter T is not a struct
ErrFieldNotFound Field name not in schema
ErrInvalidFilter Invalid operator for field type, nil spec, unknown operator, etc.

Use errors.Is() to check error types:

if errors.Is(err, vecna.ErrFieldNotFound) {
    // handle missing field
}