feat(firestore): add support for remaining map pipeline expressions (#9483)

Author: dlarocque

.changeset/afraid-pigs-heal.md

@@ -0,0 +1,6 @@
+---
+'firebase': minor
+'@firebase/firestore': minor
+---
+
+Support added for `mapSet`, `mapValues`, `mapEntries`, `mapKeys` Pipelines expressions.

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

@@ -534,14 +534,22 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     ltrim(valueToTrim?: string | Expression | Bytes): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    mapEntries(): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     mapGet(subfield: string): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    mapKeys(): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     mapMerge(secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;
     /* Excluded from this release type: _readUserData */
     mapRemove(key: string): FunctionExpression;
     /* Excluded from this release type: _readUserData */
     mapRemove(keyExpr: Expression): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    mapSet(key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
+    mapValues(): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     maximum(): AggregateFunction;
     /* Excluded from this release type: _readUserData */
     minimum(): AggregateFunction;
@@ -891,12 +899,24 @@ export function ltrim(expression: Expression, valueToTrim?: string | Expression
 // @beta
 export function map(elements: Record<string, unknown>): FunctionExpression;
 
+// @beta
+export function mapEntries(mapField: string): FunctionExpression;
+
+// @beta
+export function mapEntries(mapExpression: Expression): FunctionExpression;
+
 // @beta
 export function mapGet(fieldName: string, subField: string): FunctionExpression;
 
 // @beta
 export function mapGet(mapExpression: Expression, subField: string): FunctionExpression;
 
+// @beta
+export function mapKeys(mapField: string): FunctionExpression;
+
+// @beta
+export function mapKeys(mapExpression: Expression): FunctionExpression;
+
 // @beta
 export function mapMerge(mapField: string, secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;
 
@@ -915,6 +935,18 @@ export function mapRemove(mapField: string, keyExpr: Expression): FunctionExpres
 // @beta
 export function mapRemove(mapExpr: Expression, keyExpr: Expression): FunctionExpression;
 
+// @beta
+export function mapSet(mapField: string, key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
+
+// @beta
+export function mapSet(mapExpression: Expression, key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
+
+// @beta
+export function mapValues(mapField: string): FunctionExpression;
+
+// @beta
+export function mapValues(mapExpression: Expression): FunctionExpression;
+
 // @beta
 export function maximum(expression: Expression): AggregateFunction;
 

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

@@ -537,14 +537,22 @@ export abstract class Expression {
     /* Excluded from this release type: _readUserData */
     ltrim(valueToTrim?: string | Expression | Bytes): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    mapEntries(): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     mapGet(subfield: string): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    mapKeys(): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     mapMerge(secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;
     /* Excluded from this release type: _readUserData */
     mapRemove(key: string): FunctionExpression;
     /* Excluded from this release type: _readUserData */
     mapRemove(keyExpr: Expression): FunctionExpression;
     /* Excluded from this release type: _readUserData */
+    mapSet(key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
+    mapValues(): FunctionExpression;
+    /* Excluded from this release type: _readUserData */
     maximum(): AggregateFunction;
     /* Excluded from this release type: _readUserData */
     minimum(): AggregateFunction;
@@ -894,12 +902,24 @@ export function ltrim(expression: Expression, valueToTrim?: string | Expression
 // @beta
 export function map(elements: Record<string, unknown>): FunctionExpression;
 
+// @beta
+export function mapEntries(mapField: string): FunctionExpression;
+
+// @beta
+export function mapEntries(mapExpression: Expression): FunctionExpression;
+
 // @beta
 export function mapGet(fieldName: string, subField: string): FunctionExpression;
 
 // @beta
 export function mapGet(mapExpression: Expression, subField: string): FunctionExpression;
 
+// @beta
+export function mapKeys(mapField: string): FunctionExpression;
+
+// @beta
+export function mapKeys(mapExpression: Expression): FunctionExpression;
+
 // @beta
 export function mapMerge(mapField: string, secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;
 
@@ -918,6 +938,18 @@ export function mapRemove(mapField: string, keyExpr: Expression): FunctionExpres
 // @beta
 export function mapRemove(mapExpr: Expression, keyExpr: Expression): FunctionExpression;
 
+// @beta
+export function mapSet(mapField: string, key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
+
+// @beta
+export function mapSet(mapExpression: Expression, key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
+
+// @beta
+export function mapValues(mapField: string): FunctionExpression;
+
+// @beta
+export function mapValues(mapExpression: Expression): FunctionExpression;
+
 // @beta
 export function maximum(expression: Expression): AggregateFunction;
 

docs-devsite/firestore_lite_pipelines.expression.md

@@ -117,10 +117,14 @@ field("optional_field").ifAbsent(field('default_field'))
 |  [logicalMaximum(second, others)](./firestore_lite_pipelines.expression.md#expressionlogicalmaximum) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the larger value between this expression and another expression, based on Firestore's value type ordering. |
 |  [logicalMinimum(second, others)](./firestore_lite_pipelines.expression.md#expressionlogicalminimum) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the smaller value between this expression and another expression, based on Firestore's value type ordering. |
 |  [ltrim(valueToTrim)](./firestore_lite_pipelines.expression.md#expressionltrim) |  | <b><i>(Public Preview)</i></b> Trims whitespace or a specified set of characters/bytes from the beginning of a string or byte array. |
+|  [mapEntries()](./firestore_lite_pipelines.expression.md#expressionmapentries) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the entries of a map as an array of maps, where each map contains a <code>&quot;k&quot;</code> property for the key and a <code>&quot;v&quot;</code> property for the value. For example: <code>[{ k: &quot;key1&quot;, v: &quot;value1&quot; }, ...]</code>. |
 |  [mapGet(subfield)](./firestore_lite_pipelines.expression.md#expressionmapget) |  | <b><i>(Public Preview)</i></b> Accesses a value from a map (object) field using the provided key. |
+|  [mapKeys()](./firestore_lite_pipelines.expression.md#expressionmapkeys) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the keys of a map. |
 |  [mapMerge(secondMap, otherMaps)](./firestore_lite_pipelines.expression.md#expressionmapmerge) |  | <b><i>(Public Preview)</i></b> Creates an expression that merges multiple map values. |
 |  [mapRemove(key)](./firestore_lite_pipelines.expression.md#expressionmapremove) |  | <b><i>(Public Preview)</i></b> Creates an expression that removes a key from the map produced by evaluating this expression. |
 |  [mapRemove(keyExpr)](./firestore_lite_pipelines.expression.md#expressionmapremove) |  | <b><i>(Public Preview)</i></b> Creates an expression that removes a key from the map produced by evaluating this expression. |
+|  [mapSet(key, value, moreKeyValues)](./firestore_lite_pipelines.expression.md#expressionmapset) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns a new map with the specified entries added or updated. |
+|  [mapValues()](./firestore_lite_pipelines.expression.md#expressionmapvalues) |  | <b><i>(Public Preview)</i></b> Creates an expression that returns the values of a map. |
 |  [maximum()](./firestore_lite_pipelines.expression.md#expressionmaximum) |  | <b><i>(Public Preview)</i></b> Creates an aggregation that finds the maximum value of a field across multiple stage inputs. |
 |  [minimum()](./firestore_lite_pipelines.expression.md#expressionminimum) |  | <b><i>(Public Preview)</i></b> Creates an aggregation that finds the minimum value of a field across multiple stage inputs. |
 |  [mod(expression)](./firestore_lite_pipelines.expression.md#expressionmod) |  | <b><i>(Public Preview)</i></b> Creates an expression that calculates the modulo (remainder) of dividing this expression by another expression. |
@@ -2504,6 +2508,33 @@ field("userInput").ltrim('"');
 
 ```
 
+## Expression.mapEntries()
+
+> 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 returns the entries of a map as an array of maps, where each map contains a `"k"` property for the key and a `"v"` property for the value. For example: `[{ k: "key1", v: "value1" }, ...]`<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+mapEntries(): FunctionExpression;
+```
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the entries of the map.
+
+### Example
+
+
+```typescript
+// Get the entries of the 'address' map
+field("address").mapEntries();
+
+```
+
 ## Expression.mapGet()
 
 > 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.
@@ -2538,6 +2569,35 @@ field("address").mapGet("city");
 
 ```
 
+## Expression.mapKeys()
+
+> 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 returns the keys of a map.
+
+While the backend generally preserves insertion order, relying on the order of the output array is not guaranteed and should be avoided.
+
+<b>Signature:</b>
+
+```typescript
+mapKeys(): FunctionExpression;
+```
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the keys of the map.
+
+### Example
+
+
+```typescript
+// Get the keys of the 'address' map
+field("address").mapKeys();
+
+```
+
 ## Expression.mapMerge()
 
 > 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.
@@ -2643,6 +2703,73 @@ map({foo: 'bar', baz: true}).mapRemove(constant('baz'));
 
 ```
 
+## Expression.mapSet()
+
+> 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 returns a new map with the specified entries added or updated.
+
+Note that `mapSet` only performs shallow updates to the map. Setting a value to `null` will retain the key with a `null` value. To remove a key entirely, use `mapRemove`<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+mapSet(key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  key | string \| [Expression](./firestore_lite_pipelines.expression.md#expression_class) | The key to set. Must be a string or a constant string expression. |
+|  value | unknown | The value to set. |
+|  moreKeyValues | unknown\[\] | Additional key-value pairs to set. |
+
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the map with the entries set.
+
+### Example
+
+
+```typescript
+// Set the 'city' to "San Francisco" in the 'address' map
+field("address").mapSet("city", "San Francisco");
+
+```
+
+## Expression.mapValues()
+
+> 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 returns the values of a map.
+
+While the backend generally preserves insertion order, relying on the order of the output array is not guaranteed and should be avoided.
+
+<b>Signature:</b>
+
+```typescript
+mapValues(): FunctionExpression;
+```
+<b>Returns:</b>
+
+[FunctionExpression](./firestore_lite_pipelines.functionexpression.md#functionexpression_class)
+
+A new `Expression` representing the values of the map.
+
+### Example
+
+
+```typescript
+// Get the values of the 'address' map
+field("address").mapValues();
+
+```
+
 ## Expression.maximum()
 
 > 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.