diff --git a/dev/src/pipelines/expression.ts b/dev/src/pipelines/expression.ts index d8a322d8d..df567b1b7 100644 --- a/dev/src/pipelines/expression.ts +++ b/dev/src/pipelines/expression.ts @@ -40,11 +40,13 @@ import {cast} from '../util'; * - **Literals:** Represent constant values (strings, numbers, booleans). * - **Function calls:** Apply functions to one or more expressions. * - * The `Expr` class provides a fluent API for building expressions. You can chain together + * The `Expression` class provides a fluent API for building expressions. You can chain together * method calls to create complex expressions. */ -export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { - abstract exprType: firestore.Pipelines.ExprType; +export abstract class Expression + implements firestore.Pipelines.Expression, HasUserData +{ + abstract expressionType: firestore.Pipelines.ExpressionType; /** * @beta @@ -81,14 +83,14 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * @param second The expression or literal to add to this expression. * @param others Optional additional expressions or literals to add to this expression. - * @return A new `Expr` representing the addition operation. + * @return A new `Expression` representing the addition operation. */ add( - second: firestore.Pipelines.Expr | unknown, - ...others: Array - ): FunctionExpr { + second: firestore.Pipelines.Expression | unknown, + ...others: Array + ): FunctionExpression { const values = [second, ...others]; - return new FunctionExpr('add', [ + return new FunctionExpression('add', [ this, ...values.map(value => valueToDefaultExpr(value)), ]); @@ -104,9 +106,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param subtrahend The expression to subtract from this expression. - * @return A new `Expr` representing the subtraction operation. + * @return A new `Expression` representing the subtraction operation. */ - subtract(subtrahend: firestore.Pipelines.Expr): FunctionExpr; + subtract(subtrahend: firestore.Pipelines.Expression): FunctionExpression; /** * @beta @@ -118,11 +120,16 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param subtrahend The constant value to subtract. - * @return A new `Expr` representing the subtraction operation. + * @return A new `Expression` representing the subtraction operation. */ - subtract(subtrahend: number): FunctionExpr; - subtract(subtrahend: number | firestore.Pipelines.Expr): FunctionExpr { - return new FunctionExpr('subtract', [this, valueToDefaultExpr(subtrahend)]); + subtract(subtrahend: number): FunctionExpression; + subtract( + subtrahend: number | firestore.Pipelines.Expression + ): FunctionExpression { + return new FunctionExpression('subtract', [ + this, + valueToDefaultExpr(subtrahend), + ]); } /** @@ -136,13 +143,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * @param second The second expression or literal to multiply by. * @param others Optional additional expressions or literals to multiply by. - * @return A new `Expr` representing the multiplication operation. + * @return A new `Expression` representing the multiplication operation. */ multiply( - second: Expr | number, - ...others: Array - ): FunctionExpr { - return new FunctionExpr('multiply', [ + second: Expression | number, + ...others: Array + ): FunctionExpression { + return new FunctionExpression('multiply', [ this, valueToDefaultExpr(second), ...others.map(value => valueToDefaultExpr(value)), @@ -159,9 +166,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param divisor The expression to divide by. - * @return A new `Expr` representing the division operation. + * @return A new `Expression` representing the division operation. */ - divide(divisor: Expr): FunctionExpr; + divide(divisor: Expression): FunctionExpression; /** * @beta @@ -173,11 +180,14 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param divisor The constant value to divide by. - * @return A new `Expr` representing the division operation. + * @return A new `Expression` representing the division operation. */ - divide(divisor: number): FunctionExpr; - divide(divisor: number | Expr): FunctionExpr { - return new FunctionExpr('divide', [this, valueToDefaultExpr(divisor)]); + divide(divisor: number): FunctionExpression; + divide(divisor: number | Expression): FunctionExpression { + return new FunctionExpression('divide', [ + this, + valueToDefaultExpr(divisor), + ]); } /** @@ -190,9 +200,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param expression The expression to divide by. - * @return A new `Expr` representing the modulo operation. + * @return A new `Expression` representing the modulo operation. */ - mod(expression: Expr): FunctionExpr; + mod(expression: Expression): FunctionExpression; /** * @beta @@ -204,11 +214,11 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param value The constant value to divide by. - * @return A new `Expr` representing the modulo operation. + * @return A new `Expression` representing the modulo operation. */ - mod(value: number): FunctionExpr; - mod(other: number | Expr): FunctionExpr { - return new FunctionExpr('mod', [this, valueToDefaultExpr(other)]); + mod(value: number): FunctionExpression; + mod(other: number | Expression): FunctionExpression { + return new FunctionExpression('mod', [this, valueToDefaultExpr(other)]); } /** @@ -217,13 +227,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'age' field is equal to 21 - * field("age").eq(21); + * field("age").equal(21); * ``` * * @param expression The expression to compare for equality. - * @return A new `Expr` representing the equality comparison. + * @return A new `Expression` representing the equality comparison. */ - eq(expression: Expr): BooleanExpr; + equal(expression: Expression): BooleanExpression; /** * @beta @@ -231,15 +241,15 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'city' field is equal to "London" - * field("city").eq("London"); + * field("city").equal("London"); * ``` * * @param value The constant value to compare for equality. - * @return A new `Expr` representing the equality comparison. + * @return A new `Expression` representing the equality comparison. */ - eq(value: unknown): BooleanExpr; - eq(other: unknown): BooleanExpr { - return new BooleanExpr('eq', [this, valueToDefaultExpr(other)]); + equal(value: unknown): BooleanExpression; + equal(other: unknown): BooleanExpression { + return new BooleanExpression('equal', [this, valueToDefaultExpr(other)]); } /** @@ -248,13 +258,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'status' field is not equal to "completed" - * field("status").neq("completed"); + * field("status").notEqual("completed"); * ``` * * @param expression The expression to compare for inequality. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ - neq(expression: Expr): BooleanExpr; + notEqual(expression: Expression): BooleanExpression; /** * @beta @@ -262,15 +272,18 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'country' field is not equal to "USA" - * field("country").neq("USA"); + * field("country").notEqual("USA"); * ``` * * @param value The constant value to compare for inequality. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ - neq(value: unknown): BooleanExpr; - neq(other: unknown): BooleanExpr { - return new BooleanExpr('neq', [this, valueToDefaultExpr(other)]); + notEqual(value: unknown): BooleanExpression; + notEqual(other: unknown): BooleanExpression { + return new BooleanExpression('not_equal', [ + this, + valueToDefaultExpr(other), + ]); } /** @@ -279,13 +292,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'age' field is less than 'limit' - * field("age").lt(field('limit')); + * field("age").lessThan(field('limit')); * ``` * * @param experession The expression to compare for less than. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ - lt(experession: Expr): BooleanExpr; + lessThan(experession: Expression): BooleanExpression; /** * @beta @@ -293,15 +306,18 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'price' field is less than 50 - * field("price").lt(50); + * field("price").lessThan(50); * ``` * * @param value The constant value to compare for less than. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ - lt(value: unknown): BooleanExpr; - lt(other: unknown): BooleanExpr { - return new BooleanExpr('lt', [this, valueToDefaultExpr(other)]); + lessThan(value: unknown): BooleanExpression; + lessThan(other: unknown): BooleanExpression { + return new BooleanExpression('less_than', [ + this, + valueToDefaultExpr(other), + ]); } /** @@ -311,13 +327,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'quantity' field is less than or equal to 20 - * field("quantity").lte(constant(20)); + * field("quantity").lessThanOrEqual(constant(20)); * ``` * * @param expression The expression to compare for less than or equal to. - * @return A new `Expr` representing the less than or equal to comparison. + * @return A new `Expression` representing the less than or equal to comparison. */ - lte(expression: Expr): BooleanExpr; + lessThanOrEqual(expression: Expression): BooleanExpression; /** * @beta @@ -325,15 +341,18 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'score' field is less than or equal to 70 - * field("score").lte(70); + * field("score").lessThanOrEqual(70); * ``` * * @param value The constant value to compare for less than or equal to. - * @return A new `Expr` representing the less than or equal to comparison. + * @return A new `Expression` representing the less than or equal to comparison. */ - lte(value: unknown): BooleanExpr; - lte(other: unknown): BooleanExpr { - return new BooleanExpr('lte', [this, valueToDefaultExpr(other)]); + lessThanOrEqual(value: unknown): BooleanExpression; + lessThanOrEqual(other: unknown): BooleanExpression { + return new BooleanExpression('less_than_or_equal', [ + this, + valueToDefaultExpr(other), + ]); } /** @@ -342,13 +361,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'age' field is greater than the 'limit' field - * field("age").gt(field("limit")); + * field("age").greaterThan(field("limit")); * ``` * * @param expression The expression to compare for greater than. - * @return A new `Expr` representing the greater than comparison. + * @return A new `Expression` representing the greater than comparison. */ - gt(expression: Expr): BooleanExpr; + greaterThan(expression: Expression): BooleanExpression; /** * @beta @@ -356,15 +375,18 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'price' field is greater than 100 - * field("price").gt(100); + * field("price").greaterThan(100); * ``` * * @param value The constant value to compare for greater than. - * @return A new `Expr` representing the greater than comparison. + * @return A new `Expression` representing the greater than comparison. */ - gt(value: unknown): BooleanExpr; - gt(other: unknown): BooleanExpr { - return new BooleanExpr('gt', [this, valueToDefaultExpr(other)]); + greaterThan(value: unknown): BooleanExpression; + greaterThan(other: unknown): BooleanExpression { + return new BooleanExpression('greater_than', [ + this, + valueToDefaultExpr(other), + ]); } /** @@ -374,13 +396,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'quantity' field is greater than or equal to field 'requirement' plus 1 - * field("quantity").gte(field('requirement').add(1)); + * field("quantity").greaterThanOrEqual(field('requirement').add(1)); * ``` * * @param expression The expression to compare for greater than or equal to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ - gte(expression: Expr): BooleanExpr; + greaterThanOrEqual(expression: Expression): BooleanExpression; /** * @beta @@ -389,15 +411,39 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'score' field is greater than or equal to 80 - * field("score").gte(80); + * field("score").greaterThanOrEqual(80); * ``` * * @param value The constant value to compare for greater than or equal to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ - gte(value: unknown): BooleanExpr; - gte(other: unknown): BooleanExpr { - return new BooleanExpr('gte', [this, valueToDefaultExpr(other)]); + greaterThanOrEqual(value: unknown): BooleanExpression; + greaterThanOrEqual(other: unknown): BooleanExpression { + return new BooleanExpression('greater_than_or_equal', [ + this, + valueToDefaultExpr(other), + ]); + } + + /** + * @beta + * Creates an expression that concatenates an array expression with one or more other arrays. + * + * ```typescript + * // Combine the 'items' array with another array field. + * field("items").arrayConcat(field("otherItems")); + * ``` + * @param secondArray Second array expression or array literal to concatenate. + * @param otherArrays Optional additional array expressions or array literals to concatenate. + * @return A new `Expr` representing the concatenated array. + */ + arrayConcat( + secondArray: Expression | unknown[], + ...otherArrays: Array + ): FunctionExpression { + const elements = [secondArray, ...otherArrays]; + const exprValues = elements.map(value => valueToDefaultExpr(value)); + return new FunctionExpression('array_concat', [this, ...exprValues]); } /** @@ -410,9 +456,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param expression The element to search for in the array. - * @return A new `Expr` representing the 'array_contains' comparison. + * @return A new `Expression` representing the 'array_contains' comparison. */ - arrayContains(expression: Expr): BooleanExpr; + arrayContains(expression: Expression): BooleanExpression; /** * @beta @@ -424,11 +470,11 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param value The element to search for in the array. - * @return A new `Expr` representing the 'array_contains' comparison. + * @return A new `Expression` representing the 'array_contains' comparison. */ - arrayContains(value: unknown): BooleanExpr; - arrayContains(element: unknown): BooleanExpr { - return new BooleanExpr('array_contains', [ + arrayContains(value: unknown): BooleanExpression; + arrayContains(element: unknown): BooleanExpression { + return new BooleanExpression('array_contains', [ this, valueToDefaultExpr(element), ]); @@ -444,9 +490,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param values The elements to check for in the array. - * @return A new `Expr` representing the 'array_contains_all' comparison. + * @return A new `Expression` representing the 'array_contains_all' comparison. */ - arrayContainsAll(values: Array): BooleanExpr; + arrayContainsAll(values: Array): BooleanExpression; /** * @beta @@ -458,14 +504,14 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param arrayExpression The elements to check for in the array. - * @return A new `Expr` representing the 'array_contains_all' comparison. + * @return A new `Expression` representing the 'array_contains_all' comparison. */ - arrayContainsAll(arrayExpression: Expr): BooleanExpr; - arrayContainsAll(values: unknown[] | Expr): BooleanExpr { + arrayContainsAll(arrayExpression: Expression): BooleanExpression; + arrayContainsAll(values: unknown[] | Expression): BooleanExpression { const normalizedExpr = Array.isArray(values) ? new ListOfExprs(values.map(valueToDefaultExpr)) - : cast(values); - return new BooleanExpr('array_contains_all', [this, normalizedExpr]); + : cast(values); + return new BooleanExpression('array_contains_all', [this, normalizedExpr]); } /** @@ -478,9 +524,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param values The elements to check for in the array. - * @return A new `Expr` representing the 'array_contains_any' comparison. + * @return A new `Expression` representing the 'array_contains_any' comparison. */ - arrayContainsAny(values: Array): BooleanExpr; + arrayContainsAny(values: Array): BooleanExpression; /** * @beta @@ -493,14 +539,16 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param arrayExpression The elements to check for in the array. - * @return A new `Expr` representing the 'array_contains_any' comparison. + * @return A new `Expression` representing the 'array_contains_any' comparison. */ - arrayContainsAny(arrayExpression: Expr): BooleanExpr; - arrayContainsAny(values: Array | Expr): BooleanExpr { + arrayContainsAny(arrayExpression: Expression): BooleanExpression; + arrayContainsAny( + values: Array | Expression + ): BooleanExpression { const normalizedExpr = Array.isArray(values) ? new ListOfExprs(values.map(valueToDefaultExpr)) - : cast(values); - return new BooleanExpr('array_contains_any', [this, normalizedExpr]); + : cast(values); + return new BooleanExpression('array_contains_any', [this, normalizedExpr]); } /** @@ -512,10 +560,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("myArray").arrayReverse(); * ``` * - * @return A new {@code Expr} representing the reversed array. + * @return A new {@code Expression} representing the reversed array. */ - arrayReverse(): FunctionExpr { - return new FunctionExpr('array_reverse', [this]); + arrayReverse(): FunctionExpression { + return new FunctionExpression('array_reverse', [this]); } /** @@ -527,10 +575,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("cart").arrayLength(); * ``` * - * @return A new `Expr` representing the length of the array. + * @return A new `Expression` representing the length of the array. */ - arrayLength(): FunctionExpr { - return new FunctionExpr('array_length', [this]); + arrayLength(): FunctionExpression { + return new FunctionExpression('array_length', [this]); } /** @@ -540,13 +588,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'category' field is either "Electronics" or value of field 'primaryType' - * field("category").eqAny("Electronics", field("primaryType")); + * field("category").equalAny("Electronics", field("primaryType")); * ``` * * @param values The values or expressions to check against. - * @return A new `Expr` representing the 'IN' comparison. + * @return A new `Expression` representing the 'IN' comparison. */ - eqAny(values: Array): BooleanExpr; + equalAny(values: Array): BooleanExpression; /** * @beta @@ -555,18 +603,18 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'category' field is either "Electronics" or value of field 'primaryType' - * field("category").eqAny(array(["Electronics", field("primaryType")])); + * field("category").equalAny(array(["Electronics", field("primaryType")])); * ``` * * @param arrayExpression An expression that evaluates to an array of values to check against. - * @return A new `Expr` representing the 'IN' comparison. + * @return A new `Expression` representing the 'IN' comparison. */ - eqAny(arrayExpression: Expr): BooleanExpr; - eqAny(others: unknown[] | Expr): BooleanExpr { + equalAny(arrayExpression: Expression): BooleanExpression; + equalAny(others: unknown[] | Expression): BooleanExpression { const exprOthers = Array.isArray(others) ? new ListOfExprs(others.map(valueToDefaultExpr)) - : cast(others); - return new BooleanExpr('eq_any', [this, exprOthers]); + : cast(others); + return new BooleanExpression('equal_any', [this, exprOthers]); } /** @@ -576,13 +624,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus' - * field("status").notEqAny(["pending", field("rejectedStatus")]); + * field("status").notEqualAny(["pending", field("rejectedStatus")]); * ``` * * @param values The values or expressions to check against. - * @return A new `Expr` representing the 'NotEqAny' comparison. + * @return A new `Expression` representing the 'NotEqAny' comparison. */ - notEqAny(values: Array): BooleanExpr; + notEqualAny(values: Array): BooleanExpression; /** * @beta @@ -590,48 +638,18 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'status' field is not equal to any value in the field 'rejectedStatuses' - * field("status").notEqAny(field('rejectedStatuses')); + * field("status").notEqualAny(field('rejectedStatuses')); * ``` * * @param arrayExpression The values or expressions to check against. - * @return A new `Expr` representing the 'NotEqAny' comparison. + * @return A new `Expression` representing the 'NotEqAny' comparison. */ - notEqAny(arrayExpression: Expr): BooleanExpr; - notEqAny(others: unknown[] | Expr): BooleanExpr { + notEqualAny(arrayExpression: Expression): BooleanExpression; + notEqualAny(others: unknown[] | Expression): BooleanExpression { const exprOthers = Array.isArray(others) ? new ListOfExprs(others.map(valueToDefaultExpr)) - : cast(others); - return new BooleanExpr('not_eq_any', [this, exprOthers]); - } - - /** - * @beta - * Creates an expression that checks if this expression evaluates to 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NaN - * field("value").divide(0).isNan(); - * ``` - * - * @return A new `Expr` representing the 'isNan' check. - */ - isNan(): BooleanExpr { - return new BooleanExpr('is_nan', [this]); - } - - /** - * @beta - * Creates an expression that checks if this expression evaluates to 'Null'. - * - * ```typescript - * // Check if the result of a calculation is NaN - * field("value").isNull(); - * ``` - * - * @return A new `Expr` representing the 'isNull' check. - */ - isNull(): BooleanExpr { - return new BooleanExpr('is_null', [this]); + : cast(others); + return new BooleanExpression('not_equal_any', [this, exprOthers]); } /** @@ -643,10 +661,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("phoneNumber").exists(); * ``` * - * @return A new `Expr` representing the 'exists' check. + * @return A new `Expression` representing the 'exists' check. */ - exists(): BooleanExpr { - return new BooleanExpr('exists', [this]); + exists(): BooleanExpression { + return new BooleanExpression('exists', [this]); } /** @@ -658,10 +676,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("name").charLength(); * ``` * - * @return A new `Expr` representing the length of the string. + * @return A new `Expression` representing the length of the string. */ - charLength(): FunctionExpr { - return new FunctionExpr('char_length', [this]); + charLength(): FunctionExpression { + return new FunctionExpression('char_length', [this]); } /** @@ -674,9 +692,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new `Expr` representing the 'like' comparison. + * @return A new `Expression` representing the 'like' comparison. */ - like(pattern: string): FunctionExpr; + like(pattern: string): FunctionExpression; /** * @beta @@ -688,11 +706,14 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new `Expr` representing the 'like' comparison. + * @return A new `Expression` representing the 'like' comparison. */ - like(pattern: Expr): FunctionExpr; - like(stringOrExpr: string | Expr): FunctionExpr { - return new BooleanExpr('like', [this, valueToDefaultExpr(stringOrExpr)]); + like(pattern: Expression): FunctionExpression; + like(stringOrExpr: string | Expression): FunctionExpression { + return new BooleanExpression('like', [ + this, + valueToDefaultExpr(stringOrExpr), + ]); } /** @@ -706,9 +727,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param pattern The regular expression to use for the search. - * @return A new `Expr` representing the 'contains' comparison. + * @return A new `Expression` representing the 'contains' comparison. */ - regexContains(pattern: string): BooleanExpr; + regexContains(pattern: string): BooleanExpression; /** * @beta @@ -721,11 +742,11 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param pattern The regular expression to use for the search. - * @return A new `Expr` representing the 'contains' comparison. + * @return A new `Expression` representing the 'contains' comparison. */ - regexContains(pattern: Expr): BooleanExpr; - regexContains(stringOrExpr: string | Expr): BooleanExpr { - return new BooleanExpr('regex_contains', [ + regexContains(pattern: Expression): BooleanExpression; + regexContains(stringOrExpr: string | Expression): BooleanExpression { + return new BooleanExpression('regex_contains', [ this, valueToDefaultExpr(stringOrExpr), ]); @@ -741,9 +762,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param pattern The regular expression to use for the match. - * @return A new `Expr` representing the regular expression match. + * @return A new `Expression` representing the regular expression match. */ - regexMatch(pattern: string): BooleanExpr; + regexMatch(pattern: string): BooleanExpression; /** * @beta @@ -755,11 +776,11 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param pattern The regular expression to use for the match. - * @return A new `Expr` representing the regular expression match. + * @return A new `Expression` representing the regular expression match. */ - regexMatch(pattern: Expr): BooleanExpr; - regexMatch(stringOrExpr: string | Expr): BooleanExpr { - return new BooleanExpr('regex_match', [ + regexMatch(pattern: Expression): BooleanExpression; + regexMatch(stringOrExpr: string | Expression): BooleanExpression { + return new BooleanExpression('regex_match', [ this, valueToDefaultExpr(stringOrExpr), ]); @@ -771,13 +792,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'description' field contains "example". - * field("description").strContains("example"); + * field("description").stringContains("example"); * ``` * * @param substring The substring to search for. - * @return A new `Expr` representing the 'contains' comparison. + * @return A new `Expression` representing the 'contains' comparison. */ - strContains(substring: string): BooleanExpr; + stringContains(substring: string): BooleanExpression; /** * @beta @@ -785,15 +806,15 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Check if the 'description' field contains the value of the 'keyword' field. - * field("description").strContains(field("keyword")); + * field("description").stringContains(field("keyword")); * ``` * * @param expr The expression representing the substring to search for. - * @return A new `Expr` representing the 'contains' comparison. + * @return A new `Expression` representing the 'contains' comparison. */ - strContains(expr: Expr): BooleanExpr; - strContains(stringOrExpr: string | Expr): BooleanExpr { - return new BooleanExpr('str_contains', [ + stringContains(expr: Expression): BooleanExpression; + stringContains(stringOrExpr: string | Expression): BooleanExpression { + return new BooleanExpression('string_contains', [ this, valueToDefaultExpr(stringOrExpr), ]); @@ -809,9 +830,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param prefix The prefix to check for. - * @return A new `Expr` representing the 'starts with' comparison. + * @return A new `Expression` representing the 'starts with' comparison. */ - startsWith(prefix: string): BooleanExpr; + startsWith(prefix: string): BooleanExpression; /** * @beta @@ -824,11 +845,11 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param prefix The prefix expression to check for. - * @return A new `Expr` representing the 'starts with' comparison. + * @return A new `Expression` representing the 'starts with' comparison. */ - startsWith(prefix: Expr): BooleanExpr; - startsWith(stringOrExpr: string | Expr): BooleanExpr { - return new BooleanExpr('starts_with', [ + startsWith(prefix: Expression): BooleanExpression; + startsWith(stringOrExpr: string | Expression): BooleanExpression { + return new BooleanExpression('starts_with', [ this, valueToDefaultExpr(stringOrExpr), ]); @@ -844,9 +865,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param suffix The postfix to check for. - * @return A new `Expr` representing the 'ends with' comparison. + * @return A new `Expression` representing the 'ends with' comparison. */ - endsWith(suffix: string): BooleanExpr; + endsWith(suffix: string): BooleanExpression; /** * @beta @@ -859,11 +880,11 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param suffix The postfix expression to check for. - * @return A new `Expr` representing the 'ends with' comparison. + * @return A new `Expression` representing the 'ends with' comparison. */ - endsWith(suffix: Expr): BooleanExpr; - endsWith(stringOrExpr: string | Expr): BooleanExpr { - return new BooleanExpr('ends_with', [ + endsWith(suffix: Expression): BooleanExpression; + endsWith(stringOrExpr: string | Expression): BooleanExpression { + return new BooleanExpression('ends_with', [ this, valueToDefaultExpr(stringOrExpr), ]); @@ -878,10 +899,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("name").toLower(); * ``` * - * @return A new `Expr` representing the lowercase string. + * @return A new `Expression` representing the lowercase string. */ - toLower(): FunctionExpr { - return new FunctionExpr('to_lower', [this]); + toLower(): FunctionExpression { + return new FunctionExpression('to_lower', [this]); } /** @@ -893,10 +914,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("title").toUpper(); * ``` * - * @return A new `Expr` representing the uppercase string. + * @return A new `Expression` representing the uppercase string. */ - toUpper(): FunctionExpr { - return new FunctionExpr('to_upper', [this]); + toUpper(): FunctionExpression { + return new FunctionExpression('to_upper', [this]); } /** @@ -908,10 +929,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("userInput").trim(); * ``` * - * @return A new `Expr` representing the trimmed string. + * @return A new `Expression` representing the trimmed string. */ - trim(): FunctionExpr { - return new FunctionExpr('trim', [this]); + trim(): FunctionExpression { + return new FunctionExpression('trim', [this]); } /** @@ -920,35 +941,57 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Combine the 'firstName', " ", and 'lastName' fields into a single string - * field("firstName").strConcat(constant(" "), field("lastName")); + * field("firstName").stringConcat(constant(" "), field("lastName")); * ``` * * @param secondString The additional expression or string literal to concatenate. * @param otherStrings Optional additional expressions or string literals to concatenate. - * @return A new `Expr` representing the concatenated string. + * @return A new `Expression` representing the concatenated string. */ - strConcat( - secondString: Expr | string, - ...otherStrings: Array - ): FunctionExpr { + stringConcat( + secondString: Expression | string, + ...otherStrings: Array + ): FunctionExpression { const elements = [secondString, ...otherStrings]; const exprs = elements.map(valueToDefaultExpr); - return new FunctionExpr('str_concat', [this, ...exprs]); + return new FunctionExpression('string_concat', [this, ...exprs]); } /** * @beta - * Creates an expression that reverses this string expression. + * Creates an expression that concatenates expression results together. + * + * ```typescript + * // Combine the 'firstName', ' ', and 'lastName' fields into a single value. + * field("firstName").concat(constant(" "), field("lastName")); + * ``` + * + * @param second The additional expression or literal to concatenate. + * @param others Optional additional expressions or literals to concatenate. + * @return A new `Expr` representing the concatenated value. + */ + concat( + second: Expression | unknown, + ...others: Array + ): FunctionExpression { + const elements = [second, ...others]; + const exprs = elements.map(valueToDefaultExpr); + return new FunctionExpression('concat', [this, ...exprs]); + } + + /** + * @beta + * Creates an expression that reverses this string or bytes expression. * * ```typescript * // Reverse the value of the 'myString' field. * field("myString").reverse(); * ``` * - * @return A new {@code Expr} representing the reversed string. + * @return A new {@code Expression} representing the reversed string or bytes. */ - reverse(): FunctionExpr { - return new FunctionExpr('reverse', [this]); + reverse(): FunctionExpression { + return new FunctionExpression('reverse', [this]); } /** @@ -960,10 +1003,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("myString").byteLength(); * ``` * - * @return A new {@code Expr} representing the length of the string in bytes. + * @return A new {@code Expression} representing the length of the string in bytes. */ - byteLength(): FunctionExpr { - return new FunctionExpr('byte_length', [this]); + byteLength(): FunctionExpression { + return new FunctionExpression('byte_length', [this]); } /** @@ -975,10 +1018,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("price").ceil(); * ``` * - * @return A new {@code Expr} representing the ceiling of the numeric value. + * @return A new {@code Expression} representing the ceiling of the numeric value. */ - ceil(): FunctionExpr { - return new FunctionExpr('ceil', [this]); + ceil(): FunctionExpression { + return new FunctionExpression('ceil', [this]); } /** @@ -990,10 +1033,25 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("price").floor(); * ``` * - * @return A new {@code Expr} representing the floor of the numeric value. + * @return A new {@code Expression} representing the floor of the numeric value. + */ + floor(): FunctionExpression { + return new FunctionExpression('floor', [this]); + } + + /** + * @beta + * Creates an expression that computes the absolute value of a numeric value. + * + * ```typescript + * // Compute the absolute value of the 'price' field. + * field("price").abs(); + * ``` + * + * @return A new {@code Expr} representing the absolute value of the numeric value. */ - floor(): FunctionExpr { - return new FunctionExpr('floor', [this]); + abs(): FunctionExpression { + return new FunctionExpression('abs', [this]); } /** @@ -1005,10 +1063,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("value").exp(); * ``` * - * @return A new {@code Expr} representing the exp of the numeric value. + * @return A new {@code Expression} representing the exp of the numeric value. */ - exp(): FunctionExpr { - return new FunctionExpr('exp', [this]); + exp(): FunctionExpression { + return new FunctionExpression('exp', [this]); } /** @@ -1021,10 +1079,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param subfield The key to access in the map. - * @return A new `Expr` representing the value associated with the given key in the map. + * @return A new `Expression` representing the value associated with the given key in the map. */ - mapGet(subfield: string): FunctionExpr { - return new FunctionExpr('map_get', [this, constant(subfield)]); + mapGet(subfield: string): FunctionExpression { + return new FunctionExpression('map_get', [this, constant(subfield)]); } /** @@ -1065,13 +1123,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Calculate the average age of users - * field("age").avg().as("averageAge"); + * field("age").average().as("averageAge"); * ``` * - * @return A new `AggregateFunction` representing the 'avg' aggregation. + * @return A new `AggregateFunction` representing the 'average' aggregation. */ - avg(): AggregateFunction { - return new AggregateFunction('avg', [this]); + average(): AggregateFunction { + return new AggregateFunction('average', [this]); } /** @@ -1086,7 +1144,7 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * @return A new `AggregateFunction` representing the 'min' aggregation. */ minimum(): AggregateFunction { - return new AggregateFunction('min', [this]); + return new AggregateFunction('minimum', [this]); } /** @@ -1101,7 +1159,7 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * @return A new `AggregateFunction` representing the 'max' aggregation. */ maximum(): AggregateFunction { - return new AggregateFunction('max', [this]); + return new AggregateFunction('maximum', [this]); } /** @@ -1130,14 +1188,17 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * @param second The second expression or literal to compare with. * @param others Optional additional expressions or literals to compare with. - * @return A new {@code Expr} representing the logical max operation. + * @return A new {@code Expression} representing the logical max operation. */ logicalMaximum( - second: Expr | unknown, - ...others: Array - ): FunctionExpr { + second: Expression | unknown, + ...others: Array + ): FunctionExpression { const values = [second, ...others]; - return new FunctionExpr('max', [this, ...values.map(valueToDefaultExpr)]); + return new FunctionExpression('maximum', [ + this, + ...values.map(valueToDefaultExpr), + ]); } /** @@ -1151,14 +1212,17 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * @param second The second expression or literal to compare with. * @param others Optional additional expressions or literals to compare with. - * @return A new {@code Expr} representing the logical min operation. + * @return A new {@code Expression} representing the logical min operation. */ logicalMinimum( - second: Expr | unknown, - ...others: Array - ): FunctionExpr { + second: Expression | unknown, + ...others: Array + ): FunctionExpression { const values = [second, ...others]; - return new FunctionExpr('min', [this, ...values.map(valueToDefaultExpr)]); + return new FunctionExpression('minimum', [ + this, + ...values.map(valueToDefaultExpr), + ]); } /** @@ -1170,10 +1234,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("embedding").vectorLength(); * ``` * - * @return A new {@code Expr} representing the length of the vector. + * @return A new {@code Expression} representing the length of the vector. */ - vectorLength(): FunctionExpr { - return new FunctionExpr('vector_length', [this]); + vectorLength(): FunctionExpression { + return new FunctionExpression('vector_length', [this]); } /** @@ -1185,10 +1249,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("userVector").cosineDistance(field("itemVector")); * ``` * - * @param vectorExpression The other vector (represented as an Expr) to compare against. - * @return A new `Expr` representing the cosine distance between the two vectors. + * @param vectorExpression The other vector (represented as an Expression) to compare against. + * @return A new `Expression` representing the cosine distance between the two vectors. */ - cosineDistance(vectorExpression: Expr): FunctionExpr; + cosineDistance(vectorExpression: Expression): FunctionExpression; /** * @beta * Calculates the Cosine distance between two vectors. @@ -1199,11 +1263,16 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param vector The other vector (as a VectorValue) to compare against. - * @return A new `Expr` representing the Cosine* distance between the two vectors. + * @return A new `Expression` representing the Cosine* distance between the two vectors. */ - cosineDistance(vector: firestore.VectorValue | number[]): FunctionExpr; - cosineDistance(other: Expr | firestore.VectorValue | number[]): FunctionExpr { - return new FunctionExpr('cosine_distance', [this, vectorToExpr(other)]); + cosineDistance(vector: firestore.VectorValue | number[]): FunctionExpression; + cosineDistance( + other: Expression | firestore.VectorValue | number[] + ): FunctionExpression { + return new FunctionExpression('cosine_distance', [ + this, + vectorToExpr(other), + ]); } /** @@ -1216,9 +1285,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param vectorExpression The other vector (as an array of numbers) to calculate with. - * @return A new `Expr` representing the dot product between the two vectors. + * @return A new `Expression` representing the dot product between the two vectors. */ - dotProduct(vectorExpression: Expr): FunctionExpr; + dotProduct(vectorExpression: Expression): FunctionExpression; /** * @beta @@ -1230,11 +1299,13 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param vector The other vector (as an array of numbers) to calculate with. - * @return A new `Expr` representing the dot product between the two vectors. + * @return A new `Expression` representing the dot product between the two vectors. */ - dotProduct(vector: firestore.VectorValue | number[]): FunctionExpr; - dotProduct(other: Expr | firestore.VectorValue | number[]): FunctionExpr { - return new FunctionExpr('dot_product', [this, vectorToExpr(other)]); + dotProduct(vector: firestore.VectorValue | number[]): FunctionExpression; + dotProduct( + other: Expression | firestore.VectorValue | number[] + ): FunctionExpression { + return new FunctionExpression('dot_product', [this, vectorToExpr(other)]); } /** @@ -1247,9 +1318,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param vectorExpression The other vector (as an array of numbers) to calculate with. - * @return A new `Expr` representing the Euclidean distance between the two vectors. + * @return A new `Expression` representing the Euclidean distance between the two vectors. */ - euclideanDistance(vectorExpression: Expr): FunctionExpr; + euclideanDistance(vectorExpression: Expression): FunctionExpression; /** * @beta @@ -1261,13 +1332,18 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param vector The other vector (as a VectorValue) to compare against. - * @return A new `Expr` representing the Euclidean distance between the two vectors. + * @return A new `Expression` representing the Euclidean distance between the two vectors. */ - euclideanDistance(vector: firestore.VectorValue | number[]): FunctionExpr; euclideanDistance( - other: Expr | firestore.VectorValue | number[] - ): FunctionExpr { - return new FunctionExpr('euclidean_distance', [this, vectorToExpr(other)]); + vector: firestore.VectorValue | number[] + ): FunctionExpression; + euclideanDistance( + other: Expression | firestore.VectorValue | number[] + ): FunctionExpression { + return new FunctionExpression('euclidean_distance', [ + this, + vectorToExpr(other), + ]); } /** @@ -1280,10 +1356,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("microseconds").unixMicrosToTimestamp(); * ``` * - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - unixMicrosToTimestamp(): FunctionExpr { - return new FunctionExpr('unix_micros_to_timestamp', [this]); + unixMicrosToTimestamp(): FunctionExpression { + return new FunctionExpression('unix_micros_to_timestamp', [this]); } /** @@ -1295,10 +1371,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("timestamp").timestampToUnixMicros(); * ``` * - * @return A new {@code Expr} representing the number of microseconds since epoch. + * @return A new {@code Expression} representing the number of microseconds since epoch. */ - timestampToUnixMicros(): FunctionExpr { - return new FunctionExpr('timestamp_to_unix_micros', [this]); + timestampToUnixMicros(): FunctionExpression { + return new FunctionExpression('timestamp_to_unix_micros', [this]); } /** @@ -1311,10 +1387,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("milliseconds").unixMillisToTimestamp(); * ``` * - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - unixMillisToTimestamp(): FunctionExpr { - return new FunctionExpr('unix_millis_to_timestamp', [this]); + unixMillisToTimestamp(): FunctionExpression { + return new FunctionExpression('unix_millis_to_timestamp', [this]); } /** @@ -1326,10 +1402,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("timestamp").timestampToUnixMillis(); * ``` * - * @return A new {@code Expr} representing the number of milliseconds since epoch. + * @return A new {@code Expression} representing the number of milliseconds since epoch. */ - timestampToUnixMillis(): FunctionExpr { - return new FunctionExpr('timestamp_to_unix_millis', [this]); + timestampToUnixMillis(): FunctionExpression { + return new FunctionExpression('timestamp_to_unix_millis', [this]); } /** @@ -1342,10 +1418,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("seconds").unixSecondsToTimestamp(); * ``` * - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - unixSecondsToTimestamp(): FunctionExpr { - return new FunctionExpr('unix_seconds_to_timestamp', [this]); + unixSecondsToTimestamp(): FunctionExpression { + return new FunctionExpression('unix_seconds_to_timestamp', [this]); } /** @@ -1357,10 +1433,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("timestamp").timestampToUnixSeconds(); * ``` * - * @return A new {@code Expr} representing the number of seconds since epoch. + * @return A new {@code Expression} representing the number of seconds since epoch. */ - timestampToUnixSeconds(): FunctionExpr { - return new FunctionExpr('timestamp_to_unix_seconds', [this]); + timestampToUnixSeconds(): FunctionExpression { + return new FunctionExpression('timestamp_to_unix_seconds', [this]); } /** @@ -1374,9 +1450,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. * @param amount The expression evaluates to amount of the unit. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ - timestampAdd(unit: Expr, amount: Expr): FunctionExpr; + timestampAdd(unit: Expression, amount: Expression): FunctionExpression; /** * @beta @@ -1389,24 +1465,24 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * @param unit The unit of time to add (e.g., "day", "hour"). * @param amount The amount of time to add. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ timestampAdd( unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number - ): FunctionExpr; + ): FunctionExpression; timestampAdd( unit: - | Expr + | Expression | 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', - amount: Expr | number - ): FunctionExpr { - return new FunctionExpr('timestamp_add', [ + amount: Expression | number + ): FunctionExpression { + return new FunctionExpression('timestamp_add', [ this, valueToDefaultExpr(unit), valueToDefaultExpr(amount), @@ -1419,14 +1495,14 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Subtract some duration determined by field 'unit' and 'amount' from the 'timestamp' field. - * field("timestamp").timestampSub(field("unit"), field("amount")); + * field("timestamp").timestampSubtract(field("unit"), field("amount")); * ``` * * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. * @param amount The expression evaluates to amount of the unit. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ - timestampSub(unit: Expr, amount: Expr): FunctionExpr; + timestampSubtract(unit: Expression, amount: Expression): FunctionExpression; /** * @beta @@ -1434,29 +1510,29 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * ```typescript * // Subtract 1 day from the 'timestamp' field. - * field("timestamp").timestampSub("day", 1); + * field("timestamp").timestampSubtract("day", 1); * ``` * * @param unit The unit of time to subtract (e.g., "day", "hour"). * @param amount The amount of time to subtract. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ - timestampSub( + timestampSubtract( unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number - ): FunctionExpr; - timestampSub( + ): FunctionExpression; + timestampSubtract( unit: - | Expr + | Expression | 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', - amount: Expr | number - ): FunctionExpr { - return new FunctionExpr('timestamp_sub', [ + amount: Expression | number + ): FunctionExpression { + return new FunctionExpression('timestamp_subtract', [ this, valueToDefaultExpr(unit), valueToDefaultExpr(amount), @@ -1472,10 +1548,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("__path__").documentId(); * ``` * - * @return A new {@code Expr} representing the documentId operation. + * @return A new {@code Expression} representing the documentId operation. */ - documentId(): FunctionExpr { - return new FunctionExpr('document_id', [this]); + documentId(): FunctionExpression { + return new FunctionExpression('document_id', [this]); } /** @@ -1486,7 +1562,7 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * @param length Length of the substring. If not provided, the substring will * end at the end of the input. */ - substring(position: number, length?: number): FunctionExpr; + substring(position: number, length?: number): FunctionExpression; /** * @beta @@ -1496,13 +1572,16 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * @param length An expression returning the length of the substring. If not provided the * substring will end at the end of the input. */ - substring(position: Expr, length?: Expr): FunctionExpr; - substring(position: Expr | number, length?: Expr | number): FunctionExpr { + substring(position: Expression, length?: Expression): FunctionExpression; + substring( + position: Expression | number, + length?: Expression | number + ): FunctionExpression { const positionExpr = valueToDefaultExpr(position); if (length === undefined) { - return new FunctionExpr('substr', [this, positionExpr]); + return new FunctionExpression('substring', [this, positionExpr]); } else { - return new FunctionExpr('substr', [ + return new FunctionExpression('substring', [ this, positionExpr, valueToDefaultExpr(length), @@ -1522,9 +1601,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param index The index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @return A new Expression representing the 'arrayGet' operation. */ - arrayGet(index: number): FunctionExpr; + arrayGet(index: number): FunctionExpression; /** * @beta @@ -1538,12 +1617,15 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field('tags').arrayGet(field('favoriteTag')); * ``` * - * @param indexExpr An Expr evaluating to the index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @param indexExpr An Expression evaluating to the index of the element to return. + * @return A new Expression representing the 'arrayGet' operation. */ - arrayGet(indexExpr: Expr): FunctionExpr; - arrayGet(index: Expr | number): FunctionExpr { - return new FunctionExpr('array_get', [this, valueToDefaultExpr(index)]); + arrayGet(indexExpr: Expression): FunctionExpression; + arrayGet(index: Expression | number): FunctionExpression { + return new FunctionExpression('array_get', [ + this, + valueToDefaultExpr(index), + ]); } /** @@ -1555,10 +1637,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("title").arrayContains(1).isError(); * ``` * - * @return A new {@code BooleanExpr} representing the 'isError' check. + * @return A new {@code BooleanExpression} representing the 'isError' check. */ - isError(): BooleanExpr { - return new BooleanExpr('is_error', [this]); + isError(): BooleanExpression { + return new BooleanExpression('is_error', [this]); } /** @@ -1574,9 +1656,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * @param catchExpr The catch expression that will be evaluated and * returned if this expression produces an error. - * @return A new {@code Expr} representing the 'ifError' operation. + * @return A new {@code Expression} representing the 'ifError' operation. */ - ifError(catchExpr: Expr): FunctionExpr; + ifError(catchExpr: Expression): FunctionExpression; /** * @beta @@ -1591,11 +1673,14 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * * @param catchValue The value that will be returned if this expression * produces an error. - * @return A new {@code Expr} representing the 'ifError' operation. + * @return A new {@code Expression} representing the 'ifError' operation. */ - ifError(catchValue: unknown): FunctionExpr; - ifError(catchValue: unknown): FunctionExpr { - return new FunctionExpr('if_error', [this, valueToDefaultExpr(catchValue)]); + ifError(catchValue: unknown): FunctionExpression; + ifError(catchValue: unknown): FunctionExpression { + return new FunctionExpression('if_error', [ + this, + valueToDefaultExpr(catchValue), + ]); } /** @@ -1608,40 +1693,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("value").isAbsent(); * ``` * - * @return A new {@code BooleanExpr} representing the 'isAbsent' check. + * @return A new {@code BooleanExpression} representing the 'isAbsent' check. */ - isAbsent(): BooleanExpr { - return new BooleanExpr('is_absent', [this]); - } - - /** - * @beta - * Creates an expression that checks if tbe result of an expression is not null. - * - * ```typescript - * // Check if the value of the 'name' field is not null - * field("name").isNotNull(); - * ``` - * - * @return A new {@code BooleanExpr} representing the 'isNotNull' check. - */ - isNotNull(): BooleanExpr { - return new BooleanExpr('is_not_null', [this]); - } - - /** - * @beta - * Creates an expression that checks if the results of this expression is NOT 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NOT NaN - * field("value").divide(0).isNotNan(); - * ``` - * - * @return A new {@code Expr} representing the 'isNan' check. - */ - isNotNan(): BooleanExpr { - return new BooleanExpr('is_not_nan', [this]); + isAbsent(): BooleanExpression { + return new BooleanExpression('is_absent', [this]); } /** @@ -1656,7 +1711,7 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * @param key The name of the key to remove from the input map. * @returns A new {@code FirestoreFunction} representing the 'mapRemove' operation. */ - mapRemove(key: string): FunctionExpr; + mapRemove(key: string): FunctionExpression; /** * @beta * Creates an expression that removes a key from the map produced by evaluating this expression. @@ -1669,9 +1724,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * @param keyExpr An expression that produces the name of the key to remove from the input map. * @returns A new {@code FirestoreFunction} representing the 'mapRemove' operation. */ - mapRemove(keyExpr: Expr): FunctionExpr; - mapRemove(stringExpr: Expr | string): FunctionExpr { - return new FunctionExpr('map_remove', [ + mapRemove(keyExpr: Expression): FunctionExpression; + mapRemove(stringExpr: Expression | string): FunctionExpression { + return new FunctionExpression('map_remove', [ this, valueToDefaultExpr(stringExpr), ]); @@ -1684,7 +1739,7 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * // Merges the map in the settings field with, a map literal, and a map in * // that is conditionally returned by another expression - * field('settings').mapMerge({ enabled: true }, cond(field('isAdmin'), { admin: true}, {}) + * field('settings').mapMerge({ enabled: true }, conditional(field('isAdmin'), { admin: true}, {}) * ``` * * @param secondMap A required second map to merge. Represented as a literal or @@ -1695,12 +1750,12 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * @returns A new {@code FirestoreFunction} representing the 'mapMerge' operation. */ mapMerge( - secondMap: Record | Expr, - ...otherMaps: Array | Expr> - ): FunctionExpr { + secondMap: Record | Expression, + ...otherMaps: Array | Expression> + ): FunctionExpression { const secondMapExpr = valueToDefaultExpr(secondMap); const otherMapExprs = otherMaps.map(valueToDefaultExpr); - return new FunctionExpr('map_merge', [ + return new FunctionExpression('map_merge', [ this, secondMapExpr, ...otherMapExprs, @@ -1717,9 +1772,9 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param exponent The expression to raise this expression to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ - pow(exponent: Expr): FunctionExpr; + pow(exponent: Expression): FunctionExpression; /** * @beta @@ -1731,11 +1786,11 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param exponent The constant value to raise this expression to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ - pow(exponent: number): FunctionExpr; - pow(exponent: number | Expr): FunctionExpr { - return new FunctionExpr('pow', [this, valueToDefaultExpr(exponent)]); + pow(exponent: number): FunctionExpression; + pow(exponent: number | Expression): FunctionExpression { + return new FunctionExpression('pow', [this, valueToDefaultExpr(exponent)]); } /** @@ -1747,10 +1802,46 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("price").round(); * ``` * + * @return A new `Expression` representing the rounded value. + */ + round(): FunctionExpression; + /** + * @beta + * Creates an expression that rounds a numeric value to the specified number of decimal places. + * + * ```typescript + * // Round the value of the 'price' field to two decimal places. + * field("price").round(2); + * ``` + * + * @param decimalPlaces A constant specifying the rounding precision in decimal places. + * * @return A new `Expr` representing the rounded value. */ - round(): FunctionExpr { - return new FunctionExpr('round', [this]); + round(decimalPlaces: number): FunctionExpression; + /** + * @beta + * Creates an expression that rounds a numeric value to the specified number of decimal places. + * + * ```typescript + * // Round the value of the 'price' field to two decimal places. + * field("price").round(constant(2)); + * ``` + * + * @param decimalPlaces An expression specifying the rounding precision in decimal places. + * + * @return A new `Expr` representing the rounded value. + */ + round(decimalPlaces: Expression): FunctionExpression; + round(decimalPlaces?: number | Expression): FunctionExpression { + if (decimalPlaces === undefined) { + return new FunctionExpression('round', [this]); + } else { + return new FunctionExpression('round', [ + this, + valueToDefaultExpr(decimalPlaces), + ]); + } } /** @@ -1762,10 +1853,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("__path__").collectionId(); * ``` * - * @return A new {@code Expr} representing the collectionId operation. + * @return A new {@code Expression} representing the collectionId operation. */ - collectionId(): FunctionExpr { - return new FunctionExpr('collection_id', [this]); + collectionId(): FunctionExpression { + return new FunctionExpression('collection_id', [this]); } /** @@ -1780,10 +1871,10 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("cart").length(); * ``` * - * @return A new `Expr` representing the length of the string, array, map, vector, or bytes. + * @return A new `Expression` representing the length of the string, array, map, vector, or bytes. */ - length(): FunctionExpr { - return new FunctionExpr('length', [this]); + length(): FunctionExpression { + return new FunctionExpression('length', [this]); } /** @@ -1795,71 +1886,144 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * field("value").ln(); * ``` * - * @return A new {@code Expr} representing the natural logarithm of the numeric value. + * @return A new {@code Expression} representing the natural logarithm of the numeric value. */ - ln(): FunctionExpr { - return new FunctionExpr('ln', [this]); + ln(): FunctionExpression { + return new FunctionExpression('ln', [this]); } /** * @beta - * Creates an expression that computes the logarithm of this expression to a given base. + * Creates an expression that computes the square root of a numeric value. * * ```typescript - * // Compute the logarithm of the 'value' field with base 10. - * field("value").log(10); + * // Compute the square root of the 'value' field. + * field("value").sqrt(); * ``` * - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @return A new {@code Expression} representing the square root of the numeric value. */ - log(base: number): FunctionExpr; + sqrt(): FunctionExpression { + return new FunctionExpression('sqrt', [this]); + } /** * @beta - * Creates an expression that computes the logarithm of this expression to a given base. + * Creates an expression that reverses a string. * * ```typescript - * // Compute the logarithm of the 'value' field with the base in the 'base' field. - * field("value").log(field("base")); + * // Reverse the value of the 'myString' field. + * field("myString").stringReverse(); * ``` * - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @return A new {@code Expression} representing the reversed string. */ - log(base: Expr): FunctionExpr; - log(base: number | Expr): FunctionExpr { - return new FunctionExpr('log', [this, valueToDefaultExpr(base)]); + stringReverse(): FunctionExpression { + return new FunctionExpression('string_reverse', [this]); } /** * @beta - * Creates an expression that computes the square root of a numeric value. + * Creates an expression that returns the `elseValue` argument if this expression results in an absent value, else + * return the result of the this expression evaluation. * * ```typescript - * // Compute the square root of the 'value' field. - * field("value").sqrt(); + * // Returns the value of the optional field 'optional_field', or returns 'default_value' + * // if the field is absent. + * field("optional_field").ifAbsent("default_value") * ``` * - * @return A new {@code Expr} representing the square root of the numeric value. + * @param elseValue The value that will be returned if this Expression evaluates to an absent value. + * @return A new [Expression] representing the ifAbsent operation. */ - sqrt(): FunctionExpr { - return new FunctionExpr('sqrt', [this]); + ifAbsent(elseValue: unknown): Expression; + + /** + * @beta + * Creates an expression that returns the `elseValue` argument if this expression results in an absent value, else + * return the result of this expression evaluation. + * + * ```typescript + * // Returns the value of the optional field 'optional_field', or if that is + * // absent, then returns the value of the field ` + * field("optional_field").ifAbsent(field('default_field')) + * ``` + * + * @param elseExpression The Expression that will be evaluated if this Expression evaluates to an absent value. + * @return A new [Expression] representing the ifAbsent operation. + */ + ifAbsent(elseExpression: unknown): Expression; + + ifAbsent(elseValueOrExpression: Expression | unknown): Expression { + return new FunctionExpression('if_absent', [ + this, + valueToDefaultExpr(elseValueOrExpression), + ]); } /** * @beta - * Creates an expression that reverses a string. + * Creates an expression that joins the elements of an array into a string. * * ```typescript - * // Reverse the value of the 'myString' field. - * field("myString").strReverse(); + * // Join the elements of the 'tags' field with the delimiter from the 'separator' field. + * field("tags").join(field("separator")) * ``` * - * @return A new {@code Expr} representing the reversed string. + * @param delimiterExpression The expression that evaluates to the delimiter string. + * @return A new Expression representing the join operation. */ - strReverse(): FunctionExpr { - return new FunctionExpr('str_reverse', [this]); + join(delimiterExpression: Expression): Expression; + + /** + * @beta + * Creates an expression that joins the elements of an array field into a string. + * + * ```typescript + * // Join the elements of the 'tags' field with a comma and space. + * field("tags").join(", ") + * ``` + * + * @param delimiter The string to use as a delimiter. + * @return A new Expression representing the join operation. + */ + join(delimiter: string): Expression; + + join(delimeterValueOrExpression: string | Expression): Expression { + return new FunctionExpression('join', [ + this, + valueToDefaultExpr(delimeterValueOrExpression), + ]); + } + + /** + * @beta + * Creates an expression that computes the base-10 logarithm of a numeric value. + * + * ```typescript + * // Compute the base-10 logarithm of the 'value' field. + * field("value").log10(); + * ``` + * + * @return A new {@code Expr} representing the base-10 logarithm of the numeric value. + */ + log10(): FunctionExpression { + return new FunctionExpression('log10', [this]); + } + + /** + * @beta + * Creates an expression that computes the sum of the elements in an array. + * + * ```typescript + * // Compute the sum of the elements in the 'scores' field. + * field("scores").arraySum(); + * ``` + * + * @return A new {@code Expr} representing the sum of the elements in the array. + */ + arraySum(): FunctionExpression { + return new FunctionExpression('sum', [this]); } // TODO(new-expression): Add new expression method definitions above this line @@ -1910,11 +2074,11 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * ``` * * @param name The alias to assign to this expression. - * @return A new {@link AliasedExpr} that wraps this + * @return A new {@link AliasedExpression} that wraps this * expression and associates it with the provided alias. */ - as(name: string): AliasedExpr { - return new AliasedExpr(this, name); + as(name: string): AliasedExpression { + return new AliasedExpression(this, name); } } @@ -1923,7 +2087,7 @@ export abstract class Expr implements firestore.Pipelines.Expr, HasUserData { * A class that represents an aggregate function. */ export class AggregateFunction implements AggregateFunction, HasUserData { - exprType: firestore.Pipelines.ExprType = 'AggregateFunction'; + expressionType: firestore.Pipelines.ExpressionType = 'AggregateFunction'; /** * @beta @@ -1947,7 +2111,7 @@ export class AggregateFunction implements AggregateFunction, HasUserData { constructor( private name: string, - private params: Expr[] + private params: Expression[] ) {} /** @@ -1958,7 +2122,7 @@ export class AggregateFunction implements AggregateFunction, HasUserData { * ```typescript * // Calculate the average price of all items and assign it the alias "averagePrice". * firestore.pipeline().collection("items") - * .aggregate(field("price").avg().as("averagePrice")); + * .aggregate(field("price").average().as("averagePrice")); * ``` * * @param name The alias to assign to this AggregateFunction. @@ -1992,8 +2156,8 @@ export class AggregateFunction implements AggregateFunction, HasUserData { */ export class AliasedAggregate implements AliasedAggregate, HasUserData { constructor( - readonly aggregate: AggregateFunction, - readonly alias: string + readonly _aggregate: AggregateFunction, + readonly _alias: string ) {} /** @@ -2011,7 +2175,7 @@ export class AliasedAggregate implements AliasedAggregate, HasUserData { * @internal */ _validateUserData(ignoreUndefinedProperties: boolean): void { - this.aggregate._validateUserData(ignoreUndefinedProperties); + this._aggregate._validateUserData(ignoreUndefinedProperties); } } @@ -2019,10 +2183,10 @@ export class AliasedAggregate implements AliasedAggregate, HasUserData { * @beta * TODO */ -export class AliasedExpr +export class AliasedExpression implements firestore.Pipelines.Selectable, HasUserData { - exprType: firestore.Pipelines.ExprType = 'AliasedExpr'; + expressionType: firestore.Pipelines.ExpressionType = 'AliasedExpression'; selectable = true as const; /** @@ -2035,8 +2199,8 @@ export class AliasedExpr _createdFromLiteral = false; constructor( - readonly expr: Expr, - readonly alias: string + readonly _expr: Expression, + readonly _alias: string ) {} /** @@ -2045,7 +2209,7 @@ export class AliasedExpr * @internal */ _validateUserData(ignoreUndefinedProperties: boolean): void { - this.expr._validateUserData(ignoreUndefinedProperties); + this._expr._validateUserData(ignoreUndefinedProperties); } } @@ -2053,10 +2217,10 @@ export class AliasedExpr * @beta * @internal */ -class ListOfExprs extends Expr { - exprType: firestore.Pipelines.ExprType = 'ListOfExprs'; +class ListOfExprs extends Expression { + expressionType: firestore.Pipelines.ExpressionType = 'ListOfExprs'; - constructor(private exprs: Expr[]) { + constructor(private exprs: Expression[]) { super(); } @@ -2102,8 +2266,11 @@ class ListOfExprs extends Expr { * const cityField = field("address.city"); * ``` */ -export class Field extends Expr implements firestore.Pipelines.Selectable { - readonly exprType: firestore.Pipelines.ExprType = 'Field'; +export class Field + extends Expression + implements firestore.Pipelines.Selectable +{ + readonly expressionType: firestore.Pipelines.ExpressionType = 'Field'; selectable = true as const; /** @@ -2117,15 +2284,15 @@ export class Field extends Expr implements firestore.Pipelines.Selectable { super(); } - fieldName(): string { + get fieldName(): string { return this.fieldPath.formattedName; } - get alias(): string { - return this.fieldName(); + get _alias(): string { + return this.fieldName; } - get expr(): Expr { + get _expr(): Expression { return this; } @@ -2179,6 +2346,7 @@ export function field(field: string | firestore.FieldPath): Field { /** * @beta + * @internal * Represents a constant value that can be used in a Firestore pipeline expression. * * You can create a `Constant` instance using the static {@link #of} method: @@ -2191,8 +2359,8 @@ export function field(field: string | firestore.FieldPath): Field { * const hello = constant("hello"); * ``` */ -export class Constant extends Expr { - readonly exprType: firestore.Pipelines.ExprType = 'Constant'; +export class Constant extends Expression { + readonly expressionType: firestore.Pipelines.ExpressionType = 'Constant'; private protoValue?: api.IValue; @@ -2247,104 +2415,104 @@ export class Constant extends Expr { /** * @beta - * Creates a `Constant` instance for a number value. + * Creates an 'Expression' instance for a number value. * * @param value The number value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: number): Constant; +export function constant(value: number): Expression; /** * @beta - * Creates a `Constant` instance for a string value. + * Creates an 'Expression' instance for a string value. * * @param value The string value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: string): Constant; +export function constant(value: string): Expression; /** * @beta - * Creates a `Constant` instance for a boolean value. + * Creates an 'Expression' instance for a boolean value. * * @param value The boolean value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: boolean): Constant; +export function constant(value: boolean): BooleanExpression; /** * @beta - * Creates a `Constant` instance for a null value. + * Creates an 'Expression' instance for a null value. * * @param value The null value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: null): Constant; +export function constant(value: null): Expression; /** * @beta - * Creates a `Constant` instance for a GeoPoint value. + * Creates an 'Expression' instance for a GeoPoint value. * * @param value The GeoPoint value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: firestore.GeoPoint): Constant; +export function constant(value: firestore.GeoPoint): Expression; /** * @beta - * Creates a `Constant` instance for a Timestamp value. + * Creates an 'Expression' instance for a Timestamp value. * * @param value The Timestamp value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: firestore.Timestamp): Constant; +export function constant(value: firestore.Timestamp): Expression; /** * @beta - * Creates a `Constant` instance for a Date value. + * Creates an 'Expression' instance for a Date value. * * @param value The Date value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: Date): Constant; +export function constant(value: Date): Expression; /** * @beta - * Creates a `Constant` instance for a Buffer | Uint8Array value. + * Creates an 'Expression' instance for a Buffer | Uint8Array value. * * @param value The Buffer | Uint8Array value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: Buffer | Uint8Array): Constant; +export function constant(value: Buffer | Uint8Array): Expression; /** * @beta - * Creates a `Constant` instance for a DocumentReference value. + * Creates an 'Expression' instance for a DocumentReference value. * * @param value The DocumentReference value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: firestore.DocumentReference): Constant; +export function constant(value: firestore.DocumentReference): Expression; /** * @beta - * Creates a `Constant` instance for a Firestore proto value. + * Creates an 'Expression' instance for a Firestore proto value. * For internal use only. * @private * @internal * @param value The Firestore proto value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: api.IValue): Constant; +export function constant(value: api.IValue): Expression; /** * @beta - * Creates a `Constant` instance for a VectorValue value. + * Creates an 'Expression' instance for a VectorValue value. * * @param value The VectorValue value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ -export function constant(value: firestore.VectorValue): Constant; +export function constant(value: firestore.VectorValue): Expression; /** * @beta @@ -2352,9 +2520,9 @@ export function constant(value: firestore.VectorValue): Constant; * @private * @param value */ -export function constant(value: unknown): Constant; +export function constant(value: unknown): Expression; -export function constant(value: unknown): Constant { +export function constant(value: unknown): Expression { return new Constant(value); } @@ -2364,12 +2532,12 @@ export function constant(value: unknown): Constant { * @internal * @private */ -export class MapValue extends Expr { - constructor(private plainObject: Map) { +export class MapValue extends Expression { + constructor(private plainObject: Map) { super(); } - exprType: firestore.Pipelines.ExprType = 'Constant'; + expressionType: firestore.Pipelines.ExpressionType = 'Constant'; _toProto(serializer: Serializer): api.IValue { return serializer.encodeValue(this.plainObject); @@ -2392,15 +2560,15 @@ export class MapValue extends Expr { * This class defines the base class for Firestore {@link Pipeline} functions, which can be evaluated within pipeline * execution. * - * Typically, you would not use this class or its children directly. Use either the functions like {@link and}, {@link eq}, - * or the methods on {@link Expr} ({@link Expr#eq}, {@link Expr#lt}, etc.) to construct new Function instances. + * Typically, you would not use this class or its children directly. Use either the functions like {@link and}, {@link equal}, + * or the methods on {@link Expression} ({@link Expression#equal}, {@link Expression#lessThan}, etc.) to construct new Function instances. */ -export class FunctionExpr extends Expr { - readonly exprType: firestore.Pipelines.ExprType = 'Function'; +export class FunctionExpression extends Expression { + readonly expressionType: firestore.Pipelines.ExpressionType = 'Function'; constructor( protected name: string, - private params: Expr[] + private params: Expression[] ) { super(); } @@ -2414,7 +2582,7 @@ export class FunctionExpr extends Expr { return { functionValue: { name: this.name, - args: this.params.map(p => cast(p)._toProto(serializer)), + args: this.params.map(p => cast(p)._toProto(serializer)), }, }; } @@ -2436,13 +2604,13 @@ export class FunctionExpr extends Expr { * This class defines the base class for Firestore {@link Pipeline} functions, which can be evaluated within pipeline * execution. * - * Typically, you would not use this class or its children directly. Use either the functions like {@link and}, {@link eq}, - * or the methods on {@link Expr} ({@link Expr#eq}, {@link Expr#lt}, etc.) to construct new Function instances. + * Typically, you would not use this class or its children directly. Use either the functions like {@link and}, {@link equal}, + * or the methods on {@link Expression} ({@link Expression#equal}, {@link Expression#lessThan}, etc.) to construct new Function instances. */ -class MapFunctionExpr extends FunctionExpr { - readonly exprType: firestore.Pipelines.ExprType = 'Function'; +class MapFunctionExpr extends FunctionExpression { + readonly expressionType: firestore.Pipelines.ExpressionType = 'Function'; - constructor(private map: Record) { + constructor(private map: Record) { super('map', []); } @@ -2488,13 +2656,13 @@ class MapFunctionExpr extends FunctionExpr { * This class defines the base class for Firestore {@link Pipeline} functions, which can be evaluated within pipeline * execution. * - * Typically, you would not use this class or its children directly. Use either the functions like {@link and}, {@link eq}, - * or the methods on {@link Expr} ({@link Expr#eq}, {@link Expr#lt}, etc.) to construct new Function instances. + * Typically, you would not use this class or its children directly. Use either the functions like {@link and}, {@link equal}, + * or the methods on {@link Expression} ({@link Expression#equal}, {@link Expression#lessThan}, etc.) to construct new Function instances. */ -class ArrayFunctionExpr extends FunctionExpr { - readonly exprType: firestore.Pipelines.ExprType = 'Function'; +class ArrayFunctionExpr extends FunctionExpression { + readonly expressionType: firestore.Pipelines.ExpressionType = 'Function'; - constructor(private values: Array) { + constructor(private values: Array) { super('array', []); } @@ -2535,9 +2703,9 @@ class ArrayFunctionExpr extends FunctionExpr { * This expression type is useful for filter conditions. * */ -export class BooleanExpr - extends FunctionExpr - implements firestore.Pipelines.BooleanExpr +export class BooleanExpression + extends FunctionExpression + implements firestore.Pipelines.BooleanExpression { returnType: 'boolean' = 'boolean' as const; @@ -2548,7 +2716,7 @@ export class BooleanExpr * * ```typescript * // Find the count of documents with a score greater than 90 - * field("score").gt(90).countIf().as("highestScore"); + * field("score").greaterThan(90).countIf().as("highestScore"); * ``` * * @return A new `AggregateFunction` representing the 'countIf' aggregation. @@ -2566,10 +2734,49 @@ export class BooleanExpr * field("tags").arrayContains("completed").not(); * ``` * - * @return A new {@code Expr} representing the negated filter condition. + * @return A new {@code Expression} representing the negated filter condition. + */ + not(): BooleanExpression { + return new BooleanExpression('not', [this]); + } + + /** + * @beta + * Creates a conditional expression that evaluates to the 'then' expression + * if `this` expression evaluates to `true`, + * or evaluates to the 'else' expression if `this` expressions evaluates `false`. + * + * ```typescript + * // If 'age' is greater than 18, return "Adult"; otherwise, return "Minor". + * field("age").greaterThanOrEqual(18).conditional(constant("Adult"), constant("Minor")); + * ``` + * + * @param thenExpr The expression to evaluate if the condition is true. + * @param elseExpr The expression to evaluate if the condition is false. + * @return A new {@code Expr} representing the conditional expression. + */ + conditional(thenExpr: Expression, elseExpr: Expression): FunctionExpression { + return new FunctionExpression('conditional', [this, thenExpr, elseExpr]); + } + + /** + * @beta + * + * Creates an expression that returns the `catch` argument if there is an + * error, else return the result of this expression. + * + * ```typescript + * // Create an expression that protects against a divide by zero error + * // but always returns a boolean expression. + * constant(50).divide('length').gt(1).ifError(constant(false)); + * ``` + * + * @param catchValue The value that will be returned if this expression + * produces an error. + * @return A new {@code Expr} representing the 'ifError' operation. */ - not(): BooleanExpr { - return new BooleanExpr('not', [this]); + ifError(catchValue: BooleanExpression): BooleanExpression { + return new BooleanExpression('if_error', [this, catchValue]); } } @@ -2580,25 +2787,14 @@ export class BooleanExpr * * ```typescript * // Count the number of documents where 'is_active' field equals true - * countIf(field("is_active").eq(true)).as("numActiveDocuments"); + * countIf(field("is_active").equal(true)).as("numActiveDocuments"); * ``` * * @param booleanExpr - The boolean expression to evaluate on each input. * @returns A new `AggregateFunction` representing the 'countIf' aggregation. */ -export function countIf(booleanExpr: BooleanExpr): AggregateFunction { - return new AggregateFunction('count_if', [cast(booleanExpr)]); -} - -/** - * @beta - * Creates an expression that return a pseudo-random value of type double in the - * range of [0, 1), inclusive of 0 and exclusive of 1. - * - * @returns A new `Expr` representing the 'rand' function. - */ -export function rand(): FunctionExpr { - return new FunctionExpr('rand', []); +export function countIf(booleanExpr: BooleanExpression): AggregateFunction { + return new AggregateFunction('count_if', [cast(booleanExpr)]); } /** @@ -2614,9 +2810,9 @@ export function rand(): FunctionExpr { * * @param arrayField The name of the array field. * @param index The index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @return A new Expression representing the 'arrayGet' operation. */ -export function arrayGet(arrayField: string, index: number): FunctionExpr; +export function arrayGet(arrayField: string, index: number): FunctionExpression; /** * @beta @@ -2631,10 +2827,13 @@ export function arrayGet(arrayField: string, index: number): FunctionExpr; * ``` * * @param arrayField The name of the array field. - * @param indexExpr An Expr evaluating to the index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @param indexExpr An Expression evaluating to the index of the element to return. + * @return A new Expression representing the 'arrayGet' operation. */ -export function arrayGet(arrayField: string, indexExpr: Expr): FunctionExpr; +export function arrayGet( + arrayField: string, + indexExpr: Expression +): FunctionExpression; /** * @beta @@ -2647,11 +2846,14 @@ export function arrayGet(arrayField: string, indexExpr: Expr): FunctionExpr; * arrayGet(field('tags'), 1); * ``` * - * @param arrayExpression An Expr evaluating to an array. + * @param arrayExpression An Expression evaluating to an array. * @param index The index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @return A new Expression representing the 'arrayGet' operation. */ -export function arrayGet(arrayExpression: Expr, index: number): FunctionExpr; +export function arrayGet( + arrayExpression: Expression, + index: number +): FunctionExpression; /** * @beta @@ -2665,15 +2867,18 @@ export function arrayGet(arrayExpression: Expr, index: number): FunctionExpr; * arrayGet(field('tags'), field('favoriteTag')); * ``` * - * @param arrayExpression An Expr evaluating to an array. - * @param indexExpr An Expr evaluating to the index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @param arrayExpression An Expression evaluating to an array. + * @param indexExpr An Expression evaluating to the index of the element to return. + * @return A new Expression representing the 'arrayGet' operation. */ -export function arrayGet(arrayExpression: Expr, indexExpr: Expr): FunctionExpr; export function arrayGet( - array: Expr | string, - index: Expr | number -): FunctionExpr { + arrayExpression: Expression, + indexExpr: Expression +): FunctionExpression; +export function arrayGet( + array: Expression | string, + index: Expression | number +): FunctionExpression { return fieldOrExpression(array).arrayGet(valueToDefaultExpr(index)); } @@ -2687,13 +2892,37 @@ export function arrayGet( * ``` * * @param value The expression to check. - * @return A new {@code Expr} representing the 'isError' check. + * @return A new {@code Expression} representing the 'isError' check. */ -export function isError(value: Expr): BooleanExpr { - const expr: Expr = cast(value); +export function isError(value: Expression): BooleanExpression { + const expr: Expression = cast(value); return expr.isError(); } +/** + * @beta + * + * Creates an expression that returns the `catch` argument if there is an + * error, else return the result of the `try` argument evaluation. + * + * This overload is useful when a BooleanExpression is required. + * + * ```typescript + * // Create an expression that protects against a divide by zero error + * // but always returns a boolean expression. + * ifError(constant(50).divide('length').gt(1), constant(false)); + * ``` + * + * @param tryExpr The try expression. + * @param catchExpr The catch expression that will be evaluated and + * returned if the tryExpr produces an error. + * @return A new {@code Expr} representing the 'ifError' operation. + */ +export function ifError( + tryExpr: BooleanExpression, + catchExpr: BooleanExpression +): BooleanExpression; + /** * @beta * Creates an expression that returns the `catch` argument if there is an @@ -2708,9 +2937,12 @@ export function isError(value: Expr): BooleanExpr { * @param tryExpr The try expression. * @param catchExpr The catch expression that will be evaluated and * returned if the tryExpr produces an error. - * @return A new {@code Expr} representing the 'ifError' operation. + * @return A new {@code Expression} representing the 'ifError' operation. */ -export function ifError(tryExpr: Expr, catchExpr: Expr): FunctionExpr; +export function ifError( + tryExpr: Expression, + catchExpr: Expression +): FunctionExpression; /** * @beta @@ -2726,12 +2958,24 @@ export function ifError(tryExpr: Expr, catchExpr: Expr): FunctionExpr; * @param tryExpr The try expression. * @param catchValue The value that will be returned if the tryExpr produces an * error. - * @return A new {@code Expr} representing the 'ifError' operation. - */ -export function ifError(tryExpr: Expr, catchValue: unknown): FunctionExpr; -export function ifError(tryExpr: Expr, catchValue: unknown): FunctionExpr { - const expr: Expr = cast(tryExpr); - return expr.ifError(valueToDefaultExpr(catchValue)); + * @return A new {@code Expression} representing the 'ifError' operation. + */ +export function ifError( + tryExpr: Expression, + catchValue: unknown +): FunctionExpression; +export function ifError( + tryExpr: Expression, + catchValue: unknown +): FunctionExpression { + if ( + tryExpr instanceof BooleanExpression && + catchValue instanceof BooleanExpression + ) { + return tryExpr.ifError(catchValue); + } else { + return tryExpr.ifError(valueToDefaultExpr(catchValue)); + } } /** @@ -2745,9 +2989,9 @@ export function ifError(tryExpr: Expr, catchValue: unknown): FunctionExpr { * ``` * * @param value The expression to check. - * @return A new {@code Expr} representing the 'isAbsent' check. + * @return A new {@code Expression} representing the 'isAbsent' check. */ -export function isAbsent(value: Expr): BooleanExpr; +export function isAbsent(value: Expression): BooleanExpression; /** * @beta @@ -2760,106 +3004,13 @@ export function isAbsent(value: Expr): BooleanExpr; * ``` * * @param field The field to check. - * @return A new {@code Expr} representing the 'isAbsent' check. + * @return A new {@code Expression} representing the 'isAbsent' check. */ -export function isAbsent(field: string): BooleanExpr; -export function isAbsent(value: Expr | string): BooleanExpr { +export function isAbsent(field: string): BooleanExpression; +export function isAbsent(value: Expression | string): BooleanExpression { return fieldOrExpression(value).isAbsent(); } -/** - * @beta - * Creates an expression that checks if an expression evaluates to 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NaN - * isNull(field("value").divide(0)); - * ``` - * - * @param value The expression to check. - * @return A new {@code Expr} representing the 'isNull' check. - */ -export function isNull(value: Expr): BooleanExpr; - -/** - * @beta - * Creates an expression that checks if a field's value evaluates to 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NaN - * isNull("value"); - * ``` - * - * @param value The name of the field to check. - * @return A new {@code Expr} representing the 'isNull' check. - */ -export function isNull(value: string): BooleanExpr; -export function isNull(value: Expr | string): BooleanExpr { - return fieldOrExpression(value).isNull(); -} - -/** - * @beta - * Creates an expression that checks if tbe result of an expression is not null. - * - * ```typescript - * // Check if the value of the 'name' field is not null - * isNotNull(field("name")); - * ``` - * - * @param value The expression to check. - * @return A new {@code Expr} representing the 'isNotNull' check. - */ -export function isNotNull(value: Expr): BooleanExpr; - -/** - * @beta - * Creates an expression that checks if tbe value of a field is not null. - * - * ```typescript - * // Check if the value of the 'name' field is not null - * isNotNull("name"); - * ``` - * - * @param value The name of the field to check. - * @return A new {@code Expr} representing the 'isNotNull' check. - */ -export function isNotNull(value: string): BooleanExpr; -export function isNotNull(value: Expr | string): BooleanExpr { - return fieldOrExpression(value).isNotNull(); -} - -/** - * @beta - * Creates an expression that checks if the results of this expression is NOT 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NOT NaN - * isNotNaN(field("value").divide(0)); - * ``` - * - * @param value The expression to check. - * @return A new {@code Expr} representing the 'isNotNaN' check. - */ -export function isNotNan(value: Expr): BooleanExpr; - -/** - * @beta - * Creates an expression that checks if the results of this expression is NOT 'NaN' (Not a Number). - * - * ```typescript - * // Check if the value of a field is NOT NaN - * isNotNaN("value"); - * ``` - * - * @param value The name of the field to check. - * @return A new {@code Expr} representing the 'isNotNaN' check. - */ -export function isNotNan(value: string): BooleanExpr; -export function isNotNan(value: Expr | string): BooleanExpr { - return fieldOrExpression(value).isNotNan(); -} - /** * @beta * Creates an expression that removes a key from the map at the specified field name. @@ -2872,7 +3023,7 @@ export function isNotNan(value: Expr | string): BooleanExpr { * @param mapField The name of a field containing a map value. * @param key The name of the key to remove from the input map. */ -export function mapRemove(mapField: string, key: string): FunctionExpr; +export function mapRemove(mapField: string, key: string): FunctionExpression; /** * @beta * Creates an expression that removes a key from the map produced by evaluating an expression. @@ -2885,7 +3036,7 @@ export function mapRemove(mapField: string, key: string): FunctionExpr; * @param mapExpr An expression return a map value. * @param key The name of the key to remove from the input map. */ -export function mapRemove(mapExpr: Expr, key: string): FunctionExpr; +export function mapRemove(mapExpr: Expression, key: string): FunctionExpression; /** * @beta * Creates an expression that removes a key from the map at the specified field name. @@ -2898,7 +3049,10 @@ export function mapRemove(mapExpr: Expr, key: string): FunctionExpr; * @param mapField The name of a field containing a map value. * @param keyExpr An expression that produces the name of the key to remove from the input map. */ -export function mapRemove(mapField: string, keyExpr: Expr): FunctionExpr; +export function mapRemove( + mapField: string, + keyExpr: Expression +): FunctionExpression; /** * @beta * Creates an expression that removes a key from the map produced by evaluating an expression. @@ -2911,12 +3065,15 @@ export function mapRemove(mapField: string, keyExpr: Expr): FunctionExpr; * @param mapExpr An expression return a map value. * @param keyExpr An expression that produces the name of the key to remove from the input map. */ -export function mapRemove(mapExpr: Expr, keyExpr: Expr): FunctionExpr; +export function mapRemove( + mapExpr: Expression, + keyExpr: Expression +): FunctionExpression; export function mapRemove( - mapExpr: Expr | string, - stringExpr: Expr | string -): FunctionExpr { + mapExpr: Expression | string, + stringExpr: Expression | string +): FunctionExpression { return fieldOrExpression(mapExpr).mapRemove(valueToDefaultExpr(stringExpr)); } @@ -2927,7 +3084,7 @@ export function mapRemove( * ``` * // Merges the map in the settings field with, a map literal, and a map in * // that is conditionally returned by another expression - * mapMerge('settings', { enabled: true }, cond(field('isAdmin'), { admin: true}, {}) + * mapMerge('settings', { enabled: true }, conditional(field('isAdmin'), { admin: true}, {}) * ``` * * @param mapField Name of a field containing a map value that will be merged. @@ -2938,9 +3095,9 @@ export function mapRemove( */ export function mapMerge( mapField: string, - secondMap: Record | Expr, - ...otherMaps: Array | Expr> -): FunctionExpr; + secondMap: Record | Expression, + ...otherMaps: Array | Expression> +): FunctionExpression; /** * @beta @@ -2949,7 +3106,7 @@ export function mapMerge( * ``` * // Merges the map in the settings field with, a map literal, and a map in * // that is conditionally returned by another expression - * mapMerge(field('settings'), { enabled: true }, cond(field('isAdmin'), { admin: true}, {}) + * mapMerge(field('settings'), { enabled: true }, conditional(field('isAdmin'), { admin: true}, {}) * ``` * * @param firstMap An expression or literal map value that will be merged. @@ -2959,16 +3116,16 @@ export function mapMerge( * as a literal or an expression that returns a map. */ export function mapMerge( - firstMap: Record | Expr, - secondMap: Record | Expr, - ...otherMaps: Array | Expr> -): FunctionExpr; + firstMap: Record | Expression, + secondMap: Record | Expression, + ...otherMaps: Array | Expression> +): FunctionExpression; export function mapMerge( - firstMap: string | Record | Expr, - secondMap: Record | Expr, - ...otherMaps: Array | Expr> -): FunctionExpr { + firstMap: string | Record | Expression, + secondMap: Record | Expression, + ...otherMaps: Array | Expression> +): FunctionExpression { const secondMapExpr = valueToDefaultExpr(secondMap); const otherMapExprs = otherMaps.map(valueToDefaultExpr); return fieldOrExpression(firstMap).mapMerge(secondMapExpr, ...otherMapExprs); @@ -2976,16 +3133,36 @@ export function mapMerge( /** * @beta + * * Creates an expression that returns the document ID from a path. * * ```typescript * // Get the document ID from a path. - * documentId(field("__path__")); + * documentId(myDocumentReference); * ``` * * @return A new {@code Expr} representing the documentId operation. */ -export function documentId(documentPathExpr: Expr): FunctionExpr { +export function documentId( + documentPath: string | firestore.DocumentReference +): FunctionExpression; + +/** + * @beta + * Creates an expression that returns the document ID from a path. + * + * ```typescript + * // Get the document ID from a path. + * documentId(field("__path__")); + * ``` + * + * @return A new {@code Expression} representing the documentId operation. + */ +export function documentId(documentPathExpr: Expression): FunctionExpression; +export function documentId( + documentPath: Expression | string | firestore.DocumentReference +): FunctionExpression { + const documentPathExpr = valueToDefaultExpr(documentPath); return documentPathExpr.documentId(); } @@ -3001,7 +3178,7 @@ export function substring( field: string, position: number, length?: number -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -3012,10 +3189,10 @@ export function substring( * @param length Length of the substring. */ export function substring( - input: Expr, + input: Expression, position: number, length?: number -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -3027,9 +3204,9 @@ export function substring( */ export function substring( field: string, - position: Expr, - length?: Expr -): FunctionExpr; + position: Expression, + length?: Expression +): FunctionExpression; /** * @beta @@ -3040,16 +3217,16 @@ export function substring( * @param length An expression that returns the length of the substring. */ export function substring( - input: Expr, - position: Expr, - length?: Expr -): FunctionExpr; + input: Expression, + position: Expression, + length?: Expression +): FunctionExpression; export function substring( - field: Expr | string, - position: Expr | number, - length?: Expr | number -): FunctionExpr { + field: Expression | string, + position: Expression | number, + length?: Expression | number +): FunctionExpression { const fieldExpr = fieldOrExpression(field); const positionExpr = valueToDefaultExpr(position); const lengthExpr = @@ -3068,9 +3245,12 @@ export function substring( * * @param first The first expression to add. * @param second The second expression or literal to add. - * @return A new {@code Expr} representing the addition operation. + * @return A new {@code Expression} representing the addition operation. */ -export function add(first: Expr, second: Expr | unknown): FunctionExpr; +export function add( + first: Expression, + second: Expression | unknown +): FunctionExpression; /** * @beta @@ -3083,14 +3263,17 @@ export function add(first: Expr, second: Expr | unknown): FunctionExpr; * * @param fieldName The name of the field containing the value to add. * @param second The second expression or literal to add. - * @return A new {@code Expr} representing the addition operation. + * @return A new {@code Expression} representing the addition operation. */ -export function add(fieldName: string, second: Expr | unknown): FunctionExpr; +export function add( + fieldName: string, + second: Expression | unknown +): FunctionExpression; export function add( - first: Expr | string, - second: Expr | unknown -): FunctionExpr { + first: Expression | string, + second: Expression | unknown +): FunctionExpression { return fieldOrExpression(first).add(valueToDefaultExpr(second)); } @@ -3105,9 +3288,12 @@ export function add( * * @param minuend The expression to subtract from. * @param subtrahend The expression to subtract. - * @return A new {@code Expr} representing the subtraction operation. + * @return A new {@code Expression} representing the subtraction operation. */ -export function subtract(minuend: Expr, subtrahend: Expr): FunctionExpr; +export function subtract( + minuend: Expression, + subtrahend: Expression +): FunctionExpression; /** * @beta @@ -3120,9 +3306,12 @@ export function subtract(minuend: Expr, subtrahend: Expr): FunctionExpr; * * @param minuend The expression to subtract from. * @param subtrahend The constant value to subtract. - * @return A new {@code Expr} representing the subtraction operation. + * @return A new {@code Expression} representing the subtraction operation. */ -export function subtract(minuend: Expr, subtrahend: unknown): FunctionExpr; +export function subtract( + minuend: Expression, + subtrahend: unknown +): FunctionExpression; /** * @beta @@ -3135,12 +3324,12 @@ export function subtract(minuend: Expr, subtrahend: unknown): FunctionExpr; * * @param minuendFieldName The field name to subtract from. * @param subtrahend The expression to subtract. - * @return A new {@code Expr} representing the subtraction operation. + * @return A new {@code Expression} representing the subtraction operation. */ export function subtract( minuendFieldName: string, - subtrahend: Expr -): FunctionExpr; + subtrahend: Expression +): FunctionExpression; /** * @beta @@ -3153,16 +3342,16 @@ export function subtract( * * @param minuendFieldName The field name to subtract from. * @param subtrahend The constant value to subtract. - * @return A new {@code Expr} representing the subtraction operation. + * @return A new {@code Expression} representing the subtraction operation. */ export function subtract( minuendFieldName: string, subtrahend: unknown -): FunctionExpr; +): FunctionExpression; export function subtract( - left: Expr | string, - right: Expr | unknown -): FunctionExpr { + left: Expression | string, + right: Expression | unknown +): FunctionExpression { const normalizedLeft = fieldOrExpression(left); const normalizedRight = valueToDefaultExpr(right); return normalizedLeft.subtract(normalizedRight); @@ -3179,9 +3368,12 @@ export function subtract( * * @param first The first expression to multiply. * @param second The second expression or literal to multiply. - * @return A new {@code Expr} representing the multiplication operation. + * @return A new {@code Expression} representing the multiplication operation. */ -export function multiply(first: Expr, second: Expr | unknown): FunctionExpr; +export function multiply( + first: Expression, + second: Expression | unknown +): FunctionExpression; /** * @beta @@ -3194,17 +3386,17 @@ export function multiply(first: Expr, second: Expr | unknown): FunctionExpr; * * @param fieldName The name of the field containing the value to multiply. * @param second The second expression or literal to multiply. - * @return A new {@code Expr} representing the multiplication operation. + * @return A new {@code Expression} representing the multiplication operation. */ export function multiply( fieldName: string, - second: Expr | unknown -): FunctionExpr; + second: Expression | unknown +): FunctionExpression; export function multiply( - first: Expr | string, - second: Expr | unknown -): FunctionExpr { + first: Expression | string, + second: Expression | unknown +): FunctionExpression { return fieldOrExpression(first).multiply(valueToDefaultExpr(second)); } @@ -3219,9 +3411,12 @@ export function multiply( * * @param dividend The expression to be divided. * @param divisort The expression to divide by. - * @return A new {@code Expr} representing the division operation. + * @return A new {@code Expression} representing the division operation. */ -export function divide(dividend: Expr, divisort: Expr): FunctionExpr; +export function divide( + dividend: Expression, + divisort: Expression +): FunctionExpression; /** * @beta @@ -3234,9 +3429,12 @@ export function divide(dividend: Expr, divisort: Expr): FunctionExpr; * * @param dividend The expression to be divided. * @param divisor The constant value to divide by. - * @return A new {@code Expr} representing the division operation. + * @return A new {@code Expression} representing the division operation. */ -export function divide(dividend: Expr, divisor: unknown): FunctionExpr; +export function divide( + dividend: Expression, + divisor: unknown +): FunctionExpression; /** * @beta @@ -3249,9 +3447,12 @@ export function divide(dividend: Expr, divisor: unknown): FunctionExpr; * * @param dividend The field name to be divided. * @param divisor The expression to divide by. - * @return A new {@code Expr} representing the division operation. + * @return A new {@code Expression} representing the division operation. */ -export function divide(dividend: string, divisor: Expr): FunctionExpr; +export function divide( + dividend: string, + divisor: Expression +): FunctionExpression; /** * @beta @@ -3264,13 +3465,13 @@ export function divide(dividend: string, divisor: Expr): FunctionExpr; * * @param dividend The field name to be divided. * @param divisor The constant value to divide by. - * @return A new {@code Expr} representing the division operation. + * @return A new {@code Expression} representing the division operation. */ -export function divide(dividend: string, divisor: unknown): FunctionExpr; +export function divide(dividend: string, divisor: unknown): FunctionExpression; export function divide( - dividend: Expr | string, - divisor: Expr | unknown -): FunctionExpr { + dividend: Expression | string, + divisor: Expression | unknown +): FunctionExpression { const normalizedLeft = fieldOrExpression(dividend); const normalizedRight = valueToDefaultExpr(divisor); return normalizedLeft.divide(normalizedRight); @@ -3287,9 +3488,9 @@ export function divide( * * @param left The dividend expression. * @param right The divisor expression. - * @return A new {@code Expr} representing the modulo operation. + * @return A new {@code Expression} representing the modulo operation. */ -export function mod(left: Expr, right: Expr): FunctionExpr; +export function mod(left: Expression, right: Expression): FunctionExpression; /** * @beta @@ -3302,9 +3503,9 @@ export function mod(left: Expr, right: Expr): FunctionExpr; * * @param expression The dividend expression. * @param value The divisor constant. - * @return A new {@code Expr} representing the modulo operation. + * @return A new {@code Expression} representing the modulo operation. */ -export function mod(expression: Expr, value: unknown): FunctionExpr; +export function mod(expression: Expression, value: unknown): FunctionExpression; /** * @beta @@ -3317,9 +3518,12 @@ export function mod(expression: Expr, value: unknown): FunctionExpr; * * @param fieldName The dividend field name. * @param expression The divisor expression. - * @return A new {@code Expr} representing the modulo operation. + * @return A new {@code Expression} representing the modulo operation. */ -export function mod(fieldName: string, expression: Expr): FunctionExpr; +export function mod( + fieldName: string, + expression: Expression +): FunctionExpression; /** * @beta @@ -3332,10 +3536,13 @@ export function mod(fieldName: string, expression: Expr): FunctionExpr; * * @param fieldName The dividend field name. * @param value The divisor constant. - * @return A new {@code Expr} representing the modulo operation. + * @return A new {@code Expression} representing the modulo operation. */ -export function mod(fieldName: string, value: unknown): FunctionExpr; -export function mod(left: Expr | string, right: Expr | unknown): FunctionExpr { +export function mod(fieldName: string, value: unknown): FunctionExpression; +export function mod( + left: Expression | string, + right: Expression | unknown +): FunctionExpression { const normalizedLeft = fieldOrExpression(left); const normalizedRight = valueToDefaultExpr(right); return normalizedLeft.mod(normalizedRight); @@ -3351,10 +3558,10 @@ export function mod(left: Expr | string, right: Expr | unknown): FunctionExpr { * ``` * * @param elements The input map to evaluate in the expression. - * @return A new {@code Expr} representing the map function. + * @return A new {@code Expression} representing the map function. */ -export function map(elements: Record): FunctionExpr { - const result: Record = {}; +export function map(elements: Record): FunctionExpression { + const result: Record = {}; for (const key in elements) { if (Object.prototype.hasOwnProperty.call(elements, key)) { @@ -3380,7 +3587,7 @@ export function map(elements: Record): FunctionExpr { * @param plainObject */ export function _mapValue(plainObject: Record): MapValue { - const result: Map = new Map(); + const result: Map = new Map(); for (const key in plainObject) { if (Object.prototype.hasOwnProperty.call(plainObject, key)) { const value = plainObject[key]; @@ -3400,9 +3607,9 @@ export function _mapValue(plainObject: Record): MapValue { * ``` * * @param elements The input array to evaluate in the expression. - * @return A new {@code Expr} representing the array function. + * @return A new {@code Expression} representing the array function. */ -export function array(elements: unknown[]): FunctionExpr { +export function array(elements: unknown[]): FunctionExpression { return new ArrayFunctionExpr( elements.map(element => { return element !== undefined ? valueToDefaultExpr(element) : undefined; @@ -3416,14 +3623,14 @@ export function array(elements: unknown[]): FunctionExpr { * * ```typescript * // Check if the 'age' field is equal to an expression - * eq(field("age"), field("minAge").add(10)); + * equal(field("age"), field("minAge").add(10)); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the equality comparison. + * @return A new `Expression` representing the equality comparison. */ -export function eq(left: Expr, right: Expr): BooleanExpr; +export function equal(left: Expression, right: Expression): BooleanExpression; /** * @beta @@ -3431,14 +3638,17 @@ export function eq(left: Expr, right: Expr): BooleanExpr; * * ```typescript * // Check if the 'age' field is equal to 21 - * eq(field("age"), 21); + * equal(field("age"), 21); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the equality comparison. + * @return A new `Expression` representing the equality comparison. */ -export function eq(expression: Expr, value: unknown): BooleanExpr; +export function equal( + expression: Expression, + value: unknown +): BooleanExpression; /** * @beta @@ -3446,14 +3656,17 @@ export function eq(expression: Expr, value: unknown): BooleanExpr; * * ```typescript * // Check if the 'age' field is equal to the 'limit' field - * eq("age", field("limit")); + * equal("age", field("limit")); * ``` * * @param fieldName The field name to compare. * @param expression The expression to compare to. - * @return A new `Expr` representing the equality comparison. + * @return A new `Expression` representing the equality comparison. */ -export function eq(fieldName: string, expression: Expr): BooleanExpr; +export function equal( + fieldName: string, + expression: Expression +): BooleanExpression; /** * @beta @@ -3461,18 +3674,21 @@ export function eq(fieldName: string, expression: Expr): BooleanExpr; * * ```typescript * // Check if the 'city' field is equal to string constant "London" - * eq("city", "London"); + * equal("city", "London"); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the equality comparison. + * @return A new `Expression` representing the equality comparison. */ -export function eq(fieldName: string, value: unknown): BooleanExpr; -export function eq(left: Expr | string, right: unknown): BooleanExpr { +export function equal(fieldName: string, value: unknown): BooleanExpression; +export function equal( + left: Expression | string, + right: unknown +): BooleanExpression { const leftExpr = fieldOrExpression(left); const rightExpr = valueToDefaultExpr(right); - return leftExpr.eq(rightExpr); + return leftExpr.equal(rightExpr); } /** @@ -3481,14 +3697,17 @@ export function eq(left: Expr | string, right: unknown): BooleanExpr { * * ```typescript * // Check if the 'status' field is not equal to field 'finalState' - * neq(field("status"), field("finalState")); + * notEqual(field("status"), field("finalState")); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ -export function neq(left: Expr, right: Expr): BooleanExpr; +export function notEqual( + left: Expression, + right: Expression +): BooleanExpression; /** * @beta @@ -3496,14 +3715,17 @@ export function neq(left: Expr, right: Expr): BooleanExpr; * * ```typescript * // Check if the 'status' field is not equal to "completed" - * neq(field("status"), "completed"); + * notEqual(field("status"), "completed"); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ -export function neq(expression: Expr, value: unknown): BooleanExpr; +export function notEqual( + expression: Expression, + value: unknown +): BooleanExpression; /** * @beta @@ -3511,14 +3733,17 @@ export function neq(expression: Expr, value: unknown): BooleanExpr; * * ```typescript * // Check if the 'status' field is not equal to the value of 'expectedStatus' - * neq("status", field("expectedStatus")); + * notEqual("status", field("expectedStatus")); * ``` * * @param fieldName The field name to compare. * @param expression The expression to compare to. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ -export function neq(fieldName: string, expression: Expr): BooleanExpr; +export function notEqual( + fieldName: string, + expression: Expression +): BooleanExpression; /** * @beta @@ -3526,18 +3751,21 @@ export function neq(fieldName: string, expression: Expr): BooleanExpr; * * ```typescript * // Check if the 'country' field is not equal to "USA" - * neq("country", "USA"); + * notEqual("country", "USA"); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ -export function neq(fieldName: string, value: unknown): BooleanExpr; -export function neq(left: Expr | string, right: unknown): BooleanExpr { +export function notEqual(fieldName: string, value: unknown): BooleanExpression; +export function notEqual( + left: Expression | string, + right: unknown +): BooleanExpression { const leftExpr = fieldOrExpression(left); const rightExpr = valueToDefaultExpr(right); - return leftExpr.neq(rightExpr); + return leftExpr.notEqual(rightExpr); } /** @@ -3546,14 +3774,17 @@ export function neq(left: Expr | string, right: unknown): BooleanExpr { * * ```typescript * // Check if the 'age' field is less than 30 - * lt(field("age"), field("limit")); + * lessThan(field("age"), field("limit")); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ -export function lt(left: Expr, right: Expr): BooleanExpr; +export function lessThan( + left: Expression, + right: Expression +): BooleanExpression; /** * @beta @@ -3561,14 +3792,17 @@ export function lt(left: Expr, right: Expr): BooleanExpr; * * ```typescript * // Check if the 'age' field is less than 30 - * lt(field("age"), 30); + * lessThan(field("age"), 30); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ -export function lt(expression: Expr, value: unknown): BooleanExpr; +export function lessThan( + expression: Expression, + value: unknown +): BooleanExpression; /** * @beta @@ -3576,14 +3810,17 @@ export function lt(expression: Expr, value: unknown): BooleanExpr; * * ```typescript * // Check if the 'age' field is less than the 'limit' field - * lt("age", field("limit")); + * lessThan("age", field("limit")); * ``` * * @param fieldName The field name to compare. * @param expression The expression to compare to. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ -export function lt(fieldName: string, expression: Expr): BooleanExpr; +export function lessThan( + fieldName: string, + expression: Expression +): BooleanExpression; /** * @beta @@ -3591,18 +3828,21 @@ export function lt(fieldName: string, expression: Expr): BooleanExpr; * * ```typescript * // Check if the 'price' field is less than 50 - * lt("price", 50); + * lessThan("price", 50); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ -export function lt(fieldName: string, value: unknown): BooleanExpr; -export function lt(left: Expr | string, right: unknown): BooleanExpr { +export function lessThan(fieldName: string, value: unknown): BooleanExpression; +export function lessThan( + left: Expression | string, + right: unknown +): BooleanExpression { const leftExpr = fieldOrExpression(left); const rightExpr = valueToDefaultExpr(right); - return leftExpr.lt(rightExpr); + return leftExpr.lessThan(rightExpr); } /** @@ -3612,14 +3852,17 @@ export function lt(left: Expr | string, right: unknown): BooleanExpr { * * ```typescript * // Check if the 'quantity' field is less than or equal to 20 - * lte(field("quantity"), field("limit")); + * lessThanOrEqual(field("quantity"), field("limit")); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the less than or equal to comparison. + * @return A new `Expression` representing the less than or equal to comparison. */ -export function lte(left: Expr, right: Expr): BooleanExpr; +export function lessThanOrEqual( + left: Expression, + right: Expression +): BooleanExpression; /** * @beta @@ -3627,14 +3870,17 @@ export function lte(left: Expr, right: Expr): BooleanExpr; * * ```typescript * // Check if the 'quantity' field is less than or equal to 20 - * lte(field("quantity"), 20); + * lessThanOrEqual(field("quantity"), 20); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the less than or equal to comparison. + * @return A new `Expression` representing the less than or equal to comparison. */ -export function lte(expression: Expr, value: unknown): BooleanExpr; +export function lessThanOrEqual( + expression: Expression, + value: unknown +): BooleanExpression; /** * @beta @@ -3642,14 +3888,17 @@ export function lte(expression: Expr, value: unknown): BooleanExpr; * * ```typescript * // Check if the 'quantity' field is less than or equal to the 'limit' field - * lte("quantity", field("limit")); + * lessThanOrEqual("quantity", field("limit")); * ``` * * @param fieldName The field name to compare. * @param expression The expression to compare to. - * @return A new `Expr` representing the less than or equal to comparison. + * @return A new `Expression` representing the less than or equal to comparison. */ -export function lte(fieldName: string, expression: Expr): BooleanExpr; +export function lessThanOrEqual( + fieldName: string, + expression: Expression +): BooleanExpression; /** * @beta @@ -3657,18 +3906,24 @@ export function lte(fieldName: string, expression: Expr): BooleanExpr; * * ```typescript * // Check if the 'score' field is less than or equal to 70 - * lte("score", 70); + * lessThanOrEqual("score", 70); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the less than or equal to comparison. + * @return A new `Expression` representing the less than or equal to comparison. */ -export function lte(fieldName: string, value: unknown): BooleanExpr; -export function lte(left: Expr | string, right: unknown): BooleanExpr { +export function lessThanOrEqual( + fieldName: string, + value: unknown +): BooleanExpression; +export function lessThanOrEqual( + left: Expression | string, + right: unknown +): BooleanExpression { const leftExpr = fieldOrExpression(left); const rightExpr = valueToDefaultExpr(right); - return leftExpr.lte(rightExpr); + return leftExpr.lessThanOrEqual(rightExpr); } /** @@ -3678,14 +3933,17 @@ export function lte(left: Expr | string, right: unknown): BooleanExpr { * * ```typescript * // Check if the 'age' field is greater than 18 - * gt(field("age"), Constant(9).add(9)); + * greaterThan(field("age"), Constant(9).add(9)); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the greater than comparison. + * @return A new `Expression` representing the greater than comparison. */ -export function gt(left: Expr, right: Expr): BooleanExpr; +export function greaterThan( + left: Expression, + right: Expression +): BooleanExpression; /** * @beta @@ -3693,14 +3951,17 @@ export function gt(left: Expr, right: Expr): BooleanExpr; * * ```typescript * // Check if the 'age' field is greater than 18 - * gt(field("age"), 18); + * greaterThan(field("age"), 18); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the greater than comparison. + * @return A new `Expression` representing the greater than comparison. */ -export function gt(expression: Expr, value: unknown): BooleanExpr; +export function greaterThan( + expression: Expression, + value: unknown +): BooleanExpression; /** * @beta @@ -3708,14 +3969,17 @@ export function gt(expression: Expr, value: unknown): BooleanExpr; * * ```typescript * // Check if the value of field 'age' is greater than the value of field 'limit' - * gt("age", field("limit")); + * greaterThan("age", field("limit")); * ``` * * @param fieldName The field name to compare. * @param expression The expression to compare to. - * @return A new `Expr` representing the greater than comparison. + * @return A new `Expression` representing the greater than comparison. */ -export function gt(fieldName: string, expression: Expr): BooleanExpr; +export function greaterThan( + fieldName: string, + expression: Expression +): BooleanExpression; /** * @beta @@ -3723,18 +3987,24 @@ export function gt(fieldName: string, expression: Expr): BooleanExpr; * * ```typescript * // Check if the 'price' field is greater than 100 - * gt("price", 100); + * greaterThan("price", 100); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the greater than comparison. + * @return A new `Expression` representing the greater than comparison. */ -export function gt(fieldName: string, value: unknown): BooleanExpr; -export function gt(left: Expr | string, right: unknown): BooleanExpr { +export function greaterThan( + fieldName: string, + value: unknown +): BooleanExpression; +export function greaterThan( + left: Expression | string, + right: unknown +): BooleanExpression { const leftExpr = fieldOrExpression(left); const rightExpr = valueToDefaultExpr(right); - return leftExpr.gt(rightExpr); + return leftExpr.greaterThan(rightExpr); } /** @@ -3744,14 +4014,17 @@ export function gt(left: Expr | string, right: unknown): BooleanExpr { * * ```typescript * // Check if the 'quantity' field is greater than or equal to the field "threshold" - * gte(field("quantity"), field("threshold")); + * greaterThanOrEqual(field("quantity"), field("threshold")); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ -export function gte(left: Expr, right: Expr): BooleanExpr; +export function greaterThanOrEqual( + left: Expression, + right: Expression +): BooleanExpression; /** * @beta @@ -3760,14 +4033,17 @@ export function gte(left: Expr, right: Expr): BooleanExpr; * * ```typescript * // Check if the 'quantity' field is greater than or equal to 10 - * gte(field("quantity"), 10); + * greaterThanOrEqual(field("quantity"), 10); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ -export function gte(expression: Expr, value: unknown): BooleanExpr; +export function greaterThanOrEqual( + expression: Expression, + value: unknown +): BooleanExpression; /** * @beta @@ -3775,14 +4051,17 @@ export function gte(expression: Expr, value: unknown): BooleanExpr; * * ```typescript * // Check if the value of field 'age' is greater than or equal to the value of field 'limit' - * gte("age", field("limit")); + * greaterThanOrEqual("age", field("limit")); * ``` * * @param fieldName The field name to compare. * @param value The expression to compare to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ -export function gte(fieldName: string, value: Expr): BooleanExpr; +export function greaterThanOrEqual( + fieldName: string, + value: Expression +): BooleanExpression; /** * @beta @@ -3791,18 +4070,78 @@ export function gte(fieldName: string, value: Expr): BooleanExpr; * * ```typescript * // Check if the 'score' field is greater than or equal to 80 - * gte("score", 80); + * greaterThanOrEqual("score", 80); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ -export function gte(fieldName: string, value: unknown): BooleanExpr; -export function gte(left: Expr | string, right: unknown): BooleanExpr { +export function greaterThanOrEqual( + fieldName: string, + value: unknown +): BooleanExpression; +export function greaterThanOrEqual( + left: Expression | string, + right: unknown +): BooleanExpression { const leftExpr = fieldOrExpression(left); const rightExpr = valueToDefaultExpr(right); - return leftExpr.gte(rightExpr); + return leftExpr.greaterThanOrEqual(rightExpr); +} + +/** + * @beta + * + * Creates an expression that concatenates an array expression with other arrays. + * + * ```typescript + * // Combine the 'items' array with two new item arrays + * arrayConcat(field("items"), [field("newItems"), field("otherItems")]); + * ``` + * + * @param firstArray The first array expression to concatenate to. + * @param secondArray The second array expression or array literal to concatenate to. + * @param otherArrays Optional additional array expressions or array literals to concatenate. + * @return A new {@code Expr} representing the concatenated array. + */ +export function arrayConcat( + firstArray: Expression, + secondArray: Expression | unknown[], + ...otherArrays: Array +): FunctionExpression; + +/** + * @beta + * + * Creates an expression that concatenates a field's array value with other arrays. + * + * ```typescript + * // Combine the 'items' array with two new item arrays + * arrayConcat("items", [field("newItems"), field("otherItems")]); + * ``` + * + * @param firstArrayField The first array to concatenate to. + * @param secondArray The second array expression or array literal to concatenate to. + * @param otherArrays Optional additional array expressions or array literals to concatenate. + * @return A new {@code Expr} representing the concatenated array. + */ +export function arrayConcat( + firstArrayField: string, + secondArray: Expression | unknown[], + ...otherArrays: Array +): FunctionExpression; + +export function arrayConcat( + firstArray: Expression | string, + secondArray: Expression | unknown[], + ...otherArrays: Array +): FunctionExpression { + const exprValues = otherArrays.map(element => valueToDefaultExpr(element)); + return fieldOrExpression(firstArray).arrayConcat( + fieldOrExpression(secondArray), + ...exprValues + ); } /** @@ -3816,9 +4155,12 @@ export function gte(left: Expr | string, right: unknown): BooleanExpr { * * @param array The array expression to check. * @param element The element to search for in the array. - * @return A new {@code Expr} representing the 'array_contains' comparison. + * @return A new {@code Expression} representing the 'array_contains' comparison. */ -export function arrayContains(array: Expr, element: Expr): FunctionExpr; +export function arrayContains( + array: Expression, + element: Expression +): FunctionExpression; /** * @beta @@ -3831,9 +4173,12 @@ export function arrayContains(array: Expr, element: Expr): FunctionExpr; * * @param array The array expression to check. * @param element The element to search for in the array. - * @return A new {@code Expr} representing the 'array_contains' comparison. + * @return A new {@code Expression} representing the 'array_contains' comparison. */ -export function arrayContains(array: Expr, element: unknown): FunctionExpr; +export function arrayContains( + array: Expression, + element: unknown +): FunctionExpression; /** * @beta @@ -3846,9 +4191,12 @@ export function arrayContains(array: Expr, element: unknown): FunctionExpr; * * @param fieldName The field name to check. * @param element The element to search for in the array. - * @return A new {@code Expr} representing the 'array_contains' comparison. + * @return A new {@code Expression} representing the 'array_contains' comparison. */ -export function arrayContains(fieldName: string, element: Expr): FunctionExpr; +export function arrayContains( + fieldName: string, + element: Expression +): FunctionExpression; /** * @beta @@ -3861,13 +4209,16 @@ export function arrayContains(fieldName: string, element: Expr): FunctionExpr; * * @param fieldName The field name to check. * @param element The element to search for in the array. - * @return A new {@code Expr} representing the 'array_contains' comparison. + * @return A new {@code Expression} representing the 'array_contains' comparison. */ -export function arrayContains(fieldName: string, element: unknown): BooleanExpr; export function arrayContains( - array: Expr | string, + fieldName: string, + element: unknown +): BooleanExpression; +export function arrayContains( + array: Expression | string, element: unknown -): BooleanExpr { +): BooleanExpression { const arrayExpr = fieldOrExpression(array); const elementExpr = valueToDefaultExpr(element); return arrayExpr.arrayContains(elementExpr); @@ -3885,12 +4236,12 @@ export function arrayContains( * * @param array The array expression to check. * @param values The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_any' comparison. + * @return A new {@code Expression} representing the 'array_contains_any' comparison. */ export function arrayContainsAny( - array: Expr, - values: Array -): BooleanExpr; + array: Expression, + values: Array +): BooleanExpression; /** * @beta @@ -3905,12 +4256,12 @@ export function arrayContainsAny( * * @param fieldName The field name to check. * @param values The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_any' comparison. + * @return A new {@code Expression} representing the 'array_contains_any' comparison. */ export function arrayContainsAny( fieldName: string, - values: Array -): BooleanExpr; + values: Array +): BooleanExpression; /** * @beta @@ -3924,9 +4275,12 @@ export function arrayContainsAny( * * @param array The array expression to check. * @param values An expression that evaluates to an array, whose elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_any' comparison. + * @return A new {@code Expression} representing the 'array_contains_any' comparison. */ -export function arrayContainsAny(array: Expr, values: Expr): BooleanExpr; +export function arrayContainsAny( + array: Expression, + values: Expression +): BooleanExpression; /** * @beta @@ -3941,13 +4295,16 @@ export function arrayContainsAny(array: Expr, values: Expr): BooleanExpr; * * @param fieldName The field name to check. * @param values An expression that evaluates to an array, whose elements to check for in the array field. - * @return A new {@code Expr} representing the 'array_contains_any' comparison. + * @return A new {@code Expression} representing the 'array_contains_any' comparison. */ -export function arrayContainsAny(fieldName: string, values: Expr): BooleanExpr; export function arrayContainsAny( - array: Expr | string, - values: unknown[] | Expr -): BooleanExpr { + fieldName: string, + values: Expression +): BooleanExpression; +export function arrayContainsAny( + array: Expression | string, + values: unknown[] | Expression +): BooleanExpression { if (Array.isArray(values)) { return fieldOrExpression(array).arrayContainsAny(values); } else { @@ -3966,12 +4323,12 @@ export function arrayContainsAny( * * @param array The array expression to check. * @param values The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_all' comparison. + * @return A new {@code Expression} representing the 'array_contains_all' comparison. */ export function arrayContainsAll( - array: Expr, - values: Array -): BooleanExpr; + array: Expression, + values: Array +): BooleanExpression; /** * @beta @@ -3985,12 +4342,12 @@ export function arrayContainsAll( * * @param fieldName The field name to check. * @param values The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_all' comparison. + * @return A new {@code Expression} representing the 'array_contains_all' comparison. */ export function arrayContainsAll( fieldName: string, - values: Array -): BooleanExpr; + values: Array +): BooleanExpression; /** * @beta @@ -4003,12 +4360,12 @@ export function arrayContainsAll( * * @param array The array expression to check. * @param arrayExpression The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_all' comparison. + * @return A new {@code Expression} representing the 'array_contains_all' comparison. */ export function arrayContainsAll( - array: Expr, - arrayExpression: Expr -): BooleanExpr; + array: Expression, + arrayExpression: Expression +): BooleanExpression; /** * @beta @@ -4022,16 +4379,16 @@ export function arrayContainsAll( * * @param fieldName The field name to check. * @param arrayExpression The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_all' comparison. + * @return A new {@code Expression} representing the 'array_contains_all' comparison. */ export function arrayContainsAll( fieldName: string, - arrayExpression: Expr -): BooleanExpr; + arrayExpression: Expression +): BooleanExpression; export function arrayContainsAll( - array: Expr | string, - values: unknown[] | Expr -): BooleanExpr { + array: Expression | string, + values: unknown[] | Expression +): BooleanExpression { if (Array.isArray(values)) { return fieldOrExpression(array).arrayContainsAll(values); } else { @@ -4049,9 +4406,9 @@ export function arrayContainsAll( * ``` * * @param fieldName The name of the field containing an array to calculate the length of. - * @return A new {@code Expr} representing the length of the array. + * @return A new {@code Expression} representing the length of the array. */ -export function arrayLength(fieldName: string): FunctionExpr; +export function arrayLength(fieldName: string): FunctionExpression; /** * @beta @@ -4063,10 +4420,10 @@ export function arrayLength(fieldName: string): FunctionExpr; * ``` * * @param array The array expression to calculate the length of. - * @return A new {@code Expr} representing the length of the array. + * @return A new {@code Expression} representing the length of the array. */ -export function arrayLength(array: Expr): FunctionExpr; -export function arrayLength(array: Expr | string): FunctionExpr { +export function arrayLength(array: Expression): FunctionExpression; +export function arrayLength(array: Expression | string): FunctionExpression { return fieldOrExpression(array).arrayLength(); } @@ -4077,17 +4434,17 @@ export function arrayLength(array: Expr | string): FunctionExpr { * * ```typescript * // Check if the 'category' field is either "Electronics" or value of field 'primaryType' - * eqAny(field("category"), [constant("Electronics"), field("primaryType")]); + * equalAny(field("category"), [constant("Electronics"), field("primaryType")]); * ``` * * @param expression The expression whose results to compare. * @param values The values to check against. - * @return A new {@code Expr} representing the 'IN' comparison. + * @return A new {@code Expression} representing the 'IN' comparison. */ -export function eqAny( - expression: Expr, - values: Array -): BooleanExpr; +export function equalAny( + expression: Expression, + values: Array +): BooleanExpression; /** * @beta @@ -4095,14 +4452,17 @@ export function eqAny( * * ```typescript * // Check if the 'category' field is set to a value in the disabledCategories field - * eqAny(field("category"), field('disabledCategories')); + * equalAny(field("category"), field('disabledCategories')); * ``` * * @param expression The expression whose results to compare. * @param arrayExpression An expression that evaluates to an array, whose elements to check for equality to the input. - * @return A new {@code Expr} representing the 'IN' comparison. + * @return A new {@code Expression} representing the 'IN' comparison. */ -export function eqAny(expression: Expr, arrayExpression: Expr): BooleanExpr; +export function equalAny( + expression: Expression, + arrayExpression: Expression +): BooleanExpression; /** * @beta @@ -4111,17 +4471,17 @@ export function eqAny(expression: Expr, arrayExpression: Expr): BooleanExpr; * * ```typescript * // Check if the 'category' field is either "Electronics" or value of field 'primaryType' - * eqAny("category", [constant("Electronics"), field("primaryType")]); + * equalAny("category", [constant("Electronics"), field("primaryType")]); * ``` * * @param fieldName The field to compare. * @param values The values to check against. - * @return A new {@code Expr} representing the 'IN' comparison. + * @return A new {@code Expression} representing the 'IN' comparison. */ -export function eqAny( +export function equalAny( fieldName: string, - values: Array -): BooleanExpr; + values: Array +): BooleanExpression; /** * @beta @@ -4130,22 +4490,25 @@ export function eqAny( * * ```typescript * // Check if the 'category' field is either "Electronics" or value of field 'primaryType' - * eqAny("category", ["Electronics", field("primaryType")]); + * equalAny("category", ["Electronics", field("primaryType")]); * ``` * * @param fieldName The field to compare. * @param arrayExpression An expression that evaluates to an array, whose elements to check for equality to the input field. - * @return A new {@code Expr} representing the 'IN' comparison. + * @return A new {@code Expression} representing the 'IN' comparison. */ -export function eqAny(fieldName: string, arrayExpression: Expr): BooleanExpr; -export function eqAny( - element: Expr | string, - values: unknown[] | Expr -): BooleanExpr { +export function equalAny( + fieldName: string, + arrayExpression: Expression +): BooleanExpression; +export function equalAny( + element: Expression | string, + values: unknown[] | Expression +): BooleanExpression { if (Array.isArray(values)) { - return fieldOrExpression(element).eqAny(values); + return fieldOrExpression(element).equalAny(values); } else { - return fieldOrExpression(element).eqAny(values); + return fieldOrExpression(element).equalAny(values); } } @@ -4156,17 +4519,17 @@ export function eqAny( * * ```typescript * // Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus' - * notEqAny(field("status"), ["pending", field("rejectedStatus")]); + * notEqualAny(field("status"), ["pending", field("rejectedStatus")]); * ``` * * @param element The expression to compare. * @param values The values to check against. - * @return A new {@code Expr} representing the 'NOT IN' comparison. + * @return A new {@code Expression} representing the 'NOT IN' comparison. */ -export function notEqAny( - element: Expr, - values: Array -): BooleanExpr; +export function notEqualAny( + element: Expression, + values: Array +): BooleanExpression; /** * @beta @@ -4175,17 +4538,17 @@ export function notEqAny( * * ```typescript * // Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus' - * notEqAny("status", [constant("pending"), field("rejectedStatus")]); + * notEqualAny("status", [constant("pending"), field("rejectedStatus")]); * ``` * * @param fieldName The field name to compare. * @param values The values to check against. - * @return A new {@code Expr} representing the 'NOT IN' comparison. + * @return A new {@code Expression} representing the 'NOT IN' comparison. */ -export function notEqAny( +export function notEqualAny( fieldName: string, - values: Array -): BooleanExpr; + values: Array +): BooleanExpression; /** * @beta @@ -4194,14 +4557,17 @@ export function notEqAny( * * ```typescript * // Check if the 'status' field is neither "pending" nor the value of the field 'rejectedStatus' - * notEqAny(field("status"), ["pending", field("rejectedStatus")]); + * notEqualAny(field("status"), ["pending", field("rejectedStatus")]); * ``` * * @param element The expression to compare. * @param arrayExpression The values to check against. - * @return A new {@code Expr} representing the 'NOT IN' comparison. + * @return A new {@code Expression} representing the 'NOT IN' comparison. */ -export function notEqAny(element: Expr, arrayExpression: Expr): BooleanExpr; +export function notEqualAny( + element: Expression, + arrayExpression: Expression +): BooleanExpression; /** * @beta @@ -4209,23 +4575,26 @@ export function notEqAny(element: Expr, arrayExpression: Expr): BooleanExpr; * * ```typescript * // Check if the 'status' field is not equal to any value in the field 'rejectedStatuses' - * notEqAny("status", field("rejectedStatuses")); + * notEqualAny("status", field("rejectedStatuses")); * ``` * * @param fieldName The field name to compare. * @param arrayExpression The values to check against. - * @return A new {@code Expr} representing the 'NOT IN' comparison. + * @return A new {@code Expression} representing the 'NOT IN' comparison. */ -export function notEqAny(fieldName: string, arrayExpression: Expr): BooleanExpr; +export function notEqualAny( + fieldName: string, + arrayExpression: Expression +): BooleanExpression; -export function notEqAny( - element: Expr | string, - values: unknown[] | Expr -): BooleanExpr { +export function notEqualAny( + element: Expression | string, + values: unknown[] | Expression +): BooleanExpression { if (Array.isArray(values)) { - return fieldOrExpression(element).notEqAny(values); + return fieldOrExpression(element).notEqualAny(values); } else { - return fieldOrExpression(element).notEqAny(values); + return fieldOrExpression(element).notEqualAny(values); } } @@ -4237,22 +4606,22 @@ export function notEqAny( * // Check if only one of the conditions is true: 'age' greater than 18, 'city' is "London", * // or 'status' is "active". * const condition = xor( - * gt("age", 18), - * eq("city", "London"), - * eq("status", "active")); + * greaterThan("age", 18), + * equal("city", "London"), + * equal("status", "active")); * ``` * * @param first The first condition. * @param second The second condition. * @param additionalConditions Additional conditions to 'XOR' together. - * @return A new {@code Expr} representing the logical 'XOR' operation. + * @return A new {@code Expression} representing the logical 'XOR' operation. */ export function xor( - first: BooleanExpr, - second: BooleanExpr, - ...additionalConditions: BooleanExpr[] -): BooleanExpr { - return new BooleanExpr('xor', [first, second, ...additionalConditions]); + first: BooleanExpression, + second: BooleanExpression, + ...additionalConditions: BooleanExpression[] +): BooleanExpression { + return new BooleanExpression('xor', [first, second, ...additionalConditions]); } /** @@ -4262,24 +4631,24 @@ export function xor( * * ```typescript * // If 'age' is greater than 18, return "Adult"; otherwise, return "Minor". - * cond( - * gt("age", 18), constant("Adult"), constant("Minor")); + * conditional( + * greaterThan("age", 18), constant("Adult"), constant("Minor")); * ``` * * @param condition The condition to evaluate. * @param thenExpr The expression to evaluate if the condition is true. * @param elseExpr The expression to evaluate if the condition is false. - * @return A new {@code Expr} representing the conditional expression. - */ -export function cond( - condition: BooleanExpr, - thenExpr: Expr, - elseExpr: Expr -): FunctionExpr { - return new FunctionExpr('cond', [ + * @return A new {@code Expression} representing the conditional expression. + */ +export function conditional( + condition: BooleanExpression, + thenExpr: Expression, + elseExpr: Expression +): FunctionExpression { + return new FunctionExpression('conditional', [ condition, - cast(thenExpr), - cast(elseExpr), + cast(thenExpr), + cast(elseExpr), ]); } @@ -4289,13 +4658,13 @@ export function cond( * * ```typescript * // Find documents where the 'completed' field is NOT true - * not(eq("completed", true)); + * not(equal("completed", true)); * ``` * * @param booleanExpr The filter condition to negate. - * @return A new {@code Expr} representing the negated filter condition. + * @return A new {@code Expression} representing the negated filter condition. */ -export function not(booleanExpr: BooleanExpr): BooleanExpr { +export function not(booleanExpr: BooleanExpression): BooleanExpression { return booleanExpr.not(); } @@ -4313,13 +4682,13 @@ export function not(booleanExpr: BooleanExpr): BooleanExpr { * @param first The first operand expression. * @param second The second expression or literal. * @param others Optional additional expressions or literals. - * @return A new {@code Expr} representing the logical max operation. + * @return A new {@code Expression} representing the logical max operation. */ export function logicalMaximum( - first: Expr, - second: Expr | unknown, - ...others: Array -): FunctionExpr; + first: Expression, + second: Expression | unknown, + ...others: Array +): FunctionExpression; /** * @beta @@ -4335,19 +4704,19 @@ export function logicalMaximum( * @param fieldName The first operand field name. * @param second The second expression or literal. * @param others Optional additional expressions or literals. - * @return A new {@code Expr} representing the logical max operation. + * @return A new {@code Expression} representing the logical max operation. */ export function logicalMaximum( fieldName: string, - second: Expr | unknown, - ...others: Array -): FunctionExpr; + second: Expression | unknown, + ...others: Array +): FunctionExpression; export function logicalMaximum( - first: Expr | string, - second: Expr | unknown, - ...others: Array -): FunctionExpr { + first: Expression | string, + second: Expression | unknown, + ...others: Array +): FunctionExpression { return fieldOrExpression(first).logicalMaximum( valueToDefaultExpr(second), ...others.map(value => valueToDefaultExpr(value)) @@ -4368,13 +4737,13 @@ export function logicalMaximum( * @param first The first operand expression. * @param second The second expression or literal. * @param others Optional additional expressions or literals. - * @return A new {@code Expr} representing the logical min operation. + * @return A new {@code Expression} representing the logical min operation. */ export function logicalMinimum( - first: Expr, - second: Expr | unknown, - ...others: Array -): FunctionExpr; + first: Expression, + second: Expression | unknown, + ...others: Array +): FunctionExpression; /** * @beta @@ -4391,19 +4760,19 @@ export function logicalMinimum( * @param fieldName The first operand field name. * @param second The second expression or literal. * @param others Optional additional expressions or literals. - * @return A new {@code Expr} representing the logical min operation. + * @return A new {@code Expression} representing the logical min operation. */ export function logicalMinimum( fieldName: string, - second: Expr | unknown, - ...others: Array -): FunctionExpr; + second: Expression | unknown, + ...others: Array +): FunctionExpression; export function logicalMinimum( - first: Expr | string, - second: Expr | unknown, - ...others: Array -): FunctionExpr { + first: Expression | string, + second: Expression | unknown, + ...others: Array +): FunctionExpression { return fieldOrExpression(first).logicalMinimum( valueToDefaultExpr(second), ...others.map(value => valueToDefaultExpr(value)) @@ -4420,9 +4789,9 @@ export function logicalMinimum( * ``` * * @param value An expression evaluates to the name of the field to check. - * @return A new {@code Expr} representing the 'exists' check. + * @return A new {@code Expression} representing the 'exists' check. */ -export function exists(value: Expr): BooleanExpr; +export function exists(value: Expression): BooleanExpression; /** * @beta @@ -4434,44 +4803,13 @@ export function exists(value: Expr): BooleanExpr; * ``` * * @param fieldName The field name to check. - * @return A new {@code Expr} representing the 'exists' check. + * @return A new {@code Expression} representing the 'exists' check. */ -export function exists(fieldName: string): BooleanExpr; -export function exists(valueOrField: Expr | string): BooleanExpr { +export function exists(fieldName: string): BooleanExpression; +export function exists(valueOrField: Expression | string): BooleanExpression { return fieldOrExpression(valueOrField).exists(); } -/** - * @beta - * Creates an expression that checks if an expression evaluates to 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NaN - * isNan(field("value").divide(0)); - * ``` - * - * @param value The expression to check. - * @return A new {@code Expr} representing the 'isNan' check. - */ -export function isNan(value: Expr): BooleanExpr; - -/** - * @beta - * Creates an expression that checks if a field's value evaluates to 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NaN - * isNan("value"); - * ``` - * - * @param fieldName The name of the field to check. - * @return A new {@code Expr} representing the 'isNan' check. - */ -export function isNan(fieldName: string): BooleanExpr; -export function isNan(value: Expr | string): BooleanExpr { - return fieldOrExpression(value).isNan(); -} - /** * @beta * Creates an expression that reverses a string. @@ -4482,9 +4820,9 @@ export function isNan(value: Expr | string): BooleanExpr { * ``` * * @param stringExpression An expression evaluating to a string value, which will be reversed. - * @return A new {@code Expr} representing the reversed string. + * @return A new {@code Expression} representing the reversed string. */ -export function reverse(stringExpression: Expr): FunctionExpr; +export function reverse(stringExpression: Expression): FunctionExpression; /** * @beta @@ -4496,10 +4834,10 @@ export function reverse(stringExpression: Expr): FunctionExpr; * ``` * * @param field The name of the field representing the string to reverse. - * @return A new {@code Expr} representing the reversed string. + * @return A new {@code Expression} representing the reversed string. */ -export function reverse(field: string): FunctionExpr; -export function reverse(expr: Expr | string): FunctionExpr { +export function reverse(field: string): FunctionExpression; +export function reverse(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).reverse(); } @@ -4513,9 +4851,9 @@ export function reverse(expr: Expr | string): FunctionExpr { * ``` * * @param fieldName The name of the field to reverse. - * @return A new {@code Expr} representing the reversed array. + * @return A new {@code Expression} representing the reversed array. */ -export function arrayReverse(fieldName: string): FunctionExpr; +export function arrayReverse(fieldName: string): FunctionExpression; /** * @beta @@ -4527,10 +4865,10 @@ export function arrayReverse(fieldName: string): FunctionExpr; * ``` * * @param arrayExpression An expression evaluating to an array value, which will be reversed. - * @return A new {@code Expr} representing the reversed array. + * @return A new {@code Expression} representing the reversed array. */ -export function arrayReverse(arrayExpression: Expr): FunctionExpr; -export function arrayReverse(expr: Expr | string): FunctionExpr { +export function arrayReverse(arrayExpression: Expression): FunctionExpression; +export function arrayReverse(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).arrayReverse(); } @@ -4544,9 +4882,9 @@ export function arrayReverse(expr: Expr | string): FunctionExpr { * ``` * * @param expr The expression representing the string. - * @return A new {@code Expr} representing the length of the string in bytes. + * @return A new {@code Expression} representing the length of the string in bytes. */ -export function byteLength(expr: Expr): FunctionExpr; +export function byteLength(expr: Expression): FunctionExpression; /** * @beta @@ -4558,10 +4896,10 @@ export function byteLength(expr: Expr): FunctionExpr; * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the length of the string in bytes. + * @return A new {@code Expression} representing the length of the string in bytes. */ -export function byteLength(fieldName: string): FunctionExpr; -export function byteLength(expr: Expr | string): FunctionExpr { +export function byteLength(fieldName: string): FunctionExpression; +export function byteLength(expr: Expression | string): FunctionExpression { const normalizedExpr = fieldOrExpression(expr); return normalizedExpr.byteLength(); } @@ -4575,9 +4913,9 @@ export function byteLength(expr: Expr | string): FunctionExpr { * exp(constant(2)); * ``` * - * @return A new {@code Expr} representing the exp of the numeric value. + * @return A new {@code Expression} representing the exp of the numeric value. */ -export function exp(expression: Expr): FunctionExpr; +export function exp(expression: Expression): FunctionExpression; /** * @beta @@ -4588,11 +4926,13 @@ export function exp(expression: Expr): FunctionExpr; * exp('value'); * ``` * - * @return A new {@code Expr} representing the exp of the numeric value. + * @return A new {@code Expression} representing the exp of the numeric value. */ -export function exp(fieldName: string): FunctionExpr; +export function exp(fieldName: string): FunctionExpression; -export function exp(expressionOrFieldName: Expr | string): FunctionExpr { +export function exp( + expressionOrFieldName: Expression | string +): FunctionExpression { return fieldOrExpression(expressionOrFieldName).exp(); } @@ -4606,9 +4946,9 @@ export function exp(expressionOrFieldName: Expr | string): FunctionExpr { * ``` * * @param fieldName The name of the field to compute the ceiling of. - * @return A new {@code Expr} representing the ceiling of the numeric value. + * @return A new {@code Expression} representing the ceiling of the numeric value. */ -export function ceil(fieldName: string): FunctionExpr; +export function ceil(fieldName: string): FunctionExpression; /** * @beta @@ -4620,10 +4960,10 @@ export function ceil(fieldName: string): FunctionExpr; * ``` * * @param expression An expression evaluating to a numeric value, which the ceiling will be computed for. - * @return A new {@code Expr} representing the ceiling of the numeric value. + * @return A new {@code Expression} representing the ceiling of the numeric value. */ -export function ceil(expression: Expr): FunctionExpr; -export function ceil(expr: Expr | string): FunctionExpr { +export function ceil(expression: Expression): FunctionExpression; +export function ceil(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).ceil(); } @@ -4632,19 +4972,19 @@ export function ceil(expr: Expr | string): FunctionExpr { * Creates an expression that computes the floor of a numeric value. * * @param expr The expression to compute the floor of. - * @return A new {@code Expr} representing the floor of the numeric value. + * @return A new {@code Expression} representing the floor of the numeric value. */ -export function floor(expr: Expr): FunctionExpr; +export function floor(expr: Expression): FunctionExpression; /** * @beta * Creates an expression that computes the floor of a numeric value. * * @param fieldName The name of the field to compute the floor of. - * @return A new {@code Expr} representing the floor of the numeric value. + * @return A new {@code Expression} representing the floor of the numeric value. */ -export function floor(fieldName: string): FunctionExpr; -export function floor(expr: Expr | string): FunctionExpr { +export function floor(fieldName: string): FunctionExpression; +export function floor(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).floor(); } @@ -4655,7 +4995,7 @@ export function floor(expr: Expr | string): FunctionExpr { * @param expr The expression or field to count distinct values of. * @return A new `AggregateFunction` representing the 'count_distinct' aggregation. */ -export function countDistinct(expr: Expr | string): AggregateFunction { +export function countDistinct(expr: Expression | string): AggregateFunction { return fieldOrExpression(expr).countDistinct(); } @@ -4669,9 +5009,9 @@ export function countDistinct(expr: Expr | string): AggregateFunction { * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the length of the string. + * @return A new {@code Expression} representing the length of the string. */ -export function charLength(fieldName: string): FunctionExpr; +export function charLength(fieldName: string): FunctionExpression; /** * @beta @@ -4683,10 +5023,10 @@ export function charLength(fieldName: string): FunctionExpr; * ``` * * @param stringExpression The expression representing the string to calculate the length of. - * @return A new {@code Expr} representing the length of the string. + * @return A new {@code Expression} representing the length of the string. */ -export function charLength(stringExpression: Expr): FunctionExpr; -export function charLength(value: Expr | string): FunctionExpr { +export function charLength(stringExpression: Expression): FunctionExpression; +export function charLength(value: Expression | string): FunctionExpression { const valueExpr = fieldOrExpression(value); return valueExpr.charLength(); } @@ -4703,9 +5043,9 @@ export function charLength(value: Expr | string): FunctionExpr { * * @param fieldName The name of the field containing the string. * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new {@code Expr} representing the 'like' comparison. + * @return A new {@code Expression} representing the 'like' comparison. */ -export function like(fieldName: string, pattern: string): BooleanExpr; +export function like(fieldName: string, pattern: string): BooleanExpression; /** * @beta @@ -4719,9 +5059,9 @@ export function like(fieldName: string, pattern: string): BooleanExpr; * * @param fieldName The name of the field containing the string. * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new {@code Expr} representing the 'like' comparison. + * @return A new {@code Expression} representing the 'like' comparison. */ -export function like(fieldName: string, pattern: Expr): BooleanExpr; +export function like(fieldName: string, pattern: Expression): BooleanExpression; /** * @beta @@ -4734,9 +5074,12 @@ export function like(fieldName: string, pattern: Expr): BooleanExpr; * * @param stringExpression The expression representing the string to perform the comparison on. * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new {@code Expr} representing the 'like' comparison. + * @return A new {@code Expression} representing the 'like' comparison. */ -export function like(stringExpression: Expr, pattern: string): BooleanExpr; +export function like( + stringExpression: Expression, + pattern: string +): BooleanExpression; /** * @beta @@ -4749,13 +5092,16 @@ export function like(stringExpression: Expr, pattern: string): BooleanExpr; * * @param stringExpression The expression representing the string to perform the comparison on. * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new {@code Expr} representing the 'like' comparison. + * @return A new {@code Expression} representing the 'like' comparison. */ -export function like(stringExpression: Expr, pattern: Expr): BooleanExpr; export function like( - left: Expr | string, - pattern: Expr | string -): FunctionExpr { + stringExpression: Expression, + pattern: Expression +): BooleanExpression; +export function like( + left: Expression | string, + pattern: Expression | string +): FunctionExpression { const leftExpr = fieldOrExpression(left); const patternExpr = valueToDefaultExpr(pattern); return leftExpr.like(patternExpr); @@ -4773,9 +5119,12 @@ export function like( * * @param fieldName The name of the field containing the string. * @param pattern The regular expression to use for the search. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ -export function regexContains(fieldName: string, pattern: string): BooleanExpr; +export function regexContains( + fieldName: string, + pattern: string +): BooleanExpression; /** * @beta @@ -4789,9 +5138,12 @@ export function regexContains(fieldName: string, pattern: string): BooleanExpr; * * @param fieldName The name of the field containing the string. * @param pattern The regular expression to use for the search. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ -export function regexContains(fieldName: string, pattern: Expr): BooleanExpr; +export function regexContains( + fieldName: string, + pattern: Expression +): BooleanExpression; /** * @beta @@ -4805,12 +5157,12 @@ export function regexContains(fieldName: string, pattern: Expr): BooleanExpr; * * @param stringExpression The expression representing the string to perform the comparison on. * @param pattern The regular expression to use for the search. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ export function regexContains( - stringExpression: Expr, + stringExpression: Expression, pattern: string -): BooleanExpr; +): BooleanExpression; /** * @beta @@ -4824,16 +5176,16 @@ export function regexContains( * * @param stringExpression The expression representing the string to perform the comparison on. * @param pattern The regular expression to use for the search. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ export function regexContains( - stringExpression: Expr, - pattern: Expr -): BooleanExpr; + stringExpression: Expression, + pattern: Expression +): BooleanExpression; export function regexContains( - left: Expr | string, - pattern: Expr | string -): BooleanExpr { + left: Expression | string, + pattern: Expression | string +): BooleanExpression { const leftExpr = fieldOrExpression(left); const patternExpr = valueToDefaultExpr(pattern); return leftExpr.regexContains(patternExpr); @@ -4850,9 +5202,12 @@ export function regexContains( * * @param fieldName The name of the field containing the string. * @param pattern The regular expression to use for the match. - * @return A new {@code Expr} representing the regular expression match. + * @return A new {@code Expression} representing the regular expression match. */ -export function regexMatch(fieldName: string, pattern: string): BooleanExpr; +export function regexMatch( + fieldName: string, + pattern: string +): BooleanExpression; /** * @beta @@ -4865,9 +5220,12 @@ export function regexMatch(fieldName: string, pattern: string): BooleanExpr; * * @param fieldName The name of the field containing the string. * @param pattern The regular expression to use for the match. - * @return A new {@code Expr} representing the regular expression match. + * @return A new {@code Expression} representing the regular expression match. */ -export function regexMatch(fieldName: string, pattern: Expr): BooleanExpr; +export function regexMatch( + fieldName: string, + pattern: Expression +): BooleanExpression; /** * @beta @@ -4881,12 +5239,12 @@ export function regexMatch(fieldName: string, pattern: Expr): BooleanExpr; * * @param stringExpression The expression representing the string to match against. * @param pattern The regular expression to use for the match. - * @return A new {@code Expr} representing the regular expression match. + * @return A new {@code Expression} representing the regular expression match. */ export function regexMatch( - stringExpression: Expr, + stringExpression: Expression, pattern: string -): BooleanExpr; +): BooleanExpression; /** * @beta @@ -4900,13 +5258,16 @@ export function regexMatch( * * @param stringExpression The expression representing the string to match against. * @param pattern The regular expression to use for the match. - * @return A new {@code Expr} representing the regular expression match. + * @return A new {@code Expression} representing the regular expression match. */ -export function regexMatch(stringExpression: Expr, pattern: Expr): BooleanExpr; export function regexMatch( - left: Expr | string, - pattern: Expr | string -): BooleanExpr { + stringExpression: Expression, + pattern: Expression +): BooleanExpression; +export function regexMatch( + left: Expression | string, + pattern: Expression | string +): BooleanExpression { const leftExpr = fieldOrExpression(left); const patternExpr = valueToDefaultExpr(pattern); return leftExpr.regexMatch(patternExpr); @@ -4918,14 +5279,17 @@ export function regexMatch( * * ```typescript * // Check if the 'description' field contains "example". - * strContains("description", "example"); + * stringContains("description", "example"); * ``` * * @param fieldName The name of the field containing the string. * @param substring The substring to search for. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ -export function strContains(fieldName: string, substring: string): BooleanExpr; +export function stringContains( + fieldName: string, + substring: string +): BooleanExpression; /** * @beta @@ -4933,14 +5297,17 @@ export function strContains(fieldName: string, substring: string): BooleanExpr; * * ```typescript * // Check if the 'description' field contains the value of the 'keyword' field. - * strContains("description", field("keyword")); + * stringContains("description", field("keyword")); * ``` * * @param fieldName The name of the field containing the string. * @param substring The expression representing the substring to search for. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ -export function strContains(fieldName: string, substring: Expr): BooleanExpr; +export function stringContains( + fieldName: string, + substring: Expression +): BooleanExpression; /** * @beta @@ -4948,17 +5315,17 @@ export function strContains(fieldName: string, substring: Expr): BooleanExpr; * * ```typescript * // Check if the 'description' field contains "example". - * strContains(field("description"), "example"); + * stringContains(field("description"), "example"); * ``` * * @param stringExpression The expression representing the string to perform the comparison on. * @param substring The substring to search for. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ -export function strContains( - stringExpression: Expr, +export function stringContains( + stringExpression: Expression, substring: string -): BooleanExpr; +): BooleanExpression; /** * @beta @@ -4966,24 +5333,24 @@ export function strContains( * * ```typescript * // Check if the 'description' field contains the value of the 'keyword' field. - * strContains(field("description"), field("keyword")); + * stringContains(field("description"), field("keyword")); * ``` * * @param stringExpression The expression representing the string to perform the comparison on. * @param substring The expression representing the substring to search for. - * @return A new {@code Expr} representing the 'contains' comparison. - */ -export function strContains( - stringExpression: Expr, - substring: Expr -): BooleanExpr; -export function strContains( - left: Expr | string, - substring: Expr | string -): BooleanExpr { + * @return A new {@code Expression} representing the 'contains' comparison. + */ +export function stringContains( + stringExpression: Expression, + substring: Expression +): BooleanExpression; +export function stringContains( + left: Expression | string, + substring: Expression | string +): BooleanExpression { const leftExpr = fieldOrExpression(left); const substringExpr = valueToDefaultExpr(substring); - return leftExpr.strContains(substringExpr); + return leftExpr.stringContains(substringExpr); } /** @@ -4997,9 +5364,12 @@ export function strContains( * * @param fieldName The field name to check. * @param prefix The prefix to check for. - * @return A new {@code Expr} representing the 'starts with' comparison. + * @return A new {@code Expression} representing the 'starts with' comparison. */ -export function startsWith(fieldName: string, prefix: string): BooleanExpr; +export function startsWith( + fieldName: string, + prefix: string +): BooleanExpression; /** * @beta @@ -5012,9 +5382,12 @@ export function startsWith(fieldName: string, prefix: string): BooleanExpr; * * @param fieldName The field name to check. * @param prefix The expression representing the prefix. - * @return A new {@code Expr} representing the 'starts with' comparison. + * @return A new {@code Expression} representing the 'starts with' comparison. */ -export function startsWith(fieldName: string, prefix: Expr): BooleanExpr; +export function startsWith( + fieldName: string, + prefix: Expression +): BooleanExpression; /** * @beta @@ -5027,9 +5400,12 @@ export function startsWith(fieldName: string, prefix: Expr): BooleanExpr; * * @param stringExpression The expression to check. * @param prefix The prefix to check for. - * @return A new {@code Expr} representing the 'starts with' comparison. + * @return A new {@code Expression} representing the 'starts with' comparison. */ -export function startsWith(stringExpression: Expr, prefix: string): BooleanExpr; +export function startsWith( + stringExpression: Expression, + prefix: string +): BooleanExpression; /** * @beta @@ -5042,13 +5418,16 @@ export function startsWith(stringExpression: Expr, prefix: string): BooleanExpr; * * @param stringExpression The expression to check. * @param prefix The prefix to check for. - * @return A new {@code Expr} representing the 'starts with' comparison. + * @return A new {@code Expression} representing the 'starts with' comparison. */ -export function startsWith(stringExpression: Expr, prefix: Expr): BooleanExpr; export function startsWith( - expr: Expr | string, - prefix: Expr | string -): BooleanExpr { + stringExpression: Expression, + prefix: Expression +): BooleanExpression; +export function startsWith( + expr: Expression | string, + prefix: Expression | string +): BooleanExpression { return fieldOrExpression(expr).startsWith(valueToDefaultExpr(prefix)); } @@ -5063,9 +5442,9 @@ export function startsWith( * * @param fieldName The field name to check. * @param suffix The postfix to check for. - * @return A new {@code Expr} representing the 'ends with' comparison. + * @return A new {@code Expression} representing the 'ends with' comparison. */ -export function endsWith(fieldName: string, suffix: string): BooleanExpr; +export function endsWith(fieldName: string, suffix: string): BooleanExpression; /** * @beta @@ -5078,9 +5457,12 @@ export function endsWith(fieldName: string, suffix: string): BooleanExpr; * * @param fieldName The field name to check. * @param suffix The expression representing the postfix. - * @return A new {@code Expr} representing the 'ends with' comparison. + * @return A new {@code Expression} representing the 'ends with' comparison. */ -export function endsWith(fieldName: string, suffix: Expr): BooleanExpr; +export function endsWith( + fieldName: string, + suffix: Expression +): BooleanExpression; /** * @beta @@ -5093,9 +5475,12 @@ export function endsWith(fieldName: string, suffix: Expr): BooleanExpr; * * @param stringExpression The expression to check. * @param suffix The postfix to check for. - * @return A new {@code Expr} representing the 'ends with' comparison. + * @return A new {@code Expression} representing the 'ends with' comparison. */ -export function endsWith(stringExpression: Expr, suffix: string): BooleanExpr; +export function endsWith( + stringExpression: Expression, + suffix: string +): BooleanExpression; /** * @beta @@ -5108,13 +5493,16 @@ export function endsWith(stringExpression: Expr, suffix: string): BooleanExpr; * * @param stringExpression The expression to check. * @param suffix The postfix to check for. - * @return A new {@code Expr} representing the 'ends with' comparison. + * @return A new {@code Expression} representing the 'ends with' comparison. */ -export function endsWith(stringExpression: Expr, suffix: Expr): BooleanExpr; export function endsWith( - expr: Expr | string, - suffix: Expr | string -): BooleanExpr { + stringExpression: Expression, + suffix: Expression +): BooleanExpression; +export function endsWith( + expr: Expression | string, + suffix: Expression | string +): BooleanExpression { return fieldOrExpression(expr).endsWith(valueToDefaultExpr(suffix)); } @@ -5128,9 +5516,9 @@ export function endsWith( * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the lowercase string. + * @return A new {@code Expression} representing the lowercase string. */ -export function toLower(fieldName: string): FunctionExpr; +export function toLower(fieldName: string): FunctionExpression; /** * @beta @@ -5142,10 +5530,10 @@ export function toLower(fieldName: string): FunctionExpr; * ``` * * @param stringExpression The expression representing the string to convert to lowercase. - * @return A new {@code Expr} representing the lowercase string. + * @return A new {@code Expression} representing the lowercase string. */ -export function toLower(stringExpression: Expr): FunctionExpr; -export function toLower(expr: Expr | string): FunctionExpr { +export function toLower(stringExpression: Expression): FunctionExpression; +export function toLower(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).toLower(); } @@ -5159,9 +5547,9 @@ export function toLower(expr: Expr | string): FunctionExpr { * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the uppercase string. + * @return A new {@code Expression} representing the uppercase string. */ -export function toUpper(fieldName: string): FunctionExpr; +export function toUpper(fieldName: string): FunctionExpression; /** * @beta @@ -5173,10 +5561,10 @@ export function toUpper(fieldName: string): FunctionExpr; * ``` * * @param stringExpression The expression representing the string to convert to uppercase. - * @return A new {@code Expr} representing the uppercase string. + * @return A new {@code Expression} representing the uppercase string. */ -export function toUpper(stringExpression: Expr): FunctionExpr; -export function toUpper(expr: Expr | string): FunctionExpr { +export function toUpper(stringExpression: Expression): FunctionExpression; +export function toUpper(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).toUpper(); } @@ -5190,9 +5578,9 @@ export function toUpper(expr: Expr | string): FunctionExpr { * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the trimmed string. + * @return A new {@code Expression} representing the trimmed string. */ -export function trim(fieldName: string): FunctionExpr; +export function trim(fieldName: string): FunctionExpression; /** * @beta @@ -5204,10 +5592,10 @@ export function trim(fieldName: string): FunctionExpr; * ``` * * @param stringExpression The expression representing the string to trim. - * @return A new {@code Expr} representing the trimmed string. + * @return A new {@code Expression} representing the trimmed string. */ -export function trim(stringExpression: Expr): FunctionExpr; -export function trim(expr: Expr | string): FunctionExpr { +export function trim(stringExpression: Expression): FunctionExpression; +export function trim(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).trim(); } @@ -5217,19 +5605,19 @@ export function trim(expr: Expr | string): FunctionExpr { * * ```typescript * // Combine the 'firstName', " ", and 'lastName' fields into a single string - * strConcat("firstName", " ", field("lastName")); + * stringConcat("firstName", " ", field("lastName")); * ``` * * @param fieldName The field name containing the initial string value. * @param secondString An expression or string literal to concatenate. * @param otherStrings Optional additional expressions or literals (typically strings) to concatenate. - * @return A new {@code Expr} representing the concatenated string. + * @return A new {@code Expression} representing the concatenated string. */ -export function strConcat( +export function stringConcat( fieldName: string, - secondString: Expr | string, - ...otherStrings: Array -): FunctionExpr; + secondString: Expression | string, + ...otherStrings: Array +): FunctionExpression; /** * @beta @@ -5237,25 +5625,25 @@ export function strConcat( * * ```typescript * // Combine the 'firstName', " ", and 'lastName' fields into a single string - * strConcat(field("firstName"), " ", field("lastName")); + * stringConcat(field("firstName"), " ", field("lastName")); * ``` * * @param firstString The initial string expression to concatenate to. * @param secondString An expression or string literal to concatenate. * @param otherStrings Optional additional expressions or literals (typically strings) to concatenate. - * @return A new {@code Expr} representing the concatenated string. - */ -export function strConcat( - firstString: Expr, - secondString: Expr | string, - ...otherStrings: Array -): FunctionExpr; -export function strConcat( - first: string | Expr, - second: string | Expr, - ...elements: Array -): FunctionExpr { - return fieldOrExpression(first).strConcat( + * @return A new {@code Expression} representing the concatenated string. + */ +export function stringConcat( + firstString: Expression, + secondString: Expression | string, + ...otherStrings: Array +): FunctionExpression; +export function stringConcat( + first: string | Expression, + second: string | Expression, + ...elements: Array +): FunctionExpression { + return fieldOrExpression(first).stringConcat( valueToDefaultExpr(second), ...elements.map(valueToDefaultExpr) ); @@ -5272,9 +5660,9 @@ export function strConcat( * * @param fieldName The field name of the map field. * @param subField The key to access in the map. - * @return A new {@code Expr} representing the value associated with the given key in the map. + * @return A new {@code Expression} representing the value associated with the given key in the map. */ -export function mapGet(fieldName: string, subField: string): FunctionExpr; +export function mapGet(fieldName: string, subField: string): FunctionExpression; /** * @beta @@ -5287,13 +5675,16 @@ export function mapGet(fieldName: string, subField: string): FunctionExpr; * * @param mapExpression The expression representing the map. * @param subField The key to access in the map. - * @return A new {@code Expr} representing the value associated with the given key in the map. + * @return A new {@code Expression} representing the value associated with the given key in the map. */ -export function mapGet(mapExpression: Expr, subField: string): FunctionExpr; export function mapGet( - fieldOrExpr: string | Expr, + mapExpression: Expression, subField: string -): FunctionExpr { +): FunctionExpression; +export function mapGet( + fieldOrExpr: string | Expression, + subField: string +): FunctionExpression { return fieldOrExpression(fieldOrExpr).mapGet(subField); } @@ -5319,13 +5710,13 @@ export function countAll(): AggregateFunction { * * ```typescript * // Count the number of items where the price is greater than 10 - * count(field("price").gt(10)).as("expensiveItemCount"); + * count(field("price").greaterThan(10)).as("expensiveItemCount"); * ``` * * @param expression The expression to count. * @return A new {@code AggregateFunction} representing the 'count' aggregation. */ -export function count(expression: Expr): AggregateFunction; +export function count(expression: Expression): AggregateFunction; /** * @beta @@ -5340,7 +5731,7 @@ export function count(expression: Expr): AggregateFunction; * @return A new {@code AggregateFunction} representing the 'count' aggregation. */ export function count(fieldName: string): AggregateFunction; -export function count(value: Expr | string): AggregateFunction { +export function count(value: Expression | string): AggregateFunction { return fieldOrExpression(value).count(); } @@ -5357,7 +5748,7 @@ export function count(value: Expr | string): AggregateFunction { * @param expression The expression to sum up. * @return A new {@code AggregateFunction} representing the 'sum' aggregation. */ -export function sum(expression: Expr): AggregateFunction; +export function sum(expression: Expression): AggregateFunction; /** * @beta @@ -5373,7 +5764,7 @@ export function sum(expression: Expr): AggregateFunction; * @return A new {@code AggregateFunction} representing the 'sum' aggregation. */ export function sum(fieldName: string): AggregateFunction; -export function sum(value: Expr | string): AggregateFunction { +export function sum(value: Expression | string): AggregateFunction { return fieldOrExpression(value).sum(); } @@ -5384,13 +5775,13 @@ export function sum(value: Expr | string): AggregateFunction { * * ```typescript * // Calculate the average age of users - * avg(field("age")).as("averageAge"); + * average(field("age")).as("averageAge"); * ``` * * @param expression The expression representing the values to average. - * @return A new {@code AggregateFunction} representing the 'avg' aggregation. + * @return A new {@code AggregateFunction} representing the 'average' aggregation. */ -export function avg(expression: Expr): AggregateFunction; +export function average(expression: Expression): AggregateFunction; /** * @beta @@ -5399,15 +5790,15 @@ export function avg(expression: Expr): AggregateFunction; * * ```typescript * // Calculate the average age of users - * avg("age").as("averageAge"); + * average("age").as("averageAge"); * ``` * * @param fieldName The name of the field containing numeric values to average. - * @return A new {@code AggregateFunction} representing the 'avg' aggregation. + * @return A new {@code AggregateFunction} representing the 'average' aggregation. */ -export function avg(fieldName: string): AggregateFunction; -export function avg(value: Expr | string): AggregateFunction { - return fieldOrExpression(value).avg(); +export function average(fieldName: string): AggregateFunction; +export function average(value: Expression | string): AggregateFunction { + return fieldOrExpression(value).average(); } /** @@ -5423,7 +5814,7 @@ export function avg(value: Expr | string): AggregateFunction { * @param expression The expression to find the minimum value of. * @return A new {@code AggregateFunction} representing the 'min' aggregation. */ -export function minimum(expression: Expr): AggregateFunction; +export function minimum(expression: Expression): AggregateFunction; /** * @beta @@ -5438,7 +5829,7 @@ export function minimum(expression: Expr): AggregateFunction; * @return A new {@code AggregateFunction} representing the 'min' aggregation. */ export function minimum(fieldName: string): AggregateFunction; -export function minimum(value: Expr | string): AggregateFunction { +export function minimum(value: Expression | string): AggregateFunction { return fieldOrExpression(value).minimum(); } @@ -5455,7 +5846,7 @@ export function minimum(value: Expr | string): AggregateFunction { * @param expression The expression to find the maximum value of. * @return A new {@code AggregateFunction} representing the 'max' aggregation. */ -export function maximum(expression: Expr): AggregateFunction; +export function maximum(expression: Expression): AggregateFunction; /** * @beta @@ -5470,7 +5861,7 @@ export function maximum(expression: Expr): AggregateFunction; * @return A new {@code AggregateFunction} representing the 'max' aggregation. */ export function maximum(fieldName: string): AggregateFunction; -export function maximum(value: Expr | string): AggregateFunction { +export function maximum(value: Expression | string): AggregateFunction { return fieldOrExpression(value).maximum(); } @@ -5485,12 +5876,12 @@ export function maximum(value: Expr | string): AggregateFunction { * * @param fieldName The name of the field containing the first vector. * @param vector The other vector (as an array of doubles) or {@link VectorValue} to compare against. - * @return A new {@code Expr} representing the Cosine distance between the two vectors. + * @return A new {@code Expression} representing the Cosine distance between the two vectors. */ export function cosineDistance( fieldName: string, vector: number[] | VectorValue -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -5502,13 +5893,13 @@ export function cosineDistance( * ``` * * @param fieldName The name of the field containing the first vector. - * @param vectorExpression The other vector (represented as an Expr) to compare against. - * @return A new {@code Expr} representing the cosine distance between the two vectors. + * @param vectorExpression The other vector (represented as an Expression) to compare against. + * @return A new {@code Expression} representing the cosine distance between the two vectors. */ export function cosineDistance( fieldName: string, - vectorExpression: Expr -): FunctionExpr; + vectorExpression: Expression +): FunctionExpression; /** * @beta @@ -5519,14 +5910,14 @@ export function cosineDistance( * cosineDistance(field("location"), [37.7749, -122.4194]); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to compare against. + * @param vectorExpression The first vector (represented as an Expression) to compare against. * @param vector The other vector (as an array of doubles or VectorValue) to compare against. - * @return A new {@code Expr} representing the cosine distance between the two vectors. + * @return A new {@code Expression} representing the cosine distance between the two vectors. */ export function cosineDistance( - vectorExpression: Expr, + vectorExpression: Expression, vector: number[] | VectorValue -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -5537,18 +5928,18 @@ export function cosineDistance( * cosineDistance(field("userVector"), field("itemVector")); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to compare against. - * @param otherVectorExpression The other vector (represented as an Expr) to compare against. - * @return A new {@code Expr} representing the cosine distance between the two vectors. + * @param vectorExpression The first vector (represented as an Expression) to compare against. + * @param otherVectorExpression The other vector (represented as an Expression) to compare against. + * @return A new {@code Expression} representing the cosine distance between the two vectors. */ export function cosineDistance( - vectorExpression: Expr, - otherVectorExpression: Expr -): FunctionExpr; + vectorExpression: Expression, + otherVectorExpression: Expression +): FunctionExpression; export function cosineDistance( - expr: Expr | string, - other: Expr | number[] | firestore.VectorValue -): FunctionExpr { + expr: Expression | string, + other: Expression | number[] | firestore.VectorValue +): FunctionExpression { const expr1 = fieldOrExpression(expr); const expr2 = vectorToExpr(other); return expr1.cosineDistance(expr2); @@ -5565,12 +5956,12 @@ export function cosineDistance( * * @param fieldName The name of the field containing the first vector. * @param vector The other vector (as an array of doubles or VectorValue) to calculate with. - * @return A new {@code Expr} representing the dot product between the two vectors. + * @return A new {@code Expression} representing the dot product between the two vectors. */ export function dotProduct( fieldName: string, vector: number[] | VectorValue -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -5582,13 +5973,13 @@ export function dotProduct( * ``` * * @param fieldName The name of the field containing the first vector. - * @param vectorExpression The other vector (represented as an Expr) to calculate with. - * @return A new {@code Expr} representing the dot product between the two vectors. + * @param vectorExpression The other vector (represented as an Expression) to calculate with. + * @return A new {@code Expression} representing the dot product between the two vectors. */ export function dotProduct( fieldName: string, - vectorExpression: Expr -): FunctionExpr; + vectorExpression: Expression +): FunctionExpression; /** * @beta @@ -5599,14 +5990,14 @@ export function dotProduct( * dotProduct(field("features"), [0.5, 0.8, 0.2]); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to calculate with. + * @param vectorExpression The first vector (represented as an Expression) to calculate with. * @param vector The other vector (as an array of doubles or VectorValue) to calculate with. - * @return A new {@code Expr} representing the dot product between the two vectors. + * @return A new {@code Expression} representing the dot product between the two vectors. */ export function dotProduct( - vectorExpression: Expr, + vectorExpression: Expression, vector: number[] | VectorValue -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -5617,18 +6008,18 @@ export function dotProduct( * dotProduct(field("docVector1"), field("docVector2")); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to calculate with. - * @param otherVectorExpression The other vector (represented as an Expr) to calculate with. - * @return A new {@code Expr} representing the dot product between the two vectors. + * @param vectorExpression The first vector (represented as an Expression) to calculate with. + * @param otherVectorExpression The other vector (represented as an Expression) to calculate with. + * @return A new {@code Expression} representing the dot product between the two vectors. */ export function dotProduct( - vectorExpression: Expr, - otherVectorExpression: Expr -): FunctionExpr; + vectorExpression: Expression, + otherVectorExpression: Expression +): FunctionExpression; export function dotProduct( - expr: Expr | string, - other: Expr | number[] | VectorValue -): FunctionExpr { + expr: Expression | string, + other: Expression | number[] | VectorValue +): FunctionExpression { const expr1 = fieldOrExpression(expr); const expr2 = vectorToExpr(other); return expr1.dotProduct(expr2); @@ -5645,12 +6036,12 @@ export function dotProduct( * * @param fieldName The name of the field containing the first vector. * @param vector The other vector (as an array of doubles or VectorValue) to compare against. - * @return A new {@code Expr} representing the Euclidean distance between the two vectors. + * @return A new {@code Expression} representing the Euclidean distance between the two vectors. */ export function euclideanDistance( fieldName: string, vector: number[] | VectorValue -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -5662,13 +6053,13 @@ export function euclideanDistance( * ``` * * @param fieldName The name of the field containing the first vector. - * @param vectorExpression The other vector (represented as an Expr) to compare against. - * @return A new {@code Expr} representing the Euclidean distance between the two vectors. + * @param vectorExpression The other vector (represented as an Expression) to compare against. + * @return A new {@code Expression} representing the Euclidean distance between the two vectors. */ export function euclideanDistance( fieldName: string, - vectorExpression: Expr -): FunctionExpr; + vectorExpression: Expression +): FunctionExpression; /** * @beta @@ -5680,14 +6071,14 @@ export function euclideanDistance( * euclideanDistance(field("location"), [37.7749, -122.4194]); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to compare against. + * @param vectorExpression The first vector (represented as an Expression) to compare against. * @param vector The other vector (as an array of doubles or VectorValue) to compare against. - * @return A new {@code Expr} representing the Euclidean distance between the two vectors. + * @return A new {@code Expression} representing the Euclidean distance between the two vectors. */ export function euclideanDistance( - vectorExpression: Expr, + vectorExpression: Expression, vector: number[] | VectorValue -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -5698,18 +6089,18 @@ export function euclideanDistance( * euclideanDistance(field("pointA"), field("pointB")); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to compare against. - * @param otherVectorExpression The other vector (represented as an Expr) to compare against. - * @return A new {@code Expr} representing the Euclidean distance between the two vectors. + * @param vectorExpression The first vector (represented as an Expression) to compare against. + * @param otherVectorExpression The other vector (represented as an Expression) to compare against. + * @return A new {@code Expression} representing the Euclidean distance between the two vectors. */ export function euclideanDistance( - vectorExpression: Expr, - otherVectorExpression: Expr -): FunctionExpr; + vectorExpression: Expression, + otherVectorExpression: Expression +): FunctionExpression; export function euclideanDistance( - expr: Expr | string, - other: Expr | number[] | VectorValue -): FunctionExpr { + expr: Expression | string, + other: Expression | number[] | VectorValue +): FunctionExpression { const expr1 = fieldOrExpression(expr); const expr2 = vectorToExpr(other); return expr1.euclideanDistance(expr2); @@ -5725,9 +6116,9 @@ export function euclideanDistance( * ``` * * @param vectorExpression The expression representing the Firestore Vector. - * @return A new {@code Expr} representing the length of the array. + * @return A new {@code Expression} representing the length of the array. */ -export function vectorLength(vectorExpression: Expr): FunctionExpr; +export function vectorLength(vectorExpression: Expression): FunctionExpression; /** * @beta @@ -5739,10 +6130,10 @@ export function vectorLength(vectorExpression: Expr): FunctionExpr; * ``` * * @param fieldName The name of the field representing the Firestore Vector. - * @return A new {@code Expr} representing the length of the array. + * @return A new {@code Expression} representing the length of the array. */ -export function vectorLength(fieldName: string): FunctionExpr; -export function vectorLength(expr: Expr | string): FunctionExpr { +export function vectorLength(fieldName: string): FunctionExpression; +export function vectorLength(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).vectorLength(); } @@ -5757,9 +6148,9 @@ export function vectorLength(expr: Expr | string): FunctionExpr { * ``` * * @param expr The expression representing the number of microseconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ -export function unixMicrosToTimestamp(expr: Expr): FunctionExpr; +export function unixMicrosToTimestamp(expr: Expression): FunctionExpression; /** * @beta @@ -5772,10 +6163,12 @@ export function unixMicrosToTimestamp(expr: Expr): FunctionExpr; * ``` * * @param fieldName The name of the field representing the number of microseconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ -export function unixMicrosToTimestamp(fieldName: string): FunctionExpr; -export function unixMicrosToTimestamp(expr: Expr | string): FunctionExpr { +export function unixMicrosToTimestamp(fieldName: string): FunctionExpression; +export function unixMicrosToTimestamp( + expr: Expression | string +): FunctionExpression { return fieldOrExpression(expr).unixMicrosToTimestamp(); } @@ -5789,9 +6182,9 @@ export function unixMicrosToTimestamp(expr: Expr | string): FunctionExpr { * ``` * * @param expr The expression representing the timestamp. - * @return A new {@code Expr} representing the number of microseconds since epoch. + * @return A new {@code Expression} representing the number of microseconds since epoch. */ -export function timestampToUnixMicros(expr: Expr): FunctionExpr; +export function timestampToUnixMicros(expr: Expression): FunctionExpression; /** * @beta @@ -5803,10 +6196,12 @@ export function timestampToUnixMicros(expr: Expr): FunctionExpr; * ``` * * @param fieldName The name of the field representing the timestamp. - * @return A new {@code Expr} representing the number of microseconds since epoch. + * @return A new {@code Expression} representing the number of microseconds since epoch. */ -export function timestampToUnixMicros(fieldName: string): FunctionExpr; -export function timestampToUnixMicros(expr: Expr | string): FunctionExpr { +export function timestampToUnixMicros(fieldName: string): FunctionExpression; +export function timestampToUnixMicros( + expr: Expression | string +): FunctionExpression { return fieldOrExpression(expr).timestampToUnixMicros(); } @@ -5821,9 +6216,9 @@ export function timestampToUnixMicros(expr: Expr | string): FunctionExpr { * ``` * * @param expr The expression representing the number of milliseconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ -export function unixMillisToTimestamp(expr: Expr): FunctionExpr; +export function unixMillisToTimestamp(expr: Expression): FunctionExpression; /** * @beta @@ -5836,10 +6231,12 @@ export function unixMillisToTimestamp(expr: Expr): FunctionExpr; * ``` * * @param fieldName The name of the field representing the number of milliseconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ -export function unixMillisToTimestamp(fieldName: string): FunctionExpr; -export function unixMillisToTimestamp(expr: Expr | string): FunctionExpr { +export function unixMillisToTimestamp(fieldName: string): FunctionExpression; +export function unixMillisToTimestamp( + expr: Expression | string +): FunctionExpression { const normalizedExpr = fieldOrExpression(expr); return normalizedExpr.unixMillisToTimestamp(); } @@ -5854,9 +6251,9 @@ export function unixMillisToTimestamp(expr: Expr | string): FunctionExpr { * ``` * * @param expr The expression representing the timestamp. - * @return A new {@code Expr} representing the number of milliseconds since epoch. + * @return A new {@code Expression} representing the number of milliseconds since epoch. */ -export function timestampToUnixMillis(expr: Expr): FunctionExpr; +export function timestampToUnixMillis(expr: Expression): FunctionExpression; /** * @beta @@ -5868,10 +6265,12 @@ export function timestampToUnixMillis(expr: Expr): FunctionExpr; * ``` * * @param fieldName The name of the field representing the timestamp. - * @return A new {@code Expr} representing the number of milliseconds since epoch. + * @return A new {@code Expression} representing the number of milliseconds since epoch. */ -export function timestampToUnixMillis(fieldName: string): FunctionExpr; -export function timestampToUnixMillis(expr: Expr | string): FunctionExpr { +export function timestampToUnixMillis(fieldName: string): FunctionExpression; +export function timestampToUnixMillis( + expr: Expression | string +): FunctionExpression { const normalizedExpr = fieldOrExpression(expr); return normalizedExpr.timestampToUnixMillis(); } @@ -5887,9 +6286,9 @@ export function timestampToUnixMillis(expr: Expr | string): FunctionExpr { * ``` * * @param expr The expression representing the number of seconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ -export function unixSecondsToTimestamp(expr: Expr): FunctionExpr; +export function unixSecondsToTimestamp(expr: Expression): FunctionExpression; /** * @beta @@ -5902,10 +6301,12 @@ export function unixSecondsToTimestamp(expr: Expr): FunctionExpr; * ``` * * @param fieldName The name of the field representing the number of seconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ -export function unixSecondsToTimestamp(fieldName: string): FunctionExpr; -export function unixSecondsToTimestamp(expr: Expr | string): FunctionExpr { +export function unixSecondsToTimestamp(fieldName: string): FunctionExpression; +export function unixSecondsToTimestamp( + expr: Expression | string +): FunctionExpression { const normalizedExpr = fieldOrExpression(expr); return normalizedExpr.unixSecondsToTimestamp(); } @@ -5920,9 +6321,9 @@ export function unixSecondsToTimestamp(expr: Expr | string): FunctionExpr { * ``` * * @param expr The expression representing the timestamp. - * @return A new {@code Expr} representing the number of seconds since epoch. + * @return A new {@code Expression} representing the number of seconds since epoch. */ -export function timestampToUnixSeconds(expr: Expr): FunctionExpr; +export function timestampToUnixSeconds(expr: Expression): FunctionExpression; /** * @beta @@ -5934,10 +6335,12 @@ export function timestampToUnixSeconds(expr: Expr): FunctionExpr; * ``` * * @param fieldName The name of the field representing the timestamp. - * @return A new {@code Expr} representing the number of seconds since epoch. + * @return A new {@code Expression} representing the number of seconds since epoch. */ -export function timestampToUnixSeconds(fieldName: string): FunctionExpr; -export function timestampToUnixSeconds(expr: Expr | string): FunctionExpr { +export function timestampToUnixSeconds(fieldName: string): FunctionExpression; +export function timestampToUnixSeconds( + expr: Expression | string +): FunctionExpression { const normalizedExpr = fieldOrExpression(expr); return normalizedExpr.timestampToUnixSeconds(); } @@ -5954,13 +6357,13 @@ export function timestampToUnixSeconds(expr: Expr | string): FunctionExpr { * @param timestamp The expression representing the timestamp. * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. * @param amount The expression evaluates to amount of the unit. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ export function timestampAdd( - timestamp: Expr, - unit: Expr, - amount: Expr -): FunctionExpr; + timestamp: Expression, + unit: Expression, + amount: Expression +): FunctionExpression; /** * @beta @@ -5974,13 +6377,13 @@ export function timestampAdd( * @param timestamp The expression representing the timestamp. * @param unit The unit of time to add (e.g., "day", "hour"). * @param amount The amount of time to add. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ export function timestampAdd( - timestamp: Expr, + timestamp: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -5994,25 +6397,25 @@ export function timestampAdd( * @param fieldName The name of the field representing the timestamp. * @param unit The unit of time to add (e.g., "day", "hour"). * @param amount The amount of time to add. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ export function timestampAdd( fieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number -): FunctionExpr; +): FunctionExpression; export function timestampAdd( - timestamp: Expr | string, + timestamp: Expression | string, unit: - | Expr + | Expression | 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', - amount: Expr | number -): FunctionExpr { + amount: Expression | number +): FunctionExpression { const normalizedTimestamp = fieldOrExpression(timestamp); const normalizedUnit = valueToDefaultExpr(unit); const normalizedAmount = valueToDefaultExpr(amount); @@ -6025,19 +6428,19 @@ export function timestampAdd( * * ```typescript * // Subtract some duration determined by field 'unit' and 'amount' from the 'timestamp' field. - * timestampSub(field("timestamp"), field("unit"), field("amount")); + * timestampSubtract(field("timestamp"), field("unit"), field("amount")); * ``` * * @param timestamp The expression representing the timestamp. * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. * @param amount The expression evaluates to amount of the unit. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ -export function timestampSub( - timestamp: Expr, - unit: Expr, - amount: Expr -): FunctionExpr; +export function timestampSubtract( + timestamp: Expression, + unit: Expression, + amount: Expression +): FunctionExpression; /** * @beta @@ -6045,19 +6448,19 @@ export function timestampSub( * * ```typescript * // Subtract 1 day from the 'timestamp' field. - * timestampSub(field("timestamp"), "day", 1); + * timestampSubtract(field("timestamp"), "day", 1); * ``` * * @param timestamp The expression representing the timestamp. * @param unit The unit of time to subtract (e.g., "day", "hour"). * @param amount The amount of time to subtract. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ -export function timestampSub( - timestamp: Expr, +export function timestampSubtract( + timestamp: Expression, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number -): FunctionExpr; +): FunctionExpression; /** * @beta @@ -6065,35 +6468,54 @@ export function timestampSub( * * ```typescript * // Subtract 1 day from the 'timestamp' field. - * timestampSub("timestamp", "day", 1); + * timestampSubtract("timestamp", "day", 1); * ``` * * @param fieldName The name of the field representing the timestamp. * @param unit The unit of time to subtract (e.g., "day", "hour"). * @param amount The amount of time to subtract. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ -export function timestampSub( +export function timestampSubtract( fieldName: string, unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number -): FunctionExpr; -export function timestampSub( - timestamp: Expr | string, +): FunctionExpression; +export function timestampSubtract( + timestamp: Expression | string, unit: - | Expr + | Expression | 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', - amount: Expr | number -): FunctionExpr { + amount: Expression | number +): FunctionExpression { const normalizedTimestamp = fieldOrExpression(timestamp); const normalizedUnit = valueToDefaultExpr(unit); const normalizedAmount = valueToDefaultExpr(amount); - return normalizedTimestamp.timestampSub(normalizedUnit, normalizedAmount); + return normalizedTimestamp.timestampSubtract( + normalizedUnit, + normalizedAmount + ); +} + +/** + * @beta + * + * Creates an expression that evaluates to the current server timestamp. + * + * ```typescript + * // Get the current server timestamp + * currentTimestamp() + * ``` + * + * @return A new Expression representing the current server timestamp. + */ +export function currentTimestamp(): FunctionExpression { + return new FunctionExpression('current_timestamp', []); } /** @@ -6103,20 +6525,20 @@ export function timestampSub( * ```typescript * // Check if the 'age' field is greater than 18 AND the 'city' field is "London" AND * // the 'status' field is "active" - * const condition = and(gt("age", 18), eq("city", "London"), eq("status", "active")); + * const condition = and(greaterThan("age", 18), equal("city", "London"), equal("status", "active")); * ``` * * @param first The first filter condition. * @param second The second filter condition. * @param more Additional filter conditions to 'AND' together. - * @return A new {@code Expr} representing the logical 'AND' operation. + * @return A new {@code Expression} representing the logical 'AND' operation. */ export function and( - first: BooleanExpr, - second: BooleanExpr, - ...more: BooleanExpr[] -): BooleanExpr { - return new BooleanExpr('and', [first, second, ...more]); + first: BooleanExpression, + second: BooleanExpression, + ...more: BooleanExpression[] +): BooleanExpression { + return new BooleanExpression('and', [first, second, ...more]); } /** @@ -6126,20 +6548,20 @@ export function and( * ```typescript * // Check if the 'age' field is greater than 18 OR the 'city' field is "London" OR * // the 'status' field is "active" - * const condition = or(gt("age", 18), eq("city", "London"), eq("status", "active")); + * const condition = or(greaterThan("age", 18), equal("city", "London"), equal("status", "active")); * ``` * * @param first The first filter condition. * @param second The second filter condition. * @param more Additional filter conditions to 'OR' together. - * @return A new {@code Expr} representing the logical 'OR' operation. + * @return A new {@code Expression} representing the logical 'OR' operation. */ export function or( - first: BooleanExpr, - second: BooleanExpr, - ...more: BooleanExpr[] -): BooleanExpr { - return new BooleanExpr('or', [first, second, ...more]); + first: BooleanExpression, + second: BooleanExpression, + ...more: BooleanExpression[] +): BooleanExpression { + return new BooleanExpression('or', [first, second, ...more]); } /** @@ -6153,9 +6575,9 @@ export function or( * * @param base The expression to raise to the power of the exponent. * @param exponent The expression to raise the base to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ -export function pow(base: Expr, exponent: Expr): FunctionExpr; +export function pow(base: Expression, exponent: Expression): FunctionExpression; /** * @beta @@ -6168,9 +6590,9 @@ export function pow(base: Expr, exponent: Expr): FunctionExpr; * * @param base The expression to raise to the power of the exponent. * @param exponent The constant value to raise the base to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ -export function pow(base: Expr, exponent: number): FunctionExpr; +export function pow(base: Expression, exponent: number): FunctionExpression; /** * @beta @@ -6183,9 +6605,9 @@ export function pow(base: Expr, exponent: number): FunctionExpr; * * @param base The name of the field to raise to the power of the exponent. * @param exponent The expression to raise the base to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ -export function pow(base: string, exponent: Expr): FunctionExpr; +export function pow(base: string, exponent: Expression): FunctionExpression; /** * @beta @@ -6198,13 +6620,13 @@ export function pow(base: string, exponent: Expr): FunctionExpr; * * @param base The name of the field to raise to the power of the exponent. * @param exponent The constant value to raise the base to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ -export function pow(base: string, exponent: number): FunctionExpr; +export function pow(base: string, exponent: number): FunctionExpression; export function pow( - base: Expr | string, - exponent: Expr | number -): FunctionExpr { + base: Expression | string, + exponent: Expression | number +): FunctionExpression { return fieldOrExpression(base).pow(exponent as number); } @@ -6218,9 +6640,9 @@ export function pow( * ``` * * @param fieldName The name of the field to round. - * @return A new `Expr` representing the rounded value. + * @return A new `Expression` representing the rounded value. */ -export function round(fieldName: string): FunctionExpr; +export function round(fieldName: string): FunctionExpression; /** * @beta @@ -6232,11 +6654,53 @@ export function round(fieldName: string): FunctionExpr; * ``` * * @param expression An expression evaluating to a numeric value, which will be rounded. + * @return A new `Expression` representing the rounded value. + */ +export function round(expression: Expression): FunctionExpression; +/** + * @beta + * Creates an expression that rounds a numeric value to the specified number of decimal places. + * + * ```typescript + * // Round the value of the 'price' field to two decimal places. + * round("price", 2); + * ``` + * + * @param fieldName The name of the field to round. + * @param decimalPlaces A constant or expression specifying the rounding precision in decimal places. + * @return A new `Expr` representing the rounded value. + */ +export function round( + fieldName: string, + decimalPlaces: number | Expression +): FunctionExpression; + +/** + * @beta + * Creates an expression that rounds a numeric value to the specified number of decimal places. + * + * ```typescript + * // Round the value of the 'price' field to two decimal places. + * round(field("price"), constant(2)); + * ``` + * + * @param expression An expression evaluating to a numeric value, which will be rounded. + * @param decimalPlaces A constant or expression specifying the rounding precision in decimal places. * @return A new `Expr` representing the rounded value. */ -export function round(expression: Expr): FunctionExpr; -export function round(expr: Expr | string): FunctionExpr { - return fieldOrExpression(expr).round(); +export function round( + expression: Expression, + decimalPlaces: number | Expression +): FunctionExpression; +export function round( + expr: Expression | string, + decimalPlaces?: number | Expression +): FunctionExpression { + if (decimalPlaces === undefined) { + return fieldOrExpression(expr).round(); + } else { + return fieldOrExpression(expr).round(valueToDefaultExpr(decimalPlaces)); + } } /** @@ -6249,9 +6713,9 @@ export function round(expr: Expr | string): FunctionExpr { * ``` * * @param fieldName The name of the field to get the collection ID from. - * @return A new {@code Expr} representing the collectionId operation. + * @return A new {@code Expression} representing the collectionId operation. */ -export function collectionId(fieldName: string): FunctionExpr; +export function collectionId(fieldName: string): FunctionExpression; /** * @beta @@ -6263,10 +6727,10 @@ export function collectionId(fieldName: string): FunctionExpr; * ``` * * @param expression An expression evaluating to a path, which the collection ID will be extracted from. - * @return A new {@code Expr} representing the collectionId operation. + * @return A new {@code Expression} representing the collectionId operation. */ -export function collectionId(expression: Expr): FunctionExpr; -export function collectionId(expr: Expr | string): FunctionExpr { +export function collectionId(expression: Expression): FunctionExpression; +export function collectionId(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).collectionId(); } @@ -6283,9 +6747,9 @@ export function collectionId(expr: Expr | string): FunctionExpr { * ``` * * @param fieldName The name of the field to calculate the length of. - * @return A new `Expr` representing the length of the string, array, map, vector, or bytes. + * @return A new `Expression` representing the length of the string, array, map, vector, or bytes. */ -export function length(fieldName: string): FunctionExpr; +export function length(fieldName: string): FunctionExpression; /** * @beta @@ -6300,10 +6764,10 @@ export function length(fieldName: string): FunctionExpr; * ``` * * @param expression An expression evaluating to a string, array, map, vector, or bytes, which the length will be calculated for. - * @return A new `Expr` representing the length of the string, array, map, vector, or bytes. + * @return A new `Expression` representing the length of the string, array, map, vector, or bytes. */ -export function length(expression: Expr): FunctionExpr; -export function length(expr: Expr | string): FunctionExpr { +export function length(expression: Expression): FunctionExpression; +export function length(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).length(); } @@ -6317,9 +6781,9 @@ export function length(expr: Expr | string): FunctionExpr { * ``` * * @param fieldName The name of the field to compute the natural logarithm of. - * @return A new `Expr` representing the natural logarithm of the numeric value. + * @return A new `Expression` representing the natural logarithm of the numeric value. */ -export function ln(fieldName: string): FunctionExpr; +export function ln(fieldName: string): FunctionExpression; /** * @beta @@ -6331,132 +6795,363 @@ export function ln(fieldName: string): FunctionExpr; * ``` * * @param expression An expression evaluating to a numeric value, which the natural logarithm will be computed for. - * @return A new `Expr` representing the natural logarithm of the numeric value. + * @return A new `Expression` representing the natural logarithm of the numeric value. */ -export function ln(expression: Expr): FunctionExpr; -export function ln(expr: Expr | string): FunctionExpr { +export function ln(expression: Expression): FunctionExpression; +export function ln(expr: Expression | string): FunctionExpression { return fieldOrExpression(expr).ln(); } /** * @beta - * Creates an expression that computes the logarithm of an expression to a given base. + * Creates an expression that computes the square root of a numeric value. + * + * ```typescript + * // Compute the square root of the 'value' field. + * sqrt(field("value")); + * ``` + * + * @param expression An expression evaluating to a numeric value, which the square root will be computed for. + * @return A new {@code Expression} representing the square root of the numeric value. + */ +export function sqrt(expression: Expression): FunctionExpression; +/** + * @beta + * Creates an expression that computes the square root of a numeric value. + * + * ```typescript + * // Compute the square root of the 'value' field. + * sqrt("value"); + * ``` + * + * @param fieldName The name of the field to compute the square root of. + * @return A new {@code Expression} representing the square root of the numeric value. + */ +export function sqrt(fieldName: string): FunctionExpression; +export function sqrt(expr: Expression | string): FunctionExpression { + return fieldOrExpression(expr).sqrt(); +} + +/** + * @beta + * Creates an expression that reverses a string. * * ```typescript - * // Compute the logarithm of the 'value' field with base 10. - * log(field("value"), 10); + * // Reverse the value of the 'myString' field. + * stringReverse(field("myString")); * ``` * - * @param expression An expression evaluating to a numeric value, which the logarithm will be computed for. - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @param stringExpression An expression evaluating to a string value, which will be reversed. + * @return A new {@code Expression} representing the reversed string. */ -export function log(expression: Expr, base: number): FunctionExpr; +export function stringReverse(stringExpression: Expression): FunctionExpression; + /** * @beta - * Creates an expression that computes the logarithm of an expression to a given base. + * Creates an expression that reverses a string value in the specified field. * * ```typescript - * // Compute the logarithm of the 'value' field with the base in the 'base' field. - * log(field("value"), field("base")); + * // Reverse the value of the 'myString' field. + * stringReverse("myString"); * ``` * - * @param expression An expression evaluating to a numeric value, which the logarithm will be computed for. - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @param field The name of the field representing the string to reverse. + * @return A new {@code Expression} representing the reversed string. */ -export function log(expression: Expr, base: Expr): FunctionExpr; +export function stringReverse(field: string): FunctionExpression; +export function stringReverse(expr: Expression | string): FunctionExpression { + return fieldOrExpression(expr).stringReverse(); +} + /** * @beta - * Creates an expression that computes the logarithm of a field to a given base. + * Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed. * * ```typescript - * // Compute the logarithm of the 'value' field with base 10. - * log("value", 10); + * // Concatenate the 'firstName' and 'lastName' fields with a space in between. + * concat(field("firstName"), " ", field("lastName")) * ``` * - * @param fieldName The name of the field to compute the logarithm of. - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @param first The first expressions to concatenate. + * @param second The second literal or expression to concatenate. + * @param others Additional literals or expressions to concatenate. + * @return A new `Expression` representing the concatenation. */ -export function log(fieldName: string, base: number): FunctionExpr; +export function concat( + first: Expression, + second: Expression | unknown, + ...others: Array +): FunctionExpression; + /** * @beta - * Creates an expression that computes the logarithm of a field to a given base. + * Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed. * * ```typescript - * // Compute the logarithm of the 'value' field with the base in the 'base' field. - * log("value", field("base")); + * // Concatenate a field with a literal string. + * concat(field("firstName"), "Doe") * ``` * - * @param fieldName The name of the field to compute the logarithm of. - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @param fieldName The name of a field to concatenate. + * @param second The second literal or expression to concatenate. + * @param others Additional literal or expressions to concatenate. + * @return A new `Expression` representing the concatenation. + */ +export function concat( + fieldName: string, + second: Expression | unknown, + ...others: Array +): FunctionExpression; + +export function concat( + fieldNameOrExpression: string | Expression, + second: Expression | unknown, + ...others: Array +): FunctionExpression { + return fieldOrExpression(fieldNameOrExpression).concat( + valueToDefaultExpr(second), + ...others.map(valueToDefaultExpr) + ); +} + +/** + * @beta + * Creates an expression that computes the absolute value of a numeric value. + * + * @param expr The expression to compute the absolute value of. + * @return A new {@code Expr} representing the absolute value of the numeric value. + */ +export function abs(expr: Expression): FunctionExpression; + +/** + * @beta + * Creates an expression that computes the absolute value of a numeric value. + * + * @param fieldName The field to compute the absolute value of. + * @return A new {@code Expr} representing the absolute value of the numeric value. */ -export function log(fieldName: string, base: Expr): FunctionExpr; -export function log(expr: Expr | string, base: number | Expr): FunctionExpr { - return fieldOrExpression(expr).log(valueToDefaultExpr(base)); +export function abs(fieldName: string): FunctionExpression; +export function abs(expr: Expression | string): FunctionExpression { + return fieldOrExpression(expr).abs(); } /** * @beta - * Creates an expression that computes the square root of a numeric value. + * Creates an expression that returns the `elseExpr` argument if `ifExpr` is absent, else return + * the result of the `ifExpr` argument evaluation. * * ```typescript - * // Compute the square root of the 'value' field. - * sqrt(field("value")); + * // Returns the value of the optional field 'optional_field', or returns 'default_value' + * // if the field is absent. + * ifAbsent(field("optional_field"), constant("default_value")) * ``` * - * @param expression An expression evaluating to a numeric value, which the square root will be computed for. - * @return A new {@code Expr} representing the square root of the numeric value. + * @param ifExpr The expression to check for absence. + * @param elseExpr The expression that will be evaluated and returned if [ifExpr] is absent. + * @return A new Expression representing the ifAbsent operation. */ -export function sqrt(expression: Expr): FunctionExpr; +export function ifAbsent(ifExpr: Expression, elseExpr: Expression): Expression; + /** * @beta - * Creates an expression that computes the square root of a numeric value. + * Creates an expression that returns the `elseValue` argument if `ifExpr` is absent, else + * return the result of the `ifExpr` argument evaluation. * * ```typescript - * // Compute the square root of the 'value' field. - * sqrt("value"); + * // Returns the value of the optional field 'optional_field', or returns 'default_value' + * // if the field is absent. + * ifAbsent(field("optional_field"), "default_value") * ``` * - * @param fieldName The name of the field to compute the square root of. - * @return A new {@code Expr} representing the square root of the numeric value. + * @param ifExpr The expression to check for absence. + * @param elseValue The value that will be returned if `ifExpr` evaluates to an absent value. + * @return A new [Expression] representing the ifAbsent operation. */ -export function sqrt(fieldName: string): FunctionExpr; -export function sqrt(expr: Expr | string): FunctionExpr { - return fieldOrExpression(expr).sqrt(); +export function ifAbsent(ifExpr: Expression, elseValue: unknown): Expression; + +/** + * @beta + * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is absent, else + * return the value of the field. + * + * ```typescript + * // Returns the value of the optional field 'optional_field', or returns the value of + * // 'default_field' if 'optional_field' is absent. + * ifAbsent("optional_field", field("default_field")) + * ``` + * + * @param ifFieldName The field to check for absence. + * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is + * absent. + * @return A new Expression representing the ifAbsent operation. + */ +export function ifAbsent(ifFieldName: string, elseExpr: Expression): Expression; + +/** + * @beta + * Creates an expression that returns the `elseValue` argument if `ifFieldName` is absent, else + * return the value of the field. + * + * ```typescript + * // Returns the value of the optional field 'optional_field', or returns 'default_value' + * // if the field is absent. + * ifAbsent("optional_field", "default_value") + * ``` + * + * @param ifFieldName The field to check for absence. + * @param elseValue The value that will be returned if [ifFieldName] is absent. + * @return A new Expression representing the ifAbsent operation. + */ +export function ifAbsent( + ifFieldName: string | Expression, + elseValue: Expression | unknown +): Expression; +export function ifAbsent( + fieldNameOrExpression: string | Expression, + elseValue: Expression | unknown +): Expression { + return fieldOrExpression(fieldNameOrExpression).ifAbsent( + valueToDefaultExpr(elseValue) + ); } /** * @beta - * Creates an expression that reverses a string. + * Creates an expression that joins the elements of an array into a string. * * ```typescript - * // Reverse the value of the 'myString' field. - * strReverse(field("myString")); + * // Join the elements of the 'tags' field with a comma and space. + * join("tags", ", ") * ``` * - * @param stringExpression An expression evaluating to a string value, which will be reversed. - * @return A new {@code Expr} representing the reversed string. + * @param arrayFieldName The name of the field containing the array. + * @param delimiter The string to use as a delimiter. + * @return A new Expression representing the join operation. */ -export function strReverse(stringExpression: Expr): FunctionExpr; +export function join(arrayFieldName: string, delimiter: string): Expression; /** * @beta - * Creates an expression that reverses a string value in the specified field. + * Creates an expression that joins the elements of an array into a string. * * ```typescript - * // Reverse the value of the 'myString' field. - * strReverse("myString"); + * // Join an array of string using the delimiter from the 'separator' field. + * join(array(['foo', 'bar']), field("separator")) * ``` * - * @param field The name of the field representing the string to reverse. - * @return A new {@code Expr} representing the reversed string. + * @param arrayExpression An expression that evaluates to an array. + * @param delimiterExpression The expression that evaluates to the delimiter string. + * @return A new Expression representing the join operation. + */ +export function join( + arrayExpression: Expression, + delimiterExpression: Expression +): Expression; + +/** + * @beta + * Creates an expression that joins the elements of an array into a string. + * + * ```typescript + * // Join the elements of the 'tags' field with a comma and space. + * join(field("tags"), ", ") + * ``` + * + * @param arrayExpression An expression that evaluates to an array. + * @param delimiter The string to use as a delimiter. + * @return A new Expression representing the join operation. + */ +export function join( + arrayExpression: Expression, + delimiter: string +): Expression; + +/** + * @beta + * Creates an expression that joins the elements of an array into a string. + * + * ```typescript + * // Join the elements of the 'tags' field with the delimiter from the 'separator' field. + * join('tags', field("separator")) + * ``` + * + * @param arrayFieldName The name of the field containing the array. + * @param delimiterExpression The expression that evaluates to the delimiter string. + * @return A new Expression representing the join operation. + */ +export function join( + arrayFieldName: string, + delimiterExpression: Expression +): Expression; +export function join( + fieldNameOrExpression: string | Expression, + delimiterValueOrExpression: Expression | string +): Expression { + return fieldOrExpression(fieldNameOrExpression).join( + valueToDefaultExpr(delimiterValueOrExpression) + ); +} + +/** + * @beta + * Creates an expression that computes the base-10 logarithm of a numeric value. + * + * ```typescript + * // Compute the base-10 logarithm of the 'value' field. + * log10("value"); + * ``` + * + * @param fieldName The name of the field to compute the base-10 logarithm of. + * @return A new `Expr` representing the base-10 logarithm of the numeric value. + */ +export function log10(fieldName: string): FunctionExpression; + +/** + * @beta + * Creates an expression that computes the base-10 logarithm of a numeric value. + * + * ```typescript + * // Compute the base-10 logarithm of the 'value' field. + * log10(field("value")); + * ``` + * + * @param expression An expression evaluating to a numeric value, which the base-10 logarithm will be computed for. + * @return A new `Expr` representing the base-10 logarithm of the numeric value. + */ +export function log10(expression: Expression): FunctionExpression; +export function log10(expr: Expression | string): FunctionExpression { + return fieldOrExpression(expr).log10(); +} + +/** + * @beta + * Creates an expression that computes the sum of the elements in an array. + * + * ```typescript + * // Compute the sum of the elements in the 'scores' field. + * arraySum("scores"); + * ``` + * + * @param fieldName The name of the field to compute the sum of. + * @return A new `Expr` representing the sum of the elements in the array. + */ +export function arraySum(fieldName: string): FunctionExpression; + +/** + * @beta + * Creates an expression that computes the sum of the elements in an array. + * + * ```typescript + * // Compute the sum of the elements in the 'scores' field. + * arraySum(field("scores")); + * ``` + * + * @param expression An expression evaluating to a numeric array, which the sum will be computed for. + * @return A new `Expr` representing the sum of the elements in the array. */ -export function strReverse(field: string): FunctionExpr; -export function strReverse(expr: Expr | string): FunctionExpr { - return fieldOrExpression(expr).strReverse(); +export function arraySum(expression: Expression): FunctionExpression; +export function arraySum(expr: Expression | string): FunctionExpression { + return fieldOrExpression(expr).arraySum(); } // TODO(new-expression): Add new top-level expression function definitions above this line @@ -6474,7 +7169,7 @@ export function strReverse(expr: Expr | string): FunctionExpr { * @param expr The expression to create an ascending ordering for. * @return A new `Ordering` for ascending sorting. */ -export function ascending(expr: Expr): Ordering; +export function ascending(expr: Expression): Ordering; /** * @beta @@ -6490,7 +7185,7 @@ export function ascending(expr: Expr): Ordering; * @return A new `Ordering` for ascending sorting. */ export function ascending(fieldName: string): Ordering; -export function ascending(field: Expr | string): Ordering { +export function ascending(field: Expression | string): Ordering { return new Ordering(fieldOrExpression(field), 'ascending'); } @@ -6507,7 +7202,7 @@ export function ascending(field: Expr | string): Ordering { * @param expr The expression to create a descending ordering for. * @return A new `Ordering` for descending sorting. */ -export function descending(expr: Expr): Ordering; +export function descending(expr: Expression): Ordering; /** * @beta @@ -6523,7 +7218,7 @@ export function descending(expr: Expr): Ordering; * @return A new `Ordering` for descending sorting. */ export function descending(fieldName: string): Ordering; -export function descending(field: Expr | string): Ordering { +export function descending(field: Expression | string): Ordering { return new Ordering(fieldOrExpression(field), 'descending'); } @@ -6535,7 +7230,7 @@ export function descending(field: Expr | string): Ordering { */ export class Ordering implements HasUserData { constructor( - readonly expr: Expr, + readonly expr: Expression, readonly direction: 'ascending' | 'descending' ) {} @@ -6554,7 +7249,7 @@ export class Ordering implements HasUserData { * @internal */ _toProto(serializer: Serializer): api.IValue { - const expr = this.expr as Expr; + const expr = this.expr as Expression; return { mapValue: { fields: { @@ -6573,6 +7268,6 @@ export class Ordering implements HasUserData { * @internal */ _validateUserData(ignoreUndefinedProperties: boolean): void { - (this.expr as Expr)._validateUserData(ignoreUndefinedProperties); + (this.expr as Expression)._validateUserData(ignoreUndefinedProperties); } } diff --git a/dev/src/pipelines/index.ts b/dev/src/pipelines/index.ts index 23c7a5791..a7ccc9cec 100644 --- a/dev/src/pipelines/index.ts +++ b/dev/src/pipelines/index.ts @@ -24,46 +24,45 @@ export { arrayContains, arrayContainsAny, arrayReverse, - avg, - eq, + average, + equal, ceil, exp, floor, - gt, + greaterThan, like, - lt, - neq, + lessThan, + notEqual, ascending, not, or, regexContains, regexMatch, startsWith, - strConcat, + stringConcat, subtract, cosineDistance, countDistinct, dotProduct, euclideanDistance, mapGet, - lte, - eqAny, + lessThanOrEqual, + equalAny, map, array, field, xor, AggregateFunction, - rand, arrayGet, add, - BooleanExpr, - Expr, - FunctionExpr, + BooleanExpression, + Expression, + FunctionExpression, minimum, count, countIf, arrayLength, - strContains, + stringContains, charLength, divide, mod, @@ -72,16 +71,12 @@ export { toUpper, toLower, vectorLength, - isNotNan, exists, - isNotNull, isAbsent, ifError, isError, - isNan, substring, documentId, - isNull, arrayContainsAll, constant, Field, @@ -89,22 +84,22 @@ export { sum, maximum, descending, - gte, + greaterThanOrEqual, multiply, - cond, + conditional, Ordering, AliasedAggregate, endsWith, - AliasedExpr, + AliasedExpression, mapMerge, mapRemove, byteLength, logicalMaximum, logicalMinimum, - notEqAny, + notEqualAny, countAll, timestampAdd, - timestampSub, + timestampSubtract, timestampToUnixMicros, timestampToUnixSeconds, unixMicrosToTimestamp, @@ -115,9 +110,16 @@ export { collectionId, length, ln, - log, round, sqrt, - strReverse, + stringReverse, + abs, + arraySum, + ifAbsent, + log10, + concat, + join, + currentTimestamp, + arrayConcat, // TODO(new-expression): Add new expression exports above this line } from './expression'; diff --git a/dev/src/pipelines/pipeline-util.ts b/dev/src/pipelines/pipeline-util.ts index 9e8dab455..31455bd75 100644 --- a/dev/src/pipelines/pipeline-util.ts +++ b/dev/src/pipelines/pipeline-util.ts @@ -27,7 +27,7 @@ import Firestore, { VectorValue, } from '../index'; import {logger} from '../logger'; -import {QualifiedResourcePath} from '../path'; +import {FieldPath, QualifiedResourcePath} from '../path'; import {CompositeFilterInternal} from '../reference/composite-filter-internal'; import {NOOP_MESSAGE} from '../reference/constants'; import {FieldFilterInternal} from '../reference/field-filter-internal'; @@ -50,8 +50,8 @@ import { import api = protos.google.firestore.v1; import { - Expr, - BooleanExpr, + Expression, + BooleanExpression, and, or, field as createField, @@ -61,8 +61,8 @@ import { Constant, field, Ordering, - gt, - lt, + greaterThan, + lessThan, Field, AggregateFunction, } from './expression'; @@ -440,9 +440,9 @@ export function whereConditionsFromCursor( cursor: QueryCursor, orderings: Ordering[], position: 'before' | 'after' -): BooleanExpr { +): BooleanExpression { // The filterFunc is either greater than or less than - const filterFunc = position === 'before' ? lt : gt; + const filterFunc = position === 'before' ? lessThan : greaterThan; const cursors = cursor.values.map(value => Constant._fromProto(value)); const size = cursors.length; @@ -450,14 +450,17 @@ export function whereConditionsFromCursor( let value = cursors[size - 1]; // Add condition for last bound - let condition: BooleanExpr = filterFunc(field, value); + let condition: BooleanExpression = filterFunc(field, value); if ( (position === 'after' && cursor.before) || (position === 'before' && !cursor.before) ) { // When the cursor bound is inclusive, then the last bound // can be equal to the value, otherwise it's not equal - condition = or(condition, field.eq(value) as unknown as BooleanExpr); + condition = or( + condition, + field.equal(value) as unknown as BooleanExpression + ); } // Iterate backwards over the remaining bounds, adding @@ -467,11 +470,11 @@ export function whereConditionsFromCursor( value = cursors[i]; // For each field in the orderings, the condition is either - // a) lt|gt the cursor value, - // b) or equal the cursor value and lt|gt the cursor values for other fields + // a) lessThan|greaterThan the cursor value, + // b) or equal the cursor value and lessThan|greaterThan the cursor values for other fields condition = or( filterFunc(field, value), - and(field.eq(value) as unknown as BooleanExpr, condition) + and(field.equal(value) as unknown as BooleanExpression, condition) ); } @@ -491,53 +494,40 @@ export function reverseOrderings(orderings: Ordering[]): Ordering[] { export function toPipelineBooleanExpr( f: FilterInternal, serializer: Serializer -): BooleanExpr { +): BooleanExpression { if (f instanceof FieldFilterInternal) { const field = createField(f.field); - if (f.isNanChecking()) { - if (f.nanOp() === 'IS_NAN') { - return and(field.exists(), field.isNan()); - } else { - return and(field.exists(), field.isNotNan()); + + // Comparison filters + const value = isFirestoreValue(f.value) + ? f.value + : serializer.encodeValue(f.value); + switch (f.op) { + case 'LESS_THAN': + return and(field.exists(), field.lessThan(value)); + case 'LESS_THAN_OR_EQUAL': + return and(field.exists(), field.lessThanOrEqual(value)); + case 'GREATER_THAN': + return and(field.exists(), field.greaterThan(value)); + case 'GREATER_THAN_OR_EQUAL': + return and(field.exists(), field.greaterThanOrEqual(value)); + case 'EQUAL': + return and(field.exists(), field.equal(value)); + case 'NOT_EQUAL': + return and(field.exists(), field.notEqual(value)); + case 'ARRAY_CONTAINS': + return and(field.exists(), field.arrayContains(value)); + case 'IN': { + const values = value?.arrayValue?.values?.map(val => constant(val)); + return and(field.exists(), field.equalAny(values!)); } - } else if (f.isNullChecking()) { - if (f.nullOp() === 'IS_NULL') { - return and(field.exists(), field.isNull()); - } else { - return and(field.exists(), field.isNotNull()); + case 'ARRAY_CONTAINS_ANY': { + const values = value?.arrayValue?.values?.map(val => constant(val)); + return and(field.exists(), field.arrayContainsAny(values!)); } - } else { - // Comparison filters - const value = isFirestoreValue(f.value) - ? f.value - : serializer.encodeValue(f.value); - switch (f.op) { - case 'LESS_THAN': - return and(field.exists(), field.lt(value)); - case 'LESS_THAN_OR_EQUAL': - return and(field.exists(), field.lte(value)); - case 'GREATER_THAN': - return and(field.exists(), field.gt(value)); - case 'GREATER_THAN_OR_EQUAL': - return and(field.exists(), field.gte(value)); - case 'EQUAL': - return and(field.exists(), field.eq(value)); - case 'NOT_EQUAL': - return and(field.exists(), field.neq(value)); - case 'ARRAY_CONTAINS': - return and(field.exists(), field.arrayContains(value)); - case 'IN': { - const values = value?.arrayValue?.values?.map(val => constant(val)); - return and(field.exists(), field.eqAny(values!)); - } - case 'ARRAY_CONTAINS_ANY': { - const values = value?.arrayValue?.values?.map(val => constant(val)); - return and(field.exists(), field.arrayContainsAny(values!)); - } - case 'NOT_IN': { - const values = value?.arrayValue?.values?.map(val => constant(val)); - return and(field.exists(), field.notEqAny(values!)); - } + case 'NOT_IN': { + const values = value?.arrayValue?.values?.map(val => constant(val)); + return and(field.exists(), field.notEqualAny(values!)); } } } else if (f instanceof CompositeFilterInternal) { @@ -575,7 +565,9 @@ export function isSelectable( ): val is firestore.Pipelines.Selectable { const candidate = val as firestore.Pipelines.Selectable; return ( - candidate.selectable && isString(candidate.alias) && isExpr(candidate.expr) + candidate.selectable && + isString(candidate._alias) && + isExpr(candidate._expr) ); } @@ -593,19 +585,19 @@ export function isAliasedAggregate( ): val is firestore.Pipelines.AliasedAggregate { const candidate = val as firestore.Pipelines.AliasedAggregate; return ( - isString(candidate.alias) && - candidate.aggregate instanceof AggregateFunction + isString(candidate._alias) && + candidate._aggregate instanceof AggregateFunction ); } -export function isExpr(val: unknown): val is firestore.Pipelines.Expr { - return val instanceof Expr; +export function isExpr(val: unknown): val is firestore.Pipelines.Expression { + return val instanceof Expression; } export function isBooleanExpr( val: unknown -): val is firestore.Pipelines.BooleanExpr { - return val instanceof BooleanExpr; +): val is firestore.Pipelines.BooleanExpression { + return val instanceof BooleanExpression; } export function isField(val: unknown): val is firestore.Pipelines.Field { @@ -623,19 +615,19 @@ export function isCollectionReference( } /** - * Converts a value to an Expr, Returning either a Constant, MapFunction, + * Converts a value to an Expression, Returning either a Constant, MapFunction, * ArrayFunction, or the input itself (if it's already an expression). * * @private * @internal * @param value */ -export function valueToDefaultExpr(value: unknown): Expr { - let result: Expr | undefined; +export function valueToDefaultExpr(value: unknown): Expression { + let result: Expression | undefined; if (isFirestoreValue(value)) { return constant(value); } - if (value instanceof Expr) { + if (value instanceof Expression) { return value; } else if (isPlainObject(value)) { result = map(value as Record); @@ -651,7 +643,7 @@ export function valueToDefaultExpr(value: unknown): Expr { } /** - * Converts a value to an Expr, Returning either a Constant, MapFunction, + * Converts a value to an Expression, Returning either a Constant, MapFunction, * ArrayFunction, or the input itself (if it's already an expression). * * @private @@ -659,9 +651,9 @@ export function valueToDefaultExpr(value: unknown): Expr { * @param value */ export function vectorToExpr( - value: firestore.VectorValue | number[] | Expr -): Expr { - if (value instanceof Expr) { + value: firestore.VectorValue | number[] | Expression +): Expression { + if (value instanceof Expression) { return value; } else if (value instanceof VectorValue) { const result = constant(value); @@ -677,7 +669,7 @@ export function vectorToExpr( } /** - * Converts a value to an Expr, Returning either a Constant, MapFunction, + * Converts a value to an Expression, Returning either a Constant, MapFunction, * ArrayFunction, or the input itself (if it's already an expression). * If the input is a string, it is assumed to be a field name, and a * field(value) is returned. @@ -686,7 +678,7 @@ export function vectorToExpr( * @internal * @param value */ -export function fieldOrExpression(value: unknown): Expr { +export function fieldOrExpression(value: unknown): Expression { if (isString(value)) { const result = field(value); result._createdFromLiteral = true; @@ -725,3 +717,46 @@ export function fieldOrSelectable(value: string | Selectable): Selectable { return value; } } + +export function selectablesToMap( + selectables: (firestore.Pipelines.Selectable | string)[] +): Map { + const result = new Map(); + for (const selectable of selectables) { + let alias: string; + let expression: Expression; + if (typeof selectable === 'string') { + alias = selectable as string; + expression = new Field(FieldPath.fromArgument(selectable)); + } else { + alias = selectable._alias; + expression = selectable._expr as unknown as Expression; + } + + if (result.get(alias) !== undefined) { + throw new Error(`Duplicate alias or field '${alias}'`); + } + + result.set(alias, expression); + } + return result; +} + +export function aliasedAggregateToMap( + aliasedAggregatees: firestore.Pipelines.AliasedAggregate[] +): Map { + return aliasedAggregatees.reduce( + ( + map: Map, + selectable: firestore.Pipelines.AliasedAggregate + ) => { + if (map.get(selectable._alias) !== undefined) { + throw new Error(`Duplicate alias or field '${selectable._alias}'`); + } + + map.set(selectable._alias, selectable._aggregate as AggregateFunction); + return map; + }, + new Map() as Map + ); +} diff --git a/dev/src/pipelines/pipelines.ts b/dev/src/pipelines/pipelines.ts index f902a374b..c15fe95a9 100644 --- a/dev/src/pipelines/pipelines.ts +++ b/dev/src/pipelines/pipelines.ts @@ -24,6 +24,7 @@ import Firestore, { import {validateFieldPath} from '../path'; import { ExecutionUtil, + aliasedAggregateToMap, fieldOrExpression, isAliasedAggregate, isBooleanExpr, @@ -35,6 +36,7 @@ import { isPipeline, isSelectable, isString, + selectablesToMap, toField, vectorToExpr, } from './pipeline-util'; @@ -50,10 +52,9 @@ import {isOptionalEqual, isPlainObject} from '../util'; import { AggregateFunction, AliasedAggregate, - Expr, - AliasedExpr, + Expression, Field, - BooleanExpr, + BooleanExpression, Ordering, constant, _mapValue, @@ -250,16 +251,27 @@ export class PipelineSource implements firestore.Pipelines.PipelineSource { return new Pipeline(this.db, [new DocumentsSource(internalOptions)]); } + /** + * @beta + * Convert the given VectorQuery into an equivalent Pipeline. + * + * @param query A VectorQuery to be converted into a Pipeline. + * + * @throws {@FirestoreError} Thrown if the provided VectorQuer targets a different project or database than the Pipeline. + */ + createFrom(query: firestore.VectorQuery): Pipeline; + /** * @beta * Convert the given Query into an equivalent Pipeline. * * @param query A Query to be converted into a Pipeline. * - * @throws {@FirestoreError} Thrown if any of the provided DocumentReferences target a different project or database than the pipeline. + * @throws {@FirestoreError} Thrown if the provided VectorQuer targets a different project or database than the Pipeline. */ - createFrom(query: firestore.Query): Pipeline { - return (query as unknown as Query)._pipeline(); + createFrom(query: firestore.Query): Pipeline; + createFrom(query: firestore.Query | firestore.VectorQuery): Pipeline { + return (query as unknown as {_pipeline(): Pipeline})._pipeline(); } _validateReference( @@ -323,14 +335,14 @@ export class PipelineSource implements firestore.Pipelines.PipelineSource { * // Example 2: Filter documents where 'genre' is 'Science Fiction' and 'published' is after 1950 * const results2 = await db.pipeline() * .collection('books') - * .where(and(field('genre').eq('Science Fiction'), field('published').gt(1950))) + * .where(and(field('genre').equal('Science Fiction'), field('published').greaterThan(1950))) * .execute(); * * // Example 3: Calculate the average rating of books published after 1980 * const results3 = await db.pipeline() * .collection('books') - * .where(field('published').gt(1980)) - * .aggregate(avg(field('rating')).as('averageRating')) + * .where(field('published').greaterThan(1980)) + * .aggregate(average(field('rating')).as('averageRating')) * .execute(); * ``` */ @@ -357,8 +369,8 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * The added fields are defined using {@link Selectable}s, which can be: * * - {@link Field}: References an existing document field. - * - {@link Expr}: Either a literal value (see {@link Constant}) or a computed value - * (see {@FunctionExpr}) with an assigned alias using {@link Expr#as}. + * - {@link Expression}: Either a literal value (see {@link Constant}) or a computed value + * (see {@FunctionExpression}) with an assigned alias using {@link Expression#as}. * * Example: * @@ -389,8 +401,8 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * The added fields are defined using {@link Selectable}s, which can be: * * - {@link Field}: References an existing document field. - * - {@link Expr}: Either a literal value (see {@link Constant}) or a computed value - * (see {@FunctionExpr}) with an assigned alias using {@link Expr#as}. + * - {@link Expression}: Either a literal value (see {@link Constant}) or a computed value + * (see {@FunctionExpression}) with an assigned alias using {@link Expression#as}. * * Example: * @@ -418,7 +430,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { ) ? [fieldOrOptions, ...additionalFields] : fieldOrOptions.fields; - const normalizedFields: Map = selectablesToMap(fields); + const normalizedFields: Map = selectablesToMap(fields); this._validateUserData('select', normalizedFields); @@ -510,7 +522,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { *
  • {@code string}: Name of an existing field
    • *
  • {@link Field}: References an existing field.
    • *
  • {@link Function}: Represents the result of a function with an assigned alias name using - * {@link Expr#as}
    • + * {@link Expression#as} * * *

    If no selections are provided, the output of this stage is empty. Use {@link @@ -548,7 +560,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { *

  • {@code string}: Name of an existing field
    • *
  • {@link Field}: References an existing field.
    • *
  • {@link Function}: Represents the result of a function with an assigned alias name using - * {@link Expr#as}
    • + * {@link Expression#as} * * *

    If no selections are provided, the output of this stage is empty. Use {@link @@ -586,7 +598,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { isSelectable(selectionOrOptions) || isString(selectionOrOptions) ? [selectionOrOptions, ...additionalSelections] : selectionOrOptions.selections; - const normalizedSelections: Map = + const normalizedSelections: Map = selectablesToMap(selections); this._validateUserData('select', normalizedSelections); @@ -601,15 +613,15 @@ export class Pipeline implements firestore.Pipelines.Pipeline { /** * @beta * Filters the documents from previous stages to only include those matching the specified {@link - * BooleanExpr}. + * BooleanExpression}. * *

    This stage allows you to apply conditions to the data, similar to a "WHERE" clause in SQL. * You can filter documents based on their field values, using implementations of {@link - * BooleanExpr}, typically including but not limited to: + * BooleanExpression}, typically including but not limited to: * *

      - *
    • field comparators: {@link Function#eq}, {@link Function#lt} (less than), {@link - * Function#gt} (greater than), etc.
      • + *
    • field comparators: {@link Function#equal}, {@link Function#lessThan} (less than), {@link + * Function#greaterThan} (greater than), etc.
      • *
    • logical operators: {@link Function#and}, {@link Function#or}, {@link Function#not}, etc.
      • *
    • advanced functions: {@link Function#regexMatch}, {@link * Function#arrayContains}, etc.
      • @@ -621,28 +633,28 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * firestore.pipeline().collection("books") * .where( * and( - * gt(field("rating"), 4.0), // Filter for ratings greater than 4.0 - * field("genre").eq("Science Fiction") // Equivalent to gt("genre", "Science Fiction") + * greaterThan(field("rating"), 4.0), // Filter for ratings greater than 4.0 + * field("genre").equal("Science Fiction") // Equivalent to greaterThan("genre", "Science Fiction") * ) * ); * ``` * - * @param condition The {@link BooleanExpr} to apply. + * @param condition The {@link BooleanExpression} to apply. * @return A new Pipeline object with this stage appended to the stage list. */ - where(condition: firestore.Pipelines.BooleanExpr): Pipeline; + where(condition: firestore.Pipelines.BooleanExpression): Pipeline; /** * @beta * Filters the documents from previous stages to only include those matching the specified {@link - * BooleanExpr}. + * BooleanExpression}. * *

      This stage allows you to apply conditions to the data, similar to a "WHERE" clause in SQL. * You can filter documents based on their field values, using implementations of {@link - * BooleanExpr}, typically including but not limited to: + * BooleanExpression}, typically including but not limited to: * *

        - *
      • field comparators: {@link Function#eq}, {@link Function#lt} (less than), {@link - * Function#gt} (greater than), etc.
        • + *
      • field comparators: {@link Function#equal}, {@link Function#lessThan} (less than), {@link + * Function#greaterThan} (greater than), etc.
        • *
      • logical operators: {@link Function#and}, {@link Function#or}, {@link Function#not}, etc.
        • *
      • advanced functions: {@link Function#regexMatch}, {@link * Function#arrayContains}, etc.
        • @@ -654,8 +666,8 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * firestore.pipeline().collection("books") * .where( * and( - * gt(field("rating"), 4.0), // Filter for ratings greater than 4.0 - * field("genre").eq("Science Fiction") // Equivalent to gt("genre", "Science Fiction") + * greaterThan(field("rating"), 4.0), // Filter for ratings greater than 4.0 + * field("genre").equal("Science Fiction") // Equivalent to greaterThan("genre", "Science Fiction") * ) * ); * ``` @@ -666,17 +678,18 @@ export class Pipeline implements firestore.Pipelines.Pipeline { where(options: firestore.Pipelines.WhereStageOptions): Pipeline; where( conditionOrOptions: - | firestore.Pipelines.BooleanExpr + | firestore.Pipelines.BooleanExpression | firestore.Pipelines.WhereStageOptions ): Pipeline { const options = isBooleanExpr(conditionOrOptions) ? {} : conditionOrOptions; - const condition: firestore.Pipelines.BooleanExpr = isBooleanExpr( + const condition: firestore.Pipelines.BooleanExpression = isBooleanExpr( conditionOrOptions ) ? conditionOrOptions : conditionOrOptions.condition; - const convertedCondition: BooleanExpr = condition as BooleanExpr; + const convertedCondition: BooleanExpression = + condition as BooleanExpression; this._validateUserData('where', convertedCondition); const internalOptions: InternalWhereStageOptions = { @@ -822,14 +835,14 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * Returns a set of distinct values from the inputs to this stage. * * This stage runs through the results from previous stages to include only results with - * unique combinations of {@link Expr} values ({@link Field}, {@link Function}, etc). + * unique combinations of {@link Expression} values ({@link Field}, {@link Function}, etc). * * The parameters to this stage are defined using {@link Selectable} expressions or strings: * * - {@code string}: Name of an existing field * - {@link Field}: References an existing document field. - * - {@link AliasedExpr}: Represents the result of a function with an assigned alias name - * using {@link Expr#as}. + * - {@link AliasedExpression}: Represents the result of a function with an assigned alias name + * using {@link Expression#as}. * * Example: * @@ -855,14 +868,14 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * Returns a set of distinct values from the inputs to this stage. * * This stage runs through the results from previous stages to include only results with - * unique combinations of {@link Expr} values ({@link Field}, {@link Function}, etc). + * unique combinations of {@link Expression} values ({@link Field}, {@link Function}, etc). * * The parameters to this stage are defined using {@link Selectable} expressions or strings: * * - {@code string}: Name of an existing field * - {@link Field}: References an existing document field. - * - {@link AliasedExpr}: Represents the result of a function with an assigned alias name - * using {@link Expr#as}. + * - {@link AliasedExpression}: Represents the result of a function with an assigned alias name + * using {@link Expression#as}. * * Example: * @@ -893,7 +906,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { isString(groupOrOptions) || isSelectable(groupOrOptions) ? [groupOrOptions, ...additionalGroups] : groupOrOptions.groups; - const convertedGroups: Map = selectablesToMap(groups); + const convertedGroups: Map = selectablesToMap(groups); this._validateUserData('distinct', convertedGroups); const internalOptions: InternalDistinctStageOptions = { @@ -910,7 +923,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * *

        This stage allows you to calculate aggregate values over a set of documents. You define the * aggregations to perform using {@link AliasedAggregate} expressions which are typically results of - * calling {@link Expr#as} on {@link AggregateFunction} instances. + * calling {@link Expression#as} on {@link AggregateFunction} instances. * *

        Example: * @@ -918,7 +931,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * // Calculate the average rating and the total number of books * firestore.pipeline().collection("books") * .aggregate( - * field("rating").avg().as("averageRating"), + * field("rating").average().as("averageRating"), * countAll().as("totalBooks") * ); * ``` @@ -947,7 +960,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * specifying groups is the same as putting the entire inputs into one group. *

      • **Accumulators:** One or more accumulation operations to perform within each group. These * are defined using {@link AliasedAggregate} expressions, which are typically created by - * calling {@link Expr#as} on {@link AggregateFunction} instances. Each aggregation + * calling {@link Expression#as} on {@link AggregateFunction} instances. Each aggregation * calculates a value (e.g., sum, average, count) based on the documents within its group.
        • *
      * @@ -957,7 +970,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * // Calculate the average rating for each genre. * firestore.pipeline().collection("books") * .aggregate({ - * accumulators: [avg(field("rating")).as("avg_rating")] + * accumulators: [average(field("rating")).as("avg_rating")] * groups: ["genre"] * }); * ``` @@ -983,7 +996,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { aliasedAggregateToMap(accumulators); const groups: Array = isAliasedAggregate(targetOrOptions) ? [] : targetOrOptions.groups ?? []; - const convertedGroups: Map = selectablesToMap(groups); + const convertedGroups: Map = selectablesToMap(groups); this._validateUserData('aggregate', convertedGroups); const internalOptions: InternalAggregateStageOptions = { @@ -1109,10 +1122,10 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * // } * ``` * - * @param expr An {@link Expr} that when returned evaluates to a map. + * @param expr An {@link Expression} that when returned evaluates to a map. * @return A new {@code Pipeline} object with this stage appended to the stage list. */ - replaceWith(expr: firestore.Pipelines.Expr): Pipeline; + replaceWith(expr: firestore.Pipelines.Expression): Pipeline; /** * @beta * Fully overwrites all fields in a document with those coming from a map. @@ -1153,14 +1166,14 @@ export class Pipeline implements firestore.Pipelines.Pipeline { replaceWith(options: firestore.Pipelines.ReplaceWithStageOptions): Pipeline; replaceWith( valueOrOptions: - | firestore.Pipelines.Expr + | firestore.Pipelines.Expression | string | firestore.Pipelines.ReplaceWithStageOptions ): Pipeline { const options = isString(valueOrOptions) || isExpr(valueOrOptions) ? {} : valueOrOptions; - const fieldNameOrExpr: string | firestore.Pipelines.Expr = + const fieldNameOrExpr: string | firestore.Pipelines.Expression = isString(valueOrOptions) || isExpr(valueOrOptions) ? valueOrOptions : valueOrOptions.map; @@ -1388,8 +1401,8 @@ export class Pipeline implements firestore.Pipelines.Pipeline { ) ? selectableOrOptions : selectableOrOptions.selectable; - const alias = selectable.alias; - const expr = selectable.expr as Expr; + const alias = selectable._alias; + const expr = selectable._expr as Expression; const indexFieldName = isSelectable(selectableOrOptions) ? indexField @@ -1500,7 +1513,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * ```typescript * // Assume we don't have a built-in 'where' stage * firestore.pipeline().collection('books') - * .rawStage('where', [field('published').lt(1900)]) // Custom 'where' stage + * .rawStage('where', [field('published').lessThan(1900)]) // Custom 'where' stage * .select('title', 'author'); * ``` * @@ -1512,14 +1525,14 @@ export class Pipeline implements firestore.Pipelines.Pipeline { rawStage( name: string, params: unknown[], - options?: {[key: string]: Expr | unknown} + options?: {[key: string]: Expression | unknown} ): Pipeline { // Convert input values to Expressions. // We treat objects as mapValues and arrays as arrayValues, // this is unlike the default conversion for objects and arrays // passed to an expression. const expressionParams = params.map((value: unknown) => { - if (value instanceof Expr) { + if (value instanceof Expression) { return value; } else if (value instanceof AggregateFunction) { return value; @@ -1563,7 +1576,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * * ```typescript * const futureResults = await firestore.pipeline().collection('books') - * .where(gt(field('rating'), 4.5)) + * .where(greaterThan(field('rating'), 4.5)) * .select('title', 'author', 'rating') * .execute(); * ``` @@ -1618,7 +1631,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { * @example * ```typescript * firestore.pipeline().collection('books') - * .where(gt(field('rating'), 4.5)) + * .where(greaterThan(field('rating'), 4.5)) * .select('title', 'author', 'rating') * .stream() * .on('data', (pipelineResult) => {}) @@ -1640,6 +1653,7 @@ export class Pipeline implements firestore.Pipelines.Pipeline { } /** + * @beta * Validates user data for each expression in the expressionMap. * @param name Name of the calling function. Used for error messages when invalid user data is encountered. * @param val @@ -1664,43 +1678,6 @@ export class Pipeline implements firestore.Pipelines.Pipeline { } } -function selectablesToMap( - selectables: (firestore.Pipelines.Selectable | string)[] -): Map { - const result = new Map(); - for (const selectable of selectables) { - if (typeof selectable === 'string') { - result.set( - selectable as string, - new Field(FieldPath.fromArgument(selectable)) - ); - } else if (selectable instanceof Field) { - result.set((selectable as Field).fieldName(), selectable); - } else if (selectable instanceof AliasedExpr) { - const expr = selectable as AliasedExpr; - result.set(expr.alias, expr.expr as unknown as Expr); - } else { - throw new Error('unexpected selectable: ' + JSON.stringify(selectable)); - } - } - return result; -} - -function aliasedAggregateToMap( - aliasedAggregatees: firestore.Pipelines.AliasedAggregate[] -): Map { - return aliasedAggregatees.reduce( - ( - map: Map, - selectable: firestore.Pipelines.AliasedAggregate - ) => { - map.set(selectable.alias, selectable.aggregate as AggregateFunction); - return map; - }, - new Map() as Map - ); -} - /** * @beta * A wrapper object to access explain stats if explain or analyze @@ -1710,6 +1687,7 @@ export class ExplainStats implements firestore.Pipelines.ExplainStats { private static protoRoot: ProtoRoot | undefined = undefined; /** + * @beta * @private * @internal */ @@ -1723,6 +1701,7 @@ export class ExplainStats implements firestore.Pipelines.ExplainStats { } /** + * @beta * @private * @internal * @hideconstructor @@ -1731,6 +1710,7 @@ export class ExplainStats implements firestore.Pipelines.ExplainStats { constructor(private readonly explainStatsData: google.protobuf.IAny) {} /** + * @beta * Decode an ExplainStats proto message into a value. * @private * @internal @@ -1886,6 +1866,7 @@ export class PipelineResult implements firestore.Pipelines.PipelineResult { public readonly _updateTime: Timestamp | undefined; /** + * @beta * @private * @internal * @@ -1901,6 +1882,7 @@ export class PipelineResult implements firestore.Pipelines.PipelineResult { constructor( serializer: Serializer, /** + * @beta * @internal * @private **/ @@ -1960,23 +1942,6 @@ export class PipelineResult implements firestore.Pipelines.PipelineResult { return this._updateTime; } - /** - * @beta - * The time at which the pipeline producing this result is executed. - * - * @type {Timestamp} - * @readonly - * - */ - get executionTime(): Timestamp { - if (this._executionTime === undefined) { - throw new Error( - "'executionTime' is expected to exist, but it is undefined" - ); - } - return this._executionTime; - } - /** * @beta * Retrieves all fields in the result as an object. @@ -2038,6 +2003,7 @@ export class PipelineResult implements firestore.Pipelines.PipelineResult { } /** + * @beta * Retrieves the field specified by 'fieldPath' in its Protobuf JS * representation. * diff --git a/dev/src/pipelines/stage.ts b/dev/src/pipelines/stage.ts index ff3588726..dff5bd461 100644 --- a/dev/src/pipelines/stage.ts +++ b/dev/src/pipelines/stage.ts @@ -21,8 +21,8 @@ import {ProtoSerializable, Serializer} from '../serializer'; import { AggregateFunction, - BooleanExpr, - Expr, + BooleanExpression, + Expression, Field, field, Ordering, @@ -72,7 +72,7 @@ export type InternalAggregateStageOptions = Omit< firestore.Pipelines.AggregateStageOptions, 'groups' | 'accumulators' > & { - groups: Map; + groups: Map; accumulators: Map; }; @@ -104,7 +104,7 @@ export type InternalDistinctStageOptions = Omit< firestore.Pipelines.DistinctStageOptions, 'groups' > & { - groups: Map; + groups: Map; }; /** @@ -256,7 +256,7 @@ export type InternalWhereStageOptions = Omit< firestore.Pipelines.WhereStageOptions, 'condition' > & { - condition: BooleanExpr; + condition: BooleanExpression; }; /** @@ -284,7 +284,7 @@ export type InternalFindNearestStageOptions = Omit< firestore.Pipelines.FindNearestStageOptions, 'vectorValue' | 'field' | 'distanceField' > & { - vectorValue: Expr; + vectorValue: Expression; field: Field; distanceField?: Field; }; @@ -381,7 +381,7 @@ export type InternalUnnestStageOptions = Omit< 'selectable' | 'indexField' > & { alias: string; - expr: Expr; + expr: Expression; indexField?: Field; }; @@ -463,7 +463,7 @@ export type InternalReplaceWithStageOptions = Omit< firestore.Pipelines.ReplaceWithStageOptions, 'map' > & { - map: Expr; + map: Expression; }; /** @@ -494,7 +494,7 @@ export type InternalSelectStageOptions = Omit< firestore.Pipelines.SelectStageOptions, 'selections' > & { - selections: Map; + selections: Map; }; /** @@ -522,7 +522,7 @@ export type InternalAddFieldsStageOptions = Omit< firestore.Pipelines.AddFieldsStageOptions, 'fields' > & { - fields: Map; + fields: Map; }; /** @@ -586,7 +586,7 @@ export class RawStage implements Stage { */ constructor( public name: string, - private params: Array, + private params: Array, private rawOptions: Record ) {} diff --git a/dev/src/pipelines/structured-pipeline.ts b/dev/src/pipelines/structured-pipeline.ts index 69e9192de..9c8f5e04a 100644 --- a/dev/src/pipelines/structured-pipeline.ts +++ b/dev/src/pipelines/structured-pipeline.ts @@ -25,7 +25,7 @@ export type StructuredPipelineOptions = { indexMode?: 'recommended'; explainOptions?: { mode?: 'execute' | 'explain' | 'analyze'; - outputFormat?: 'text' | 'json'; + outputFormat?: 'text'; }; }; diff --git a/dev/src/reference/aggregate-query.ts b/dev/src/reference/aggregate-query.ts index 8143a9c37..a4b62fd43 100644 --- a/dev/src/reference/aggregate-query.ts +++ b/dev/src/reference/aggregate-query.ts @@ -22,7 +22,7 @@ import * as deepEqual from 'fast-deep-equal'; import * as firestore from '@google-cloud/firestore'; import {Aggregate, AggregateSpec} from '../aggregate'; -import {avg, count, countAll, field, sum} from '../pipelines'; +import {average, count, countAll, field, sum} from '../pipelines'; import {Pipeline} from '../pipelines'; import {Timestamp} from '../timestamp'; import {mapToArray, requestTag, wrapError} from '../util'; @@ -363,7 +363,7 @@ export class AggregateQuery< } return count(field(aggregate._field)).as(clientAlias); } else if (aggregate.aggregateType === 'avg') { - return avg(field(aggregate._field!)).as(clientAlias); + return average(field(aggregate._field!)).as(clientAlias); } else if (aggregate.aggregateType === 'sum') { return sum(field(aggregate._field!)).as(clientAlias); } else { diff --git a/dev/src/reference/vector-query.ts b/dev/src/reference/vector-query.ts index 6f6abfff0..20ecfe1e5 100644 --- a/dev/src/reference/vector-query.ts +++ b/dev/src/reference/vector-query.ts @@ -140,7 +140,11 @@ export class VectorQuery< return result; } - toPipeline(): Pipeline { + /** + * @private + * @internal + */ + _toPipeline(): Pipeline { const options: firestore.Pipelines.FindNearestStageOptions = { field: field(this._options.vectorField), vectorValue: this._options.queryVector, diff --git a/dev/src/transaction.ts b/dev/src/transaction.ts index 3d754d8bf..61dc35cc6 100644 --- a/dev/src/transaction.ts +++ b/dev/src/transaction.ts @@ -313,7 +313,7 @@ export class Transaction implements firestore.Transaction { * const futureResults = await transaction * .execute( * firestore.pipeline().collection("books") - * .where(gt(field("rating"), 4.5)) + * .where(greaterThan(field("rating"), 4.5)) * .select("title", "author", "rating")); * ``` * @@ -330,8 +330,9 @@ export class Transaction implements firestore.Transaction { this.executePipelineFn ).then(results => { const executionTime = results.reduce((maxTime, result) => { - return result.executionTime.valueOf() > maxTime.valueOf() - ? result.executionTime + return result._executionTime && + result._executionTime?.valueOf() > maxTime.valueOf() + ? result._executionTime : maxTime; }, Timestamp.fromMillis(0)); diff --git a/dev/system-test/pipeline.ts b/dev/system-test/pipeline.ts index 5c420266a..73dd7417c 100644 --- a/dev/system-test/pipeline.ts +++ b/dev/system-test/pipeline.ts @@ -19,7 +19,7 @@ import { } from '@google-cloud/firestore'; import { - BooleanExpr, + BooleanExpression, map, array, field, @@ -28,25 +28,24 @@ import { exp, xor, AggregateFunction, - rand, arrayGet, timestampToUnixMicros, timestampToUnixSeconds, unixMicrosToTimestamp, timestampToUnixMillis, - timestampSub, + timestampSubtract, timestampAdd, byteLength, multiply, sum, maximum, descending, - FunctionExpr, + FunctionExpression, minimum, count, countIf, arrayLength, - strContains, + stringContains, charLength, divide, mod, @@ -55,16 +54,12 @@ import { toUpper, toLower, vectorLength, - isNotNan, exists, - isNotNull, isAbsent, ifError, isError, - isNan, substring, documentId, - isNull, arrayContainsAll, mapRemove, mapMerge, @@ -75,32 +70,32 @@ import { arrayContains, arrayContainsAny, arrayReverse, - avg, + average, countAll, endsWith, - eq, - gt, + equal, + greaterThan, like, - lt, - neq, + lessThan, + notEqual, ascending, not, or, regexContains, regexMatch, startsWith, - strConcat, + stringConcat, subtract, cosineDistance, dotProduct, euclideanDistance, mapGet, - lte, - eqAny, - notEqAny, + lessThanOrEqual, + equalAny, + notEqualAny, logicalMinimum, logicalMaximum, - cond, + conditional, constant, PipelineResult, PipelineSnapshot, @@ -111,9 +106,16 @@ import { collectionId, length, ln, - log, sqrt, - strReverse, + stringReverse, + abs, + log10, + concat, + ifAbsent, + join, + arraySum, + currentTimestamp, + arrayConcat, // TODO(new-expression): add new expression imports above this line } from '../src/pipelines'; @@ -137,13 +139,11 @@ import {getTestDb, getTestRoot} from './firestore'; import {Firestore as InternalFirestore} from '../src'; import {ServiceError} from 'google-gax'; -import * as google from '../protos/firestore_v1_proto_api'; - use(chaiAsPromised); const timestampDeltaMS = 3000; -describe('Pipeline class', () => { +describe.skip('Pipeline class', () => { let firestore: Firestore; let randomCol: CollectionReference; let beginDocCreation = 0; @@ -421,7 +421,7 @@ describe('Pipeline class', () => { const pipeline = firestore .pipeline() .collection(randomCol.path) - .aggregate(avg('rating').as('avgRating')); + .aggregate(average('rating').as('avgRating')); const snapshot = await pipeline.execute(); const end = new Date().valueOf(); @@ -439,7 +439,7 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .aggregate({ - accumulators: [avg('rating').as('avgRating')], + accumulators: [average('rating').as('avgRating')], groups: ['genre'], }); @@ -455,7 +455,47 @@ describe('Pipeline class', () => { }); describe('pipeline explain', () => { - it('mode: analyze', async () => { + it('mode: analyze, format: text', async () => { + const ppl = firestore + .pipeline() + .collection(randomCol.path) + .sort(ascending('__name__')); + + const snapshot = await ppl.execute({ + explainOptions: { + mode: 'analyze', + outputFormat: 'text', + }, + }); + + expect(snapshot.explainStats).not.to.be.undefined; + expect(snapshot.explainStats!.text.length).to.be.greaterThan(0); + expect(snapshot.explainStats!.text.charAt(0)).not.to.equal('{'); + + expect(snapshot.explainStats!.rawData.type_url).to.equal( + 'type.googleapis.com/google.protobuf.StringValue' + ); + expect(snapshot.explainStats!.rawData.value).to.not.be.null; + expect(snapshot.explainStats!.rawData.value).to.not.be.undefined; + + expect(snapshot.results.length).to.equal(10); + expect(snapshot.pipeline).to.equal(ppl); + expectResults( + snapshot, + 'book1', + 'book10', + 'book2', + 'book3', + 'book4', + 'book5', + 'book6', + 'book7', + 'book8', + 'book9' + ); + }); + + it('mode: analyze, format: unspecified', async () => { const ppl = firestore .pipeline() .collection(randomCol.path) @@ -492,13 +532,16 @@ describe('Pipeline class', () => { ); }); - it('mode: unspecified', async () => { + it('mode: execute, format: text', async () => { const ppl = firestore .pipeline() .collection(randomCol.path) .sort(ascending('__name__')); const snapshot = await ppl.execute({ - explainOptions: {}, + explainOptions: { + mode: 'execute', + outputFormat: 'text', + }, }); expect(snapshot.explainStats).to.be.undefined; @@ -519,7 +562,7 @@ describe('Pipeline class', () => { ); }); - it('mode: undefined', async () => { + it('mode: unspecified, format: text', async () => { const ppl = firestore .pipeline() .collection(randomCol.path) @@ -623,7 +666,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .database() - .where(eq('randomId', randomId)) + .where(equal('randomId', randomId)) .sort(ascending('order')) .execute(); expectResults(snapshot, doc1.id, doc2.id); @@ -851,7 +894,7 @@ describe('Pipeline class', () => { ) .where( and( - eq('metadataArray', [ + equal('metadataArray', [ 1, 2, field('genre'), @@ -861,7 +904,7 @@ describe('Pipeline class', () => { published: field('published'), }, ]), - eq('metadata', { + equal('metadata', { genre: field('genre'), rating: multiply('rating', 10), nestedArray: [field('title')], @@ -918,10 +961,10 @@ describe('Pipeline class', () => { snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('genre', 'Science Fiction')) + .where(equal('genre', 'Science Fiction')) .aggregate( countAll().as('count'), - avg('rating').as('avgRating'), + average('rating').as('avgRating'), maximum('rating').as('maxRating'), sum('rating').as('sumRating') ) @@ -934,6 +977,27 @@ describe('Pipeline class', () => { }); }); + it('throws on duplicate aliases', async () => { + expect(() => + firestore + .pipeline() + .collection(randomCol.path) + .aggregate(countAll().as('count'), count('foo').as('count')) + ).to.throw("Duplicate alias or field 'count'"); + }); + + it('throws on duplicate group aliases', async () => { + expect(() => + firestore + .pipeline() + .collection(randomCol.path) + .aggregate({ + accumulators: [countAll().as('count')], + groups: ['bax', field('bar').as('bax')], + }) + ).to.throw("Duplicate alias or field 'bax'"); + }); + it('supports aggregate options', async () => { let snapshot = await firestore .pipeline() @@ -947,10 +1011,10 @@ describe('Pipeline class', () => { snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('genre', 'Science Fiction')) + .where(equal('genre', 'Science Fiction')) .aggregate( countAll().as('count'), - avg('rating').as('avgRating'), + average('rating').as('avgRating'), maximum('rating').as('maxRating'), sum('rating').as('sumRating') ) @@ -968,7 +1032,7 @@ describe('Pipeline class', () => { firestore .pipeline() .collection(randomCol.path) - .where(lt('published', 1900)) + .where(lessThan('published', 1900)) .aggregate({ accumulators: [], groups: ['genre'], @@ -981,12 +1045,12 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(lt(field('published'), 1984)) + .where(lessThan(field('published'), 1984)) .aggregate({ - accumulators: [avg('rating').as('avgRating')], + accumulators: [average('rating').as('avgRating')], groups: ['genre'], }) - .where(gt('avgRating', 4.3)) + .where(greaterThan('avgRating', 4.3)) .sort(field('avgRating').descending()) .execute(); expectResults( @@ -1020,7 +1084,7 @@ describe('Pipeline class', () => { let snapshot = await firestore .pipeline() .collection(randomCol.path) - .aggregate(countIf(field('rating').gt(4.3)).as('count')) + .aggregate(countIf(field('rating').greaterThan(4.3)).as('count')) .execute(); const expectedResults = { count: 3, @@ -1030,7 +1094,7 @@ describe('Pipeline class', () => { snapshot = await firestore .pipeline() .collection(randomCol.path) - .aggregate(field('rating').gt(4.3).countIf().as('count')) + .aggregate(field('rating').greaterThan(4.3).countIf().as('count')) .execute(); expectResults(snapshot, expectedResults); }); @@ -1125,6 +1189,16 @@ describe('Pipeline class', () => { ); }); + it('throws on duplicate aliases', async () => { + expect(() => { + firestore + .pipeline() + .collection(randomCol.path) + .limit(1) + .select(constant(1).as('foo'), constant(2).as('foo')); + }).to.throw("Duplicate alias or field 'foo'"); + }); + it('supports options', async () => { const snapshot = await firestore .pipeline() @@ -1196,6 +1270,17 @@ describe('Pipeline class', () => { ); }); + it('throws on duplicate aliases', async () => { + expect(() => + firestore + .pipeline() + .collection(randomCol.path) + .select('title', 'author') + .addFields(constant('bar').as('foo'), constant('baz').as('foo')) + .sort(field('author').ascending()) + ).to.throw("Duplicate alias or field 'foo'"); + }); + it('supports options', async () => { const snapshot = await firestore .pipeline() @@ -1258,7 +1343,6 @@ describe('Pipeline class', () => { .select('title', 'author') .sort(field('author').ascending()) .removeFields(field('author')) - .sort(field('author').ascending()) .execute(); expectResults( snapshot, @@ -1298,7 +1382,6 @@ describe('Pipeline class', () => { .removeFields({ fields: [field('author'), 'genre'], }) - .sort(field('author').ascending()) .execute(); expectResults( snapshot, @@ -1338,7 +1421,6 @@ describe('Pipeline class', () => { .select('title', 'author') .sort(field('author').ascending()) .removeFields(field('author')) - .sort(field('author').ascending()) .execute(); expectResults( snapshot, @@ -1378,7 +1460,6 @@ describe('Pipeline class', () => { .removeFields({ fields: [field('author'), 'genre'], }) - .sort(field('author').ascending()) .execute(); expectResults( snapshot, @@ -1417,8 +1498,8 @@ describe('Pipeline class', () => { .collection(randomCol.path) .where( and( - gt('rating', 4.5), - eqAny('genre', ['Science Fiction', 'Romance', 'Fantasy']) + greaterThan('rating', 4.5), + equalAny('genre', ['Science Fiction', 'Romance', 'Fantasy']) ) ) .execute(); @@ -1431,9 +1512,9 @@ describe('Pipeline class', () => { .collection(randomCol.path) .where( and( - gt('rating', 4.5), - eqAny('genre', ['Science Fiction', 'Romance', 'Fantasy']), - lt('published', 1965) + greaterThan('rating', 4.5), + equalAny('genre', ['Science Fiction', 'Romance', 'Fantasy']), + lessThan('published', 1965) ) ) .execute(); @@ -1446,9 +1527,9 @@ describe('Pipeline class', () => { .collection(randomCol.path) .where( or( - eq('genre', 'Romance'), - eq('genre', 'Dystopian'), - eq('genre', 'Fantasy') + equal('genre', 'Romance'), + equal('genre', 'Dystopian'), + equal('genre', 'Fantasy') ) ) .sort(ascending('title')) @@ -1469,10 +1550,10 @@ describe('Pipeline class', () => { .collection(randomCol.path) .where( xor( - eq('genre', 'Romance'), - eq('genre', 'Dystopian'), - eq('genre', 'Fantasy'), - eq('published', 1949) + equal('genre', 'Romance'), + equal('genre', 'Dystopian'), + equal('genre', 'Fantasy'), + equal('published', 1949) ) ) .select('title') @@ -1491,8 +1572,8 @@ describe('Pipeline class', () => { .collection(randomCol.path) .where({ condition: and( - gt('rating', 4.5), - eqAny('genre', ['Science Fiction', 'Romance', 'Fantasy']) + greaterThan('rating', 4.5), + equalAny('genre', ['Science Fiction', 'Romance', 'Fantasy']) ), }) .execute(); @@ -1598,12 +1679,17 @@ describe('Pipeline class', () => { expect('statusDetails' in err).to.be.true; expect(Array.isArray(err['statusDetails'])).to.be.true; - const explainStatsAny = ( - err['statusDetails'] as Array - )[0] as google.google.protobuf.IAny; - expect(explainStatsAny['type_url']).to.equal( - 'type.googleapis.com/google.firestore.v1.ExplainStats' - ); + + const statusDetails = err['statusDetails'] as Array; + + const foundExplainStats = statusDetails.find(x => { + return ( + 'type_url' in x && + x['type_url'] === + 'type.googleapis.com/google.firestore.v1.ExplainStats' + ); + }); + expect(foundExplainStats).to.not.be.undefined; } }); }); @@ -1641,7 +1727,7 @@ describe('Pipeline class', () => { .select('title', 'author') .rawStage('add_fields', [ { - display: strConcat('title', ' - ', field('author')), + display: stringConcat('title', ' - ', field('author')), }, ]) .execute(); @@ -1657,7 +1743,7 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .select('title', 'author') - .rawStage('where', [field('author').eq('Douglas Adams')]) + .rawStage('where', [field('author').equal('Douglas Adams')]) .execute(); expectResults(snapshot, { title: "The Hitchhiker's Guide to the Galaxy", @@ -1690,7 +1776,10 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .select('title', 'author', 'rating') - .rawStage('aggregate', [{averageRating: field('rating').avg()}, {}]) + .rawStage('aggregate', [ + {averageRating: field('rating').average()}, + {}, + ]) .execute(); expectResults(snapshot, { averageRating: 4.3100000000000005, @@ -1768,7 +1857,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('title', "The Hitchhiker's Guide to the Galaxy")) + .where(equal('title', "The Hitchhiker's Guide to the Galaxy")) .replaceWith('awards') .execute(); expectResults(snapshot, { @@ -1778,11 +1867,11 @@ describe('Pipeline class', () => { }); }); - it('run pipeline with replaceWith Expr result', async () => { + it('run pipeline with replaceWith Expression result', async () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('title', "The Hitchhiker's Guide to the Galaxy")) + .where(equal('title', "The Hitchhiker's Guide to the Galaxy")) .replaceWith( map({ foo: 'bar', @@ -1802,7 +1891,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('title', "The Hitchhiker's Guide to the Galaxy")) + .where(equal('title', "The Hitchhiker's Guide to the Galaxy")) .replaceWith({map: 'awards'}) .execute(); expectResults(snapshot, { @@ -1920,7 +2009,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('title', "The Hitchhiker's Guide to the Galaxy")) + .where(equal('title', "The Hitchhiker's Guide to the Galaxy")) .unnest(field('tags').as('tag')) .select( 'title', @@ -1988,7 +2077,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('title', "The Hitchhiker's Guide to the Galaxy")) + .where(equal('title', "The Hitchhiker's Guide to the Galaxy")) .unnest(field('tags').as('tag'), 'tagsIndex') .select( 'title', @@ -1999,7 +2088,8 @@ describe('Pipeline class', () => { 'tags', 'tag', 'awards', - 'nestedField' + 'nestedField', + 'tagsIndex' ) .execute(); expectResults( @@ -2059,7 +2149,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('title', "The Hitchhiker's Guide to the Galaxy")) + .where(equal('title', "The Hitchhiker's Guide to the Galaxy")) .unnest(array([1, 2, 3]).as('copy')) .select( 'title', @@ -2127,7 +2217,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('title', "The Hitchhiker's Guide to the Galaxy")) + .where(equal('title', "The Hitchhiker's Guide to the Galaxy")) .unnest({ selectable: field('tags').as('tag'), indexField: 'tagsIndex', @@ -2141,7 +2231,8 @@ describe('Pipeline class', () => { 'tags', 'tag', 'awards', - 'nestedField' + 'nestedField', + 'tagsIndex' ) .execute(); expectResults( @@ -2301,34 +2392,38 @@ describe('Pipeline class', () => { ); }); - it('cond works', async () => { + it('conditional works', async () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) .select( 'title', - cond( - lt(field('published'), 1960), + conditional( + lessThan(field('published'), 1960), constant(1960), field('published') - ).as('published-safe') + ).as('published-safe'), + field('rating') + .greaterThanOrEqual(4.5) + .conditional(constant('great'), constant('good')) + .as('rating') ) .sort(field('title').ascending()) .limit(3) .execute(); expectResults( snapshot, - {title: '1984', 'published-safe': 1960}, - {title: 'Crime and Punishment', 'published-safe': 1960}, - {title: 'Dune', 'published-safe': 1965} + {title: '1984', 'published-safe': 1960, rating: 'good'}, + {title: 'Crime and Punishment', 'published-safe': 1960, rating: 'good'}, + {title: 'Dune', 'published-safe': 1965, rating: 'great'} ); }); - it('eqAny works', async () => { + it('equalAny works', async () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eqAny('published', [1979, 1999, 1967])) + .where(equalAny('published', [1979, 1999, 1967])) .sort(descending('title')) .select('title') .execute(); @@ -2339,12 +2434,12 @@ describe('Pipeline class', () => { ); }); - it('notEqAny works', async () => { + it('notEqualAny works', async () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) .where( - notEqAny( + notEqualAny( 'published', [1965, 1925, 1949, 1960, 1866, 1985, 1954, 1967, 1979] ) @@ -2396,7 +2491,7 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .select(arrayLength('tags').as('tagsCount')) - .where(eq('tagsCount', 3)) + .where(equal('tagsCount', 3)) .execute(); expect(snapshot.results.length).to.equal(10); }); @@ -2406,7 +2501,9 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .sort(ascending('author')) - .select(field('author').strConcat(' - ', field('title')).as('bookInfo')) + .select( + field('author').stringConcat(' - ', field('title')).as('bookInfo') + ) .limit(1) .execute(); expectResults(snapshot, { @@ -2450,7 +2547,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(strContains('title', "'s")) + .where(stringContains('title', "'s")) .select('title') .sort(field('title').ascending()) .execute(); @@ -2466,7 +2563,7 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .select(charLength('title').as('titleLength'), field('title')) - .where(gt('titleLength', 20)) + .where(greaterThan('titleLength', 20)) .sort(field('title').ascending()) .execute(); @@ -2526,7 +2623,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('title', 'To Kill a Mockingbird')) + .where(equal('title', 'To Kill a Mockingbird')) .select( add(field('rating'), 1).as('ratingPlusOne'), subtract(field('published'), 1900).as('yearsSince1900'), @@ -2555,9 +2652,9 @@ describe('Pipeline class', () => { .collection(randomCol.path) .where( and( - gt('rating', 4.2), - lte(field('rating'), 4.5), - neq('genre', 'Science Fiction') + greaterThan('rating', 4.2), + lessThanOrEqual(field('rating'), 4.5), + notEqual('genre', 'Science Fiction') ) ) .select('rating', 'title') @@ -2580,8 +2677,8 @@ describe('Pipeline class', () => { .collection(randomCol.path) .where( or( - and(gt('rating', 4.5), eq('genre', 'Science Fiction')), - lt('published', 1900) + and(greaterThan('rating', 4.5), equal('genre', 'Science Fiction')), + lessThan('published', 1900) ) ) .select('title') @@ -2602,13 +2699,21 @@ describe('Pipeline class', () => { .sort(field('rating').descending()) .limit(1) .select( - isNull('rating').as('ratingIsNull'), - isNan('rating').as('ratingIsNaN'), - isError(arrayGet('title', 0)).as('isError'), - ifError(arrayGet('title', 0), constant('was error')).as('ifError'), + equal('rating', null).as('ratingIsNull'), + equal('rating', NaN).as('ratingIsNaN'), + isError(divide(constant(1), constant(0))).as('isError'), + ifError(divide(constant(1), constant(0)), constant('was error')).as( + 'ifError' + ), + ifError( + divide(constant(1), constant(0)).greaterThan(1), + constant(true) + ) + .not() + .as('ifErrorBooleanExpression'), isAbsent('foo').as('isAbsent'), - isNotNull('title').as('titleIsNotNull'), - isNotNan('cost').as('costIsNotNan'), + notEqual('title', null).as('titleIsNotNull'), + notEqual('cost', NaN).as('costIsNotNan'), exists('fooBarBaz').as('fooBarBazExists'), field('title').exists().as('titleExists') ) @@ -2618,6 +2723,7 @@ describe('Pipeline class', () => { ratingIsNaN: false, isError: true, ifError: 'was error', + ifErrorBooleanExpression: false, isAbsent: true, titleIsNotNull: true, costIsNotNan: false, @@ -2631,13 +2737,20 @@ describe('Pipeline class', () => { .sort(field('rating').descending()) .limit(1) .select( - field('rating').isNull().as('ratingIsNull'), - field('rating').isNan().as('ratingIsNaN'), - arrayGet('title', 0).isError().as('isError'), - arrayGet('title', 0).ifError(constant('was error')).as('ifError'), + field('rating').equal(null).as('ratingIsNull'), + field('rating').equal(NaN).as('ratingIsNaN'), + divide(constant(1), constant(0)).isError().as('isError'), + divide(constant(1), constant(0)) + .ifError(constant('was error')) + .as('ifError'), + divide(constant(1), constant(0)) + .greaterThan(1) + .ifError(constant(true)) + .not() + .as('ifErrorBooleanExpression'), field('foo').isAbsent().as('isAbsent'), - field('title').isNotNull().as('titleIsNotNull'), - field('cost').isNotNan().as('costIsNotNan') + field('title').notEqual(null).as('titleIsNotNull'), + field('cost').notEqual(NaN).as('costIsNotNan') ) .execute(); expectResults(snapshot, { @@ -2645,6 +2758,7 @@ describe('Pipeline class', () => { ratingIsNaN: false, isError: true, ifError: 'was error', + ifErrorBooleanExpression: false, isAbsent: true, titleIsNotNull: true, costIsNotNan: false, @@ -2661,7 +2775,7 @@ describe('Pipeline class', () => { field('awards').mapGet('others').as('others'), field('title') ) - .where(eq('hugoAward', true)) + .where(equal('hugoAward', true)) .execute(); expectResults( snapshot, @@ -2670,7 +2784,7 @@ describe('Pipeline class', () => { title: "The Hitchhiker's Guide to the Galaxy", others: {unknown: {year: 1980}}, }, - {hugoAward: true, title: 'Dune', others: null} + {hugoAward: true, title: 'Dune'} ); }); @@ -2744,7 +2858,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('awards.hugo', true)) + .where(equal('awards.hugo', true)) .sort(descending('title')) .select('title', 'awards.hugo') .execute(); @@ -2762,23 +2876,32 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('awards.hugo', true)) + .limit(1) + .replaceWith( + map({ + title: 'foo', + nested: { + level: { + '1': 'bar', + }, + 'level.1': { + 'level.2': 'baz', + }, + }, + }) + ) .select( 'title', - field('nestedField.level.1'), - mapGet('nestedField', 'level.1').mapGet('level.2').as('nested') + field('nested.level.1'), + mapGet('nested', 'level.1').mapGet('level.2').as('nested') ) - .sort(descending('title')) .execute(); - expectResults( - snapshot, - { - title: "The Hitchhiker's Guide to the Galaxy", - 'nestedField.level.`1`': null, - nested: true, - }, - {title: 'Dune', 'nestedField.level.`1`': null, nested: null} - ); + + expectResults(snapshot, { + title: 'foo', + 'nested.level.`1`': 'bar', + nested: 'baz', + }); }); describe('genericFunction', () => { @@ -2789,7 +2912,9 @@ describe('Pipeline class', () => { .sort(descending('rating')) .limit(1) .select( - new FunctionExpr('add', [field('rating'), constant(1)]).as('rating') + new FunctionExpression('add', [field('rating'), constant(1)]).as( + 'rating' + ) ) .execute(); expectResults(snapshot, { @@ -2802,9 +2927,9 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .where( - new BooleanExpr('and', [ - field('rating').gt(0), - field('title').charLength().lt(5), + new BooleanExpression('and', [ + field('rating').greaterThan(0), + field('title').charLength().lessThan(5), field('tags').arrayContains('propaganda'), ]) ) @@ -2820,7 +2945,7 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .where( - new BooleanExpr('array_contains_any', [ + new BooleanExpression('array_contains_any', [ field('tags'), array(['politics']), ]) @@ -2837,9 +2962,9 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .aggregate( - new AggregateFunction('count_if', [field('rating').gte(4.5)]).as( - 'countOfBest' - ) + new AggregateFunction('count_if', [ + field('rating').greaterThanOrEqual(4.5), + ]).as('countOfBest') ) .execute(); expectResults(snapshot, { @@ -2852,7 +2977,7 @@ describe('Pipeline class', () => { .pipeline() .collection(randomCol.path) .sort( - new FunctionExpr('char_length', [field('title')]).ascending(), + new FunctionExpression('char_length', [field('title')]).ascending(), descending('__name__') ) .limit(3) @@ -2873,20 +2998,6 @@ describe('Pipeline class', () => { }); }); - it('supports Rand', async () => { - const snapshot = await firestore - .pipeline() - .collection(randomCol.path) - .limit(10) - .select(rand().as('result')) - .execute(); - expect(snapshot.results.length).to.equal(10); - snapshot.results.forEach((d: PipelineResult) => { - expect(d.get('result')).to.be.lt(1); - expect(d.get('result')).to.be.gte(0); - }); - }); - it('supports array', async () => { const snapshot = await firestore .pipeline() @@ -3087,12 +3198,12 @@ describe('Pipeline class', () => { timestampAdd('timestamp', 'second', 10).as('plus10seconds'), timestampAdd('timestamp', 'microsecond', 10).as('plus10micros'), timestampAdd('timestamp', 'millisecond', 10).as('plus10millis'), - timestampSub('timestamp', 'day', 10).as('minus10days'), - timestampSub('timestamp', 'hour', 10).as('minus10hours'), - timestampSub('timestamp', 'minute', 10).as('minus10minutes'), - timestampSub('timestamp', 'second', 10).as('minus10seconds'), - timestampSub('timestamp', 'microsecond', 10).as('minus10micros'), - timestampSub('timestamp', 'millisecond', 10).as('minus10millis') + timestampSubtract('timestamp', 'day', 10).as('minus10days'), + timestampSubtract('timestamp', 'hour', 10).as('minus10hours'), + timestampSubtract('timestamp', 'minute', 10).as('minus10minutes'), + timestampSubtract('timestamp', 'second', 10).as('minus10seconds'), + timestampSubtract('timestamp', 'microsecond', 10).as('minus10micros'), + timestampSubtract('timestamp', 'millisecond', 10).as('minus10millis') ) .execute(); expectResults(snapshot, { @@ -3131,7 +3242,7 @@ describe('Pipeline class', () => { .collection(randomCol) .limit(1) .select(constant(true).as('trueField')) - .select('trueField', not(eq('trueField', true)).as('falseField')) + .select('trueField', not(equal('trueField', true)).as('falseField')) .execute(); expectResults(snapshot, { @@ -3144,7 +3255,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('tags').arrayReverse().as('reversedTags')) .execute(); @@ -3157,7 +3268,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(arrayReverse('tags').as('reversedTags')) .execute(); @@ -3170,7 +3281,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('rating').ceil().as('ceilingRating')) .execute(); @@ -3183,7 +3294,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(ceil('rating').as('ceilingRating')) .execute(); @@ -3196,7 +3307,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('rating').floor().as('floorRating')) .execute(); @@ -3209,7 +3320,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(floor('rating').as('floorRating')) .execute(); @@ -3222,20 +3333,21 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq('The Lord of the Rings')) + .where(field('title').equal('The Lord of the Rings')) .limit(1) .select(field('rating').exp().as('expRating')) .execute(); - expectResults(snapshot, { - expRating: 109.94717245212352, - }); + expect(snapshot.results[0].get('expRating')).to.be.approximately( + 109.94717245212352, + 0.00001 + ); }); it('can compute e to the power of a numeric value with the top-level function', async () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq('The Lord of the Rings')) + .where(field('title').equal('The Lord of the Rings')) .limit(1) .select(exp('rating').as('expRating')) .execute(); @@ -3249,7 +3361,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('rating').pow(2).as('powerRating')) .execute(); @@ -3263,7 +3375,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(pow('rating', 2).as('powerRating')) .execute(); @@ -3277,7 +3389,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('rating').round().as('roundedRating')) .execute(); @@ -3290,7 +3402,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(round('rating').as('roundedRating')) .execute(); @@ -3303,7 +3415,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .addFields(constant(1.5).as('positiveHalf')) .select(field('positiveHalf').round().as('roundedRating')) @@ -3317,7 +3429,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .addFields(constant(-1.5).as('negativeHalf')) .select(field('negativeHalf').round().as('roundedRating')) @@ -3327,6 +3439,31 @@ describe('Pipeline class', () => { }); }); + it('can round a numeric value to specified precision', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .limit(1) + .replaceWith( + map({ + foo: 4.123456, + }) + ) + .select( + field('foo').round(0).as('0'), + round('foo', 1).as('1'), + round('foo', constant(2)).as('2'), + round(field('foo'), 4).as('4') + ) + .execute(); + expectResults(snapshot, { + '0': 4, + '1': 4.1, + '2': 4.12, + '4': 4.1235, + }); + }); + it('can get the collectionId from a path', async () => { const snapshot = await firestore .pipeline() @@ -3355,7 +3492,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('title').length().as('titleLength')) .execute(); @@ -3368,7 +3505,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(length('title').as('titleLength')) .execute(); @@ -3381,7 +3518,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('tags').length().as('tagsLength')) .execute(); @@ -3394,7 +3531,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(length('tags').as('tagsLength')) .execute(); @@ -3407,7 +3544,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('awards').length().as('awardsLength')) .execute(); @@ -3420,7 +3557,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('embedding').length().as('embeddingLength')) .execute(); @@ -3446,7 +3583,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('rating').ln().as('lnRating')) .execute(); @@ -3457,7 +3594,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(ln('rating').as('lnRating')) .execute(); @@ -3468,7 +3605,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(ln('rating').as('lnRating')) .execute(); @@ -3477,37 +3614,11 @@ describe('Pipeline class', () => { }); }); - it('can compute the logarithm of a numeric value', async () => { - const snapshot = await firestore - .pipeline() - .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) - .limit(1) - .select(field('rating').log(10).as('logRating')) - .execute(); - expectResults(snapshot, { - logRating: 0.6232492903979004, - }); - }); - - it('can compute the logarithm of a numeric value with the top-level function', async () => { - const snapshot = await firestore - .pipeline() - .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) - .limit(1) - .select(log('rating', 10).as('logRating')) - .execute(); - expectResults(snapshot, { - logRating: 0.6232492903979004, - }); - }); - it('can round a numeric value', async () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('rating').round().as('roundedRating')) .execute(); @@ -3520,7 +3631,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(round('rating').as('roundedRating')) .execute(); @@ -3533,7 +3644,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(field('rating').sqrt().as('sqrtRating')) .execute(); @@ -3546,7 +3657,7 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) .select(sqrt('rating').as('sqrtRating')) .execute(); @@ -3559,9 +3670,9 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) - .select(field('title').strReverse().as('reversedTitle')) + .select(field('title').stringReverse().as('reversedTitle')) .execute(); expectResults(snapshot, { reversedTitle: "yxalaG eht ot ediuG s'rekihhctiH ehT", @@ -3572,9 +3683,9 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(field('title').eq("The Hitchhiker's Guide to the Galaxy")) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) .limit(1) - .select(strReverse('title').as('reversedTitle')) + .select(stringReverse('title').as('reversedTitle')) .execute(); expectResults(snapshot, { reversedTitle: "yxalaG eht ot ediuG s'rekihhctiH ehT", @@ -3589,12 +3700,14 @@ describe('Pipeline class', () => { .limit(1) .select( documentId(field('__name__')).as('docId'), - documentId(field('__path__')).as('noDocId') + documentId(field('__path__')).as('noDocId'), + documentId(randomCol.doc('foo')).as('fromDocRef') ) .execute(); expectResults(snapshot, { docId: 'book4', noDocId: null, + fromDocRef: 'foo', }); snapshot = await firestore .pipeline() @@ -3654,6 +3767,33 @@ describe('Pipeline class', () => { }); }); + it('arrayConcat works', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .where(field('title').equal("The Hitchhiker's Guide to the Galaxy")) + .select( + arrayConcat('tags', ['newTag1', 'newTag2'], field('tags'), [null]).as( + 'modifiedTags' + ) + ) + .limit(1) + .execute(); + expectResults(snapshot, { + modifiedTags: [ + 'comedy', + 'space', + 'adventure', + 'newTag1', + 'newTag2', + 'comedy', + 'space', + 'adventure', + null, + ], + }); + }); + it('test toLower', async () => { const snapshot = await firestore .pipeline() @@ -3698,13 +3838,168 @@ describe('Pipeline class', () => { const snapshot = await firestore .pipeline() .collection(randomCol.path) - .where(eq('title', '1984')) + .where(equal('title', '1984')) .limit(1) .select(reverse('title').as('reverseTitle')) .execute(); expectResults(snapshot, {reverseTitle: '4891'}); }); + it('testAbs', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .limit(1) + .select( + constant(-10).as('neg10'), + constant(-22.22).as('neg22'), + constant(1).as('pos1') + ) + .select( + abs('neg10').as('10'), + abs(field('neg22')).as('22'), + field('pos1').as('1') + ) + .execute(); + expectResults(snapshot, { + '10': 10, + '22': 22.22, + '1': 1, + }); + }); + + it('can compute the base-10 logarithm of a numeric value', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .where(field('title').equal('The Lord of the Rings')) + .limit(1) + .select(field('rating').log10().as('log10Rating')) + .execute(); + expect(snapshot.results[0]!.data().log10Rating).to.be.closeTo( + 0.672, + 0.001 + ); + }); + + it('can compute the base-10 logarithm of a numeric value with the top-level function', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .where(field('title').equal('The Lord of the Rings')) + .limit(1) + .select(log10('rating').as('log10Rating')) + .execute(); + expect(snapshot.results[0]!.data().log10Rating).to.be.closeTo( + 0.672, + 0.001 + ); + }); + + it('can concat fields', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .addFields( + concat('author', ' ', field('title')).as('display'), + field('author').concat(': ', field('title')).as('display2') + ) + .where(equal('author', 'Douglas Adams')) + .select('display', 'display2') + .execute(); + expectResults(snapshot, { + display: "Douglas Adams The Hitchhiker's Guide to the Galaxy", + display2: "Douglas Adams: The Hitchhiker's Guide to the Galaxy", + }); + }); + + it('supports currentTimestamp', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .limit(1) + .addFields(currentTimestamp().as('now')) + .select('now') + .execute(); + const now = snapshot.results[0].get('now') as Timestamp; + expect(now).instanceof(Timestamp); + expect( + now.toDate().getUTCSeconds() - new Date().getUTCSeconds() + ).lessThan(5000); + }); + + it('supports ifAbsent', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .limit(1) + .replaceWith( + map({ + title: 'foo', + }) + ) + .select( + ifAbsent('title', 'default title').as('title'), + field('name').ifAbsent('default name').as('name'), + field('name').ifAbsent(field('title')).as('nameOrTitle') + ) + .execute(); + + expectResults(snapshot, { + title: 'foo', + name: 'default name', + nameOrTitle: 'foo', + }); + }); + + it('supports join', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .limit(1) + .replaceWith( + map({ + tags: ['foo', 'bar', 'baz'], + delimeter: '|', + }) + ) + .select(join('tags', ',').as('csv'), field('tags').join('|').as('or')) + .execute(); + + expectResults(snapshot, { + csv: 'foo,bar,baz', + or: 'foo|bar|baz', + }); + }); + + it('can compute the sum of the elements in an array', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .where(field('title').equal('The Lord of the Rings')) + .limit(1) + .addFields(array([150, 200]).as('sales')) + .select(field('sales').arraySum().as('totalSales')) + .execute(); + expectResults(snapshot, { + totalSales: 350, + }); + }); + + it('can compute the sum of the elements in an array with the top-level function', async () => { + const snapshot = await firestore + .pipeline() + .collection(randomCol.path) + .where(field('title').equal('The Lord of the Rings')) + .limit(1) + .addFields(array([150, 200]).as('sales')) + .select(arraySum('sales').as('totalSales')) + .execute(); + expectResults(snapshot, { + totalSales: 350, + }); + }); + // TODO(new-expression): Add new expression tests above this line }); @@ -3793,10 +4088,10 @@ describe('Pipeline class', () => { .where( or( and( - field('rating').eq(lastDoc.get('rating')), - field('__name__').gt(lastDoc.ref) + field('rating').equal(lastDoc.get('rating')), + field('__name__').greaterThan(lastDoc.ref) ), - field('rating').lt(lastDoc.get('rating')) + field('rating').lessThan(lastDoc.get('rating')) ) ) .limit(pageSize) @@ -3980,7 +4275,7 @@ describe('Pipeline class', () => { // This is the Query integration tests from the lite API (no cache support) // with some additional test cases added for more complete coverage. -describe('Query to Pipeline', () => { +describe.skip('Query to Pipeline', () => { async function execute(ppl: Pipeline): Promise { return ppl.execute(); } @@ -4497,7 +4792,7 @@ describe('Query to Pipeline', () => { }); }); - it('supports eq nan', () => { + it('supports equal nan', () => { return testCollectionWithDocs( { 1: {foo: 1, bar: NaN}, @@ -4506,13 +4801,16 @@ describe('Query to Pipeline', () => { }, async (collRef, db) => { const query1 = collRef.where('bar', '==', NaN); + const classicSnapshot = await query1.get(); + const classicData = classicSnapshot.docs.map(d => d.data()); + const snapshot = await execute(db.pipeline().createFrom(query1)); - verifyResults(snapshot, {foo: 1, bar: NaN}); + verifyResults(snapshot, ...classicData); } ); }); - it('supports neq nan', () => { + it('supports notEqual nan', () => { return testCollectionWithDocs( { 1: {foo: 1, bar: NaN}, @@ -4521,13 +4819,17 @@ describe('Query to Pipeline', () => { }, async (collRef, db) => { const query1 = collRef.where('bar', '!=', NaN); + + const classicSnapshot = await query1.get(); + const classicData = classicSnapshot.docs.map(d => d.data()); + const snapshot = await execute(db.pipeline().createFrom(query1)); - verifyResults(snapshot, {foo: 2, bar: 1}); + verifyResults(snapshot, ...classicData); } ); }); - it('supports eq null', () => { + it('supports equal null', () => { return testCollectionWithDocs( { 1: {foo: 1, bar: null}, @@ -4535,13 +4837,16 @@ describe('Query to Pipeline', () => { }, async (collRef, db) => { const query1 = collRef.where('bar', '==', null); + const classicSnapshot = await query1.get(); + const classicData = classicSnapshot.docs.map(d => d.data()); + const snapshot = await execute(db.pipeline().createFrom(query1)); - verifyResults(snapshot, {foo: 1, bar: null}); + verifyResults(snapshot, ...classicData); } ); }); - it('supports neq null', () => { + it('supports notEqual null', () => { return testCollectionWithDocs( { 1: {foo: 1, bar: null}, @@ -4549,13 +4854,15 @@ describe('Query to Pipeline', () => { }, async (collRef, db) => { const query1 = collRef.where('bar', '!=', null); + const classicSnapshot = await query1.get(); + const classicData = classicSnapshot.docs.map(d => d.data()); const snapshot = await execute(db.pipeline().createFrom(query1)); - verifyResults(snapshot, {foo: 2, bar: 1}); + verifyResults(snapshot, ...classicData); } ); }); - it('supports neq', () => { + it('supports notEqual', () => { return testCollectionWithDocs( { 1: {foo: 1, bar: 0}, diff --git a/dev/system-test/query.ts b/dev/system-test/query.ts index 877016419..a5acbce28 100644 --- a/dev/system-test/query.ts +++ b/dev/system-test/query.ts @@ -128,7 +128,7 @@ describe('Query class', () => { query: VectorQuery ): Promise { const queryResults = await query.get(); - const pipeline = query.toPipeline(); + const pipeline = query.query.firestore.pipeline().createFrom(query); const pipelineResults = await pipeline.execute(); expect(pipelineResults.results.map(r => r._fieldsProto)).to.deep.equal( diff --git a/dev/test/pipelines/pipeline.ts b/dev/test/pipelines/pipeline.ts index 69b9a3b84..b0106f57f 100644 --- a/dev/test/pipelines/pipeline.ts +++ b/dev/test/pipelines/pipeline.ts @@ -399,7 +399,7 @@ describe('stage option serialization', () => { .pipeline() .database() .where({ - condition: field('foo').eq(1), + condition: field('foo').equal(1), rawOptions, }), stageIndex: 1, diff --git a/dev/test/structured-pipeline.ts b/dev/test/structured-pipeline.ts index 89b0af406..80499a7f1 100644 --- a/dev/test/structured-pipeline.ts +++ b/dev/test/structured-pipeline.ts @@ -63,7 +63,7 @@ describe('StructuredPipeline', () => { indexMode: 'recommended', explainOptions: { mode: 'explain', - outputFormat: 'json', + outputFormat: 'text', }, }, {} @@ -84,7 +84,7 @@ describe('StructuredPipeline', () => { stringValue: 'explain', }, output_format: { - stringValue: 'json', + stringValue: 'text', }, }, }, @@ -109,8 +109,6 @@ describe('StructuredPipeline', () => { const proto = structuredPipeline._toProto(new Serializer(db!)); - console.log(JSON.stringify(proto)); - expect(proto).to.deep.equal({ pipeline: {}, options: { diff --git a/samples/pipelines-quickstart.js b/samples/pipelines-quickstart.js index aadec0992..552dca1bc 100644 --- a/samples/pipelines-quickstart.js +++ b/samples/pipelines-quickstart.js @@ -43,7 +43,7 @@ async function quickstartPipelines() { .pipeline() .collection('posts') .select('rating', field('title').toUpper().as('lowercaseTitle')) - .where(field('rating').gt(5)); + .where(field('rating').greaterThan(5)); // Execute the Pipeline against the Firestore server. const pipelineSnapshot = await myPipeline.execute(); diff --git a/types/firestore.d.ts b/types/firestore.d.ts index b618c03a5..a2195f6e0 100644 --- a/types/firestore.d.ts +++ b/types/firestore.d.ts @@ -925,7 +925,7 @@ declare namespace FirebaseFirestore { * const futureResults = await transaction * .execute( * firestore.pipeline().collection("books") - * .where(gt(Field.of("rating"), 4.5)) + * .where(greaterThan(Field.of("rating"), 4.5)) * .select("title", "author", "rating")); * ``` * @@ -3122,28 +3122,24 @@ declare namespace FirebaseFirestore { */ distanceThreshold?: number; } - - /** - * @beta - */ export namespace Pipelines { /** * @beta * Represents an expression that has been assigned an alias using the `.as()` method. * - * This class wraps an existing {@link Expr} and associates it with a user-defined alias, + * This class wraps an existing {@link Expression} and associates it with a user-defined alias, * allowing the expression's result to be referred to by a different name in the output * of a Firestore pipeline query, particularly within `select()` operations. * * @internal */ - export type ExprType = + export type ExpressionType = | 'Field' | 'Constant' | 'Function' | 'AggregateFunction' | 'ListOfExprs' - | 'AliasedExpr'; + | 'AliasedExpression'; /** * @beta * Represents an expression that can be evaluated to a value within the execution of a {@link @@ -3156,11 +3152,11 @@ declare namespace FirebaseFirestore { * - **Literals:** Represent constant values (strings, numbers, booleans). * - **Function calls:** Apply functions to one or more expressions. * - * The `Expr` class provides a fluent API for building expressions. You can chain together + * The `Expression` class provides a fluent API for building expressions. You can chain together * method calls to create complex expressions. */ - export abstract class Expr { - abstract readonly exprType: ExprType; + export abstract class Expression { + abstract readonly expressionType: ExpressionType; /** * @beta * Creates an expression that adds this expression to another expression. @@ -3172,12 +3168,12 @@ declare namespace FirebaseFirestore { * * @param second The expression or literal to add to this expression. * @param others Optional additional expressions or literals to add to this expression. - * @return A new `Expr` representing the addition operation. + * @return A new `Expression` representing the addition operation. */ add( - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta * Creates an expression that subtracts another expression from this expression. @@ -3188,9 +3184,9 @@ declare namespace FirebaseFirestore { * ``` * * @param subtrahend The expression to subtract from this expression. - * @return A new `Expr` representing the subtraction operation. + * @return A new `Expression` representing the subtraction operation. */ - subtract(subtrahend: Expr): FunctionExpr; + subtract(subtrahend: Expression): FunctionExpression; /** * @beta * Creates an expression that subtracts a constant value from this expression. @@ -3201,9 +3197,9 @@ declare namespace FirebaseFirestore { * ``` * * @param subtrahend The constant value to subtract. - * @return A new `Expr` representing the subtraction operation. + * @return A new `Expression` representing the subtraction operation. */ - subtract(subtrahend: number): FunctionExpr; + subtract(subtrahend: number): FunctionExpression; /** * @beta * Creates an expression that multiplies this expression by another expression. @@ -3215,12 +3211,12 @@ declare namespace FirebaseFirestore { * * @param second The second expression or literal to multiply by. * @param others Optional additional expressions or literals to multiply by. - * @return A new `Expr` representing the multiplication operation. + * @return A new `Expression` representing the multiplication operation. */ multiply( - second: Expr | number, - ...others: Array - ): FunctionExpr; + second: Expression | number, + ...others: Array + ): FunctionExpression; /** * @beta * Creates an expression that divides this expression by another expression. @@ -3231,9 +3227,9 @@ declare namespace FirebaseFirestore { * ``` * * @param divisor The expression to divide by. - * @return A new `Expr` representing the division operation. + * @return A new `Expression` representing the division operation. */ - divide(divisor: Expr): FunctionExpr; + divide(divisor: Expression): FunctionExpression; /** * @beta * Creates an expression that divides this expression by a constant value. @@ -3244,9 +3240,9 @@ declare namespace FirebaseFirestore { * ``` * * @param divisor The constant value to divide by. - * @return A new `Expr` representing the division operation. + * @return A new `Expression` representing the division operation. */ - divide(divisor: number): FunctionExpr; + divide(divisor: number): FunctionExpression; /** * @beta * Creates an expression that calculates the modulo (remainder) of dividing this expression by another expression. @@ -3257,9 +3253,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expression The expression to divide by. - * @return A new `Expr` representing the modulo operation. + * @return A new `Expression` representing the modulo operation. */ - mod(expression: Expr): FunctionExpr; + mod(expression: Expression): FunctionExpression; /** * @beta * Creates an expression that calculates the modulo (remainder) of dividing this expression by a constant value. @@ -3270,9 +3266,9 @@ declare namespace FirebaseFirestore { * ``` * * @param value The constant value to divide by. - * @return A new `Expr` representing the modulo operation. + * @return A new `Expression` representing the modulo operation. */ - mod(value: number): FunctionExpr; + mod(value: number): FunctionExpression; /** * @beta @@ -3280,29 +3276,29 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'age' field is equal to the value of another field named 'otherAge'. - * field("age").eq(field("otherAge")); + * field("age").equal(field("otherAge")); * * // Check if the 'status' field is equal to a string literal. - * field("status").eq("active"); + * field("status").equal("active"); * ``` * * @param expression The expression to compare for equality. - * @return A new `BooleanExpr` representing the equality comparison. + * @return A new `BooleanExpression` representing the equality comparison. */ - eq(expression: Expr): BooleanExpr; + equal(expression: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if this expression is equal to a constant value. * * ```typescript * // Check if the 'city' field is equal to "London" - * field("city").eq("London"); + * field("city").equal("London"); * ``` * * @param value The constant value to compare for equality. - * @return A new `Expr` representing the equality comparison. + * @return A new `Expression` representing the equality comparison. */ - eq(value: unknown): BooleanExpr; + equal(value: unknown): BooleanExpression; /** * @beta @@ -3310,26 +3306,26 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'status' field is not equal to "completed" - * field("status").neq("completed"); + * field("status").notEqual("completed"); * ``` * * @param expression The expression to compare for inequality. - * @return A new {@link BooleanExpr} representing the inequality comparison. + * @return A new {@link BooleanExpression} representing the inequality comparison. */ - neq(expression: Expr): BooleanExpr; + notEqual(expression: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if this expression is not equal to a constant value. * * ```typescript * // Check if the 'country' field is not equal to "USA" - * field("country").neq("USA"); + * field("country").notEqual("USA"); * ``` * * @param value The constant value to compare for inequality. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ - neq(value: unknown): BooleanExpr; + notEqual(value: unknown): BooleanExpression; /** * @beta @@ -3337,26 +3333,26 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'age' field is less than 'limit' - * field("age").lt(field('limit')); + * field("age").lessThan(field('limit')); * ``` * * @param expression The expression to compare against. - * @return A new `BooleanExpr` representing the less than comparison. + * @return A new `BooleanExpression` representing the less than comparison. */ - lt(expression: Expr): BooleanExpr; + lessThan(expression: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if this expression is less than a constant value. * * ```typescript * // Check if the 'price' field is less than 50 - * field("price").lt(50); + * field("price").lessThan(50); * ``` * * @param value The constant value to compare for less than. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ - lt(value: unknown): BooleanExpr; + lessThan(value: unknown): BooleanExpression; /** * @beta @@ -3364,26 +3360,26 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'quantity' field is less than or equal to 20 - * field("quantity").lte(constant(20)); + * field("quantity").lessThanOrEqual(constant(20)); * ``` * * @param expression The expression to compare against. - * @return A new `BooleanExpr` representing the less than or equal to comparison. + * @return A new `BooleanExpression` representing the less than or equal to comparison. */ - lte(expression: Expr): BooleanExpr; + lessThanOrEqual(expression: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if this expression is less than or equal to a constant value. * * ```typescript * // Check if the 'score' field is less than or equal to 70 - * field("score").lte(70); + * field("score").lessThanOrEqual(70); * ``` * * @param value The constant value to compare for less than or equal to. - * @return A new `Expr` representing the less than or equal to comparison. + * @return A new `Expression` representing the less than or equal to comparison. */ - lte(value: unknown): BooleanExpr; + lessThanOrEqual(value: unknown): BooleanExpression; /** * @beta @@ -3391,26 +3387,26 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'age' field is greater than the 'limit' field - * field("age").gt(field("limit")); + * field("age").greaterThan(field("limit")); * ``` * * @param expression The expression to compare for greater than. - * @return A new {@link BooleanExpr} representing the greater than comparison. + * @return A new {@link BooleanExpression} representing the greater than comparison. */ - gt(expression: Expr): BooleanExpr; + greaterThan(expression: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if this expression is greater than a constant value. * * ```typescript * // Check if the 'price' field is greater than 100 - * field("price").gt(100); + * field("price").greaterThan(100); * ``` * * @param value The constant value to compare for greater than. - * @return A new `Expr` representing the greater than comparison. + * @return A new `Expression` representing the greater than comparison. */ - gt(value: unknown): BooleanExpr; + greaterThan(value: unknown): BooleanExpression; /** * @beta * Creates an expression that checks if this expression is greater than or equal to another @@ -3418,13 +3414,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'quantity' field is greater than or equal to field 'requirement' plus 1 - * field("quantity").gte(field('requirement').add(1)); + * field("quantity").greaterThanOrEqual(field('requirement').add(1)); * ``` * * @param expression The expression to compare for greater than or equal to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ - gte(expression: Expr): BooleanExpr; + greaterThanOrEqual(expression: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if this expression is greater than or equal to a constant @@ -3432,13 +3428,31 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'score' field is greater than or equal to 80 - * field("score").gte(80); + * field("score").greaterThanOrEqual(80); * ``` * * @param value The constant value to compare for greater than or equal to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. + */ + greaterThanOrEqual(value: unknown): BooleanExpression; + + /** + * @beta + * Creates an expression that concatenates an array expression with one or more other arrays. + * + * ```typescript + * // Combine the 'items' array with another array field. + * field("items").arrayConcat(field("otherItems")); + * ``` + * @param secondArray Second array expression or array literal to concatenate. + * @param otherArrays Optional additional array expressions or array literals to concatenate. + * @return A new `Expr` representing the concatenated array. */ - gte(value: unknown): BooleanExpr; + arrayConcat( + secondArray: Expression | unknown[], + ...otherArrays: Array + ): FunctionExpression; + /** * @beta * Creates an expression that checks if an array contains a specific element. @@ -3449,9 +3463,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expression The element to search for in the array. - * @return A new `Expr` representing the 'array_contains' comparison. + * @return A new `Expression` representing the 'array_contains' comparison. */ - arrayContains(expression: Expr): BooleanExpr; + arrayContains(expression: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if an array contains a specific value. @@ -3462,9 +3476,9 @@ declare namespace FirebaseFirestore { * ``` * * @param value The element to search for in the array. - * @return A new `Expr` representing the 'array_contains' comparison. + * @return A new `Expression` representing the 'array_contains' comparison. */ - arrayContains(value: unknown): BooleanExpr; + arrayContains(value: unknown): BooleanExpression; /** * @beta * Creates an expression that checks if an array contains all the specified elements. @@ -3475,9 +3489,9 @@ declare namespace FirebaseFirestore { * ``` * * @param values The elements to check for in the array. - * @return A new `Expr` representing the 'array_contains_all' comparison. + * @return A new `Expression` representing the 'array_contains_all' comparison. */ - arrayContainsAll(values: Array): BooleanExpr; + arrayContainsAll(values: Array): BooleanExpression; /** * @beta * Creates an expression that checks if an array contains all the specified elements. @@ -3488,9 +3502,9 @@ declare namespace FirebaseFirestore { * ``` * * @param arrayExpression The elements to check for in the array. - * @return A new `Expr` representing the 'array_contains_all' comparison. + * @return A new `Expression` representing the 'array_contains_all' comparison. */ - arrayContainsAll(arrayExpression: Expr): BooleanExpr; + arrayContainsAll(arrayExpression: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if an array contains any of the specified elements. @@ -3501,9 +3515,9 @@ declare namespace FirebaseFirestore { * ``` * * @param values The elements to check for in the array. - * @return A new `Expr` representing the 'array_contains_any' comparison. + * @return A new `Expression` representing the 'array_contains_any' comparison. */ - arrayContainsAny(values: Array): BooleanExpr; + arrayContainsAny(values: Array): BooleanExpression; /** * @beta * Creates an expression that checks if an array contains any of the specified elements. @@ -3515,9 +3529,9 @@ declare namespace FirebaseFirestore { * ``` * * @param arrayExpression The elements to check for in the array. - * @return A new `Expr` representing the 'array_contains_any' comparison. + * @return A new `Expression` representing the 'array_contains_any' comparison. */ - arrayContainsAny(arrayExpression: Expr): BooleanExpr; + arrayContainsAny(arrayExpression: Expression): BooleanExpression; /** * @beta * Creates an expression that calculates the length of an array. @@ -3527,9 +3541,9 @@ declare namespace FirebaseFirestore { * field("cart").arrayLength(); * ``` * - * @return A new `Expr` representing the length of the array. + * @return A new `Expression` representing the length of the array. */ - arrayLength(): FunctionExpr; + arrayLength(): FunctionExpression; /** * @beta @@ -3538,13 +3552,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'category' field is either "Electronics" or the value of field 'primaryType' - * field("category").eqAny(["Electronics", field("primaryType")]); + * field("category").equalAny(["Electronics", field("primaryType")]); * ``` * * @param values An array of values or expressions to check against. - * @return A new `BooleanExpr` representing the 'IN' comparison. + * @return A new `BooleanExpression` representing the 'IN' comparison. */ - eqAny(values: Array): BooleanExpr; + equalAny(values: Array): BooleanExpression; /** * @beta * Creates an expression that checks if this expression is equal to any of the provided values or @@ -3552,13 +3566,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'category' field is either "Electronics" or the value of field 'primaryType' - * field("category").eqAny(array(["Electronics", field("primaryType")])); + * field("category").equalAny(array(["Electronics", field("primaryType")])); * ``` * * @param arrayExpression An expression that evaluates to an array of values to check against. - * @return A new `Expr` representing the 'IN' comparison. + * @return A new `Expression` representing the 'IN' comparison. */ - eqAny(arrayExpression: Expr): BooleanExpr; + equalAny(arrayExpression: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if this expression is not equal to any of the provided values or @@ -3566,13 +3580,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus' - * field("status").notEqAny(["pending", field("rejectedStatus")]); + * field("status").notEqualAny(["pending", field("rejectedStatus")]); * ``` * * @param values The values or expressions to check against. - * @return A new `Expr` representing the 'NotEqAny' comparison. + * @return A new `Expression` representing the 'NotEqAny' comparison. */ - notEqAny(values: Array): BooleanExpr; + notEqualAny(values: Array): BooleanExpression; /** * @beta @@ -3580,38 +3594,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'status' field is not equal to any value in the array returned by the 'rejectedStatuses' field. - * field("status").notEqAny(field('rejectedStatuses')); - * ``` - * - * @param arrayExpression An `Expr` that evaluates to an array of values to compare against. - * @return A new `BooleanExpr` representing the result of the 'not equal to any' comparison. - */ - notEqAny(arrayExpression: Expr): BooleanExpr; - /** - * @beta - * Creates an expression that checks if this expression evaluates to 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NaN - * field("value").divide(0).isNaN(); - * ``` - * - * @return A new `Expr` representing the 'isNaN' check. - */ - isNan(): BooleanExpr; - - /** - * @beta - * Creates an expression that checks if this expression evaluates to `null`. - * - * ```typescript - * // Check if the 'status' field is null. - * field("status").isNull(); + * field("status").notEqualAny(field('rejectedStatuses')); * ``` * - * @return A new `BooleanExpr` representing the `isNull` check. + * @param arrayExpression An `Expression` that evaluates to an array of values to compare against. + * @return A new `BooleanExpression` representing the result of the 'not equal to any' comparison. */ - isNull(): BooleanExpr; + notEqualAny(arrayExpression: Expression): BooleanExpression; /** * @beta @@ -3622,9 +3611,9 @@ declare namespace FirebaseFirestore { * field("phoneNumber").exists(); * ``` * - * @returns A new {@link BooleanExpr} representing the 'exists' check. + * @returns A new {@link BooleanExpression} representing the 'exists' check. */ - exists(): BooleanExpr; + exists(): BooleanExpression; /** * @beta * Creates an expression that calculates the character length of a string in UTF-8. @@ -3634,9 +3623,9 @@ declare namespace FirebaseFirestore { * field("name").charLength(); * ``` * - * @return A new `Expr` representing the length of the string. + * @return A new `Expression` representing the length of the string. */ - charLength(): FunctionExpr; + charLength(): FunctionExpression; /** * @beta @@ -3648,9 +3637,9 @@ declare namespace FirebaseFirestore { * ``` * * @param pattern The string pattern to search for. You can use "%" as a wildcard character within the pattern. - * @return A new {@link FunctionExpr} representing the 'like' comparison. + * @return A new {@link FunctionExpression} representing the 'like' comparison. */ - like(pattern: string): FunctionExpr; + like(pattern: string): FunctionExpression; /** * @beta @@ -3661,10 +3650,10 @@ declare namespace FirebaseFirestore { * field("description").like(field("searchPattern")); * ``` * - * @param pattern An {@link Expr} that evaluates to the string pattern to search for. You can use "%" as a wildcard character within the pattern. - * @return A new {@link FunctionExpr} representing the 'like' comparison. + * @param pattern An {@link Expression} that evaluates to the string pattern to search for. You can use "%" as a wildcard character within the pattern. + * @return A new {@link FunctionExpression} representing the 'like' comparison. */ - like(pattern: Expr): FunctionExpr; + like(pattern: Expression): FunctionExpression; /** * @beta * Creates an expression that checks if a string contains a specified regular expression as a @@ -3676,9 +3665,9 @@ declare namespace FirebaseFirestore { * ``` * * @param pattern The regular expression to use for the search. - * @return A new `Expr` representing the 'contains' comparison. + * @return A new `Expression` representing the 'contains' comparison. */ - regexContains(pattern: string): BooleanExpr; + regexContains(pattern: string): BooleanExpression; /** * @beta @@ -3691,9 +3680,9 @@ declare namespace FirebaseFirestore { * ``` * * @param pattern The regular expression to use for the search. - * @return A new {@link BooleanExpr} representing the 'contains' comparison. + * @return A new {@link BooleanExpression} representing the 'contains' comparison. */ - regexContains(pattern: Expr): BooleanExpr; + regexContains(pattern: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if a string matches a specified regular expression. @@ -3704,9 +3693,9 @@ declare namespace FirebaseFirestore { * ``` * * @param pattern The regular expression to use for the match. - * @return A new `Expr` representing the regular expression match. + * @return A new `Expression` representing the regular expression match. */ - regexMatch(pattern: string): BooleanExpr; + regexMatch(pattern: string): BooleanExpression; /** * @beta @@ -3718,22 +3707,22 @@ declare namespace FirebaseFirestore { * ``` * * @param pattern An expression that evaluates to the regular expression string to use for the match. - * @return A new `BooleanExpr` representing the result of the regular expression match. + * @return A new `BooleanExpression` representing the result of the regular expression match. */ - regexMatch(pattern: Expr): BooleanExpr; + regexMatch(pattern: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if a string contains a specified substring. * * ```typescript * // Check if the 'description' field contains "example". - * field("description").strContains("example"); + * field("description").stringContains("example"); * ``` * * @param substring The substring to search for. - * @return A new `Expr` representing the 'contains' comparison. + * @return A new `Expression` representing the 'contains' comparison. */ - strContains(substring: string): BooleanExpr; + stringContains(substring: string): BooleanExpression; /** * @beta @@ -3741,13 +3730,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'description' field contains the value of the 'keyword' field. - * field("description").strContains(field("keyword")); + * field("description").stringContains(field("keyword")); * ``` * * @param expr The expression representing the substring to search for. - * @return A new {@link BooleanExpr} representing the 'contains' comparison. + * @return A new {@link BooleanExpression} representing the 'contains' comparison. */ - strContains(expr: Expr): BooleanExpr; + stringContains(expr: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if a string starts with a given prefix. @@ -3758,9 +3747,9 @@ declare namespace FirebaseFirestore { * ``` * * @param prefix The prefix to check for. - * @return A new `Expr` representing the 'starts with' comparison. + * @return A new `Expression` representing the 'starts with' comparison. */ - startsWith(prefix: string): BooleanExpr; + startsWith(prefix: string): BooleanExpression; /** * @beta @@ -3772,9 +3761,9 @@ declare namespace FirebaseFirestore { * ``` * * @param prefix An expression whose string value will be used as the prefix to check against. - * @returns A new `BooleanExpr` representing the 'starts with' comparison result. + * @returns A new `BooleanExpression` representing the 'starts with' comparison result. */ - startsWith(prefix: Expr): BooleanExpr; + startsWith(prefix: Expression): BooleanExpression; /** * @beta @@ -3786,9 +3775,9 @@ declare namespace FirebaseFirestore { * ``` * * @param suffix The postfix to check for. - * @return A new {@link BooleanExpr} representing the 'ends with' comparison. + * @return A new {@link BooleanExpression} representing the 'ends with' comparison. */ - endsWith(suffix: string): BooleanExpr; + endsWith(suffix: string): BooleanExpression; /** * @beta * Creates an expression that checks if a string ends with a given postfix (represented as an @@ -3800,9 +3789,9 @@ declare namespace FirebaseFirestore { * ``` * * @param suffix The postfix expression to check for. - * @return A new `Expr` representing the 'ends with' comparison. + * @return A new `Expression` representing the 'ends with' comparison. */ - endsWith(suffix: Expr): BooleanExpr; + endsWith(suffix: Expression): BooleanExpression; /** * @beta * Creates an expression that converts a string to lowercase. @@ -3812,9 +3801,9 @@ declare namespace FirebaseFirestore { * field("name").toLower(); * ``` * - * @return A new `Expr` representing the lowercase string. + * @return A new `Expression` representing the lowercase string. */ - toLower(): FunctionExpr; + toLower(): FunctionExpression; /** * @beta * Creates an expression that converts a string to uppercase. @@ -3824,9 +3813,9 @@ declare namespace FirebaseFirestore { * field("title").toUpper(); * ``` * - * @return A new `Expr` representing the uppercase string. + * @return A new `Expression` representing the uppercase string. */ - toUpper(): FunctionExpr; + toUpper(): FunctionExpression; /** * @beta * Creates an expression that removes leading and trailing whitespace from a string. @@ -3836,38 +3825,38 @@ declare namespace FirebaseFirestore { * field("userInput").trim(); * ``` * - * @return A new `Expr` representing the trimmed string. + * @return A new `Expression` representing the trimmed string. */ - trim(): FunctionExpr; + trim(): FunctionExpression; /** * @beta * Creates an expression that concatenates string expressions together. * * ```typescript * // Combine the 'firstName', " ", and 'lastName' fields into a single string - * field("firstName").strConcat(constant(" "), field("lastName")); + * field("firstName").stringConcat(constant(" "), field("lastName")); * ``` * * @param secondString The additional expression or string literal to concatenate. * @param otherStrings Optional additional expressions or string literals to concatenate. - * @return A new `Expr` representing the concatenated string. + * @return A new `Expression` representing the concatenated string. */ - strConcat( - secondString: Expr | string, - ...otherStrings: Array - ): FunctionExpr; + stringConcat( + secondString: Expression | string, + ...otherStrings: Array + ): FunctionExpression; /** * @beta - * Creates an expression that reverses this string expression. + * Creates an expression that reverses this string or bytes expression. * * ```typescript * // Reverse the value of the 'myString' field. * field("myString").reverse(); * ``` * - * @return A new {@code Expr} representing the reversed string. + * @return A new {@code Expression} representing the reversed string or bytes. */ - reverse(): FunctionExpr; + reverse(): FunctionExpression; /** * @beta * Creates an expression that calculates the length of this string expression in bytes. @@ -3877,9 +3866,9 @@ declare namespace FirebaseFirestore { * field("myString").byteLength(); * ``` * - * @return A new {@code Expr} representing the length of the string in bytes. + * @return A new {@code Expression} representing the length of the string in bytes. */ - byteLength(): FunctionExpr; + byteLength(): FunctionExpression; /** * @beta * Creates an expression that computes the ceiling of a numeric value. @@ -3889,9 +3878,9 @@ declare namespace FirebaseFirestore { * field("price").ceil(); * ``` * - * @return A new {@code Expr} representing the ceiling of the numeric value. + * @return A new {@code Expression} representing the ceiling of the numeric value. */ - ceil(): FunctionExpr; + ceil(): FunctionExpression; /** * @beta * Creates an expression that computes the floor of a numeric value. @@ -3901,9 +3890,22 @@ declare namespace FirebaseFirestore { * field("price").floor(); * ``` * - * @return A new {@code Expr} representing the floor of the numeric value. + * @return A new {@code Expression} representing the floor of the numeric value. */ - floor(): FunctionExpr; + floor(): FunctionExpression; + + /** + * @beta + * Creates an expression that computes the absolute value of a numeric value. + * + * ```typescript + * // Compute the absolute value of the 'price' field. + * field("price").abs(); + * ``` + * + * @return A new {@code Expr} representing the absolute value of the numeric value. + */ + abs(): FunctionExpression; /** * @beta @@ -3914,9 +3916,9 @@ declare namespace FirebaseFirestore { * field("value").exp(); * ``` * - * @return A new {@code FunctionExpr} representing `e` raised to the power of the numeric value. + * @return A new {@code FunctionExpression} representing `e` raised to the power of the numeric value. */ - exp(): FunctionExpr; + exp(): FunctionExpression; /** * @beta * Creates an aggregation that counts the number of distinct values of the expression or field. @@ -3934,9 +3936,9 @@ declare namespace FirebaseFirestore { * ``` * * @param subfield The key to access in the map. - * @return A new `Expr` representing the value associated with the given key in the map. + * @return A new `Expression` representing the value associated with the given key in the map. */ - mapGet(subfield: string): FunctionExpr; + mapGet(subfield: string): FunctionExpression; /** * @beta * Creates an aggregation that counts the number of stage inputs with valid evaluations of the @@ -3969,12 +3971,12 @@ declare namespace FirebaseFirestore { * * ```typescript * // Calculate the average age of users - * field("age").avg().as("averageAge"); + * field("age").average().as("averageAge"); * ``` * - * @return A new `AggregateFunction` representing the 'avg' aggregation. + * @return A new `AggregateFunction` representing the 'average' aggregation. */ - avg(): AggregateFunction; + average(): AggregateFunction; /** * @beta * Creates an aggregation that finds the minimum value of a field across multiple stage inputs. @@ -4010,12 +4012,12 @@ declare namespace FirebaseFirestore { * * @param second The second expression or literal to compare with. * @param others Optional additional expressions or literals to compare with. - * @return A new {@code Expr} representing the logical max operation. + * @return A new {@code Expression} representing the logical max operation. */ logicalMaximum( - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta * Creates an expression that returns the smaller value between this expression and another expression, based on Firestore's value type ordering. @@ -4027,12 +4029,12 @@ declare namespace FirebaseFirestore { * * @param second The second expression or literal to compare with. * @param others Optional additional expressions or literals to compare with. - * @return A new {@code Expr} representing the logical min operation. + * @return A new {@code Expression} representing the logical min operation. */ logicalMinimum( - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta * Creates an expression that calculates the length (number of dimensions) of this Firestore Vector expression. @@ -4042,9 +4044,9 @@ declare namespace FirebaseFirestore { * field("embedding").vectorLength(); * ``` * - * @return A new {@code Expr} representing the length of the vector. + * @return A new {@code Expression} representing the length of the vector. */ - vectorLength(): FunctionExpr; + vectorLength(): FunctionExpression; /** * @beta * Calculates the cosine distance between two vectors. @@ -4054,10 +4056,10 @@ declare namespace FirebaseFirestore { * field("userVector").cosineDistance(field("itemVector")); * ``` * - * @param vectorExpression The other vector (represented as an Expr) to compare against. - * @return A new `Expr` representing the cosine distance between the two vectors. + * @param vectorExpression The other vector (represented as an Expression) to compare against. + * @return A new `Expression` representing the cosine distance between the two vectors. */ - cosineDistance(vectorExpression: Expr): FunctionExpr; + cosineDistance(vectorExpression: Expression): FunctionExpression; /** * @beta @@ -4072,9 +4074,9 @@ declare namespace FirebaseFirestore { * ``` * * @param vector The other vector to compare against, provided as either a `VectorValue` object or a plain `number[]` array. - * @return A new `FunctionExpr` representing the Cosine distance between the two vectors. + * @return A new `FunctionExpression` representing the Cosine distance between the two vectors. */ - cosineDistance(vector: VectorValue | number[]): FunctionExpr; + cosineDistance(vector: VectorValue | number[]): FunctionExpression; /** * @beta * Calculates the dot product between the current expression (representing a vector) @@ -4087,10 +4089,10 @@ declare namespace FirebaseFirestore { * field("features").dotProduct(field("targetVector")); * ``` * - * @param vectorExpression An {@link Expr} representing the second vector. - * @returns A new {@link FunctionExpr} representing the dot product of the two vectors. + * @param vectorExpression An {@link Expression} representing the second vector. + * @returns A new {@link FunctionExpression} representing the dot product of the two vectors. */ - dotProduct(vectorExpression: Expr): FunctionExpr; + dotProduct(vectorExpression: Expression): FunctionExpression; /** * @beta @@ -4102,9 +4104,9 @@ declare namespace FirebaseFirestore { * ``` * * @param vector The other vector to calculate the dot product with. This can be a `VectorValue` object or a plain array of numbers. - * @return A new `Expr` representing the dot product between the two vectors. + * @return A new `Expression` representing the dot product between the two vectors. */ - dotProduct(vector: VectorValue | number[]): FunctionExpr; + dotProduct(vector: VectorValue | number[]): FunctionExpression; /** * @beta @@ -4115,10 +4117,10 @@ declare namespace FirebaseFirestore { * field("vectorA").euclideanDistance(field("vectorB")); * ``` * - * @param vectorExpression An {@link Expr} that evaluates to the second vector (an array of numbers) for the distance calculation. - * @return A new {@link FunctionExpr} representing the Euclidean distance between the two vectors. + * @param vectorExpression An {@link Expression} that evaluates to the second vector (an array of numbers) for the distance calculation. + * @return A new {@link FunctionExpression} representing the Euclidean distance between the two vectors. */ - euclideanDistance(vectorExpression: Expr): FunctionExpr; + euclideanDistance(vectorExpression: Expression): FunctionExpression; /** * @beta * Calculates the Euclidean distance between two vectors. @@ -4134,9 +4136,9 @@ declare namespace FirebaseFirestore { * ``` * * @param vector The other vector (as a `VectorValue` or `number[]`) to compare against. - * @return A new `Expr` representing the Euclidean distance between the two vectors. + * @return A new `Expression` representing the Euclidean distance between the two vectors. */ - euclideanDistance(vector: VectorValue | number[]): FunctionExpr; + euclideanDistance(vector: VectorValue | number[]): FunctionExpression; /** * @beta * Creates an expression that interprets this expression as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC) @@ -4147,9 +4149,9 @@ declare namespace FirebaseFirestore { * field("microseconds").unixMicrosToTimestamp(); * ``` * - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - unixMicrosToTimestamp(): FunctionExpr; + unixMicrosToTimestamp(): FunctionExpression; /** * @beta * Creates an expression that converts this timestamp expression to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC). @@ -4159,9 +4161,9 @@ declare namespace FirebaseFirestore { * field("timestamp").timestampToUnixMicros(); * ``` * - * @return A new {@code Expr} representing the number of microseconds since epoch. + * @return A new {@code Expression} representing the number of microseconds since epoch. */ - timestampToUnixMicros(): FunctionExpr; + timestampToUnixMicros(): FunctionExpression; /** * @beta * Creates an expression that interprets this expression as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC) @@ -4172,9 +4174,9 @@ declare namespace FirebaseFirestore { * field("milliseconds").unixMillisToTimestamp(); * ``` * - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - unixMillisToTimestamp(): FunctionExpr; + unixMillisToTimestamp(): FunctionExpression; /** * @beta * Creates an expression that converts this timestamp expression to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC). @@ -4184,9 +4186,9 @@ declare namespace FirebaseFirestore { * field("timestamp").timestampToUnixMillis(); * ``` * - * @return A new {@code Expr} representing the number of milliseconds since epoch. + * @return A new {@code Expression} representing the number of milliseconds since epoch. */ - timestampToUnixMillis(): FunctionExpr; + timestampToUnixMillis(): FunctionExpression; /** * @beta * Creates an expression that interprets this expression as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC) @@ -4197,9 +4199,9 @@ declare namespace FirebaseFirestore { * field("seconds").unixSecondsToTimestamp(); * ``` * - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - unixSecondsToTimestamp(): FunctionExpr; + unixSecondsToTimestamp(): FunctionExpression; /** * @beta * Creates an expression that converts this timestamp expression to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC). @@ -4209,9 +4211,9 @@ declare namespace FirebaseFirestore { * field("timestamp").timestampToUnixSeconds(); * ``` * - * @return A new {@code Expr} representing the number of seconds since epoch. + * @return A new {@code Expression} representing the number of seconds since epoch. */ - timestampToUnixSeconds(): FunctionExpr; + timestampToUnixSeconds(): FunctionExpression; /** * @beta * Creates an expression that adds a specified amount of time to this timestamp expression. @@ -4223,9 +4225,9 @@ declare namespace FirebaseFirestore { * * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. * @param amount The expression evaluates to amount of the unit. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ - timestampAdd(unit: Expr, amount: Expr): FunctionExpr; + timestampAdd(unit: Expression, amount: Expression): FunctionExpression; /** * @beta * Creates an expression that adds a specified amount of time to this timestamp expression. @@ -4237,7 +4239,7 @@ declare namespace FirebaseFirestore { * * @param unit The unit of time to add (e.g., "day", "hour"). * @param amount The amount of time to add. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ timestampAdd( unit: @@ -4248,21 +4250,24 @@ declare namespace FirebaseFirestore { | 'hour' | 'day', amount: number - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Creates an expression that subtracts a specified amount of time from this timestamp expression. * * ```typescript * // Subtract some duration determined by field 'unit' and 'amount' from the 'timestamp' field. - * field("timestamp").timestampSub(field("unit"), field("amount")); + * field("timestamp").timestampSubtract(field("unit"), field("amount")); * ``` * * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. * @param amount The expression evaluates to amount of the unit. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ - timestampSub(unit: Expr, amount: Expr): FunctionExpr; + timestampSubtract( + unit: Expression, + amount: Expression + ): FunctionExpression; /** * @beta @@ -4270,14 +4275,14 @@ declare namespace FirebaseFirestore { * * ```typescript * // Subtract 1 day from the 'timestamp' field. - * field("timestamp").timestampSub("day", 1); + * field("timestamp").timestampSubtract("day", 1); * ``` * * @param unit The unit of time to subtract. Supported units are 'microsecond', 'millisecond', 'second', 'minute', 'hour', and 'day'. * @param amount The amount of time to subtract. - * @return A new {@code FunctionExpr} representing the resulting timestamp after subtraction. + * @return A new {@code FunctionExpression} representing the resulting timestamp after subtraction. */ - timestampSub( + timestampSubtract( unit: | 'microsecond' | 'millisecond' @@ -4286,7 +4291,7 @@ declare namespace FirebaseFirestore { | 'hour' | 'day', amount: number - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Creates an expression that returns the document ID from a DocumentReference. @@ -4296,9 +4301,9 @@ declare namespace FirebaseFirestore { * field("__name__").documentId(); * ``` * - * @return A new {@code Expr} representing the documentId operation. + * @return A new {@code Expression} representing the documentId operation. */ - documentId(): FunctionExpr; + documentId(): FunctionExpression; /** * @beta * Creates an expression that returns a substring of the results of this expression. @@ -4307,7 +4312,7 @@ declare namespace FirebaseFirestore { * @param length Length of the substring. If not provided, the substring will * end at the end of the input. */ - substring(position: number, length?: number): FunctionExpr; + substring(position: number, length?: number): FunctionExpression; /** * @beta * Creates an expression that returns a substring of the results of this expression. @@ -4316,7 +4321,7 @@ declare namespace FirebaseFirestore { * @param length An expression returning the length of the substring. If not provided the * substring will end at the end of the input. */ - substring(position: Expr, length?: Expr): FunctionExpr; + substring(position: Expression, length?: Expression): FunctionExpression; /** * @beta * Creates an expression that indexes into an array from the beginning or end @@ -4329,9 +4334,9 @@ declare namespace FirebaseFirestore { * ``` * * @param index The index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @return A new Expression representing the 'arrayGet' operation. */ - arrayGet(index: number): FunctionExpr; + arrayGet(index: number): FunctionExpression; /** * @beta * Creates an expression that indexes into an array from the beginning or end @@ -4344,10 +4349,10 @@ declare namespace FirebaseFirestore { * field('tags').arrayGet(field('favoriteTag')); * ``` * - * @param indexExpr An Expr evaluating to the index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @param indexExpr An Expression evaluating to the index of the element to return. + * @return A new Expression representing the 'arrayGet' operation. */ - arrayGet(indexExpr: Expr): FunctionExpr; + arrayGet(indexExpr: Expression): FunctionExpression; /** * @beta * Creates an expression that checks if a given expression produces an error. @@ -4357,9 +4362,9 @@ declare namespace FirebaseFirestore { * field("title").arrayContains(1).isError(); * ``` * - * @return A new {@code BooleanExpr} representing the 'isError' check. + * @return A new {@code BooleanExpression} representing the 'isError' check. */ - isError(): BooleanExpr; + isError(): BooleanExpression; /** * @beta * Creates an expression that returns the result of the `catchExpr` argument @@ -4373,9 +4378,9 @@ declare namespace FirebaseFirestore { * * @param catchExpr The catch expression that will be evaluated and * returned if this expression produces an error. - * @return A new {@code Expr} representing the 'ifError' operation. + * @return A new {@code Expression} representing the 'ifError' operation. */ - ifError(catchExpr: Expr): FunctionExpr; + ifError(catchExpr: Expression): FunctionExpression; /** * @beta * Creates an expression that returns the `catch` argument if there is an @@ -4389,9 +4394,9 @@ declare namespace FirebaseFirestore { * * @param catchValue The value that will be returned if this expression * produces an error. - * @return A new {@code Expr} representing the 'ifError' operation. + * @return A new {@code Expression} representing the 'ifError' operation. */ - ifError(catchValue: unknown): FunctionExpr; + ifError(catchValue: unknown): FunctionExpression; /** * @beta * Creates an expression that returns `true` if the result of this expression @@ -4402,34 +4407,9 @@ declare namespace FirebaseFirestore { * field("value").isAbsent(); * ``` * - * @return A new {@code BooleanExpr} representing the 'isAbsent' check. + * @return A new {@code BooleanExpression} representing the 'isAbsent' check. */ - isAbsent(): BooleanExpr; - - /** - * @beta - * Creates an expression that checks if the result of an expression is not null. - * - * ```typescript - * // Check if the value of the 'name' field is not null - * field("name").isNotNull(); - * ``` - * - * @return A new {@code BooleanExpr} representing the 'isNotNull' check. - */ - isNotNull(): BooleanExpr; - /** - * @beta - * Creates an expression that checks if the results of this expression is NOT 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NOT NaN - * field("value").divide(0).isNotNan(); - * ``` - * - * @return A new {@code Expr} representing the 'isNaN' check. - */ - isNotNan(): BooleanExpr; + isAbsent(): BooleanExpression; /** * @beta @@ -4441,9 +4421,9 @@ declare namespace FirebaseFirestore { * ``` * * @param key The name of the key to remove from the input map. - * @returns A new {@code FunctionExpr} representing the 'mapRemove' operation. + * @returns A new {@code FunctionExpression} representing the 'mapRemove' operation. */ - mapRemove(key: string): FunctionExpr; + mapRemove(key: string): FunctionExpression; /** * @beta @@ -4455,9 +4435,9 @@ declare namespace FirebaseFirestore { * ``` * * @param keyExpr An expression that produces the name of the key to remove from the input map. - * @returns A new {@code FunctionExpr} representing the 'mapRemove' operation. + * @returns A new {@code FunctionExpression} representing the 'mapRemove' operation. */ - mapRemove(keyExpr: Expr): FunctionExpr; + mapRemove(keyExpr: Expression): FunctionExpression; /** * @beta @@ -4468,7 +4448,7 @@ declare namespace FirebaseFirestore { * ```typescript * // Merges the map in the 'settings' field with a literal map and a map * // conditionally returned by another expression. - * field('settings').mapMerge({ enabled: true }, cond(field('isAdmin'), { admin: true }, {})) + * field('settings').mapMerge({ enabled: true }, conditional(field('isAdmin'), { admin: true }, {})) * ``` * * @param secondMap A required second map to merge. This can be a literal object @@ -4476,12 +4456,12 @@ declare namespace FirebaseFirestore { * @param otherMaps Optional additional maps to merge. Each can be a literal * object or an expression that evaluates to a map. * - * @returns A new {@code FunctionExpr} representing the result of the map merge operation. + * @returns A new {@code FunctionExpression} representing the result of the map merge operation. */ mapMerge( - secondMap: Record | Expr, - ...otherMaps: Array | Expr> - ): FunctionExpr; + secondMap: Record | Expression, + ...otherMaps: Array | Expression> + ): FunctionExpression; /** * @beta * Creates an expression that returns the value of this expression raised to the power of another expression. @@ -4492,9 +4472,9 @@ declare namespace FirebaseFirestore { * ``` * * @param exponent The expression to raise this expression to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ - pow(exponent: Expr): FunctionExpr; + pow(exponent: Expression): FunctionExpression; /** * @beta * Creates an expression that returns the value of this expression raised to the power of a constant value. @@ -4505,9 +4485,9 @@ declare namespace FirebaseFirestore { * ``` * * @param exponent The constant value to raise this expression to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ - pow(exponent: number): FunctionExpr; + pow(exponent: number): FunctionExpression; /** * @beta * Creates an expression that rounds a numeric value to the nearest whole number. @@ -4517,9 +4497,49 @@ declare namespace FirebaseFirestore { * field("price").round(); * ``` * + * @return A new `Expression` representing the rounded value. + */ + round(): FunctionExpression; + /** + * @beta + * Creates an expression that rounds a numeric value to the nearest whole number. + * + * ```typescript + * // Round the value of the 'price' field. + * field("price").round(); + * ``` + * + * @return A new `Expression` representing the rounded value. + */ + round(): FunctionExpression; + /** + * @beta + * Creates an expression that rounds a numeric value to the specified number of decimal places. + * + * ```typescript + * // Round the value of the 'price' field to two decimal places. + * field("price").round(2); + * ``` + * + * @param decimalPlaces A constant specifying the rounding precision in decimal places. + * * @return A new `Expr` representing the rounded value. */ - round(): FunctionExpr; + round(decimalPlaces: number): FunctionExpression; + /** + * @beta + * Creates an expression that rounds a numeric value to the specified number of decimal places. + * + * ```typescript + * // Round the value of the 'price' field to two decimal places. + * field("price").round(constant(2)); + * ``` + * + * @param decimalPlaces An expression specifying the rounding precision in decimal places. + * + * @return A new `Expr` representing the rounded value. + */ + round(decimalPlaces: Expression): FunctionExpression; /** * @beta * Creates an expression that returns the collection ID from a path. @@ -4529,9 +4549,9 @@ declare namespace FirebaseFirestore { * field("__name__").collectionId(); * ``` * - * @return A new {@code Expr} representing the collectionId operation. + * @return A new {@code Expression} representing the collectionId operation. */ - collectionId(): FunctionExpr; + collectionId(): FunctionExpression; /** * @beta * Creates an expression that calculates the length of a string, array, map, vector, or bytes. @@ -4544,9 +4564,9 @@ declare namespace FirebaseFirestore { * field("cart").length(); * ``` * - * @return A new `Expr` representing the length of the string, array, map, vector, or bytes. + * @return A new `Expression` representing the length of the string, array, map, vector, or bytes. */ - length(): FunctionExpr; + length(): FunctionExpression; /** * @beta * Creates an expression that computes the natural logarithm of a numeric value. @@ -4556,59 +4576,123 @@ declare namespace FirebaseFirestore { * field("value").ln(); * ``` * - * @return A new {@code Expr} representing the natural logarithm of the numeric value. + * @return A new {@code Expression} representing the natural logarithm of the numeric value. */ - ln(): FunctionExpr; + ln(): FunctionExpression; /** * @beta - * Creates an expression that computes the logarithm of this expression to a given base. + * Creates an expression that computes the square root of a numeric value. * * ```typescript - * // Compute the logarithm of the 'value' field with base 10. - * field("value").log(10); + * // Compute the square root of the 'value' field. + * field("value").sqrt(); * ``` * - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @return A new {@code Expression} representing the square root of the numeric value. */ - log(base: number): FunctionExpr; + sqrt(): FunctionExpression; /** * @beta - * Creates an expression that computes the logarithm of this expression to a given base. + * Creates an expression that reverses a string. * * ```typescript - * // Compute the logarithm of the 'value' field with the base in the 'base' field. - * field("value").log(field("base")); + * // Reverse the value of the 'myString' field. + * field("myString").stringReverse(); * ``` * - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @return A new {@code Expression} representing the reversed string. */ - log(base: Expr): FunctionExpr; + stringReverse(): FunctionExpression; + /** * @beta - * Creates an expression that computes the square root of a numeric value. + * Creates an expression that returns the `elseValue` argument if this expression results in an absent value, else + * return the result of the this expression evaluation. * * ```typescript - * // Compute the square root of the 'value' field. - * field("value").sqrt(); + * // Returns the value of the optional field 'optional_field', or returns 'default_value' + * // if the field is absent. + * field("optional_field").ifAbsent("default_value") * ``` * - * @return A new {@code Expr} representing the square root of the numeric value. + * @param elseValue The value that will be returned if this Expression evaluates to an absent value. + * @return A new [Expression] representing the ifAbsent operation. */ - sqrt(): FunctionExpr; + ifAbsent(elseValue: unknown): Expression; + /** * @beta - * Creates an expression that reverses a string. + * Creates an expression that returns the `elseValue` argument if this expression results in an absent value, else + * return the result of this expression evaluation. * * ```typescript - * // Reverse the value of the 'myString' field. - * field("myString").strReverse(); + * // Returns the value of the optional field 'optional_field', or if that is + * // absent, then returns the value of the field ` + * field("optional_field").ifAbsent(field('default_field')) + * ``` + * + * @param elseExpression The Expression that will be evaluated if this Expression evaluates to an absent value. + * @return A new [Expression] representing the ifAbsent operation. + */ + ifAbsent(elseExpression: unknown): Expression; + + ifAbsent(elseValueOrExpression: Expression | unknown): Expression; + + /** + * @beta + * Creates an expression that joins the elements of an array into a string. + * + * ```typescript + * // Join the elements of the 'tags' field with the delimiter from the 'separator' field. + * field("tags").join(field("separator")) + * ``` + * + * @param delimiterExpression The expression that evaluates to the delimiter string. + * @return A new Expression representing the join operation. + */ + join(delimiterExpression: Expression): Expression; + + /** + * @beta + * Creates an expression that joins the elements of an array field into a string. + * + * ```typescript + * // Join the elements of the 'tags' field with a comma and space. + * field("tags").join(", ") + * ``` + * + * @param delimiter The string to use as a delimiter. + * @return A new Expression representing the join operation. + */ + join(delimiter: string): Expression; + + join(delimeterValueOrExpression: string | Expression): Expression; + + /** + * @beta + * Creates an expression that computes the base-10 logarithm of a numeric value. + * + * ```typescript + * // Compute the base-10 logarithm of the 'value' field. + * field("value").log10(); * ``` * - * @return A new {@code Expr} representing the reversed string. + * @return A new {@code Expr} representing the base-10 logarithm of the numeric value. */ - strReverse(): FunctionExpr; + log10(): FunctionExpression; + + /** + * @beta + * Creates an expression that computes the sum of the elements in an array. + * + * ```typescript + * // Compute the sum of the elements in the 'scores' field. + * field("scores").arraySum(); + * ``` + * + * @return A new {@code Expr} representing the sum of the elements in the array. + */ + arraySum(): FunctionExpression; // TODO(new-expression): Add new expression method declarations above this line /** * @beta @@ -4650,10 +4734,10 @@ declare namespace FirebaseFirestore { * ``` * * @param name The alias to assign to this expression. - * @return A new {@link AliasedExpr} that wraps this + * @return A new {@link AliasedExpression} that wraps this * expression and associates it with the provided alias. */ - as(name: string): AliasedExpr; + as(name: string): AliasedExpression; } /** * @beta @@ -4661,8 +4745,16 @@ declare namespace FirebaseFirestore { */ export interface Selectable { selectable: true; - readonly alias: string; - readonly expr: Expr; + /** + * @beta + * @internal + */ + readonly _alias: string; + /** + * @beta + * @internal + */ + readonly _expr: Expression; } /** @@ -4674,9 +4766,9 @@ declare namespace FirebaseFirestore { export class AggregateFunction { /** * @beta - * @property exprType The type of the aggregate expression, indicating the specific aggregate function (e.g., COUNT, SUM, AVG). + * @property expressionType The type of the aggregate expression, indicating the specific aggregate function (e.g., COUNT, SUM, AVG). */ - exprType: ExprType; + expressionType: ExpressionType; /** * @beta @@ -4685,7 +4777,7 @@ declare namespace FirebaseFirestore { * @param name * @param params */ - constructor(name: string, params: Expr[]); + constructor(name: string, params: Expression[]); /** * @beta * Assigns an alias to this AggregateFunction. The alias specifies the name that @@ -4694,7 +4786,7 @@ declare namespace FirebaseFirestore { * ```typescript * // Calculate the average price of all items and assign it the alias "averagePrice". * pipeline().collection("items") - * .aggregate(field("price").avg().as("averagePrice")); + * .aggregate(field("price").average().as("averagePrice")); * ``` * * @param name The alias to assign to this AggregateFunction. @@ -4713,71 +4805,76 @@ declare namespace FirebaseFirestore { /** * @beta * The underlying {@link AggregateFunction} that this aliased aggregate wraps. + * @internal */ - readonly aggregate: AggregateFunction; + readonly _aggregate: AggregateFunction; /** * @beta * Specifies the name of the property that will contain the aggregate result in the output document. + * @internal */ - readonly alias: string; + readonly _alias: string; } /** * @beta * Represents an expression that has been assigned an alias using the `.as()` method. * - * This class wraps an existing {@link Expr} and associates it with a user-defined alias, + * This class wraps an existing {@link Expression} and associates it with a user-defined alias, * allowing the expression's result to be referred to by name in the output * of a Firestore pipeline query. */ - export class AliasedExpr implements Selectable { + export class AliasedExpression implements Selectable { /** * @beta - * @internal Specifies that the instance is an AliasedExpr. + * @internal + * Specifies that the instance is an AliasedExpression. */ - exprType: ExprType; + expressionType: ExpressionType; /** * @beta - * Specifies that this class is selectable, meaning it contains an {@link Expr} and an alias, + * Specifies that this class is selectable, meaning it contains an {@link Expression} and an alias, * and can be provided to the Select stage of a pipeline. */ selectable: true; /** * @beta + * @internal * The underlying expression that is being aliased. */ - readonly expr: Expr; + readonly _expr: Expression; /** * @beta + * @internal * Specifies the name of the property that will contain the aggregate result in the output document. */ - readonly alias: string; + readonly _alias: string; } /** * @beta * Represents a reference to a field within a Firestore document or an output from a {@link Pipeline} stage. * - * This class extends {@link Expr}. It is a type of expression that can be evaluated + * This class extends {@link Expression}. It is a type of expression that can be evaluated * within Firestore Pipelines. It also implements {@link Selectable}, * meaning instances of `Field` can be used to specify fields for selection in the {@link Pipeline.select} stage. * * `Field` instances are fundamental for constructing expressions that access document field values, * and for defining criteria for sorting, filtering, and projecting data in Firestore Pipelines. */ - export class Field extends Expr implements Selectable { + export class Field extends Expression implements Selectable { /** * @beta * @internal Specifies that the instance is a Field. */ - readonly exprType: ExprType; + readonly expressionType: ExpressionType; /** * @beta - * Specifies that this class is selectable, meaning it contains an {@link Expr} and an alias, + * Specifies that this class is selectable, meaning it contains an {@link Expression} and an alias, * and can be provided to the Select stage of a pipeline. */ selectable: true; @@ -4787,27 +4884,29 @@ declare namespace FirebaseFirestore { * * @example * ```typescript - * const name = field("price").fieldName(); + * const name = field("price").fieldName; * console.log(name); // "price" * ``` * * @returns The name of the field. */ - fieldName(): string; + get fieldName(): string; /** * @beta + * @internal * Returns the alias of the field, which is the field-name itself. * * @returns The field name itself. */ - get alias(): string; + get _alias(): string; /** * @beta + * @internal * Self-referential getter that returns this. * * @returns This {@link Field} object. */ - get expr(): Expr; + get _expr(): Expression; } /** * @beta @@ -4839,6 +4938,7 @@ declare namespace FirebaseFirestore { /** * @beta + * @internal * Represents a constant value that can be used as part of a Firestore pipeline expression. * * Instances of `Constant` are typically created via the top-level `constant()` function. @@ -4851,128 +4951,128 @@ declare namespace FirebaseFirestore { * const hello = constant("hello"); * ``` */ - export class Constant extends Expr { - readonly exprType: ExprType; + export class Constant extends Expression { + readonly expressionType: ExpressionType; } /** * @beta - * Creates a `Constant` instance for a number value. + * Creates an `Expression` instance for a number value. * * @param value The number value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: number): Constant; + export function constant(value: number): Expression; /** * @beta - * Creates a `Constant` instance for a string value. + * Creates an `Expression` instance for a string value. * * @param value The string value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: string): Constant; + export function constant(value: string): Expression; /** * @beta - * Creates a `Constant` instance for a boolean value. + * Creates an `Expression` instance for a boolean value. * * @param value The boolean value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: boolean): Constant; + export function constant(value: boolean): BooleanExpression; /** * @beta - * Creates a `Constant` instance for a null value. + * Creates an `Expression` instance for a null value. * * @param value The null value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: null): Constant; + export function constant(value: null): Expression; /** * @beta - * Creates a `Constant` instance for a GeoPoint value. + * Creates an `Expression` instance for a GeoPoint value. * * @param value The GeoPoint value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: GeoPoint): Constant; + export function constant(value: GeoPoint): Expression; /** * @beta - * Creates a `Constant` instance for a Timestamp value. + * Creates an `Expression` instance for a Timestamp value. * * @param value The Timestamp value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: Timestamp): Constant; + export function constant(value: Timestamp): Expression; /** * @beta - * Creates a `Constant` instance for a Date value. + * Creates an `Expression` instance for a Date value. * * @param value The Date value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: Date): Constant; + export function constant(value: Date): Expression; /** * @beta - * Creates a `Constant` instance for a Buffer | Uint8Array value. + * Creates an `Expression` instance for a Buffer | Uint8Array value. * * @param value The Buffer | Uint8Array value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: Buffer | Uint8Array): Constant; + export function constant(value: Buffer | Uint8Array): Expression; /** * @beta - * Creates a `Constant` instance for a DocumentReference value. + * Creates an `Expression` instance for a DocumentReference value. * * @param value The DocumentReference value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: DocumentReference): Constant; + export function constant(value: DocumentReference): Expression; /** * @beta - * Creates a `Constant` instance for a VectorValue value. + * Creates an `Expression` instance for a VectorValue value. * * @param value The VectorValue value. - * @return A new `Constant` instance. + * @return A new `Expression` instance. */ - export function constant(value: VectorValue): Constant; + export function constant(value: VectorValue): Expression; /** * @beta * Represents an expression that encapsulates a function call within the Firestore Pipelines. * - * `FunctionExpr` extends {@link Expr} and is used to build complex queries and transformations - * by applying various functions (e.g., `and`, `eq`, `ceil`) to fields or other expressions. + * `FunctionExpression` extends {@link Expression} and is used to build complex queries and transformations + * by applying various functions (e.g., `and`, `equal`, `ceil`) to fields or other expressions. * - * You typically do not instantiate `FunctionExpr` directly. Instead, use the provided - * top-level functions (like {@link and}, {@link eq}, {@link ceil}) or methods available - * on {@link Expr} instances (e.g., {@link Expr#eq}, {@link Expr#lt}) to construct - * `FunctionExpr` instances. + * You typically do not instantiate `FunctionExpression` directly. Instead, use the provided + * top-level functions (like {@link and}, {@link equal}, {@link ceil}) or methods available + * on {@link Expression} instances (e.g., {@link Expression#equal}, {@link Expression#lessThan}) to construct + * `FunctionExpression` instances. * * ```typescript - * // Example of creating a FunctionExpr indirectly using helper functions: - * const priceGreaterThan10 = field("price").gt(10); - * const combinedCondition = and(priceGreaterThan10, field("category").eq("books")); + * // Example of creating a FunctionExpression indirectly using helper functions: + * const priceGreaterThan10 = field("price").greaterThan(10); + * const combinedCondition = and(priceGreaterThan10, field("category").equal("books")); * - * // 'priceGreaterThan10' and 'combinedCondition' are instances of FunctionExpr. + * // 'priceGreaterThan10' and 'combinedCondition' are instances of FunctionExpression. * ``` */ - export class FunctionExpr extends Expr { + export class FunctionExpression extends Expression { /** * @beta * @internal - * Indicates that this expression is a `FunctionExpr`. + * Indicates that this expression is a `FunctionExpression`. */ - readonly exprType: ExprType; + readonly expressionType: ExpressionType; /** * @beta * @private * @internal * - * Initializes a new `FunctionExpr` instance with the given function name and parameters. + * Initializes a new `FunctionExpression` instance with the given function name and parameters. * * @param name The name of the function. - * @param params An array of `Expr` instances representing the parameters of the function. + * @param params An array of `Expression` instances representing the parameters of the function. */ - constructor(name: string, params: Expr[]); + constructor(name: string, params: Expression[]); } /** * @beta @@ -4981,7 +5081,7 @@ declare namespace FirebaseFirestore { * This expression type is useful for filter conditions. * */ - export class BooleanExpr extends FunctionExpr { + export class BooleanExpression extends FunctionExpression { /** * @beta * @internal @@ -4995,7 +5095,7 @@ declare namespace FirebaseFirestore { * * ```typescript * // Find the count of documents with a score greater than 90 - * field("score").gt(90).countIf().as("highestScore"); + * field("score").greaterThan(90).countIf().as("highestScore"); * ``` * * @return A new `AggregateFunction` representing the 'countIf' aggregation. @@ -5010,9 +5110,9 @@ declare namespace FirebaseFirestore { * field("tags").arrayContains("completed").not(); * ``` * - * @return A new {@code Expr} representing the negated filter condition. + * @return A new {@code Expression} representing the negated filter condition. */ - not(): BooleanExpr; + not(): BooleanExpression; } /** * @beta @@ -5021,21 +5121,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Count the number of documents where 'is_active' field equals true - * countIf(field("is_active").eq(true)).as("numActiveDocuments"); + * countIf(field("is_active").equal(true)).as("numActiveDocuments"); * ``` * * @param booleanExpr - The boolean expression to evaluate on each input. * @returns A new `AggregateFunction` representing the 'countIf' aggregation. */ - export function countIf(booleanExpr: BooleanExpr): AggregateFunction; - /** - * @beta - * Creates an expression that return a pseudo-random value of type double in the - * range of [0, 1), inclusive of 0 and exclusive of 1. - * - * @returns A new `Expr` representing the 'rand' function. - */ - export function rand(): FunctionExpr; + export function countIf(booleanExpr: BooleanExpression): AggregateFunction; /** * @beta * Creates an expression that indexes into an array from the beginning or end @@ -5049,9 +5141,12 @@ declare namespace FirebaseFirestore { * * @param arrayField The name of the array field. * @param index The index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @return A new Expression representing the 'arrayGet' operation. */ - export function arrayGet(arrayField: string, index: number): FunctionExpr; + export function arrayGet( + arrayField: string, + index: number + ): FunctionExpression; /** * @beta * Creates an expression that indexes into an array from the beginning or end @@ -5065,10 +5160,13 @@ declare namespace FirebaseFirestore { * ``` * * @param arrayField The name of the array field. - * @param indexExpr An Expr evaluating to the index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @param indexExpr An Expression evaluating to the index of the element to return. + * @return A new Expression representing the 'arrayGet' operation. */ - export function arrayGet(arrayField: string, indexExpr: Expr): FunctionExpr; + export function arrayGet( + arrayField: string, + indexExpr: Expression + ): FunctionExpression; /** * @beta * Creates an expression that indexes into an array from the beginning or end @@ -5080,14 +5178,14 @@ declare namespace FirebaseFirestore { * arrayGet(field('tags'), 1); * ``` * - * @param arrayExpression An Expr evaluating to an array. + * @param arrayExpression An Expression evaluating to an array. * @param index The index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @return A new Expression representing the 'arrayGet' operation. */ export function arrayGet( - arrayExpression: Expr, + arrayExpression: Expression, index: number - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Creates an expression that indexes into an array from the beginning or end @@ -5100,14 +5198,14 @@ declare namespace FirebaseFirestore { * arrayGet(field('tags'), field('favoriteTag')); * ``` * - * @param arrayExpression An Expr evaluating to an array. - * @param indexExpr An Expr evaluating to the index of the element to return. - * @return A new Expr representing the 'arrayGet' operation. + * @param arrayExpression An Expression evaluating to an array. + * @param indexExpr An Expression evaluating to the index of the element to return. + * @return A new Expression representing the 'arrayGet' operation. */ export function arrayGet( - arrayExpression: Expr, - indexExpr: Expr - ): FunctionExpr; + arrayExpression: Expression, + indexExpr: Expression + ): FunctionExpression; /** * @beta * Creates an expression that checks if a given expression produces an error. @@ -5118,9 +5216,32 @@ declare namespace FirebaseFirestore { * ``` * * @param value The expression to check. - * @return A new {@code Expr} representing the 'isError' check. + * @return A new {@code Expression} representing the 'isError' check. + */ + export function isError(value: Expression): BooleanExpression; + /** + * @beta + * + * Creates an expression that returns the `catch` argument if there is an + * error, else return the result of the `try` argument evaluation. + * + * This overload is useful when a BooleanExpression is required. + * + * ```typescript + * // Create an expression that protects against a divide by zero error + * // but always returns a boolean expression. + * ifError(constant(50).divide('length').gt(1), constant(false)); + * ``` + * + * @param tryExpr The try expression. + * @param catchExpr The catch expression that will be evaluated and + * returned if the tryExpr produces an error. + * @return A new {@code Expr} representing the 'ifError' operation. */ - export function isError(value: Expr): BooleanExpr; + export function ifError( + tryExpr: BooleanExpression, + catchExpr: BooleanExpression + ): BooleanExpression; /** * @beta * Creates an expression that returns the `catch` argument if there is an @@ -5135,9 +5256,12 @@ declare namespace FirebaseFirestore { * @param tryExpr The try expression. * @param catchExpr The catch expression that will be evaluated and * returned if the tryExpr produces an error. - * @return A new {@code Expr} representing the 'ifError' operation. + * @return A new {@code Expression} representing the 'ifError' operation. */ - export function ifError(tryExpr: Expr, catchExpr: Expr): FunctionExpr; + export function ifError( + tryExpr: Expression, + catchExpr: Expression + ): FunctionExpression; /** * @beta * Creates an expression that returns the `catch` argument if there is an @@ -5152,9 +5276,12 @@ declare namespace FirebaseFirestore { * @param tryExpr The try expression. * @param catchValue The value that will be returned if the tryExpr produces an * error. - * @return A new {@code Expr} representing the 'ifError' operation. + * @return A new {@code Expression} representing the 'ifError' operation. */ - export function ifError(tryExpr: Expr, catchValue: unknown): FunctionExpr; + export function ifError( + tryExpr: Expression, + catchValue: unknown + ): FunctionExpression; /** * @beta * Creates an expression that returns `true` if a value is absent. Otherwise, @@ -5166,9 +5293,9 @@ declare namespace FirebaseFirestore { * ``` * * @param value The expression to check. - * @return A new {@code Expr} representing the 'isAbsent' check. + * @return A new {@code Expression} representing the 'isAbsent' check. */ - export function isAbsent(value: Expr): BooleanExpr; + export function isAbsent(value: Expression): BooleanExpression; /** * @beta * Creates an expression that returns `true` if a field is absent. Otherwise, @@ -5180,93 +5307,10 @@ declare namespace FirebaseFirestore { * ``` * * @param field The field to check. - * @return A new {@code Expr} representing the 'isAbsent' check. - */ - export function isAbsent(field: string): BooleanExpr; - - /** - * @beta - * Creates an expression that checks if an expression evaluates to 'null'. - * - * ```typescript - * // Check if the 'lastLogin' field is null - * isNull(field("lastLogin")); - * ``` - * - * @param value The expression to check for null. - * @return A new {@code BooleanExpr} representing the 'isNull' check. - */ - export function isNull(value: Expr): BooleanExpr; - - /** - * @beta - * Creates an expression that checks if a field's value evaluates to 'null'. - * - * ```typescript - * // Check if the 'endDate' field is null. - * isNull("endDate"); - * ``` - * - * @param value The name of the field to check. - * @return A new {@code BooleanExpr} representing the 'isNull' check. - */ - export function isNull(value: string): BooleanExpr; - - /** - * @beta - * Creates an expression that checks if the result of an expression is not null. - * - * ```typescript - * // Check if the value of the 'name' field is not null - * isNotNull(field("name")); - * ``` - * - * @param value The expression to check. - * @return A new {@code BooleanExpr} representing the 'not null' check. + * @return A new {@code Expression} representing the 'isAbsent' check. */ - export function isNotNull(value: Expr): BooleanExpr; + export function isAbsent(field: string): BooleanExpression; - /** - * @beta - * Creates an expression that checks if the value of a field is not null. - * - * ```typescript - * // Check if the value of the 'name' field is not null - * isNotNull("name"); - * ``` - * - * @param value The name of the field to check. - * @return A new {@code BooleanExpr} representing the 'not null' check. - */ - export function isNotNull(value: string): BooleanExpr; - - /** - * @beta - * Creates an expression that evaluates to `true` if the given expression's result is not `NaN` (Not a Number), and `false` otherwise. - * - * ```typescript - * // Check if the result of a calculation is NOT NaN - * isNotNan(field("value").divide(0)); - * ``` - * - * @param value The expression to check for `NaN`. - * @return A new {@code BooleanExpr} representing the result of the `isNotNaN` check. - */ - export function isNotNan(value: Expr): BooleanExpr; - - /** - * @beta - * Creates an expression that checks if a numeric value is not NaN (Not a Number). - * - * ```typescript - * // Check if the value of a field is not NaN - * isNotNan("value"); - * ``` - * - * @param value The name of the field to check. - * @return A new {@code BooleanExpr} representing the 'isNotNan' check. - */ - export function isNotNan(value: string): BooleanExpr; /** * @beta * Creates an expression that removes a key from the map at the specified field name. @@ -5279,7 +5323,10 @@ declare namespace FirebaseFirestore { * @param mapField The name of a field containing a map value. * @param key The name of the key to remove from the input map. */ - export function mapRemove(mapField: string, key: string): FunctionExpr; + export function mapRemove( + mapField: string, + key: string + ): FunctionExpression; /** * @beta @@ -5292,9 +5339,12 @@ declare namespace FirebaseFirestore { * * @param mapExpr An expression that evaluates to a map value. * @param key The name of the key to remove from the input map. - * @returns A new {@link FunctionExpr} representing the map with the specified key removed. + * @returns A new {@link FunctionExpression} representing the map with the specified key removed. */ - export function mapRemove(mapExpr: Expr, key: string): FunctionExpr; + export function mapRemove( + mapExpr: Expression, + key: string + ): FunctionExpression; /** * @beta @@ -5307,9 +5357,12 @@ declare namespace FirebaseFirestore { * * @param mapField The name of a field containing a map value. * @param keyExpr An expression that produces the name of the key to remove from the input map. - * @returns A new {@code FunctionExpr} representing the map after the key has been removed. + * @returns A new {@code FunctionExpression} representing the map after the key has been removed. */ - export function mapRemove(mapField: string, keyExpr: Expr): FunctionExpr; + export function mapRemove( + mapField: string, + keyExpr: Expression + ): FunctionExpression; /** * @beta @@ -5326,9 +5379,12 @@ declare namespace FirebaseFirestore { * * @param mapExpr An expression that evaluates to a map value. * @param keyExpr An expression that evaluates to the string key to remove from the map. - * @returns A new {@link FunctionExpr} representing the map with the specified key removed. + * @returns A new {@link FunctionExpression} representing the map with the specified key removed. */ - export function mapRemove(mapExpr: Expr, keyExpr: Expr): FunctionExpr; + export function mapRemove( + mapExpr: Expression, + keyExpr: Expression + ): FunctionExpression; /** * @beta * Creates an expression that merges multiple map values. @@ -5336,7 +5392,7 @@ declare namespace FirebaseFirestore { * ``` * // Merges the map in the settings field with, a map literal, and a map in * // that is conditionally returned by another expression - * mapMerge('settings', { enabled: true }, cond(field('isAdmin'), { admin: true}, {}) + * mapMerge('settings', { enabled: true }, conditional(field('isAdmin'), { admin: true}, {}) * ``` * * @param mapField Name of a field containing a map value that will be merged. @@ -5347,9 +5403,9 @@ declare namespace FirebaseFirestore { */ export function mapMerge( mapField: string, - secondMap: Record | Expr, - ...otherMaps: Array | Expr> - ): FunctionExpr; + secondMap: Record | Expression, + ...otherMaps: Array | Expression> + ): FunctionExpression; /** * @beta * Creates an expression that merges multiple map values. @@ -5357,7 +5413,7 @@ declare namespace FirebaseFirestore { * ``` * // Merges the map in the settings field with, a map literal, and a map in * // that is conditionally returned by another expression - * mapMerge(field('settings'), { enabled: true }, cond(field('isAdmin'), { admin: true}, {}) + * mapMerge(field('settings'), { enabled: true }, conditional(field('isAdmin'), { admin: true}, {}) * ``` * * @param firstMap An expression or literal map value that will be merged. @@ -5367,10 +5423,10 @@ declare namespace FirebaseFirestore { * as a literal or an expression that returns a map. */ export function mapMerge( - firstMap: Record | Expr, - secondMap: Record | Expr, - ...otherMaps: Array | Expr> - ): FunctionExpr; + firstMap: Record | Expression, + secondMap: Record | Expression, + ...otherMaps: Array | Expression> + ): FunctionExpression; /** * @beta @@ -5382,9 +5438,42 @@ declare namespace FirebaseFirestore { * ``` * * @param documentPathExpr An expression evaluating to a document path. - * @return A new {@code FunctionExpr} representing the document ID as a string. + * @return A new {@code FunctionExpression} representing the document ID as a string. + */ + export function documentId( + documentPathExpr: Expression + ): FunctionExpression; + + /** + * @beta + * + * Creates an expression that returns the document ID from a path. + * + * ```typescript + * // Get the document ID from a path. + * documentId(myDocumentReference); + * ``` + * + * @return A new {@code Expr} representing the documentId operation. */ - export function documentId(documentPathExpr: Expr): FunctionExpr; + export function documentId( + documentPath: string | DocumentReference + ): FunctionExpression; + + /** + * @beta + * Creates an expression that returns the document ID from a path. + * + * ```typescript + * // Get the document ID from a path. + * documentId(field("__path__")); + * ``` + * + * @return A new {@code Expression} representing the documentId operation. + */ + export function documentId( + documentPathExpr: Expression + ): FunctionExpression; /** * @beta * Creates an expression that returns a substring of a string or byte array. @@ -5397,7 +5486,7 @@ declare namespace FirebaseFirestore { field: string, position: number, length?: number - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Creates an expression that returns a substring of a string or byte array. @@ -5407,10 +5496,10 @@ declare namespace FirebaseFirestore { * @param length Length of the substring. */ export function substring( - input: Expr, + input: Expression, position: number, length?: number - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Creates an expression that returns a substring of a string or byte array. @@ -5421,9 +5510,9 @@ declare namespace FirebaseFirestore { */ export function substring( field: string, - position: Expr, - length?: Expr - ): FunctionExpr; + position: Expression, + length?: Expression + ): FunctionExpression; /** * @beta @@ -5437,13 +5526,13 @@ declare namespace FirebaseFirestore { * @param input An expression returning a string or byte array from which to extract the substring. * @param position An expression that returns the 0-based starting index of the substring. * @param length Optional. An expression that returns the length of the substring. If omitted, the substring extends to the end of the input. - * @return A new {@code FunctionExpr} representing the substring operation. + * @return A new {@code FunctionExpression} representing the substring operation. */ export function substring( - input: Expr, - position: Expr, - length?: Expr - ): FunctionExpr; + input: Expression, + position: Expression, + length?: Expression + ): FunctionExpression; /** * @beta @@ -5462,13 +5551,13 @@ declare namespace FirebaseFirestore { * @param first The initial numeric expression or literal value. * @param second The second numeric expression or literal value to add. * @param others Optional: Additional numeric expressions or literal values to add. - * @return A new {@code FunctionExpr} representing the sum of all provided arguments. + * @return A new {@code FunctionExpression} representing the sum of all provided arguments. */ export function add( - first: Expr, - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + first: Expression, + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta @@ -5486,15 +5575,15 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field whose value will be the first operand in the addition. - * @param second The second operand, which can be an {@code Expr} or a literal value. - * @param others Optional additional operands, each of which can be an {@code Expr} or a literal value. - * @return A new {@code Expr} representing the addition operation. + * @param second The second operand, which can be an {@code Expression} or a literal value. + * @param others Optional additional operands, each of which can be an {@code Expression} or a literal value. + * @return A new {@code Expression} representing the addition operation. */ export function add( fieldName: string, - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta * Creates an expression that subtracts two expressions. @@ -5506,9 +5595,12 @@ declare namespace FirebaseFirestore { * * @param minuend The expression to subtract from. * @param subtrahend The expression to subtract. - * @return A new {@code Expr} representing the subtraction operation. + * @return A new {@code Expression} representing the subtraction operation. */ - export function subtract(minuend: Expr, subtrahend: Expr): FunctionExpr; + export function subtract( + minuend: Expression, + subtrahend: Expression + ): FunctionExpression; /** * @beta @@ -5521,9 +5613,12 @@ declare namespace FirebaseFirestore { * * @param minuend The expression to subtract from. * @param subtrahend The value to subtract. - * @return A new {@code Expr} representing the subtraction operation. + * @return A new {@code Expression} representing the subtraction operation. */ - export function subtract(minuend: Expr, subtrahend: unknown): FunctionExpr; + export function subtract( + minuend: Expression, + subtrahend: unknown + ): FunctionExpression; /** * @beta * Creates an expression that subtracts an expression from a field's value. @@ -5535,12 +5630,12 @@ declare namespace FirebaseFirestore { * * @param minuendFieldName The field name to subtract from. * @param subtrahend The expression to subtract. - * @return A new {@code Expr} representing the subtraction operation. + * @return A new {@code Expression} representing the subtraction operation. */ export function subtract( minuendFieldName: string, - subtrahend: Expr - ): FunctionExpr; + subtrahend: Expression + ): FunctionExpression; /** * @beta @@ -5554,12 +5649,12 @@ declare namespace FirebaseFirestore { * * @param minuendFieldName The name of the field to subtract from. * @param subtrahend The value to subtract. - * @return A new {@code Expr} representing the subtraction operation. + * @return A new {@code Expression} representing the subtraction operation. */ export function subtract( minuendFieldName: string, subtrahend: unknown - ): FunctionExpr; + ): FunctionExpression; /** * @beta @@ -5576,13 +5671,13 @@ declare namespace FirebaseFirestore { * @param first The first expression to multiply. * @param second The second expression or literal to multiply. * @param others Optional additional expressions or literals to multiply. - * @return A new {@code FunctionExpr} representing the multiplication operation. + * @return A new {@code FunctionExpression} representing the multiplication operation. */ export function multiply( - first: Expr, - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + first: Expression, + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta @@ -5594,15 +5689,15 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field whose value will be the initial operand of the multiplication. - * @param second The second operand, which can be an {@link Expr} or a literal value, to be multiplied. - * @param others Optional additional operands ({@link Expr} or literal values) to be included in the multiplication. - * @return A new {@link FunctionExpr} representing the multiplication operation. + * @param second The second operand, which can be an {@link Expression} or a literal value, to be multiplied. + * @param others Optional additional operands ({@link Expression} or literal values) to be included in the multiplication. + * @return A new {@link FunctionExpression} representing the multiplication operation. */ export function multiply( fieldName: string, - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta * Creates an expression that divides two expressions. @@ -5614,9 +5709,12 @@ declare namespace FirebaseFirestore { * * @param dividend The expression to be divided. * @param divisor The expression to divide by. - * @return A new {@code Expr} representing the division operation. + * @return A new {@code Expression} representing the division operation. */ - export function divide(dividend: Expr, divisor: Expr): FunctionExpr; + export function divide( + dividend: Expression, + divisor: Expression + ): FunctionExpression; /** * @beta * Creates an expression that divides an expression by a constant value. @@ -5628,9 +5726,12 @@ declare namespace FirebaseFirestore { * * @param dividend The expression to be divided. * @param divisor The constant value to divide by. - * @return A new {@code Expr} representing the division operation. + * @return A new {@code Expression} representing the division operation. */ - export function divide(dividend: Expr, divisor: unknown): FunctionExpr; + export function divide( + dividend: Expression, + divisor: unknown + ): FunctionExpression; /** * @beta * Creates an expression that divides a field's value by an expression. @@ -5642,9 +5743,12 @@ declare namespace FirebaseFirestore { * * @param dividend The field name to be divided. * @param divisor The expression to divide by. - * @return A new {@code Expr} representing the division operation. + * @return A new {@code Expression} representing the division operation. */ - export function divide(dividend: string, divisor: Expr): FunctionExpr; + export function divide( + dividend: string, + divisor: Expression + ): FunctionExpression; /** * @beta * Creates an expression that divides a field's value by a constant value. @@ -5656,9 +5760,12 @@ declare namespace FirebaseFirestore { * * @param dividend The field name to be divided. * @param divisor The constant value to divide by. - * @return A new {@code Expr} representing the division operation. + * @return A new {@code Expression} representing the division operation. */ - export function divide(dividend: string, divisor: unknown): FunctionExpr; + export function divide( + dividend: string, + divisor: unknown + ): FunctionExpression; /** * @beta * Creates an expression that calculates the modulo (remainder) of dividing two expressions. @@ -5670,9 +5777,12 @@ declare namespace FirebaseFirestore { * * @param left The dividend expression. * @param right The divisor expression. - * @return A new {@code Expr} representing the modulo operation. + * @return A new {@code Expression} representing the modulo operation. */ - export function mod(left: Expr, right: Expr): FunctionExpr; + export function mod( + left: Expression, + right: Expression + ): FunctionExpression; /** * @beta * Creates an expression that calculates the modulo (remainder) of dividing an expression by a constant. @@ -5684,9 +5794,12 @@ declare namespace FirebaseFirestore { * * @param expression The dividend expression. * @param value The divisor constant. - * @return A new {@code Expr} representing the modulo operation. + * @return A new {@code Expression} representing the modulo operation. */ - export function mod(expression: Expr, value: unknown): FunctionExpr; + export function mod( + expression: Expression, + value: unknown + ): FunctionExpression; /** * @beta * Creates an expression that calculates the modulo (remainder) of dividing a field's value by an expression. @@ -5698,9 +5811,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The dividend field name. * @param expression The divisor expression. - * @return A new {@code Expr} representing the modulo operation. + * @return A new {@code Expression} representing the modulo operation. */ - export function mod(fieldName: string, expression: Expr): FunctionExpr; + export function mod( + fieldName: string, + expression: Expression + ): FunctionExpression; /** * @beta * Creates an expression that calculates the modulo (remainder) of dividing a field's value by a constant. @@ -5712,9 +5828,9 @@ declare namespace FirebaseFirestore { * * @param fieldName The dividend field name. * @param value The divisor constant. - * @return A new {@code Expr} representing the modulo operation. + * @return A new {@code Expression} representing the modulo operation. */ - export function mod(fieldName: string, value: unknown): FunctionExpr; + export function mod(fieldName: string, value: unknown): FunctionExpression; /** * @beta @@ -5729,9 +5845,9 @@ declare namespace FirebaseFirestore { * ``` * * @param elements The JavaScript object literal whose properties will be used to create the Firestore map expression. - * @returns A new {@code FunctionExpr} representing the map function. + * @returns A new {@code FunctionExpression} representing the map function. */ - export function map(elements: Record): FunctionExpr; + export function map(elements: Record): FunctionExpression; /** * @beta * Creates an expression that creates a Firestore array value from a given JavaScript array. @@ -5743,9 +5859,9 @@ declare namespace FirebaseFirestore { * ``` * * @param elements The input array to evaluate in the expression. - * @return A new {@code Expr} representing the array function. + * @return A new {@code Expression} representing the array function. */ - export function array(elements: unknown[]): FunctionExpr; + export function array(elements: unknown[]): FunctionExpression; /** * @beta @@ -5753,28 +5869,34 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'age' field is equal to an expression - * eq(field("age"), field("minAge").add(10)); + * equal(field("age"), field("minAge").add(10)); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `BooleanExpr` representing the equality comparison. + * @return A new `BooleanExpression` representing the equality comparison. */ - export function eq(left: Expr, right: Expr): BooleanExpr; + export function equal( + left: Expression, + right: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if an expression is equal to a constant value. * * ```typescript * // Check if the 'age' field is equal to 21 - * eq(field("age"), 21); + * equal(field("age"), 21); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the equality comparison. + * @return A new `Expression` representing the equality comparison. */ - export function eq(expression: Expr, value: unknown): BooleanExpr; + export function equal( + expression: Expression, + value: unknown + ): BooleanExpression; /** * @beta @@ -5782,56 +5904,65 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'age' field is equal to the 'limit' field - * eq("age", field("limit")); + * equal("age", field("limit")); * ``` * * @param fieldName The name of the field to compare. * @param expression The expression to compare the field's value against. - * @return A new `BooleanExpr` representing the equality comparison. + * @return A new `BooleanExpression` representing the equality comparison. */ - export function eq(fieldName: string, expression: Expr): BooleanExpr; + export function equal( + fieldName: string, + expression: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is equal to a constant value. * * ```typescript * // Check if the 'city' field is equal to string constant "London" - * eq("city", "London"); + * equal("city", "London"); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the equality comparison. + * @return A new `Expression` representing the equality comparison. */ - export function eq(fieldName: string, value: unknown): BooleanExpr; + export function equal(fieldName: string, value: unknown): BooleanExpression; /** * @beta * Creates an expression that checks if two expressions are not equal. * * ```typescript * // Check if the 'status' field is not equal to field 'finalState' - * neq(field("status"), field("finalState")); + * notEqual(field("status"), field("finalState")); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ - export function neq(left: Expr, right: Expr): BooleanExpr; + export function notEqual( + left: Expression, + right: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if an expression is not equal to a constant value. * * ```typescript * // Check if the 'status' field is not equal to "completed" - * neq(field("status"), "completed"); + * notEqual(field("status"), "completed"); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ - export function neq(expression: Expr, value: unknown): BooleanExpr; + export function notEqual( + expression: Expression, + value: unknown + ): BooleanExpression; /** * @beta @@ -5839,56 +5970,68 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'status' field is not equal to the value of 'expectedStatus' - * neq("status", field("expectedStatus")); + * notEqual("status", field("expectedStatus")); * ``` * * @param fieldName The field name to compare. * @param expression The expression to compare to. - * @return A new {@link BooleanExpr} representing the inequality comparison. + * @return A new {@link BooleanExpression} representing the inequality comparison. */ - export function neq(fieldName: string, expression: Expr): BooleanExpr; + export function notEqual( + fieldName: string, + expression: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is not equal to a constant value. * * ```typescript * // Check if the 'country' field is not equal to "USA" - * neq("country", "USA"); + * notEqual("country", "USA"); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the inequality comparison. + * @return A new `Expression` representing the inequality comparison. */ - export function neq(fieldName: string, value: unknown): BooleanExpr; + export function notEqual( + fieldName: string, + value: unknown + ): BooleanExpression; /** * @beta * Creates an expression that checks if the first expression is less than the second expression. * * ```typescript * // Check if the 'age' field is less than 30 - * lt(field("age"), field("limit")); + * lessThan(field("age"), field("limit")); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ - export function lt(left: Expr, right: Expr): BooleanExpr; + export function lessThan( + left: Expression, + right: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if an expression is less than a constant value. * * ```typescript * // Check if the 'age' field is less than 30 - * lt(field("age"), 30); + * lessThan(field("age"), 30); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ - export function lt(expression: Expr, value: unknown): BooleanExpr; + export function lessThan( + expression: Expression, + value: unknown + ): BooleanExpression; /** * @beta @@ -5896,28 +6039,34 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'age' field is less than the 'limit' field - * lt("age", field("limit")); + * lessThan("age", field("limit")); * ``` * * @param fieldName The field name to compare. * @param expression The expression to compare to. - * @return A new `BooleanExpr` representing the less than comparison. + * @return A new `BooleanExpression` representing the less than comparison. */ - export function lt(fieldName: string, expression: Expr): BooleanExpr; + export function lessThan( + fieldName: string, + expression: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is less than a constant value. * * ```typescript * // Check if the 'price' field is less than 50 - * lt("price", 50); + * lessThan("price", 50); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the less than comparison. + * @return A new `Expression` representing the less than comparison. */ - export function lt(fieldName: string, value: unknown): BooleanExpr; + export function lessThan( + fieldName: string, + value: unknown + ): BooleanExpression; /** * @beta * Creates an expression that checks if the first expression is less than or equal to the second @@ -5925,14 +6074,17 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'quantity' field is less than or equal to 20 - * lte(field("quantity"), field("limit")); + * lessThanOrEqual(field("quantity"), field("limit")); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the less than or equal to comparison. + * @return A new `Expression` representing the less than or equal to comparison. */ - export function lte(left: Expr, right: Expr): BooleanExpr; + export function lessThanOrEqual( + left: Expression, + right: Expression + ): BooleanExpression; /** * @beta @@ -5940,14 +6092,17 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'quantity' field is less than or equal to 20 - * lte(field("quantity"), 20); + * lessThanOrEqual(field("quantity"), 20); * ``` * - * @param expression The {@link Expr} to compare. + * @param expression The {@link Expression} to compare. * @param value The constant value to compare against. - * @return A new {@link BooleanExpr} representing the less than or equal to comparison. + * @return A new {@link BooleanExpression} representing the less than or equal to comparison. */ - export function lte(expression: Expr, value: unknown): BooleanExpr; + export function lessThanOrEqual( + expression: Expression, + value: unknown + ): BooleanExpression; /** * @beta @@ -5955,28 +6110,34 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'quantity' field is less than or equal to the 'limit' field - * lte("quantity", field("limit")); + * lessThanOrEqual("quantity", field("limit")); * ``` * * @param fieldName The name of the field whose value will be compared. * @param expression The expression to compare against the field's value. - * @return A new {@link BooleanExpr} representing the less than or equal to comparison. + * @return A new {@link BooleanExpression} representing the less than or equal to comparison. */ - export function lte(fieldName: string, expression: Expr): BooleanExpr; + export function lessThanOrEqual( + fieldName: string, + expression: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is less than or equal to a constant value. * * ```typescript * // Check if the 'score' field is less than or equal to 70 - * lte("score", 70); + * lessThanOrEqual("score", 70); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the less than or equal to comparison. + * @return A new `Expression` representing the less than or equal to comparison. */ - export function lte(fieldName: string, value: unknown): BooleanExpr; + export function lessThanOrEqual( + fieldName: string, + value: unknown + ): BooleanExpression; /** * @beta * Creates an expression that checks if the first expression is greater than the second @@ -5984,28 +6145,34 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'age' field is greater than 18 - * gt(field("age"), Constant(9).add(9)); + * greaterThan(field("age"), constant(9).add(9)); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the greater than comparison. + * @return A new `Expression` representing the greater than comparison. */ - export function gt(left: Expr, right: Expr): BooleanExpr; + export function greaterThan( + left: Expression, + right: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if an expression is greater than a constant value. * * ```typescript * // Check if the 'age' field is greater than 18 - * gt(field("age"), 18); + * greaterThan(field("age"), 18); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the greater than comparison. + * @return A new `Expression` representing the greater than comparison. */ - export function gt(expression: Expr, value: unknown): BooleanExpr; + export function greaterThan( + expression: Expression, + value: unknown + ): BooleanExpression; /** * @beta @@ -6013,28 +6180,34 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the value of field 'age' is greater than the value of field 'limit' - * gt("age", field("limit")); + * greaterThan("age", field("limit")); * ``` * * @param fieldName The name of the field to compare. * @param expression The expression to compare against. - * @return A new {@link BooleanExpr} representing the greater than comparison. + * @return A new {@link BooleanExpression} representing the greater than comparison. */ - export function gt(fieldName: string, expression: Expr): BooleanExpr; + export function greaterThan( + fieldName: string, + expression: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is greater than a constant value. * * ```typescript * // Check if the 'price' field is greater than 100 - * gt("price", 100); + * greaterThan("price", 100); * ``` * * @param fieldName The name of the field to compare. * @param value The constant value to compare to. - * @return A new {@link BooleanExpr} representing the greater than comparison. + * @return A new {@link BooleanExpression} representing the greater than comparison. */ - export function gt(fieldName: string, value: unknown): BooleanExpr; + export function greaterThan( + fieldName: string, + value: unknown + ): BooleanExpression; /** * @beta * Creates an expression that checks if the first expression is greater than or equal to the @@ -6042,14 +6215,17 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'quantity' field is greater than or equal to the field "threshold" - * gte(field("quantity"), field("threshold")); + * greaterThanOrEqual(field("quantity"), field("threshold")); * ``` * * @param left The first expression to compare. * @param right The second expression to compare. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ - export function gte(left: Expr, right: Expr): BooleanExpr; + export function greaterThanOrEqual( + left: Expression, + right: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if an expression is greater than or equal to a constant @@ -6057,28 +6233,34 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'quantity' field is greater than or equal to 10 - * gte(field("quantity"), 10); + * greaterThanOrEqual(field("quantity"), 10); * ``` * * @param expression The expression to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ - export function gte(expression: Expr, value: unknown): BooleanExpr; + export function greaterThanOrEqual( + expression: Expression, + value: unknown + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is greater than or equal to an expression. * * ```typescript * // Check if the value of field 'age' is greater than or equal to the value of field 'limit' - * gte("age", field("limit")); + * greaterThanOrEqual("age", field("limit")); * ``` * * @param fieldName The field name to compare. * @param value The expression to compare to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ - export function gte(fieldName: string, value: Expr): BooleanExpr; + export function greaterThanOrEqual( + fieldName: string, + value: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is greater than or equal to a constant @@ -6086,14 +6268,60 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'score' field is greater than or equal to 80 - * gte("score", 80); + * greaterThanOrEqual("score", 80); * ``` * * @param fieldName The field name to compare. * @param value The constant value to compare to. - * @return A new `Expr` representing the greater than or equal to comparison. + * @return A new `Expression` representing the greater than or equal to comparison. */ - export function gte(fieldName: string, value: unknown): BooleanExpr; + export function greaterThanOrEqual( + fieldName: string, + value: unknown + ): BooleanExpression; + + /** + * @beta + * + * Creates an expression that concatenates an array expression with other arrays. + * + * ```typescript + * // Combine the 'items' array with two new item arrays + * arrayConcat(field("items"), [field("newItems"), field("otherItems")]); + * ``` + * + * @param firstArray The first array expression to concatenate to. + * @param secondArray The second array expression or array literal to concatenate to. + * @param otherArrays Optional additional array expressions or array literals to concatenate. + * @return A new {@code Expr} representing the concatenated array. + */ + export function arrayConcat( + firstArray: Expression, + secondArray: Expression | unknown[], + ...otherArrays: Array + ): FunctionExpression; + + /** + * @beta + * + * Creates an expression that concatenates a field's array value with other arrays. + * + * ```typescript + * // Combine the 'items' array with two new item arrays + * arrayConcat("items", [field("newItems"), field("otherItems")]); + * ``` + * + * @param firstArrayField The first array to concatenate to. + * @param secondArray The second array expression or array literal to concatenate to. + * @param otherArrays Optional additional array expressions or array literals to concatenate. + * @return A new {@code Expr} representing the concatenated array. + */ + export function arrayConcat( + firstArrayField: string, + secondArray: Expression | unknown[], + ...otherArrays: Array + ): FunctionExpression; + /** * @beta * Creates an expression that checks if an array expression contains a specific element. @@ -6105,9 +6333,12 @@ declare namespace FirebaseFirestore { * * @param array The array expression to check. * @param element The element to search for in the array. - * @return A new {@code Expr} representing the 'array_contains' comparison. + * @return A new {@code Expression} representing the 'array_contains' comparison. */ - export function arrayContains(array: Expr, element: Expr): FunctionExpr; + export function arrayContains( + array: Expression, + element: Expression + ): FunctionExpression; /** * @beta * Creates an expression that checks if an array expression contains a specific element. @@ -6119,9 +6350,12 @@ declare namespace FirebaseFirestore { * * @param array The array expression to check. * @param element The element to search for in the array. - * @return A new {@code Expr} representing the 'array_contains' comparison. + * @return A new {@code Expression} representing the 'array_contains' comparison. */ - export function arrayContains(array: Expr, element: unknown): FunctionExpr; + export function arrayContains( + array: Expression, + element: unknown + ): FunctionExpression; /** * @beta * Creates an expression that checks if a field's array value contains a specific element. @@ -6133,12 +6367,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name to check. * @param element The element to search for in the array. - * @return A new {@code Expr} representing the 'array_contains' comparison. + * @return A new {@code Expression} representing the 'array_contains' comparison. */ export function arrayContains( fieldName: string, - element: Expr - ): FunctionExpr; + element: Expression + ): FunctionExpression; /** * @beta * Creates an expression that checks if a field's array value contains a specific value. @@ -6150,12 +6384,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name to check. * @param element The element to search for in the array. - * @return A new {@code Expr} representing the 'array_contains' comparison. + * @return A new {@code Expression} representing the 'array_contains' comparison. */ export function arrayContains( fieldName: string, element: unknown - ): BooleanExpr; + ): BooleanExpression; /** * @beta * Creates an expression that checks if an array expression contains any of the specified @@ -6168,12 +6402,12 @@ declare namespace FirebaseFirestore { * * @param array The array expression to check. * @param values The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_any' comparison. + * @return A new {@code Expression} representing the 'array_contains_any' comparison. */ export function arrayContainsAny( - array: Expr, - values: Array - ): BooleanExpr; + array: Expression, + values: Array + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's array value contains any of the specified @@ -6187,12 +6421,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name to check. * @param values The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_any' comparison. + * @return A new {@code Expression} representing the 'array_contains_any' comparison. */ export function arrayContainsAny( fieldName: string, - values: Array - ): BooleanExpr; + values: Array + ): BooleanExpression; /** * @beta * Creates an expression that checks if an array expression contains any of the specified @@ -6205,9 +6439,12 @@ declare namespace FirebaseFirestore { * * @param array The array expression to check. * @param values An expression that evaluates to an array, whose elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_any' comparison. + * @return A new {@code Expression} representing the 'array_contains_any' comparison. */ - export function arrayContainsAny(array: Expr, values: Expr): BooleanExpr; + export function arrayContainsAny( + array: Expression, + values: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's array value contains any of the specified @@ -6221,12 +6458,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name to check. * @param values An expression that evaluates to an array, whose elements to check for in the array field. - * @return A new {@code Expr} representing the 'array_contains_any' comparison. + * @return A new {@code Expression} representing the 'array_contains_any' comparison. */ export function arrayContainsAny( fieldName: string, - values: Expr - ): BooleanExpr; + values: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if an array expression contains all the specified elements. @@ -6238,12 +6475,12 @@ declare namespace FirebaseFirestore { * * @param array The array expression to check. * @param values The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_all' comparison. + * @return A new {@code Expression} representing the 'array_contains_all' comparison. */ export function arrayContainsAll( - array: Expr, - values: Array - ): BooleanExpr; + array: Expression, + values: Array + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's array value contains all the specified values or @@ -6256,12 +6493,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name to check. * @param values The elements to check for in the array. - * @return A new {@code Expr} representing the 'array_contains_all' comparison. + * @return A new {@code Expression} representing the 'array_contains_all' comparison. */ export function arrayContainsAll( fieldName: string, - values: Array - ): BooleanExpr; + values: Array + ): BooleanExpression; /** * @beta * Creates an expression that checks if an array expression contains all the specified elements. @@ -6280,12 +6517,12 @@ declare namespace FirebaseFirestore { * * @param array An expression evaluating to the array to check. * @param arrayExpression An expression evaluating to an array of elements to check for. - * @return A new {@code BooleanExpr} representing the 'array_contains_all' comparison. + * @return A new {@code BooleanExpression} representing the 'array_contains_all' comparison. */ export function arrayContainsAll( - array: Expr, - arrayExpression: Expr - ): BooleanExpr; + array: Expression, + arrayExpression: Expression + ): BooleanExpression; /** * @beta @@ -6298,12 +6535,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The name of the array field to check. * @param arrayExpression An expression that evaluates to an array of values to check for. - * @return A new {@code BooleanExpr} representing the 'array_contains_all' comparison. + * @return A new {@code BooleanExpression} representing the 'array_contains_all' comparison. */ export function arrayContainsAll( fieldName: string, - arrayExpression: Expr - ): BooleanExpr; + arrayExpression: Expression + ): BooleanExpression; /** * @beta * Creates an expression that calculates the length of an array in a specified field. @@ -6314,9 +6551,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing an array to calculate the length of. - * @return A new {@code Expr} representing the length of the array. + * @return A new {@code Expression} representing the length of the array. */ - export function arrayLength(fieldName: string): FunctionExpr; + export function arrayLength(fieldName: string): FunctionExpression; /** * @beta * Creates an expression that calculates the length of an array expression. @@ -6327,9 +6564,9 @@ declare namespace FirebaseFirestore { * ``` * * @param array The array expression to calculate the length of. - * @return A new {@code Expr} representing the length of the array. + * @return A new {@code Expression} representing the length of the array. */ - export function arrayLength(array: Expr): FunctionExpr; + export function arrayLength(array: Expression): FunctionExpression; /** * @beta * Creates an expression that checks if an expression, when evaluated, is equal to any of the provided values or @@ -6337,31 +6574,34 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'category' field is either "Electronics" or value of field 'primaryType' - * eqAny(field("category"), [constant("Electronics"), field("primaryType")]); + * equalAny(field("category"), [constant("Electronics"), field("primaryType")]); * ``` * * @param expression The expression whose results to compare. * @param values The values to check against. - * @return A new {@code Expr} representing the 'IN' comparison. + * @return A new {@code Expression} representing the 'IN' comparison. */ - export function eqAny( - expression: Expr, - values: Array - ): BooleanExpr; + export function equalAny( + expression: Expression, + values: Array + ): BooleanExpression; /** * @beta * Creates an expression that checks if an expression is equal to any of the provided values. * * ```typescript * // Check if the 'category' field is set to a value in the disabledCategories field - * eqAny(field("category"), field('disabledCategories')); + * equalAny(field("category"), field('disabledCategories')); * ``` * * @param expression The expression whose results to compare. * @param arrayExpression An expression that evaluates to an array, whose elements to check for equality to the input. - * @return A new {@code Expr} representing the 'IN' comparison. + * @return A new {@code Expression} representing the 'IN' comparison. */ - export function eqAny(expression: Expr, arrayExpression: Expr): BooleanExpr; + export function equalAny( + expression: Expression, + arrayExpression: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is equal to any of the provided values or @@ -6369,17 +6609,17 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'category' field is either "Electronics" or value of field 'primaryType' - * eqAny("category", [constant("Electronics"), field("primaryType")]); + * equalAny("category", [constant("Electronics"), field("primaryType")]); * ``` * * @param fieldName The field to compare. * @param values The values to check against. - * @return A new {@code Expr} representing the 'IN' comparison. + * @return A new {@code Expression} representing the 'IN' comparison. */ - export function eqAny( + export function equalAny( fieldName: string, - values: Array - ): BooleanExpr; + values: Array + ): BooleanExpression; /** * @beta @@ -6390,17 +6630,17 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'category' field's value is present in the 'allowedCategories' array field. - * eqAny("category", field("allowedCategories")); + * equalAny("category", field("allowedCategories")); * ``` * * @param fieldName The name of the field to compare. * @param arrayExpression An expression that evaluates to an array. The function checks if the value of `fieldName` is equal to any element within this array. - * @return A new {@code BooleanExpr} representing the 'IN' comparison. + * @return A new {@code BooleanExpression} representing the 'IN' comparison. */ - export function eqAny( + export function equalAny( fieldName: string, - arrayExpression: Expr - ): BooleanExpr; + arrayExpression: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if an expression is not equal to any of the provided values @@ -6408,17 +6648,17 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus' - * notEqAny(field("status"), ["pending", field("rejectedStatus")]); + * notEqualAny(field("status"), ["pending", field("rejectedStatus")]); * ``` * * @param element The expression to compare. * @param values The values to check against. - * @return A new {@code Expr} representing the 'NOT IN' comparison. + * @return A new {@code Expression} representing the 'NOT IN' comparison. */ - export function notEqAny( - element: Expr, - values: Array - ): BooleanExpr; + export function notEqualAny( + element: Expression, + values: Array + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is not equal to any of the provided values @@ -6426,17 +6666,17 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus' - * notEqAny("status", [constant("pending"), field("rejectedStatus")]); + * notEqualAny("status", [constant("pending"), field("rejectedStatus")]); * ``` * * @param fieldName The field name to compare. * @param values The values to check against. - * @return A new {@code Expr} representing the 'NOT IN' comparison. + * @return A new {@code Expression} representing the 'NOT IN' comparison. */ - export function notEqAny( + export function notEqualAny( fieldName: string, - values: Array - ): BooleanExpr; + values: Array + ): BooleanExpression; /** * @beta @@ -6445,31 +6685,34 @@ declare namespace FirebaseFirestore { * * ```typescript * // Check if the 'status' field is not present in the array stored in the 'invalidStatuses' field. - * notEqAny(field("status"), field("invalidStatuses")); + * notEqualAny(field("status"), field("invalidStatuses")); * ``` * * @param element The expression representing the value to check. * @param arrayExpression An expression that evaluates to an array of values to check against. - * @return A new {@code BooleanExpr} representing the 'NOT IN' comparison. + * @return A new {@code BooleanExpression} representing the 'NOT IN' comparison. */ - export function notEqAny(element: Expr, arrayExpression: Expr): BooleanExpr; + export function notEqualAny( + element: Expression, + arrayExpression: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value is not equal to any of the values in the evaluated expression. * * ```typescript * // Check if the 'status' field is not equal to any value in the field 'rejectedStatuses' - * notEqAny("status", field("rejectedStatuses")); + * notEqualAny("status", field("rejectedStatuses")); * ``` * * @param fieldName The field name to compare. * @param arrayExpression The values to check against. - * @return A new {@code Expr} representing the 'NOT IN' comparison. + * @return A new {@code Expression} representing the 'NOT IN' comparison. */ - export function notEqAny( + export function notEqualAny( fieldName: string, - arrayExpression: Expr - ): BooleanExpr; + arrayExpression: Expression + ): BooleanExpression; /** * @beta @@ -6480,22 +6723,22 @@ declare namespace FirebaseFirestore { * // Check if exactly one of the conditions is true: 'age' greater than 18, 'city' is "London", * // or 'status' is "active". * const condition = xor( - * gt("age", 18), - * eq("city", "London"), - * eq("status", "active") + * greaterThan("age", 18), + * equal("city", "London"), + * equal("status", "active") * ); * ``` * * @param first The first Boolean expression. * @param second The second Boolean expression. * @param additionalConditions Optional: Additional Boolean expressions to include in the XOR operation. - * @returns A new {@link BooleanExpr} representing the logical 'XOR' operation. + * @returns A new {@link BooleanExpression} representing the logical 'XOR' operation. */ export function xor( - first: BooleanExpr, - second: BooleanExpr, - ...additionalConditions: BooleanExpr[] - ): BooleanExpr; + first: BooleanExpression, + second: BooleanExpression, + ...additionalConditions: BooleanExpression[] + ): BooleanExpression; /** * @beta * Creates a conditional expression that evaluates to a 'then' expression if a condition is true @@ -6503,33 +6746,33 @@ declare namespace FirebaseFirestore { * * ```typescript * // If 'age' is greater than 18, return "Adult"; otherwise, return "Minor". - * cond( - * gt("age", 18), constant("Adult"), constant("Minor")); + * conditional( + * greaterThan("age", 18), constant("Adult"), constant("Minor")); * ``` * * @param condition The condition to evaluate. * @param thenExpr The expression to evaluate if the condition is true. * @param elseExpr The expression to evaluate if the condition is false. - * @return A new {@code Expr} representing the conditional expression. + * @return A new {@code Expression} representing the conditional expression. */ - export function cond( - condition: BooleanExpr, - thenExpr: Expr, - elseExpr: Expr - ): FunctionExpr; + export function conditional( + condition: BooleanExpression, + thenExpr: Expression, + elseExpr: Expression + ): FunctionExpression; /** * @beta * Creates an expression that negates a filter condition. * * ```typescript * // Find documents where the 'completed' field is NOT true - * not(eq("completed", true)); + * not(equal("completed", true)); * ``` * * @param booleanExpr The filter condition to negate. - * @return A new {@code Expr} representing the negated filter condition. + * @return A new {@code Expression} representing the negated filter condition. */ - export function not(booleanExpr: BooleanExpr): BooleanExpr; + export function not(booleanExpr: BooleanExpression): BooleanExpression; /** * @beta * Creates an expression that returns the largest value between multiple input @@ -6544,13 +6787,13 @@ declare namespace FirebaseFirestore { * @param first The first operand expression. * @param second The second expression or literal. * @param others Optional additional expressions or literals. - * @return A new {@code Expr} representing the logical max operation. + * @return A new {@code Expression} representing the logical max operation. */ export function logicalMaximum( - first: Expr, - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + first: Expression, + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta * Creates an expression that returns the largest value between multiple input @@ -6565,13 +6808,13 @@ declare namespace FirebaseFirestore { * @param fieldName The first operand field name. * @param second The second expression or literal. * @param others Optional additional expressions or literals. - * @return A new {@code Expr} representing the logical max operation. + * @return A new {@code Expression} representing the logical max operation. */ export function logicalMaximum( fieldName: string, - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta * Creates an expression that returns the smallest value between multiple input @@ -6586,13 +6829,13 @@ declare namespace FirebaseFirestore { * @param first The first operand expression. * @param second The second expression or literal. * @param others Optional additional expressions or literals. - * @return A new {@code Expr} representing the logical min operation. + * @return A new {@code Expression} representing the logical min operation. */ export function logicalMinimum( - first: Expr, - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + first: Expression, + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta * Creates an expression that returns the smallest value between a field's value @@ -6608,13 +6851,13 @@ declare namespace FirebaseFirestore { * @param fieldName The first operand field name. * @param second The second expression or literal. * @param others Optional additional expressions or literals. - * @return A new {@code Expr} representing the logical min operation. + * @return A new {@code Expression} representing the logical min operation. */ export function logicalMinimum( fieldName: string, - second: Expr | unknown, - ...others: Array - ): FunctionExpr; + second: Expression | unknown, + ...others: Array + ): FunctionExpression; /** * @beta @@ -6626,9 +6869,9 @@ declare namespace FirebaseFirestore { * ``` * * @param value An expression representing the field to check for existence. - * @return A new {@code BooleanExpr} representing the 'exists' check. + * @return A new {@code BooleanExpression} representing the 'exists' check. */ - export function exists(value: Expr): BooleanExpr; + export function exists(value: Expression): BooleanExpression; /** * @beta * Creates an expression that checks if a field exists. @@ -6639,37 +6882,10 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The field name to check. - * @return A new {@code Expr} representing the 'exists' check. + * @return A new {@code Expression} representing the 'exists' check. */ - export function exists(fieldName: string): BooleanExpr; + export function exists(fieldName: string): BooleanExpression; - /** - * @beta - * Creates an expression that checks if an expression evaluates to 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NaN - * isNan(field("value").divide(0)); - * ``` - * - * @param value The expression to check. - * @return A new {@code Expr} representing the 'isNaN' check. - */ - export function isNan(value: Expr): BooleanExpr; - - /** - * @beta - * Creates an expression that checks if a field's value evaluates to 'NaN' (Not a Number). - * - * ```typescript - * // Check if the result of a calculation is NaN - * isNan("value"); - * ``` - * - * @param fieldName The name of the field to check. - * @return A new {@code BooleanExpr} representing the 'isNan' check. - */ - export function isNan(fieldName: string): BooleanExpr; /** * @beta * Creates an expression that reverses a string. @@ -6680,9 +6896,9 @@ declare namespace FirebaseFirestore { * ``` * * @param stringExpression An expression evaluating to a string value, which will be reversed. - * @return A new {@code Expr} representing the reversed string. + * @return A new {@code Expression} representing the reversed string. */ - export function reverse(stringExpression: Expr): FunctionExpr; + export function reverse(stringExpression: Expression): FunctionExpression; /** * @beta * Creates an expression that reverses a string value in the specified field. @@ -6693,9 +6909,9 @@ declare namespace FirebaseFirestore { * ``` * * @param field The name of the field representing the string to reverse. - * @return A new {@code Expr} representing the reversed string. + * @return A new {@code Expression} representing the reversed string. */ - export function reverse(field: string): FunctionExpr; + export function reverse(field: string): FunctionExpression; /** * @beta * Creates an expression that reverses an array. @@ -6706,9 +6922,11 @@ declare namespace FirebaseFirestore { * ``` * * @param arrayExpression An expression evaluating to an array value, which will be reversed. - * @return A new {@code Expr} representing the reversed array. + * @return A new {@code Expression} representing the reversed array. */ - export function arrayReverse(arrayExpression: Expr): FunctionExpr; + export function arrayReverse( + arrayExpression: Expression + ): FunctionExpression; /** * @beta * Creates an expression that reverses an array. @@ -6719,9 +6937,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field to reverse. - * @return A new {@code Expr} representing the reversed array. + * @return A new {@code Expression} representing the reversed array. */ - export function arrayReverse(fieldName: string): FunctionExpr; + export function arrayReverse(fieldName: string): FunctionExpression; /** * @beta * Creates an expression that computes the ceiling of a numeric value. @@ -6732,9 +6950,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expression An expression evaluating to a numeric value, which the ceiling will be computed for. - * @return A new {@code Expr} representing the ceiling of the numeric value. + * @return A new {@code Expression} representing the ceiling of the numeric value. */ - export function ceil(expression: Expr): FunctionExpr; + export function ceil(expression: Expression): FunctionExpression; /** * @beta * Creates an expression that computes the ceiling of a numeric value. @@ -6745,9 +6963,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field to compute the ceiling of. - * @return A new {@code Expr} representing the ceiling of the numeric value. + * @return A new {@code Expression} representing the ceiling of the numeric value. */ - export function ceil(fieldName: string): FunctionExpr; + export function ceil(fieldName: string): FunctionExpression; /** * @beta @@ -6761,9 +6979,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expression An expression evaluating to a numeric value, which will be used as the exponent for `e`. - * @returns A new {@link FunctionExpr} representing `e` raised to the power of the input expression's result. + * @returns A new {@link FunctionExpression} representing `e` raised to the power of the input expression's result. */ - export function exp(expression: Expr): FunctionExpr; + export function exp(expression: Expression): FunctionExpression; /** * @beta @@ -6775,9 +6993,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field whose numeric value will be used as the exponent. - * @return A new {@code FunctionExpr} representing 'e' raised to the power of the numeric value. + * @return A new {@code FunctionExpression} representing 'e' raised to the power of the numeric value. */ - export function exp(fieldName: string): FunctionExpr; + export function exp(fieldName: string): FunctionExpression; /** * @beta * Creates an aggregation that counts the number of distinct values of an evaluated expression. @@ -6785,7 +7003,7 @@ declare namespace FirebaseFirestore { * @param expression The expression to count distinct values of. * @return A new `AggregateFunction` representing the 'count_distinct' aggregation. */ - export function countDistinct(expression: Expr): AggregateFunction; + export function countDistinct(expression: Expression): AggregateFunction; /** * @beta * Creates an aggregation that counts the number of distinct values of a field. @@ -6804,9 +7022,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expr The expression representing the string. - * @return A new {@code Expr} representing the length of the string in bytes. + * @return A new {@code Expression} representing the length of the string in bytes. */ - export function byteLength(expr: Expr): FunctionExpr; + export function byteLength(expr: Expression): FunctionExpression; /** * @beta * Creates an expression that calculates the length of a string represented by a field in UTF-8 bytes, or just the length of a Blob. @@ -6817,9 +7035,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the length of the string in bytes. + * @return A new {@code Expression} representing the length of the string in bytes. */ - export function byteLength(fieldName: string): FunctionExpr; + export function byteLength(fieldName: string): FunctionExpression; /** * @beta @@ -6831,9 +7049,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the length of the string. + * @return A new {@code Expression} representing the length of the string. */ - export function charLength(fieldName: string): FunctionExpr; + export function charLength(fieldName: string): FunctionExpression; /** * @beta @@ -6845,9 +7063,11 @@ declare namespace FirebaseFirestore { * ``` * * @param stringExpression The expression representing the string to calculate the length of. - * @return A new {@code Expr} representing the length of the string. + * @return A new {@code Expression} representing the length of the string. */ - export function charLength(stringExpression: Expr): FunctionExpr; + export function charLength( + stringExpression: Expression + ): FunctionExpression; /** * @beta * Creates an expression that performs a case-sensitive wildcard string comparison against a @@ -6860,9 +7080,9 @@ declare namespace FirebaseFirestore { * * @param fieldName The name of the field containing the string. * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new {@code Expr} representing the 'like' comparison. + * @return A new {@code Expression} representing the 'like' comparison. */ - export function like(fieldName: string, pattern: string): BooleanExpr; + export function like(fieldName: string, pattern: string): BooleanExpression; /** * @beta * Creates an expression that performs a case-sensitive wildcard string comparison against a @@ -6875,9 +7095,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The name of the field containing the string. * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new {@code Expr} representing the 'like' comparison. + * @return A new {@code Expression} representing the 'like' comparison. */ - export function like(fieldName: string, pattern: Expr): BooleanExpr; + export function like( + fieldName: string, + pattern: Expression + ): BooleanExpression; /** * @beta @@ -6890,9 +7113,12 @@ declare namespace FirebaseFirestore { * * @param stringExpression The expression representing the string to perform the comparison on. * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new {@code BooleanExpr} representing the 'like' comparison. + * @return A new {@code BooleanExpression} representing the 'like' comparison. */ - export function like(stringExpression: Expr, pattern: string): BooleanExpr; + export function like( + stringExpression: Expression, + pattern: string + ): BooleanExpression; /** * @beta * Creates an expression that performs a case-sensitive wildcard string comparison. @@ -6904,9 +7130,12 @@ declare namespace FirebaseFirestore { * * @param stringExpression The expression representing the string to perform the comparison on. * @param pattern The pattern to search for. You can use "%" as a wildcard character. - * @return A new {@code Expr} representing the 'like' comparison. + * @return A new {@code Expression} representing the 'like' comparison. */ - export function like(stringExpression: Expr, pattern: Expr): BooleanExpr; + export function like( + stringExpression: Expression, + pattern: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string field contains a specified regular expression as @@ -6919,12 +7148,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The name of the field containing the string. * @param pattern The regular expression to use for the search. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ export function regexContains( fieldName: string, pattern: string - ): BooleanExpr; + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string field contains a specified regular expression as @@ -6937,12 +7166,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The name of the field containing the string. * @param pattern The regular expression to use for the search. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ export function regexContains( fieldName: string, - pattern: Expr - ): BooleanExpr; + pattern: Expression + ): BooleanExpression; /** * @beta @@ -6956,12 +7185,12 @@ declare namespace FirebaseFirestore { * * @param stringExpression The expression representing the string to perform the regex comparison on. * @param pattern The regular expression string to search for within the `stringExpression`. - * @return A new {@code BooleanExpr} representing the result of the regex contains comparison. + * @return A new {@code BooleanExpression} representing the result of the regex contains comparison. */ export function regexContains( - stringExpression: Expr, + stringExpression: Expression, pattern: string - ): BooleanExpr; + ): BooleanExpression; /** * @beta @@ -6978,12 +7207,12 @@ declare namespace FirebaseFirestore { * * @param stringExpression The expression representing the string to perform the comparison on. * @param pattern The regular expression to use for the search. - * @return A new {@code BooleanExpr} representing the 'contains' comparison. + * @return A new {@code BooleanExpression} representing the 'contains' comparison. */ export function regexContains( - stringExpression: Expr, - pattern: Expr - ): BooleanExpr; + stringExpression: Expression, + pattern: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string field matches a specified regular expression. @@ -6995,15 +7224,18 @@ declare namespace FirebaseFirestore { * * @param fieldName The name of the field containing the string. * @param pattern The regular expression to use for the match. - * @return A new {@code Expr} representing the regular expression match. + * @return A new {@code Expression} representing the regular expression match. */ - export function regexMatch(fieldName: string, pattern: string): BooleanExpr; + export function regexMatch( + fieldName: string, + pattern: string + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string field matches a specified regular expression. * - * The `pattern` parameter is an {@link Expr} that evaluates to the regular expression string. + * The `pattern` parameter is an {@link Expression} that evaluates to the regular expression string. * This allows for dynamic regex patterns, such as those stored in other fields. * * ```typescript @@ -7012,10 +7244,13 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing the string value to be matched. - * @param pattern An {@link Expr} that evaluates to the regular expression string to use for the match. - * @return A new {@link BooleanExpr} representing the result of the regular expression match. + * @param pattern An {@link Expression} that evaluates to the regular expression string to use for the match. + * @return A new {@link BooleanExpression} representing the result of the regular expression match. */ - export function regexMatch(fieldName: string, pattern: Expr): BooleanExpr; + export function regexMatch( + fieldName: string, + pattern: Expression + ): BooleanExpression; /** * @beta @@ -7029,12 +7264,12 @@ declare namespace FirebaseFirestore { * * @param stringExpression An expression that evaluates to the string to match against. * @param pattern The regular expression to use for the match. - * @return A new {@link BooleanExpr} representing the result of the regular expression match. + * @return A new {@link BooleanExpression} representing the result of the regular expression match. */ export function regexMatch( - stringExpression: Expr, + stringExpression: Expression, pattern: string - ): BooleanExpr; + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string expression matches a specified regular @@ -7047,80 +7282,80 @@ declare namespace FirebaseFirestore { * * @param stringExpression The expression representing the string to match against. * @param pattern The regular expression to use for the match. - * @return A new {@code Expr} representing the regular expression match. + * @return A new {@code Expression} representing the regular expression match. */ export function regexMatch( - stringExpression: Expr, - pattern: Expr - ): BooleanExpr; + stringExpression: Expression, + pattern: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string field contains a specified substring. * * ```typescript * // Check if the 'description' field contains "example". - * strContains("description", "example"); + * stringContains("description", "example"); * ``` * * @param fieldName The name of the field containing the string. * @param substring The substring to search for. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ - export function strContains( + export function stringContains( fieldName: string, substring: string - ): BooleanExpr; + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string field contains a substring specified by an expression. * * ```typescript * // Check if the 'description' field contains the value of the 'keyword' field. - * strContains("description", field("keyword")); + * stringContains("description", field("keyword")); * ``` * * @param fieldName The name of the field containing the string. * @param substring The expression representing the substring to search for. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ - export function strContains( + export function stringContains( fieldName: string, - substring: Expr - ): BooleanExpr; + substring: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string expression contains a specified substring. * * ```typescript * // Check if the 'description' field contains "example". - * strContains(field("description"), "example"); + * stringContains(field("description"), "example"); * ``` * * @param stringExpression The expression representing the string to perform the comparison on. * @param substring The substring to search for. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ - export function strContains( - stringExpression: Expr, + export function stringContains( + stringExpression: Expression, substring: string - ): BooleanExpr; + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string expression contains a substring specified by another expression. * * ```typescript * // Check if the 'description' field contains the value of the 'keyword' field. - * strContains(field("description"), field("keyword")); + * stringContains(field("description"), field("keyword")); * ``` * * @param stringExpression The expression representing the string to perform the comparison on. * @param substring The expression representing the substring to search for. - * @return A new {@code Expr} representing the 'contains' comparison. + * @return A new {@code Expression} representing the 'contains' comparison. */ - export function strContains( - stringExpression: Expr, - substring: Expr - ): BooleanExpr; + export function stringContains( + stringExpression: Expression, + substring: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value starts with a given prefix. @@ -7132,9 +7367,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name to check. * @param prefix The prefix to check for. - * @return A new {@code Expr} representing the 'starts with' comparison. + * @return A new {@code Expression} representing the 'starts with' comparison. */ - export function startsWith(fieldName: string, prefix: string): BooleanExpr; + export function startsWith( + fieldName: string, + prefix: string + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value starts with a given prefix. @@ -7146,9 +7384,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name to check. * @param prefix The expression representing the prefix. - * @return A new {@code Expr} representing the 'starts with' comparison. + * @return A new {@code Expression} representing the 'starts with' comparison. */ - export function startsWith(fieldName: string, prefix: Expr): BooleanExpr; + export function startsWith( + fieldName: string, + prefix: Expression + ): BooleanExpression; /** * @beta @@ -7161,12 +7402,12 @@ declare namespace FirebaseFirestore { * * @param stringExpression An expression that evaluates to a string, which will be checked for the prefix. * @param prefix The string prefix to check for. - * @return A new {@code BooleanExpr} representing the 'starts with' comparison. + * @return A new {@code BooleanExpression} representing the 'starts with' comparison. */ export function startsWith( - stringExpression: Expr, + stringExpression: Expression, prefix: string - ): BooleanExpr; + ): BooleanExpression; /** * @beta @@ -7179,12 +7420,12 @@ declare namespace FirebaseFirestore { * * @param stringExpression The string expression to check. * @param prefix The prefix expression to check for. - * @return A new {@code BooleanExpr} representing the 'starts with' comparison. + * @return A new {@code BooleanExpression} representing the 'starts with' comparison. */ export function startsWith( - stringExpression: Expr, - prefix: Expr - ): BooleanExpr; + stringExpression: Expression, + prefix: Expression + ): BooleanExpression; /** * @beta @@ -7197,9 +7438,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name to check. * @param suffix The suffix to check for. - * @return A new {@link BooleanExpr} representing the 'ends with' comparison. + * @return A new {@link BooleanExpression} representing the 'ends with' comparison. */ - export function endsWith(fieldName: string, suffix: string): BooleanExpr; + export function endsWith( + fieldName: string, + suffix: string + ): BooleanExpression; /** * @beta * Creates an expression that checks if a field's value ends with a given postfix. @@ -7211,9 +7455,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name to check. * @param suffix The expression representing the postfix. - * @return A new {@code Expr} representing the 'ends with' comparison. + * @return A new {@code Expression} representing the 'ends with' comparison. */ - export function endsWith(fieldName: string, suffix: Expr): BooleanExpr; + export function endsWith( + fieldName: string, + suffix: Expression + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string expression ends with a given postfix. @@ -7225,12 +7472,12 @@ declare namespace FirebaseFirestore { * * @param stringExpression The expression to check. * @param suffix The postfix to check for. - * @return A new {@code Expr} representing the 'ends with' comparison. + * @return A new {@code Expression} representing the 'ends with' comparison. */ export function endsWith( - stringExpression: Expr, + stringExpression: Expression, suffix: string - ): BooleanExpr; + ): BooleanExpression; /** * @beta * Creates an expression that checks if a string expression ends with a given postfix. @@ -7242,9 +7489,12 @@ declare namespace FirebaseFirestore { * * @param stringExpression The expression to check. * @param suffix The postfix to check for. - * @return A new {@code Expr} representing the 'ends with' comparison. + * @return A new {@code Expression} representing the 'ends with' comparison. */ - export function endsWith(stringExpression: Expr, suffix: Expr): BooleanExpr; + export function endsWith( + stringExpression: Expression, + suffix: Expression + ): BooleanExpression; /** * @beta @@ -7256,9 +7506,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the lowercase string. + * @return A new {@code Expression} representing the lowercase string. */ - export function toLower(fieldName: string): FunctionExpr; + export function toLower(fieldName: string): FunctionExpression; /** * @beta @@ -7270,9 +7520,9 @@ declare namespace FirebaseFirestore { * ``` * * @param stringExpression The expression representing the string to convert to lowercase. - * @return A new {@code Expr} representing the lowercase string. + * @return A new {@code Expression} representing the lowercase string. */ - export function toLower(stringExpression: Expr): FunctionExpr; + export function toLower(stringExpression: Expression): FunctionExpression; /** * @beta * Creates an expression that converts a string field to uppercase. @@ -7283,9 +7533,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the uppercase string. + * @return A new {@code Expression} representing the uppercase string. */ - export function toUpper(fieldName: string): FunctionExpr; + export function toUpper(fieldName: string): FunctionExpression; /** * @beta @@ -7297,9 +7547,9 @@ declare namespace FirebaseFirestore { * ``` * * @param stringExpression The expression representing the string to convert to uppercase. - * @return A new {@code FunctionExpr} representing the uppercase string. + * @return A new {@code FunctionExpression} representing the uppercase string. */ - export function toUpper(stringExpression: Expr): FunctionExpr; + export function toUpper(stringExpression: Expression): FunctionExpression; /** * @beta * Creates an expression that removes leading and trailing whitespace from a string field. @@ -7310,9 +7560,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing the string. - * @return A new {@code Expr} representing the trimmed string. + * @return A new {@code Expression} representing the trimmed string. */ - export function trim(fieldName: string): FunctionExpr; + export function trim(fieldName: string): FunctionExpression; /** * @beta * Creates an expression that removes leading and trailing whitespace from a string expression. @@ -7323,9 +7573,9 @@ declare namespace FirebaseFirestore { * ``` * * @param stringExpression The expression representing the string to trim. - * @return A new {@code Expr} representing the trimmed string. + * @return A new {@code Expression} representing the trimmed string. */ - export function trim(stringExpression: Expr): FunctionExpr; + export function trim(stringExpression: Expression): FunctionExpression; /** * @beta @@ -7333,38 +7583,38 @@ declare namespace FirebaseFirestore { * * ```typescript * // Combine the 'firstName' field, a space, and the 'lastName' field into a single string. - * strConcat("firstName", " ", field("lastName")); + * stringConcat("firstName", " ", field("lastName")); * ``` * * @param fieldName The name of the field to use as the initial string value for concatenation. * @param secondString An expression or string literal to concatenate. * @param otherStrings Optional additional expressions or literals (typically strings) to concatenate. - * @return A new {@code FunctionExpr} representing the concatenated string. + * @return A new {@code FunctionExpression} representing the concatenated string. */ - export function strConcat( + export function stringConcat( fieldName: string, - secondString: Expr | string, - ...otherStrings: Array - ): FunctionExpr; + secondString: Expression | string, + ...otherStrings: Array + ): FunctionExpression; /** * @beta * Creates an expression that concatenates string expressions together. * * ```typescript * // Combine the 'firstName', " ", and 'lastName' fields into a single string - * strConcat(field("firstName"), " ", field("lastName")); + * stringConcat(field("firstName"), " ", field("lastName")); * ``` * * @param firstString The initial string expression to concatenate to. * @param secondString An expression or string literal to concatenate. * @param otherStrings Optional additional expressions or literals (typically strings) to concatenate. - * @return A new {@code Expr} representing the concatenated string. + * @return A new {@code Expression} representing the concatenated string. */ - export function strConcat( - firstString: Expr, - secondString: Expr | string, - ...otherStrings: Array - ): FunctionExpr; + export function stringConcat( + firstString: Expression, + secondString: Expression | string, + ...otherStrings: Array + ): FunctionExpression; /** * @beta * Accesses a value from a map (object) field using the provided key. @@ -7376,9 +7626,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The field name of the map field. * @param subField The key to access in the map. - * @return A new {@code Expr} representing the value associated with the given key in the map. + * @return A new {@code Expression} representing the value associated with the given key in the map. */ - export function mapGet(fieldName: string, subField: string): FunctionExpr; + export function mapGet( + fieldName: string, + subField: string + ): FunctionExpression; /** * @beta * Accesses a value from a map (object) expression using the provided key. @@ -7390,9 +7643,12 @@ declare namespace FirebaseFirestore { * * @param mapExpression The expression representing the map. * @param subField The key to access in the map. - * @return A new {@code Expr} representing the value associated with the given key in the map. + * @return A new {@code Expression} representing the value associated with the given key in the map. */ - export function mapGet(mapExpression: Expr, subField: string): FunctionExpr; + export function mapGet( + mapExpression: Expression, + subField: string + ): FunctionExpression; /** * @beta * Creates an aggregation that counts the total number of stage inputs. @@ -7412,13 +7668,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Count the number of items where the price is greater than 10 - * count(field("price").gt(10)).as("expensiveItemCount"); + * count(field("price").greaterThan(10)).as("expensiveItemCount"); * ``` * * @param expression The expression to count. * @return A new {@code AggregateFunction} representing the 'count' aggregation. */ - export function count(expression: Expr): AggregateFunction; + export function count(expression: Expression): AggregateFunction; /** * @beta * Creates an aggregation that counts the number of stage inputs where the input field exists. @@ -7445,7 +7701,7 @@ declare namespace FirebaseFirestore { * @param expression The expression to sum up. * @return A new {@code AggregateFunction} representing the 'sum' aggregation. */ - export function sum(expression: Expr): AggregateFunction; + export function sum(expression: Expression): AggregateFunction; /** * @beta * Creates an aggregation that calculates the sum of a field's values across multiple stage @@ -7467,13 +7723,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Calculate the average age of users - * avg(field("age")).as("averageAge"); + * average(field("age")).as("averageAge"); * ``` * * @param expression The expression representing the values to average. - * @return A new {@code AggregateFunction} representing the 'avg' aggregation. + * @return A new {@code AggregateFunction} representing the 'average' aggregation. */ - export function avg(expression: Expr): AggregateFunction; + export function average(expression: Expression): AggregateFunction; /** * @beta * Creates an aggregation that calculates the average (mean) of a field's values across multiple @@ -7481,13 +7737,13 @@ declare namespace FirebaseFirestore { * * ```typescript * // Calculate the average age of users - * avg("age").as("averageAge"); + * average("age").as("averageAge"); * ``` * * @param fieldName The name of the field containing numeric values to average. - * @return A new {@code AggregateFunction} representing the 'avg' aggregation. + * @return A new {@code AggregateFunction} representing the 'average' aggregation. */ - export function avg(fieldName: string): AggregateFunction; + export function average(fieldName: string): AggregateFunction; /** * @beta * Creates an aggregation that finds the minimum value of an expression across multiple stage @@ -7501,7 +7757,7 @@ declare namespace FirebaseFirestore { * @param expression The expression to find the minimum value of. * @return A new {@code AggregateFunction} representing the 'min' aggregation. */ - export function minimum(expression: Expr): AggregateFunction; + export function minimum(expression: Expression): AggregateFunction; /** * @beta * Creates an aggregation that finds the minimum value of a field across multiple stage inputs. @@ -7528,7 +7784,7 @@ declare namespace FirebaseFirestore { * @param expression The expression to find the maximum value of. * @return A new {@code AggregateFunction} representing the 'max' aggregation. */ - export function maximum(expression: Expr): AggregateFunction; + export function maximum(expression: Expression): AggregateFunction; /** * @beta * Creates an aggregation that finds the maximum value of a field across multiple stage inputs. @@ -7553,12 +7809,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The name of the field containing the first vector. * @param vector The other vector (as an array of doubles) or {@link VectorValue} to compare against. - * @return A new {@code Expr} representing the Cosine distance between the two vectors. + * @return A new {@code Expression} representing the Cosine distance between the two vectors. */ export function cosineDistance( fieldName: string, vector: number[] | VectorValue - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Calculates the Cosine distance between a field's vector value and a vector expression. @@ -7569,13 +7825,13 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing the first vector. - * @param vectorExpression The other vector (represented as an Expr) to compare against. - * @return A new {@code Expr} representing the cosine distance between the two vectors. + * @param vectorExpression The other vector (represented as an Expression) to compare against. + * @return A new {@code Expression} representing the cosine distance between the two vectors. */ export function cosineDistance( fieldName: string, - vectorExpression: Expr - ): FunctionExpr; + vectorExpression: Expression + ): FunctionExpression; /** * @beta @@ -7593,14 +7849,14 @@ declare namespace FirebaseFirestore { * cosineDistance(field("vector1"), field("vector2")); * ``` * - * @param vectorExpression The first vector, represented as an {@link Expr} (e.g., a field path). - * @param vector The second vector, which can be either a numeric array literal (`number[]`) or another {@link Expr}. - * @return A new {@link FunctionExpr} representing the cosine distance. + * @param vectorExpression The first vector, represented as an {@link Expression} (e.g., a field path). + * @param vector The second vector, which can be either a numeric array literal (`number[]`) or another {@link Expression}. + * @return A new {@link FunctionExpression} representing the cosine distance. */ export function cosineDistance( - vectorExpression: Expr, - vector: number[] | Expr - ): FunctionExpr; + vectorExpression: Expression, + vector: number[] | Expression + ): FunctionExpression; /** * @beta * Calculates the Cosine distance between two vector expressions. @@ -7610,14 +7866,14 @@ declare namespace FirebaseFirestore { * cosineDistance(field("userVector"), field("itemVector")); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to compare against. - * @param otherVectorExpression The other vector (represented as an Expr) to compare against. - * @return A new {@code Expr} representing the cosine distance between the two vectors. + * @param vectorExpression The first vector (represented as an Expression) to compare against. + * @param otherVectorExpression The other vector (represented as an Expression) to compare against. + * @return A new {@code Expression} representing the cosine distance between the two vectors. */ export function cosineDistance( - vectorExpression: Expr, - otherVectorExpression: Expr - ): FunctionExpr; + vectorExpression: Expression, + otherVectorExpression: Expression + ): FunctionExpression; /** * @beta * Calculates the dot product between a field's vector value and a double array. @@ -7629,12 +7885,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The name of the field containing the first vector. * @param vector The other vector (as an array of doubles or VectorValue) to calculate with. - * @return A new {@code Expr} representing the dot product between the two vectors. + * @return A new {@code Expression} representing the dot product between the two vectors. */ export function dotProduct( fieldName: string, vector: number[] | VectorValue - ): FunctionExpr; + ): FunctionExpression; /** * @beta @@ -7646,13 +7902,13 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing the first vector. - * @param vectorExpression The other vector (represented as an Expr) to calculate with. - * @return A new {@code Expr} representing the dot product between the two vectors. + * @param vectorExpression The other vector (represented as an Expression) to calculate with. + * @return A new {@code Expression} representing the dot product between the two vectors. */ export function dotProduct( fieldName: string, - vectorExpression: Expr - ): FunctionExpr; + vectorExpression: Expression + ): FunctionExpression; /** * @beta @@ -7663,14 +7919,14 @@ declare namespace FirebaseFirestore { * dotProduct(field("features"), [0.5, 0.8, 0.2]); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to calculate with. + * @param vectorExpression The first vector (represented as an Expression) to calculate with. * @param vector The other vector (as an array of numbers or VectorValue) to calculate with. - * @return A new {@code Expr} representing the dot product between the two vectors. + * @return A new {@code Expression} representing the dot product between the two vectors. */ export function dotProduct( - vectorExpression: Expr, + vectorExpression: Expression, vector: number[] | VectorValue - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Calculates the dot product between two vector expressions. @@ -7680,14 +7936,14 @@ declare namespace FirebaseFirestore { * dotProduct(field("docVector1"), field("docVector2")); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to calculate with. - * @param otherVectorExpression The other vector (represented as an Expr) to calculate with. - * @return A new {@code Expr} representing the dot product between the two vectors. + * @param vectorExpression The first vector (represented as an Expression) to calculate with. + * @param otherVectorExpression The other vector (represented as an Expression) to calculate with. + * @return A new {@code Expression} representing the dot product between the two vectors. */ export function dotProduct( - vectorExpression: Expr, - otherVectorExpression: Expr - ): FunctionExpr; + vectorExpression: Expression, + otherVectorExpression: Expression + ): FunctionExpression; /** * @beta @@ -7701,12 +7957,12 @@ declare namespace FirebaseFirestore { * * @param fieldName The name of the field containing the first vector. * @param vector The other vector (as an array of doubles or VectorValue) to compare against. - * @return A new {@code Expr} representing the Euclidean distance between the two vectors. + * @return A new {@code Expression} representing the Euclidean distance between the two vectors. */ export function euclideanDistance( fieldName: string, vector: number[] | VectorValue - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Calculates the Euclidean distance between a field's vector value and a vector expression. @@ -7717,13 +7973,13 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field containing the first vector. - * @param vectorExpression The other vector (represented as an Expr) to compare against. - * @return A new {@code Expr} representing the Euclidean distance between the two vectors. + * @param vectorExpression The other vector (represented as an Expression) to compare against. + * @return A new {@code Expression} representing the Euclidean distance between the two vectors. */ export function euclideanDistance( fieldName: string, - vectorExpression: Expr - ): FunctionExpr; + vectorExpression: Expression + ): FunctionExpression; /** * @beta * Calculates the Euclidean distance between a vector expression and a double array. @@ -7734,14 +7990,14 @@ declare namespace FirebaseFirestore { * euclideanDistance(field("location"), [37.7749, -122.4194]); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to compare against. + * @param vectorExpression The first vector (represented as an Expression) to compare against. * @param vector The other vector (as an array of doubles or VectorValue) to compare against. - * @return A new {@code Expr} representing the Euclidean distance between the two vectors. + * @return A new {@code Expression} representing the Euclidean distance between the two vectors. */ export function euclideanDistance( - vectorExpression: Expr, + vectorExpression: Expression, vector: number[] | VectorValue - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Calculates the Euclidean distance between two vector expressions. @@ -7751,14 +8007,14 @@ declare namespace FirebaseFirestore { * euclideanDistance(field("pointA"), field("pointB")); * ``` * - * @param vectorExpression The first vector (represented as an Expr) to compare against. - * @param otherVectorExpression The other vector (represented as an Expr) to compare against. - * @return A new {@code Expr} representing the Euclidean distance between the two vectors. + * @param vectorExpression The first vector (represented as an Expression) to compare against. + * @param otherVectorExpression The other vector (represented as an Expression) to compare against. + * @return A new {@code Expression} representing the Euclidean distance between the two vectors. */ export function euclideanDistance( - vectorExpression: Expr, - otherVectorExpression: Expr - ): FunctionExpr; + vectorExpression: Expression, + otherVectorExpression: Expression + ): FunctionExpression; /** * @beta * Creates an expression that calculates the length of a Firestore Vector. @@ -7769,9 +8025,11 @@ declare namespace FirebaseFirestore { * ``` * * @param vectorExpression The expression representing the Firestore Vector. - * @return A new {@code Expr} representing the length of the array. + * @return A new {@code Expression} representing the length of the array. */ - export function vectorLength(vectorExpression: Expr): FunctionExpr; + export function vectorLength( + vectorExpression: Expression + ): FunctionExpression; /** * @beta @@ -7783,9 +8041,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field representing the Firestore Vector. - * @return A new {@code FunctionExpr} representing the length (dimension) of the vector. + * @return A new {@code FunctionExpression} representing the length (dimension) of the vector. */ - export function vectorLength(fieldName: string): FunctionExpr; + export function vectorLength(fieldName: string): FunctionExpression; /** * @beta * Creates an expression that interprets an expression as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC) @@ -7797,9 +8055,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expr The expression representing the number of microseconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - export function unixMicrosToTimestamp(expr: Expr): FunctionExpr; + export function unixMicrosToTimestamp(expr: Expression): FunctionExpression; /** * @beta * Creates an expression that interprets a field's value as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC) @@ -7811,9 +8069,11 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field representing the number of microseconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - export function unixMicrosToTimestamp(fieldName: string): FunctionExpr; + export function unixMicrosToTimestamp( + fieldName: string + ): FunctionExpression; /** * @beta * Creates an expression that converts a timestamp expression to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC). @@ -7824,9 +8084,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expr The expression representing the timestamp. - * @return A new {@code Expr} representing the number of microseconds since epoch. + * @return A new {@code Expression} representing the number of microseconds since epoch. */ - export function timestampToUnixMicros(expr: Expr): FunctionExpr; + export function timestampToUnixMicros(expr: Expression): FunctionExpression; /** * @beta * Creates an expression that converts a timestamp field to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC). @@ -7837,9 +8097,11 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field representing the timestamp. - * @return A new {@code Expr} representing the number of microseconds since epoch. + * @return A new {@code Expression} representing the number of microseconds since epoch. */ - export function timestampToUnixMicros(fieldName: string): FunctionExpr; + export function timestampToUnixMicros( + fieldName: string + ): FunctionExpression; /** * @beta * Creates an expression that interprets an expression as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC) @@ -7851,9 +8113,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expr The expression representing the number of milliseconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - export function unixMillisToTimestamp(expr: Expr): FunctionExpr; + export function unixMillisToTimestamp(expr: Expression): FunctionExpression; /** * @beta * Creates an expression that interprets a field's value as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC) @@ -7865,9 +8127,11 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field representing the number of milliseconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - export function unixMillisToTimestamp(fieldName: string): FunctionExpr; + export function unixMillisToTimestamp( + fieldName: string + ): FunctionExpression; /** * @beta * Creates an expression that converts a timestamp expression to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC). @@ -7878,9 +8142,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expr The expression representing the timestamp. - * @return A new {@code Expr} representing the number of milliseconds since epoch. + * @return A new {@code Expression} representing the number of milliseconds since epoch. */ - export function timestampToUnixMillis(expr: Expr): FunctionExpr; + export function timestampToUnixMillis(expr: Expression): FunctionExpression; /** * @beta * Creates an expression that converts a timestamp field to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC). @@ -7891,9 +8155,11 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field representing the timestamp. - * @return A new {@code Expr} representing the number of milliseconds since epoch. + * @return A new {@code Expression} representing the number of milliseconds since epoch. */ - export function timestampToUnixMillis(fieldName: string): FunctionExpr; + export function timestampToUnixMillis( + fieldName: string + ): FunctionExpression; /** * @beta * Creates an expression that interprets an expression as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC) @@ -7905,9 +8171,11 @@ declare namespace FirebaseFirestore { * ``` * * @param expr The expression representing the number of seconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - export function unixSecondsToTimestamp(expr: Expr): FunctionExpr; + export function unixSecondsToTimestamp( + expr: Expression + ): FunctionExpression; /** * @beta * Creates an expression that interprets a field's value as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC) @@ -7919,9 +8187,11 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field representing the number of seconds since epoch. - * @return A new {@code Expr} representing the timestamp. + * @return A new {@code Expression} representing the timestamp. */ - export function unixSecondsToTimestamp(fieldName: string): FunctionExpr; + export function unixSecondsToTimestamp( + fieldName: string + ): FunctionExpression; /** * @beta * Creates an expression that converts a timestamp expression to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC). @@ -7932,9 +8202,11 @@ declare namespace FirebaseFirestore { * ``` * * @param expr The expression representing the timestamp. - * @return A new {@code Expr} representing the number of seconds since epoch. + * @return A new {@code Expression} representing the number of seconds since epoch. */ - export function timestampToUnixSeconds(expr: Expr): FunctionExpr; + export function timestampToUnixSeconds( + expr: Expression + ): FunctionExpression; /** * @beta * Creates an expression that converts a timestamp field to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC). @@ -7945,9 +8217,11 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field representing the timestamp. - * @return A new {@code Expr} representing the number of seconds since epoch. + * @return A new {@code Expression} representing the number of seconds since epoch. */ - export function timestampToUnixSeconds(fieldName: string): FunctionExpr; + export function timestampToUnixSeconds( + fieldName: string + ): FunctionExpression; /** * @beta * Creates an expression that adds a specified amount of time to a timestamp. @@ -7960,13 +8234,13 @@ declare namespace FirebaseFirestore { * @param timestamp The expression representing the timestamp. * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. * @param amount The expression evaluates to amount of the unit. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ export function timestampAdd( - timestamp: Expr, - unit: Expr, - amount: Expr - ): FunctionExpr; + timestamp: Expression, + unit: Expression, + amount: Expression + ): FunctionExpression; /** * @beta @@ -7980,10 +8254,10 @@ declare namespace FirebaseFirestore { * @param timestamp The expression representing the timestamp. * @param unit The unit of time to add: 'microsecond', 'millisecond', 'second', 'minute', 'hour', or 'day'. * @param amount The amount of time to add. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ export function timestampAdd( - timestamp: Expr, + timestamp: Expression, unit: | 'microsecond' | 'millisecond' @@ -7992,7 +8266,7 @@ declare namespace FirebaseFirestore { | 'hour' | 'day', amount: number - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Creates an expression that adds a specified amount of time to a timestamp represented by a field. @@ -8005,7 +8279,7 @@ declare namespace FirebaseFirestore { * @param fieldName The name of the field representing the timestamp. * @param unit The unit of time to add (e.g., "day", "hour"). * @param amount The amount of time to add. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ export function timestampAdd( fieldName: string, @@ -8017,42 +8291,42 @@ declare namespace FirebaseFirestore { | 'hour' | 'day', amount: number - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Creates an expression that subtracts a specified amount of time from a timestamp. * * ```typescript * // Subtract some duration determined by field 'unit' and 'amount' from the 'timestamp' field. - * timestampSub(field("timestamp"), field("unit"), field("amount")); + * timestampSubtract(field("timestamp"), field("unit"), field("amount")); * ``` * * @param timestamp The expression representing the timestamp. * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. * @param amount The expression evaluates to amount of the unit. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ - export function timestampSub( - timestamp: Expr, - unit: Expr, - amount: Expr - ): FunctionExpr; + export function timestampSubtract( + timestamp: Expression, + unit: Expression, + amount: Expression + ): FunctionExpression; /** * @beta * Creates an expression that subtracts a specified amount of time from a timestamp. * * ```typescript * // Subtract 1 day from the 'timestamp' field. - * timestampSub(field("timestamp"), "day", 1); + * timestampSubtract(field("timestamp"), "day", 1); * ``` * * @param timestamp The expression representing the timestamp. * @param unit The unit of time to subtract (e.g., "day", "hour"). * @param amount The amount of time to subtract. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ - export function timestampSub( - timestamp: Expr, + export function timestampSubtract( + timestamp: Expression, unit: | 'microsecond' | 'millisecond' @@ -8061,22 +8335,22 @@ declare namespace FirebaseFirestore { | 'hour' | 'day', amount: number - ): FunctionExpr; + ): FunctionExpression; /** * @beta * Creates an expression that subtracts a specified amount of time from a timestamp represented by a field. * * ```typescript * // Subtract 1 day from the 'timestamp' field. - * timestampSub("timestamp", "day", 1); + * timestampSubtract("timestamp", "day", 1); * ``` * * @param fieldName The name of the field representing the timestamp. * @param unit The unit of time to subtract (e.g., "day", "hour"). * @param amount The amount of time to subtract. - * @return A new {@code Expr} representing the resulting timestamp. + * @return A new {@code Expression} representing the resulting timestamp. */ - export function timestampSub( + export function timestampSubtract( fieldName: string, unit: | 'microsecond' @@ -8086,7 +8360,22 @@ declare namespace FirebaseFirestore { | 'hour' | 'day', amount: number - ): FunctionExpr; + ): FunctionExpression; + + /** + * @beta + * + * Creates an expression that evaluates to the current server timestamp. + * + * ```typescript + * // Get the current server timestamp + * currentTimestamp() + * ``` + * + * @return A new Expression representing the current server timestamp. + */ + export function currentTimestamp(): FunctionExpression; + /** * @beta * Creates an expression that performs a logical 'AND' operation on multiple filter conditions. @@ -8094,19 +8383,19 @@ declare namespace FirebaseFirestore { * ```typescript * // Check if the 'age' field is greater than 18 AND the 'city' field is "London" AND * // the 'status' field is "active" - * const condition = and(gt("age", 18), eq("city", "London"), eq("status", "active")); + * const condition = and(greaterThan("age", 18), equal("city", "London"), equal("status", "active")); * ``` * * @param first The first filter condition. * @param second The second filter condition. * @param more Additional filter conditions to 'AND' together. - * @return A new {@code Expr} representing the logical 'AND' operation. + * @return A new {@code Expression} representing the logical 'AND' operation. */ export function and( - first: BooleanExpr, - second: BooleanExpr, - ...more: BooleanExpr[] - ): BooleanExpr; + first: BooleanExpression, + second: BooleanExpression, + ...more: BooleanExpression[] + ): BooleanExpression; /** * @beta * Creates an expression that performs a logical 'OR' operation on multiple filter conditions. @@ -8114,19 +8403,19 @@ declare namespace FirebaseFirestore { * ```typescript * // Check if the 'age' field is greater than 18 OR the 'city' field is "London" OR * // the 'status' field is "active" - * const condition = or(gt("age", 18), eq("city", "London"), eq("status", "active")); + * const condition = or(greaterThan("age", 18), equal("city", "London"), equal("status", "active")); * ``` * * @param first The first filter condition. * @param second The second filter condition. * @param more Additional filter conditions to 'OR' together. - * @return A new {@code Expr} representing the logical 'OR' operation. + * @return A new {@code Expression} representing the logical 'OR' operation. */ export function or( - first: BooleanExpr, - second: BooleanExpr, - ...more: BooleanExpr[] - ): BooleanExpr; + first: BooleanExpression, + second: BooleanExpression, + ...more: BooleanExpression[] + ): BooleanExpression; /** * @beta * Creates an expression that returns the value of the base expression raised to the power of the exponent expression. @@ -8138,9 +8427,12 @@ declare namespace FirebaseFirestore { * * @param base The expression to raise to the power of the exponent. * @param exponent The expression to raise the base to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ - export function pow(base: Expr, exponent: Expr): FunctionExpr; + export function pow( + base: Expression, + exponent: Expression + ): FunctionExpression; /** * @beta * Creates an expression that returns the value of the base expression raised to the power of the exponent. @@ -8152,9 +8444,9 @@ declare namespace FirebaseFirestore { * * @param base The expression to raise to the power of the exponent. * @param exponent The constant value to raise the base to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ - export function pow(base: Expr, exponent: number): FunctionExpr; + export function pow(base: Expression, exponent: number): FunctionExpression; /** * @beta * Creates an expression that returns the value of the base field raised to the power of the exponent expression. @@ -8166,9 +8458,9 @@ declare namespace FirebaseFirestore { * * @param base The name of the field to raise to the power of the exponent. * @param exponent The expression to raise the base to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ - export function pow(base: string, exponent: Expr): FunctionExpr; + export function pow(base: string, exponent: Expression): FunctionExpression; /** * @beta * Creates an expression that returns the value of the base field raised to the power of the exponent. @@ -8180,9 +8472,9 @@ declare namespace FirebaseFirestore { * * @param base The name of the field to raise to the power of the exponent. * @param exponent The constant value to raise the base to the power of. - * @return A new `Expr` representing the power operation. + * @return A new `Expression` representing the power operation. */ - export function pow(base: string, exponent: number): FunctionExpr; + export function pow(base: string, exponent: number): FunctionExpression; /** * @beta * Creates an expression that returns the collection ID from a path. @@ -8193,9 +8485,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expression An expression evaluating to a path, which the collection ID will be extracted from. - * @return A new {@code Expr} representing the collectionId operation. + * @return A new {@code Expression} representing the collectionId operation. */ - export function collectionId(expression: Expr): FunctionExpr; + export function collectionId(expression: Expression): FunctionExpression; /** * @beta * Creates an expression that returns the collection ID from a path. @@ -8206,9 +8498,9 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field to get the collection ID from. - * @return A new {@code Expr} representing the collectionId operation. + * @return A new {@code Expression} representing the collectionId operation. */ - export function collectionId(fieldName: string): FunctionExpr; + export function collectionId(fieldName: string): FunctionExpression; /** * @beta * Creates an expression that calculates the length of a string, array, map, vector, or bytes. @@ -8222,9 +8514,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expression An expression evaluating to a string, array, map, vector, or bytes, which the length will be calculated for. - * @return A new `Expr` representing the length of the string, array, map, vector, or bytes. + * @return A new `Expression` representing the length of the string, array, map, vector, or bytes. */ - export function length(expression: Expr): FunctionExpr; + export function length(expression: Expression): FunctionExpression; /** * @beta * Creates an expression that calculates the length of a string, array, map, vector, or bytes. @@ -8238,118 +8530,260 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field to calculate the length of. - * @return A new `Expr` representing the length of the string, array, map, vector, or bytes. + * @return A new `Expression` representing the length of the string, array, map, vector, or bytes. */ - export function length(fieldName: string): FunctionExpr; + export function length(fieldName: string): FunctionExpression; /** * @beta * Creates an expression that reverses a string. * * ```typescript * // Reverse the value of the 'myString' field. - * strReverse(field("myString")); + * stringReverse(field("myString")); * ``` * * @param stringExpression An expression evaluating to a string value, which will be reversed. - * @return A new {@code Expr} representing the reversed string. + * @return A new {@code Expression} representing the reversed string. */ - export function strReverse(stringExpression: Expr): FunctionExpr; + export function stringReverse( + stringExpression: Expression + ): FunctionExpression; /** * @beta * Creates an expression that reverses a string value in the specified field. * * ```typescript * // Reverse the value of the 'myString' field. - * strReverse("myString"); + * stringReverse("myString"); * ``` * * @param field The name of the field representing the string to reverse. - * @return A new {@code Expr} representing the reversed string. + * @return A new {@code Expression} representing the reversed string. */ - export function strReverse(field: string): FunctionExpr; - // TODO(new-expression): Add new top-level expression function declarations above this line + export function stringReverse(field: string): FunctionExpression; + /** * @beta - * Creates an expression that computes the natural logarithm of a numeric value. + * Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed. * * ```typescript - * // Compute the natural logarithm of the 'value' field. - * ln(field("value")); + * // Concatenate the 'firstName' and 'lastName' fields with a space in between. + * concat(field("firstName"), " ", field("lastName")) * ``` * - * @param expression An expression evaluating to a numeric value, which the natural logarithm will be computed for. - * @return A new {@code Expr} representing the natural logarithm of the numeric value. + * @param first The first expressions to concatenate. + * @param second The second literal or expression to concatenate. + * @param others Additional literals or expressions to concatenate. + * @return A new `Expression` representing the concatenation. */ - export function ln(expression: Expr): FunctionExpr; + export function concat( + first: Expression, + second: Expression | unknown, + ...others: Array + ): FunctionExpression; + /** * @beta - * Creates an expression that computes the natural logarithm of a numeric value. + * Creates an expression that computes the absolute value of a numeric value. + * + * @param expr The expression to compute the absolute value of. + * @return A new {@code Expr} representing the absolute value of the numeric value. + */ + export function abs(expr: Expression): FunctionExpression; + + /** + * @beta + * Creates an expression that returns the `elseExpr` argument if `ifExpr` is absent, else return + * the result of the `ifExpr` argument evaluation. * * ```typescript - * // Compute the natural logarithm of the 'value' field. - * ln("value"); + * // Returns the value of the optional field 'optional_field', or returns 'default_value' + * // if the field is absent. + * ifAbsent(field("optional_field"), constant("default_value")) * ``` * - * @param fieldName The name of the field to compute the natural logarithm of. - * @return A new {@code Expr} representing the natural logarithm of the numeric value. + * @param ifExpr The expression to check for absence. + * @param elseExpr The expression that will be evaluated and returned if [ifExpr] is absent. + * @return A new Expression representing the ifAbsent operation. + */ + export function ifAbsent( + ifExpr: Expression, + elseExpr: Expression + ): Expression; + + /** + * @beta + * Creates an expression that returns the `elseValue` argument if `ifExpr` is absent, else + * return the result of the `ifExpr` argument evaluation. + * + * ```typescript + * // Returns the value of the optional field 'optional_field', or returns 'default_value' + * // if the field is absent. + * ifAbsent(field("optional_field"), "default_value") + * ``` + * + * @param ifExpr The expression to check for absence. + * @param elseValue The value that will be returned if `ifExpr` evaluates to an absent value. + * @return A new [Expression] representing the ifAbsent operation. + */ + export function ifAbsent( + ifExpr: Expression, + elseValue: unknown + ): Expression; + + /** + * @beta + * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is absent, else + * return the value of the field. + * + * ```typescript + * // Returns the value of the optional field 'optional_field', or returns the value of + * // 'default_field' if 'optional_field' is absent. + * ifAbsent("optional_field", field("default_field")) + * ``` + * + * @param ifFieldName The field to check for absence. + * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is + * absent. + * @return A new Expression representing the ifAbsent operation. */ - export function ln(fieldName: string): FunctionExpr; + export function ifAbsent( + ifFieldName: string, + elseExpr: Expression + ): Expression; + /** * @beta - * Creates an expression that computes the logarithm of an expression to a given base. + * Creates an expression that joins the elements of an array into a string. * * ```typescript - * // Compute the logarithm of the 'value' field with base 10. - * log(field("value"), 10); + * // Join the elements of the 'tags' field with a comma and space. + * join("tags", ", ") * ``` * - * @param expression An expression evaluating to a numeric value, which the logarithm will be computed for. - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @param arrayFieldName The name of the field containing the array. + * @param delimiter The string to use as a delimiter. + * @return A new Expression representing the join operation. */ - export function log(expression: Expr, base: number): FunctionExpr; + export function join(arrayFieldName: string, delimiter: string): Expression; + /** * @beta - * Creates an expression that computes the logarithm of an expression to a given base. + * Creates an expression that joins the elements of an array into a string. * * ```typescript - * // Compute the logarithm of the 'value' field with the base in the 'base' field. - * log(field("value"), field("base")); + * // Join an array of string using the delimiter from the 'separator' field. + * join(array(['foo', 'bar']), field("separator")) * ``` * - * @param expression An expression evaluating to a numeric value, which the logarithm will be computed for. - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @param arrayExpression An expression that evaluates to an array. + * @param delimiterExpression The expression that evaluates to the delimiter string. + * @return A new Expression representing the join operation. */ - export function log(expression: Expr, base: Expr): FunctionExpr; + export function join( + arrayExpression: Expression, + delimiterExpression: Expression + ): Expression; + /** * @beta - * Creates an expression that computes the logarithm of a field to a given base. + * Creates an expression that joins the elements of an array into a string. * * ```typescript - * // Compute the logarithm of the 'value' field with base 10. - * log("value", 10); + * // Join the elements of the 'tags' field with a comma and space. + * join(field("tags"), ", ") * ``` * - * @param fieldName The name of the field to compute the logarithm of. - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @param arrayExpression An expression that evaluates to an array. + * @param delimiter The string to use as a delimiter. + * @return A new Expression representing the join operation. */ - export function log(fieldName: string, base: number): FunctionExpr; + export function join( + arrayExpression: Expression, + delimiter: string + ): Expression; + /** * @beta - * Creates an expression that computes the logarithm of a field to a given base. + * Creates an expression that computes the base-10 logarithm of a numeric value. * * ```typescript - * // Compute the logarithm of the 'value' field with the base in the 'base' field. - * log("value", field("base")); + * // Compute the base-10 logarithm of the 'value' field. + * log10("value"); * ``` * - * @param fieldName The name of the field to compute the logarithm of. - * @param base The base of the logarithm. - * @return A new {@code Expr} representing the logarithm of the numeric value. + * @param fieldName The name of the field to compute the base-10 logarithm of. + * @return A new `Expr` representing the base-10 logarithm of the numeric value. */ - export function log(fieldName: string, base: Expr): FunctionExpr; + export function log10(fieldName: string): FunctionExpression; + + /** + * @beta + * Creates an expression that computes the base-10 logarithm of a numeric value. + * + * ```typescript + * // Compute the base-10 logarithm of the 'value' field. + * log10(field("value")); + * ``` + * + * @param expression An expression evaluating to a numeric value, which the base-10 logarithm will be computed for. + * @return A new `Expr` representing the base-10 logarithm of the numeric value. + */ + export function log10(expression: Expression): FunctionExpression; + + /** + * @beta + * Creates an expression that computes the sum of the elements in an array. + * + * ```typescript + * // Compute the sum of the elements in the 'scores' field. + * arraySum("scores"); + * ``` + * + * @param fieldName The name of the field to compute the sum of. + * @return A new `Expr` representing the sum of the elements in the array. + */ + export function arraySum(fieldName: string): FunctionExpression; + + /** + * @beta + * Creates an expression that computes the sum of the elements in an array. + * + * ```typescript + * // Compute the sum of the elements in the 'scores' field. + * arraySum(field("scores")); + * ``` + * + * @param expression An expression evaluating to a numeric array, which the sum will be computed for. + * @return A new `Expr` representing the sum of the elements in the array. + */ + export function arraySum(expression: Expression): FunctionExpression; + /** + * @beta + * Creates an expression that computes the natural logarithm of a numeric value. + * + * ```typescript + * // Compute the natural logarithm of the 'value' field. + * ln(field("value")); + * ``` + * + * @param expression An expression evaluating to a numeric value, which the natural logarithm will be computed for. + * @return A new {@code Expression} representing the natural logarithm of the numeric value. + */ + export function ln(expression: Expression): FunctionExpression; + /** + * @beta + * Creates an expression that computes the natural logarithm of a numeric value. + * + * ```typescript + * // Compute the natural logarithm of the 'value' field. + * ln("value"); + * ``` + * + * @param fieldName The name of the field to compute the natural logarithm of. + * @return A new {@code Expression} representing the natural logarithm of the numeric value. + */ + export function ln(fieldName: string): FunctionExpression; /** * @beta * Creates an expression that rounds a numeric value to the nearest whole number. @@ -8360,9 +8794,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expression An expression evaluating to a numeric value, which will be rounded. - * @return A new `Expr` representing the rounded value. + * @return A new `Expression` representing the rounded value. */ - export function round(expression: Expr): FunctionExpr; + export function round(expression: Expression): FunctionExpression; /** * @beta * Creates an expression that rounds a numeric value to the nearest whole number. @@ -8373,9 +8807,44 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field to round. + * @return A new `Expression` representing the rounded value. + */ + export function round(fieldName: string): FunctionExpression; + /** + * @beta + * Creates an expression that rounds a numeric value to the specified number of decimal places. + * + * ```typescript + * // Round the value of the 'price' field to two decimal places. + * round("price", 2); + * ``` + * + * @param fieldName The name of the field to round. + * @param decimalPlaces A constant or expression specifying the rounding precision in decimal places. * @return A new `Expr` representing the rounded value. */ - export function round(fieldName: string): FunctionExpr; + export function round( + fieldName: string, + decimalPlaces: number | Expression + ): FunctionExpression; + + /** + * @beta + * Creates an expression that rounds a numeric value to the specified number of decimal places. + * + * ```typescript + * // Round the value of the 'price' field to two decimal places. + * round(field("price"), constant(2)); + * ``` + * + * @param expression An expression evaluating to a numeric value, which will be rounded. + * @param decimalPlaces A constant or expression specifying the rounding precision in decimal places. + * @return A new `Expr` representing the rounded value. + */ + export function round( + expression: Expression, + decimalPlaces: number | Expression + ): FunctionExpression; /** * @beta * Creates an expression that computes the square root of a numeric value. @@ -8386,9 +8855,9 @@ declare namespace FirebaseFirestore { * ``` * * @param expression An expression evaluating to a numeric value, which the square root will be computed for. - * @return A new {@code Expr} representing the square root of the numeric value. + * @return A new {@code Expression} representing the square root of the numeric value. */ - export function sqrt(expression: Expr): FunctionExpr; + export function sqrt(expression: Expression): FunctionExpression; /** * @beta * Creates an expression that computes the square root of a numeric value. @@ -8399,9 +8868,10 @@ declare namespace FirebaseFirestore { * ``` * * @param fieldName The name of the field to compute the square root of. - * @return A new {@code Expr} representing the square root of the numeric value. + * @return A new {@code Expression} representing the square root of the numeric value. */ - export function sqrt(fieldName: string): FunctionExpr; + export function sqrt(fieldName: string): FunctionExpression; + // TODO(new-expression): Add new top-level expression function declarations above this line /** * @beta * Creates an {@link Ordering} that sorts documents in ascending order based on an expression. @@ -8415,7 +8885,7 @@ declare namespace FirebaseFirestore { * @param expr The expression to create an ascending ordering for. * @return A new `Ordering` for ascending sorting. */ - export function ascending(expr: Expr): Ordering; + export function ascending(expr: Expression): Ordering; /** * @beta * Creates an {@link Ordering} that sorts documents in ascending order based on a field. @@ -8443,7 +8913,7 @@ declare namespace FirebaseFirestore { * @param expr The expression to create a descending ordering for. * @return A new `Ordering` for descending sorting. */ - export function descending(expr: Expr): Ordering; + export function descending(expr: Expression): Ordering; /** * @beta * Creates an {@link Ordering} that sorts documents in descending order based on a field. @@ -8465,7 +8935,7 @@ declare namespace FirebaseFirestore { * You create `Ordering` instances using the `ascending` and `descending` helper functions. */ export class Ordering { - readonly expr: Expr; + readonly expr: Expression; readonly direction: 'ascending' | 'descending'; } @@ -8601,14 +9071,14 @@ declare namespace FirebaseFirestore { * // Example 2: Filter documents where 'genre' is "Science Fiction" and 'published' is after 1950 * const results2 = await db.pipeline() * .collection("books") - * .where(and(Field.of("genre").eq("Science Fiction"), Field.of("published").gt(1950))) + * .where(and(Field.of("genre").equal("Science Fiction"), Field.of("published").greaterThan(1950))) * .execute(); * * // Example 3: Calculate the average rating of books published after 1980 * const results3 = await db.pipeline() * .collection("books") - * .where(Field.of("published").gt(1980)) - * .aggregate(avg(Field.of("rating")).as("averageRating")) + * .where(Field.of("published").greaterThan(1980)) + * .aggregate(average(Field.of("rating")).as("averageRating")) * .execute(); * ``` */ @@ -8624,8 +9094,8 @@ declare namespace FirebaseFirestore { * The added fields are defined using {@link Selectable}s, which can be: * * - {@link Field}: References an existing document field. - * - {@link Expr}: Either a literal value (see {@link Constant}) or a computed value - * (see {@FunctionExpr}) with an assigned alias using {@link Expr#as}. + * - {@link Expression}: Either a literal value (see {@link Constant}) or a computed value + * (see {@FunctionExpression}) with an assigned alias using {@link Expression#as}. * * Example: * @@ -8653,8 +9123,8 @@ declare namespace FirebaseFirestore { * The added fields are defined using {@link Selectable}s, which can be: * * - {@link Field}: References an existing document field. - * - {@link Expr}: Either a literal value (see {@link Constant}) or a computed value - * (see {@FunctionExpr}) with an assigned alias using {@link Expr#as}. + * - {@link Expression}: Either a literal value (see {@link Constant}) or a computed value + * (see {@FunctionExpression}) with an assigned alias using {@link Expression#as}. * * Example: * @@ -8716,7 +9186,7 @@ declare namespace FirebaseFirestore { * ``` * * @param options - An object containing the configuration for this stage. - * @param options.fields - An array of field names (strings) or {@link Expr} objects + * @param options.fields - An array of field names (strings) or {@link Expression} objects * representing the fields to be removed from the output. * @returns A new {@link Pipeline} object with this stage appended to the stage list. */ @@ -8731,8 +9201,8 @@ declare namespace FirebaseFirestore { *
        *
      • {@code string}: The name of an existing field.
        • *
      • {@link Field}: A reference to an existing field.
        • - *
      • {@link Expr}: An expression (e.g., a {@link FunctionExpr}) that represents the result of an expression., - * The Expr must be aliased using {@link Expr#as}.
        • + *
      • {@link Expression}: An expression (e.g., a {@link FunctionExpression}) that represents the result of an expression., + * The Expression must be aliased using {@link Expression#as}.
        • *
      * *

      Example: @@ -8766,8 +9236,8 @@ declare namespace FirebaseFirestore { *

        *
      • {@code string}: The name of an existing field.
        • *
      • {@link Field}: A reference to an existing field.
        • - *
      • {@link Expr}: An expression (e.g., a {@link FunctionExpr}) that represents the result of an expression., - * The Expr must be aliased using {@link Expr#as}.
        • + *
      • {@link Expression}: An expression (e.g., a {@link FunctionExpression}) that represents the result of an expression., + * The Expression must be aliased using {@link Expression#as}.
        • *
      * * If no selections are provided within the `options` (i.e., the `fields` array is empty), @@ -8795,15 +9265,15 @@ declare namespace FirebaseFirestore { /** * @beta * Filters the documents from previous stages to only include those matching the specified {@link - * BooleanExpr}. + * BooleanExpression}. * *

      This stage allows you to apply conditions to the data, similar to a "WHERE" clause in SQL. * You can filter documents based on their field values, using implementations of {@link - * BooleanExpr}, typically including but not limited to: + * BooleanExpression}, typically including but not limited to: * *

        - *
      • field comparators: {@link Function#eq}, {@link Function#lt} (less than), {@link - * Function#gt} (greater than), etc.
        • + *
      • field comparators: {@link Function#equal}, {@link Function#lessThan} (less than), {@link + * Function#greaterThan} (greater than), etc.
        • *
      • logical operators: {@link Function#and}, {@link Function#or}, {@link Function#not}, etc.
        • *
      • advanced functions: {@link Function#regexMatch}, {@link * Function#arrayContains}, etc.
        • @@ -8815,28 +9285,28 @@ declare namespace FirebaseFirestore { * firestore.pipeline().collection("books") * .where( * and( - * gt(field("rating"), 4.0), // Filter for ratings greater than 4.0 - * field("genre").eq("Science Fiction") // Equivalent to gt("genre", "Science Fiction") + * greaterThan(field("rating"), 4.0), // Filter for ratings greater than 4.0 + * field("genre").equal("Science Fiction") // Equivalent to greaterThan("genre", "Science Fiction") * ) * ); * ``` * - * @param condition The {@link BooleanExpr} to apply. + * @param condition The {@link BooleanExpression} to apply. * @return A new Pipeline object with this stage appended to the stage list. */ - where(condition: BooleanExpr): Pipeline; + where(condition: BooleanExpression): Pipeline; /** * @beta * Filters the documents from previous stages to only include those matching the specified {@link - * BooleanExpr}. + * BooleanExpression}. * *

        This stage allows you to apply conditions to the data, similar to a "WHERE" clause in SQL. * You can filter documents based on their field values, using implementations of {@link - * BooleanExpr}, typically including but not limited to: + * BooleanExpression}, typically including but not limited to: * *

          - *
        • field comparators: {@link Function#eq}, {@link Function#lt} (less than), {@link - * Function#gt} (greater than), etc.
          • + *
        • field comparators: {@link Function#equal}, {@link Function#lessThan} (less than), {@link + * Function#greaterThan} (greater than), etc.
          • *
        • logical operators: {@link Function#and}, {@link Function#or}, {@link Function#not}, etc.
          • *
        • advanced functions: {@link Function#regexMatch}, {@link * Function#arrayContains}, etc.
          • @@ -8848,13 +9318,13 @@ declare namespace FirebaseFirestore { * firestore.pipeline().collection("books") * .where({ * filter: and( - * gt(field("rating"), 4.0), // Filter for ratings greater than 4.0 - * field("genre").eq("Science Fiction") // Equivalent to gt("genre", "Science Fiction") + * greaterThan(field("rating"), 4.0), // Filter for ratings greater than 4.0 + * field("genre").equal("Science Fiction") // Equivalent to greaterThan("genre", "Science Fiction") * ) * }); * ``` * - * @param options An object that specifies the filtering criteria. It is expected to contain a `filter` property of type {@link BooleanExpr}. + * @param options An object that specifies the filtering criteria. It is expected to contain a `filter` property of type {@link BooleanExpression}. * @return A new Pipeline object with this stage appended to the stage list. */ where(options: WhereStageOptions): Pipeline; @@ -8963,14 +9433,14 @@ declare namespace FirebaseFirestore { * Returns a set of distinct values from the inputs to this stage. * * This stage runs through the results from previous stages to include only results with - * unique combinations of {@link Expr} values ({@link Field}, {@link Function}, etc). + * unique combinations of {@link Expression} values ({@link Field}, {@link Function}, etc). * * The parameters to this stage are defined using {@link Selectable} expressions or strings: * * - {@code string}: Name of an existing field * - {@link Field}: References an existing document field. - * - {@link AliasedExpr}: Represents the result of a function with an assigned alias name - * using {@link Expr#as}. + * - {@link AliasedExpression}: Represents the result of a function with an assigned alias name + * using {@link Expression#as}. * * Example: * @@ -8996,14 +9466,14 @@ declare namespace FirebaseFirestore { * Returns a set of distinct values from the inputs to this stage. * * This stage runs through the results from previous stages to include only results with - * unique combinations of {@link Expr} values ({@link Field}, {@link Function}, etc). + * unique combinations of {@link Expression} values ({@link Field}, {@link Function}, etc). * * The parameters to this stage are defined using {@link Selectable} expressions or strings: * * - {@code string}: Name of an existing field * - {@link Field}: References an existing document field. - * - {@link AliasedExpr}: Represents the result of a function with an assigned alias name - * using {@link Expr#as}. + * - {@link AliasedExpression}: Represents the result of a function with an assigned alias name + * using {@link Expression#as}. * * Example: * @@ -9024,7 +9494,7 @@ declare namespace FirebaseFirestore { * *

          This stage allows you to calculate aggregate values over a set of documents. You define the * aggregations to perform using {@link AliasedAggregate} expressions which are typically results of - * calling {@link Expr#as} on {@link AggregateFunction} instances. + * calling {@link Expression#as} on {@link AggregateFunction} instances. * *

          Example: * @@ -9032,7 +9502,7 @@ declare namespace FirebaseFirestore { * // Calculate the average rating and the total number of books * firestore.pipeline().collection("books") * .aggregate( - * field("rating").avg().as("averageRating"), + * field("rating").average().as("averageRating"), * countAll().as("totalBooks") * ); * ``` @@ -9061,7 +9531,7 @@ declare namespace FirebaseFirestore { * specifying groups is the same as putting the entire inputs into one group. *

        • **Accumulators:** One or more accumulation operations to perform within each group. These * are defined using {@link AliasedAggregate} expressions, which are typically created by - * calling {@link Expr#as} on {@link AggregateFunction} instances. Each aggregation + * calling {@link Expression#as} on {@link AggregateFunction} instances. Each aggregation * calculates a value (e.g., sum, average, count) based on the documents within its group.
          • *
        * @@ -9071,7 +9541,7 @@ declare namespace FirebaseFirestore { * // Calculate the average rating for each genre. * firestore.pipeline().collection("books") * .aggregate({ - * accumulators: [avg(field("rating")).as("avg_rating")] + * accumulators: [average(field("rating")).as("avg_rating")] * groups: ["genre"] * }); * ``` @@ -9148,7 +9618,7 @@ declare namespace FirebaseFirestore { * Fully replaces all fields in a document with the fields from a map expression. * *

        This stage allows you to transform the current document into a new one - * by providing an {@link Expr} that evaluates to a map. Each key-value pair + * by providing an {@link Expression} that evaluates to a map. Each key-value pair * in the resulting map will become a field-value pair in the document. * *

        Example: @@ -9176,10 +9646,10 @@ declare namespace FirebaseFirestore { * // } * ``` * - * @param expr An {@link Expr} that evaluates to a map. The key-value pairs of this map will replace the document's fields. + * @param expr An {@link Expression} that evaluates to a map. The key-value pairs of this map will replace the document's fields. * @return A new {@code Pipeline} object with this stage appended to the stage list. */ - replaceWith(expr: Expr): Pipeline; + replaceWith(expr: Expression): Pipeline; /** * @beta @@ -9442,7 +9912,7 @@ declare namespace FirebaseFirestore { * ```typescript * // Assume we don't have a built-in "where" stage * firestore.pipeline().collection("books") - * .rawStage("where", [Field.of("published").lt(1900)]) // Custom "where" stage + * .rawStage("where", [Field.of("published").lessThan(1900)]) // Custom "where" stage * .select("title", "author"); * ``` * @@ -9476,7 +9946,7 @@ declare namespace FirebaseFirestore { * * ```typescript * const futureResults = await firestore.pipeline().collection("books") - * .where(gt(Field.of("rating"), 4.5)) + * .where(greaterThan(Field.of("rating"), 4.5)) * .select("title", "author", "rating") * .execute(); * ``` @@ -9497,7 +9967,7 @@ declare namespace FirebaseFirestore { * @example * ```typescript * firestore.pipeline().collection("books") - * .where(gt(Field.of("rating"), 4.5)) + * .where(greaterThan(Field.of("rating"), 4.5)) * .select("title", "author", "rating") * .stream() * .on('data', (pipelineResult) => { @@ -9537,7 +10007,7 @@ declare namespace FirebaseFirestore { * @beta * Specifies the output format of the query planner information. */ - outputFormat?: 'text' | 'json'; + outputFormat?: 'text'; }; /** * @beta @@ -9719,9 +10189,9 @@ declare namespace FirebaseFirestore { export type WhereStageOptions = StageOptions & { /** * @beta - * The {@link BooleanExpr} to apply as a filter for each input document to this stage. + * The {@link BooleanExpression} to apply as a filter for each input document to this stage. */ - condition: BooleanExpr; + condition: BooleanExpression; }; /** * @beta @@ -9822,10 +10292,10 @@ declare namespace FirebaseFirestore { export type ReplaceWithStageOptions = StageOptions & { /** * @beta - * The name of a field that contains a map or an {@link Expr} that + * The name of a field that contains a map or an {@link Expression} that * evaluates to a map. */ - map: Expr | string; + map: Expression | string; }; /** * @beta @@ -9953,7 +10423,7 @@ declare namespace FirebaseFirestore { * const snapshot = await firestore * .pipeline() * .collection('myCollection') - * .where(field('value').gt(10)) + * .where(field('value').greaterThan(10)) * .execute(); * * snapshot.results.forEach(doc => { @@ -9997,7 +10467,6 @@ declare namespace FirebaseFirestore { * value. */ export class PipelineResult { - readonly executionTime: Timestamp; readonly createTime: Timestamp | undefined; readonly updateTime: Timestamp | undefined; /**