add pow()

Author: cherylEnkidu

Firestore/Swift/Source/ExpressionImplementation.swift

@@ -296,6 +296,14 @@ public extension Expression {
     return FunctionExpression("ln", [self])
   }
 
+  func pow(_ exponent: Sendable) -> FunctionExpression {
+    return FunctionExpression("pow", [self, Helper.sendableToExpr(exponent)])
+  }
+
+  func pow(_ exponent: Expression) -> FunctionExpression {
+    return FunctionExpression("pow", [self, exponent])
+  }
+
   func exp() -> FunctionExpression {
     return FunctionExpression("exp", [self])
   }

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

@@ -36,6 +36,32 @@ public protocol Expression: Sendable {
 
   // --- Added Mathematical Operations ---
 
+  /// Creates an expression that returns the value of self raised to the power of Y.
+  ///
+  /// Returns zero on underflow.
+  ///
+  /// ```swift
+  /// // Get the value of the "amount" field raised to the power of 2.
+  /// Field("amount").pow(2)
+  /// ```
+  ///
+  /// - Parameter exponent: The exponent to raise self to.
+  /// - Returns: A new `FunctionExpression` representing the power of the number.
+  func pow(_ exponent: Sendable) -> FunctionExpression
+
+  /// Creates an expression that returns the value of self raised to the power of Y.
+  ///
+  /// Returns zero on underflow.
+  ///
+  /// ```swift
+  /// // Get the value of the "amount" field raised to the power of the "exponent" field.
+  /// Field("amount").pow(Field("exponent"))
+  /// ```
+  ///
+  /// - Parameter exponent: The exponent to raise self to.
+  /// - Returns: A new `FunctionExpression` representing the power of the number.
+  func pow(_ exponent: Expression) -> FunctionExpression
+
   /// Creates an expression that returns the natural logarithm of self.
   ///
   /// ```swift

Firestore/Swift/Tests/Integration/PipelineTests.swift

@@ -2130,6 +2130,32 @@ class PipelineIntegrationTests: FSTIntegrationTestCase {
     TestHelper.compare(pipelineSnapshot: snapshot, expected: expectedResults, enforceOrder: true)
   }
 
+  func testPowWorks() async throws {
+    let collRef = collectionRef(withDocuments: [
+      "doc1": ["base": 2, "exponent": 3],
+      "doc2": ["base": 3, "exponent": 2],
+      "doc3": ["base": 4, "exponent": 0.5],
+    ])
+    let db = collRef.firestore
+
+    let pipeline = db.pipeline()
+      .collection(collRef.path)
+      .select([
+        Field("base").pow(Field("exponent")).as("powValue"),
+      ])
+      .sort([Field("powValue").ascending()])
+
+    let snapshot = try await pipeline.execute()
+
+    let expectedResults: [[String: Sendable]] = [
+      ["powValue": 2],
+      ["powValue": 8],
+      ["powValue": 9],
+    ]
+
+    TestHelper.compare(pipelineSnapshot: snapshot, expected: expectedResults, enforceOrder: true)
+  }
+
   func testExpWorks() async throws {
     let collRef = collectionRef(withDocuments: [
       "doc1": ["value": 1],