queryparams

Documentation

Overview

Package queryparams parses stable core collection query parameters.

Start with ParseSortChecked, ParseFiltersChecked, ParseFieldsChecked, and ParseIncludesChecked when HTTP handlers need structured field errors for sort, filter, sparse fieldset, and include parameters. The unchecked helpers remain available when callers prefer ordinary errors.

The package intentionally stops at parsing and validation. Applications map parsed fields to database, search, or service-layer queries and must maintain their own allowlists through SortConfig and FilterConfig.

Index

• type FieldSet
  • func ParseFields(values url.Values) (FieldSet, error)
  • func ParseFieldsChecked(values url.Values) (FieldSet, fielderrors.FieldErrors)
• type Filter
  • func ParseFilters(values url.Values, config FilterConfig) ([]Filter, error)
  • func ParseFiltersChecked(values url.Values, config FilterConfig) ([]Filter, fielderrors.FieldErrors)
• type FilterConfig
• type FilterField
• type FilterOperator
• type IncludeSet
  • func ParseIncludes(values url.Values) (IncludeSet, error)
  • func ParseIncludesChecked(values url.Values) (IncludeSet, fielderrors.FieldErrors)
• type Sort
  • func ParseSort(values url.Values, config SortConfig) (Sort, error)
  • func ParseSortChecked(values url.Values, config SortConfig) (Sort, fielderrors.FieldErrors)
• type SortConfig
• type SortField

Types

type FieldSet

type FieldSet struct {
	Fields     []string
	ByResource map[string][]string
}

FieldSet describes sparse fieldset parameters.

func ParseFields

func ParseFields(values url.Values) (FieldSet, error)

ParseFields parses fields=id,name and fields[resource]=id,name query values.

func ParseFieldsChecked

func ParseFieldsChecked(values url.Values) (FieldSet, fielderrors.FieldErrors)

ParseFieldsChecked parses sparse fieldset parameters and returns field errors for invalid input.

type Filter

type Filter struct {
	Field    string
	Operator FilterOperator
	Values   []string
}

Filter describes one parsed filter expression.

func ParseFilters

func ParseFilters(values url.Values, config FilterConfig) ([]Filter, error)

ParseFilters parses filter[field]=value and filter[field][operator]=value query values.

func ParseFiltersChecked

func ParseFiltersChecked(values url.Values, config FilterConfig) ([]Filter, fielderrors.FieldErrors)

ParseFiltersChecked parses filters and returns field errors for invalid input.

type FilterConfig

type FilterConfig struct {
	Fields []FilterField
}

FilterConfig configures allowed filter fields and operators. Empty Fields accepts any known operator.

type FilterField

type FilterField struct {
	Name      string
	Operators []FilterOperator
}

FilterField configures one allowed filter field.

type FilterOperator

type FilterOperator string

FilterOperator describes a supported filter operator.

const (
	// FilterOperatorEqual is the default equality operator.
	FilterOperatorEqual FilterOperator = "eq"
	// FilterOperatorNotEqual selects non-equal values.
	FilterOperatorNotEqual FilterOperator = "ne"
	// FilterOperatorGreaterThan selects values greater than the filter value.
	FilterOperatorGreaterThan FilterOperator = "gt"
	// FilterOperatorGreaterThanOrEqual selects values greater than or equal to the filter value.
	FilterOperatorGreaterThanOrEqual FilterOperator = "gte"
	// FilterOperatorLessThan selects values less than the filter value.
	FilterOperatorLessThan FilterOperator = "lt"
	// FilterOperatorLessThanOrEqual selects values less than or equal to the filter value.
	FilterOperatorLessThanOrEqual FilterOperator = "lte"
	// FilterOperatorIn selects values contained in the provided values.
	FilterOperatorIn FilterOperator = "in"
	// FilterOperatorContains selects values containing the provided value.
	FilterOperatorContains FilterOperator = "contains"
)

type IncludeSet

type IncludeSet struct {
	Includes []string
}

IncludeSet describes included relationship names.

func ParseIncludes

func ParseIncludes(values url.Values) (IncludeSet, error)

ParseIncludes parses include=owner,items query values.

func ParseIncludesChecked

func ParseIncludesChecked(values url.Values) (IncludeSet, fielderrors.FieldErrors)

ParseIncludesChecked parses include parameters and returns field errors for invalid input.

type Sort

type Sort struct {
	Fields []SortField
}

Sort describes parsed sort fields in request order.

func ParseSort

func ParseSort(values url.Values, config SortConfig) (Sort, error)

ParseSort parses sort=name,-created_at from query values.

func ParseSortChecked

func ParseSortChecked(values url.Values, config SortConfig) (Sort, fielderrors.FieldErrors)

ParseSortChecked parses sort parameters and returns field errors for invalid input.

type SortConfig

type SortConfig struct {
	AllowedFields []string
}

SortConfig configures allowed sort fields. Empty AllowedFields accepts any field.

type SortField

type SortField struct {
	Name string
	Desc bool
}

SortField describes one sortable field and direction.