Implement VectorValue type support.

Author: MarkDuckworth

packages/firestore/src/lite-api/field_value_impl.ts

@@ -23,6 +23,7 @@ import {
   NumericIncrementFieldValueImpl,
   ServerTimestampFieldValueImpl
 } from './user_data_reader';
+import { VectorValue } from './vector_value';
 
 /**
  * Returns a sentinel for use with {@link @firebase/firestore/lite#(updateDoc:1)} or
@@ -97,3 +98,14 @@ export function arrayRemove(...elements: unknown[]): FieldValue {
 export function increment(n: number): FieldValue {
   return new NumericIncrementFieldValueImpl('increment', n);
 }
+
+/**
+ * Creates a new `VectorValue` constructed with a copy of the given array of numbers.
+ *
+ * @param values - Create a `VectorValue` instance with a copy of this array of numbers.
+ *
+ * @returns A new `VectorValue` constructed with a copy of the given array of numbers.
+ */
+export function vector(values?: number[]): VectorValue {
+  return new VectorValue(values);
+}

packages/firestore/src/lite-api/user_data_reader.ts

@@ -26,6 +26,7 @@ import { ParseContext } from '../api/parse_context';
 import { DatabaseId } from '../core/database_info';
 import { DocumentKey } from '../model/document_key';
 import { FieldMask } from '../model/field_mask';
+import { vectorValue } from '../model/map_type';
 import {
   FieldTransform,
   Mutation,
@@ -69,6 +70,7 @@ import {
   WithFieldValue
 } from './reference';
 import { Timestamp } from './timestamp';
+import { VectorValue } from './vector_value';
 
 const RESERVED_FIELD_REGEX = /^__.*__$/;
 
@@ -901,6 +903,9 @@ function parseScalarValue(
         value._key.path
       )
     };
+  }
+  if (value instanceof VectorValue) {
+    return vectorValue(value);
   } else {
     throw context.createError(
       `Unsupported field value: ${valueDescription(value)}`
@@ -925,7 +930,8 @@ function looksLikeJsonObject(input: unknown): boolean {
     !(input instanceof GeoPoint) &&
     !(input instanceof Bytes) &&
     !(input instanceof DocumentReference) &&
-    !(input instanceof FieldValue)
+    !(input instanceof FieldValue) &&
+    !(input instanceof VectorValue)
   );
 }
 

packages/firestore/src/lite-api/user_data_writer.ts

@@ -19,6 +19,7 @@ import { DocumentData } from '@firebase/firestore-types';
 
 import { DatabaseId } from '../core/database_info';
 import { DocumentKey } from '../model/document_key';
+import { VECTOR_MAP_VECTORS_KEY } from '../model/map_type';
 import {
   normalizeByteString,
   normalizeNumber,
@@ -48,6 +49,7 @@ import { forEach } from '../util/obj';
 
 import { GeoPoint } from './geo_point';
 import { Timestamp } from './timestamp';
+import { VectorValue } from './vector_value';
 
 export type ServerTimestampBehavior = 'estimate' | 'previous' | 'none';
 
@@ -85,6 +87,8 @@ export abstract class AbstractUserDataWriter {
         return this.convertArray(value.arrayValue!, serverTimestampBehavior);
       case TypeOrder.ObjectValue:
         return this.convertObject(value.mapValue!, serverTimestampBehavior);
+      case TypeOrder.VectorValue:
+        return this.convertVectorValue(value.mapValue!);
       default:
         throw fail('Invalid value type: ' + JSON.stringify(value));
     }
@@ -111,6 +115,19 @@ export abstract class AbstractUserDataWriter {
     return result;
   }
 
+  /**
+   * @internal
+   */
+  convertVectorValue(mapValue: ProtoMapValue): VectorValue {
+    const values = mapValue.fields?.[
+      VECTOR_MAP_VECTORS_KEY
+    ].arrayValue?.values?.map(value => {
+      return normalizeNumber(value.doubleValue);
+    });
+
+    return new VectorValue(values);
+  }
+
   private convertGeoPoint(value: ProtoLatLng): GeoPoint {
     return new GeoPoint(
       normalizeNumber(value.latitude),

packages/firestore/src/lite-api/vector_value.ts

@@ -0,0 +1,34 @@
+import { isPrimitiveArrayEqual } from '../util/array';
+
+/**
+ * Represent a vector type in Firestore documents.
+ * Create an instance with {@link FieldValue.vector}.
+ *
+ * @class VectorValue
+ */
+export class VectorValue {
+  private readonly _values: number[];
+
+  /**
+   * @private
+   * @internal
+   */
+  constructor(values: number[] | undefined) {
+    // Making a copy of the parameter.
+    this._values = (values || []).map(n => n);
+  }
+
+  /**
+   * Returns a copy of the raw number array form of the vector.
+   */
+  toArray(): number[] {
+    return this._values.map(n => n);
+  }
+
+  /**
+   * Returns `true` if the two VectorValue has the same raw number arrays, returns `false` otherwise.
+   */
+  isEqual(other: VectorValue): boolean {
+    return isPrimitiveArrayEqual(this._values, other._values);
+  }
+}

packages/firestore/src/model/type_order.ts

@@ -35,6 +35,7 @@ export const enum TypeOrder {
   RefValue = 7,
   GeoPointValue = 8,
   ArrayValue = 9,
-  ObjectValue = 10,
+  VectorValue = 10,
+  ObjectValue = 11,
   MaxValue = 9007199254740991 // Number.MAX_SAFE_INTEGER
 }

packages/firestore/src/model/values.ts

@@ -29,6 +29,7 @@ import { forEach, objectSize } from '../util/obj';
 import { isNegativeZero } from '../util/types';
 
 import { DocumentKey } from './document_key';
+import { isVectorValue, VECTOR_MAP_VECTORS_KEY } from './map_type';
 import {
   normalizeByteString,
   normalizeNumber,
@@ -79,6 +80,8 @@ export function typeOrder(value: Value): TypeOrder {
       return TypeOrder.ServerTimestampValue;
     } else if (isMaxValue(value)) {
       return TypeOrder.MaxValue;
+    } else if (isVectorValue(value)) {
+      return TypeOrder.VectorValue;
     }
     return TypeOrder.ObjectValue;
   } else {
@@ -123,6 +126,7 @@ export function valueEquals(left: Value, right: Value): boolean {
         right.arrayValue!.values || [],
         valueEquals
       );
+    case TypeOrder.VectorValue:
     case TypeOrder.ObjectValue:
       return objectEquals(left, right);
     case TypeOrder.MaxValue:
@@ -252,6 +256,8 @@ export function valueCompare(left: Value, right: Value): number {
       return compareGeoPoints(left.geoPointValue!, right.geoPointValue!);
     case TypeOrder.ArrayValue:
       return compareArrays(left.arrayValue!, right.arrayValue!);
+    case TypeOrder.VectorValue:
+      return compareVectors(left.mapValue!, right.mapValue!);
     case TypeOrder.ObjectValue:
       return compareMaps(left.mapValue!, right.mapValue!);
     default:
@@ -349,6 +355,25 @@ function compareArrays(left: ArrayValue, right: ArrayValue): number {
   return primitiveComparator(leftArray.length, rightArray.length);
 }
 
+function compareVectors(left: MapValue, right: MapValue): number {
+  const leftMap = left.fields || {};
+  const rightMap = right.fields || {};
+
+  // The vector is a map, but only vector value is compared.
+  const leftArrayValue = leftMap[VECTOR_MAP_VECTORS_KEY]?.arrayValue;
+  const rightArrayValue = rightMap[VECTOR_MAP_VECTORS_KEY]?.arrayValue;
+
+  const lengthCompare = primitiveComparator(
+    leftArrayValue?.values?.length || 0,
+    rightArrayValue?.values?.length || 0
+  );
+  if (lengthCompare !== 0) {
+    return lengthCompare;
+  }
+
+  return compareArrays(leftArrayValue!, rightArrayValue!);
+}
+
 function compareMaps(left: MapValue, right: MapValue): number {
   if (left === MAX_VALUE.mapValue && right === MAX_VALUE.mapValue) {
     return 0;
@@ -504,6 +529,7 @@ export function estimateByteSize(value: Value): number {
       return 16;
     case TypeOrder.ArrayValue:
       return estimateArrayByteSize(value.arrayValue!);
+    case TypeOrder.VectorValue:
     case TypeOrder.ObjectValue:
       return estimateMapByteSize(value.mapValue!);
     default:

packages/firestore/src/util/array.ts

@@ -28,7 +28,7 @@ export function includes<T>(array: T[], value: T): boolean {
 }
 
 /**
- * Returns true iff the array contains any value mathching the predicate
+ * Returns true iff the array contains any value matching the predicate
  */
 export function some<T>(array: T[], predicate: (t: T) => boolean): boolean {
   for (let i = 0; i < array.length; i++) {
@@ -111,3 +111,55 @@ export function diffArrays<T>(
     onRemove(before[b++]);
   }
 }
+
+/**
+ * Verifies equality for an array of objects using the `isEqual` interface.
+ *
+ * @private
+ * @internal
+ * @param left Array of objects supporting `isEqual`.
+ * @param right Array of objects supporting `isEqual`.
+ * @return True if arrays are equal.
+ */
+export function isArrayEqual<T extends { isEqual: (t: T) => boolean }>(
+  left: T[],
+  right: T[]
+): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+
+  for (let i = 0; i < left.length; ++i) {
+    if (!left[i].isEqual(right[i])) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Verifies equality for an array of primitives.
+ *
+ * @private
+ * @internal
+ * @param left Array of primitives.
+ * @param right Array of primitives.
+ * @return True if arrays are equal.
+ */
+export function isPrimitiveArrayEqual<T extends number | string>(
+  left: T[],
+  right: T[]
+): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+
+  for (let i = 0; i < left.length; ++i) {
+    if (left[i] !== right[i]) {
+      return false;
+    }
+  }
+
+  return true;
+}