update js docs

Author: milaGGL

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;
 

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,