Implement Timestamp.valueOf() (#2662)

This enables comparison of Timestamp objects using the arithmetic comparison operators, such as < and >.

Fixes: #2632

Author: dconeybe

config/tsconfig.base.json

@@ -14,6 +14,7 @@
       "es2015.symbol.wellknown",
       "es2015.core",
       "es2017.object",
+      "es2017.string",
     ],
     "module": "ES2015",
     "moduleResolution": "node",

packages/firebase/index.d.ts

@@ -7521,6 +7521,12 @@ declare namespace firebase.firestore {
      * @return true if this `Timestamp` is equal to the provided one.
      */
     isEqual(other: Timestamp): boolean;
+
+   /**
+    * Converts this object to a primitive string, which allows Timestamp objects to be compared
+    * using the `>`, `<=`, `>=` and `>` operators.
+    */
+    valueOf(): string;
   }
 
   /**

packages/firestore-types/index.d.ts

@@ -113,6 +113,8 @@ export class Timestamp {
   toMillis(): number;
 
   isEqual(other: Timestamp): boolean;
+
+  valueOf(): string;
 }
 
 export class Blob {

packages/firestore/CHANGELOG.md

@@ -1,4 +1,7 @@
 # Unreleased
+- [feature] Implemented `Timestamp.valueOf()` so that `Timestamp` objects can be
+  compared for relative ordering using the JavaScript arithmetic comparison
+  operators (#2632).
 - [fixed] Fixed an issue where auth credentials were not respected in Cordova
   environments (#2626).
 - [fixed] Fixed a performance regression introduced by the addition of

packages/firestore/externs.json

@@ -10,6 +10,7 @@
     "node_modules/typescript/lib/lib.es2015.symbol.wellknown.d.ts",
     "node_modules/typescript/lib/lib.es2015.core.d.ts",
     "node_modules/typescript/lib/lib.es2017.object.d.ts",
+    "node_modules/typescript/lib/lib.es2017.string.d.ts",
     "packages/app-types/index.d.ts",
     "packages/app-types/private.d.ts",
     "packages/auth-interop-types/index.d.ts",

packages/firestore/src/api/timestamp.ts

@@ -18,6 +18,9 @@
 import { Code, FirestoreError } from '../util/error';
 import { primitiveComparator } from '../util/misc';
 
+// The earlist date supported by Firestore timestamps (0001-01-01T00:00:00Z).
+const MIN_SECONDS = -62135596800;
+
 export class Timestamp {
   static now(): Timestamp {
     return Timestamp.fromMillis(Date.now());
@@ -46,8 +49,7 @@ export class Timestamp {
         'Timestamp nanoseconds out of range: ' + nanoseconds
       );
     }
-    // Midnight at the beginning of 1/1/1 is the earliest Firestore supports.
-    if (seconds < -62135596800) {
+    if (seconds < MIN_SECONDS) {
       throw new FirestoreError(
         Code.INVALID_ARGUMENT,
         'Timestamp seconds out of range: ' + seconds
@@ -92,4 +94,18 @@ export class Timestamp {
       ')'
     );
   }
+
+  valueOf(): string {
+    // This method returns a string of the form <seconds>.<nanoseconds> where <seconds> is
+    // translated to have a non-negative value and both <seconds> and <nanoseconds> are left-padded
+    // with zeroes to be a consistent length. Strings with this format then have a lexiographical
+    // ordering that matches the expected ordering. The <seconds> translation is done to avoid
+    // having a leading negative sign (i.e. a leading '-' character) in its string representation,
+    // which would affect its lexiographical ordering.
+    const adjustedSeconds = this.seconds - MIN_SECONDS;
+    // Note: Up to 12 decimal digits are required to represent all valid 'seconds' values.
+    const formattedSeconds = String(adjustedSeconds).padStart(12, '0');
+    const formattedNanoseconds = String(this.nanoseconds).padStart(9, '0');
+    return formattedSeconds + '.' + formattedNanoseconds;
+  }
 }

packages/firestore/test/unit/api/timestamp.test.ts

@@ -16,12 +16,55 @@
  */
 
 import { expect } from 'chai';
+import { Code } from '../../../src/util/error';
 import { Timestamp } from '../../../src/api/timestamp';
 import { addEqualityMatcher } from '../../util/equality_matcher';
 
 describe('Timestamp', () => {
   addEqualityMatcher();
 
+  it('constructor should validate the "seconds" argument and store it', () => {
+    expect(new Timestamp(1, 0)).to.have.property('seconds', 1);
+    expect(new Timestamp(-62135596800, 0)).to.have.property(
+      'seconds',
+      -62135596800
+    );
+    expect(new Timestamp(253402300799, 0)).to.have.property(
+      'seconds',
+      253402300799
+    );
+
+    expect(() => {
+      new Timestamp(-62135596801, 0);
+    })
+      .to.throw(/seconds/)
+      .with.property('code', Code.INVALID_ARGUMENT);
+
+    expect(() => {
+      new Timestamp(253402300800, 0);
+    })
+      .to.throw(/seconds/)
+      .with.property('code', Code.INVALID_ARGUMENT);
+  });
+
+  it('constructor should validate the "nanoseconds" argument and store it', () => {
+    expect(new Timestamp(0, 1)).to.have.property('nanoseconds', 1);
+    expect(new Timestamp(0, 0)).to.have.property('nanoseconds', 0);
+    expect(new Timestamp(0, 1e9 - 1)).to.have.property('nanoseconds', 1e9 - 1);
+
+    expect(() => {
+      new Timestamp(0, -1);
+    })
+      .to.throw(/nanoseconds/)
+      .with.property('code', Code.INVALID_ARGUMENT);
+
+    expect(() => {
+      new Timestamp(0, 1e9);
+    })
+      .to.throw(/nanoseconds/)
+      .with.property('code', Code.INVALID_ARGUMENT);
+  });
+
   it('fromDate', () => {
     expect(Timestamp.fromDate(new Date(1488872578916))).to.deep.equal({
       seconds: 1488872578,
@@ -33,4 +76,60 @@ describe('Timestamp', () => {
       nanoseconds: 750000000
     });
   });
+
+  it('valueOf', () => {
+    expect(new Timestamp(-62135596677, 456).valueOf()).to.equal(
+      '000000000123.000000456'
+    );
+    expect(new Timestamp(-62135596800, 0).valueOf()).to.equal(
+      '000000000000.000000000'
+    );
+    expect(new Timestamp(253402300799, 1e9 - 1).valueOf()).to.equal(
+      '315537897599.999999999'
+    );
+  });
+
+  it('arithmetic comparison of a Timestamp object to itself', () => {
+    const timestamp = new Timestamp(1, 1);
+    expect(timestamp < timestamp).to.be.false;
+    expect(timestamp <= timestamp).to.be.true;
+    expect(timestamp > timestamp).to.be.false;
+    expect(timestamp >= timestamp).to.be.true;
+  });
+
+  it('arithmetic comparison of equivalent, but distinct, Timestamp objects', () => {
+    const t1 = new Timestamp(1, 1);
+    const t2 = new Timestamp(1, 1);
+    expect(t1 < t2).to.be.false;
+    expect(t1 <= t2).to.be.true;
+    expect(t1 > t2).to.be.false;
+    expect(t1 >= t2).to.be.true;
+  });
+
+  it('arithmetic comparison of Timestamp objects whose nanoseconds differ', () => {
+    const t1 = new Timestamp(1, 1);
+    const t2 = new Timestamp(1, 2);
+    expect(t1 < t2).to.be.true;
+    expect(t1 <= t2).to.be.true;
+    expect(t1 > t2).to.be.false;
+    expect(t1 >= t2).to.be.false;
+  });
+
+  it('arithmetic comparison of Timestamp objects whose seconds differ', () => {
+    const t1 = new Timestamp(100, 0);
+    const t2 = new Timestamp(200, 0);
+    expect(t1 < t2).to.be.true;
+    expect(t1 <= t2).to.be.true;
+    expect(t1 > t2).to.be.false;
+    expect(t1 >= t2).to.be.false;
+  });
+
+  it('arithmetic comparison of the smallest and largest Timestamp objects', () => {
+    const t1 = new Timestamp(-62135596800, 0);
+    const t2 = new Timestamp(253402300799, 999999999);
+    expect(t1 < t2).to.be.true;
+    expect(t1 <= t2).to.be.true;
+    expect(t1 > t2).to.be.false;
+    expect(t1 >= t2).to.be.false;
+  });
 });