feat(firestore): Add ifNull and 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(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

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.

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';