DateValue is module-private, so this is only callable from parsePrecisionDate — the
one way in — without needing a private constructor and a factory to say so.
Render for a human reader.
A date renders bare — no time, and no zone, because a date is the same date everywhere. So
withZone asks for the zone rather than commanding it, and renderZone is ignored.
renderZone is required rather than defaulted: a value with no zone of its own cannot be
placed without one, and defaulting silently would hide a caller that forgot to thread it. For
the same reason an invalid renderZone throws rather than falling back — but only when it is
actually needed. A date renders bare, so it is never consulted, and a nonsense zone alongside a
date is ignored.
The instant at the start of this date, in zone.
Named so that inventing a time for a date is a visible choice. This is what
convertToUTCDate's timeStr || "00:00:00" did implicitly, upstream of everything that then
had to guess whether the midnight it saw was real.
The instant this represents, for sorting and for storage.
null for a date: a calendar date is not an instant, and picking one for it is a decision the
caller has to make out loud — see startOfDay. Silently choosing midnight is
how precision gets destroyed at the point of storage.
YYYY-MM-DD, for a date column. null for unparsed input.
zone is which calendar the date is read off, and is required for the same reason the other
conversions require one: an instant falls on different days in different zones, so a zoneless
answer would be the UTC day and silently wrong for every facility that is not on it. Ignored
for a value that is already a date, which has no zone to be read in.
ISO 8601 with an offset, for a timestamptz column. null for a date — see toDate.
A date that carries its own precision.
A date arrives as one of three things — a calendar date, a wall clock with no zone, or an instant — and a JavaScript
Datecan only be the third. Coercing the first two into it forces a zone to be guessed, and readers downstream then try to recover the original intent by inspecting the string's shape or noticing the instant landed on UTC midnight. This keeps the distinction, so nothing has to guess.Precisionnames what travels with the value, and the guarantees around it are strict rather than loose: it will not invent a time for a date, will not default a zone, and will not yield an instant unless asked out loud — see startOfDay.Two features look unusual for a date type, and both are concessions to input we do not control rather than anything domain-specific.
"bare"precision preserves a value that matched no known format instead of discarding it. The{ date, time }input form exists because some sources store a date and a time in separate fields — LightningStep's split columns are the case that motivated it.