feat(firestore): add isType expression (#9484)

Author: dlarocque

.changeset/tiny-jokes-compete.md

@@ -0,0 +1,6 @@
+---
+'firebase': minor
+'@firebase/firestore': minor
+---
+
+feat(firestore): Support added for the `isType` Pipeline expression.

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

@@ -502,6 +502,8 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     isError(): BooleanExpression;
     /* Excluded from this release type: _readUserData */
+    isType(type: Type): BooleanExpression;
+    /* Excluded from this release type: _readUserData */
     join(delimiterExpression: Expression): Expression;
     /* Excluded from this release type: _readUserData */
     join(delimiter: string): Expression;
@@ -771,6 +773,12 @@ export function isAbsent(field: string): BooleanExpression;
 // @beta
 export function isError(value: Expression): BooleanExpression;
 
+// @beta
+export function isType(fieldName: string, type: Type): BooleanExpression;
+
+// @beta
+export function isType(expression: Expression, type: Type): BooleanExpression;
+
 // @beta
 export function join(arrayFieldName: string, delimiter: string): Expression;
 
@@ -1376,6 +1384,9 @@ export function trunc(fieldName: string, decimalPlaces: number | Expression): Fu
 // @beta
 export function trunc(expression: Expression, decimalPlaces: number | Expression): FunctionExpression;
 
+// @beta
+export type Type = 'null' | 'array' | 'boolean' | 'bytes' | 'timestamp' | 'geo_point' | 'number' | 'int32' | 'int64' | 'float64' | 'decimal128' | 'map' | 'reference' | 'string' | 'vector' | 'max_key' | 'min_key' | 'object_id' | 'regex' | 'request_timestamp';
+
 // @beta
 export function type(fieldName: string): FunctionExpression;
 

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

@@ -505,6 +505,8 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     isError(): BooleanExpression;
     /* Excluded from this release type: _readUserData */
+    isType(type: Type): BooleanExpression;
+    /* Excluded from this release type: _readUserData */
     join(delimiterExpression: Expression): Expression;
     /* Excluded from this release type: _readUserData */
     join(delimiter: string): Expression;
@@ -774,6 +776,12 @@ export function isAbsent(field: string): BooleanExpression;
 // @beta
 export function isError(value: Expression): BooleanExpression;
 
+// @beta
+export function isType(fieldName: string, type: Type): BooleanExpression;
+
+// @beta
+export function isType(expression: Expression, type: Type): BooleanExpression;
+
 // @beta
 export function join(arrayFieldName: string, delimiter: string): Expression;
 
@@ -1413,6 +1421,9 @@ export function trunc(fieldName: string, decimalPlaces: number | Expression): Fu
 // @beta
 export function trunc(expression: Expression, decimalPlaces: number | Expression): FunctionExpression;
 
+// @beta
+export type Type = 'null' | 'array' | 'boolean' | 'bytes' | 'timestamp' | 'geo_point' | 'number' | 'int32' | 'int64' | 'float64' | 'decimal128' | 'map' | 'reference' | 'string' | 'vector' | 'max_key' | 'min_key' | 'object_id' | 'regex' | 'request_timestamp';
+
 // @beta
 export function type(fieldName: string): FunctionExpression;
 

docs-devsite/firestore_lite_pipelines.expression.md

@@ -101,6 +101,7 @@ field("optional_field").ifAbsent(field('default_field'))
 |  [ifError(catchValue)](./firestore_lite_pipelines.expression.md#expressioniferror) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the <code>catch</code> argument if there is an error, else return the result of this expression. |
 |  [isAbsent()](./firestore_lite_pipelines.expression.md#expressionisabsent) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns <code>true</code> if the result of this expression is absent. Otherwise, returns <code>false</code> even if the value is <code>null</code>. |
 |  [isError()](./firestore_lite_pipelines.expression.md#expressioniserror) |  | <b><i>(Public Preview)</i></b> Creates an expression that checks if a given expression produces an error. |
+|  [isType(type)](./firestore_lite_pipelines.expression.md#expressionistype) |  | <b><i>(Public Preview)</i></b> Creates an expression that checks if the result of this expression is of the given type. |
 |  [join(delimiterExpression)](./firestore_lite_pipelines.expression.md#expressionjoin) |  | <b><i>(Public Preview)</i></b> Creates an expression that joins the elements of an array into a string. |
 |  [join(delimiter)](./firestore_lite_pipelines.expression.md#expressionjoin) |  | <b><i>(Public Preview)</i></b> Creates an expression that joins the elements of an array field into a string. |
 |  [last()](./firestore_lite_pipelines.expression.md#expressionlast) |  | <b><i>(Public Preview)</i></b> Creates an aggregation that finds the last value of an expression across multiple stage inputs. |
@@ -1977,6 +1978,42 @@ field("title").arrayContains(1).isError();
 
 ```
 
+## Expression.isType()
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Creates an expression that checks if the result of this expression is of the given type.
+
+Null or undefined fields evaluate to skip/error. Use `ifAbsent()` / `isAbsent()` to evaluate missing data.
+
+<b>Signature:</b>
+
+```typescript
+isType(type: Type): BooleanExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  type | [Type](./firestore_lite_pipelines.md#type) | The type to check for. |
+
+<b>Returns:</b>
+
+[BooleanExpression](./firestore_lite_pipelines.booleanexpression.md#booleanexpression_class)
+
+A new `BooleanExpression` that evaluates to true if the expression's result is of the given type, false otherwise.
+
+### Example
+
+
+```typescript
+// Check if the 'price' field is specifically an integer (not just 'number')
+field('price').isType('int64');
+
+```
+
 ## Expression.join()
 
 > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
@@ -4463,6 +4500,8 @@ field("rating").trunc(constant(2));
 
 Creates an expression that returns the data type of this expression's result, as a string.
 
+This is evaluated on the backend. This means: 1. Generic typed elements (like `array<string>`<!-- -->) evaluate strictly to the primitive `'array'`<!-- -->. 2. Any custom `FirestoreDataConverter` mappings are ignored. 3. For numeric values, the backend does not yield the JavaScript `"number"` type; it evaluates precisely as `"int64"` or `"float64"`<!-- -->. 4. For date or timestamp objects, the backend evaluates to `"timestamp"`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript

docs-devsite/firestore_lite_pipelines.md

@@ -87,6 +87,7 @@ https://github.com/firebase/firebase-js-sdk
 |  [first(expression)](./firestore_lite_pipelines.md#first_1138a27) | <b><i>(Public Preview)</i></b> Creates an aggregation that finds the first value of an expression across multiple stage inputs. |
 |  [greaterThan(expression, value)](./firestore_lite_pipelines.md#greaterthan_01df3cf) | <b><i>(Public Preview)</i></b> Creates an expression that checks if an expression is greater than a constant value. |
 |  [greaterThanOrEqual(expression, value)](./firestore_lite_pipelines.md#greaterthanorequal_01df3cf) | <b><i>(Public Preview)</i></b> Creates an expression that checks if an expression is greater than or equal to a constant value. |
+|  [isType(expression, type)](./firestore_lite_pipelines.md#istype_27398ce) | <b><i>(Public Preview)</i></b> Creates an expression that checks if the result of an expression is of the given type. |
 |  [last(expression)](./firestore_lite_pipelines.md#last_1138a27) | <b><i>(Public Preview)</i></b> Creates an aggregation that finds the last value of an expression across multiple stage inputs. |
 |  [length\_2(expression)](./firestore_lite_pipelines.md#length_2_1138a27) | <b><i>(Public Preview)</i></b> Creates an expression that calculates the length of a string, array, map, vector, or bytes. |
 |  [lessThan(expression, value)](./firestore_lite_pipelines.md#lessthan_01df3cf) | <b><i>(Public Preview)</i></b> Creates an expression that checks if an expression is less than a constant value. |
@@ -165,6 +166,7 @@ https://github.com/firebase/firebase-js-sdk
 |  [greaterThan(fieldName, value)](./firestore_lite_pipelines.md#greaterthan_65e2f32) | <b><i>(Public Preview)</i></b> Creates an expression that checks if a field's value is greater than a constant value. |
 |  [greaterThanOrEqual(fieldName, value)](./firestore_lite_pipelines.md#greaterthanorequal_2e16acb) | <b><i>(Public Preview)</i></b> Creates an expression that checks if a field's value is greater than or equal to an expression. |
 |  [greaterThanOrEqual(fieldName, value)](./firestore_lite_pipelines.md#greaterthanorequal_65e2f32) | <b><i>(Public Preview)</i></b> Creates an expression that checks if a field's value is greater than or equal to a constant value. |
+|  [isType(fieldName, type)](./firestore_lite_pipelines.md#istype_5da287e) | <b><i>(Public Preview)</i></b> Creates an expression that checks if the value in the specified field is of the given type. |
 |  [last(fieldName)](./firestore_lite_pipelines.md#last_e5b0480) | <b><i>(Public Preview)</i></b> Creates an aggregation that finds the last value of a field across multiple stage inputs. |
 |  [length\_2(fieldName)](./firestore_lite_pipelines.md#length_2_e5b0480) | <b><i>(Public Preview)</i></b> Creates an expression that calculates the length of a string, array, map, vector, or bytes. |
 |  [lessThan(fieldName, expression)](./firestore_lite_pipelines.md#lessthan_1e91657) | <b><i>(Public Preview)</i></b> Creates an expression that checks if a field's value is less than an expression. |
@@ -405,6 +407,7 @@ https://github.com/firebase/firebase-js-sdk
 |  [SetOptions](./firestore_lite_pipelines.md#setoptions) | An options object that configures the behavior of [setDoc()](./firestore_lite.md#setdoc_ee215ad)<!-- -->,  and  calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a <code>SetOptions</code> with <code>merge: true</code>. |
 |  [SortStageOptions](./firestore_lite_pipelines.md#sortstageoptions) | <b><i>(Public Preview)</i></b> Options defining how a SortStage is evaluated. See [Pipeline.sort()](./firestore_pipelines.pipeline.md#pipelinesort)<!-- -->. |
 |  [TimeGranularity](./firestore_lite_pipelines.md#timegranularity) | <b><i>(Public Preview)</i></b> Specify time granularity for expressions. |
+|  [Type](./firestore_lite_pipelines.md#type) | <b><i>(Public Preview)</i></b> An enumeration of the different types generated by the Firestore backend.<ul> <li>Numerics evaluate directly to backend representation (<code>int64</code> or <code>float64</code>), not JS <code>number</code>.</li> <li>JavaScript <code>Date</code> and firestore <code>Timestamp</code> objects strictly evaluate to <code>'timestamp'</code>.</li> <li>Advanced configurations parsing backend types (such as <code>decimal128</code>, <code>max_key</code> or <code>min_key</code> from BSON) are also incorporated in this union string type. Note that <code>decimal128</code> is a backend-only numeric type that the JavaScript SDK cannot create natively, but can be evaluated in pipelines.</li> </ul> |
 |  [UnionStageOptions](./firestore_lite_pipelines.md#unionstageoptions) | <b><i>(Public Preview)</i></b> Options defining how a UnionStage is evaluated. See [Pipeline.union()](./firestore_pipelines.pipeline.md#pipelineunion)<!-- -->. |
 |  [UnnestStageOptions](./firestore_lite_pipelines.md#unneststageoptions) | <b><i>(Public Preview)</i></b> Represents the specific options available for configuring an <code>UnnestStage</code> within a pipeline. |
 |  [WhereStageOptions](./firestore_lite_pipelines.md#wherestageoptions) | <b><i>(Public Preview)</i></b> Options defining how a WhereStage is evaluated. See [Pipeline.where()](./firestore_pipelines.pipeline.md#pipelinewhere)<!-- -->. |
@@ -2399,6 +2402,43 @@ greaterThanOrEqual(field("quantity"), 10);
 
 ```
 
+### isType(expression, type) {:#istype_27398ce}
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Creates an expression that checks if the result of an expression is of the given type.
+
+Null or undefined fields evaluate to skip/error. Use `ifAbsent()` / `isAbsent()` to evaluate missing data.
+
+<b>Signature:</b>
+
+```typescript
+export declare function isType(expression: Expression, type: Type): BooleanExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  expression | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The expression to check. |
+|  type | [Type](./firestore_lite_pipelines.md#type) | The type to check for. |
+
+<b>Returns:</b>
+
+[BooleanExpression](./firestore_lite_pipelines.booleanexpression.md#booleanexpression_class)
+
+A new `BooleanExpression` that evaluates to true if the expression's result is of the given type, false otherwise.
+
+### Example
+
+
+```typescript
+// Check if the result of a calculation is a number
+isType(add('count', 1), 'number')
+
+```
+
 ### last(expression) {:#last_1138a27}
 
 > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
@@ -5014,6 +5054,43 @@ greaterThanOrEqual("score", 80);
 
 ```
 
+### isType(fieldName, type) {:#istype_5da287e}
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Creates an expression that checks if the value in the specified field is of the given type.
+
+Null or undefined fields evaluate to skip/error. Use `ifAbsent()` / `isAbsent()` to evaluate missing data.
+
+<b>Signature:</b>
+
+```typescript
+export declare function isType(fieldName: string, type: Type): BooleanExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  fieldName | string | The name of the field to check. |
+|  type | [Type](./firestore_lite_pipelines.md#type) | The type to check for. |
+
+<b>Returns:</b>
+
+[BooleanExpression](./firestore_lite_pipelines.booleanexpression.md#booleanexpression_class)
+
+A new `BooleanExpression` that evaluates to true if the field's value is of the given type, false otherwise.
+
+### Example
+
+
+```typescript
+// Check if the 'price' field is a floating point number (evaluating to true inside pipeline conditionals)
+isType('price', 'float64');
+
+```
+
 ### last(fieldName) {:#last_e5b0480}
 
 > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
@@ -7242,6 +7319,8 @@ trunc("rating", 2);
 
 Creates an expression that returns the data type of the data in the specified field.
 
+String inputs passed iteratively to this global function act as `field()` path lookups. If you wish to pass a string literal value, it must be wrapped: `type(constant("my_string"))`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript
@@ -10728,6 +10807,21 @@ Specify time granularity for expressions.
 export declare type TimeGranularity = 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'week(monday)' | 'week(tuesday)' | 'week(wednesday)' | 'week(thursday)' | 'week(friday)' | 'week(saturday)' | 'week(sunday)' | 'isoWeek' | 'month' | 'quarter' | 'year' | 'isoYear';
 ```
 
+## Type
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+An enumeration of the different types generated by the Firestore backend.
+
+<ul> <li>Numerics evaluate directly to backend representation (`int64` or `float64`<!-- -->), not JS `number`<!-- -->.</li> <li>JavaScript `Date` and firestore `Timestamp` objects strictly evaluate to `'timestamp'`<!-- -->.</li> <li>Advanced configurations parsing backend types (such as `decimal128`<!-- -->, `max_key` or `min_key` from BSON) are also incorporated in this union string type. Note that `decimal128` is a backend-only numeric type that the JavaScript SDK cannot create natively, but can be evaluated in pipelines.</li> </ul>
+
+<b>Signature:</b>
+
+```typescript
+export declare type Type = 'null' | 'array' | 'boolean' | 'bytes' | 'timestamp' | 'geo_point' | 'number' | 'int32' | 'int64' | 'float64' | 'decimal128' | 'map' | 'reference' | 'string' | 'vector' | 'max_key' | 'min_key' | 'object_id' | 'regex' | 'request_timestamp';
+```
+
 ## UnionStageOptions
 
 > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.

docs-devsite/firestore_pipelines.expression.md

@@ -101,6 +101,7 @@ field("optional_field").ifAbsent(field('default_field'))
 |  [ifError(catchValue)](./firestore_pipelines.expression.md#expressioniferror) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the <code>catch</code> argument if there is an error, else return the result of this expression. |
 |  [isAbsent()](./firestore_pipelines.expression.md#expressionisabsent) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns <code>true</code> if the result of this expression is absent. Otherwise, returns <code>false</code> even if the value is <code>null</code>. |
 |  [isError()](./firestore_pipelines.expression.md#expressioniserror) |  | <b><i>(Public Preview)</i></b> Creates an expression that checks if a given expression produces an error. |
+|  [isType(type)](./firestore_pipelines.expression.md#expressionistype) |  | <b><i>(Public Preview)</i></b> Creates an expression that checks if the result of this expression is of the given type. |
 |  [join(delimiterExpression)](./firestore_pipelines.expression.md#expressionjoin) |  | <b><i>(Public Preview)</i></b> Creates an expression that joins the elements of an array into a string. |
 |  [join(delimiter)](./firestore_pipelines.expression.md#expressionjoin) |  | <b><i>(Public Preview)</i></b> Creates an expression that joins the elements of an array field into a string. |
 |  [last()](./firestore_pipelines.expression.md#expressionlast) |  | <b><i>(Public Preview)</i></b> Creates an aggregation that finds the last value of an expression across multiple stage inputs. |
@@ -1977,6 +1978,42 @@ field("title").arrayContains(1).isError();
 
 ```
 
+## Expression.isType()
+
+> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
+> 
+
+Creates an expression that checks if the result of this expression is of the given type.
+
+Null or undefined fields evaluate to skip/error. Use `ifAbsent()` / `isAbsent()` to evaluate missing data.
+
+<b>Signature:</b>
+
+```typescript
+isType(type: Type): BooleanExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  type | [Type](./firestore_pipelines.md#type) | The type to check for. |
+
+<b>Returns:</b>
+
+[BooleanExpression](./firestore_pipelines.booleanexpression.md#booleanexpression_class)
+
+A new `BooleanExpression` that evaluates to true if the expression's result is of the given type, false otherwise.
+
+### Example
+
+
+```typescript
+// Check if the 'price' field is specifically an integer (not just 'number')
+field('price').isType('int64');
+
+```
+
 ## Expression.join()
 
 > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
@@ -4463,6 +4500,8 @@ field("rating").trunc(constant(2));
 
 Creates an expression that returns the data type of this expression's result, as a string.
 
+This is evaluated on the backend. This means: 1. Generic typed elements (like `array<string>`<!-- -->) evaluate strictly to the primitive `'array'`<!-- -->. 2. Any custom `FirestoreDataConverter` mappings are ignored. 3. For numeric values, the backend does not yield the JavaScript `"number"` type; it evaluates precisely as `"int64"` or `"float64"`<!-- -->. 4. For date or timestamp objects, the backend evaluates to `"timestamp"`<!-- -->.
+
 <b>Signature:</b>
 
 ```typescript