Editorial: Introduce Record for relativeTo

[ptomato]

After #2826 lands, consider introducing a relativeTo Record in the spec, to show implementations how relativeTo can be handled in a more statically-typed way.

There might be an opportunity to give a formal shape to "relativeTo". Kevin Ness brought this up in the last meeting regarding difficulty in statically typed languages.

type RelativeTo = {
  plainDateTime: Temporal.PlainDateTime
  timeZone: Temporal.TimeZone // or null if UTC?
}

function normalizeRelativeTo(input): RelativeTo {
  if (input instanceof Temporal.ZonedDateTime) {
    return {
      plainDateTime: input.toPlainDateTime(),
      timeZone: input.getTimeZone(),
    }
  } else if (input instanceof Temporal.PlainDate) {
    return {
      plainDateTime: input.toPlainDateTime(), // gives 00:00:00
      timeZone: new Temporal.TimeZone('UTC')
    }
  }
}

/*
Adds a Duration to the relativeTo and returns an epoch nanoseconds
This function is only ever called with time units zeroed out!
(It's just the way our nudging/bubbling system works during relative-rounding)
Thus, we don't need to worry about the intricacies of *when* time units are
added in PlainDateTime vs ZonedDateTime.

A utility function is nice because we don't need to call GetUTCEpochNanoseconds and
GetInstantFor conditionally each time.
*/
function addToRelativeTo(relativeTo: RelativeTo, duration): bigint {
  return relativeTo.timeZone.getInstantFor(
    relativeTo.plainDateTime.add(duration)
  ).epochNanoseconds
}

Originally posted by @arshaw in #2758 (review)

[ptomato]

Also use this to eliminate UnbalanceDateDurationRelative as suggested in that review.

[ptomato]

@arshaw I might need some input from you on this. What do you do in the fullcalendar polyfill if the ZonedDateTime passed as relativeTo has an ambiguous wall-clock time? You can convert it to the PlainDateTime in the RelativeTo struct, but then you couldn't convert it back.

[arshaw]

Hi @ptomato, I devised this during the Duration rounding refactor, but I haven't actually implemented this RelativeTo record stuff in the fullcalendar polyfill yet. I can do that and report back. Will be sometime in Oct probably.

I'm not quite sure what you mean though. I'm sort-of converting it back (to an epochNanoseconds) in the addToRelativeTo function above.

[ptomato]

@arshaw But if the original ZonedDateTime was, say, 2023-11-05T01:30-05:00[America/New_York], it becomes 2023-11-05T01:30 in the RelativeTo record, then when you go to convert it back to epochNanoseconds in addRelativeTo ... there are two possible epochNanoseconds.

[ptomato]

Oh! Does it not matter because you never need the original ZonedDateTime back? You only add or subtract date duration units, and so if you land on an ambiguous wall clock time you actually want the disambiguation: 'compatible' behaviour...

[arshaw]

@ptomato yes exactly

[ptomato]

I've written up a draft of this refactor in https://github.com/tc39/proposal-temporal/compare/main...2837-relativeto-record?expand=1

It turns out we do need the original ZonedDateTime in only one place: the check at the start of DifferenceZonedDateTimeWithRounding where we return difference-of-instants if largestUnit is a time unit. I don't have a solution for that yet.

It's also slightly annoying, but doable, that you have to compute the sign separately and pass it in to DifferenceZonedDateTimeWithRounding.

Other than those, I think this works pretty well.

[arshaw]

Hey @ptomato, that's a great start, though if we can't figure out those two issues, it probably creates more problems than it solves. I want to take a more in-depth look at all this, and potentially devise a way to avoid passing a relativeTo into DifferenceZonedDateTimeWithRounding altogether (and possibly refactor-away DifferenceZonedDateTimeWithRounding somehow, as it's no longer really diffing two zoneddatetimes anymore) but I won't have time before the meeting. Hopefully shortly after.