feat(firestore): refine Pipelines API, error handling, and integration tests

Author: bhshkh

firestore/integration_test.go

@@ -16,12 +16,20 @@ package firestore
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"reflect"
 
 	pb "cloud.google.com/go/firestore/apiv1/firestorepb"
 )
 
+var (
+	// ErrPipelineWithoutDatabase is returned when a pipeline is executed without a database such as a subcollection pipeline.
+	ErrPipelineWithoutDatabase = errors.New("firestore: pipeline without a database cannot be executed directly, only as part of another pipeline")
+	// ErrUnionNotSupportRelativeScope is returned when a union is used with a relative scope pipeline.
+	ErrUnionNotSupportRelativeScope = errors.New("firestore: union only supports combining root pipelines; relative scope pipelines (like subcollection pipelines) are not supported")
+)
+
 // Pipeline class provides a flexible and expressive framework for building complex data
 // transformation and query pipelines for Firestore.
 //
@@ -256,7 +264,7 @@ func (p *Pipeline) Execute(ctx context.Context, opts ...ExecuteOption) *Pipeline
 	}
 
 	if newP.c == nil {
-		newP.err = fmt.Errorf("pipeline created without a database (e.g., as a subcollection pipeline) cannot be executed directly; it can only be used as part of another pipeline")
+		newP.err = ErrPipelineWithoutDatabase
 		return &PipelineSnapshot{
 			iter: &PipelineResultIterator{
 				err: newP.err,
@@ -900,7 +908,7 @@ func (p *Pipeline) Union(other *Pipeline, opts ...UnionOption) *Pipeline {
 		return p
 	}
 	if other.c == nil {
-		p.err = fmt.Errorf("union only supports combining root pipelines; relative scope pipelines (like subcollection pipelines) are not supported")
+		p.err = ErrUnionNotSupportRelativeScope
 		return p
 	}
 	options := make(map[string]any)

firestore/pipeline.go

@@ -174,11 +174,11 @@ type Expression interface {
 	//
 	// The parameter 'offset' is the 0-based index of the first element to include. It can be an int, int32, int64 or [Expression].
 	ArraySlice(offset any) Expression
-	// ArraySliceWithLength creates an expression that returns a slice of an array starting from the specified offset with a given length.
+	// ArraySliceToEnd creates an expression that returns a slice of an array starting from the specified offset with a given length.
 	//
 	// The parameter 'offset' is the 0-based index of the first element to include. It can be an int, int32, int64 or [Expression].
 	// The parameter 'length' is the number of elements to include. It can be an int, int32, int64 or [Expression].
-	ArraySliceWithLength(offset, length any) Expression
+	ArraySliceToEnd(offset, length any) Expression
 	// ArrayIndexOf creates an expression that returns the first index of a search value in an array.
 	//
 	// The parameter 'search' is the value to search for. It can be a constant or [Expression].
@@ -205,12 +205,11 @@ type Expression interface {
 	// If the expression resolves to an absent value, it is converted to NULL.
 	// The order of elements in the output array is not stable and shouldn't be relied upon.
 	ArrayAggDistinct() AggregateFunction
-	// TODO: Uncomment this after fixing the proto representation of this function.
 	// ArrayFilter creates an expression for array_filter(array, param, body).
 	//
 	// The parameter 'param' is the name of the parameter to use in the body expression.
 	// The parameter 'body' is the expression to evaluate for each element of the array.
-	// ArrayFilter(param string, body BooleanExpression) Expression
+	ArrayFilter(param string, body BooleanExpression) Expression
 	// LogicalMaximum returns the maximum value of the expression and the specified values.
 	LogicalMaximum(others ...any) Expression
 	// LogicalMinimum returns the minimum value of the expression and the specified values.
@@ -242,7 +241,7 @@ type Expression interface {
 	// "week(wednesday)", "week(thursday)", "week(friday)", "week(saturday)", "week(sunday)", "isoweek", "month", "quarter", "year", and "isoyear".
 	// The parameter 'timezone' can be a string constant (e.g., "America/Los_Angeles") or an [Expression] that evaluates to a valid timezone string.
 	// Valid values are from the TZ database or in the format "Etc/GMT-1".
-	TimestampTruncateWithTimezone(granularity any, timezone string) Expression
+	TimestampTruncateWithTimezone(granularity any, timezone any) Expression
 	// TimestampToUnixMicros creates an expression that converts a timestamp expression to the number of microseconds since
 	// the Unix epoch (1970-01-01 00:00:00 UTC).
 	TimestampToUnixMicros() Expression
@@ -588,8 +587,8 @@ func (b *baseExpression) ArrayFirstN(n any) Expression     { return ArrayFirstN(
 func (b *baseExpression) ArrayLast() Expression            { return ArrayLast(b) }
 func (b *baseExpression) ArrayLastN(n any) Expression      { return ArrayLastN(b, n) }
 func (b *baseExpression) ArraySlice(offset any) Expression { return ArraySlice(b, offset) }
-func (b *baseExpression) ArraySliceWithLength(offset, length any) Expression {
-	return ArraySliceLength(b, offset, length)
+func (b *baseExpression) ArraySliceToEnd(offset, length any) Expression {
+	return ArraySliceToEnd(b, offset, length)
 }
 func (b *baseExpression) ArrayIndexOf(search any) Expression {
 	return ArrayIndexOf(b, search)
@@ -605,11 +604,9 @@ func (b *baseExpression) Last() AggregateFunction             { return Last(b) }
 func (b *baseExpression) ArrayAgg() AggregateFunction         { return ArrayAgg(b) }
 func (b *baseExpression) ArrayAggDistinct() AggregateFunction { return ArrayAggDistinct(b) }
 
-// TODO: Uncomment this after fixing the proto representation of this function.
-//
-//	func (b *baseExpression) ArrayFilter(param string, body BooleanExpression) Expression {
-//		return ArrayFilter(b, param, body)
-//	}
+func (b *baseExpression) ArrayFilter(param string, body BooleanExpression) Expression {
+	return ArrayFilter(b, param, body)
+}
 func (b *baseExpression) LogicalMaximum(others ...any) Expression {
 	return LogicalMaximum(b, others...)
 }
@@ -627,7 +624,7 @@ func (b *baseExpression) TimestampSubtract(unit, amount any) Expression {
 func (b *baseExpression) TimestampTruncate(granularity any) Expression {
 	return TimestampTruncate(b, granularity)
 }
-func (b *baseExpression) TimestampTruncateWithTimezone(granularity any, timezone string) Expression {
+func (b *baseExpression) TimestampTruncateWithTimezone(granularity any, timezone any) Expression {
 	return TimestampTruncateWithTimezone(b, granularity, timezone)
 }
 func (b *baseExpression) TimestampToUnixMicros() Expression  { return TimestampToUnixMicros(b) }

firestore/pipeline_expression.go

@@ -322,7 +322,7 @@ func TimestampTruncate(timestamp, granularity any) Expression {
 //
 // Experimental: Firestore Pipelines is currently in preview and is subject to potential breaking changes in future versions,
 // regardless of any other documented package stability guarantees.
-func TimestampTruncateWithTimezone(timestamp, granularity any, timezone string) Expression {
+func TimestampTruncateWithTimezone(timestamp, granularity any, timezone any) Expression {
 	return newBaseFunction("timestamp_trunc", []Expression{asFieldExpr(timestamp), asStringExpr(granularity), asStringExpr(timezone)})
 }
 
@@ -579,14 +579,14 @@ func ArraySlice(exprOrFieldPath any, offset any) Expression {
 	return newBaseFunction("array_slice", []Expression{asFieldExpr(exprOrFieldPath), asInt64Expr(offset)})
 }
 
-// ArraySliceLength creates an expression that returns a slice of an array starting from the specified offset with a given length.
+// ArraySliceToEnd creates an expression that returns a slice of an array starting from the specified offset with a given length.
 // - exprOrFieldPath can be a field path string, [FieldPath] or an [Expression] that evaluates to an array.
 // - offset is the 0-based index of the first element to include. It can be an int, int32, int64 or [Expression].
 // - length is the number of elements to include. It can be an int, int32, int64 or [Expression].
 //
 // Experimental: Firestore Pipelines is currently in preview and is subject to potential breaking changes in future versions,
 // regardless of any other documented package stability guarantees.
-func ArraySliceLength(exprOrFieldPath any, offset any, length any) Expression {
+func ArraySliceToEnd(exprOrFieldPath any, offset any, length any) Expression {
 	return newBaseFunction("array_slice", []Expression{asFieldExpr(exprOrFieldPath), asInt64Expr(offset), asInt64Expr(length)})
 }
 
@@ -597,10 +597,9 @@ func ArraySliceLength(exprOrFieldPath any, offset any, length any) Expression {
 //
 // Experimental: Firestore Pipelines is currently in preview and is subject to potential breaking changes in future versions,
 // regardless of any other documented package stability guarantees.
-// TODO: Uncomment this after fixing the proto representation of this function.
-// func ArrayFilter(array any, param string, body BooleanExpression) Expression {
-// 	return newBaseFunction("array_filter", []Expression{asFieldExpr(array), ConstantOf(param), body})
-// }
+func ArrayFilter(array any, param string, body BooleanExpression) Expression {
+	return newBaseFunction("array_filter", []Expression{asFieldExpr(array), ConstantOf(param), body})
+}
 
 // ArrayIndexOf creates an expression that returns the first index of a search value in an array.
 // - exprOrFieldPath can be a field path string, [FieldPath] or an [Expression] that evaluates to an array.

firestore/pipeline_function.go

@@ -983,7 +983,7 @@ func TestArrayFunctions(t *testing.T) {
 		},
 		{
 			desc: "ArraySliceWithLength",
-			expr: ArraySliceLength("field", 1, 2),
+			expr: ArraySliceToEnd("field", 1, 2),
 			want: &pb.Value{ValueType: &pb.Value_FunctionValue{
 				FunctionValue: &pb.Function{
 					Name: "array_slice",
@@ -995,51 +995,50 @@ func TestArrayFunctions(t *testing.T) {
 				},
 			}},
 		},
-		// TODO: Uncomment this after fixing the proto representation of this function.
-		// {
-		// 	desc: "ArrayFilter",
-		// 	expr: ArrayFilter("field", "item", FieldOf("item").GreaterThan(5)),
-		// 	want: &pb.Value{ValueType: &pb.Value_FunctionValue{
-		// 		FunctionValue: &pb.Function{
-		// 			Name: "array_filter",
-		// 			Args: []*pb.Value{
-		// 				{ValueType: &pb.Value_FieldReferenceValue{FieldReferenceValue: "field"}},
-		// 				{ValueType: &pb.Value_StringValue{StringValue: "item"}},
-		// 				{ValueType: &pb.Value_FunctionValue{
-		// 					FunctionValue: &pb.Function{
-		// 						Name: "greater_than",
-		// 						Args: []*pb.Value{
-		// 							{ValueType: &pb.Value_FieldReferenceValue{FieldReferenceValue: "item"}},
-		// 							{ValueType: &pb.Value_IntegerValue{IntegerValue: 5}},
-		// 						},
-		// 					},
-		// 				}},
-		// 			},
-		// 		},
-		// 	}},
-		// },
-		// {
-		// 	desc: "baseExpression ArrayFilter",
-		// 	expr: FieldOf("field").ArrayFilter("item", FieldOf("item").GreaterThan(5)),
-		// 	want: &pb.Value{ValueType: &pb.Value_FunctionValue{
-		// 		FunctionValue: &pb.Function{
-		// 			Name: "array_filter",
-		// 			Args: []*pb.Value{
-		// 				{ValueType: &pb.Value_FieldReferenceValue{FieldReferenceValue: "field"}},
-		// 				{ValueType: &pb.Value_StringValue{StringValue: "item"}},
-		// 				{ValueType: &pb.Value_FunctionValue{
-		// 					FunctionValue: &pb.Function{
-		// 						Name: "greater_than",
-		// 						Args: []*pb.Value{
-		// 							{ValueType: &pb.Value_FieldReferenceValue{FieldReferenceValue: "item"}},
-		// 							{ValueType: &pb.Value_IntegerValue{IntegerValue: 5}},
-		// 						},
-		// 					},
-		// 				}},
-		// 			},
-		// 		},
-		// 	}},
-		// },
+		{
+			desc: "ArrayFilter",
+			expr: ArrayFilter("field", "item", FieldOf("item").GreaterThan(5)),
+			want: &pb.Value{ValueType: &pb.Value_FunctionValue{
+				FunctionValue: &pb.Function{
+					Name: "array_filter",
+					Args: []*pb.Value{
+						{ValueType: &pb.Value_FieldReferenceValue{FieldReferenceValue: "field"}},
+						{ValueType: &pb.Value_StringValue{StringValue: "item"}},
+						{ValueType: &pb.Value_FunctionValue{
+							FunctionValue: &pb.Function{
+								Name: "greater_than",
+								Args: []*pb.Value{
+									{ValueType: &pb.Value_FieldReferenceValue{FieldReferenceValue: "item"}},
+									{ValueType: &pb.Value_IntegerValue{IntegerValue: 5}},
+								},
+							},
+						}},
+					},
+				},
+			}},
+		},
+		{
+			desc: "baseExpression ArrayFilter",
+			expr: FieldOf("field").ArrayFilter("item", FieldOf("item").GreaterThan(5)),
+			want: &pb.Value{ValueType: &pb.Value_FunctionValue{
+				FunctionValue: &pb.Function{
+					Name: "array_filter",
+					Args: []*pb.Value{
+						{ValueType: &pb.Value_FieldReferenceValue{FieldReferenceValue: "field"}},
+						{ValueType: &pb.Value_StringValue{StringValue: "item"}},
+						{ValueType: &pb.Value_FunctionValue{
+							FunctionValue: &pb.Function{
+								Name: "greater_than",
+								Args: []*pb.Value{
+									{ValueType: &pb.Value_FieldReferenceValue{FieldReferenceValue: "item"}},
+									{ValueType: &pb.Value_IntegerValue{IntegerValue: 5}},
+								},
+							},
+						}},
+					},
+				},
+			}},
+		},
 		{
 			desc: "ArrayIndexOf",
 			expr: ArrayIndexOf("field", "search"),