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
- func BuildFilterCriteriaFromPredicates(predicates []Predicate, cfg Config) ([]Criteria, []UnsupportedPredicate, error)
- func BuildOrderCriteria(order string, cfg Config) ([]Criteria, []Order)
- func NormalizeOrder(opts ListOptions) string
- func NormalizePagination(opts ListOptions, cfg Config) (int, int, int)
- func NormalizePredicatesWithUnsupported(opts ListOptions, configs ...Config) ([]Predicate, []UnsupportedPredicate)
- func NormalizeValueStrings(raw any) ([]string, bool)
- func ResolveSearchColumns(configured []string, cfg Config) []string
- func VirtualFieldExpr(dialect, sourceField, key string, asJSON bool) string
- type CaseMode
- type ComposedResolver
- type Config
- type Criteria
- type Expression
- type FieldConfig
- type FieldRequest
- type FieldResolver
- type FieldResolverFunc
- type FieldUse
- type IncludeRequest
- type ListOptions
- type LogicalExpression
- type LogicalKind
- type MapResolver
- type Metadata
- type MultiValueMode
- type Operator
- type OperatorKind
- type OperatorSet
- type OperatorSpec
- type Order
- type PaginationConfig
- type PatternConfig
- type PatternMode
- type Plan
- type Predicate
- type PredicateBuilder
- type PredicateBuilderFunc
- type PredicateBuilderHelpers
- type PredicateBuilderInput
- type PredicateBuilderResult
- type PredicateBuilderSet
- type PredicateExpression
- type QuerySyntax
- type ResolvedField
- type SafeIdentifierResolver
- type SearchConfig
- type UnsupportedPredicate
- type UnsupportedReason
- type ValidationConfig
- type ValidationError
- type ValidationErrorCode
- type ValidationMode
Constants ¶
const ( DefaultLimit = 25 DefaultOffset = 0 )
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 ¶
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 ¶
NormalizeValueStrings converts supported scalar and slice values into trimmed, comma-split strings.
func ResolveSearchColumns ¶
ResolveSearchColumns maps configured search fields or trusted columns to SQL columns.
func VirtualFieldExpr ¶
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.
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 ¶
BuildPaginationCriteria returns limit/offset criteria plus normalized values.
func BuildSearchCriteria ¶
BuildSearchCriteria returns dialect-aware search criteria for _search.
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
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.
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
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.
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 PaginationConfig ¶ added in v0.26.0
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
CountCriteria returns criteria suitable for count queries.
func (Plan) ListCriteria ¶
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
PageCriteria returns pagination criteria only.
func (Plan) ReadCriteria ¶
ReadCriteria returns criteria that apply to single-record read operations.
func (Plan) WhereCriteria ¶ added in v0.26.0
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
func (fn PredicateBuilderFunc) BuildPredicate(in PredicateBuilderInput) (PredicateBuilderResult, error)
BuildPredicate implements PredicateBuilder.
type PredicateBuilderHelpers ¶ added in v0.26.0
type PredicateBuilderHelpers struct{}
PredicateBuilderHelpers exposes small helpers for custom predicate 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
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" )