r3json

package
v0.5.2 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package r3json converts r3 query types (r3.Filters, r3.Sorts, r3.PaginationSpec, r3.Fields) to and from JSON for REST request/response bodies. Filters use the compact form {"f":field,"op":operator,"v":value}.

Category: Serialization dialect.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// FilterOperatorNames maps operator constants to their canonical string names.
	FilterOperatorNames = map[JSONFilterOperator]string{
		OperatorUnspecified:      "",
		OperatorEq:               "eq",
		OperatorNe:               "ne",
		OperatorExists:           "exists",
		OperatorGt:               "gt",
		OperatorGte:              "gte",
		OperatorLt:               "lt",
		OperatorLte:              "lte",
		OperatorBetween:          "between",
		OperatorBetweenEx:        "between_exc",
		OperatorBetweenExInc:     "between_exc_inc",
		OperatorBetweenIncEx:     "between_inc_exc",
		OperatorIn:               "in",
		OperatorNotIn:            "nin",
		OperatorLike:             "like",
		OperatorNotLike:          "notlike",
		OperatorILike:            "ilike",
		OperatorWeekdayIn:        "weekday_in",
		OperatorTimeOfDayBetween: "tod_between",
	}
	// FilterOperatorValues maps string representations (including aliases) to operator constants.
	FilterOperatorValues = map[string]JSONFilterOperator{
		"":                OperatorUnspecified,
		"eq":              OperatorEq,
		"==":              OperatorEq,
		"ne":              OperatorNe,
		"!=":              OperatorNe,
		"exists":          OperatorExists,
		"gt":              OperatorGt,
		">":               OperatorGt,
		"gte":             OperatorGte,
		">=":              OperatorGte,
		"lt":              OperatorLt,
		"<":               OperatorLt,
		"lte":             OperatorLte,
		"<=":              OperatorLte,
		"between":         OperatorBetween,
		"between_inc":     OperatorBetween,
		"between_exc":     OperatorBetweenEx,
		"between_exc_inc": OperatorBetweenExInc,
		"between_inc_exc": OperatorBetweenIncEx,
		"in":              OperatorIn,
		"nin":             OperatorNotIn,
		"like":            OperatorLike,
		"*=":              OperatorLike,
		"notlike":         OperatorNotLike,
		"!*=":             OperatorNotLike,
		"ilike":           OperatorILike,
		"**=":             OperatorILike,
		"weekday_in":      OperatorWeekdayIn,
		"tod_between":     OperatorTimeOfDayBetween,
	}
)

Enum value maps for JSONFilterOperator.

View Source 
var ErrInvalidFilterOperator = errors.New("invalid filter operator")

ErrInvalidFilterOperator is returned when a filter operator string cannot be parsed.

View Source 
var ErrJSONDialectorFailed = errors.New("json dialector failed")

ErrJSONDialectorFailed is a generic error for r3json dialector failures.

Functions

func IsErrDialectorFailure 

func IsErrDialectorFailure(err error) bool

IsErrDialectorFailure checks if the given error is a r3json failure.

func JSONFiltersToFilters deprecated 

func JSONFiltersToFilters(inboundFilters JSONFilters) (r3.Filters, error)

JSONFiltersToFilters is an alias for JSONToFilters for backward compatibility.

Deprecated: Use JSONToFilters instead.

func JSONToField 

func JSONToField(jf JSONField) *r3.FieldSpec

JSONToField converts a JSONField to a FieldSpec.

func JSONToFilter 

func JSONToFilter(jf *JSONFilter) (*r3.FilterSpec, error)

JSONToFilter converts a JSONFilter to a FilterSpec.

func JSONToFilters 

func JSONToFilters(jfs JSONFilters) (r3.Filters, error)

JSONToFilters converts a slice of JSONFilters to r3.Filters.

func JSONToOperator 

func JSONToOperator(jop JSONFilterOperator) (r3.FilterOperatorSpec, error)

JSONToOperator converts a JSONFilterOperator to a FilterOperatorSpec.

func JSONToPagination 

func JSONToPagination(jp *JSONPagination) (*r3.PaginationSpec, error)

JSONToPagination converts a JSONPagination to a PaginationSpec.

func JSONToSort 

func JSONToSort(js *JSONSort) (*r3.SortSpec, error)

JSONToSort converts a JSONSort to a SortSpec.

Types

type JSONCursorPagination 

type JSONCursorPagination struct {
	After  string `json:"after,omitempty"`
	Before string `json:"before,omitempty"`
	Limit  int    `json:"limit,omitempty"`
}

JSONCursorPagination represents cursor-based pagination in JSON format.

func CursorToJSON 

func CursorToJSON(c *r3.CursorSpec) *JSONCursorPagination

CursorToJSON converts an r3.CursorSpec to JSONCursorPagination, nil if nil.

func (*JSONCursorPagination) ToCursorSpec 

func (jc *JSONCursorPagination) ToCursorSpec() *r3.CursorSpec

ToCursorSpec converts JSONCursorPagination to an r3.CursorSpec, nil if unset.

type JSONField 

type JSONField string

JSONField is a field name inside a JSON object, e.g. {"fields":["id","status"]}.

func FieldToJSON 

func FieldToJSON(f *r3.FieldSpec) JSONField

FieldToJSON converts a FieldSpec to a JSONField.

func (*JSONField) MarshalText 

func (f *JSONField) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface.

func (*JSONField) String 

func (f *JSONField) String() string

String returns the field name.

func (*JSONField) ToFieldSpec 

func (f *JSONField) ToFieldSpec() (*r3.FieldSpec, error)

ToFieldSpec converts a JSON field into r3 FieldSpec.

func (*JSONField) UnmarshalJSON 

func (f *JSONField) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

func (*JSONField) UnmarshalText 

func (f *JSONField) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type JSONFields 

type JSONFields []JSONField

JSONFields is a collection of JSONField.

func (JSONFields) String 

func (fields JSONFields) String() string

String joins the fields comma-separated, e.g. {"id","status"} => "id,status".

func (JSONFields) ToFieldSpecs 

func (fields JSONFields) ToFieldSpecs() (r3.Fields, error)

ToFieldSpecs converts list of JSON Fields into r3 Fields.

type JSONFilter 

type JSONFilter struct {
	Field JSONField `json:"f,omitempty"`

	Op    JSONFilterOperator `json:"op,omitempty"`
	Value any                `json:"v,omitempty"` // raw value

	// Logical groups:
	And JSONFilters `json:"and,omitempty"`
	Or  JSONFilters `json:"or,omitempty"`
}

JSONFilter represents a filter in JSON format with field, operator, value, and logical groups.

func FilterToJSON 

func FilterToJSON(f *r3.FilterSpec) (*JSONFilter, error)

FilterToJSON converts a FilterSpec to a JSONFilter.

func (*JSONFilter) MarshalJSON 

func (jf *JSONFilter) MarshalJSON() ([]byte, error)

MarshalJSON implements custom JSON marshaling to handle nil values correctly.

func (*JSONFilter) String 

func (jf *JSONFilter) String() string

String returns a string representation of a single filter (as a json string).

func (*JSONFilter) ToFilterSpec 

func (jf *JSONFilter) ToFilterSpec() (*r3.FilterSpec, error)

func (*JSONFilter) UnmarshalJSON 

func (jf *JSONFilter) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type JSONFilterOperator 

type JSONFilterOperator int8

JSONFilterOperator represents a filter operator in JSON format.

The receivers are deliberately mixed, as a codec pattern: value receivers marshal, pointer receivers unmarshal. Making them pointer-only would stop values from satisfying the json and text Marshaler interfaces. 

const (
	OperatorUnspecified      JSONFilterOperator = iota
	OperatorEq                                  // eq, ==
	OperatorNe                                  // ne, !=
	OperatorExists                              // exists
	OperatorGt                                  // gt, >
	OperatorGte                                 // gte, >=
	OperatorLt                                  // lt, <
	OperatorLte                                 // lte, <=
	OperatorBetween                             // between (inclusive both)
	OperatorBetweenEx                           // between_exc (exclusive both)
	OperatorBetweenExInc                        // between_exc_inc
	OperatorBetweenIncEx                        // between_inc_exc
	OperatorIn                                  // in
	OperatorNotIn                               // nin
	OperatorLike                                // like, *=
	OperatorNotLike                             // notlike, !*=
	OperatorILike                               // ilike, **=
	OperatorWeekdayIn                           // weekday_in
	OperatorTimeOfDayBetween                    // tod_between
)

JSON filter operator constants.

func OperatorToJSON 

func OperatorToJSON(op r3.FilterOperatorSpec) (JSONFilterOperator, error)

OperatorToJSON converts a FilterOperatorSpec to a JSONFilterOperator.

func (JSONFilterOperator) MarshalJSON 

func (op JSONFilterOperator) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler.

func (JSONFilterOperator) MarshalText 

func (op JSONFilterOperator) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (JSONFilterOperator) String 

func (op JSONFilterOperator) String() string

String returns the operator's canonical name.

func (JSONFilterOperator) ToFilterOperatorSpec 

func (op JSONFilterOperator) ToFilterOperatorSpec() (r3.FilterOperatorSpec, error)

ToFilterOperatorSpec converts a JSONFilterOperator to an r3.FilterOperatorSpec.

func (*JSONFilterOperator) UnmarshalJSON 

func (op *JSONFilterOperator) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler, expecting a quoted operator string.

func (*JSONFilterOperator) UnmarshalText 

func (op *JSONFilterOperator) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type JSONFilters 

type JSONFilters []*JSONFilter

JSONFilters is a slice of JSONFilter.

func (JSONFilters) String 

func (jfs JSONFilters) String() string

String returns string representation of the JSON Filters (as a json string).

type JSONNullsPosition 

type JSONNullsPosition string

JSONNullsPosition represents nulls position in JSON. 

const (
	// JSONNullsPositionFirst represents nulls first.
	JSONNullsPositionFirst JSONNullsPosition = "first"
	// JSONNullsPositionLast represents nulls last.
	JSONNullsPositionLast JSONNullsPosition = "last"
	// JSONNullsPositionUnspecified represents unspecified nulls position.
	JSONNullsPositionUnspecified JSONNullsPosition = ""
)

func (JSONNullsPosition) ToR3NullsPosition 

func (jnp JSONNullsPosition) ToR3NullsPosition() r3.SortNullsPosition

ToR3NullsPosition converts JSONNullsPosition to r3.SortNullsPosition.

type JSONPagination 

type JSONPagination struct {
	PageNum  int `json:"page_num,omitempty"`
	PageSize int `json:"page_size,omitempty"`
}

JSONPagination represents pagination in JSON format using page_num and page_size.

func PaginationToJSON 

func PaginationToJSON(p *r3.PaginationSpec) *JSONPagination

PaginationToJSON converts a PaginationSpec to a JSONPagination.

func (*JSONPagination) String 

func (jp *JSONPagination) String() string

String returns the JSON string representation of pagination.

func (*JSONPagination) ToPaginationSpec 

func (jp *JSONPagination) ToPaginationSpec() (*r3.PaginationSpec, error)

ToPaginationSpec converts JSONPagination to r3.PaginationSpec.

type JSONSort 

type JSONSort struct {
	Field         JSONField         `json:"field"`
	Direction     JSONSortDirection `json:"direction,omitempty"`
	NullsPosition JSONNullsPosition `json:"nulls_position,omitempty"`
}

JSONSort represents a sort criteria in JSON format.

func SortToJSON 

func SortToJSON(s *r3.SortSpec) *JSONSort

SortToJSON converts a SortSpec to a JSONSort.

func (*JSONSort) String 

func (js *JSONSort) String() string

String returns the string representation of the sort.

func (*JSONSort) ToSortSpec 

func (js *JSONSort) ToSortSpec() (*r3.SortSpec, error)

ToSortSpec converts JSONSort to r3.SortSpec.

type JSONSortDirection 

type JSONSortDirection string

JSONSortDirection represents sort direction in JSON. 

const (
	// JSONSortDirectionAsc represents ascending sort.
	JSONSortDirectionAsc JSONSortDirection = "asc"
	// JSONSortDirectionDesc represents descending sort.
	JSONSortDirectionDesc JSONSortDirection = "desc"
	// JSONSortDirectionUnspecified represents unspecified direction.
	JSONSortDirectionUnspecified JSONSortDirection = ""
)

func (JSONSortDirection) ToR3SortDirection 

func (jsd JSONSortDirection) ToR3SortDirection() r3.SortDirection

ToR3SortDirection converts JSONSortDirection to r3.SortDirection.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.