feat: add global variables for all query params name (#12)

Co-authored-by: SystemGlitch <jeremy.la@outlook.fr>

Author: fnoopv

README.md

@@ -106,6 +106,16 @@ results := []*model.User{}
 paginator, err := settings.Scope(session.DB(ctx, r.DB), request, &results)
 ```
 
+You can customize the names of the query parameters using the following global variables:
+- `QueryParamSearch`
+- `QueryParamFilter`
+- `QueryParamOr`
+- `QueryParamSort`
+- `QueryParamJoin`
+- `QueryParamFields`
+- `QueryParamPage`
+- `QueryParamPerPage`
+
 ### Filter
 
 > ?filter=**field**||**$operator**||**value**

settings.go

@@ -27,43 +27,59 @@ type Request struct {
 	PerPage typeutil.Undefined[int]
 }
 
+var (
+	// QueryParamSearch the name of the query parameter for the search feature
+	QueryParamSearch = "search"
+	// QueryParamFilter the name of the query parameter for the filter feature
+	QueryParamFilter = "filter"
+	// QueryParamOr the name of the query parameter for the "or" filter feature
+	QueryParamOr = "or"
+	// QueryParamSort the name of the query parameter for the sort feature
+	QueryParamSort = "sort"
+	// QueryParamJoin the name of the query parameter for the join feature
+	QueryParamJoin = "join"
+	// QueryParamFields the name of the query parameter for the fields feature
+	QueryParamFields = "fields"
+	// QueryParamPage the name of the query parameter indicating the current page
+	QueryParamPage = "page"
+	// QueryParamPerPage the name of the query parameter indicating the page size
+	QueryParamPerPage = "per_page"
+	// DefaultPageSize the default pagination page size if the "per_page" query param
+	// isn't provided.
+	DefaultPageSize = 10
+
+	modelCache = &sync.Map{}
+)
+
 // NewRequest creates a filter request from an HTTP request's query.
-// Uses the following entries in the query, expected to be validated:
-//   - search
-//   - filter
-//   - or
-//   - sort
-//   - join
-//   - fields
-//   - page
-//   - per_page
+// Uses the entries defined by the "QueryParam*" global variables from the given query. All those entries are expected to be validated.
 //
 // If a field in the query doesn't match the expected type (non-validated) for the
 // filtering option, it will be ignored without an error.
 func NewRequest(query map[string]any) *Request {
 	r := &Request{}
-	if search, ok := query["search"].(string); ok {
+	if search, ok := query[QueryParamSearch].(string); ok {
 		r.Search = typeutil.NewUndefined(search)
 	}
-	if filter, ok := query["filter"].([]*Filter); ok {
+	if filter, ok := query[QueryParamFilter].([]*Filter); ok {
 		r.Filter = typeutil.NewUndefined(filter)
 	}
-	if or, ok := query["or"].([]*Filter); ok {
+	if or, ok := query[QueryParamOr].([]*Filter); ok {
 		r.Or = typeutil.NewUndefined(or)
 	}
-	if sort, ok := query["sort"].([]*Sort); ok {
+	if sort, ok := query[QueryParamSort].([]*Sort); ok {
 		r.Sort = typeutil.NewUndefined(sort)
 	}
-	if join, ok := query["join"].([]*Join); ok {
+	if join, ok := query[QueryParamJoin].([]*Join); ok {
 		r.Join = typeutil.NewUndefined(join)
 	}
-	if fields, ok := query["fields"].([]string); ok {
+	if fields, ok := query[QueryParamFields].([]string); ok {
 		r.Fields = typeutil.NewUndefined(fields)
 	}
-	if page, ok := query["page"].(int); ok {
+	if page, ok := query[QueryParamPage].(int); ok {
 		r.Page = typeutil.NewUndefined(page)
 	}
-	if perPage, ok := query["per_page"].(int); ok {
+	if perPage, ok := query[QueryParamPerPage].(int); ok {
 		r.PerPage = typeutil.NewUndefined(perPage)
 	}
 	return r
@@ -116,14 +132,6 @@ type Blacklist struct {
 	IsFinal bool
 }
 
-var (
-	// DefaultPageSize the default pagination page size if the "per_page" query param
-	// isn't provided.
-	DefaultPageSize = 10
-
-	modelCache = &sync.Map{}
-)
-
 func parseModel(db *gorm.DB, model any) (*schema.Schema, error) {
 	return schema.Parse(model, modelCache, db.NamingStrategy)
 }

settings_test.go

@@ -1997,19 +1997,19 @@ func TestNewRequest(t *testing.T) {
 		{
 			desc: "all_fields",
 			query: map[string]any{
-				"filter": []*Filter{
+				QueryParamFilter: []*Filter{
 					{Field: "name", Args: []string{"val1"}, Operator: Operators["$cont"]},
 					{Field: "name", Args: []string{"val2"}, Operator: Operators["$cont"]},
 				},
-				"or": []*Filter{
+				QueryParamOr: []*Filter{
 					{Field: "name", Args: []string{"val3"}, Or: true, Operator: Operators["$eq"]},
 				},
-				"sort":     []*Sort{{Field: "name", Order: SortDescending}},
-				"join":     []*Join{{Relation: "Relation", Fields: []string{"a", "b"}}},
-				"page":     2,
-				"per_page": 15,
-				"fields":   []string{"id", "name", "email", "computed"},
-				"search":   "val",
+				QueryParamSort:    []*Sort{{Field: "name", Order: SortDescending}},
+				QueryParamJoin:    []*Join{{Relation: "Relation", Fields: []string{"a", "b"}}},
+				QueryParamPage:    2,
+				QueryParamPerPage: 15,
+				QueryParamFields:  []string{"id", "name", "email", "computed"},
+				QueryParamSearch:  "val",
 			},
 			want: &Request{
 				Filter: typeutil.NewUndefined([]*Filter{
@@ -2030,12 +2030,12 @@ func TestNewRequest(t *testing.T) {
 		{
 			desc: "partial",
 			query: map[string]any{
-				"filter": []*Filter{
+				QueryParamFilter: []*Filter{
 					{Field: "name", Args: []string{"val1"}, Operator: Operators["$cont"]},
 					{Field: "name", Args: []string{"val2"}, Operator: Operators["$cont"]},
 				},
-				"sort":     []*Sort{{Field: "name", Order: SortDescending}},
-				"per_page": 15,
+				QueryParamSort:    []*Sort{{Field: "name", Order: SortDescending}},
+				QueryParamPerPage: 15,
 			},
 			want: &Request{
 				Filter: typeutil.NewUndefined([]*Filter{
@@ -2049,14 +2049,14 @@ func TestNewRequest(t *testing.T) {
 		{
 			desc: "incorrect_type",
 			query: map[string]any{
-				"filter":   "a",
-				"or":       "b",
-				"sort":     "c",
-				"join":     "d",
-				"page":     "e",
-				"per_page": "f",
-				"fields":   "g",
-				"search":   1,
+				QueryParamFilter:  "a",
+				QueryParamOr:      "b",
+				QueryParamSort:    "c",
+				QueryParamJoin:    "d",
+				QueryParamPage:    "e",
+				QueryParamPerPage: "f",
+				QueryParamFields:  "g",
+				QueryParamSearch:  1,
 			},
 			want: &Request{},
 		},

validation.go

@@ -135,18 +135,18 @@ func (v *JoinValidator) IsType() bool { return true }
 // Validation returns a new RuleSet for query validation.
 func Validation(_ *goyave.Request) v.RuleSet {
 	return v.RuleSet{
-		{Path: "filter", Rules: v.List{v.Array()}},
-		{Path: "filter[]", Rules: v.List{&FilterValidator{}}},
-		{Path: "or", Rules: v.List{v.Array()}},
-		{Path: "or[]", Rules: v.List{&FilterValidator{Or: true}}},
-		{Path: "sort", Rules: v.List{v.Array()}},
-		{Path: "sort[]", Rules: v.List{&SortValidator{}}},
-		{Path: "join", Rules: v.List{v.Array()}},
-		{Path: "join[]", Rules: v.List{&JoinValidator{}}},
-		{Path: "page", Rules: v.List{v.Int(), v.Min(1)}},
-		{Path: "per_page", Rules: v.List{v.Int(), v.Between(1, 500)}},
-		{Path: "search", Rules: v.List{v.String(), v.Max(255)}},
-		{Path: "fields", Rules: v.List{v.String(), &FieldsValidator{}}},
+		{Path: QueryParamFilter, Rules: v.List{v.Array()}},
+		{Path: fmt.Sprintf("%s[]", QueryParamFilter), Rules: v.List{&FilterValidator{}}},
+		{Path: QueryParamOr, Rules: v.List{v.Array()}},
+		{Path: fmt.Sprintf("%s[]", QueryParamOr), Rules: v.List{&FilterValidator{Or: true}}},
+		{Path: QueryParamSort, Rules: v.List{v.Array()}},
+		{Path: fmt.Sprintf("%s[]", QueryParamSort), Rules: v.List{&SortValidator{}}},
+		{Path: QueryParamJoin, Rules: v.List{v.Array()}},
+		{Path: fmt.Sprintf("%s[]", QueryParamJoin), Rules: v.List{&JoinValidator{}}},
+		{Path: QueryParamPage, Rules: v.List{v.Int(), v.Min(1)}},
+		{Path: QueryParamPerPage, Rules: v.List{v.Int(), v.Between(1, 500)}},
+		{Path: QueryParamSearch, Rules: v.List{v.String(), v.Max(255)}},
+		{Path: QueryParamFields, Rules: v.List{v.String(), &FieldsValidator{}}},
 	}
 }
 

validation_test.go

@@ -12,7 +12,19 @@ import (
 func TestApplyValidation(t *testing.T) {
 	set := Validation(nil)
 
-	expectedFields := []string{"filter", "filter[]", "or", "or[]", "sort", "sort[]", "join", "join[]", "fields", "page", "per_page", "search"}
+	expectedFields := []string{
+		QueryParamFilter,
+		fmt.Sprintf("%s[]", QueryParamFilter),
+		QueryParamOr,
+		fmt.Sprintf("%s[]", QueryParamOr),
+		QueryParamSort,
+		fmt.Sprintf("%s[]", QueryParamSort),
+		QueryParamJoin,
+		fmt.Sprintf("%s[]", QueryParamJoin),
+		QueryParamFields,
+		QueryParamPage,
+		QueryParamPerPage,
+		QueryParamSearch}
 	assert.True(t, lo.EveryBy(set, func(f *validation.FieldRules) bool {
 		return lo.Contains(expectedFields, f.Path)
 	}))