Skip to content

Commit 9620f9a

Browse files
milaGGLmilaGGL
authored
feat(firestore): Add array expressions (#9788)
1 parent 2ca39c7 commit 9620f9a

11 files changed

Lines changed: 1577 additions & 0 deletions

File tree

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,12 @@ export function arrayContainsAny(array: Expression, values: Expression): Boolean
119119
// @public
120120
export function arrayContainsAny(fieldName: string, values: Expression): BooleanExpression;
121121

122+
// @public
123+
export function arrayFilter(fieldName: string, alias: string, filter: BooleanExpression): FunctionExpression;
124+
125+
// @public
126+
export function arrayFilter(arrayExpression: Expression, alias: string, filter: BooleanExpression): FunctionExpression;
127+
122128
// @public
123129
export function arrayFirst(fieldName: string): FunctionExpression;
124130

@@ -227,12 +233,30 @@ export function arrayMinimumN(arrayExpression: Expression, n: number): FunctionE
227233
// @public
228234
export function arrayMinimumN(arrayExpression: Expression, n: Expression): FunctionExpression;
229235

236+
// @public
237+
export function arraySlice(fieldName: string, offset: number | Expression, length?: number | Expression): FunctionExpression;
238+
239+
// @public
240+
export function arraySlice(arrayExpression: Expression, offset: number | Expression, length?: number | Expression): FunctionExpression;
241+
230242
// @public
231243
export function arraySum(fieldName: string): FunctionExpression;
232244

233245
// @public
234246
export function arraySum(expression: Expression): FunctionExpression;
235247

248+
// @public
249+
export function arrayTransform(arrayExpression: Expression, elementAlias: string, transform: Expression): FunctionExpression;
250+
251+
// @public
252+
export function arrayTransform(fieldName: string, elementAlias: string, transform: Expression): FunctionExpression;
253+
254+
// @public
255+
export function arrayTransformWithIndex(arrayExpression: Expression, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
256+
257+
// @public
258+
export function arrayTransformWithIndex(fieldName: string, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
259+
236260
// @public
237261
export function ascending(expr: Expression): Ordering;
238262

@@ -514,6 +538,8 @@ export abstract class Expression {
514538
/* Excluded from this release type: _readUserData */
515539
arrayContainsAny(arrayExpression: Expression): BooleanExpression;
516540
/* Excluded from this release type: _readUserData */
541+
arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
542+
/* Excluded from this release type: _readUserData */
517543
arrayFirst(): FunctionExpression;
518544
/* Excluded from this release type: _readUserData */
519545
arrayFirstN(n: number): FunctionExpression;
@@ -558,8 +584,14 @@ export abstract class Expression {
558584
/* Excluded from this release type: _readUserData */
559585
arrayReverse(): FunctionExpression;
560586
/* Excluded from this release type: _readUserData */
587+
arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
588+
/* Excluded from this release type: _readUserData */
561589
arraySum(): FunctionExpression;
562590
/* Excluded from this release type: _readUserData */
591+
arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
592+
/* Excluded from this release type: _readUserData */
593+
arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
594+
/* Excluded from this release type: _readUserData */
563595
as(name: string): AliasedExpression;
564596
/* Excluded from this release type: _readUserData */
565597
asBoolean(): BooleanExpression;

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,12 @@ export function arrayContainsAny(array: Expression, values: Expression): Boolean
119119
// @public
120120
export function arrayContainsAny(fieldName: string, values: Expression): BooleanExpression;
121121

122+
// @public
123+
export function arrayFilter(fieldName: string, alias: string, filter: BooleanExpression): FunctionExpression;
124+
125+
// @public
126+
export function arrayFilter(arrayExpression: Expression, alias: string, filter: BooleanExpression): FunctionExpression;
127+
122128
// @public
123129
export function arrayFirst(fieldName: string): FunctionExpression;
124130

@@ -227,12 +233,30 @@ export function arrayMinimumN(arrayExpression: Expression, n: number): FunctionE
227233
// @public
228234
export function arrayMinimumN(arrayExpression: Expression, n: Expression): FunctionExpression;
229235

236+
// @public
237+
export function arraySlice(fieldName: string, offset: number | Expression, length?: number | Expression): FunctionExpression;
238+
239+
// @public
240+
export function arraySlice(arrayExpression: Expression, offset: number | Expression, length?: number | Expression): FunctionExpression;
241+
230242
// @public
231243
export function arraySum(fieldName: string): FunctionExpression;
232244

233245
// @public
234246
export function arraySum(expression: Expression): FunctionExpression;
235247

248+
// @public
249+
export function arrayTransform(arrayExpression: Expression, elementAlias: string, transform: Expression): FunctionExpression;
250+
251+
// @public
252+
export function arrayTransform(fieldName: string, elementAlias: string, transform: Expression): FunctionExpression;
253+
254+
// @public
255+
export function arrayTransformWithIndex(arrayExpression: Expression, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
256+
257+
// @public
258+
export function arrayTransformWithIndex(fieldName: string, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
259+
236260
// @public
237261
export function ascending(expr: Expression): Ordering;
238262

@@ -517,6 +541,8 @@ export abstract class Expression {
517541
/* Excluded from this release type: _readUserData */
518542
arrayContainsAny(arrayExpression: Expression): BooleanExpression;
519543
/* Excluded from this release type: _readUserData */
544+
arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
545+
/* Excluded from this release type: _readUserData */
520546
arrayFirst(): FunctionExpression;
521547
/* Excluded from this release type: _readUserData */
522548
arrayFirstN(n: number): FunctionExpression;
@@ -561,8 +587,14 @@ export abstract class Expression {
561587
/* Excluded from this release type: _readUserData */
562588
arrayReverse(): FunctionExpression;
563589
/* Excluded from this release type: _readUserData */
590+
arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
591+
/* Excluded from this release type: _readUserData */
564592
arraySum(): FunctionExpression;
565593
/* Excluded from this release type: _readUserData */
594+
arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
595+
/* Excluded from this release type: _readUserData */
596+
arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
597+
/* Excluded from this release type: _readUserData */
566598
as(name: string): AliasedExpression;
567599
/* Excluded from this release type: _readUserData */
568600
asBoolean(): BooleanExpression;

‎docs-devsite/firestore_lite_pipelines.expression.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ export declare abstract class Expression
4545
| [arrayContainsAll(arrayExpression)](./firestore_lite_pipelines.expression.md#expressionarraycontainsall) | | Creates an expression that checks if an array contains all the specified elements. |
4646
| [arrayContainsAny(values)](./firestore_lite_pipelines.expression.md#expressionarraycontainsany) | | Creates an expression that checks if an array contains any of the specified elements. |
4747
| [arrayContainsAny(arrayExpression)](./firestore_lite_pipelines.expression.md#expressionarraycontainsany) | | Creates an expression that checks if an array contains any of the specified elements. |
48+
| [arrayFilter(alias, filter)](./firestore_lite_pipelines.expression.md#expressionarrayfilter) | | Filters the array using a provided alias and predicate expression. |
4849
| [arrayFirst()](./firestore_lite_pipelines.expression.md#expressionarrayfirst) | | Returns the first element of the array. |
4950
| [arrayFirstN(n)](./firestore_lite_pipelines.expression.md#expressionarrayfirstn) | | Returns the first <code>n</code> elements of the array. |
5051
| [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
6768
| [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. |
6869
| [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. |
6970
| [arrayReverse()](./firestore_lite_pipelines.expression.md#expressionarrayreverse) | | Creates an expression that reverses an array. |
71+
| [arraySlice(offset, length)](./firestore_lite_pipelines.expression.md#expressionarrayslice) | | Returns a subset of the array. |
7072
| [arraySum()](./firestore_lite_pipelines.expression.md#expressionarraysum) | | Creates an expression that computes the sum of the elements in an array. |
73+
| [arrayTransform(elementAlias, transform)](./firestore_lite_pipelines.expression.md#expressionarraytransform) | | Creates an expression that applies a provided transformation to each element in an array. |
74+
| [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. |
7175
| [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. |
7276
| [asBoolean()](./firestore_lite_pipelines.expression.md#expressionasboolean) | | Wraps the expression in a \[BooleanExpression\]. |
7377
| [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. |
@@ -539,6 +543,38 @@ field("groups").arrayContainsAny(array([field("userGroup"), "guest"]));
539543
540544
```
541545

546+
## Expression.arrayFilter()
547+
548+
Filters the array using a provided alias and predicate expression.
549+
550+
<b>Signature:</b>
551+
552+
```typescript
553+
arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
554+
```
555+
556+
#### Parameters
557+
558+
| Parameter | Type | Description |
559+
| --- | --- | --- |
560+
| alias | string | The variable name to use for each element. |
561+
| filter | [BooleanExpression](./firestore_lite_pipelines.booleanexpression.md#booleanexpression_class) | The predicate boolean expression to filter by. |
562+
563+
<b>Returns:</b>
564+
565+
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
566+
567+
A new `Expression` representing the filtered array.
568+
569+
### Example
570+
571+
572+
```typescript
573+
// Filter the 'items' array to only include those where the 'price' is greater than 10
574+
field("items").arrayFilter('item', greaterThan(variable('item.price'), 10));
575+
576+
```
577+
542578
## Expression.arrayFirst()
543579

544580
Returns the first element of the array.
@@ -1188,6 +1224,41 @@ field("myArray").arrayReverse();
11881224
11891225
```
11901226

1227+
## Expression.arraySlice()
1228+
1229+
Returns a subset of the array.
1230+
1231+
<b>Signature:</b>
1232+
1233+
```typescript
1234+
arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
1235+
```
1236+
1237+
#### Parameters
1238+
1239+
| Parameter | Type | Description |
1240+
| --- | --- | --- |
1241+
| offset | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The starting offset. |
1242+
| length | number \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The optional length of the slice. |
1243+
1244+
<b>Returns:</b>
1245+
1246+
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
1247+
1248+
A new `Expression` representing the sliced array.
1249+
1250+
### Example
1251+
1252+
1253+
```typescript
1254+
// Get 5 elements from the 'items' array starting from index 2
1255+
field("items").arraySlice(2, 5);
1256+
1257+
// Get n number of elements from the 'items' array starting from index 2
1258+
field("items").arraySlice(2, field("count"));
1259+
1260+
```
1261+
11911262
## Expression.arraySum()
11921263

11931264
Creates an expression that computes the sum of the elements in an array.
@@ -1212,6 +1283,71 @@ field("scores").arraySum();
12121283
12131284
```
12141285

1286+
## Expression.arrayTransform()
1287+
1288+
Creates an expression that applies a provided transformation to each element in an array.
1289+
1290+
<b>Signature:</b>
1291+
1292+
```typescript
1293+
arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
1294+
```
1295+
1296+
#### Parameters
1297+
1298+
| Parameter | Type | Description |
1299+
| --- | --- | --- |
1300+
| elementAlias | string | The variable name to use for each element. |
1301+
| transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
1302+
1303+
<b>Returns:</b>
1304+
1305+
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
1306+
1307+
A new `Expression` representing the arrayTransform operation.
1308+
1309+
### Example
1310+
1311+
1312+
```typescript
1313+
// Transform the 'scores' array by multiplying each score by 10
1314+
field("scores").arrayTransform("score", multiply(variable("score"), 10));
1315+
1316+
```
1317+
1318+
## Expression.arrayTransformWithIndex()
1319+
1320+
Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
1321+
1322+
<b>Signature:</b>
1323+
1324+
```typescript
1325+
arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
1326+
```
1327+
1328+
#### Parameters
1329+
1330+
| Parameter | Type | Description |
1331+
| --- | --- | --- |
1332+
| elementAlias | string | The variable name to use for each element. |
1333+
| indexAlias | string | The variable name to use for the current index. |
1334+
| transform | [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The lambda expression used to transform the elements. |
1335+
1336+
<b>Returns:</b>
1337+
1338+
[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
1339+
1340+
A new `Expression` representing the arrayTransformWithIndex operation.
1341+
1342+
### Example
1343+
1344+
1345+
```typescript
1346+
// Transform the 'scores' array by adding the index to each score
1347+
field("scores").arrayTransformWithIndex("score", "i", add(variable("score"), variable("i")));
1348+
1349+
```
1350+
12151351
## Expression.as()
12161352

12171353
Assigns an alias to this expression.

0 commit comments

Comments
 (0)