feat: add db.collection.distinct() operation support (#10)

Add support for the distinct() method which returns an array of unique
values for a specified field across a collection.

Syntax:
- db.collection.distinct("field")
- db.collection.distinct("field", { filter })

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: h3n4l

executor.go

@@ -2,6 +2,7 @@ package gomongo
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
 
 	"github.com/antlr4-go/antlr/v4"
@@ -79,6 +80,8 @@ func executeOperation(ctx context.Context, client *mongo.Client, database string
 		return executeCountDocuments(ctx, client, database, op)
 	case opEstimatedDocumentCount:
 		return executeEstimatedDocumentCount(ctx, client, database, op)
+	case opDistinct:
+		return executeDistinct(ctx, client, database, op)
 	default:
 		return nil, &UnsupportedOperationError{
 			Operation: statement,
@@ -376,3 +379,51 @@ func executeEstimatedDocumentCount(ctx context.Context, client *mongo.Client, da
 		RowCount: 1,
 	}, nil
 }
+
+// executeDistinct executes a db.collection.distinct() command.
+func executeDistinct(ctx context.Context, client *mongo.Client, database string, op *mongoOperation) (*Result, error) {
+	collection := client.Database(database).Collection(op.collection)
+
+	filter := op.filter
+	if filter == nil {
+		filter = bson.D{}
+	}
+
+	result := collection.Distinct(ctx, op.distinctField, filter)
+	if err := result.Err(); err != nil {
+		return nil, fmt.Errorf("distinct failed: %w", err)
+	}
+
+	var values []any
+	if err := result.Decode(&values); err != nil {
+		return nil, fmt.Errorf("decode failed: %w", err)
+	}
+
+	var rows []string
+	for _, val := range values {
+		jsonBytes, err := marshalValue(val)
+		if err != nil {
+			return nil, fmt.Errorf("marshal failed: %w", err)
+		}
+		rows = append(rows, string(jsonBytes))
+	}
+
+	return &Result{
+		Rows:     rows,
+		RowCount: len(rows),
+	}, nil
+}
+
+// marshalValue marshals a value to JSON.
+// bson.MarshalExtJSONIndent only works for documents/arrays at top level,
+// so we use encoding/json for primitive values (strings, numbers, booleans).
+func marshalValue(val any) ([]byte, error) {
+	switch v := val.(type) {
+	case bson.M, bson.D, map[string]any:
+		return bson.MarshalExtJSONIndent(v, false, false, "", "  ")
+	case bson.A, []any:
+		return bson.MarshalExtJSONIndent(v, false, false, "", "  ")
+	default:
+		return json.Marshal(v)
+	}
+}

executor_test.go

@@ -1755,3 +1755,138 @@ func TestEstimatedDocumentCountWithEmptyOptions(t *testing.T) {
 	require.NotNil(t, result)
 	require.Equal(t, "2", result.Rows[0])
 }
+
+func TestDistinct(t *testing.T) {
+	client, cleanup := setupTestContainer(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a collection with documents
+	collection := client.Database("testdb").Collection("users")
+	_, err := collection.InsertMany(ctx, []any{
+		bson.M{"name": "alice", "status": "active"},
+		bson.M{"name": "bob", "status": "inactive"},
+		bson.M{"name": "charlie", "status": "active"},
+		bson.M{"name": "diana", "status": "active"},
+	})
+	require.NoError(t, err)
+
+	gc := gomongo.NewClient(client)
+
+	// Test distinct on status field
+	result, err := gc.Execute(ctx, "testdb", `db.users.distinct("status")`)
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	require.Equal(t, 2, result.RowCount)
+
+	// Verify both values are present
+	values := make(map[string]bool)
+	for _, row := range result.Rows {
+		values[row] = true
+	}
+	require.True(t, values[`"active"`] || values[`"inactive"`])
+}
+
+func TestDistinctWithFilter(t *testing.T) {
+	client, cleanup := setupTestContainer(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a collection with documents
+	collection := client.Database("testdb").Collection("products")
+	_, err := collection.InsertMany(ctx, []any{
+		bson.M{"category": "electronics", "brand": "Apple", "price": 999},
+		bson.M{"category": "electronics", "brand": "Samsung", "price": 799},
+		bson.M{"category": "electronics", "brand": "Apple", "price": 1299},
+		bson.M{"category": "clothing", "brand": "Nike", "price": 99},
+		bson.M{"category": "clothing", "brand": "Adidas", "price": 89},
+	})
+	require.NoError(t, err)
+
+	gc := gomongo.NewClient(client)
+
+	// Test distinct with filter
+	result, err := gc.Execute(ctx, "testdb", `db.products.distinct("brand", { category: "electronics" })`)
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	require.Equal(t, 2, result.RowCount)
+
+	// Verify only electronics brands are returned
+	values := make(map[string]bool)
+	for _, row := range result.Rows {
+		values[row] = true
+	}
+	require.True(t, values[`"Apple"`])
+	require.True(t, values[`"Samsung"`])
+	require.False(t, values[`"Nike"`])
+	require.False(t, values[`"Adidas"`])
+}
+
+func TestDistinctEmptyCollection(t *testing.T) {
+	client, cleanup := setupTestContainer(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	gc := gomongo.NewClient(client)
+
+	// Test distinct on empty/non-existent collection
+	result, err := gc.Execute(ctx, "testdb", `db.users.distinct("status")`)
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	require.Equal(t, 0, result.RowCount)
+	require.Empty(t, result.Rows)
+}
+
+func TestDistinctBracketNotation(t *testing.T) {
+	client, cleanup := setupTestContainer(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a collection with hyphenated name
+	collection := client.Database("testdb").Collection("user-logs")
+	_, err := collection.InsertMany(ctx, []any{
+		bson.M{"level": "info"},
+		bson.M{"level": "warn"},
+		bson.M{"level": "error"},
+		bson.M{"level": "info"},
+	})
+	require.NoError(t, err)
+
+	gc := gomongo.NewClient(client)
+
+	// Test with bracket notation
+	result, err := gc.Execute(ctx, "testdb", `db["user-logs"].distinct("level")`)
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	require.Equal(t, 3, result.RowCount)
+}
+
+func TestDistinctNumericValues(t *testing.T) {
+	client, cleanup := setupTestContainer(t)
+	defer cleanup()
+
+	ctx := context.Background()
+
+	// Create a collection with numeric values
+	collection := client.Database("testdb").Collection("scores")
+	_, err := collection.InsertMany(ctx, []any{
+		bson.M{"score": 100},
+		bson.M{"score": 85},
+		bson.M{"score": 100},
+		bson.M{"score": 90},
+		bson.M{"score": 85},
+	})
+	require.NoError(t, err)
+
+	gc := gomongo.NewClient(client)
+
+	// Test distinct on numeric field
+	result, err := gc.Execute(ctx, "testdb", `db.scores.distinct("score")`)
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	require.Equal(t, 3, result.RowCount) // 100, 85, 90
+}

translator.go

@@ -24,6 +24,7 @@ const (
 	opGetIndexes
 	opCountDocuments
 	opEstimatedDocumentCount
+	opDistinct
 )
 
 // mongoOperation represents a parsed MongoDB operation.
@@ -40,6 +41,8 @@ type mongoOperation struct {
 	pipeline bson.A
 	// countDocuments options
 	hint any // string (index name) or document (index spec)
+	// distinct field name
+	distinctField string
 }
 
 // mongoShellVisitor extracts operations from a parse tree.
@@ -177,6 +180,81 @@ func (v *mongoShellVisitor) extractGetCollectionInfosArgs(ctx *mongodb.GetCollec
 	v.operation.filter = filter
 }
 
+func (v *mongoShellVisitor) extractDistinctArgs(ctx *mongodb.GenericMethodContext) {
+	args := ctx.Arguments()
+	if args == nil {
+		v.err = fmt.Errorf("distinct() requires a field name argument")
+		return
+	}
+
+	argsCtx, ok := args.(*mongodb.ArgumentsContext)
+	if !ok {
+		v.err = fmt.Errorf("distinct() requires a field name argument")
+		return
+	}
+
+	allArgs := argsCtx.AllArgument()
+	if len(allArgs) == 0 {
+		v.err = fmt.Errorf("distinct() requires a field name argument")
+		return
+	}
+
+	// First argument is the field name (required)
+	firstArg, ok := allArgs[0].(*mongodb.ArgumentContext)
+	if !ok {
+		v.err = fmt.Errorf("distinct() requires a field name argument")
+		return
+	}
+
+	valueCtx := firstArg.Value()
+	if valueCtx == nil {
+		v.err = fmt.Errorf("distinct() requires a field name argument")
+		return
+	}
+
+	literalValue, ok := valueCtx.(*mongodb.LiteralValueContext)
+	if !ok {
+		v.err = fmt.Errorf("distinct() field name must be a string")
+		return
+	}
+
+	stringLiteral, ok := literalValue.Literal().(*mongodb.StringLiteralValueContext)
+	if !ok {
+		v.err = fmt.Errorf("distinct() field name must be a string")
+		return
+	}
+
+	v.operation.distinctField = unquoteString(stringLiteral.StringLiteral().GetText())
+
+	// Second argument is the filter (optional)
+	if len(allArgs) < 2 {
+		return
+	}
+
+	secondArg, ok := allArgs[1].(*mongodb.ArgumentContext)
+	if !ok {
+		return
+	}
+
+	filterValueCtx := secondArg.Value()
+	if filterValueCtx == nil {
+		return
+	}
+
+	docValue, ok := filterValueCtx.(*mongodb.DocumentValueContext)
+	if !ok {
+		v.err = fmt.Errorf("distinct() filter must be a document")
+		return
+	}
+
+	filter, err := convertDocument(docValue.Document())
+	if err != nil {
+		v.err = fmt.Errorf("invalid filter: %w", err)
+		return
+	}
+	v.operation.filter = filter
+}
+
 func (v *mongoShellVisitor) extractCountDocumentsArgs(ctx *mongodb.GenericMethodContext) {
 	args := ctx.Arguments()
 	if args == nil {
@@ -527,6 +605,9 @@ func (v *mongoShellVisitor) visitMethodCall(ctx mongodb.IMethodCallContext) {
 			v.extractCountDocumentsArgs(gmCtx)
 		case "estimatedDocumentCount":
 			v.operation.opType = opEstimatedDocumentCount
+		case "distinct":
+			v.operation.opType = opDistinct
+			v.extractDistinctArgs(gmCtx)
 		default:
 			v.err = &UnsupportedOperationError{
 				Operation: methodName,