feat(firestore): Add ifNull and coalesce expressions

.changeset/rotten-tigers-bake.md

@@ -0,0 +1,6 @@
+---
+'firebase': minor
+'@firebase/firestore': minor
+---
+
+Add support for pipeline expressions `ifNull` and `coalesce`.

common/api-review/firestore-lite-pipelines.api.md

@@ -274,6 +274,12 @@ export function charLength(fieldName: string): FunctionExpression;
 // @beta
 export function charLength(stringExpression: Expression): FunctionExpression;
 
+// @beta
+export function coalesce(expression: Expression, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
+
+// @beta
+export function coalesce(fieldName: string, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
+
 // @beta
 export type CollectionGroupStageOptions = StageOptions & {
     collectionId: string;
@@ -557,6 +563,8 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     charLength(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    coalesce(replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     collectionId(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
     concat(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
@@ -624,6 +632,10 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     ifError(catchValue: unknown): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    ifNull(elseExpression: Expression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
+    ifNull(elseValue: unknown): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     isAbsent(): BooleanExpression;
     /* Excluded from this release type: _readUserData */
     isError(): BooleanExpression;
@@ -906,6 +918,18 @@ export function ifError(tryExpr: Expression, catchExpr: Expression): FunctionExp
 // @beta
 export function ifError(tryExpr: Expression, catchValue: unknown): FunctionExpression;
 
+// @beta
+export function ifNull(ifExpr: Expression, elseExpr: Expression): FunctionExpression;
+
+// @beta
+export function ifNull(ifExpr: Expression, elseValue: unknown): FunctionExpression;
+
+// @beta
+export function ifNull(ifFieldName: string, elseExpr: Expression): FunctionExpression;
+
+// @beta
+export function ifNull(ifFieldName: string, elseValue: unknown): FunctionExpression;
+
 // @beta
 export function isAbsent(value: Expression): BooleanExpression;
 

common/api-review/firestore-pipelines.api.md

@@ -274,6 +274,12 @@ export function charLength(fieldName: string): FunctionExpression;
 // @beta
 export function charLength(stringExpression: Expression): FunctionExpression;
 
+// @beta
+export function coalesce(expression: Expression, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
+
+// @beta
+export function coalesce(fieldName: string, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
+
 // @beta
 export type CollectionGroupStageOptions = StageOptions & {
     collectionId: string;
@@ -560,6 +566,8 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     charLength(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    coalesce(replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     collectionId(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
     concat(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
@@ -627,6 +635,10 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     ifError(catchValue: unknown): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    ifNull(elseExpression: Expression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
+    ifNull(elseValue: unknown): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     isAbsent(): BooleanExpression;
     /* Excluded from this release type: _readUserData */
     isError(): BooleanExpression;
@@ -909,6 +921,18 @@ export function ifError(tryExpr: Expression, catchExpr: Expression): FunctionExp
 // @beta
 export function ifError(tryExpr: Expression, catchValue: unknown): FunctionExpression;
 
+// @beta
+export function ifNull(ifExpr: Expression, elseExpr: Expression): FunctionExpression;
+
+// @beta
+export function ifNull(ifExpr: Expression, elseValue: unknown): FunctionExpression;
+
+// @beta
+export function ifNull(ifFieldName: string, elseExpr: Expression): FunctionExpression;
+
+// @beta
+export function ifNull(ifFieldName: string, elseValue: unknown): FunctionExpression;
+
 // @beta
 export function isAbsent(value: Expression): BooleanExpression;
 

docs-devsite/firestore_lite_pipelines.expression.md

@@ -78,6 +78,7 @@ export declare abstract class Expression
 |  [byteLength()](./firestore_lite_pipelines.expression.md#expressionbytelength) |  | <b><i>(Public Preview)</i></b> Creates an expression that calculates the length of this string expression in bytes. |
 |  [ceil()](./firestore_lite_pipelines.expression.md#expressionceil) |  | <b><i>(Public Preview)</i></b> Creates an expression that computes the ceiling of a numeric value. |
 |  [charLength()](./firestore_lite_pipelines.expression.md#expressioncharlength) |  | <b><i>(Public Preview)</i></b> Creates an expression that calculates the character length of a string in UTF-8. |
+|  [coalesce(replacement, others)](./firestore_lite_pipelines.expression.md#expressioncoalesce) |  | <b><i>(Public Preview)</i></b> 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. |
 |  [collectionId()](./firestore_lite_pipelines.expression.md#expressioncollectionid) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the collection ID from a path. |
 |  [concat(second, others)](./firestore_lite_pipelines.expression.md#expressionconcat) |  | <b><i>(Public Preview)</i></b> Creates an expression that concatenates expression results together. |
 |  [cosineDistance(vectorExpression)](./firestore_lite_pipelines.expression.md#expressioncosinedistance) |  | <b><i>(Public Preview)</i></b> Calculates the cosine distance between two vectors. |
@@ -110,6 +111,8 @@ export declare abstract class Expression
 |  [ifAbsent(elseExpression)](./firestore_lite_pipelines.expression.md#expressionifabsent) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the <code>elseValue</code> argument if this expression results in an absent value, else return the result of this expression evaluation. |
 |  [ifError(catchExpr)](./firestore_lite_pipelines.expression.md#expressioniferror) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the result of the <code>catchExpr</code> argument if there is an error, else return the result of this expression. |
 |  [ifError(catchValue)](./firestore_lite_pipelines.expression.md#expressioniferror) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the <code>catch</code> argument if there is an error, else return the result of this expression. |
+|  [ifNull(elseExpression)](./firestore_lite_pipelines.expression.md#expressionifnull) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the <code>elseValue</code> argument if this expression evaluates to null, else return the result of this expression evaluation. |
+|  [ifNull(elseValue)](./firestore_lite_pipelines.expression.md#expressionifnull) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the <code>elseValue</code> argument if this expression evaluates to null, else return the result of this expression evaluation. |
 |  [isAbsent()](./firestore_lite_pipelines.expression.md#expressionisabsent) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns <code>true</code> if the result of this expression is absent. Otherwise, returns <code>false</code> even if the value is <code>null</code>. |
 |  [isError()](./firestore_lite_pipelines.expression.md#expressioniserror) |  | <b><i>(Public Preview)</i></b> Creates an expression that checks if a given expression produces an error. |
 |  [isType(type)](./firestore_lite_pipelines.expression.md#expressionistype) |  | <b><i>(Public Preview)</i></b> Creates an expression that checks if the result of this expression is of the given type. |
@@ -1506,6 +1509,42 @@ field("name").charLength();
 
 ```
 
+## Expression.coalesce()
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+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.
+
+<b>Signature:</b>
+
+```typescript
+coalesce(replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  replacement | [Expression](./firestore_lite_pipelines.expression.md#expression_class) \| unknown | The value to use if this expression evaluates to null. |
+|  others | Array&lt;[Expression](./firestore_lite_pipelines.expression.md#expression_class) \| unknown&gt; | Optional additional values to check if previous values are null. |
+
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the coalesce operation.
+
+### 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");
+
+```
+
 ## Expression.collectionId()
 
 > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
@@ -2537,6 +2576,78 @@ field("title").arrayGet(0).ifError("Default Title");
 
 ```
 
+## Expression.ifNull()
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Creates an expression that returns the `elseValue` argument if this expression evaluates to null, else return the result of this expression evaluation.
+
+This function provides a fallback for both absent and explicit null values. In contrast, `ifAbsent()` only triggers for missing fields.
+
+<b>Signature:</b>
+
+```typescript
+ifNull(elseExpression: Expression): FunctionExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  elseExpression | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The Expression that will be evaluated if this Expression evaluates to null. |
+
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the ifNull operation.
+
+### Example
+
+
+```typescript
+// Returns the user's preferred name, or if that is null, returns their full name.
+field("preferredName").ifNull(field("fullName"))
+
+```
+
+## Expression.ifNull()
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Creates an expression that returns the `elseValue` argument if this expression evaluates to null, else return the result of this expression evaluation.
+
+This function provides a fallback for both absent and explicit null values. In contrast, `ifAbsent()` only triggers for missing fields.
+
+<b>Signature:</b>
+
+```typescript
+ifNull(elseValue: unknown): FunctionExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  elseValue | unknown | The value that will be returned if this Expression evaluates to null. |
+
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the ifNull operation.
+
+### Example
+
+
+```typescript
+// Returns the user's display name, or returns "Anonymous" if the field is null.
+field("displayName").ifNull("Anonymous")
+
+```
+
 ## Expression.isAbsent()
 
 > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.