querybun

package
v0.27.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package querybun builds reusable Bun query plans from typed list options.

The package is staged inside go-crud so predicate parsing and criteria planning can later move to github.com/goliatone/go-query-bun with a mechanical import path replacement.

Planning is configured through Config, which groups query syntax, field resolution, semantic operators, search behavior, custom predicate builders, pagination defaults, and validation behavior. Use MapResolver for trusted field maps, SafeIdentifierResolver for strict dynamic identifiers, and OperatorSet for aliases or custom operator behavior.

The default REST syntax supports field__operator keys, object-shaped operator maps, search aliases, and unsupported metadata. Unknown operators are never rendered as equality predicates.

Index

Constants

View Source
const (
	DefaultLimit  = 25
	DefaultOffset = 0
)
View Source
const (
	VirtualDialectPostgres = "postgres"
	VirtualDialectSQLite   = "sqlite"
)

Variables

This section is empty.

Functions

func BuildFilterCriteriaFromPredicates

func BuildFilterCriteriaFromPredicates(predicates []Predicate, cfg Config) ([]Criteria, []UnsupportedPredicate, error)

BuildFilterCriteriaFromPredicates builds Bun WHERE criteria from normalized predicates and a trusted allowed field map.

func BuildOrderCriteria

func BuildOrderCriteria(order string, cfg Config) ([]Criteria, []Order)

BuildOrderCriteria returns trusted order criteria and metadata.

func NormalizeOrder

func NormalizeOrder(opts ListOptions) string

NormalizeOrder returns the effective order string for list options.

func NormalizePagination

func NormalizePagination(opts ListOptions, cfg Config) (int, int, int)

NormalizePagination returns the effective limit, offset, and one-based page.

func NormalizePredicatesWithUnsupported

func NormalizePredicatesWithUnsupported(opts ListOptions, configs ...Config) ([]Predicate, []UnsupportedPredicate)

NormalizePredicatesWithUnsupported converts ListOptions filters or predicates into normalized predicates and reports values that cannot be represented.

func NormalizeValueStrings

func NormalizeValueStrings(raw any) ([]string, bool)

NormalizeValueStrings converts supported scalar and slice values into trimmed, comma-split strings.

func ResolveSearchColumns

func ResolveSearchColumns(configured []string, cfg Config) []string

ResolveSearchColumns maps configured search fields or trusted columns to SQL columns.

func VirtualFieldExpr

func VirtualFieldExpr(dialect, sourceField, key string, asJSON bool) string

VirtualFieldExpr returns a SQL snippet for the given dialect to access a virtual field. When asJSON is false, text extraction is used for comparisons and ordering. When asJSON is true, the raw JSON value is returned.

Types

type CaseMode added in v0.26.0

type CaseMode string

CaseMode controls case-sensitive or case-insensitive pattern matching.

const (
	CaseSensitive   CaseMode = "sensitive"
	CaseInsensitive CaseMode = "insensitive"
)

type ComposedResolver added in v0.26.0

type ComposedResolver []FieldResolver

ComposedResolver tries resolvers in order.

func ComposeResolvers added in v0.26.0

func ComposeResolvers(resolvers ...FieldResolver) ComposedResolver

ComposeResolvers creates a resolver chain.

func (ComposedResolver) ResolveField added in v0.26.0

func (r ComposedResolver) ResolveField(req FieldRequest) (ResolvedField, bool)

ResolveField implements FieldResolver.

type Config

type Config struct {
	Syntax     QuerySyntax
	Fields     FieldConfig
	Operators  OperatorSet
	Search     SearchConfig
	Predicates PredicateBuilderSet
	Pagination PaginationConfig
	Validation ValidationConfig
}

Config controls syntax, field resolution, operators, search, predicates, pagination, and validation.

func DefaultConfig added in v0.26.0

func DefaultConfig() Config

DefaultConfig returns the primary semantic planner configuration.

type Criteria

type Criteria func(*bun.SelectQuery) *bun.SelectQuery

Criteria is compatible with github.com/goliatone/go-repository-bun SelectCriteria.

func BuildPaginationCriteria

func BuildPaginationCriteria(opts ListOptions, cfg Config) ([]Criteria, int, int, int)

BuildPaginationCriteria returns limit/offset criteria plus normalized values.

func BuildSearchCriteria

func BuildSearchCriteria(search string, cfg Config) ([]Criteria, string, error)

BuildSearchCriteria returns dialect-aware search criteria for _search.

func BuildSelectCriteria

func BuildSelectCriteria(fields []string, cfg Config) ([]Criteria, []string)

BuildSelectCriteria returns projection criteria and trusted selected columns.

type Expression added in v0.26.0

type Expression interface {
	// contains filtered or unexported methods
}

Expression is the marker interface for future nested logical query ASTs.

type FieldConfig added in v0.26.0

type FieldConfig struct {
	Resolver FieldResolver
}

FieldConfig groups field resolution behavior.

type FieldRequest added in v0.26.0

type FieldRequest struct {
	Field string
	Use   FieldUse
}

FieldRequest describes a request to resolve a public field name.

type FieldResolver added in v0.26.0

type FieldResolver interface {
	ResolveField(FieldRequest) (ResolvedField, bool)
}

FieldResolver resolves public field names for filter, order, search, and select use.

type FieldResolverFunc added in v0.26.0

type FieldResolverFunc func(FieldRequest) (ResolvedField, bool)

FieldResolverFunc adapts a function to FieldResolver.

func (FieldResolverFunc) ResolveField added in v0.26.0

func (fn FieldResolverFunc) ResolveField(req FieldRequest) (ResolvedField, bool)

ResolveField implements FieldResolver.

type FieldUse added in v0.26.0

type FieldUse string

FieldUse describes the planner section requesting a field resolution.

const (
	FieldUseFilter FieldUse = "filter"
	FieldUseOrder  FieldUse = "order"
	FieldUseSearch FieldUse = "search"
	FieldUseSelect FieldUse = "select"
)

type IncludeRequest

type IncludeRequest struct {
	Path string
}

IncludeRequest describes a normalized include path. Bun Relation criteria remain adapter-owned by go-crud.

func NormalizeIncludes

func NormalizeIncludes(includes []string) []IncludeRequest

NormalizeIncludes returns trimmed, comma-split include requests.

type ListOptions

type ListOptions struct {
	Page       int
	PerPage    int
	Limit      int
	LimitSet   bool
	Offset     int
	OffsetSet  bool
	SortBy     string
	SortDesc   bool
	Order      string
	Search     string
	Filters    map[string]any
	Predicates []Predicate
	Select     []string
	Include    []string
}

ListOptions provides a non-HTTP contract for list query planning.

type LogicalExpression added in v0.26.0

type LogicalExpression struct {
	Kind     LogicalKind
	Children []Expression
	RawKey   string
	RawValue any
}

LogicalExpression models nested cross-field boolean input. SQL rendering for these nodes is intentionally not enabled by default.

type LogicalKind added in v0.26.0

type LogicalKind string

LogicalKind identifies cross-field boolean expression nodes.

const (
	LogicalAnd LogicalKind = "and"
	LogicalOr  LogicalKind = "or"
	LogicalNot LogicalKind = "not"
)

type MapResolver added in v0.26.0

type MapResolver map[string]string

MapResolver maps trusted public field names to trusted SQL columns or expressions.

func NewMapResolver added in v0.26.0

func NewMapResolver(fields map[string]string) MapResolver

NewMapResolver returns a trusted map resolver with copied values.

func (MapResolver) ResolveField added in v0.26.0

func (r MapResolver) ResolveField(req FieldRequest) (ResolvedField, bool)

ResolveField implements FieldResolver.

type Metadata

type Metadata struct {
	Limit   int
	Offset  int
	Page    int
	Search  string
	Order   []Order
	Fields  []string
	Include []string
}

Metadata contains normalized query values for response adapters and callers.

type MultiValueMode added in v0.26.0

type MultiValueMode string

MultiValueMode controls whether repeated values are ANDed or ORed.

const (
	MultiValueAll MultiValueMode = "all"
	MultiValueAny MultiValueMode = "any"
)

type Operator

type Operator struct {
	Token     string
	Canonical OperatorKind
	SQL       string
	Spec      OperatorSpec
}

Operator is a resolved operator token with its semantic kind and SQL behavior.

func ResolveOperator

func ResolveOperator(token, field string, cfg Config) (Operator, error)

ResolveOperator resolves token into a semantic operator.

type OperatorKind added in v0.26.0

type OperatorKind string

OperatorKind identifies a semantic predicate operator independent of SQL.

const (
	OperatorEq       OperatorKind = "eq"
	OperatorNe       OperatorKind = "ne"
	OperatorGt       OperatorKind = "gt"
	OperatorLt       OperatorKind = "lt"
	OperatorGte      OperatorKind = "gte"
	OperatorLte      OperatorKind = "lte"
	OperatorIn       OperatorKind = "in"
	OperatorNin      OperatorKind = "nin"
	OperatorLike     OperatorKind = "like"
	OperatorILike    OperatorKind = "ilike"
	OperatorContains OperatorKind = "contains"
	OperatorAnd      OperatorKind = "and"
	OperatorOr       OperatorKind = "or"
)

func ParsePredicateKey

func ParsePredicateKey(key string) (string, OperatorKind)

ParsePredicateKey splits field__operator keys into field and operator parts.

type OperatorSet added in v0.26.0

type OperatorSet struct {
	Specs   map[OperatorKind]OperatorSpec
	Aliases map[string]OperatorKind
}

OperatorSet resolves aliases to semantic operator specs.

func DefaultOperatorSet added in v0.26.0

func DefaultOperatorSet() OperatorSet

DefaultOperatorSet returns the built-in semantic operators.

func (OperatorSet) Resolve added in v0.26.0

func (s OperatorSet) Resolve(token string) (Operator, bool)

Resolve resolves a user token to an operator.

func (OperatorSet) WithAlias added in v0.26.0

func (s OperatorSet) WithAlias(alias string, kind OperatorKind) OperatorSet

WithAlias returns a copy with one additional alias.

func (OperatorSet) WithSpec added in v0.26.0

func (s OperatorSet) WithSpec(spec OperatorSpec, aliases ...string) OperatorSet

WithSpec returns a copy with a replaced or added operator spec.

type OperatorSpec added in v0.26.0

type OperatorSpec struct {
	Kind       OperatorKind
	SQL        string
	Pattern    PatternConfig
	Case       CaseMode
	MultiValue MultiValueMode
}

OperatorSpec describes how a semantic operator renders.

type Order

type Order struct {
	Field string
	Dir   string
}

Order describes a trusted order clause after field resolution.

type PaginationConfig added in v0.26.0

type PaginationConfig struct {
	DefaultLimit  int
	DefaultOffset int
}

PaginationConfig groups pagination defaults.

type PatternConfig added in v0.26.0

type PatternConfig struct {
	Mode       PatternMode
	EscapeChar string
	MultiValue MultiValueMode
}

PatternConfig controls pattern wrapping and escaping.

type PatternMode added in v0.26.0

type PatternMode string

PatternMode controls how user input becomes a SQL pattern.

const (
	PatternRaw             PatternMode = "raw"
	PatternContains        PatternMode = "contains"
	PatternContainsEscaped PatternMode = "contains_escaped"
)

type Plan

type Plan struct {
	Filters     []Criteria
	Search      []Criteria
	Order       []Criteria
	Pagination  []Criteria
	Select      []Criteria
	Includes    []IncludeRequest
	Metadata    Metadata
	Unsupported []UnsupportedPredicate
}

Plan contains independently applicable criteria groups for a list query.

func BuildQueryPlan

func BuildQueryPlan(opts ListOptions, cfg Config) (Plan, error)

BuildQueryPlan builds a separated, reusable query plan from list options.

func (Plan) CountCriteria added in v0.26.0

func (p Plan) CountCriteria() []Criteria

CountCriteria returns criteria suitable for count queries.

func (Plan) ListCriteria

func (p Plan) ListCriteria() []Criteria

ListCriteria returns the legacy combined criteria order used by go-crud list operations: pagination, order, filters/search, select.

func (Plan) PageCriteria added in v0.26.0

func (p Plan) PageCriteria() []Criteria

PageCriteria returns pagination criteria only.

func (Plan) ReadCriteria

func (p Plan) ReadCriteria() []Criteria

ReadCriteria returns criteria that apply to single-record read operations.

func (Plan) WhereCriteria added in v0.26.0

func (p Plan) WhereCriteria() []Criteria

WhereCriteria returns criteria that constrain rows without order, pagination, or projection.

type Predicate

type Predicate struct {
	Field    string
	Operator OperatorKind
	Values   []string
	RawKey   string
	RawValue any
}

Predicate represents a normalized field/operator/value query predicate.

func NormalizePredicates

func NormalizePredicates(opts ListOptions, configs ...Config) []Predicate

NormalizePredicates converts ListOptions filters or predicates into a normalized predicate list. Explicit Predicates take precedence over Filters.

type PredicateBuilder added in v0.26.0

type PredicateBuilder interface {
	BuildPredicate(PredicateBuilderInput) (PredicateBuilderResult, error)
}

PredicateBuilder can render custom field or operator predicates.

type PredicateBuilderFunc added in v0.26.0

type PredicateBuilderFunc func(PredicateBuilderInput) (PredicateBuilderResult, error)

PredicateBuilderFunc adapts a function to PredicateBuilder.

func (PredicateBuilderFunc) BuildPredicate added in v0.26.0

BuildPredicate implements PredicateBuilder.

type PredicateBuilderHelpers added in v0.26.0

type PredicateBuilderHelpers struct{}

PredicateBuilderHelpers exposes small helpers for custom predicate builders.

func (PredicateBuilderHelpers) Compare added in v0.26.0

func (PredicateBuilderHelpers) Compare(column, sqlOp string, values []string) Criteria

Compare builds comparison criteria for custom builders.

func (PredicateBuilderHelpers) WhereExpr added in v0.26.0

func (PredicateBuilderHelpers) WhereExpr(expr string, args ...any) Criteria

WhereExpr builds a raw trusted criteria expression for custom builders.

type PredicateBuilderInput added in v0.26.0

type PredicateBuilderInput struct {
	Predicate     Predicate
	Operator      Operator
	Field         ResolvedField
	FieldResolved bool
	Values        []string
	Config        Config
	Helpers       PredicateBuilderHelpers
}

PredicateBuilderInput describes one predicate planning request.

type PredicateBuilderResult added in v0.26.0

type PredicateBuilderResult struct {
	Criteria []Criteria
	Handled  bool
}

PredicateBuilderResult reports whether a custom builder handled a predicate.

func PredicateHandled added in v0.26.0

func PredicateHandled(criteria ...Criteria) PredicateBuilderResult

PredicateHandled returns a handled custom predicate result.

func PredicateUnhandled added in v0.26.0

func PredicateUnhandled() PredicateBuilderResult

PredicateUnhandled returns an unhandled custom predicate result.

type PredicateBuilderSet added in v0.26.0

type PredicateBuilderSet struct {
	Fields    map[string]PredicateBuilder
	Operators map[OperatorKind]PredicateBuilder
}

PredicateBuilderSet groups field-specific and operator-specific builders.

type PredicateExpression added in v0.26.0

type PredicateExpression struct {
	Predicate Predicate
}

PredicateExpression wraps a normalized field predicate as an expression node.

type QuerySyntax added in v0.26.0

type QuerySyntax struct {
	PredicateDelimiter string
	ReservedKeys       map[string]struct{}
	OperatorAliases    map[string]OperatorKind
	LogicalAliases     map[string]LogicalKind
}

QuerySyntax owns generic query decoding behavior outside search aliases.

func DefaultRESTSyntax added in v0.26.0

func DefaultRESTSyntax() QuerySyntax

DefaultRESTSyntax returns the current REST field__operator query syntax.

type ResolvedField added in v0.26.0

type ResolvedField struct {
	Field      string
	Column     string
	Expression string
	Use        FieldUse
	Trusted    bool
}

ResolvedField describes a trusted SQL column or expression.

func (ResolvedField) SQLName added in v0.26.0

func (f ResolvedField) SQLName() string

SQLName returns the SQL expression used by the planner.

type SafeIdentifierResolver added in v0.26.0

type SafeIdentifierResolver struct {
	AllowDotted bool
}

SafeIdentifierResolver resolves only simple SQL identifiers.

func (SafeIdentifierResolver) ResolveField added in v0.26.0

func (r SafeIdentifierResolver) ResolveField(req FieldRequest) (ResolvedField, bool)

ResolveField implements FieldResolver.

type SearchConfig added in v0.26.0

type SearchConfig struct {
	Aliases []string
	Fields  []string
	Pattern PatternConfig
	Case    CaseMode
}

SearchConfig owns search aliases, fields, and matching behavior.

type UnsupportedPredicate

type UnsupportedPredicate struct {
	Field    string
	Operator OperatorKind
	RawKey   string
	RawValue any
	Reason   UnsupportedReason
}

UnsupportedPredicate records a dropped or rejected query predicate.

type UnsupportedReason

type UnsupportedReason string

UnsupportedReason identifies why a query fragment was not planned.

const (
	UnsupportedUnknownField       UnsupportedReason = "unknown_field"
	UnsupportedDisallowedField    UnsupportedReason = "disallowed_field"
	UnsupportedOperator           UnsupportedReason = "unsupported_operator"
	UnsupportedEmptyValue         UnsupportedReason = "empty_value"
	UnsupportedValueShape         UnsupportedReason = "unsupported_value_shape"
	UnsupportedUnhandledPredicate UnsupportedReason = "unhandled_custom_predicate"
)

type ValidationConfig added in v0.26.0

type ValidationConfig struct {
	Mode               ValidationMode
	StrictFields       bool
	StrictSearchFields bool
}

ValidationConfig controls strict versus collect behavior.

type ValidationError

type ValidationError struct {
	Code     ValidationErrorCode
	Field    string
	Operator string
	Search   string
}

ValidationError provides typed strict-mode query validation failures.

func (*ValidationError) Error

func (e *ValidationError) Error() string

type ValidationErrorCode

type ValidationErrorCode string

ValidationErrorCode identifies strict query validation failures.

const (
	ValidationUnsupportedOperator   ValidationErrorCode = "unsupported_operator"
	ValidationSearchColumnsRequired ValidationErrorCode = "search_columns_required"
	ValidationFieldNotAllowed       ValidationErrorCode = "field_not_allowed"
)

type ValidationMode added in v0.26.0

type ValidationMode string

ValidationMode chooses strict errors or collect-style unsupported metadata.

const (
	ValidationCollect ValidationMode = "collect"
	ValidationStrict  ValidationMode = "strict"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址