merge in main branch

Author: cherylEnkidu

Firestore/Swift/Source/ExpressionImplementation.swift

@@ -373,17 +373,6 @@ extension Expression {
   func stringReplace(_ find: Expression, with replace: Expression) -> FunctionExpression {
     return FunctionExpression(functionName: "string_replace", args: [self, find, replace])
   }
-
-  // MARK: Equivalence Operations
-
-  /// Creates a `BooleanExpr` that returns `true` if this expression is equivalent
-  /// to the given value.
-  ///
-  /// - Parameter other: The value to compare against.
-  /// - Returns: A `BooleanExpr` that can be used in `where` clauses.
-  func equivalent(_ other: Sendable) -> BooleanExpression {
-    return BooleanExpression(functionName: "equivalent", args: [self, Helper.sendableToExpr(other)])
-  }
 }
 
 public extension Expression {
@@ -709,8 +698,15 @@ public extension Expression {
     return FunctionExpression(functionName: "to_upper", args: [self])
   }
 
-  func trim() -> FunctionExpression {
-    return FunctionExpression(functionName: "trim", args: [self])
+  func trim(_ value: String) -> FunctionExpression {
+    return FunctionExpression(
+      functionName: "trim",
+      args: [self, Helper.sendableToExpr(value)]
+    )
+  }
+
+  func trim(_ value: Expression) -> FunctionExpression {
+    return FunctionExpression(functionName: "trim", args: [self, value])
   }
 
   func stringConcat(_ strings: [Expression]) -> FunctionExpression {
@@ -731,7 +727,7 @@ public extension Expression {
   }
 
   func byteLength() -> FunctionExpression {
-    return FunctionExpression(functionName: "byte_length", args: [self])
+    return FunctionExpression("byte_length", [self])
   }
 
   func substring(position: Int, length: Int? = nil) -> FunctionExpression {

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

@@ -22,32 +22,31 @@
 import Foundation
 
 @objc public extension Firestore {
-  /// Creates a `PipelineSource` that can be used to build and execute a pipeline of operations on
-  /// the Firestore database.
+  /// Creates a new `PipelineSource` to build and execute a data pipeline.
   ///
-  /// A pipeline is a sequence of stages that are executed in order. Each stage can perform an
-  /// operation on the data, such as filtering, sorting, or transforming it.
+  /// A pipeline is composed of a sequence of stages. Each stage processes the
+  /// output from the previous one, and the final stage's output is the result of the
+  /// pipeline's execution.
   ///
   /// Example usage:
   /// ```swift
-  /// let db = Firestore.firestore()
-  /// let pipeline = db.pipeline()
+  /// let pipeline = firestore.pipeline()
   ///   .collection("books")
   ///   .where(Field("rating").isGreaterThan(4.5))
-  ///   .sort([Field("rating").descending()])
+  ///   .sort(Field("rating").descending())
   ///   .limit(2)
-  ///
-  /// do {
-  ///   let snapshot = try await pipeline.execute()
-  ///   for doc in snapshot.results {
-  ///     print(doc.data())
-  ///   }
-  /// } catch {
-  ///   print("Error executing pipeline: \(error)")
-  /// }
   /// ```
   ///
-  /// - Returns: A `PipelineSource` that can be used to build and execute a pipeline.
+  /// Note on Execution: The stages are conceptual. The Firestore backend may
+  /// optimize execution (e.g., reordering or merging stages) as long as the
+  /// final result remains the same.
+  ///
+  /// Important Limitations:
+  /// - Pipelines operate on a request/response basis only.
+  /// - They do not utilize or update the local SDK cache.
+  /// - They do not support realtime snapshot listeners.
+  ///
+  /// - Returns: A `PipelineSource` to begin defining the pipeline's stages.
   @available(iOS 13, tvOS 13, macOS 10.15, macCatalyst 13, watchOS 7, *)
   @nonobjc func pipeline() -> PipelineSource {
     return PipelineSource(db: self) { stages, db in

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

@@ -466,83 +466,96 @@ public protocol Expression: Sendable {
   ///
   /// - Parameter other: The expression to compare against.
   /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func greaterThan(_ other: Expression) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is greater
   /// than the given value.
   ///
   /// - Parameter other: The value to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func greaterThan(_ other: Sendable) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is
   /// greater than or equal to the given expression.
   ///
   /// - Parameter other: The expression to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func greaterThanOrEqual(_ other: Expression) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is
   /// greater than or equal to the given value.
   ///
   /// - Parameter other: The value to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func greaterThanOrEqual(_ other: Sendable) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is less
   /// than the given expression.
   ///
   /// - Parameter other: The expression to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func lessThan(_ other: Expression) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is less
   /// than the given value.
   ///
   /// - Parameter other: The value to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func lessThan(_ other: Sendable) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is less
   /// than or equal to the given expression.
   ///
   /// - Parameter other: The expression to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func lessThanOrEqual(_ other: Expression) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is less
   /// than or equal to the given value.
   ///
   /// - Parameter other: The value to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func lessThanOrEqual(_ other: Sendable) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is equal
   /// to the given expression.
   ///
   /// - Parameter other: The expression to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func equal(_ other: Expression) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is equal
   /// to the given value.
   ///
   /// - Parameter other: The value to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func equal(_ other: Sendable) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is not
   /// equal to the given expression.
   ///
   /// - Parameter other: The expression to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func notEqual(_ other: Expression) -> BooleanExpression
 
   /// Creates a `BooleanExpression` that returns `true` if this expression is not
   /// equal to the given value.
   ///
   /// - Parameter other: The value to compare against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func notEqual(_ other: Sendable) -> BooleanExpression
 
   /// Creates an expression that checks if this expression is equal to any of the provided
@@ -554,7 +567,8 @@ public protocol Expression: Sendable {
   /// ```
   ///
   /// - Parameter others: An array of at least one `Expression` value to check against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func equalAny(_ others: [Expression]) -> BooleanExpression
 
   /// Creates an expression that checks if this expression is equal to any of the provided literal
@@ -566,7 +580,8 @@ public protocol Expression: Sendable {
   /// ```
   ///
   /// - Parameter others: An array of at least one `Sendable` literal value to check against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func equalAny(_ others: [Sendable]) -> BooleanExpression
 
   /// Creates an expression that checks if this expression is equal to any of the provided
@@ -578,7 +593,8 @@ public protocol Expression: Sendable {
   /// ```
   ///
   /// - Parameter arrayExpression: An `Expression` elements evaluated to be array.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func equalAny(_ arrayExpression: Expression) -> BooleanExpression
 
   /// Creates an expression that checks if this expression is not equal to any of the provided
@@ -590,7 +606,8 @@ public protocol Expression: Sendable {
   /// ```
   ///
   /// - Parameter others: An array of at least one `Expression` value to check against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func notEqualAny(_ others: [Expression]) -> BooleanExpression
 
   /// Creates an expression that checks if this expression is not equal to any of the provided
@@ -602,7 +619,8 @@ public protocol Expression: Sendable {
   /// ```
   ///
   /// - Parameter others: An array of at least one `Sendable` literal value to check against.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func notEqualAny(_ others: [Sendable]) -> BooleanExpression
 
   /// Creates an expression that checks if this expression is equal to any of the provided
@@ -614,7 +632,8 @@ public protocol Expression: Sendable {
   /// ```
   ///
   /// - Parameter arrayExpression: An `Expression` elements evaluated to be array.
-  /// - Returns: A `BooleanExpression` that can be used in `where` clauses.
+  /// - Returns: A `BooleanExpression` that can be used in a where stage, together with other
+  /// boolean expressions.
   func notEqualAny(_ arrayExpression: Expression) -> BooleanExpression
 
   /// Creates an expression that checks if a field exists in the document.
@@ -721,7 +740,7 @@ public protocol Expression: Sendable {
   /// ```
   ///
   /// - Parameter pattern: The literal string regular expression to use for the search.
-  /// - Returns: A new `BooleanExpression` representing the "regex_contains" comparison.
+  /// - Returns: A new `BooleanExpr` representing the "regex_contains" comparison.
   func regexContains(_ pattern: String) -> BooleanExpression
 
   /// Creates an expression that checks if a string (from `self`) contains a specified regular
@@ -868,17 +887,32 @@ public protocol Expression: Sendable {
   /// - Returns: A new `FunctionExpression` representing the uppercase string.
   func toUpper() -> FunctionExpression
 
-  /// Creates an expression that removes leading and trailing whitespace from a string (from
-  /// `self`).
-  /// Assumes `self` evaluates to a string.
+  /// Creates an expression that removes leading and trailing occurrences of specified characters
+  /// from a string (from `self`).
+  /// Assumes `self` evaluates to a string, and `value` evaluates to a string.
+  ///
+  /// ```swift
+  /// // Trim leading/trailing "xy" from field
+  /// Field("code").trim(characters: "xy")
+  /// ```
+  ///
+  /// - Parameter value: A `String` containing the characters to trim.
+  /// - Returns: A new `FunctionExpression` representing the trimmed string.
+  func trim(_ value: String) -> FunctionExpression
+
+  /// Creates an expression that removes leading and trailing occurrences of specified string
+  /// (from an expression) from a string (from `self`).
+  /// Assumes `self` evaluates to a string, and `value` evaluates to a string.
   ///
   /// ```swift
-  /// // Trim whitespace from the "userInput" field
-  /// Field("userInput").trim()
+  /// // Trim characters specified by the "trimChars" field from "data"
+  /// Field("data").trim(characters: Field("trimChars"))
   /// ```
   ///
+  /// - Parameter value: An `Expression` (evaluating to a string) containing the characters to
+  /// trim.
   /// - Returns: A new `FunctionExpression` representing the trimmed string.
-  func trim() -> FunctionExpression
+  func trim(_ value: Expression) -> FunctionExpression
 
   /// Creates an expression that concatenates this string expression with other string expressions.
   /// Assumes `self` and all parameters evaluate to strings.