From 9b81e092705df713af5bfb7be1ddde0b664d4b79 Mon Sep 17 00:00:00 2001
From: Mila <107142260+milaGGL@users.noreply.github.com>
Date: Tue, 24 Mar 2026 15:41:39 -0400
Subject: [PATCH 1/4] feat(firestore): Add ifNull and coalesce

---
 .../firestore/api-report/firestore.api.md     |  51 +++--
 .../firestore/dev/src/pipelines/expression.ts | 201 ++++++++++++++++++
 .../firestore/dev/src/pipelines/index.ts      |   2 +
 .../firestore/dev/system-test/pipeline.ts     |  83 ++++++++
 handwritten/firestore/types/firestore.d.ts    | 177 +++++++++++++++
 5 files changed, 499 insertions(+), 15 deletions(-)

diff --git a/handwritten/firestore/api-report/firestore.api.md b/handwritten/firestore/api-report/firestore.api.md
index df8cc5c85c2..b7602461a2b 100644
--- a/handwritten/firestore/api-report/firestore.api.md
+++ b/handwritten/firestore/api-report/firestore.api.md
@@ -498,6 +498,12 @@ function charLength(fieldName: string): FunctionExpression;
 // @beta
 function charLength(stringExpression: Expression): FunctionExpression;
 
+// @beta
+function coalesce(first: Expression, second: Expression | unknown, ...others: Array<Expression | unknown>): Expression;
+
+// @beta
+function coalesce(firstFieldName: string, second: Expression | unknown, ...others: Array<Expression | unknown>): Expression;
+
 // Warning: (tsdoc-undefined-tag) The TSDoc tag "@class" is not defined in this configuration
 //
 // @public
@@ -1099,6 +1105,7 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     byteLength(): FunctionExpression;
     ceil(): FunctionExpression;
     charLength(): FunctionExpression;
+    coalesce(second: Expression | unknown, ...others: Array<Expression | unknown>): Expression;
     collectionId(): FunctionExpression;
     concat(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
     cosineDistance(vectorExpression: Expression): FunctionExpression;
@@ -1135,9 +1142,11 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     ifAbsent(elseExpression: unknown): Expression;
     ifError(catchExpr: Expression): FunctionExpression;
     ifError(catchValue: unknown): FunctionExpression;
+    ifNull(elseValue: unknown): Expression;
+    ifNull(elseExpression: unknown): Expression;
     isAbsent(): BooleanExpression;
     isError(): BooleanExpression;
-    isType(type: Type): BooleanExpression;
+    isType(type: string): BooleanExpression;
     join(delimiterExpression: Expression): Expression;
     join(delimiter: string): Expression;
     last(): AggregateFunction;
@@ -1414,6 +1423,8 @@ class Firestore implements firestore.Firestore {
     // Warning: (tsdoc-param-tag-with-invalid-name) The @param block should be followed by a valid parameter name: The identifier cannot non-word characters
     // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
     constructor(settings?: firestore.Settings);
+    // @internal
+    get alwaysUseImplicitOrderBy(): boolean;
     // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
     batch(): WriteBatch;
@@ -1636,6 +1647,18 @@ function ifError(tryExpr: Expression, catchExpr: Expression): FunctionExpression
 // @beta
 function ifError(tryExpr: Expression, catchValue: unknown): FunctionExpression;
 
+// @beta
+function ifNull(ifExpr: Expression, elseExpr: Expression): Expression;
+
+// @beta
+function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
+
+// @beta
+function ifNull(ifFieldName: string, elseExpr: Expression): Expression;
+
+// @beta
+function ifNull(ifFieldName: string, elseValue: unknown): Expression;
+
 // @beta
 function isAbsent(value: Expression): BooleanExpression;
 
@@ -1646,10 +1669,10 @@ function isAbsent(field: string): BooleanExpression;
 function isError(value: Expression): BooleanExpression;
 
 // @beta
-function isType(fieldName: string, type: Type): BooleanExpression;
+function isType(fieldName: string, type: string): BooleanExpression;
 
 // @beta
-function isType(expression: Expression, type: Type): BooleanExpression;
+function isType(expression: Expression, type: string): BooleanExpression;
 
 // @beta
 function join(arrayFieldName: string, delimiter: string): Expression;
@@ -1884,7 +1907,7 @@ class Ordering implements HasUserData {
 // @beta
 class Pipeline implements firestore.Pipelines.Pipeline {
     // Warning: (ae-forgotten-export) The symbol "Stage" needs to be exported by the entry point index.d.ts
-    constructor(db: Firestore, stages: Stage[]);
+    constructor(db: Firestore | undefined, stages: Stage[]);
     addFields(field: firestore.Pipelines.Selectable, ...additionalFields: firestore.Pipelines.Selectable[]): Pipeline;
     // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
     addFields(options: firestore.Pipelines.AddFieldsStageOptions): Pipeline;
@@ -1933,8 +1956,8 @@ class Pipeline implements firestore.Pipelines.Pipeline {
     union(options: firestore.Pipelines.UnionStageOptions): Pipeline;
     unnest(selectable: firestore.Pipelines.Selectable, indexField?: string): Pipeline;
     unnest(options: firestore.Pipelines.UnnestStageOptions): Pipeline;
-    // Warning: (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
-    _validateUserData<T extends Map<string, HasUserData> | HasUserData[] | HasUserData>(_: string, val: T): T;
+    // (undocumented)
+    _validateUserData(ignoreUndefinedProperties: boolean): void;
     where(condition: firestore.Pipelines.BooleanExpression): Pipeline;
     where(options: firestore.Pipelines.WhereStageOptions): Pipeline;
 }
@@ -2114,7 +2137,6 @@ declare namespace Pipelines {
         arrayConcat,
         type,
         isType,
-        Type,
         timestampTruncate,
         split,
         ltrim,
@@ -2124,7 +2146,9 @@ declare namespace Pipelines {
         stringReplaceAll,
         stringReplaceOne,
         nor,
-        switchOn
+        switchOn,
+        ifNull,
+        coalesce
     }
 }
 export { Pipelines }
@@ -2354,7 +2378,7 @@ export class Query<AppModelType = firestore.DocumentData, DbModelType extends fi
     // Warning: (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
     //
     // @internal
-    toProto(transactionOrReadTime?: Uint8Array | Timestamp | api.ITransactionOptions, explainOptions?: firestore.ExplainOptions): api.IRunQueryRequest;
+    toProto(transactionOrReadTime?: Uint8Array | Timestamp | api.ITransactionOptions, explainOptions?: firestore.ExplainOptions, forceImplicitOrderBy?: boolean): api.IRunQueryRequest;
     // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
     // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
     // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
@@ -2876,9 +2900,6 @@ function trunc(fieldName: string, decimalPlaces: number | Expression): FunctionE
 // @beta
 function trunc(expression: Expression, decimalPlaces: number | Expression): FunctionExpression;
 
-// @beta
-type Type = 'null' | 'array' | 'boolean' | 'bytes' | 'timestamp' | 'geo_point' | 'number' | 'int32' | 'int64' | 'float64' | 'decimal128' | 'map' | 'reference' | 'string' | 'vector' | 'max_key' | 'min_key' | 'object_id' | 'regex' | 'request_timestamp';
-
 // Warning: (tsdoc-escape-right-brace) The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag
 // Warning: (tsdoc-malformed-inline-tag) Expecting a TSDoc tag starting with "{@"
 //
@@ -3118,9 +3139,9 @@ function xor(first: BooleanExpression, second: BooleanExpression, ...additionalC
 // build/types/src/index.d.ts:371:8 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
 // build/types/src/index.d.ts:378:8 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
 // build/types/src/index.d.ts:387:8 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
-// build/types/src/index.d.ts:881:8 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
-// build/types/src/index.d.ts:900:8 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
-// build/types/src/index.d.ts:915:8 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
+// build/types/src/index.d.ts:886:8 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
+// build/types/src/index.d.ts:905:8 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
+// build/types/src/index.d.ts:920:8 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
 // build/types/src/path.d.ts:29:4 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
 // build/types/src/path.d.ts:31:4 - (tsdoc-undefined-tag) The TSDoc tag "@class" is not defined in this configuration
 // build/types/src/path.d.ts:146:4 - (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
diff --git a/handwritten/firestore/dev/src/pipelines/expression.ts b/handwritten/firestore/dev/src/pipelines/expression.ts
index 8a32713c36b..2b3a092e229 100644
--- a/handwritten/firestore/dev/src/pipelines/expression.ts
+++ b/handwritten/firestore/dev/src/pipelines/expression.ts
@@ -2876,6 +2876,74 @@ export abstract class Expression
     ]);
   }
 
+  /**
+   * @beta
+   * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
+   * return the result of this expression evaluation.
+   *
+   * @example
+   * ```typescript
+   * // Returns the value of the 'optional_field', or returns 'default_value'
+   * // if the field is null.
+   * field("optional_field").ifNull("default_value")
+   * ```
+   *
+   * @param elseValue The value that will be returned if this Expression evaluates to a null value.
+   * @returns A new [Expression] representing the ifNull operation.
+   */
+  ifNull(elseValue: unknown): Expression;
+
+  /**
+   * @beta
+   * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
+   * return the result of this expression evaluation.
+   *
+   * @example
+   * ```typescript
+   * // Returns the value of the 'optional_field', or if that is
+   * // null, then returns the value of the field `
+   * field("optional_field").ifNull(field('default_field'))
+   * ```
+   *
+   * @param elseExpression The Expression that will be evaluated if this Expression evaluates to a null value.
+   * @returns A new [Expression] representing the ifNull operation.
+   */
+  ifNull(elseExpression: unknown): Expression;
+  ifNull(elseValueOrExpression: Expression | unknown): Expression {
+    return new FunctionExpression('if_null', [
+      this,
+      valueToDefaultExpr(elseValueOrExpression),
+    ]);
+  }
+
+  /**
+   * @beta
+   * Creates an expression that Returns the first non-null, non-absent argument, without evaluating
+   * the rest of the arguments. When all arguments are null or absent, returns the last argument.
+   *
+   * @example
+   * ```typescript
+   * // Return "Anonymous" if the 'name' field is null.
+   * field("name").coalesce("Anonymous");
+   * // Return "val1" if "val1" is not null, otherwise "val2", or "default" if both are null.
+   * field("val1").coalesce(field("val2"), "default");
+   * ```
+   *
+   * @param replacement - The value to use if this expression evaluates to null.
+   * @param others - Optional additional values to check if previous values are null.
+   * @returns A new [Expression] representing the coalesce operation.
+   */
+  coalesce(
+    second: Expression | unknown,
+    ...others: Array<Expression | unknown>
+  ): Expression {
+    const values = [second, ...others];
+    return new FunctionExpression('coalesce', [
+      this,
+      ...values.map(valueToDefaultExpr),
+    ]);
+  }
+
   /**
    * @beta
    * Creates an expression that joins the elements of an array into a string.
@@ -9188,6 +9256,139 @@ export function ifAbsent(
   );
 }
 
+/**
+ * @beta
+ * Creates an expression that returns the `elseExpr` argument if `ifExpr` is null, else
+ * return the result of the `ifExpr` argument evaluation.
+ *
+ * @example
+ * ```typescript
+ * // Returns the value of the 'optional_field', or returns value of the 'default_field'
+ * // if the 'optional_field' value is null.
+ * ifNull(field("optional_field"), field("default_field"))
+ * ```
+ *
+ * @param ifExpr The expression to check for null.
+ * @param elseExpr The value that will be returned if `ifExpr` evaluates to a null value.
+ * @returns A new `Expression` representing the ifNull operation.
+ */
+export function ifNull(ifExpr: Expression, elseExpr: Expression): Expression;
+
+/**
+ * @beta
+ * Creates an expression that returns the `elseValue` argument if `ifExpr` is null, else
+ * return the result of the `ifExpr` argument evaluation.
+ *
+ * @example
+ * ```typescript
+ * // Returns the value of the 'optional_field', or returns 'default_value'
+ * // if the 'optional_field' value is null.
+ * ifNull(field("optional_field"), "default_value")
+ * ```
+ *
+ * @param ifExpr The expression to check for null.
+ * @param elseValue The value that will be returned if `ifExpr` evaluates to a null value.
+ * @returns A new `Expression` representing the ifNull operation.
+ */
+export function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
+
+/**
+ * @beta
+ * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is null, else
+ * return the value of the field.
+ *
+ * @example
+ * ```typescript
+ * // Returns the value of the 'optional_field', or returns the value of
+ * // 'default_field' if 'optional_field' is null.
+ * ifNull("optional_field", field("default_field"))
+ * ```
+ *
+ * @param ifFieldName The field to check for null.
+ * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is
+ * null.
+ * @returns A new `Expression` representing the ifNull operation.
+ */
+export function ifNull(ifFieldName: string, elseExpr: Expression): Expression;
+
+/**
+ * @beta
+ * Creates an expression that returns the `elseValue` argument if `ifFieldName` is null, else
+ * return the value of the field.
+ *
+ * @example
+ * ```typescript
+ * // Returns the value of the 'optional_field', or returns 'default_value'
+ * // if the field is null.
+ * ifNull("optional_field", "default_value")
+ * ```
+ *
+ * @param ifFieldName The field to check for null.
+ * @param elseValue The value that will be returned if `ifFieldName` is null.
+ * @returns A new `Expression` representing the ifNull operation.
+ */
+export function ifNull(ifFieldName: string, elseValue: unknown): Expression;
+export function ifNull(
+  fieldNameOrExpression: string | Expression,
+  elseValue: Expression | unknown,
+): Expression {
+  return fieldOrExpression(fieldNameOrExpression).ifNull(
+    valueToDefaultExpr(elseValue),
+  );
+}
+
+/**
+ * @beta
+ * Returns the first non-null value among the given expressions/values.
+ *
+ * @example
+ * ```typescript
+ * // Returns the value of 'optional_field', or if that is
+ * // null, then returns the value of 'default_field'
+ * coalesce("optional_field", field("default_field"))
+ * ```
+ *
+ * @param first The first expression to evaluate.
+ * @param second The next expression or literal to evaluate.
+ * @param others Additional expressions or literals to evaluate.
+ * @returns A new `Expression` representing the coalesce operation.
+ */
+export function coalesce(
+  first: Expression,
+  second: Expression | unknown,
+  ...others: Array<Expression | unknown>
+): Expression;
+
+/**
+ * @beta
+ * Returns the first non-null value among the given expressions/values.
+ *
+ * @example
+ * ```typescript
+ * // Returns the value of 'optional_field', or if that is
+ * // null, then returns the value of 'default_field'
+ * coalesce("optional_field", field("default_field"))
+ * ```
+ *
+ * @param firstFieldName The first field name to evaluate.
+ * @param second The next expression or literal to evaluate.
+ * @param others Additional expressions or literals to evaluate.
+ * @returns A new `Expression` representing the coalesce operation.
+ */
+export function coalesce(
+  firstFieldName: string,
+  second: Expression | unknown,
+  ...others: Array<Expression | unknown>
+): Expression;
+
+export function coalesce(
+  first: Expression | string,
+  second: Expression | unknown,
+  ...others: Array<Expression | unknown>
+): Expression {
+  return fieldOrExpression(first).coalesce(second, ...others);
+}
+
 /**
  * @beta
  * Creates an expression that joins the elements of an array into a string.
diff --git a/handwritten/firestore/dev/src/pipelines/index.ts b/handwritten/firestore/dev/src/pipelines/index.ts
index 4dcf2694b61..95288b3232c 100644
--- a/handwritten/firestore/dev/src/pipelines/index.ts
+++ b/handwritten/firestore/dev/src/pipelines/index.ts
@@ -156,5 +156,7 @@ export {
   stringReplaceOne,
   nor,
   switchOn,
+  ifNull,
+  coalesce,
   // TODO(new-expression): Add new expression exports above this line
 } from './expression';
diff --git a/handwritten/firestore/dev/system-test/pipeline.ts b/handwritten/firestore/dev/system-test/pipeline.ts
index 8377424c8d2..018866bdadf 100644
--- a/handwritten/firestore/dev/system-test/pipeline.ts
+++ b/handwritten/firestore/dev/system-test/pipeline.ts
@@ -140,6 +140,8 @@ import {
   log10,
   concat,
   ifAbsent,
+  ifNull,
+  coalesce,
   join,
   arraySum,
   currentTimestamp,
@@ -4984,6 +4986,87 @@ describe.skipClassic('Pipeline class', () => {
       });
     });
 
+    it('supports ifNull', async () => {
+      const snapshot = await firestore
+        .pipeline()
+        .collection(randomCol.path)
+        .limit(1)
+        .replaceWith(
+          map({
+            title: 'foo',
+            name: null,
+          }),
+        )
+        .select(
+          ifNull('title', 'default title').as('staticMethod'),
+          field('title').ifNull('default title').as('instanceMethod'),
+          field('name').ifNull(field('title')).as('nameOrTitle'),
+          field('name').ifNull('default name').as('fieldIsNull'),
+          field('absent').ifNull('default name').as('fieldIsAbsent'),
+        )
+        .execute();
+
+      expectResults(snapshot, {
+        staticMethod: 'foo',
+        instanceMethod: 'foo',
+        nameOrTitle: 'foo',
+        fieldIsNull: 'default name',
+        fieldIsAbsent: 'default name',
+      });
+    });
+
+    it('supports coalesce', async () => {
+      const snapshot = await firestore
+        .pipeline()
+        .collection(randomCol.path)
+        .limit(1)
+        .replaceWith(
+          map({
+            numberValue: 1,
+            stringValue: 'hello',
+            booleanValue: false,
+            nullValue: null,
+            nullValue2: null,
+          }),
+        )
+        .select(
+          coalesce(field('numberValue'), field('stringValue')).as(
+            'staticMethod',
+          ),
+          field('numberValue')
+            .coalesce(field('stringValue'))
+            .as('instanceMethod'),
+          coalesce(field('nullValue'), field('stringValue')).as('firstIsNull'),
+          coalesce(
+            field('nullValue'),
+            field('nullValue2'),
+            field('booleanValue'),
+          ).as('lastIsNotNull'),
+          coalesce(field('nullValue'), field('nullValue2')).as('allFieldsNull'),
+          coalesce(
+            field('nullValue'),
+            field('nullValue2'),
+            constant('default'),
+          ).as('allFieldsNullWithDefault'),
+          coalesce(
+            field('absentField'),
+            field('numberValue'),
+            constant('default'),
+          ).as('withAbsentField'),
+        )
+        .execute();
+
+      expectResults(snapshot, {
+        staticMethod: 1,
+        instanceMethod: 1,
+        firstIsNull: 'hello',
+        lastIsNotNull: false,
+        allFieldsNull: null,
+        allFieldsNullWithDefault: 'default',
+        withAbsentField: 1,
+      });
+    });
+
     it('supports join', async () => {
       const snapshot = await firestore
         .pipeline()
diff --git a/handwritten/firestore/types/firestore.d.ts b/handwritten/firestore/types/firestore.d.ts
index 6b88278d4e4..492e79f066d 100644
--- a/handwritten/firestore/types/firestore.d.ts
+++ b/handwritten/firestore/types/firestore.d.ts
@@ -5454,6 +5454,60 @@ declare namespace FirebaseFirestore {
 
       ifAbsent(elseValueOrExpression: Expression | unknown): Expression;
 
+      /**
+       * @beta
+       * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
+       * return the result of this expression evaluation.
+       *
+       * @example
+       * ```typescript
+       * // Returns the value of the 'optional_field', or returns 'default_value'
+       * // if the field is null.
+       * field("optional_field").ifNull("default_value")
+       * ```
+       *
+       * @param elseValue The value that will be returned if this Expression evaluates to a null value.
+       * @returns A new [Expression] representing the ifNull operation.
+       */
+      ifNull(elseValue: unknown): Expression;
+
+      /**
+       * @beta
+       * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
+       * return the result of this expression evaluation.
+       *
+       * @example
+       * ```typescript
+       * // Returns the value of the 'optional_field', or if that is
+       * // null, then returns the value of the field `
+       * field("optional_field").ifNull(field('default_field'))
+       * ```
+       *
+       * @param elseExpression The Expression that will be evaluated if this Expression evaluates to a null value.
+       * @returns A new [Expression] representing the ifNull operation.
+       */
+      ifNull(elseExpression: unknown): Expression;
+
+      /**
+       * @beta
+       * Returns the first non-null value among the given expressions/values.
+       *
+       * @example
+       * ```typescript
+       * // Returns the value of the 'optional_field', or if that is
+       * // null, then returns the value of the 'default_field'
+       * field("optional_field").coalesce(field("default_field"))
+       * ```
+       *
+       * @param second The next expression or literal to evaluate.
+       * @param others Additional expressions or literals to evaluate.
+       * @returns A new [Expression] representing the coalesce operation.
+       */
+      coalesce(
+        second: Expression | unknown,
+        ...others: Array<Expression | unknown>
+      ): Expression;
+
       /**
        * @beta
        * Creates an expression that joins the elements of an array into a string.
@@ -10886,6 +10940,129 @@ declare namespace FirebaseFirestore {
       elseExpr: Expression,
     ): Expression;
 
+    /**
+     * @beta
+     * Creates an expression that returns the `elseExpr` argument if `ifExpr` is null, else
+     * return the result of the `ifExpr` argument evaluation.
+     *
+     * @example
+     * ```typescript
+     * // Returns the value of the 'optional_field', or returns 'default_value'
+     * // if the field is null.
+     * ifNull(field("optional_field"), "default_value")
+     * ```
+     *
+     * @param ifExpr The expression to check for null.
+     * @param elseExpr The value that will be returned if `ifExpr` evaluates to a null value.
+     * @returns A new {@code Expression} representing the ifNull operation.
+     */
+    export function ifNull(
+      ifExpr: Expression,
+      elseExpr: Expression,
+    ): Expression;
+
+    /**
+     * @beta
+     * Creates an expression that returns the `elseValue` argument if `ifExpr` is null, else
+     * return the result of the `ifExpr` argument evaluation.
+     *
+     * @example
+     * ```typescript
+     * // Returns the value of the 'optional_field', or returns 'default_value'
+     * // if the field is null.
+     * ifNull(field("optional_field"), "default_value")
+     * ```
+     *
+     * @param ifExpr The expression to check for null.
+     * @param elseValue The value that will be returned if `ifExpr` evaluates to a null value.
+     * @returns A new {@code Expression} representing the ifNull operation.
+     */
+    export function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
+
+    /**
+     * @beta
+     * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is null, else
+     * return the value of the field.
+     *
+     * @example
+     * ```typescript
+     * // Returns the value of the 'optional_field', or returns the value of
+     * // 'default_field' if 'optional_field' is null.
+     * ifNull("optional_field", field("default_field"))
+     * ```
+     *
+     * @param ifFieldName The field to check for null.
+     * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is
+     * null.
+     * @returns A new {@code Expression} representing the ifNull operation.
+     */
+    export function ifNull(
+      ifFieldName: string,
+      elseExpr: Expression,
+    ): Expression;
+
+    /**
+     * @beta
+     * Creates an expression that returns the `elseValue` argument if `ifFieldName` is null, else
+     * return the value of the field.
+     *
+     * @example
+     * ```typescript
+     * // Returns the value of the 'optional_field', or returns 'default_value'
+     * // if the field is null.
+     * ifNull("optional_field", "default_value")
+     * ```
+     *
+     * @param ifFieldName The field to check for null.
+     * @param elseValue The value that will be returned if `ifFieldName` is null.
+     * @returns A new {@code Expression} representing the ifNull operation.
+     */
+    export function ifNull(ifFieldName: string, elseValue: unknown): Expression;
+
+    /**
+     * @beta
+     * Returns the first non-null value among the given expressions/values.
+     *
+     * @example
+     * ```typescript
+     * // Returns the value of 'optional_field', or if that is
+     * // null, then returns the value of 'default_field'
+     * coalesce("optional_field", field("default_field"))
+     * ```
+     *
+     * @param first The first expression to evaluate.
+     * @param second The next expression or literal to evaluate.
+     * @param others Additional expressions or literals to evaluate.
+     * @returns A new {@code Expression} representing the coalesce operation.
+     */
+    export function coalesce(
+      first: Expression,
+      second: Expression | unknown,
+      ...others: Array<Expression | unknown>
+    ): Expression;
+
+    /**
+     * @beta
+     * Returns the first non-null value among the given expressions/values.
+     *
+     * @example
+     * ```typescript
+     * // Returns the value of 'optional_field', or if that is
+     * // null, then returns the value of 'default_field'
+     * coalesce("optional_field", field("default_field"))
+     * ```
+     *
+     * @param firstFieldName The first field name to evaluate.
+     * @param second The next expression or literal to evaluate.
+     * @param others Additional expressions or literals to evaluate.
+     * @returns A new [Expression] representing the coalesce operation.
+     */
+    export function coalesce(
+      firstFieldName: string,
+      second: Expression | unknown,
+      ...others: Array<Expression | unknown>
+    ): Expression;
+
     /**
      * @beta
      * Creates an expression that joins the elements of an array into a string.

From 0f01cc0dc1c701c8e04d4ebd71b8cd975cc3884e Mon Sep 17 00:00:00 2001
From: Mila <107142260+milaGGL@users.noreply.github.com>
Date: Tue, 24 Mar 2026 15:54:51 -0400
Subject: [PATCH 2/4] update js docs

---
 .../firestore/dev/src/pipelines/expression.ts | 60 ++++++++++---------
 handwritten/firestore/types/firestore.d.ts    | 15 +++--
 2 files changed, 40 insertions(+), 35 deletions(-)

diff --git a/handwritten/firestore/dev/src/pipelines/expression.ts b/handwritten/firestore/dev/src/pipelines/expression.ts
index 2b3a092e229..096207d6a6b 100644
--- a/handwritten/firestore/dev/src/pipelines/expression.ts
+++ b/handwritten/firestore/dev/src/pipelines/expression.ts
@@ -9258,73 +9258,73 @@ export function ifAbsent(
 
 /**
  * @beta
- * Creates an expression that returns the `elseExpr` argument if `ifExpr` is null, else
+ * Creates an expression that returns the `elseExpr` argument if `ifExpr` is null or absent, else
  * return the result of the `ifExpr` argument evaluation.
  *
  * @example
  * ```typescript
  * // Returns the value of the 'optional_field', or returns value of the 'default_field'
- * // if the 'optional_field' value is null.
+ * // if the 'optional_field' value is null or absent.
  * ifNull(field("optional_field"), field("default_field"))
  * ```
  *
- * @param ifExpr The expression to check for null.
- * @param elseExpr The value that will be returned if `ifExpr` evaluates to a null value.
+ * @param ifExpr The expression to check for null or absence.
+ * @param elseExpr The expression that will be evaluated and returned if `ifExpr` is null or absent.
  * @returns A new `Expression` representing the ifNull operation.
  */
 export function ifNull(ifExpr: Expression, elseExpr: Expression): Expression;
 
 /**
  * @beta
- * Creates an expression that returns the `elseValue` argument if `ifExpr` is null, else
+ * Creates an expression that returns the `elseValue` argument if `ifExpr` is null or absent, else
  * return the result of the `ifExpr` argument evaluation.
  *
  * @example
  * ```typescript
  * // Returns the value of the 'optional_field', or returns 'default_value'
- * // if the 'optional_field' value is null.
+ * // if the 'optional_field' value is null or absent.
  * ifNull(field("optional_field"), "default_value")
  * ```
  *
- * @param ifExpr The expression to check for null.
- * @param elseValue The value that will be returned if `ifExpr` evaluates to a null value.
+ * @param ifExpr The expression to check for absence.
+ * @param elseValue The value that will be returned if `ifExpr` evaluates to a null or absent value.
  * @returns A new `Expression` representing the ifNull operation.
  */
 export function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
 
 /**
  * @beta
- * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is null, else
+ * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is null or absent, else
  * return the value of the field.
  *
  * @example
  * ```typescript
  * // Returns the value of the 'optional_field', or returns the value of
- * // 'default_field' if 'optional_field' is null.
+ * // 'default_field' if 'optional_field' is null or absent.
  * ifNull("optional_field", field("default_field"))
  * ```
  *
- * @param ifFieldName The field to check for null.
+ * @param ifFieldName The field to check for null or absence.
  * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is
- * null.
+ * null or absent.
  * @returns A new `Expression` representing the ifNull operation.
  */
 export function ifNull(ifFieldName: string, elseExpr: Expression): Expression;
 
 /**
  * @beta
- * Creates an expression that returns the `elseValue` argument if `ifFieldName` is null, else
+ * Creates an expression that returns the `elseValue` argument if `ifFieldName` is null or absent, else
  * return the value of the field.
  *
  * @example
  * ```typescript
  * // Returns the value of the 'optional_field', or returns 'default_value'
- * // if the field is null.
+ * // if the field is null or absent.
  * ifNull("optional_field", "default_value")
  * ```
  *
- * @param ifFieldName The field to check for null.
- * @param elseValue The value that will be returned if `ifFieldName` is null.
+ * @param ifFieldName The field to check for null or absence.
+ * @param elseValue The value that will be returned if `ifFieldName` is null or absent.
  * @returns A new `Expression` representing the ifNull operation.
  */
 export function ifNull(ifFieldName: string, elseValue: unknown): Expression;
@@ -9339,29 +9339,31 @@ export function ifNull(
 
 /**
  * @beta
- * Returns the first non-null value among the given expressions/values.
+ * Returns the first non-null, non-absent argument, without evaluating
+ * the rest of the arguments. When all arguments are null or absent, returns the last argument.
  *
  * @example
  * ```typescript
  * // Returns the value of 'optional_field', or if that is
  * // null, then returns the value of 'default_field'
- * coalesce("optional_field", field("default_field"))
+ * coalesce(field("optional_field"), field("default_field"))
  * ```
  *
- * @param first The first expression to evaluate.
- * @param second The next expression or literal to evaluate.
- * @param others Additional expressions or literals to evaluate.
+ * @param expression The first expression to check for null.
+ * @param replacement The fallback expression or value if the first one is null.
+ * @param others Optional additional expressions to check if previous ones are null.
  * @returns A new `Expression` representing the coalesce operation.
  */
 export function coalesce(
-  first: Expression,
-  second: Expression | unknown,
+  expression: Expression,
+  replacement: Expression | unknown,
   ...others: Array<Expression | unknown>
 ): Expression;
 
 /**
  * @beta
- * Returns the first non-null value among the given expressions/values.
+ * Returns the first non-null, non-absent argument, without evaluating
+ * the rest of the arguments. When all arguments are null or absent, returns the last argument.
  *
  * @example
  * ```typescript
@@ -9370,14 +9372,14 @@ export function coalesce(
  * coalesce("optional_field", field("default_field"))
  * ```
  *
- * @param firstFieldName The first field name to evaluate.
- * @param second The next expression or literal to evaluate.
- * @param others Additional expressions or literals to evaluate.
+ * @param fieldName The name of the first field to check for null.
+ * @param replacement The fallback expression or value if the first one is null.
+ * @param others Optional additional expressions to check if previous ones are null.
  * @returns A new `Expression` representing the coalesce operation.
  */
 export function coalesce(
-  firstFieldName: string,
-  second: Expression | unknown,
+  fieldName: string,
+  replacement: Expression | unknown,
   ...others: Array<Expression | unknown>
 ): Expression;
 
diff --git a/handwritten/firestore/types/firestore.d.ts b/handwritten/firestore/types/firestore.d.ts
index 492e79f066d..f0fa56b0b78 100644
--- a/handwritten/firestore/types/firestore.d.ts
+++ b/handwritten/firestore/types/firestore.d.ts
@@ -10954,7 +10954,7 @@ declare namespace FirebaseFirestore {
      *
      * @param ifExpr The expression to check for null.
      * @param elseExpr The value that will be returned if `ifExpr` evaluates to a null value.
-     * @returns A new {@code Expression} representing the ifNull operation.
+     * @returns A new [Expression] representing the ifNull operation.
      */
     export function ifNull(
       ifExpr: Expression,
@@ -10975,7 +10975,7 @@ declare namespace FirebaseFirestore {
      *
      * @param ifExpr The expression to check for null.
      * @param elseValue The value that will be returned if `ifExpr` evaluates to a null value.
-     * @returns A new {@code Expression} representing the ifNull operation.
+     * @returns A new [Expression] representing the ifNull operation.
      */
     export function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
 
@@ -10994,7 +10994,7 @@ declare namespace FirebaseFirestore {
      * @param ifFieldName The field to check for null.
      * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is
      * null.
-     * @returns A new {@code Expression} representing the ifNull operation.
+     * @returns A new Expression representing the ifNull operation.
      */
     export function ifNull(
       ifFieldName: string,
@@ -11015,9 +11015,12 @@ declare namespace FirebaseFirestore {
      *
      * @param ifFieldName The field to check for null.
      * @param elseValue The value that will be returned if `ifFieldName` is null.
-     * @returns A new {@code Expression} representing the ifNull operation.
+     * @returns A new Expression representing the ifNull operation.
      */
-    export function ifNull(ifFieldName: string, elseValue: unknown): Expression;
+    export function ifNull(
+      ifFieldName: string | Expression,
+      elseValue: Expression | unknown,
+    ): Expression;
 
     /**
      * @beta
@@ -11033,7 +11036,7 @@ declare namespace FirebaseFirestore {
      * @param first The first expression to evaluate.
      * @param second The next expression or literal to evaluate.
      * @param others Additional expressions or literals to evaluate.
-     * @returns A new {@code Expression} representing the coalesce operation.
+     * @returns A new [Expression] representing the coalesce operation.
      */
     export function coalesce(
       first: Expression,

From f00ca5ba6fdcd7870418fc22f829c9674ceaaa58 Mon Sep 17 00:00:00 2001
From: Mila <107142260+milaGGL@users.noreply.github.com>
Date: Wed, 25 Mar 2026 15:49:53 -0400
Subject: [PATCH 3/4] update jsdocs

---
 .../firestore/api-report/firestore.api.md     |  18 +--
 .../firestore/dev/src/pipelines/expression.ts | 143 +++++++++++-------
 handwritten/firestore/types/firestore.d.ts    | 138 ++++++++++-------
 3 files changed, 177 insertions(+), 122 deletions(-)

diff --git a/handwritten/firestore/api-report/firestore.api.md b/handwritten/firestore/api-report/firestore.api.md
index b7602461a2b..e152832bc54 100644
--- a/handwritten/firestore/api-report/firestore.api.md
+++ b/handwritten/firestore/api-report/firestore.api.md
@@ -499,10 +499,10 @@ function charLength(fieldName: string): FunctionExpression;
 function charLength(stringExpression: Expression): FunctionExpression;
 
 // @beta
-function coalesce(first: Expression, second: Expression | unknown, ...others: Array<Expression | unknown>): Expression;
+function coalesce(expression: Expression, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
 
 // @beta
-function coalesce(firstFieldName: string, second: Expression | unknown, ...others: Array<Expression | unknown>): Expression;
+function coalesce(fieldName: string, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
 
 // Warning: (tsdoc-undefined-tag) The TSDoc tag "@class" is not defined in this configuration
 //
@@ -1105,7 +1105,7 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     byteLength(): FunctionExpression;
     ceil(): FunctionExpression;
     charLength(): FunctionExpression;
-    coalesce(second: Expression | unknown, ...others: Array<Expression | unknown>): Expression;
+    coalesce(replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
     collectionId(): FunctionExpression;
     concat(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
     cosineDistance(vectorExpression: Expression): FunctionExpression;
@@ -1142,8 +1142,8 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     ifAbsent(elseExpression: unknown): Expression;
     ifError(catchExpr: Expression): FunctionExpression;
     ifError(catchValue: unknown): FunctionExpression;
-    ifNull(elseValue: unknown): Expression;
-    ifNull(elseExpression: unknown): Expression;
+    ifNull(elseExpression: Expression): FunctionExpression;
+    ifNull(elseValue: unknown): FunctionExpression;
     isAbsent(): BooleanExpression;
     isError(): BooleanExpression;
     isType(type: string): BooleanExpression;
@@ -1648,16 +1648,16 @@ function ifError(tryExpr: Expression, catchExpr: Expression): FunctionExpression
 function ifError(tryExpr: Expression, catchValue: unknown): FunctionExpression;
 
 // @beta
-function ifNull(ifExpr: Expression, elseExpr: Expression): Expression;
+function ifNull(ifExpr: Expression, elseExpr: Expression): FunctionExpression;
 
 // @beta
-function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
+function ifNull(ifExpr: Expression, elseValue: unknown): FunctionExpression;
 
 // @beta
-function ifNull(ifFieldName: string, elseExpr: Expression): Expression;
+function ifNull(ifFieldName: string, elseExpr: Expression): FunctionExpression;
 
 // @beta
-function ifNull(ifFieldName: string, elseValue: unknown): Expression;
+function ifNull(ifFieldName: string, elseValue: unknown): FunctionExpression;
 
 // @beta
 function isAbsent(value: Expression): BooleanExpression;
diff --git a/handwritten/firestore/dev/src/pipelines/expression.ts b/handwritten/firestore/dev/src/pipelines/expression.ts
index 096207d6a6b..fb60cdde547 100644
--- a/handwritten/firestore/dev/src/pipelines/expression.ts
+++ b/handwritten/firestore/dev/src/pipelines/expression.ts
@@ -2881,35 +2881,41 @@ export abstract class Expression
    * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
    * return the result of this expression evaluation.
    *
+   * @remarks
+   * This function provides a fallback for both absent and explicit null values. In contrast, {@link ifAbsent}
+   * only triggers for missing fields.
+   *
    * @example
    * ```typescript
-   * // Returns the value of the 'optional_field', or returns 'default_value'
-   * // if the field is null.
-   * field("optional_field").ifNull("default_value")
+   * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+   * field("preferredName").ifNull(field("fullName"))
    * ```
    *
-   * @param elseValue The value that will be returned if this Expression evaluates to a null value.
+   * @param elseExpression The Expression that will be evaluated if this Expression evaluates to a null or absent value.
    * @returns A new [Expression] representing the ifNull operation.
    */
-  ifNull(elseValue: unknown): Expression;
+  ifNull(elseExpression: Expression): FunctionExpression;
 
   /**
    * @beta
    * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
    * return the result of this expression evaluation.
    *
+   * @remarks
+   * This function provides a fallback for both absent and explicit null values. In contrast, {@link ifAbsent}
+   * only triggers for missing fields.
+   *
    * @example
    * ```typescript
-   * // Returns the value of the 'optional_field', or if that is
-   * // null, then returns the value of the field `
-   * field("optional_field").ifNull(field('default_field'))
+   * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+   * field("displayName").ifNull("Anonymous")
    * ```
    *
-   * @param elseExpression The Expression that will be evaluated if this Expression evaluates to a null value.
+   * @param elseValue The value that will be returned if this Expression evaluates to a null or absent value.
    * @returns A new [Expression] representing the ifNull operation.
    */
-  ifNull(elseExpression: unknown): Expression;
-  ifNull(elseValueOrExpression: Expression | unknown): Expression {
+  ifNull(elseValue: unknown): FunctionExpression;
+  ifNull(elseValueOrExpression: Expression | unknown): FunctionExpression {
     return new FunctionExpression('if_null', [
       this,
       valueToDefaultExpr(elseValueOrExpression),
@@ -2918,15 +2924,14 @@ export abstract class Expression
 
   /**
    * @beta
-   * Creates an expression that Returns the first non-null, non-absent argument, without evaluating
+   * Creates an expression that returns the first non-null, non-absent argument, without evaluating
    * the rest of the arguments. When all arguments are null or absent, returns the last argument.
    *
    * @example
    * ```typescript
-   * // Return "Anonymous" if the 'name' field is null.
-   * field("name").coalesce("Anonymous");
-   * // Return "val1" if "val1" is not null, otherwise "val2", or "default" if both are null.
-   * field("val1").coalesce(field("val2"), "default");
+   * // Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
+   * // or the last argument if all previous fields are null.
+   * field("preferredName").coalesce(field("fullName"), "Anonymous");
    * ```
    *
    * @param replacement - The value to use if this expression evaluates to null.
@@ -2934,10 +2939,10 @@ export abstract class Expression
    * @returns A new [Expression] representing the coalesce operation.
    */
   coalesce(
-    second: Expression | unknown,
+    replacement: Expression | unknown,
     ...others: Array<Expression | unknown>
-  ): Expression {
-    const values = [second, ...others];
+  ): FunctionExpression {
+    const values = [replacement, ...others];
     return new FunctionExpression('coalesce', [
       this,
       ...values.map(valueToDefaultExpr),
@@ -9258,50 +9263,65 @@ export function ifAbsent(
 
 /**
  * @beta
- * Creates an expression that returns the `elseExpr` argument if `ifExpr` is null or absent, else
+ * Creates an expression that returns the `elseExpr` argument if `ifExpr` is null, else
  * return the result of the `ifExpr` argument evaluation.
  *
+ * @remarks
+ * This function provides a fallback for both absent and explicit null values. In contrast,
+ * {@link ifAbsent} only triggers for missing fields.
+ *
  * @example
  * ```typescript
- * // Returns the value of the 'optional_field', or returns value of the 'default_field'
- * // if the 'optional_field' value is null or absent.
- * ifNull(field("optional_field"), field("default_field"))
+ * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+ * ifNull(field("preferredName"), field("fullName"))
  * ```
  *
  * @param ifExpr The expression to check for null or absence.
  * @param elseExpr The expression that will be evaluated and returned if `ifExpr` is null or absent.
  * @returns A new `Expression` representing the ifNull operation.
  */
-export function ifNull(ifExpr: Expression, elseExpr: Expression): Expression;
+export function ifNull(
+  ifExpr: Expression,
+  elseExpr: Expression,
+): FunctionExpression;
 
 /**
  * @beta
- * Creates an expression that returns the `elseValue` argument if `ifExpr` is null or absent, else
+ * Creates an expression that returns the `elseValue` argument if `ifExpr` is null, else
  * return the result of the `ifExpr` argument evaluation.
  *
+ * @remarks
+ * This function provides a fallback for both absent and explicit null values. In contrast,
+ * {@link ifAbsent} only triggers for missing fields.
+ *
  * @example
  * ```typescript
- * // Returns the value of the 'optional_field', or returns 'default_value'
- * // if the 'optional_field' value is null or absent.
- * ifNull(field("optional_field"), "default_value")
+ * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+ * ifNull(field("displayName"), "Anonymous")
  * ```
  *
- * @param ifExpr The expression to check for absence.
+ * @param ifExpr The expression to check for null or absence.
  * @param elseValue The value that will be returned if `ifExpr` evaluates to a null or absent value.
  * @returns A new `Expression` representing the ifNull operation.
  */
-export function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
+export function ifNull(
+  ifExpr: Expression,
+  elseValue: unknown,
+): FunctionExpression;
 
 /**
  * @beta
- * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is null or absent, else
+ * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is null, else
  * return the value of the field.
  *
+ * @remarks
+ * This function provides a fallback for both absent and explicit null values. In contrast,
+ * {@link ifAbsent} only triggers for missing fields.
+ *
  * @example
  * ```typescript
- * // Returns the value of the 'optional_field', or returns the value of
- * // 'default_field' if 'optional_field' is null or absent.
- * ifNull("optional_field", field("default_field"))
+ * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+ * ifNull("preferredName", field("fullName"))
  * ```
  *
  * @param ifFieldName The field to check for null or absence.
@@ -9309,29 +9329,38 @@ export function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
  * null or absent.
  * @returns A new `Expression` representing the ifNull operation.
  */
-export function ifNull(ifFieldName: string, elseExpr: Expression): Expression;
+export function ifNull(
+  ifFieldName: string,
+  elseExpr: Expression,
+): FunctionExpression;
 
 /**
  * @beta
- * Creates an expression that returns the `elseValue` argument if `ifFieldName` is null or absent, else
+ * Creates an expression that returns the `elseValue` argument if `ifFieldName` is null, else
  * return the value of the field.
  *
+ * @remarks
+ * This function provides a fallback for both absent and explicit null values. In contrast,
+ * {@link ifAbsent} only triggers for missing fields.
+ *
  * @example
  * ```typescript
- * // Returns the value of the 'optional_field', or returns 'default_value'
- * // if the field is null or absent.
- * ifNull("optional_field", "default_value")
+ * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+ * ifNull("displayName", "Anonymous")
  * ```
  *
  * @param ifFieldName The field to check for null or absence.
  * @param elseValue The value that will be returned if `ifFieldName` is null or absent.
  * @returns A new `Expression` representing the ifNull operation.
  */
-export function ifNull(ifFieldName: string, elseValue: unknown): Expression;
+export function ifNull(
+  ifFieldName: string,
+  elseValue: unknown,
+): FunctionExpression;
 export function ifNull(
   fieldNameOrExpression: string | Expression,
   elseValue: Expression | unknown,
-): Expression {
+): FunctionExpression {
   return fieldOrExpression(fieldNameOrExpression).ifNull(
     valueToDefaultExpr(elseValue),
   );
@@ -9339,14 +9368,14 @@ export function ifNull(
 
 /**
  * @beta
- * Returns the first non-null, non-absent argument, without evaluating
+ * Creates an expression that returns the first non-null, non-absent argument, without evaluating
  * the rest of the arguments. When all arguments are null or absent, returns the last argument.
  *
  * @example
  * ```typescript
- * // Returns the value of 'optional_field', or if that is
- * // null, then returns the value of 'default_field'
- * coalesce(field("optional_field"), field("default_field"))
+ * // Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
+ * // or the last argument if all previous fields are null.
+ * coalesce(field("preferredName"), field("fullName"), constant("Anonymous"))
  * ```
  *
  * @param expression The first expression to check for null.
@@ -9358,18 +9387,18 @@ export function coalesce(
   expression: Expression,
   replacement: Expression | unknown,
   ...others: Array<Expression | unknown>
-): Expression;
+): FunctionExpression;
 
 /**
  * @beta
- * Returns the first non-null, non-absent argument, without evaluating
+ * Creates an expression that returns the first non-null, non-absent argument, without evaluating
  * the rest of the arguments. When all arguments are null or absent, returns the last argument.
  *
  * @example
  * ```typescript
- * // Returns the value of 'optional_field', or if that is
- * // null, then returns the value of 'default_field'
- * coalesce("optional_field", field("default_field"))
+ * // Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
+ * // or the last argument if all previous fields are null.
+ * coalesce("preferredName", field("fullName"), constant("Anonymous"))
  * ```
  *
  * @param fieldName The name of the first field to check for null.
@@ -9381,14 +9410,16 @@ export function coalesce(
   fieldName: string,
   replacement: Expression | unknown,
   ...others: Array<Expression | unknown>
-): Expression;
-
+): FunctionExpression;
 export function coalesce(
-  first: Expression | string,
-  second: Expression | unknown,
+  fieldNameOrExpression: Expression | string,
+  replacement: Expression | unknown,
   ...others: Array<Expression | unknown>
-): Expression {
-  return fieldOrExpression(first).coalesce(second, ...others);
+): FunctionExpression {
+  return fieldOrExpression(fieldNameOrExpression).coalesce(
+    replacement,
+    ...others,
+  );
 }
 
 /**
diff --git a/handwritten/firestore/types/firestore.d.ts b/handwritten/firestore/types/firestore.d.ts
index f0fa56b0b78..c5878fa0ead 100644
--- a/handwritten/firestore/types/firestore.d.ts
+++ b/handwritten/firestore/types/firestore.d.ts
@@ -5459,54 +5459,61 @@ declare namespace FirebaseFirestore {
        * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
        * return the result of this expression evaluation.
        *
+       * @remarks
+       * This function provides a fallback for both absent and explicit null values. In contrast, {@link ifAbsent}
+       * only triggers for missing fields.
+       *
        * @example
        * ```typescript
-       * // Returns the value of the 'optional_field', or returns 'default_value'
-       * // if the field is null.
-       * field("optional_field").ifNull("default_value")
+       * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+       * field("displayName").ifNull("Anonymous")
        * ```
        *
        * @param elseValue The value that will be returned if this Expression evaluates to a null value.
-       * @returns A new [Expression] representing the ifNull operation.
+       * @returns A new `Expression` representing the ifNull operation.
        */
-      ifNull(elseValue: unknown): Expression;
+      ifNull(elseValue: unknown): FunctionExpression;
 
       /**
        * @beta
        * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
        * return the result of this expression evaluation.
        *
+       * @remarks
+       * This function provides a fallback for both absent and explicit null values. In contrast, {@link ifAbsent}
+       * only triggers for missing fields.
+       *
        * @example
        * ```typescript
-       * // Returns the value of the 'optional_field', or if that is
-       * // null, then returns the value of the field `
-       * field("optional_field").ifNull(field('default_field'))
+       * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+       * field("preferredName").ifNull(field("fullName"))
        * ```
        *
        * @param elseExpression The Expression that will be evaluated if this Expression evaluates to a null value.
-       * @returns A new [Expression] representing the ifNull operation.
+       * @returns A new `Expression` representing the ifNull operation.
        */
-      ifNull(elseExpression: unknown): Expression;
+      ifNull(elseExpression: Expression): FunctionExpression;
 
       /**
        * @beta
-       * Returns the first non-null value among the given expressions/values.
+       * Creates an expression that Returns the first non-null, non-absent argument, without evaluating
+       * the rest of the arguments. When all arguments are null or absent, returns the last argument.
        *
        * @example
        * ```typescript
-       * // Returns the value of the 'optional_field', or if that is
-       * // null, then returns the value of the 'default_field'
-       * field("optional_field").coalesce(field("default_field"))
+       * // Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
+       * // or the last argument if all previous fields are null.
+       * field("preferredName").coalesce(field("fullName"), "Anonymous");
        * ```
        *
-       * @param second The next expression or literal to evaluate.
+       * @param replacement The next expression or literal to evaluate.
        * @param others Additional expressions or literals to evaluate.
        * @returns A new [Expression] representing the coalesce operation.
        */
       coalesce(
-        second: Expression | unknown,
+        replacement: Expression | unknown,
         ...others: Array<Expression | unknown>
-      ): Expression;
+      ): FunctionExpression;
 
       /**
        * @beta
@@ -10945,126 +10952,143 @@ declare namespace FirebaseFirestore {
      * Creates an expression that returns the `elseExpr` argument if `ifExpr` is null, else
      * return the result of the `ifExpr` argument evaluation.
      *
+     * @remarks
+     * This function provides a fallback for both absent and explicit null values. In contrast,
+     * {@link ifAbsent} only triggers for missing fields.
+     *
      * @example
      * ```typescript
-     * // Returns the value of the 'optional_field', or returns 'default_value'
-     * // if the field is null.
-     * ifNull(field("optional_field"), "default_value")
+     * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+     * ifNull(field("preferredName"), field("fullName"))
      * ```
      *
      * @param ifExpr The expression to check for null.
      * @param elseExpr The value that will be returned if `ifExpr` evaluates to a null value.
-     * @returns A new [Expression] representing the ifNull operation.
+     * @returns A new {@code Expression} representing the ifNull operation.
      */
     export function ifNull(
       ifExpr: Expression,
       elseExpr: Expression,
-    ): Expression;
+    ): FunctionExpression;
 
     /**
      * @beta
      * Creates an expression that returns the `elseValue` argument if `ifExpr` is null, else
      * return the result of the `ifExpr` argument evaluation.
      *
+     * @remarks
+     * This function provides a fallback for both absent and explicit null values. In contrast,
+     * {@link ifAbsent} only triggers for missing fields.
+     *
      * @example
      * ```typescript
-     * // Returns the value of the 'optional_field', or returns 'default_value'
-     * // if the field is null.
-     * ifNull(field("optional_field"), "default_value")
+     * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+     * ifNull(field("displayName"), "Anonymous")
      * ```
      *
      * @param ifExpr The expression to check for null.
      * @param elseValue The value that will be returned if `ifExpr` evaluates to a null value.
-     * @returns A new [Expression] representing the ifNull operation.
+     * @returns A new {@code Expression} representing the ifNull operation.
      */
-    export function ifNull(ifExpr: Expression, elseValue: unknown): Expression;
+    export function ifNull(
+      ifExpr: Expression,
+      elseValue: unknown,
+    ): FunctionExpression;
 
     /**
      * @beta
      * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is null, else
      * return the value of the field.
      *
+     * @remarks
+     * This function provides a fallback for both absent and explicit null values. In contrast,
+     * {@link ifAbsent} only triggers for missing fields.
+     *
      * @example
      * ```typescript
-     * // Returns the value of the 'optional_field', or returns the value of
-     * // 'default_field' if 'optional_field' is null.
-     * ifNull("optional_field", field("default_field"))
+     * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+     * ifNull("preferredName", field("fullName"))
      * ```
      *
      * @param ifFieldName The field to check for null.
      * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is
      * null.
-     * @returns A new Expression representing the ifNull operation.
+     * @returns A new {@code Expression} representing the ifNull operation.
      */
     export function ifNull(
       ifFieldName: string,
       elseExpr: Expression,
-    ): Expression;
+    ): FunctionExpression;
 
     /**
      * @beta
      * Creates an expression that returns the `elseValue` argument if `ifFieldName` is null, else
      * return the value of the field.
      *
+     * @remarks
+     * This function provides a fallback for both absent and explicit null values. In contrast,
+     * {@link ifAbsent} only triggers for missing fields.
+     *
      * @example
      * ```typescript
-     * // Returns the value of the 'optional_field', or returns 'default_value'
-     * // if the field is null.
-     * ifNull("optional_field", "default_value")
+     * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+     * ifNull("displayName", "Anonymous")
      * ```
      *
      * @param ifFieldName The field to check for null.
      * @param elseValue The value that will be returned if `ifFieldName` is null.
-     * @returns A new Expression representing the ifNull operation.
+     * @returns A new {@code Expression} representing the ifNull operation.
      */
     export function ifNull(
-      ifFieldName: string | Expression,
-      elseValue: Expression | unknown,
-    ): Expression;
+      ifFieldName: string,
+      elseValue: unknown,
+    ): FunctionExpression;
 
     /**
      * @beta
-     * Returns the first non-null value among the given expressions/values.
+     * Creates an expression that returns the first non-null, non-absent argument, without evaluating
+     * the rest of the arguments. When all arguments are null or absent, returns the last argument.
      *
      * @example
      * ```typescript
-     * // Returns the value of 'optional_field', or if that is
-     * // null, then returns the value of 'default_field'
-     * coalesce("optional_field", field("default_field"))
+     * // Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
+     * // or the last argument if all previous fields are null.
+     * coalesce(field("preferredName"), field("fullName"), constant("Anonymous"))
      * ```
      *
-     * @param first The first expression to evaluate.
-     * @param second The next expression or literal to evaluate.
+     * @param expression The first expression to evaluate.
+     * @param replacement The next expression or literal to evaluate.
      * @param others Additional expressions or literals to evaluate.
      * @returns A new [Expression] representing the coalesce operation.
      */
     export function coalesce(
-      first: Expression,
-      second: Expression | unknown,
+      expression: Expression,
+      replacement: Expression | unknown,
       ...others: Array<Expression | unknown>
-    ): Expression;
+    ): FunctionExpression;
 
     /**
      * @beta
-     * Returns the first non-null value among the given expressions/values.
+     * Creates an expression that returns the first non-null, non-absent argument, without evaluating
+     * the rest of the arguments. When all arguments are null or absent, returns the last argument.
      *
      * @example
      * ```typescript
-     * // Returns the value of 'optional_field', or if that is
-     * // null, then returns the value of 'default_field'
-     * coalesce("optional_field", field("default_field"))
+     * // Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
+     * // or the last argument if all previous fields are null.
+     * coalesce("preferredName", field("fullName"), constant("Anonymous"))
      * ```
      *
-     * @param firstFieldName The first field name to evaluate.
-     * @param second The next expression or literal to evaluate.
+     * @param fieldName The first field name to evaluate.
+     * @param replacement The next expression or literal to evaluate.
      * @param others Additional expressions or literals to evaluate.
      * @returns A new [Expression] representing the coalesce operation.
      */
     export function coalesce(
-      firstFieldName: string,
-      second: Expression | unknown,
+      fieldName: string,
+      replacement: Expression | unknown,
       ...others: Array<Expression | unknown>
-    ): Expression;
+    ): FunctionExpression;
 
     /**
      * @beta

From 534545d1ba264b184a6f091e1d538f5cde55d177 Mon Sep 17 00:00:00 2001
From: Mila <107142260+milaGGL@users.noreply.github.com>
Date: Thu, 26 Mar 2026 11:42:25 -0400
Subject: [PATCH 4/4] format

---
 .../firestore/dev/src/pipelines/expression.ts | 48 +++++++++----------
 handwritten/firestore/types/firestore.d.ts    | 26 +++++-----
 2 files changed, 37 insertions(+), 37 deletions(-)

diff --git a/handwritten/firestore/dev/src/pipelines/expression.ts b/handwritten/firestore/dev/src/pipelines/expression.ts
index fb60cdde547..d7b3c9641ef 100644
--- a/handwritten/firestore/dev/src/pipelines/expression.ts
+++ b/handwritten/firestore/dev/src/pipelines/expression.ts
@@ -2878,40 +2878,40 @@ export abstract class Expression
 
   /**
    * @beta
-   * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
+   * Creates an expression that returns the `elseValue` argument if this expression evaluates to null, else
    * return the result of this expression evaluation.
    *
    * @remarks
-   * This function provides a fallback for both absent and explicit null values. In contrast, {@link ifAbsent}
+   * This function provides a fallback for both absent and explicit null values. In contrast, {@link Expression#ifAbsent}
    * only triggers for missing fields.
    *
    * @example
    * ```typescript
-   * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+   * // Returns the user's preferred name, or if that is null, returns their full name.
    * field("preferredName").ifNull(field("fullName"))
    * ```
    *
-   * @param elseExpression The Expression that will be evaluated if this Expression evaluates to a null or absent value.
+   * @param elseExpression The Expression that will be evaluated if this Expression evaluates to null.
    * @returns A new [Expression] representing the ifNull operation.
    */
   ifNull(elseExpression: Expression): FunctionExpression;
 
   /**
    * @beta
-   * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
+   * Creates an expression that returns the `elseValue` argument if this expression evaluates to null, else
    * return the result of this expression evaluation.
    *
    * @remarks
-   * This function provides a fallback for both absent and explicit null values. In contrast, {@link ifAbsent}
+   * This function provides a fallback for both absent and explicit null values. In contrast, {@link Expression#ifAbsent}
    * only triggers for missing fields.
    *
    * @example
    * ```typescript
-   * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+   * // Returns the user's display name, or returns "Anonymous" if the field is null.
    * field("displayName").ifNull("Anonymous")
    * ```
    *
-   * @param elseValue The value that will be returned if this Expression evaluates to a null or absent value.
+   * @param elseValue The value that will be returned if this Expression evaluates to null.
    * @returns A new [Expression] representing the ifNull operation.
    */
   ifNull(elseValue: unknown): FunctionExpression;
@@ -9268,16 +9268,16 @@ export function ifAbsent(
  *
  * @remarks
  * This function provides a fallback for both absent and explicit null values. In contrast,
- * {@link ifAbsent} only triggers for missing fields.
+ * {@link Expression#ifAbsent} only triggers for missing fields.
  *
  * @example
  * ```typescript
- * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+ * // Returns the user's preferred name, or if that is null, returns their full name.
  * ifNull(field("preferredName"), field("fullName"))
  * ```
  *
- * @param ifExpr The expression to check for null or absence.
- * @param elseExpr The expression that will be evaluated and returned if `ifExpr` is null or absent.
+ * @param ifExpr The expression to check for null.
+ * @param elseExpr The expression that will be evaluated and returned if `ifExpr` is null.
  * @returns A new `Expression` representing the ifNull operation.
  */
 export function ifNull(
@@ -9292,16 +9292,16 @@ export function ifNull(
  *
  * @remarks
  * This function provides a fallback for both absent and explicit null values. In contrast,
- * {@link ifAbsent} only triggers for missing fields.
+ * {@link Expression#ifAbsent} only triggers for missing fields.
  *
  * @example
  * ```typescript
- * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+ * // Returns the user's display name, or returns "Anonymous" if the field is null.
  * ifNull(field("displayName"), "Anonymous")
  * ```
  *
- * @param ifExpr The expression to check for null or absence.
- * @param elseValue The value that will be returned if `ifExpr` evaluates to a null or absent value.
+ * @param ifExpr The expression to check for null.
+ * @param elseValue The value that will be returned if `ifExpr` evaluates to null.
  * @returns A new `Expression` representing the ifNull operation.
  */
 export function ifNull(
@@ -9316,17 +9316,17 @@ export function ifNull(
  *
  * @remarks
  * This function provides a fallback for both absent and explicit null values. In contrast,
- * {@link ifAbsent} only triggers for missing fields.
+ * {@link Expression#ifAbsent} only triggers for missing fields.
  *
  * @example
  * ```typescript
- * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+ * // Returns the user's preferred name, or if that is null, returns their full name.
  * ifNull("preferredName", field("fullName"))
  * ```
  *
- * @param ifFieldName The field to check for null or absence.
+ * @param ifFieldName The field to check for null.
  * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is
- * null or absent.
+ * null.
  * @returns A new `Expression` representing the ifNull operation.
  */
 export function ifNull(
@@ -9341,16 +9341,16 @@ export function ifNull(
  *
  * @remarks
  * This function provides a fallback for both absent and explicit null values. In contrast,
- * {@link ifAbsent} only triggers for missing fields.
+ * {@link Expression#ifAbsent} only triggers for missing fields.
  *
  * @example
  * ```typescript
- * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+ * // Returns the user's display name, or returns "Anonymous" if the field is null.
  * ifNull("displayName", "Anonymous")
  * ```
  *
- * @param ifFieldName The field to check for null or absence.
- * @param elseValue The value that will be returned if `ifFieldName` is null or absent.
+ * @param ifFieldName The field to check for null.
+ * @param elseValue The value that will be returned if `ifFieldName` is null.
  * @returns A new `Expression` representing the ifNull operation.
  */
 export function ifNull(
diff --git a/handwritten/firestore/types/firestore.d.ts b/handwritten/firestore/types/firestore.d.ts
index c5878fa0ead..29a149f132e 100644
--- a/handwritten/firestore/types/firestore.d.ts
+++ b/handwritten/firestore/types/firestore.d.ts
@@ -5456,7 +5456,7 @@ declare namespace FirebaseFirestore {
 
       /**
        * @beta
-       * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
+       * Creates an expression that returns the `elseValue` argument if this expression evaluates to null, else
        * return the result of this expression evaluation.
        *
        * @remarks
@@ -5465,18 +5465,18 @@ declare namespace FirebaseFirestore {
        *
        * @example
        * ```typescript
-       * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+       * // Returns the user's display name, or returns "Anonymous" if the field is null.
        * field("displayName").ifNull("Anonymous")
        * ```
        *
-       * @param elseValue The value that will be returned if this Expression evaluates to a null value.
+       * @param elseValue The value that will be returned if this Expression evaluates to null.
        * @returns A new `Expression` representing the ifNull operation.
        */
       ifNull(elseValue: unknown): FunctionExpression;
 
       /**
        * @beta
-       * Creates an expression that returns the `elseValue` argument if this expression results in a null value, else
+       * Creates an expression that returns the `elseValue` argument if this expression evaluates to null, else
        * return the result of this expression evaluation.
        *
        * @remarks
@@ -5485,18 +5485,18 @@ declare namespace FirebaseFirestore {
        *
        * @example
        * ```typescript
-       * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+       * // Returns the user's preferred name, or if that is null, returns their full name.
        * field("preferredName").ifNull(field("fullName"))
        * ```
        *
-       * @param elseExpression The Expression that will be evaluated if this Expression evaluates to a null value.
+       * @param elseExpression The Expression that will be evaluated if this Expression evaluates to null.
        * @returns A new `Expression` representing the ifNull operation.
        */
       ifNull(elseExpression: Expression): FunctionExpression;
 
       /**
        * @beta
-       * Creates an expression that Returns the first non-null, non-absent argument, without evaluating
+       * Creates an expression that returns the first non-null, non-absent argument, without evaluating
        * the rest of the arguments. When all arguments are null or absent, returns the last argument.
        *
        * @example
@@ -10958,12 +10958,12 @@ declare namespace FirebaseFirestore {
      *
      * @example
      * ```typescript
-     * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+     * // Returns the user's preferred name, or if that is null, returns their full name.
      * ifNull(field("preferredName"), field("fullName"))
      * ```
      *
      * @param ifExpr The expression to check for null.
-     * @param elseExpr The value that will be returned if `ifExpr` evaluates to a null value.
+     * @param elseExpr The value that will be returned if `ifExpr` evaluates to null.
      * @returns A new {@code Expression} representing the ifNull operation.
      */
     export function ifNull(
@@ -10982,12 +10982,12 @@ declare namespace FirebaseFirestore {
      *
      * @example
      * ```typescript
-     * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+     * // Returns the user's display name, or returns "Anonymous" if the field is null.
      * ifNull(field("displayName"), "Anonymous")
      * ```
      *
      * @param ifExpr The expression to check for null.
-     * @param elseValue The value that will be returned if `ifExpr` evaluates to a null value.
+     * @param elseValue The value that will be returned if `ifExpr` evaluates to null.
      * @returns A new {@code Expression} representing the ifNull operation.
      */
     export function ifNull(
@@ -11006,7 +11006,7 @@ declare namespace FirebaseFirestore {
      *
      * @example
      * ```typescript
-     * // Returns the user's preferred name, or if that is null or absent, returns their full name.
+     * // Returns the user's preferred name, or if that is null, returns their full name.
      * ifNull("preferredName", field("fullName"))
      * ```
      *
@@ -11031,7 +11031,7 @@ declare namespace FirebaseFirestore {
      *
      * @example
      * ```typescript
-     * // Returns the user's display name, or returns "Anonymous" if the field is null or absent.
+     * // Returns the user's display name, or returns "Anonymous" if the field is null.
      * ifNull("displayName", "Anonymous")
      * ```
      *