[discussion] epoch vs relative distance in ms as the value to format

[caridy]

This is related to #4, and we should make a decision as soon as possible because this will affect various open issues.

[caridy]

My position is:

• format() is a low level API
• diffing againstnow, or whatever their anchoring value is, seems to be trivial and does not require any extra data, can be done by users before calling format()

[zbraniecki]

Unfortunately, I don't think that this is an acceptable consensus for us.

@jswalden in the review of my patch for SM said:

If execution is slow enough -- maybe the OS pages in another process to run for awhile or something -- this test can fail.  (And so for all the others, with progressively less likelihood.)

It seems to me that RTF needs to have a mode of operation that takes *two* time arguments.  One for the presumed current time, and one for the historical time being talked about.  It seems fine for the default to be to the current moment, but there needs to be a way to override that.  (For a real-world use case, consider a web-based version of Oregon Trail, that displays a journal of things that have happened to you, and wants to say that -- as of some particular time in the game -- eight days prior you tried to ford the river and your oxen died.)

Spec change/spec issue, please come back after you've addressed it there and then in a new patch.  :-)

Originally, my position was that an optional "root" for now would be enough, like:

let rtf = new Intl.RelativeTimeformat('en', {
  now: Date.now()
});
rtf.format(Date.now() - 1000);

but the longer I think about how people will use it, and what are the traps we set up for them, the more I realize that by attempting to reduce the cognitive load and let them "just pass the date" we actually set them for failure for two reasons:

1. I believe that most UIs that will use it will do more than just display a string. They may alter the UI depending on the delta, or have a special now string.

In that case, asking the user to take a Date.now to add the delta and pass it for us, so that we substract Date.now again, seems like a bad API design.

2. By removing the need to pass now we remove the opportunity for the user to realize that their delta is against some now. That's disguising something that should not be disguised because it actually affects the UI.
   If the user is using react, to build a view, that he then passes from server side to client-side for display, then realizing that there will be time between executing the call to RTF, calculating the value, and then before the screen will be displayed, is actually important for the quality of the product.
   And users generally, for good reasons, are not taught to think about the time between when they call a function and when it is computed and when the output is displayed. So in this case, I'd say we should avoid creating a space for a bug that might be very had to find.

Thus, my proposal is to just take delta in milliseconds as an argument to format.

[rxaviers]

@caridy can correct me if I'm wrong, but taking the delta in milliseconds as the argument for rtf.format was the direction we were inclined to as well when we talked about it days ago.

PS: Note you can't use the below, because considering we wanted to pass now in the API, this should happen when calling the formatter (i.e., rtf.format), not when instantiating it. Note you can create rtf and then call rtf.format later.

let rtf = new Intl.RelativeTimeformat('en', {
  now: Date.now()
});

[rxaviers]

@caridy can correct me if I'm wrong, but taking the delta in milliseconds as the argument for rtf.format was the direction we were inclined to as well when we talked about it days ago.

Another point we discussed is: taking delta in ms, what should happen if developer passes a date as input: should we type cast it into a number? That would result in an unexpected result and we were considering throwing an exception in that case... Thoughts?

[zbraniecki]

Yup, let's throw an exception. Date casted to number as delta ms is probably never what the dev wanted to do.

[caridy]

Thus, my proposal is to just take delta in milliseconds as an argument to format.

That's precisely my position @zbraniecki. As I mentioned before, doing the delta calculation in user-land is trivial, they can do it. By removing the now and the date from the picture, we can clean the API considerable.