Merge pull request #7857 from googleapis/mila/ifnull-coalesce

Author: milaGGL

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(expression: Expression, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
+
+// @beta
+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
 //
 // @public
@@ -1099,6 +1105,7 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     byteLength(): FunctionExpression;
     ceil(): FunctionExpression;
     charLength(): FunctionExpression;
+    coalesce(replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
     collectionId(): FunctionExpression;
     concat(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
     cosineDistance(vectorExpression: Expression): FunctionExpression;
@@ -1135,6 +1142,8 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     ifAbsent(elseExpression: unknown): Expression;
     ifError(catchExpr: Expression): FunctionExpression;
     ifError(catchValue: unknown): FunctionExpression;
+    ifNull(elseExpression: Expression): FunctionExpression;
+    ifNull(elseValue: unknown): FunctionExpression;
     isAbsent(): BooleanExpression;
     isError(): BooleanExpression;
     isType(type: string): BooleanExpression;
@@ -1643,6 +1652,18 @@ function ifError(tryExpr: Expression, catchExpr: Expression): FunctionExpression
 // @beta
 function ifError(tryExpr: Expression, catchValue: unknown): FunctionExpression;
 
+// @beta
+function ifNull(ifExpr: Expression, elseExpr: Expression): FunctionExpression;
+
+// @beta
+function ifNull(ifExpr: Expression, elseValue: unknown): FunctionExpression;
+
+// @beta
+function ifNull(ifFieldName: string, elseExpr: Expression): FunctionExpression;
+
+// @beta
+function ifNull(ifFieldName: string, elseValue: unknown): FunctionExpression;
+
 // @beta
 function isAbsent(value: Expression): BooleanExpression;
 
@@ -2139,7 +2160,9 @@ declare namespace Pipelines {
         stringReplaceAll,
         stringReplaceOne,
         nor,
-        switchOn
+        switchOn,
+        ifNull,
+        coalesce
     }
 }
 export { Pipelines }

handwritten/firestore/dev/src/pipelines/expression.ts

@@ -2976,6 +2976,79 @@ export abstract class Expression
     ]);
   }
 
+  /**
+   * @beta
+   * 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 Expression#ifAbsent}
+   * only triggers for missing fields.
+   *
+   * @example
+   * ```typescript
+   * // 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 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 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 Expression#ifAbsent}
+   * only triggers for missing fields.
+   *
+   * @example
+   * ```typescript
+   * // 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 null.
+   * @returns A new [Expression] representing the ifNull operation.
+   */
+  ifNull(elseValue: unknown): FunctionExpression;
+  ifNull(elseValueOrExpression: Expression | unknown): FunctionExpression {
+    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
+   * // 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.
+   * @param others - Optional additional values to check if previous values are null.
+   * @returns A new [Expression] representing the coalesce operation.
+   */
+  coalesce(
+    replacement: Expression | unknown,
+    ...others: Array<Expression | unknown>
+  ): FunctionExpression {
+    const values = [replacement, ...others];
+    return new FunctionExpression('coalesce', [
+      this,
+      ...values.map(valueToDefaultExpr),
+    ]);
+  }
+
   /**
    * @beta
    * Creates an expression that joins the elements of an array into a string.
@@ -9310,6 +9383,167 @@ 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.
+ *
+ * @remarks
+ * 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, returns their full name.
+ * ifNull(field("preferredName"), field("fullName"))
+ * ```
+ *
+ * @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(
+  ifExpr: Expression,
+  elseExpr: 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 Expression#ifAbsent} only triggers for missing fields.
+ *
+ * @example
+ * ```typescript
+ * // 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 null.
+ * @returns A new `Expression` representing the ifNull operation.
+ */
+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 Expression#ifAbsent} only triggers for missing fields.
+ *
+ * @example
+ * ```typescript
+ * // 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.
+ * @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,
+): 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 Expression#ifAbsent} only triggers for missing fields.
+ *
+ * @example
+ * ```typescript
+ * // 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.
+ * @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,
+): FunctionExpression;
+export function ifNull(
+  fieldNameOrExpression: string | Expression,
+  elseValue: Expression | unknown,
+): FunctionExpression {
+  return fieldOrExpression(fieldNameOrExpression).ifNull(
+    valueToDefaultExpr(elseValue),
+  );
+}
+
+/**
+ * @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
+ * // 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.
+ * @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(
+  expression: Expression,
+  replacement: Expression | unknown,
+  ...others: Array<Expression | unknown>
+): FunctionExpression;
+
+/**
+ * @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
+ * // 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.
+ * @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(
+  fieldName: string,
+  replacement: Expression | unknown,
+  ...others: Array<Expression | unknown>
+): FunctionExpression;
+export function coalesce(
+  fieldNameOrExpression: Expression | string,
+  replacement: Expression | unknown,
+  ...others: Array<Expression | unknown>
+): FunctionExpression {
+  return fieldOrExpression(fieldNameOrExpression).coalesce(
+    replacement,
+    ...others,
+  );
+}
+
 /**
  * @beta
  * Creates an expression that joins the elements of an array into a string.

handwritten/firestore/dev/src/pipelines/index.ts

@@ -159,5 +159,7 @@ export {
   stringReplaceOne,
   nor,
   switchOn,
+  ifNull,
+  coalesce,
   // TODO(new-expression): Add new expression exports above this line
 } from './expression';