feat: add remaining map expressions

Adds support for the remaining `map` pipeline expressions; `mapSet`,
`mapValues`, `mapEntries`, `mapKeys`.

Ported from: firebase/firebase-js-sdk#9483

Author: dlarocque

api-report/firestore.api.md

@@ -1027,10 +1027,14 @@ abstract class Expression implements firestore.Pipelines.Expression, HasUserData
     log10(): FunctionExpression;
     logicalMaximum(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
     logicalMinimum(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
+    mapEntries(): FunctionExpression;
     mapGet(subfield: string): FunctionExpression;
+    mapKeys(): FunctionExpression;
     mapMerge(secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;
     mapRemove(key: string): FunctionExpression;
     mapRemove(keyExpr: Expression): FunctionExpression;
+    mapSet(key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
+    mapValues(): FunctionExpression;
     maximum(): AggregateFunction;
     minimum(): AggregateFunction;
     mod(expression: Expression): FunctionExpression;
@@ -1582,12 +1586,18 @@ function logicalMinimum(fieldName: string, second: Expression | unknown, ...othe
 // @beta
 function map(elements: Record<string, unknown>): FunctionExpression;
 
+// @beta
+function mapEntries(map: unknown): FunctionExpression;
+
 // @beta
 function mapGet(fieldName: string, subField: string): FunctionExpression;
 
 // @beta
 function mapGet(mapExpression: Expression, subField: string): FunctionExpression;
 
+// @beta
+function mapKeys(map: unknown): FunctionExpression;
+
 // @beta
 function mapMerge(mapField: string, secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;
 
@@ -1606,6 +1616,12 @@ function mapRemove(mapField: string, keyExpr: Expression): FunctionExpression;
 // @beta
 function mapRemove(mapExpr: Expression, keyExpr: Expression): FunctionExpression;
 
+// @beta
+function mapSet(map: unknown, key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
+
+// @beta
+function mapValues(map: unknown): FunctionExpression;
+
 // Warning: (tsdoc-undefined-tag) The TSDoc tag "@private" is not defined in this configuration
 //
 // @public
@@ -1825,6 +1841,10 @@ declare namespace Pipelines {
         dotProduct,
         euclideanDistance,
         mapGet,
+        mapEntries,
+        mapKeys,
+        mapSet,
+        mapValues,
         lessThanOrEqual,
         equalAny,
         map,

dev/src/pipelines/expression.ts

@@ -1274,6 +1274,95 @@ export abstract class Expression
     return new FunctionExpression('map_get', [this, constant(subfield)]);
   }
 
+  /**
+   * @beta
+   * Creates an expression that returns a new map with the specified entries added or updated.
+   *
+   * @remarks
+   * 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`.
+   *
+   * @example
+   * ```typescript
+   * // Set the 'city' to "San Francisco" in the 'address' map
+   * field("address").mapSet("city", "San Francisco");
+   * ```
+   *
+   * @param key - The key to set. Must be a string or a constant string expression.
+   * @param value - The value to set.
+   * @param moreKeyValues - Additional key-value pairs to set.
+   * @returns A new `Expression` representing the map with the entries set.
+   */
+  mapSet(
+    key: string | Expression,
+    value: unknown,
+    ...moreKeyValues: unknown[]
+  ): FunctionExpression {
+    const args = [
+      this,
+      valueToDefaultExpr(key),
+      valueToDefaultExpr(value),
+      ...moreKeyValues.map(valueToDefaultExpr),
+    ];
+    return new FunctionExpression('map_set', args);
+  }
+
+  /**
+   * @beta
+   * Creates an expression that returns the keys of a map.
+   *
+   * Note: While the backend generally preserves insertion order, relying on the
+   * order of the output array is not guaranteed and should be avoided.
+   *
+   * @example
+   * ```typescript
+   * // Get the keys of the 'address' map
+   * field("address").mapKeys();
+   * ```
+   *
+   * @returns A new `Expression` representing the keys of the map.
+   */
+  mapKeys(): FunctionExpression {
+    return new FunctionExpression('map_keys', [this]);
+  }
+
+  /**
+   * @beta
+   * Creates an expression that returns the values of a map.
+   *
+   * Note: While the backend generally preserves insertion order, relying on the
+   * order of the output array is not guaranteed and should be avoided.
+   *
+   * @example
+   * ```typescript
+   * // Get the values of the 'address' map
+   * field("address").mapValues();
+   * ```
+   *
+   * @returns A new `Expression` representing the values of the map.
+   */
+  mapValues(): FunctionExpression {
+    return new FunctionExpression('map_values', [this]);
+  }
+
+  /**
+   * @beta
+   * 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" }, ...]`.
+   *
+   * @example
+   * ```typescript
+   * // Get the entries of the 'address' map
+   * field("address").mapEntries();
+   * ```
+   *
+   * @returns A new `Expression` representing the entries of the map.
+   */
+  mapEntries(): FunctionExpression {
+    return new FunctionExpression('map_entries', [this]);
+  }
+
   /**
    * @beta
    * Creates an aggregation that counts the number of stage inputs with valid evaluations of the
@@ -6342,6 +6431,93 @@ export function mapGet(
   return fieldOrExpression(fieldOrExpr).mapGet(subField);
 }
 
+/**
+ * @beta
+ * 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`.
+ *
+ * @example
+ * ```typescript
+ * // Set the 'city' to "San Francisco" in the 'address' map field
+ * mapSet("address", "city", "San Francisco");
+ * ```
+ *
+ * @param map - The map to set entries in.
+ * @param key - The key to set. Must be a string or a constant string expression.
+ * @param value - The value to set.
+ * @param moreKeyValues - Additional key-value pairs to set.
+ * @returns A new `Expression` representing the map with the entries set.
+ */
+export function mapSet(
+  map: unknown,
+  key: string | Expression,
+  value: unknown,
+  ...moreKeyValues: unknown[]
+): FunctionExpression {
+  return fieldOrExpression(map).mapSet(key, value, ...moreKeyValues);
+}
+
+/**
+ * @beta
+ * Creates an expression that returns the keys of a map.
+ *
+ * Note: While the backend generally preserves insertion order, relying on the
+ * order of the output array is not guaranteed and should be avoided.
+ *
+ * @example
+ * ```typescript
+ * // Get the keys of the 'address' map field
+ * mapKeys("address");
+ * ```
+ *
+ * @param map - The map to get the keys of.
+ * @returns A new `Expression` representing the keys of the map.
+ */
+export function mapKeys(map: unknown): FunctionExpression {
+  return fieldOrExpression(map).mapKeys();
+}
+
+/**
+ * @beta
+ * Creates an expression that returns the values of a map.
+ *
+ * Note: While the backend generally preserves insertion order, relying on the
+ * order of the output array is not guaranteed and should be avoided.
+ *
+ * @example
+ * ```typescript
+ * // Get the values of the 'address' map field
+ * mapValues("address");
+ * ```
+ *
+ * @param map - The map to get the values of.
+ * @returns A new `Expression` representing the values of the map.
+ */
+export function mapValues(map: unknown): FunctionExpression {
+  return fieldOrExpression(map).mapValues();
+}
+
+/**
+ * @beta
+ * 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" }, ...]`.
+ *
+ * @example
+ * ```typescript
+ * // Get the entries of the 'address' map field
+ * mapEntries("address");
+ * ```
+ *
+ * @param map - The map to get the entries of.
+ * @returns A new `Expression` representing the entries of the map.
+ */
+export function mapEntries(map: unknown): FunctionExpression {
+  return fieldOrExpression(map).mapEntries();
+}
+
 /**
  * @beta
  * Creates an aggregation that counts the total number of stage inputs.

dev/src/pipelines/index.ts

@@ -46,6 +46,10 @@ export {
   dotProduct,
   euclideanDistance,
   mapGet,
+  mapEntries,
+  mapKeys,
+  mapSet,
+  mapValues,
   lessThanOrEqual,
   equalAny,
   map,

dev/system-test/pipeline.ts

@@ -89,6 +89,10 @@ import {
   dotProduct,
   euclideanDistance,
   mapGet,
+  mapEntries,
+  mapKeys,
+  mapSet,
+  mapValues,
   lessThanOrEqual,
   equalAny,
   notEqualAny,
@@ -2830,6 +2834,103 @@ describe.skipClassic('Pipeline class', () => {
       );
     });
 
+    it('test mapSet', async () => {
+      const snapshot = await firestore
+        .pipeline()
+        .collection(randomCol.path)
+        .limit(1)
+        .replaceWith(map({}))
+        .addFields(
+          mapSet(map({}), 'a', 1).as('simple'),
+          mapSet(map({a: 1}), 'b', 2).as('add'),
+          mapSet(map({a: 1}), 'a', 2).as('overwrite'),
+          mapSet(map({a: 1, b: 2}), 'a', 3, 'c', 4).as('multi'),
+          mapSet(map({a: 1}), 'a', field('non_existent')).as('remove'),
+          mapSet(map({a: 1}), 'b', null).as('setNull'),
+          mapSet(map({a: {b: 1}}), 'a.b', 2).as('setDotted'),
+          mapSet(map({}), '', 'empty').as('setEmptyKey'),
+          mapSet(map({a: 1}), 'b', add(constant(1), constant(2))).as(
+            'setExprVal',
+          ),
+          mapSet(map({}), 'obj', map({hidden: true})).as('setNestedMap'),
+          mapSet(map({}), '~!@#$%^&*()_+', 'special').as('setSpecialChars'),
+        )
+        .execute();
+      expectResults(snapshot, {
+        simple: {a: 1},
+        add: {a: 1, b: 2},
+        overwrite: {a: 2},
+        multi: {a: 3, b: 2, c: 4},
+        remove: {},
+        setNull: {a: 1, b: null},
+        setDotted: {a: {b: 1}, 'a.b': 2},
+        setEmptyKey: {'': 'empty'},
+        setExprVal: {a: 1, b: 3},
+        setNestedMap: {obj: {hidden: true}},
+        setSpecialChars: {'~!@#$%^&*()_+': 'special'},
+      });
+    });
+
+    it('test mapKeys', async () => {
+      const snapshot = await firestore
+        .pipeline()
+        .collection(randomCol.path)
+        .limit(1)
+        .replaceWith(map({a: 1, b: 2, c: 3}))
+        .addFields(
+          mapKeys(map({a: 1, b: 2})).as('keys'),
+          mapKeys(map({})).as('empty_keys'),
+          mapKeys(map({a: {nested: true}})).as('nested_keys'),
+        )
+        .execute();
+
+      const res = snapshot.results[0].data();
+      expect(res.keys).to.have.members(['a', 'b']);
+      expect(res.empty_keys).to.deep.equal([]);
+      expect(res.nested_keys).to.have.members(['a']);
+    });
+
+    it('test mapValues', async () => {
+      const snapshot = await firestore
+        .pipeline()
+        .collection(randomCol.path)
+        .limit(1)
+        .replaceWith(map({a: 1, b: 2}))
+        .addFields(
+          mapValues(map({a: 1, b: 2})).as('values'),
+          mapValues(map({})).as('empty_values'),
+          mapValues(map({a: {nested: true}})).as('nested_values'),
+        )
+        .execute();
+      const res = snapshot.results[0].data();
+      expect(res.values).to.have.members([1, 2]);
+      expect(res.empty_values).to.deep.equal([]);
+      expect(res.nested_values).to.deep.include.members([{nested: true}]);
+    });
+
+    it('test mapEntries', async () => {
+      const snapshot = await firestore
+        .pipeline()
+        .collection(randomCol.path)
+        .limit(1)
+        .replaceWith(map({a: 1, b: 2}))
+        .addFields(
+          mapEntries(map({a: 1, b: 2})).as('entries'),
+          mapEntries(map({})).as('empty_entries'),
+          mapEntries(map({a: {nested: true}})).as('nested_entries'),
+        )
+        .execute();
+      const res = snapshot.results[0].data();
+      expect(res.entries).to.deep.include.members([
+        {k: 'a', v: 1},
+        {k: 'b', v: 2},
+      ]);
+      expect(res.empty_entries).to.deep.equal([]);
+      expect(res.nested_entries).to.deep.include.members([
+        {k: 'a', v: {nested: true}},
+      ]);
+    });
+
     it('testDistanceFunctions', async () => {
       const sourceVector = FieldValue.vector([0.1, 0.1]);
       const targetVector = FieldValue.vector([0.5, 0.8]);