feat(firestore): Add array expressions

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

@@ -119,6 +119,12 @@ export function arrayContainsAny(array: Expression, values: Expression): Boolean
 // @public
 export function arrayContainsAny(fieldName: string, values: Expression): BooleanExpression;
 
+// @public
+export function arrayFilter(fieldName: string, alias: string, filter: BooleanExpression): FunctionExpression;
+
+// @public
+export function arrayFilter(arrayExpression: Expression, alias: string, filter: BooleanExpression): FunctionExpression;
+
 // @public
 export function arrayFirst(fieldName: string): FunctionExpression;
 
@@ -227,12 +233,30 @@ export function arrayMinimumN(arrayExpression: Expression, n: number): FunctionE
 // @public
 export function arrayMinimumN(arrayExpression: Expression, n: Expression): FunctionExpression;
 
+// @public
+export function arraySlice(fieldName: string, offset: number | Expression, length?: number | Expression): FunctionExpression;
+
+// @public
+export function arraySlice(arrayExpression: Expression, offset: number | Expression, length?: number | Expression): FunctionExpression;
+
 // @public
 export function arraySum(fieldName: string): FunctionExpression;
 
 // @public
 export function arraySum(expression: Expression): FunctionExpression;
 
+// @public
+export function arrayTransform(arrayExpression: Expression, elementAlias: string, transform: Expression): FunctionExpression;
+
+// @public
+export function arrayTransform(fieldName: string, elementAlias: string, transform: Expression): FunctionExpression;
+
+// @public
+export function arrayTransformWithIndex(arrayExpression: Expression, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
+
+// @public
+export function arrayTransformWithIndex(fieldName: string, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
+
 // @public
 export function ascending(expr: Expression): Ordering;
 
@@ -514,6 +538,8 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     arrayContainsAny(arrayExpression: Expression): BooleanExpression;
     /* Excluded from this release type: _readUserData */
+    arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     arrayFirst(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
     arrayFirstN(n: number): FunctionExpression;
@@ -558,8 +584,14 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     arrayReverse(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     arraySum(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
+    arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     as(name: string): AliasedExpression;
     /* Excluded from this release type: _readUserData */
     asBoolean(): BooleanExpression;

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

@@ -119,6 +119,12 @@ export function arrayContainsAny(array: Expression, values: Expression): Boolean
 // @public
 export function arrayContainsAny(fieldName: string, values: Expression): BooleanExpression;
 
+// @public
+export function arrayFilter(fieldName: string, alias: string, filter: BooleanExpression): FunctionExpression;
+
+// @public
+export function arrayFilter(arrayExpression: Expression, alias: string, filter: BooleanExpression): FunctionExpression;
+
 // @public
 export function arrayFirst(fieldName: string): FunctionExpression;
 
@@ -227,12 +233,30 @@ export function arrayMinimumN(arrayExpression: Expression, n: number): FunctionE
 // @public
 export function arrayMinimumN(arrayExpression: Expression, n: Expression): FunctionExpression;
 
+// @public
+export function arraySlice(fieldName: string, offset: number | Expression, length?: number | Expression): FunctionExpression;
+
+// @public
+export function arraySlice(arrayExpression: Expression, offset: number | Expression, length?: number | Expression): FunctionExpression;
+
 // @public
 export function arraySum(fieldName: string): FunctionExpression;
 
 // @public
 export function arraySum(expression: Expression): FunctionExpression;
 
+// @public
+export function arrayTransform(arrayExpression: Expression, elementAlias: string, transform: Expression): FunctionExpression;
+
+// @public
+export function arrayTransform(fieldName: string, elementAlias: string, transform: Expression): FunctionExpression;
+
+// @public
+export function arrayTransformWithIndex(arrayExpression: Expression, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
+
+// @public
+export function arrayTransformWithIndex(fieldName: string, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
+
 // @public
 export function ascending(expr: Expression): Ordering;
 
@@ -517,6 +541,8 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     arrayContainsAny(arrayExpression: Expression): BooleanExpression;
     /* Excluded from this release type: _readUserData */
+    arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     arrayFirst(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
     arrayFirstN(n: number): FunctionExpression;
@@ -561,8 +587,14 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     arrayReverse(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     arraySum(): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
+    arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     as(name: string): AliasedExpression;
     /* Excluded from this release type: _readUserData */
     asBoolean(): BooleanExpression;

docs-devsite/firestore_lite_pipelines.expression.md

@@ -45,6 +45,7 @@ export declare abstract class Expression
 |  [arrayContainsAll(arrayExpression)](./firestore_lite_pipelines.expression.md#expressionarraycontainsall) |  | Creates an expression that checks if an array contains all the specified elements. |
 |  [arrayContainsAny(values)](./firestore_lite_pipelines.expression.md#expressionarraycontainsany) |  | Creates an expression that checks if an array contains any of the specified elements. |
 |  [arrayContainsAny(arrayExpression)](./firestore_lite_pipelines.expression.md#expressionarraycontainsany) |  | Creates an expression that checks if an array contains any of the specified elements. |
+|  [arrayFilter(alias, filter)](./firestore_lite_pipelines.expression.md#expressionarrayfilter) |  | Filters the array using a provided alias and predicate expression. |
 |  [arrayFirst()](./firestore_lite_pipelines.expression.md#expressionarrayfirst) |  | Returns the first element of the array. |
 |  [arrayFirstN(n)](./firestore_lite_pipelines.expression.md#expressionarrayfirstn) |  | Returns the first <code>n</code> elements of the array. |
 |  [arrayFirstN(n)](./firestore_lite_pipelines.expression.md#expressionarrayfirstn) |  | Returns the first <code>n</code> elements of the array. |
@@ -67,7 +68,10 @@ export declare abstract class Expression
 |  [arrayMinimumN(n)](./firestore_lite_pipelines.expression.md#expressionarrayminimumn) |  | Returns the smallest <code>n</code> elements of the array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
 |  [arrayMinimumN(n)](./firestore_lite_pipelines.expression.md#expressionarrayminimumn) |  | Returns the smallest <code>n</code> elements of the array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. |
 |  [arrayReverse()](./firestore_lite_pipelines.expression.md#expressionarrayreverse) |  | Creates an expression that reverses an array. |
+|  [arraySlice(offset, length)](./firestore_lite_pipelines.expression.md#expressionarrayslice) |  | Returns a subset of the array. |
 |  [arraySum()](./firestore_lite_pipelines.expression.md#expressionarraysum) |  | Creates an expression that computes the sum of the elements in an array. |
+|  [arrayTransform(elementAlias, transform)](./firestore_lite_pipelines.expression.md#expressionarraytransform) |  | Creates an expression that applies a provided transformation to each element in an array. |
+|  [arrayTransformWithIndex(elementAlias, indexAlias, transform)](./firestore_lite_pipelines.expression.md#expressionarraytransformwithindex) |  | Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression. |
 |  [as(name)](./firestore_lite_pipelines.expression.md#expressionas) |  | Assigns an alias to this expression.<!-- -->Aliases are useful for renaming fields in the output of a stage or for giving meaningful names to calculated values. |
 |  [asBoolean()](./firestore_lite_pipelines.expression.md#expressionasboolean) |  | Wraps the expression in a \[BooleanExpression\]. |
 |  [ascending()](./firestore_lite_pipelines.expression.md#expressionascending) |  | Creates an [Ordering](./firestore_pipelines.ordering.md#ordering_class) that sorts documents in ascending order based on this expression. |
@@ -538,6 +542,38 @@ field("groups").arrayContainsAny(array([field("userGroup"), "guest"]));
 
 ```
 
+## Expression.arrayFilter()
+
+Filters the array using a provided alias and predicate expression.
+
+<b>Signature:</b>
+
+```typescript
+arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  alias | string | The variable name to use for each element. |
+|  filter | [BooleanExpression](./firestore_lite_pipelines.booleanexpression.md#booleanexpression_class) | The predicate boolean expression to filter by. |
+
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the filtered array.
+
+### Example
+
+
+```typescript
+// Filter the 'items' array to only include those where the 'price' is greater than 10
+field("items").arrayFilter('item', greaterThan(variable('item.price'), 10));
+
+```
+
 ## Expression.arrayFirst()
 
 Returns the first element of the array.
@@ -1187,6 +1223,41 @@ field("myArray").arrayReverse();
 
 ```
 
+## Expression.arraySlice()
+
+Returns a subset of the array.
+
+<b>Signature:</b>
+
+```typescript
+arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  offset | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The starting offset. |
+|  length | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The optional length of the slice. |
+
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the sliced array.
+
+### Example
+
+
+```typescript
+// Get 5 elements from the 'items' array starting from index 2
+field("items").arraySlice(2, 5);
+
+// Get n number of elements from the 'items' array starting from index 2
+field("items").arraySlice(2, field("count"));
+
+```
+
 ## Expression.arraySum()
 
 Creates an expression that computes the sum of the elements in an array.
@@ -1211,6 +1282,71 @@ field("scores").arraySum();
 
 ```
 
+## Expression.arrayTransform()
+
+Creates an expression that applies a provided transformation to each element in an array.
+
+<b>Signature:</b>
+
+```typescript
+arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  elementAlias | string | The variable name to use for each element. |
+|  transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
+
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the arrayTransform operation.
+
+### Example
+
+
+```typescript
+// Transform the 'scores' array by multiplying each score by 10
+field("scores").arrayTransform("score", multiply(variable("score"), 10));
+
+```
+
+## Expression.arrayTransformWithIndex()
+
+Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
+
+<b>Signature:</b>
+
+```typescript
+arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  elementAlias | string | The variable name to use for each element. |
+|  indexAlias | string | The variable name to use for the current index. |
+|  transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
+
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the arrayTransformWithIndex operation.
+
+### Example
+
+
+```typescript
+// Transform the 'scores' array by adding the index to each score
+field("scores").arrayTransformWithIndex("score", "i", add(variable("score"), variable("i")));
+
+```
+
 ## Expression.as()
 
 Assigns an alias to this expression.