search

README

Package Search

A generic query builder for Go 1.25+ designed to handle dynamic filtering, sorting, and projection through JSON.

Features

• Type-Safe Filters: Specialized conditions for String, Number, Boolean, and Date.
• Custom Sort Unmarshaling: Supports JSON object syntax for sorting ({"field": 1}) while maintaining order internally.
• Projection Validation: Validates if requested projection/sort fields exist in the target struct's JSON tags.
• Generics: Works with any filter struct and field key constraint.

Usage

1. Define Filter and Keys

type UserFilter struct {
    Name search.StringCondition      `json:"name"`
    Age  search.NumberCondition[int] `json:"age"`
}

type UserKeys string // Usually matches JSON tags

2. Parse Query from JSON

jsonData := []byte(`{
    "where": { "age": { "gte": 18 } },
    "sort": { "name": 1 },
    "project": { "mode": "include", "fields": ["name"] },
    "limit": 20
}`)

var q search.Query[UserFilter, UserKeys]
json.Unmarshal(jsonData, &q)

3. Validate Projection and Sort

If your filter shape matches the returned item shape, you can call:

if err := q.Validate(); err != nil {
    log.Fatal(err)
}

If you want to validate against a different struct (recommended for read models/views), use:

type UserView struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

if err := q.ValidateAgainst[UserView](); err != nil {
    log.Fatal(err)
}

Core Components

• Conditions: Each type (String, Number, etc.) has its own set of operators (eq, gt, like, in, etc.).
• Query Struct: The container for Where (filters), Sort, Project, and pagination (Limit/Offset).
• Result Struct: A standard wrapper for paginated responses containing items and total count.

Installation

go get github.com/leandroluk/gox/search

Documentation

Index

• func NewSearchSchema[T any]() *v.ObjectSchema[SearchQuery[T]]
• type SearchFields
• type SearchQuery
  • func ParseSearch[T any](q string) (SearchQuery[T], error)
• type SearchResult

Functions

func NewSearchSchema

func NewSearchSchema[T any]() *v.ObjectSchema[SearchQuery[T]]

NewSearchSchema builds a validator for SearchQuery[T]. Keys in where/fields/sort are validated against T's json field names. Operator keys inside where[field] are validated against the allowed set.

Types

type SearchFields

type SearchFields struct {
	Include []string `json:"include"`
	Exclude []string `json:"exclude"`
}

type SearchQuery

type SearchQuery[T any] struct {
	Text   *string         `json:"text"`
	Offset *int64          `json:"offset"`
	Limit  *int64          `json:"limit"`
	Where  map[string]any  `json:"where"`
	Fields *SearchFields   `json:"fields"`
	Sort   map[string]int8 `json:"sort"`
}

func ParseSearch

func ParseSearch[T any](q string) (SearchQuery[T], error)

ParseSearch validates and parses a JSON search query string. Designed for GET ?q=<json> pattern.

type SearchResult

type SearchResult[T any] struct {
	Items  []T   `json:"items"`
	Total  int64 `json:"total"`
	Offset int64 `json:"offset"`
	Limit  int64 `json:"limit"`
}