Update godocs for release

Co-authored-by: Erik Dubbelboer <[email protected]>

Author: koenbollen

filter/converter.go

@@ -20,11 +20,12 @@ var basicOperatorMap = map[string]string{
 	"$regex": "~*",
 }
 
-// DefaultPlaceholderName is the default placeholder name used in the generated SQL query.
+// defaultPlaceholderName is the default placeholder name used in the generated SQL query.
 // This name should not be used in the database or any JSONB column. It can be changed using
 // the WithPlaceholderName option.
-const DefaultPlaceholderName = "__filter_placeholder"
+const defaultPlaceholderName = "__filter_placeholder"
 
+// Converter converts MongoDB filter queries to SQL conditions and values. Use [filter.NewConverter] to create a new instance.
 type Converter struct {
 	nestedColumn     string
 	nestedExemptions []string
@@ -38,9 +39,9 @@ type Converter struct {
 	once sync.Once
 }
 
-// NewConverter creates a new Converter with optional nested JSONB field mapping.
+// NewConverter creates a new [Converter] with optional nested JSONB field mapping.
 //
-// Note: When using github.com/lib/pq, the filter.WithArrayDriver should be set to pq.Array.
+// Note: When using https://github.com/lib/pq, the [filter.WithArrayDriver] should be set to pq.Array.
 func NewConverter(options ...Option) *Converter {
 	converter := &Converter{
 		// don't set defaults, use the once.Do in #Convert()
@@ -63,7 +64,7 @@ func (c *Converter) Convert(query []byte, startAtParameterIndex int) (conditions
 			c.emptyCondition = "FALSE"
 		}
 		if c.placeholderName == "" {
-			c.placeholderName = DefaultPlaceholderName
+			c.placeholderName = defaultPlaceholderName
 		}
 	})
 

filter/converter_test.go

@@ -1,13 +1,35 @@
 package filter_test
 
 import (
+	"database/sql"
 	"fmt"
 	"reflect"
 	"testing"
 
 	"github.com/poki/mongodb-filter-to-postgres/filter"
 )
 
+func ExampleNewConverter() {
+	// Remeber to use `filter.WithArrayDriver(pg.Array)` when using github.com/lib/pq
+	converter := filter.NewConverter(filter.WithNestedJSONB("meta", "created_at", "updated_at"))
+
+	mongoFilterQuery := `{
+		"name": "John",
+		"created_at": {
+			"$gte": "2020-01-01T00:00:00Z"
+		}
+	}`
+	conditions, values, err := converter.Convert([]byte(mongoFilterQuery), 1)
+	if err != nil {
+		// handle error
+	}
+
+	var db *sql.DB // setup your database connection
+
+	db.Query("SELECT * FROM users WHERE "+conditions, values)
+	// SELECT * FROM users WHERE (("created_at" >= $1) AND ("meta"->>'name' = $2)), 2020-01-01T00:00:00Z, "John"
+}
+
 func TestConverter_Convert(t *testing.T) {
 	tests := []struct {
 		name       string
@@ -427,3 +449,14 @@ func TestConverter_NoConstructor(t *testing.T) {
 		t.Errorf("Converter.Convert() values = %v, want nil", values)
 	}
 }
+
+func TestConverter_CopyReference(t *testing.T) {
+	c := filter.Converter{}
+	conditions, _, err := c.Convert([]byte(``), 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := "FALSE"; conditions != want {
+		t.Errorf("Converter.Convert() conditions = %v, want %v", conditions, want)
+	}
+}

filter/doc.go

@@ -0,0 +1,5 @@
+// This package converts MongoDB query filters into PostgreSQL WHERE clauses.
+// It's designed to be simple, secure, and free of dependencies.
+//
+// See: https://www.mongodb.com/docs/compass/current/query/filter
+package filter