feat(timestamp): create new date/timestamp classes

[callmehiphop]

Fixes #494
Fixes #526
Closes #529

• Tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)

---

Timestamps

This PR brings a new class for dealing with Cloud Spanner Timestamps. Previously we would return Date objects, but these were only good for millisecond precision. Since timestamps can come from the API in the form of either an ISO string or a protobuf timestamp, the class can handle either allowing users to easily use commit and read timestamps in queries, as well as result timestamps in snapshot bounds.

With ISO string.

const timestamp = Spanner.timestamp('2019-02-08T10:34:29.481145231Z');

With protobuf timestamp.

const [seconds, nanos] = process.hrtime();
const timestamp = Spanner.timestamp({seconds, nanos});

The Timestamp class extends the native Date class, so users can perform basic operations to the Timestamp if they choose.

timestamp.setNanoseconds(10);

console.log(timestamp.toISOString());
// => "2019-02-08T10:34:29.481145010Z"

It will also accept any single value that the Date object would accept in scenarios where micro-precision isn't important.

const timestamp = Spanner.timestamp(Date.now());

console.log(timestamp.toISOString());
// => "1985-06-03T22:37:14.312Z"

SpannerDate

To keep dealing with date times consistent, I've also refactored the SpannerDate class to extend the native Date class. It accepts any single value that the Date class would also accept.

const date = Spanner.date('6-3-1985');

console.log(date.toISOString());
// => "1985-06-03T00:00:00.000Z"

console.log(date.toJSON());
// => "1985-06-03"

[codecov]

Codecov Report

Merging #517 into master will increase coverage by 0.07%.
The diff coverage is 100%.

@@            Coverage Diff             @@
##           master     #517      +/-   ##
==========================================
+ Coverage   89.87%   89.95%   +0.07%     
==========================================
  Files          15       15              
  Lines        1432     1443      +11     
  Branches       42       42              
==========================================
+ Hits         1287     1298      +11     
  Misses        140      140              
  Partials        5        5

Impacted Files	Coverage Δ
src/index.ts	99.1% <100%> (+0.02%)	⬆️
src/codec.ts	97.65% <100%> (+0.17%)	⬆️
src/transaction.ts	98.82% <100%> (-0.01%)	⬇️
src/batch-transaction.ts	97.29% <100%> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update d712018...ae1dc67. Read the comment docs.

[callmehiphop]

@JustinBeckwith I'm not sure what your feelings are on my Timestamp class, but assuming it is something we would like to move forward with, I think it would be better suited for @google-cloud/common since we might be able to utilize it elsewhere (googleapis/nodejs-bigquery#6)

[JustinBeckwith]

I'm +1 to exposing nanosecond precision in a reusable way across our libs. Is common really the right place for it though? Thinking out loud:

1. I have a general aversion to the notion of a common module, as it usually turns into a dumping ground. Though I get for many of our modules it makes sense.
2. It sounds like this could be of general use to the rest of the node community. Maybe it makes sense to have our own individual npm module just for nanosecond precision dates?

Adding @ofrobots and @googleapis/node-team as they will know if there's already something in the ecosystem we should be using, or if what you got here is of enough value to the community to spin out :)

[JustinBeckwith]

Oh also @callmehiphop silly question - is this a breaking change?

[callmehiphop]

Yeah, technically it is, I hadn't released our latest major breaking change yet so my plan was to ship this with it.

[ofrobots]

How does this compare to something like nano-date?

[JustinBeckwith]

😨

[ofrobots]

My preference would be a new public module for this. This seems like a feature anybody could take advantage of. IMHO there is no reason to sequester it into the common module. Two ways I see this can happen are:

1. See if we can contribute to the existing nano-date module.
2. Create a new module (date-nano?)

[callmehiphop]

@stephenplusplus I made some changes to the SpannerDate class per #526 if you wouldn't mind giving it another go through D: