address API feedbacks

Author: cherylEnkidu

Firestore/Swift/Source/ExprImpl.swift

@@ -121,80 +121,80 @@ public extension Expression {
   }
 
   func greaterThan(_ other: Expression) -> BooleanExpression {
-    return BooleanExpression("gt", [self, other])
+    return BooleanExpression("greater_than", [self, other])
   }
 
   func greaterThan(_ other: Sendable) -> BooleanExpression {
     let exprOther = Helper.sendableToExpr(other)
-    return BooleanExpression("gt", [self, exprOther])
+    return BooleanExpression("greater_than", [self, exprOther])
   }
 
   func greaterThanOrEqual(_ other: Expression) -> BooleanExpression {
-    return BooleanExpression("gte", [self, other])
+    return BooleanExpression("greater_than_or_equal", [self, other])
   }
 
   func greaterThanOrEqual(_ other: Sendable) -> BooleanExpression {
     let exprOther = Helper.sendableToExpr(other)
-    return BooleanExpression("gte", [self, exprOther])
+    return BooleanExpression("greater_than_or_equal", [self, exprOther])
   }
 
   func lessThan(_ other: Expression) -> BooleanExpression {
-    return BooleanExpression("lt", [self, other])
+    return BooleanExpression("less_than", [self, other])
   }
 
   func lessThan(_ other: Sendable) -> BooleanExpression {
     let exprOther = Helper.sendableToExpr(other)
-    return BooleanExpression("lt", [self, exprOther])
+    return BooleanExpression("less_than", [self, exprOther])
   }
 
   func lessThanOrEqual(_ other: Expression) -> BooleanExpression {
-    return BooleanExpression("lte", [self, other])
+    return BooleanExpression("less_than_or_equal", [self, other])
   }
 
   func lessThanOrEqual(_ other: Sendable) -> BooleanExpression {
     let exprOther = Helper.sendableToExpr(other)
-    return BooleanExpression("lte", [self, exprOther])
+    return BooleanExpression("less_than_or_equal", [self, exprOther])
   }
 
   func equal(_ other: Expression) -> BooleanExpression {
-    return BooleanExpression("eq", [self, other])
+    return BooleanExpression("equal", [self, other])
   }
 
   func equal(_ other: Sendable) -> BooleanExpression {
     let exprOther = Helper.sendableToExpr(other)
-    return BooleanExpression("eq", [self, exprOther])
+    return BooleanExpression("equal", [self, exprOther])
   }
 
   func notEqual(_ other: Expression) -> BooleanExpression {
-    return BooleanExpression("neq", [self, other])
+    return BooleanExpression("not_equal", [self, other])
   }
 
   func notEqual(_ other: Sendable) -> BooleanExpression {
-    return BooleanExpression("neq", [self, Helper.sendableToExpr(other)])
+    return BooleanExpression("not_equal", [self, Helper.sendableToExpr(other)])
   }
 
   func equalAny(_ others: [Expression]) -> BooleanExpression {
-    return BooleanExpression("eq_any", [self, Helper.array(others)])
+    return BooleanExpression("equal_any", [self, Helper.array(others)])
   }
 
   func equalAny(_ others: [Sendable]) -> BooleanExpression {
-    return BooleanExpression("eq_any", [self, Helper.array(others)])
+    return BooleanExpression("equal_any", [self, Helper.array(others)])
   }
 
   func equalAny(_ arrayExpression: Expression) -> BooleanExpression {
-    return BooleanExpression("eq_any", [self, arrayExpression])
+    return BooleanExpression("equal_any", [self, arrayExpression])
   }
 
   func notEqualAny(_ others: [Expression]) -> BooleanExpression {
-    return BooleanExpression("not_eq_any", [self, Helper.array(others)])
+    return BooleanExpression("not_equal_any", [self, Helper.array(others)])
   }
 
   func notEqualAny(_ others: [Sendable]) -> BooleanExpression {
-    return BooleanExpression("not_eq_any", [self, Helper.array(others)])
+    return BooleanExpression("not_equal_any", [self, Helper.array(others)])
   }
 
   func notEqualAny(_ arrayExpression: Expression) -> BooleanExpression {
-    return BooleanExpression("not_eq_any", [self, arrayExpression])
+    return BooleanExpression("not_equal_any", [self, arrayExpression])
   }
 
   // MARK: Checks
@@ -260,11 +260,11 @@ public extension Expression {
   }
 
   func strContains(_ substring: String) -> BooleanExpression {
-    return BooleanExpression("str_contains", [self, Helper.sendableToExpr(substring)])
+    return BooleanExpression("string_contains", [self, Helper.sendableToExpr(substring)])
   }
 
   func strContains(_ expr: Expression) -> BooleanExpression {
-    return BooleanExpression("str_contains", [self, expr])
+    return BooleanExpression("string_contains", [self, expr])
   }
 
   func startsWith(_ prefix: String) -> BooleanExpression {
@@ -283,11 +283,11 @@ public extension Expression {
     return BooleanExpression("ends_with", [self, suffix])
   }
 
-  func lowercased() -> FunctionExpression {
+  func toLower() -> FunctionExpression {
     return FunctionExpression("to_lower", [self])
   }
 
-  func uppercased() -> FunctionExpression {
+  func toUpper() -> FunctionExpression {
     return FunctionExpression("to_upper", [self])
   }
 
@@ -296,7 +296,7 @@ public extension Expression {
   }
 
   func strConcat(_ strings: [Expression]) -> FunctionExpression {
-    return FunctionExpression("str_concat", [self] + strings)
+    return FunctionExpression("string_concat", [self] + strings)
   }
 
   func reverse() -> FunctionExpression {
@@ -380,35 +380,35 @@ public extension Expression {
   }
 
   func average() -> AggregateFunction {
-    return AggregateFunction("avg", [self])
+    return AggregateFunction("average", [self])
   }
 
   func minimum() -> AggregateFunction {
-    return AggregateFunction("min", [self])
+    return AggregateFunction("minimum", [self])
   }
 
   func maximum() -> AggregateFunction {
-    return AggregateFunction("max", [self])
+    return AggregateFunction("maximum", [self])
   }
 
   // MARK: Logical min/max
 
   func logicalMaximum(_ expressions: [Expression]) -> FunctionExpression {
-    return FunctionExpression("max", [self] + expressions)
+    return FunctionExpression("logical_maximum", [self] + expressions)
   }
 
   func logicalMaximum(_ values: [Sendable]) -> FunctionExpression {
     let exprs = [self] + values.map { Helper.sendableToExpr($0) }
-    return FunctionExpression("max", exprs)
+    return FunctionExpression("logical_maximum", exprs)
   }
 
   func logicalMinimum(_ expressions: [Expression]) -> FunctionExpression {
-    return FunctionExpression("min", [self] + expressions)
+    return FunctionExpression("logical_minimum", [self] + expressions)
   }
 
   func logicalMinimum(_ values: [Sendable]) -> FunctionExpression {
     let exprs = [self] + values.map { Helper.sendableToExpr($0) }
-    return FunctionExpression("min", exprs)
+    return FunctionExpression("logical_minimum", exprs)
   }
 
   // MARK: Vector Operations
@@ -503,12 +503,12 @@ public extension Expression {
   }
 
   func timestampSub(amount: Expression, unit: Expression) -> FunctionExpression {
-    return FunctionExpression("timestamp_sub", [self, unit, amount])
+    return FunctionExpression("timestamp_subtract", [self, unit, amount])
   }
 
   func timestampSub(_ amount: Int, _ unit: TimeUnit) -> FunctionExpression {
     return FunctionExpression(
-      "timestamp_sub",
+      "timestamp_subtract",
       [self, Helper.sendableToExpr(unit), Helper.sendableToExpr(amount)]
     )
   }

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

@@ -779,22 +779,22 @@ public protocol Expression: Sendable {
   ///
   /// ```swift
   /// // Convert the "name" field to lowercase
-  /// Field("name").lowercased()
+  /// Field("name").toLower()
   /// ```
   ///
   /// - Returns: A new `FunctionExpression` representing the lowercase string.
-  func lowercased() -> FunctionExpression
+  func toLower() -> FunctionExpression
 
   /// Creates an expression that converts a string (from `self`) to uppercase.
   /// Assumes `self` evaluates to a string.
   ///
   /// ```swift
-  /// // Convert the "title" field to uppercase3
-  /// Field("title").uppercased()
+  /// // Convert the "title" field to uppercase
+  /// Field("title").toUpper()
   /// ```
   ///
   /// - Returns: A new `FunctionExpression` representing the uppercase string.
-  func uppercased() -> FunctionExpression
+  func toUpper() -> FunctionExpression
 
   /// Creates an expression that removes leading and trailing whitespace from a string (from
   /// `self`).

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

@@ -12,6 +12,25 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// An expression that represents an array of values.
+///
+/// `ArrayExpression` is used to construct an array from a list of `Sendable`
+/// values, which can include literals (like numbers and strings) as well as other
+/// `Expression` instances. This allows for the creation of dynamic arrays within
+
+/// a pipeline.
+///
+/// Example:
+/// ```swift
+/// ArrayExpression([
+///   1,
+///   2,
+///   Field("genre"),
+///   Field("rating").multiply(10),
+///   ArrayExpression([Field("title")]),
+///   MapExpression(["published": Field("published")]),
+/// ]).as("metadataArray")
+/// ```
 public class ArrayExpression: FunctionExpression, @unchecked Sendable {
   var result: [Expression] = []
   public init(_ elements: [Sendable]) {
@@ -21,4 +40,4 @@ public class ArrayExpression: FunctionExpression, @unchecked Sendable {
 
     super.init("array", result)
   }
-}
+}

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

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-public class Field: ExprBridge, Expression, Selectable, BridgeWrapper, SelectableWrapper,
+public struct Field: Expression, Selectable, BridgeWrapper, SelectableWrapper,
   @unchecked Sendable {
   let bridge: ExprBridge
 

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

@@ -18,7 +18,7 @@ import Foundation
 /// A `BooleanExpression` is a specialized `FunctionExpression` that evaluates to a boolean value.
 ///
 /// It is used to construct conditional logic within Firestore pipelines, such as in `where`
-/// clauses or `cond` expressions. `BooleanExpression` instances can be combined using standard
+/// clauses or `ConditionalExpression`. `BooleanExpression` instances can be combined using standard
 /// logical operators (`&&`, `||`, `!`, `^`) to create complex conditions.
 ///
 /// Example usage in a `where` clause:
@@ -79,7 +79,7 @@ public class BooleanExpression: FunctionExpression, @unchecked Sendable {
   /// - Returns: A new `FunctionExpression` representing the conditional logic.
   public func then(_ thenExpression: Expression,
                    else elseExpression: Expression) -> FunctionExpression {
-    return FunctionExpression("cond", [self, thenExpression, elseExpression])
+    return FunctionExpression("conditional", [self, thenExpression, elseExpression])
   }
 
   /// Combines two boolean expressions with a logical AND (`&&`).

Firestore/Swift/Source/SwiftAPI/Pipeline/Expressions/FunctionExpressions/BooleanExpression.swift

@@ -12,6 +12,22 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+/// An expression that represents a map (or dictionary) of key-value pairs.
+///
+/// `MapExpression` is used to construct a map from a dictionary of `String` keys
+/// and `Sendable` values. The values can be literals (like numbers and strings)
+/// or other `Expression` instances, allowing for the creation of dynamic nested
+/// objects within a pipeline.
+///
+/// Example:
+/// ```swift
+/// MapExpression([
+///   "genre": Field("genre"),
+///   "rating": Field("rating").multiply(10),
+///   "nestedArray": ArrayExpression([Field("title")]),
+///   "nestedMap": MapExpression(["published": Field("published")]),
+/// ]).as("metadata")
+/// ```
 public class MapExpression: FunctionExpression, @unchecked Sendable {
   var result: [Expression] = []
   public init(_ elements: [String: Sendable]) {
@@ -22,4 +38,4 @@ public class MapExpression: FunctionExpression, @unchecked Sendable {
 
     super.init("map", result)
   }
-}
+}

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

@@ -183,7 +183,7 @@ public struct Pipeline: @unchecked Sendable {
   /// - `String`: Name of an existing field (implicitly converted to `Field`).
   /// - `Field`: References an existing field.
   /// - `FunctionExpression`: Represents the result of a function with an assigned alias
-  ///   (e.g., `Field("address").uppercased().as("upperAddress")`).
+  ///   (e.g., `Field("address").toUpper().as("upperAddress")`).
   ///
   /// If no selections are provided, the output of this stage is typically empty.
   /// Use `addFields` if only additions are desired without replacing the existing document
@@ -194,7 +194,7 @@ public struct Pipeline: @unchecked Sendable {
   /// let projectedPipeline = pipeline.select([
   ///   Field("firstName"),
   ///   Field("lastName"),
-  ///   Field("address").uppercased().as("upperAddress")
+  ///   Field("address").toUpper().as("upperAddress")
   /// ])
   /// // let results = try await projectedPipeline.execute()
   /// ```
@@ -335,7 +335,7 @@ public struct Pipeline: @unchecked Sendable {
   /// // let pipeline: Pipeline = ... // Assume initial pipeline.
   /// // Get unique uppercase author names and genre combinations.
   /// let distinctPipeline = pipeline.distinct(
-  ///   Field("author").uppercased().as("authorName"),
+  ///   Field("author").toUpper().as("authorName"),
   ///   Field("genre")
   /// )
   /// // To select only the transformed author name: