A big step in the right direction, but I still don't like the API, here's why:
Especially in JavaScript where I often share a lot of code between the client and the server and therefore also transfer data between them, I like to strictly separate data from logic. What i mean by this is that all my data is plain JSON and no class instances or objects that have function properties, so that I can serialize/deserialize it easily.
This is not the case for Temporal objects. Also, the temporal objects have functions on them, which, granted, makes it convenient to use, but a pain to pass it over the wire.
I'd clearly prefer a set of pure functions, into which I can pass data-only temporal objects, quite a bit like date-fns did it.
This was an intentional design decision. We wanted to make sure all the temporal types could be serialize/deserializable, but as you mentioned, you couldn't implicitly go back to the object you started with as JSON.parse doesn't support that.
Instead the onus is on the developer to re-create the correct object they need on the other side. I don't believe this is problematic because if you know you're sending a Date, DateTime, MonthDay, YearMonth type from one side, then you know what type to rebuild from the ISO string on the other. Having it be automatic could be an issue if you receive unexpected values and are now dealing with the wrong types.
There are no date, time or datetime types in JSON, so you'll have to serialise it to a string or an int anyway, and then when deserialising you'll need to identify explicitly which values should be parsed as dates.
Well, you could still have a compound object in JSON, that is output by the Temporal API, and which given as input is guaranteed to result in an equal object it was created/serialized from. This compound object must contain all required infos about timezones and such stuff.
.... we're talking about serialization here. "convert to a raw string" is sort of the name of the game.
It's a string in a well specified string format. That's typically what you want for serialization.
Temporal is typed; but its serialization helpers aren't, because there's no single way to talk about types across serialization. That's functionality a serialization library may choose to provide, but can't really be designed into the language.
You realize that JSON isn't just for JavaScript to JavaScript communication, right? Even if you had a magical format (which doesn't make sense and is a bad idea to attempt to auto-deserialize), it wouldn't work across languages.
If you really want that, it's not very hard to design a pair of functions `mySerialize()`, `myDeserialize()` that's a thin wrapper over `JSON.parse`.
This is a real pain point and I run into the same tension in systems where data crosses serialization boundaries constantly. The prototype-stripping problem you're describing with JSON.parse/stringify is a specific case of a more general issue: rich domain objects don't survive wire transfer without a reconstitution step.
That said, I think the Temporal team made the right call here. Date-time logic is one of those domains where the "bag of data plus free functions" approach leads to subtle bugs because callers forget to pass the right context (calendar system, timezone) to the right function. Binding the operations to the object means the type system can enforce that a PlainDate never accidentally gets treated as a ZonedDateTime. date-fns is great but it can't give you that.
The serialization issue is solvable at the boundary. If you're using tRPC or similar, a thin transform layer that calls Temporal.Whatever.from() on the way in and .toString() on the way out is pretty minimal overhead. Same pattern people use with Decimal types or any value object that doesn't roundtrip through JSON natively. Annoying, sure, but the alternative is giving up the type safety that makes the API worth having in the first place.
Sounds like we need an extended JSON with the express intent of conveying common extended values and rich objects: DateTime instants (with calendar system & timezone), Decimal, BigInt, etc.
I disagree: this is not unlike including the schema in the JSON itself. This should be handled by the apps themselves, since they would have to know what the keys mean regardless.
If you do want the interchange format to be the one deserializing into specific runtime data structures, use YAML. YAML's tag syntax allows you to run arbitrary code inside YAML, which can be used for what you want.
I'm not talking about something arbitrarily extensible or compound values like vectors or lat/lon. Just a few more common data types -- primitive-like values that frequently need to be passed around.
This would probably best exist as a well-known wrapper around JSON itself.
there are a zillion of these "json pro" kind of things: superjson, devalue, capnweb, all with slightly different ideas about how to lower high-level semantics to json's available types. it's so easy to do this kind of thing, its a real https://xkcd.com/927/ situation.
CBOR (Concise Binary Object Representation) has JSON-like semantics with type extension support; with built in type extensions its much easier to get some agreement about registering certain magic type IDs to mean certain things. for example from a random google search for "cbor datetime" https://j-richter.github.io/CBOR/date.html; there's an IANA registry of type IDs: https://www.iana.org/assignments/cbor-tags/cbor-tags.xhtml
I think a more practical and compatible approach is to keep json as it is, and use a side channel (e.g. an openapi spec) to convey metadata.
Then it is up to the client to decide that a date returned as a string is a date or string, or to create a specific class instead of a generic object
For most situations, I deal with this by keeping dates as strings throughout the app, not objects. They get read from the db as strings, passed around as strings. If I need datetime calculations, I use the language's datetime objects to do it and convert right back to string. Display formatting for users happens at the last moment, in the template.
No-one seems to like this style, but I find it much simpler than converting on db read/write and passing datetime objects around.
It's not that much about type safety. Since TypeScript uses duck typing, a DateTime could not be used as a ZonedDateTime because it'd lack the "timezone" property. The other way around, though, it would work. But I wouldn't even mind that, honestly.
The real drawback of the functional approach is UX, because it's harder to code and you don't get nice auto-complete.
Updating JSON.parse() to automatically create Temporal objects (from what shape of JSON value?) without a custom reviver would be a step too far, in my opinion.
This is effectively no different from Date:
serialize: date.toJSON()
deserialize: new Date(jsonDate)
Don’t JavaScript Date instances have the same problem? Date implements toJSON, but when parsing JSON you’ll have to manually identify which string values represent Dates and convert them back to Date instances. The exact same is true of Temporal (e.g. Instant).
And as far as I know, date-fns deals with native Date instances, not “data-only objects.”
The serialization thing is real but I don't think OOP vs functional is the actual issue here. JSON has no date type, period. You JSON.stringify a Date, get an ISO string, and hope whoever's parsing remembers to reconstruct it. Temporal doesn't fix that part, but at least when you do reconstruct you're saying "this is a ZonedDateTime" vs "this is an Instant" instead of everything being one ambiguous Date object.
That's not what I mean. Even though it is serializable, it's still not the same when you serialize/deserialize it.
For example `JSON.parse(JSON.stringify(Temporal.PlainYearMonth.from({year:2026,month:1}))).subtract({ years: 1})` won't work, because it misses the prototype and is no longer an instance of Temporal.PlainYearMonth.
You would need to use the `reviver` parameter of `JSON.parse()` to revive your date strings to Temporal objects. As others have said, it's a simple `Temporal.from()`
Depending on your needs (i.e. how you would otherwise use your output jspn), using the reviver can have a significant impact on performance. JSON.parse itself is hyper-optimized. At the company I work we used the reviver for almost exactly this, but profiling showed that using the reviver had enormous impact on performance. We cut it out, and won in the seconds of performance for some large json's.
The main advantage of json is that it’s human readable and writable. Beyond that, it has no notion of user created data types so anyone using it has to do custom unmarshalling to get a type apart from sting, number, dict and list.
Even if you don't explicitly provide a schema, you implicitly still have one. The recipient needs to know what you're sending them. Unless maybe you want to start parsing JSON payloads with an LLM.
Which is why many developers only use JavaScript Object Notation for JavaScript objects, and only JavaScript objects that can losslessly be written as JSON. Which this proposal explicitly does not support.
> For example `JSON.parse(JSON.stringify(Temporal.PlainYearMonth.from({year:2026,month:1}))).subtract({ years: 1})` won't work, because it misses the prototype and is no longer an instance of Temporal.PlainYearMonth.
I don't know if I'm missing something, but that's exactly how I'd expect it to compose. Does the following do what you wanted your snippet to do?
JSON.stringify and JSON.parse should not be viewed as strict inverses of each other. `JSON.parse(JSON.stringify(x)) = x` is only true for a for a small category of values. That category is even smaller if parsing is happening in a different place than stringification because JSON doesn't specify runtime characteristics. This can lead to things like JSON parsing incorrect in JS because they're too large for JS to represent as a number.
The JSON types are string, number, boolean, null, object and array. So how could the suggested code possibly work? Do you want JSON.parse to do arbitrary code execution like Python's pickle?
I'm with you on this. I worked on a big Temporal project briefly and I was really turned off by how much of the codebase was just rote mapping properties from one layer to the next.
> What i mean by this is that all my data is plain JSON and no class instances or objects that have function properties, so that I can serialize/deserialize it easily.
This is known as the "primitive obsession" anti-pattern.
> Especially in JavaScript where I often share a lot of code between the client and the server and therefore also transfer data between them, I like to strictly separate data from logic
Which makes me wonder how it'll look like when interfacing with WASM. Better than Date?
yes, sure. probably there will even pop up a functional wrapper around the temporal API occasionally. But would've been nice if it was like this from the start.
This is not the case for Temporal objects. Also, the temporal objects have functions on them, which, granted, makes it convenient to use, but a pain to pass it over the wire.
I'd clearly prefer a set of pure functions, into which I can pass data-only temporal objects, quite a bit like date-fns did it.