r3json

package
v0.0.5 Latest Latest
Warning

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

 Go to latest Published: Jul 9, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package r3json provides bidirectional conversion between r3 query types and JSON.

Category: Serialization dialect.

It serializes r3.Filters, r3.Sorts, r3.PaginationSpec, and r3.Fields to JSON for REST API request/response bodies, and parses them back. This is useful for building HTTP APIs on top of r3 repositories.

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",
	}
	// 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,
	}
)

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. Returns nil if the cursor is nil.

func (*JSONCursorPagination) ToCursorSpec 

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

ToCursorSpec converts JSONCursorPagination to an r3.CursorSpec. Returns nil if no cursor parameters are set.

type JSONField 

type JSONField string

JSONField is just a string value that represents a field 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 string representation of the field.

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 is optional, depending on how you want to handle the Value.

func (*JSONField) UnmarshalText 

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

UnmarshalText implements the encoding.TextUnmarshaler interface. This is used to decode operator from plain text.

type JSONFields 

type JSONFields []JSONField

JSONFields as of collection of json.JSONField's.

func (JSONFields) String 

func (fields JSONFields) String() string

String returns string representation of the fields E.g. JSONFields{"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"`

	// The operator is provided as a string (like "eq", "ne", etc.)
	Op    JSONFilterOperator `json:"op,omitempty"`
	Value any                `json:"v,omitempty"` // allow for raw value handling (or use any, string, etc.)

	// 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 is optional, depending on how you want to handle the Value.

type JSONFilterOperator 

type JSONFilterOperator int8

JSONFilterOperator represents a filter operator in JSON format. 

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, **=
)

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 the json.Marshaler interface.

func (JSONFilterOperator) MarshalText 

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

MarshalText implements the encoding.TextMarshaler interface. This is used to encode operator as plain text.

func (JSONFilterOperator) String 

func (op JSONFilterOperator) String() string

String is implemented for debugging purposes, so the JSONFilterOperator is a fmt.Stringer.

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 the json.Unmarshaler interface. It expects the JSON value to be a string representing the operator.

func (*JSONFilterOperator) UnmarshalText 

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

UnmarshalText implements the encoding.TextUnmarshaler interface. This is used to decode operator from plain text.

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.