Add decimal128 to new types (#344)

* add decimal128

* add new tests

* format

* resolve comments

* update comments

* refactor compareNumbers

* copy paste Quadruple code

* resolve comments 1

* make Quadruple value in decimal128 private

Author: milaGGL

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

@@ -136,6 +136,14 @@ export function connectFirestoreEmulator(firestore: Firestore, host: string, por
 // @public
 export function count(): AggregateField<number>;
 
+// @public
+export class Decimal128Value {
+    constructor(value: string);
+    isEqual(other: Decimal128Value): boolean;
+    // (undocumented)
+    readonly stringValue: string;
+    }
+
 // @public
 export function deleteDoc<AppModelType, DbModelType extends DocumentData>(reference: DocumentReference<AppModelType, DbModelType>): Promise<void>;
 

common/api-review/firestore.api.md

@@ -142,6 +142,14 @@ export function connectFirestoreEmulator(firestore: Firestore, host: string, por
 // @public
 export function count(): AggregateField<number>;
 
+// @public
+export class Decimal128Value {
+    constructor(value: string);
+    isEqual(other: Decimal128Value): boolean;
+    // (undocumented)
+    readonly stringValue: string;
+    }
+
 // @public
 export function deleteAllPersistentCacheIndexes(indexManager: PersistentCacheIndexManager): void;
 

packages/firestore/lite/index.ts

@@ -143,6 +143,8 @@ export { VectorValue } from '../src/lite-api/vector_value';
 
 export { Int32Value } from '../src/lite-api/int32_value';
 
+export { Decimal128Value } from '../src/lite-api/decimal128_value';
+
 export { RegexValue } from '../src/lite-api/regex_value';
 
 export { BsonBinaryData } from '../src/lite-api/bson_binary_data';

packages/firestore/src/api.ts

@@ -180,6 +180,8 @@ export { VectorValue } from './lite-api/vector_value';
 
 export { Int32Value } from './lite-api/int32_value';
 
+export { Decimal128Value } from './lite-api/decimal128_value';
+
 export { RegexValue } from './lite-api/regex_value';
 
 export { BsonBinaryData } from './lite-api/bson_binary_data';

packages/firestore/src/index/firestore_index_value_writer.ts

@@ -31,9 +31,16 @@ import {
   MapRepresentation,
   RESERVED_REGEX_PATTERN_KEY,
   RESERVED_REGEX_OPTIONS_KEY,
-  RESERVED_INT32_KEY
+  RESERVED_INT32_KEY,
+  RESERVED_DECIMAL128_KEY
 } from '../model/values';
-import { ArrayValue, MapValue, Value } from '../protos/firestore_proto_api';
+import {
+  ArrayValue,
+  MapValue,
+  Value,
+  Timestamp,
+  LatLng
+} from '../protos/firestore_proto_api';
 import { fail } from '../util/assert';
 import { isNegativeZero } from '../util/types';
 
@@ -106,26 +113,10 @@ export class FirestoreIndexValueWriter {
       this.writeValueTypeLabel(encoder, INDEX_TYPE_NUMBER);
       encoder.writeNumber(normalizeNumber(indexValue.integerValue));
     } else if ('doubleValue' in indexValue) {
-      const n = normalizeNumber(indexValue.doubleValue);
-      if (isNaN(n)) {
-        this.writeValueTypeLabel(encoder, INDEX_TYPE_NAN);
-      } else {
-        this.writeValueTypeLabel(encoder, INDEX_TYPE_NUMBER);
-        if (isNegativeZero(n)) {
-          // -0.0, 0 and 0.0 are all considered the same
-          encoder.writeNumber(0.0);
-        } else {
-          encoder.writeNumber(n);
-        }
-      }
+      const doubleValue = normalizeNumber(indexValue.doubleValue);
+      this.writeIndexDouble(doubleValue, encoder);
     } else if ('timestampValue' in indexValue) {
-      let timestamp = indexValue.timestampValue!;
-      this.writeValueTypeLabel(encoder, INDEX_TYPE_TIMESTAMP);
-      if (typeof timestamp === 'string') {
-        timestamp = normalizeTimestamp(timestamp);
-      }
-      encoder.writeString(`${timestamp.seconds || ''}`);
-      encoder.writeNumber(timestamp.nanos || 0);
+      this.writeIndexTimestamp(indexValue.timestampValue!, encoder);
     } else if ('stringValue' in indexValue) {
       this.writeIndexString(indexValue.stringValue!, encoder);
       this.writeTruncationMarker(encoder);
@@ -136,10 +127,7 @@ export class FirestoreIndexValueWriter {
     } else if ('referenceValue' in indexValue) {
       this.writeIndexEntityRef(indexValue.referenceValue!, encoder);
     } else if ('geoPointValue' in indexValue) {
-      const geoPoint = indexValue.geoPointValue!;
-      this.writeValueTypeLabel(encoder, INDEX_TYPE_GEOPOINT);
-      encoder.writeNumber(geoPoint.latitude || 0);
-      encoder.writeNumber(geoPoint.longitude || 0);
+      this.writeIndexGeoPoint(indexValue.geoPointValue!, encoder);
     } else if ('mapValue' in indexValue) {
       const type = detectMapRepresentation(indexValue);
       if (type === MapRepresentation.INTERNAL_MAX) {
@@ -159,12 +147,14 @@ export class FirestoreIndexValueWriter {
       } else if (type === MapRepresentation.BSON_OBJECT_ID) {
         this.writeIndexBsonObjectId(indexValue.mapValue!, encoder);
       } else if (type === MapRepresentation.INT32) {
-        this.writeValueTypeLabel(encoder, INDEX_TYPE_NUMBER);
-        encoder.writeNumber(
-          normalizeNumber(
-            indexValue.mapValue!.fields![RESERVED_INT32_KEY]!.integerValue!
-          )
+        this.writeIndexInt32(indexValue.mapValue!, encoder);
+      } else if (type === MapRepresentation.DECIMAL128) {
+        // Double and Decimal128 sort the same
+        // Decimal128 is written as double with precision lost
+        const parsedValue = parseFloat(
+          indexValue.mapValue!.fields![RESERVED_DECIMAL128_KEY]!.stringValue!
         );
+        this.writeIndexDouble(parsedValue, encoder);
       } else {
         this.writeIndexMap(indexValue.mapValue!, encoder);
         this.writeTruncationMarker(encoder);
@@ -192,6 +182,54 @@ export class FirestoreIndexValueWriter {
     encoder.writeString(stringIndexValue);
   }
 
+  private writeIndexDouble(
+    double: number,
+    encoder: DirectionalIndexByteEncoder
+  ): void {
+    if (isNaN(double)) {
+      this.writeValueTypeLabel(encoder, INDEX_TYPE_NAN);
+    } else {
+      this.writeValueTypeLabel(encoder, INDEX_TYPE_NUMBER);
+      if (isNegativeZero(double)) {
+        // -0.0, 0 and 0.0 are all considered the same
+        encoder.writeNumber(0.0);
+      } else {
+        encoder.writeNumber(double);
+      }
+    }
+  }
+
+  private writeIndexInt32(
+    mapValue: MapValue,
+    encoder: DirectionalIndexByteEncoder
+  ): void {
+    this.writeValueTypeLabel(encoder, INDEX_TYPE_NUMBER);
+    encoder.writeNumber(
+      normalizeNumber(mapValue.fields![RESERVED_INT32_KEY]!.integerValue!)
+    );
+  }
+
+  private writeIndexTimestamp(
+    timestamp: Timestamp,
+    encoder: DirectionalIndexByteEncoder
+  ): void {
+    this.writeValueTypeLabel(encoder, INDEX_TYPE_TIMESTAMP);
+    if (typeof timestamp === 'string') {
+      timestamp = normalizeTimestamp(timestamp);
+    }
+    encoder.writeString(`${timestamp.seconds || ''}`);
+    encoder.writeNumber(timestamp.nanos || 0);
+  }
+
+  private writeIndexGeoPoint(
+    geoPoint: LatLng,
+    encoder: DirectionalIndexByteEncoder
+  ): void {
+    this.writeValueTypeLabel(encoder, INDEX_TYPE_GEOPOINT);
+    encoder.writeNumber(geoPoint.latitude || 0);
+    encoder.writeNumber(geoPoint.longitude || 0);
+  }
+
   private writeIndexMap(
     mapIndexValue: MapValue,
     encoder: DirectionalIndexByteEncoder

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

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Quadruple } from '../util/quadruple';
+
+/**
+ * Represents a 128-bit decimal type in Firestore documents.
+ *
+ * @class Decimal128Value
+ */
+export class Decimal128Value {
+  readonly stringValue: string;
+  private value: Quadruple;
+
+  constructor(value: string) {
+    this.stringValue = value;
+    this.value = Quadruple.fromString(value);
+  }
+
+  /**
+   * Returns true if this `Decimal128Value` is equal to the provided one.
+   *
+   * @param other - The `Decimal128Value` to compare against.
+   * @return 'true' if this `Decimal128Value` is equal to the provided one.
+   */
+  isEqual(other: Decimal128Value): boolean {
+    // Firestore considers +0 and -0 to be equal.
+    if (this.value.isZero() && other.value.isZero()) {
+      return true;
+    }
+    return this.value.compareTo(other.value) === 0;
+  }
+}

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

@@ -55,7 +55,8 @@ import {
   RESERVED_BSON_TIMESTAMP_INCREMENT_KEY,
   RESERVED_BSON_BINARY_KEY,
   RESERVED_MIN_KEY,
-  RESERVED_MAX_KEY
+  RESERVED_MAX_KEY,
+  RESERVED_DECIMAL128_KEY
 } from '../model/values';
 import { newSerializer } from '../platform/serializer';
 import {
@@ -80,6 +81,7 @@ import { BsonObjectId } from './bson_object_Id';
 import { BsonTimestamp } from './bson_timestamp';
 import { Bytes } from './bytes';
 import { Firestore } from './database';
+import { Decimal128Value } from './decimal128_value';
 import { FieldPath } from './field_path';
 import { FieldValue } from './field_value';
 import { GeoPoint } from './geo_point';
@@ -936,6 +938,8 @@ function parseScalarValue(
     return parseBsonObjectId(value);
   } else if (value instanceof Int32Value) {
     return parseInt32Value(value);
+  } else if (value instanceof Decimal128Value) {
+    return parseDecimal128Value(value);
   } else if (value instanceof BsonTimestamp) {
     return parseBsonTimestamp(value);
   } else if (value instanceof BsonBinaryData) {
@@ -1045,6 +1049,17 @@ export function parseInt32Value(value: Int32Value): ProtoValue {
   return { mapValue };
 }
 
+export function parseDecimal128Value(value: Decimal128Value): ProtoValue {
+  const mapValue: ProtoMapValue = {
+    fields: {
+      [RESERVED_DECIMAL128_KEY]: {
+        stringValue: value.stringValue
+      }
+    }
+  };
+  return { mapValue };
+}
+
 export function parseBsonTimestamp(value: BsonTimestamp): ProtoValue {
   const mapValue: ProtoMapValue = {
     fields: {
@@ -1105,6 +1120,7 @@ function looksLikeJsonObject(input: unknown): boolean {
     !(input instanceof MinKey) &&
     !(input instanceof MaxKey) &&
     !(input instanceof Int32Value) &&
+    !(input instanceof Decimal128Value) &&
     !(input instanceof RegexValue) &&
     !(input instanceof BsonObjectId) &&
     !(input instanceof BsonTimestamp) &&

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

@@ -41,7 +41,10 @@ import {
   RESERVED_BSON_TIMESTAMP_KEY,
   RESERVED_BSON_TIMESTAMP_SECONDS_KEY,
   typeOrder,
-  VECTOR_MAP_VECTORS_KEY
+  VECTOR_MAP_VECTORS_KEY,
+  RESERVED_DECIMAL128_KEY,
+  isInt32Value,
+  isDecimal128Value
 } from '../model/values';
 import {
   ApiClientObjectMap,
@@ -61,6 +64,7 @@ import { forEach } from '../util/obj';
 import { BsonBinaryData } from './bson_binary_data';
 import { BsonObjectId } from './bson_object_Id';
 import { BsonTimestamp } from './bson_timestamp';
+import { Decimal128Value } from './decimal128_value';
 import { GeoPoint } from './geo_point';
 import { Int32Value } from './int32_value';
 import { MaxKey } from './max_key';
@@ -89,7 +93,11 @@ export abstract class AbstractUserDataWriter {
         return value.booleanValue!;
       case TypeOrder.NumberValue:
         if ('mapValue' in value) {
-          return this.convertToInt32Value(value.mapValue!);
+          if (isInt32Value(value)) {
+            return this.convertToInt32Value(value.mapValue!);
+          } else if (isDecimal128Value(value)) {
+            return this.convertToDecimal128Value(value.mapValue!);
+          }
         }
         return normalizeNumber(value.integerValue || value.doubleValue);
       case TypeOrder.TimestampValue:
@@ -215,6 +223,12 @@ export abstract class AbstractUserDataWriter {
     return new Int32Value(value);
   }
 
+  private convertToDecimal128Value(mapValue: ProtoMapValue): Decimal128Value {
+    const value =
+      mapValue!.fields?.[RESERVED_DECIMAL128_KEY]?.stringValue ?? '';
+    return new Decimal128Value(value);
+  }
+
   private convertGeoPoint(value: ProtoLatLng): GeoPoint {
     return new GeoPoint(
       normalizeNumber(value.latitude),

packages/firestore/src/model/transform_operation.ts

@@ -23,7 +23,7 @@ import { arrayEquals } from '../util/misc';
 
 import { normalizeNumber } from './normalize';
 import { serverTimestamp } from './server_timestamps';
-import { isArray, isInteger, isNumber, valueEquals } from './values';
+import { isArray, isIntegerValue, isNumber, valueEquals } from './values';
 
 /** Used to represent a field transform on a mutation. */
 export class TransformOperation {
@@ -205,7 +205,7 @@ export function applyNumericIncrementTransformOperationToLocalView(
     previousValue
   )!;
   const sum = asNumber(baseValue) + asNumber(transform.operand);
-  if (isInteger(baseValue) && isInteger(transform.operand)) {
+  if (isIntegerValue(baseValue) && isIntegerValue(transform.operand)) {
     return toInteger(sum);
   } else {
     return toDouble(transform.serializer, sum);