customsort

Documentation

Overview

Package customsort provides types and methods to handle the `sort` query param. It provides two types: `Sort` and `SortMap`. The `Sort` type is a string, and the `SortMap` type is a map of `fieldName:order` pairs.

SortMap provides a custom marshaler which helps Echo to properly convert the `sort` query to a `SortMap` type. In this case, it not only converts but also validates that. The downside of using it is that it can only be used with Echo's `Bind` method.

The `Sort` type is more powerful and flexible, it's framework agnostic, can be easily extended adding more formats. It's used under-the-hood by the `SortMap` type.

Index

• Constants
• type Sort
  • func NewFromMap(m map[string]string) Sort
  • func NewFromString(s, betweenEntriesSeparator string, ascSymbol, descSymbol string) (Sort, error)
  • func (s Sort) IsValid() bool
  • func (s Sort) String() string
  • func (s Sort) ToAnyString(desiredBetweenKVSeparator, desiredBetweenEntriesSeparator string) (string, error)
  • func (s Sort) ToMap() (map[string]string, error)
• type SortMap
  • func (sM *SortMap) ToSort() Sort
  • func (sM *SortMap) UnmarshalParam(src string) error

Constants

const (
	// Asc is the ascending order.
	Asc = "asc"

	// Desc is the descending order.
	Desc = "desc"
)

Types

type Sort

type Sort string

Sort is the raw sort from the request.

func NewFromMap

func NewFromMap(m map[string]string) Sort

NewFromMap creates a new `Sort` from a map[fieldName]order. It first sorts the map by the keys, then it joins the pairs using the `,` separator.

func NewFromString

func NewFromString(
	s,
	betweenEntriesSeparator string,
	ascSymbol, descSymbol string,
) (Sort, error)

NewFromString creates a new Sort instance from a string representation of sort criteria. It supports flexible sort direction symbols:

• Both ascSymbol and descSymbol can be defined: "+name,-age"
• Only ascSymbol defined: "+name,age" (where age defaults to desc)
• Only descSymbol defined: "name,-age" (where name defaults to asc)
• Neither can be undefined (will return error)

Parameters:

• s: The input string containing sort criteria
• betweenEntriesSeparator: Character used to separate multiple sort fields
• ascSymbol: Optional symbol for ascending sort (e.g., "+"). If empty and descSymbol is defined, ascending is implicit (no prefix)
• descSymbol: Optional symbol for descending sort (e.g., "-"). If empty and ascSymbol is defined, descending is implicit (no prefix)

Returns:

• Sort: A properly formatted Sort instance ("field:asc,field:desc")
• error: Invalid input errors for empty string, empty entries, invalid parts, or when both symbols are undefined

Examples:

NewFromString("name,-age", ",", "", "-")     // name:asc,age:desc
NewFromString("+name,age", ",", "+", "")     // name:asc,age:desc
NewFromString("+name,-age", ",", "+", "-")   // name:asc,age:desc

func (Sort) IsValid

func (s Sort) IsValid() bool

IsValid checks if the `s` is formatted correctly.

func (Sort) String

func (s Sort) String() string

String is the Stringer interface implementation.

func (Sort) ToAnyString

func (s Sort) ToAnyString(desiredBetweenKVSeparator, desiredBetweenEntriesSeparator string) (string, error)

ToAnyString function receives two parameters: `desiredBetweenKVSeparator` and `desiredBetweenEntriesSeparator`, which are used to format the `sort` output. It uses `sortRegex` to match and validate `fieldName:order` pairs.

The function returns an error if no matches were found, indicating that the `sort` string format is not correct. The error message specifies the expected format -> `key:order`. If the `sort` string is formatted correctly, it joins the pairs using the `desiredBetweenEntriesSeparator`.

Finally, it replaces the `:` separator with the `desiredBetweenKVSeparator`. If the function executes successfully, it returns the formatted sort string along with a nil error value.

func (Sort) ToMap

func (s Sort) ToMap() (map[string]string, error)

ToMap converts and validates `s` to a map[fieldName]order.

type SortMap

type SortMap map[string]string

SortMap created to satisfy the Echo's `BindUnmarshaler` interface. Powered by the `Sort` type.

func (*SortMap) ToSort

func (sM *SortMap) ToSort() Sort

ToSort converts a SortMap to a raw `Sort` type.

func (*SortMap) UnmarshalParam

func (sM *SortMap) UnmarshalParam(src string) error

UnmarshalParam is the `BindUnmarshaler` implementation.