API changes

Author: cherylEnkidu

Firestore/Swift/Source/Helper/PipelineHelper.swift

@@ -13,10 +13,6 @@
 // limitations under the License.
 
 enum Helper {
-  static func exprConvertFrom(_ value: Any) -> any Expr {
-    return Field("PLACEHOLDER")
-  }
-
   static func valueToDefaultExpr(_ value: Any) -> any Expr {
     return Field("PLACEHOLDER")
   }

Firestore/Swift/Source/SwiftAPI/Pipeline/AggregateOption.swift

@@ -14,9 +14,9 @@
 
 public struct AggregateOption {
   public let accumulators: [AggregateWithAlias]
-  public let groups: [SelectableOrFieldName]?
+  public let groups: [Selectable]?
 
-  public init(accumulators: [AggregateWithAlias], groups: [SelectableOrFieldName]? = nil) {
+  public init(accumulators: [AggregateWithAlias], groups: [Selectable]? = nil) {
     self.accumulators = accumulators
     self.groups = groups
   }

Firestore/Swift/Source/SwiftAPI/Pipeline/ArrayContains.swift

@@ -0,0 +1,19 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+public class ArrayContains: BooleanExpr, @unchecked Sendable {
+  public init(_ values: Any...) {
+    super.init("array_concat", values as! [any Expr])
+  }
+}

Firestore/Swift/Source/SwiftAPI/Pipeline/Ascending.swift

@@ -0,0 +1,19 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+public class Ascending: Ordering, @unchecked Sendable {
+  public init(_ fieldName: String) {
+    super.init(expr: Field(fieldName), direction: .ascending)
+  }
+}

Firestore/Swift/Source/SwiftAPI/Pipeline/Descending.swift

@@ -0,0 +1,19 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+public class Descending: Ordering, @unchecked Sendable {
+  public init(_ fieldName: String) {
+    super.init(expr: Field(fieldName), direction: .descending)
+  }
+}

Firestore/Swift/Source/SwiftAPI/Pipeline/Expr.swift

@@ -13,7 +13,7 @@
 // limitations under the License.
 
 public protocol Expr: Sendable {
-  func alias(_ name: String) -> ExprWithAlias
+  func `as`(_ name: String) -> ExprWithAlias
 
   // MARK: Comparison Operators
 
@@ -221,7 +221,7 @@ public protocol Expr: Sendable {
 }
 
 public extension Expr {
-  func alias(_ name: String) -> ExprWithAlias {
+  func `as`(_ name: String) -> ExprWithAlias {
     return ExprWithAlias(self, name)
   }
 
@@ -794,3 +794,22 @@ public extension Expr {
     return Ordering(expr: self, direction: .descending)
   }
 }
+
+// protocal cannot overwrite operator, since every inheritated class will have this function
+// it will lead to error: Generic parameter 'Self' could not be inferred
+
+public func > (lhs: Expr, rhs: @autoclosure () throws -> Any) rethrows -> BooleanExpr {
+  try BooleanExpr("gt", [lhs, Helper.valueToDefaultExpr(rhs())])
+}
+
+public func < (lhs: Expr, rhs: @autoclosure () throws -> Any) rethrows -> BooleanExpr {
+  try BooleanExpr("lt", [lhs, Helper.valueToDefaultExpr(rhs())])
+}
+
+public func <= (lhs: Expr, rhs: @autoclosure () throws -> Any) rethrows -> BooleanExpr {
+  try BooleanExpr("lte", [lhs, Helper.valueToDefaultExpr(rhs())])
+}
+
+public func == (lhs: Expr, rhs: @autoclosure () throws -> Any) rethrows -> BooleanExpr {
+  try BooleanExpr("eq", [lhs, Helper.valueToDefaultExpr(rhs())])
+}

Firestore/Swift/Source/SwiftAPI/Pipeline/Expr/FunctionExpr/BooleanExpr.swift

@@ -16,4 +16,23 @@ public class BooleanExpr: FunctionExpr, @unchecked Sendable {
   public static func and(_ value: Expr ...) -> BooleanExpr {
     return BooleanExpr("and", value)
   }
+
+  override init(_ functionName: String, _ agrs: [any Expr]) {
+    super.init(functionName, agrs)
+  }
+
+  public static func && (lhs: BooleanExpr,
+                         rhs: @autoclosure () throws -> BooleanExpr) rethrows -> BooleanExpr {
+    try BooleanExpr("and", [lhs, rhs()])
+  }
+
+  public static func || (lhs: BooleanExpr,
+                         rhs: @autoclosure () throws -> BooleanExpr) rethrows -> BooleanExpr {
+    try BooleanExpr("or", [lhs, rhs()])
+  }
+
+  // not
+  public static prefix func ! (lhs: BooleanExpr) -> BooleanExpr {
+    return BooleanExpr("not", [lhs])
+  }
 }

Firestore/Swift/Source/SwiftAPI/Pipeline/Ordering.swift

@@ -14,9 +14,14 @@
  * limitations under the License.
  */
 
-public struct Ordering {
+public class Ordering: @unchecked Sendable {
   let expr: Expr
   let direction: Direction
+
+  init(expr: Expr, direction: Direction) {
+    self.expr = expr
+    self.direction = direction
+  }
 }
 
 public struct Direction: Sendable, Equatable, Hashable {

Firestore/Swift/Source/SwiftAPI/Pipeline/Pipeline.swift

@@ -64,9 +64,27 @@ public struct Pipeline {
   /// only additions are desired.
   ///
   /// - Parameter selections: The fields to include in the output documents, specified as
-  /// `Selectable` expressions or `String` values representing field names.
+  /// `Selectable` expressions.
   /// - Returns: A new `Pipeline` object with this stage appended to the stage list.
-  public func select(_ selections: SelectableOrFieldName...) -> Pipeline {
+  public func select(_ selections: Selectable...) -> Pipeline {
+    // Implementation
+    return self
+  }
+
+  /// Selects or creates a set of fields from the outputs of previous stages.
+  ///
+  /// The selected fields are defined using `Selectable` expressions, which can be:
+  ///
+  /// - `String`: Name of an existing field.
+  /// - `Field`: References an existing field.
+  /// - `Function`: Represents the result of a function with an assigned alias name using `Expr#as`.
+  ///
+  /// If no selections are provided, the output of this stage is empty. Use `addFields` instead if
+  /// only additions are desired.
+  ///
+  /// - Parameter selections: `String` values representing field names.
+  /// - Returns: A new `Pipeline` object with this stage appended to the stage list.
+  public func select(_ selections: String...) -> Pipeline {
     // Implementation
     return self
   }
@@ -87,7 +105,7 @@ public struct Pipeline {
   ///
   /// - Parameter condition: The `BooleanExpr` to apply.
   /// - Returns: A new `Pipeline` object with this stage appended to the stage list.
-  public func `where`(_ condition: BooleanExpr) -> Pipeline {
+  public func `where`(_ condition: () -> BooleanExpr) -> Pipeline {
     return self
   }
 
@@ -131,8 +149,26 @@ public struct Pipeline {
   /// `Expr.alias(_:)`.
   ///
   /// - Parameter selections: The fields to include in the output documents, specified as
-  /// `Selectable` expressions or `String` values representing field names.
-  public func distinct(_ groups: SelectableOrFieldName...) -> Pipeline {
+  ///  `String` values representing field names.
+  public func distinct(_ groups: String...) -> Pipeline {
+    return self
+  }
+
+  /// Returns a set of distinct `Expr` values from the inputs to this stage.
+  ///
+  /// This stage processes the results from previous stages, ensuring that only unique
+  /// combinations of `Expr` values (such as `Field` and `Function`) are included.
+  ///
+  /// The parameters to this stage are defined using `Selectable` expressions or field names:
+  ///
+  /// - `String`: The name of an existing field.
+  /// - `Field`: A reference to an existing document field.
+  /// - `Function`: Represents the result of a function with an assigned alias using
+  /// `Expr.alias(_:)`.
+  ///
+  /// - Parameter selections: The fields to include in the output documents, specified as
+  /// `Selectable` expressions.
+  public func distinct(_ groups: Selectable...) -> Pipeline {
     return self
   }
 
@@ -188,7 +224,7 @@ public struct Pipeline {
   ///
   /// - Parameter orderings: One or more `Ordering` instances specifying the sorting criteria.
   /// - Returns: A new `Pipeline` object with this stage appended to the stage list.
-  public func sort(_ orderings: [Ordering]) -> Pipeline {
+  public func sort(_ orderings: Ordering...) -> Pipeline {
     // Implementation
     return self
   }
@@ -200,7 +236,19 @@ public struct Pipeline {
   ///
   /// - Parameter field: The `Selectable` field containing the nested map.
   /// - Returns: A new `Pipeline` object with this stage appended to the stage list.
-  public func replace(_ field: SelectableOrFieldName) -> Pipeline {
+  public func replace(_ field: Selectable) -> Pipeline {
+    // Implementation
+    return self
+  }
+
+  /// Fully overwrites all fields in a document with those coming from a nested map.
+  ///
+  /// This stage allows you to emit a map value as a document. Each key of the map becomes a
+  /// field on the document that contains the corresponding value.
+  ///
+  /// - Parameter fieldName: The field containing the nested map.
+  /// - Returns: A new `Pipeline` object with this stage appended to the stage list.
+  public func replace(_ fieldName: String) -> Pipeline {
     // Implementation
     return self
   }

Firestore/Swift/Source/SwiftAPI/Pipeline/PipelineSource.swift

@@ -40,11 +40,11 @@ public struct PipelineSource {
     return Pipeline(db)
   }
 
-  public func createFrom(_ query: Query) -> Pipeline {
+  public func create(from query: Query) -> Pipeline {
     return Pipeline(db)
   }
 
-  public func createFrom(_ aggregateQuery: AggregateQuery) -> Pipeline {
+  public func create(from aggregateQuery: AggregateQuery) -> Pipeline {
     return Pipeline(db)
   }
 }

Firestore/Swift/Source/SwiftAPI/Pipeline/SelectableOrFieldName.swift

@@ -29,22 +29,19 @@ final class PipelineTests: FSTIntegrationTestCase {
     let _: Pipeline = pipelineSource.database()
 
     let query: Query = db.collection("foo").limit(to: 2)
-    let _: Pipeline = pipelineSource.createFrom(query)
+    let _: Pipeline = pipelineSource.create(from: query)
 
     let aggregateQuery = db.collection("foo").count
-    let _: Pipeline = pipelineSource.createFrom(aggregateQuery)
+    let _: Pipeline = pipelineSource.create(from: aggregateQuery)
 
     let _: PipelineSnapshot = try await pipeline.execute()
   }
 
   func testWhereStage() async throws {
     _ = db.pipeline().collection("books")
-      .where(
-        BooleanExpr.and(
-          Field("rating").gt(4.0), // Filter for ratings greater than 4.0
-          Field("genre").eq("Science Fiction")
-        )
-      )
+      .where {
+        Field("rating") > 4.0 && Field("genre") == "Science Fiction" || ArrayContains("rating")
+      }
   }
 
   func testAddFieldStage() async throws {
@@ -58,7 +55,7 @@ final class PipelineTests: FSTIntegrationTestCase {
 
     // An expression becomes a Selectable when given an alias. In this case
     // the alias is 'salePrice'
-    let priceSelectableExpr: Selectable = priceExpr.alias("salePrice")
+    let priceSelectableExpr: Selectable = priceExpr.as("salePrice")
 
     _ = db.pipeline().collection("books")
       .addFields(
@@ -71,12 +68,43 @@ final class PipelineTests: FSTIntegrationTestCase {
     // is to inline the Expr definition
     _ = db.pipeline().collection("books")
       .addFields(
-        Field("msrp").multiply(Field("discount")).alias("salePrice")
+        Field("msrp").multiply(Field("discount")).as("salePrice")
       )
 
     // Output
     // { title: 'title1', price: 10, discount: 0.8,  salePrice: 8.0},
     // { title: 'title2', price: 12, discount: 1.0,  salePrice: 12.0 },
     // { title: 'title3', price: 5,  discount: 0.66, salePrice: 3.30 }
   }
+
+  func testSelectStage() async throws {
+    // Input
+    // { title: 'title1', price: 10, discount: 0.8 },
+    // { title: 'title2', price: 12, discount: 1.0 },
+    // { title: 'title3', price: 5,  discount: 0.66 }
+
+    // Overload for string and Selectable
+    _ = db.pipeline().collection("books")
+      .select(
+        Field("title"), // Field class inheritates Selectable
+        Field("msrp").multiply(Field("discount")).as("salePrice")
+      )
+
+    _ = db.pipeline().collection("books").select("title", "author")
+
+    // Output
+    // { title: 'title1', salePrice: 8.0},
+    // { title: 'title2', salePrice: 12.0 },
+    // { title: 'title3', salePrice: 3.30 }
+  }
+
+  func testSortStage() async throws {
+    // Sort books by rating in descending order, and then by title in ascending order for books
+    // with the same rating
+    _ = db.pipeline().collection("books")
+      .sort(
+        Field("rating").descending(),
+        Ascending("title") // alternative API offered
+      )
+  }
 }