Skip to content

1.api.md

Latest commit

 

History

History
323 lines (213 loc) · 4.9 KB

1.api.md

File metadata and controls

323 lines (213 loc) · 4.9 KB
title API Reference
description Function documentation for vecna
author zoobzio
published 2025-01-01
updated 2025-01-14
tags
vecna
api
reference

API Reference

Function documentation for vecna. For type definitions, see Types Reference.

Package Functions

New

func New[T any]() (*Builder[T], error)

Creates a schema-validated Builder for metadata type T.

Type Parameter:

  • T — A struct type representing your metadata schema

Returns:

  • *Builder[T] — Filter builder for the schema
  • error — ErrNotStruct if T is not a struct

Example:

type Metadata struct {
    Category string `json:"category"`
    Score    float64 `json:"score"`
}

builder, err := vecna.New[Metadata]()
if err != nil {
    log.Fatal(err)
}

Builder Methods

Spec

func (b *Builder[T]) Spec() Spec

Returns the extracted schema for documentation or export.

Returns:

  • Spec — Schema metadata including type name and field specifications

Example:

spec := builder.Spec()
fmt.Println(spec.TypeName)  // "Metadata"
for _, f := range spec.Fields {
    fmt.Printf("%s: %s\n", f.Name, f.Kind)
}

Where

func (b *Builder[T]) Where(field string) *FieldBuilder[T]

Begins a filter condition on a field.

Parameters:

  • field — Field name (from json tag or Go field name)

Returns:

  • *FieldBuilder[T] — Builder for chaining operators

Errors:

  • If field doesn't exist, the returned FieldBuilder carries an error that surfaces via Filter.Err()

Example:

filter := builder.Where("category").Eq("tech")

And

func (b *Builder[T]) And(filters ...*Filter) *Filter

Combines filters with logical AND.

Parameters:

  • filters — Child filters to combine

Returns:

  • *Filter — Filter that matches when all children match

Example:

filter := builder.And(
    builder.Where("category").Eq("tech"),
    builder.Where("active").Eq(true),
)

Or

func (b *Builder[T]) Or(filters ...*Filter) *Filter

Combines filters with logical OR.

Parameters:

  • filters — Child filters to combine

Returns:

  • *Filter — Filter that matches when any child matches

Example:

filter := builder.Or(
    builder.Where("category").Eq("tech"),
    builder.Where("category").Eq("science"),
)

FromSpec

func (b *Builder[T]) FromSpec(spec *FilterSpec) *Filter

Converts a FilterSpec to a validated Filter.

Parameters:

  • spec — Serializable filter specification

Returns:

  • *Filter — Validated filter (check Err() for validation errors)

Example:

spec := &vecna.FilterSpec{
    Op:    "eq",
    Field: "category",
    Value: "tech",
}
filter := builder.FromSpec(spec)
if err := filter.Err(); err != nil {
    log.Fatal(err)
}

FieldBuilder Methods

Eq

func (fb *FieldBuilder[T]) Eq(value any) *Filter

Creates an equality filter (field == value).

Ne

func (fb *FieldBuilder[T]) Ne(value any) *Filter

Creates a not-equal filter (field != value).

Gt

func (fb *FieldBuilder[T]) Gt(value any) *Filter

Creates a greater-than filter (field > value).

Errors: Returns filter with error if field is not numeric.

Gte

func (fb *FieldBuilder[T]) Gte(value any) *Filter

Creates a greater-than-or-equal filter (field >= value).

Errors: Returns filter with error if field is not numeric.

Lt

func (fb *FieldBuilder[T]) Lt(value any) *Filter

Creates a less-than filter (field < value).

Errors: Returns filter with error if field is not numeric.

Lte

func (fb *FieldBuilder[T]) Lte(value any) *Filter

Creates a less-than-or-equal filter (field <= value).

Errors: Returns filter with error if field is not numeric.

In

func (fb *FieldBuilder[T]) In(values ...any) *Filter

Creates a set membership filter (field IN (values...)).

Example:

filter := builder.Where("category").In("tech", "science", "art")

Filter Methods

Op

func (f *Filter) Op() Op

Returns the filter operator.

Field

func (f *Filter) Field() string

Returns the field name. Empty string for logical operators (And, Or).

Value

func (f *Filter) Value() any

Returns the comparison value. Nil for logical operators (And, Or).

Children

func (f *Filter) Children() []*Filter

Returns child filters for logical operators. Nil for field conditions.

Err

func (f *Filter) Err() error

Returns any error from filter construction. Recursively checks children and returns the first error encountered.

Example:

filter := builder.And(
    builder.Where("valid").Eq("x"),
    builder.Where("invalid").Eq("y"),
)
if err := filter.Err(); err != nil {
    // err: vecna: field not found: invalid
}