feat: Add Decimal128Value support (#6)

* feat: Add `Decimal128Value` support.

* Address feedback.

* Address feedback, and fix serialization.

* Address feedback.

* Add test for numerically equal numbers of different types.

* Format.

* Address feedback.

* Format.

* Update the Quadruple and QuadrupleBuilder with the latest updates from GOB.

* Fix the documentation lint CI failure.

Author: ehsannas

google-cloud-firestore/src/main/java/com/google/cloud/firestore/Decimal128Value.java

@@ -0,0 +1,75 @@
+/*
+ * 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.
+ */
+
+package com.google.cloud.firestore;
+
+import com.google.firestore.v1.MapValue;
+import java.io.Serializable;
+import java.util.Objects;
+import javax.annotation.Nonnull;
+
+/** Represents a 128-bit decimal type in Firestore documents. */
+public class Decimal128Value implements Serializable {
+  private static final long serialVersionUID = 8091951856970036899L;
+
+  public final String stringValue;
+  final Quadruple value;
+
+  public Decimal128Value(String val) {
+    this.stringValue = val;
+    this.value = Quadruple.fromString(val);
+  }
+
+  MapValue toProto() {
+    return UserDataConverter.encodeDecimal128Value(stringValue);
+  }
+
+  /**
+   * Returns true if this Decimal128Value is equal to the provided object.
+   *
+   * @param obj The object to compare against.
+   * @return Whether this Decimal128Value is equal to the provided object.
+   */
+  @Override
+  public boolean equals(Object obj) {
+    if (obj == null || getClass() != obj.getClass()) {
+      return false;
+    }
+
+    Quadruple lhs = this.value;
+    Quadruple rhs = ((Decimal128Value) obj).value;
+
+    // Firestore considers +0 and -0 to be equal, but `Quadruple.compareTo()` does not.
+    if (lhs.isZero() && rhs.isZero()) return true;
+
+    return this == obj || lhs.compareTo(rhs) == 0;
+  }
+
+  @Override
+  public int hashCode() {
+    // Since +0 and -0 are considered equal, they should have the same hash code.
+    Quadruple quadruple =
+        (this.value.compareTo(Quadruple.NEGATIVE_ZERO) == 0) ? Quadruple.POSITIVE_ZERO : this.value;
+
+    return Objects.hash(quadruple);
+  }
+
+  @Nonnull
+  @Override
+  public String toString() {
+    return "Decimal128Value{value=" + this.stringValue + "}";
+  }
+}

google-cloud-firestore/src/main/java/com/google/cloud/firestore/DocumentSnapshot.java

@@ -446,6 +446,18 @@ public Int32Value getInt32Value(@Nonnull String field) {
     return (Int32Value) get(field);
   }
 
+  /**
+   * Returns the value of the field as a 128-bit decimal.
+   *
+   * @param field The path to the field.
+   * @throws RuntimeException if the value is not a Decimal128Value.
+   * @return The value of the field.
+   */
+  @Nullable
+  public Decimal128Value getDecimal128Value(@Nonnull String field) {
+    return (Decimal128Value) get(field);
+  }
+
   /**
    * Returns the value of the field as a BsonObjectId.
    *

google-cloud-firestore/src/main/java/com/google/cloud/firestore/MapType.java

@@ -38,6 +38,9 @@ abstract class MapType {
   // For Int32 type
   static final String RESERVED_INT32_KEY = "__int__";
 
+  // For Decimal128 type.
+  static final String RESERVED_DECIMAL128_KEY = "__decimal128__";
+
   // For RequestTimestamp
   static final String RESERVED_BSON_TIMESTAMP_KEY = "__request_timestamp__";
   static final String RESERVED_BSON_TIMESTAMP_SECONDS_KEY = "seconds";

google-cloud-firestore/src/main/java/com/google/cloud/firestore/Order.java

@@ -90,6 +90,7 @@ static TypeOrder fromMapValue(MapValue mapValue) {
         return TypeOrder.MAX_KEY;
       case REGEX:
         return TypeOrder.REGEX;
+      case DECIMAL128:
       case INT32:
         return TypeOrder.NUMBER;
       case BSON_OBJECT_ID:
@@ -328,8 +329,7 @@ private long getIntegerValue(Value value) {
     if (value.hasIntegerValue()) {
       return value.getIntegerValue();
     }
-    if (value.hasMapValue()
-        && value.getMapValue().getFieldsMap().containsKey(MapType.RESERVED_INT32_KEY)) {
+    if (UserDataConverter.isInt32Value(value)) {
       return value.getMapValue().getFieldsMap().get(MapType.RESERVED_INT32_KEY).getIntegerValue();
     }
     throw new IllegalArgumentException("getIntegerValue was called on a non-integer value.");
@@ -343,6 +343,18 @@ private int compareNumbers(Value left, Value right) {
       return 1;
     }
 
+    // If either argument is Decimal128, we cast both to wider (128-bit) representation, and compare
+    // Quadruple values.
+    if (UserDataConverter.isDecimal128Value(left) || UserDataConverter.isDecimal128Value(right)) {
+      Quadruple leftQuadruple = convertNumberToQuadruple(left);
+      Quadruple rightQuadruple = convertNumberToQuadruple(right);
+
+      // Firestore considers +0 and -0 to be equal, but `Quadruple.compareTo()` does not.
+      if (leftQuadruple.isZero() && rightQuadruple.isZero()) return 0;
+
+      return leftQuadruple.compareTo(rightQuadruple);
+    }
+
     if (left.getValueTypeCase() == ValueTypeCase.DOUBLE_VALUE) {
       if (right.getValueTypeCase() == ValueTypeCase.DOUBLE_VALUE) {
         // left and right are both doubles.
@@ -391,7 +403,44 @@ private int compareBsonBinary(Value left, Value right) {
   }
 
   private boolean isNaN(Value value) {
-    return value.hasDoubleValue() && Double.isNaN(value.getDoubleValue());
+    if (value.hasDoubleValue() && Double.isNaN(value.getDoubleValue())) {
+      return true;
+    }
+
+    if (UserDataConverter.isDecimal128Value(value)) {
+      return value
+          .getMapValue()
+          .getFieldsMap()
+          .get(MapType.RESERVED_DECIMAL128_KEY)
+          .getStringValue()
+          .equals("NaN");
+    }
+
+    return false;
+  }
+
+  /**
+   * Converts the given number value to a Quadruple. Throws an exception if the value is not a
+   * number.
+   */
+  private Quadruple convertNumberToQuadruple(Value value) {
+    // Doubles
+    if (value.hasDoubleValue()) {
+      return Quadruple.fromDouble(value.getDoubleValue());
+    }
+
+    // 32-bit and 64-bit integers.
+    if (UserDataConverter.isIntegerValue(value)) {
+      return Quadruple.fromLong(getIntegerValue(value));
+    }
+
+    // Decimal128 numbers
+    if (UserDataConverter.isDecimal128Value(value)) {
+      return UserDataConverter.decodeDecimal128Value(value.getMapValue()).value;
+    }
+
+    throw new IllegalArgumentException(
+        "convertNumberToQuadruple was called on a non-numeric value.");
   }
 
   private int compareDoubles(double left, double right) {