Add ConvertOrderBy method for MongoDB-style sorting

Add `ORDER BY` support with `ConvertOrderBy` method.

- Converts MongoDB-style sort objects to PostgreSQL `ORDER BY` clauses.
- Supports both regular columns and JSONB fields with dual sorting.
- Includes integration tests and fuzz tests.

Author: erikdubbelboer

README.md

@@ -97,6 +97,39 @@ values := []any{"aztec", "nuke", "", 2, 10}
 (given "customdata" is configured with `filter.WithNestedJSONB("customdata", "password", "playerCount")`)
 
 
+## Order By Support
+
+In addition to filtering, this package also supports converting MongoDB-style sort objects into PostgreSQL ORDER BY clauses using the `ConvertOrderBy` method:
+
+```go
+// Convert a sort object to an ORDER BY clause
+sortInput := []byte(`{"playerCount": -1, "name": 1}`)
+orderBy, err := converter.ConvertOrderBy(sortInput)
+if err != nil {
+  // handle error
+}
+fmt.Println(orderBy) // "playerCount" DESC, "name" ASC
+
+db.Query("SELECT * FROM games ORDER BY " + orderBy)
+```
+
+### Sort Direction Values:
+- `1`: Ascending (ASC)
+- `-1`: Descending (DESC)
+
+### JSONB Field Sorting:
+For JSONB fields, the package generates sophisticated ORDER BY clauses that handle both numeric and text sorting:
+
+```go
+// With WithNestedJSONB("metadata", "created_at"):
+sortInput := []byte(`{"score": -1}`)
+orderBy, err := converter.ConvertOrderBy(sortInput)
+// Generates: (CASE WHEN jsonb_typeof(metadata->'score') = 'number' THEN (metadata->>'score')::numeric END) DESC NULLS LAST, metadata->>'score' DESC NULLS LAST
+```
+
+This ensures proper sorting whether the JSONB field contains numeric or text values.
+
+
 ## Difference with MongoDB
 
 - The MongoDB query filters don't have the option to compare fields with each other. This package adds the `$field` operator to compare fields with each other.  

filter/converter.go

@@ -404,3 +404,77 @@ func (c *Converter) isNestedColumn(column string) bool {
 	}
 	return true
 }
+
+// ConvertOrderBy converts a JSON object with field names and sort directions
+// into a PostgreSQL ORDER BY clause. The JSON object should have keys with values
+// of 1 (ASC) or -1 (DESC).
+//
+// For JSONB fields, it generates clauses that handle both numeric and text sorting.
+//
+// Example: {"playerCount": -1, "name": 1} -> "playerCount DESC, name ASC"
+func (c *Converter) ConvertOrderBy(query []byte) (string, error) {
+	keyValues, err := objectInOrder(query)
+	if err != nil {
+		return "", err
+	}
+
+	parts := make([]string, 0, len(keyValues))
+
+	for _, kv := range keyValues {
+		key, value := kv.Key, kv.Value
+
+		if !isValidPostgresIdentifier(key) {
+			return "", fmt.Errorf("invalid column name: %s", key)
+		}
+		if !c.isColumnAllowed(key) {
+			return "", ColumnNotAllowedError{Column: key}
+		}
+
+		// Convert value to number for direction
+		var direction string
+		switch v := value.(type) {
+		case json.Number:
+			if num, err := v.Int64(); err == nil {
+				switch num {
+				case 1:
+					direction = "ASC"
+				case -1:
+					direction = "DESC"
+				default:
+					return "", InvalidOrderDirectionError{Field: key, Value: value}
+				}
+			} else {
+				return "", InvalidOrderDirectionError{Field: key, Value: value}
+			}
+		case float64:
+			switch v {
+			case 1:
+				direction = "ASC"
+			case -1:
+				direction = "DESC"
+			default:
+				return "", InvalidOrderDirectionError{Field: key, Value: value}
+			}
+		default:
+			return "", InvalidOrderDirectionError{Field: key, Value: value}
+		}
+
+		var fieldClause string
+		if c.isNestedColumn(key) {
+			// For JSONB fields, handle both numeric and text sorting.
+			// We need to use the raw JSONB reference for jsonb_typeof, but columnName() for the actual sorting
+			fieldClause = fmt.Sprintf("(CASE WHEN jsonb_typeof(%s->'%s') = 'number' THEN (%s)::numeric END) %s NULLS LAST, %s %s NULLS LAST", c.nestedColumn, key, c.columnName(key), direction, c.columnName(key), direction)
+		} else {
+			// Regular field.
+			fieldClause = fmt.Sprintf(`%s %s`, c.columnName(key), direction)
+		}
+
+		parts = append(parts, fieldClause)
+	}
+
+	if len(parts) == 0 {
+		return "", nil
+	}
+
+	return strings.Join(parts, ", "), nil
+}

filter/converter_test.go

@@ -2,6 +2,7 @@ package filter_test
 
 import (
 	"database/sql"
+	"encoding/json"
 	"fmt"
 	"reflect"
 	"testing"
@@ -641,3 +642,134 @@ func TestConverter_AccessControl(t *testing.T) {
 	t.Run("nested but disallow password, disallow",
 		f(`{"password": "hacks"}`, no("password"), filter.WithNestedJSONB("meta", "created_at"), filter.WithDisallowColumns("password")))
 }
+
+func TestConverter_ConvertOrderBy(t *testing.T) {
+	tests := []struct {
+		name     string
+		options  []filter.Option
+		input    string
+		expected string
+		err      error
+	}{
+		{
+			"single field ascending",
+			[]filter.Option{filter.WithAllowAllColumns()},
+			`{"playerCount": 1}`,
+			`"playerCount" ASC`,
+			nil,
+		},
+		{
+			"single field descending",
+			[]filter.Option{filter.WithAllowAllColumns()},
+			`{"playerCount": -1}`,
+			`"playerCount" DESC`,
+			nil,
+		},
+		{
+			"multiple fields",
+			[]filter.Option{filter.WithAllowAllColumns()},
+			`{"playerCount": -1, "name": 1}`,
+			`"playerCount" DESC, "name" ASC`,
+			nil,
+		},
+		{
+			"nested JSONB single field ascending",
+			[]filter.Option{filter.WithNestedJSONB("customdata", "created_at")},
+			`{"map": 1}`,
+			`(CASE WHEN jsonb_typeof(customdata->'map') = 'number' THEN ("customdata"->>'map')::numeric END) ASC NULLS LAST, "customdata"->>'map' ASC NULLS LAST`,
+			nil,
+		},
+		{
+			"nested JSONB single field descending",
+			[]filter.Option{filter.WithNestedJSONB("customdata", "created_at")},
+			`{"map": -1}`,
+			`(CASE WHEN jsonb_typeof(customdata->'map') = 'number' THEN ("customdata"->>'map')::numeric END) DESC NULLS LAST, "customdata"->>'map' DESC NULLS LAST`,
+			nil,
+		},
+		{
+			"nested JSONB multiple fields",
+			[]filter.Option{filter.WithNestedJSONB("customdata", "created_at")},
+			`{"map": 1, "bar": -1}`,
+			`(CASE WHEN jsonb_typeof(customdata->'map') = 'number' THEN ("customdata"->>'map')::numeric END) ASC NULLS LAST, "customdata"->>'map' ASC NULLS LAST, (CASE WHEN jsonb_typeof(customdata->'bar') = 'number' THEN ("customdata"->>'bar')::numeric END) DESC NULLS LAST, "customdata"->>'bar' DESC NULLS LAST`,
+			nil,
+		},
+		{
+			"mixed nested and regular fields",
+			[]filter.Option{filter.WithNestedJSONB("customdata", "created_at")},
+			`{"created_at": 1, "map": -1}`,
+			`"created_at" ASC, (CASE WHEN jsonb_typeof(customdata->'map') = 'number' THEN ("customdata"->>'map')::numeric END) DESC NULLS LAST, "customdata"->>'map' DESC NULLS LAST`,
+			nil,
+		},
+		{
+			"field name with spaces",
+			[]filter.Option{filter.WithAllowAllColumns()},
+			`{"my_field": 1}`,
+			`"my_field" ASC`,
+			nil,
+		},
+		{
+			"empty object",
+			[]filter.Option{filter.WithAllowAllColumns()},
+			`{}`,
+			``,
+			nil,
+		},
+		{
+			"invalid field name for SQL injection",
+			[]filter.Option{filter.WithAllowAllColumns()},
+			`{"my field": 1}`,
+			``,
+			fmt.Errorf("invalid column name: my field"),
+		},
+		{
+			"invalid direction value",
+			[]filter.Option{filter.WithAllowAllColumns()},
+			`{"playerCount": 2}`,
+			``,
+			filter.InvalidOrderDirectionError{Field: "playerCount", Value: json.Number("2")},
+		},
+		{
+			"invalid direction string",
+			[]filter.Option{filter.WithAllowAllColumns()},
+			`{"playerCount": "asc"}`,
+			``,
+			filter.InvalidOrderDirectionError{Field: "playerCount", Value: "asc"},
+		},
+		{
+			"disallowed column",
+			[]filter.Option{filter.WithAllowColumns("name")},
+			`{"playerCount": 1}`,
+			``,
+			filter.ColumnNotAllowedError{Column: "playerCount"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			converter, err := filter.NewConverter(tt.options...)
+			if err != nil {
+				t.Fatalf("Failed to create converter: %v", err)
+			}
+
+			result, err := converter.ConvertOrderBy([]byte(tt.input))
+
+			if tt.err != nil {
+				if err == nil {
+					t.Fatalf("Expected error %v, got nil", tt.err)
+				}
+				if err.Error() != tt.err.Error() {
+					t.Errorf("Expected error %v, got %v", tt.err, err)
+				}
+				return
+			}
+
+			if err != nil {
+				t.Fatalf("Unexpected error: %v", err)
+			}
+
+			if result != tt.expected {
+				t.Errorf("Expected %q, got %q", tt.expected, result)
+			}
+		})
+	}
+}

filter/errors.go

@@ -12,3 +12,12 @@ type ColumnNotAllowedError struct {
 func (e ColumnNotAllowedError) Error() string {
 	return fmt.Sprintf("column not allowed: %s", e.Column)
 }
+
+type InvalidOrderDirectionError struct {
+	Field string
+	Value any
+}
+
+func (e InvalidOrderDirectionError) Error() string {
+	return fmt.Sprintf("invalid order direction for field %s: %v (must be 1 or -1)", e.Field, e.Value)
+}

filter/util.go

@@ -1,5 +1,11 @@
 package filter
 
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+)
+
 func isNumeric(v any) bool {
 	// json.Unmarshal returns float64 for all numbers
 	// so we only need to check for float64.
@@ -71,3 +77,47 @@ func isValidPostgresIdentifier(s string) bool {
 
 	return true
 }
+
+func objectInOrder(b []byte) ([]struct{ Key string; Value any }, error) {
+	dec := json.NewDecoder(bytes.NewReader(b))
+	dec.UseNumber()
+
+	// expect {
+	tok, err := dec.Token()
+	if err != nil {
+		return nil, err
+	}
+	if d, ok := tok.(json.Delim); !ok || d != '{' {
+		return nil, fmt.Errorf("expected object, got %v", tok)
+	}
+
+	var result []struct{ Key string; Value any }
+
+	for dec.More() {
+		// key
+		tok, err := dec.Token()
+		if err != nil {
+			return nil, err
+		}
+		key, ok := tok.(string)
+		if !ok {
+			return nil, fmt.Errorf("expected string key, got %v", tok)
+		}
+
+		// value
+		var v any
+		if err := dec.Decode(&v); err != nil {
+			return nil, err
+		}
+
+		result = append(result, struct{ Key string; Value any }{Key: key, Value: v})
+	}
+
+	// consume }
+	_, err = dec.Token()
+	if err != nil {
+		return nil, err
+	}
+
+	return result, nil
+}