Skip to content

Temporal support - #52

Open
Gouvernathor wants to merge 27 commits into
squirrelchat:mistressfrom
Gouvernathor:temporal
Open

Temporal support#52
Gouvernathor wants to merge 27 commits into
squirrelchat:mistressfrom
Gouvernathor:temporal

Conversation

@Gouvernathor

@Gouvernathor Gouvernathor commented Mar 28, 2026

Copy link
Copy Markdown
Contributor

This is not meant to be merged in the short term.

When it comes to parsing, I made the choice of never generating Instant objects and always ZonedDateTime objects (in UTC if needed).
That decision could be reversed by changing the contents of the if (offset.toLowerCase() == "z") in temporal.ts.
Parsing will never generate Temporal objects unless temporal:true is passed, in which case it will never generate a TomlDate.

Some differences when it comes to serializing can be found by comparing the "stringifies dates properly" and "stringifies Temporal values properly" tests. I consider these differences to be acceptable (mainly, not showing a decimal part after the seconds when there is no nanoseconds).
In accordance to TOML spec, supported types are Instant, PlainDate, PlainDateTime, PlainTime, and ZonedDateTime.
Duration, PlainMonthDay and PlainYearMonth are not supported.
Instant will be serialized but then parsed as a ZonedDateTime (see previous section).
ZonedDateTime will only keep the offset information, and lose the time zone and calendar identities.


This code imports a polyfill as a test dependency, which I think is acceptable, but it also imports the polyfill in the main code which is evidently not OK.
After removing these imports, and assuming typescript is ignored, the parsing part won't error out unless the option is toggled to true, as all direct accesses to the Temporal object are either in typescript expressions or in the parseTemporal function body.

The serializing part will error out, as it tests instanceof with runtime access to the Temporal object, but it could be solved by something like the following code:

let Temporal = {};
if (globalThis.Temporal) {
    Temporal = globalThis.Temporal
} else {
    Temporal.Instant = Temporal.PlainDate = Temporal.PlainDateTime = Temporal.PlainTime = Temporal.ZonedDateTime = class {}
}

In other news, the exposed types for parsing become a mess, due to the overlapping combinations of "does it include bigints ?", "does it include TomlDate ?" and "does it include Temporal types ?".
There are now 11 types which is obviously too many to expose in my view, due to forwards-compatibility.
I had introduced a generic version of the TomlValue and TomlTable types, generic in the supported primitives, which was removed I believe for simplicity. Given the multiplicity of types here, I think it should be reintroduced.

@cyyynthia

Copy link
Copy Markdown
Member

When it comes to parsing, I made the choice of never generating Instant objects and always ZonedDateTime objects

That's good. It's a bit unfortunate that OffsetDateTime was dropped in favor of a hybrid ZonedDateTime that does both offset and properly timezoned dates in the Temporal API imho, since the two are very different, but oh well.

I consider [the differences when it comes to serializing] to be acceptable (mainly, not showing a decimal part after the seconds when there is no nanoseconds).

Sounds good to me too.

This code imports a polyfill as a test dependency

Given that the lib will wait for Temporal to land in an even-supported Node version, the polyfill will be temporary in all cases since we'll be able to drop it from the tests and rely on platform support.

In other news, the exposed types for parsing become a mess

Yeah that's always the catch when making precise types, exponential growth 😔

@cyyynthia cyyynthia linked an issue Mar 28, 2026 that may be closed by this pull request
@Gouvernathor
Gouvernathor marked this pull request as ready for review August 21, 2026 03:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support the Temporal API for parsing

2 participants