builder

README

Expression Builder 🔨

Safe queries from URL query strings

Expression Builder works with the exp expression library to define templates that are safely populated with data from a URL query string. More documentation to come.

func Handler(r *http.Request, w http.ResponseWriter) {

	// Define the URL arguments you want to allow and their types
	b := NewBuilder().
		String("firstName").
		String("lastName").
		Int("publishDate").
		Bool("isPublished")

	// Create a usable expression from the URL query string
	expression := b.Evaluate(r.URL.Query())

	// Next, safely pass it into the database, or something...
}

Pull Requests Welcome

This library is a work in progress, and will benefit from your experience reports, use cases, and contributions. If you have an idea for making this library better, send in a pull request. We're all in this together! 🔨

Documentation

Overview

Package builder generates dynamic expressions based on a set of url.Values and a map of allowed fields. It supports several different data types, along with a simple list of operators that can be applied to each predicate.

Index

• Constants
• type Builder
  • func NewBuilder() Builder
  • func (b Builder) Bool(name string, options ...FieldOption) Builder
  • func (b Builder) Evaluate(values url.Values) exp.Expression
  • func (b Builder) EvaluateAll(values url.Values) (exp.Expression, error)
  • func (b Builder) EvaluateField(field Field, values []string) exp.Expression
  • func (b Builder) HasURLParams(values url.Values) bool
  • func (b Builder) Int(name string, options ...FieldOption) Builder
  • func (b Builder) Int64(name string, options ...FieldOption) Builder
  • func (b Builder) Location(name string, options ...FieldOption) Builder
  • func (b Builder) ObjectID(name string, options ...FieldOption) Builder
  • func (b Builder) String(name string, options ...FieldOption) Builder
  • func (b Builder) Time(name string, options ...FieldOption) Builder
• type Field
  • func NewField(name string, dataType string, options ...FieldOption) Field
• type FieldOption
  • func WithAlias(name string) FieldOption
  • func WithDefaultOpBeginsWith() FieldOption
  • func WithDefaultOpContains() FieldOption
  • func WithDefaultOpEqual() FieldOption
  • func WithDefaultOperator(operator string) FieldOption
  • func WithFilter(filter Filter) FieldOption
• type Filter

Constants

const DataTypeBool = "BOOL"

DataTypeFloat represents a boolean parameter

const DataTypeInt = "INT"

DataTypeInt represents an integer parameter

const DataTypeInt64 = "INT64"

DataTypeFloat represents a 64-bit integer parameter

const DataTypeLocation = "LOCATION"

DataTypeLocation represents a GeoJSON location parameter

const DataTypeObjectID = "OBJECTID"

DataTypeFloat represents a mongodb "ObjectId" parameter (24-byte hex string)

const DataTypeString = "STRING"

DataTypeString represents a string parameter

const DataTypeTime = "TIME"

DataTypeTime represents a time.Time parameter

Types

type Builder

type Builder map[string]Field

func NewBuilder

func NewBuilder() Builder

func (Builder) Bool

func (b Builder) Bool(name string, options ...FieldOption) Builder

Bool adds a boolean-based parameter to the expression Builder

func (Builder) Evaluate

func (b Builder) Evaluate(values url.Values) exp.Expression

Evaluate returns an Expression based on the specific url.Values provided

func (Builder) EvaluateAll

func (b Builder) EvaluateAll(values url.Values) (exp.Expression, error)

EvaluateAll returns an Expression that requires ALL of the values in the builder are present.

func (Builder) EvaluateField

func (b Builder) EvaluateField(field Field, values []string) exp.Expression

func (Builder) HasURLParams

func (b Builder) HasURLParams(values url.Values) bool

HasURLParams returns TRUE if the URL contains any parameters that match the Builder. It does not test the validity of those values.

func (Builder) Int

func (b Builder) Int(name string, options ...FieldOption) Builder

Int adds an integer-based parameter to the expression Builder

func (Builder) Int64

func (b Builder) Int64(name string, options ...FieldOption) Builder

Int64 adds an 64-bit integer-based parameter to the expression Builder

func (Builder) Location

func (b Builder) Location(name string, options ...FieldOption) Builder

Location adds a location-based parameter to the expression Builder

func (Builder) ObjectID

func (b Builder) ObjectID(name string, options ...FieldOption) Builder

ObjectID adds a mongodb ObjectID-based parameter to the expression Builder

func (Builder) String

func (b Builder) String(name string, options ...FieldOption) Builder

String adds a string-based parameter to the expression Builder

func (Builder) Time

func (b Builder) Time(name string, options ...FieldOption) Builder

Time adds a stime-based parameter to the expression Builder

type Field

type Field struct {
	Name     string
	DataType string
	Operator string
	Filters  []Filter
}

func NewField

func NewField(name string, dataType string, options ...FieldOption) Field

type FieldOption

type FieldOption func(*Field)

func WithAlias

func WithAlias(name string) FieldOption

WithAlias defines the field name to use when creating an expression, which may be different from the field name to read from the URL.

func WithDefaultOpBeginsWith

func WithDefaultOpBeginsWith() FieldOption

WithDefaultOpBeginsWith defines "BEGINS" as the default operator to use when creating an expression.

func WithDefaultOpContains

func WithDefaultOpContains() FieldOption

WithDefaultOpEqual defines "CONTAINS" as the default operator to use when creating an expression.

func WithDefaultOpEqual

func WithDefaultOpEqual() FieldOption

WithDefaultOpEqual defines "EQUAL" as the default operator to use when creating an expression.

func WithDefaultOperator

func WithDefaultOperator(operator string) FieldOption

WithDefaultOperator defines the default operator to use when creating an expression

func WithFilter

func WithFilter(filter Filter) FieldOption

type Filter

type Filter func(string) string