fabon's blog

The difference between `gregory` and `iso8601` calendars in ECMAScript

2026-09-13T19:15:00Z

Temporal and Intl.DateTimeFormat can handle various calendars, such as the Gregorian calendar with Japanese regnal eras, East Asian lunisolar calendars, Hijri calendars, and the Hebrew calendar. They also support the iso8601 and gregory calendars, both of which represent the proleptic Gregorian calendar. So, what is the difference between iso8601 and gregory?

The short answer is: gregory is the real-world Gregorian calendar in the context of internationalization, while iso8601 is an "artificial" and "culturally neutral" Gregorian calendar modeled for computer usage.

`iso8601` as a calendar

ISO 8601 is the origin of standard date and time formats for data exchange. However, the standard itself is not suitable for practical use as a reference: we cannot obtain the ISO standard document for free, the syntax definition is ambiguous, and it defines various formats that almost no one uses. The term "ISO 8601 format" roughly refers to formats defined in RFC 3339 and its successors.

https://www.rfc-editor.org/info/rfc3339/

https://ijmacd.github.io/rfc3339-iso8601/

The ISO 8601 format is based on the Gregorian calendar with astronomical year numbering (year 0 for 1 BC), so it does not depend on the concept of eras. ISO 8601 also defines formats based on weeks and days of the week. The start of the week is Monday, and days of the week are 1-indexed (1 for Monday, 7 for Sunday). The first week of the year is defined as the week that contains 4 January.

The calendar ID iso8601 comes from CLDR. I suspect it originally meant the Gregorian calendar with ISO 8601 week numbering, in contrast to gregory, which referred to the Gregorian calendar with locale-dependent week numbering.

https://github.com/unicode-org/cldr/commit/dd46a84dabf145428cdd7fbf9a350368f3055d78

As an aside, TC39 and the Unicode Consortium concluded that there was insufficient evidence for locale-dependent week numbering systems other than ISO 8601. Across the world, people who care about week numbers usually expect the ISO 8601 definition. While some people may use different week numbering systems for specific use cases, it is generally not something that should be determined by locale.

https://github.com/tc39/proposal-intl-locale-info/issues/86

`iso8601` as a culturally neutral data model

In ECMAScript, the iso8601 calendar is defined as a culturally neutral calendar, while gregory is a Gregorian calendar closely tied to cultural contexts. I am not sure when this distinction was first established, but we can see many discussions and decisions that assume it in the meeting notes of TC39 and ECMA-402 (TG2), issues on date-related proposals, and so on.

Of course, the iso8601 calendar is based on the Gregorian calendar and anno Domini, so it inevitably has European and Christian origins. That being said, it is obvious that the ISO 8601 format and the calendar model behind it are widely used, even in non-Western and non-Christian regions. Therefore, I believe that it is practical and reasonable to treat the iso8601 calendar as neutral, even though it is not completely neutral.

`Intl.DateTimeFormat`

We can specify the calendar in Intl.DateTimeFormat. If no calendar is specified, Intl.DateTimeFormat selects the default calendar for the locale (gregory in most cases). gregory represents the standard Gregorian calendar used in the real world, so it includes the concept of eras, such as BC/BCE and AD/CE. You can display the era using the era option.

const formatter = new Intl.DateTimeFormat("en-US");
formatter.format(Temporal.PlainDate.from("2026-06-01"));
// returns a date format used in the US, such as "6/1/2026"
formatter.resolvedOptions().calendar;
// "gregory"

Temporal.PlainDate.from("-000020-01-01").toLocaleString("en-US", {
  era: "short",
  year: "numeric",
  month: "long",
  day: "numeric",
}); // "January 1, 21 BC"

You can format dates with the iso8601 calendar via Intl.DateTimeFormat, since the API supports all calendars specified in ECMAScript. However, there is no specification or consensus on what it means to "format dates in the iso8601 calendar". JavaScript engines tend to choose a pattern similar to the ISO 8601 format, but in general, the result is neither a machine-readable ISO 8601 string nor a natural human-readable format (use Temporal if you want the former). Specifying formatting options that contradict the ISO 8601 format is semantically contradictory, and the output can even be broken in such cases:

// A format similar to ISO 8601 with English month names (semantically conflicting)
new Date().toLocaleString("en-u-ca-iso8601", {
  year: "numeric",
  month: "long",
});
// "2026 July" in Chrome
// "2026 " in Node.js (!!!)

https://github.com/tc39/ecma402/issues/1036

https://github.com/nodejs/node/issues/63041

Because Intl.DateTimeFormat is designed for internationalization and produces localized output for humans, we should generally use gregory here rather than iso8601. We do not use the iso8601 calendar in daily life.

Temporal

iso8601 and gregory behave differently in Temporal. For example, the weekOfYear and yearOfWeek properties return the ISO week number for iso8601, but they are undefined for other calendars, including gregory.

const isoDate = Temporal.PlainDate.from("2024-12-31");
const gregorianDate = Temporal.PlainDate.from("2024-12-31[u-ca=gregory]");
// 31 Dec 2024 belongs to the first week of 2025
isoDate.weekOfYear; // 1
isoDate.yearOfWeek; // 2025
// `undefined` for other calendars
gregorianDate.weekOfYear; // undefined
gregorianDate.yearOfWeek; // undefined

The year property uses astronomical year numbering for both calendars. However, iso8601 does not have eras, whereas gregory defines two eras: bce and ce.

const isoDate = Temporal.PlainDate.from("-000020-01-01");
isoDate.year; // -20
// "iso8601" does not have eras
isoDate.era; // undefined
isoDate.eraYear; // undefined

const gregorianDate = Temporal.PlainDate.from("-000020-01-01[u-ca=gregory]");
gregorianDate.year; // -20
// "year -20" corresponds to 21 BC
gregorianDate.era; // "bce"
gregorianDate.eraYear; // 21

The most fundamental difference between iso8601 and gregory is that iso8601 is treated as a special calendar in Temporal, while gregory is not. Temporal places gregory in the same category as other cultural calendars like chinese (the traditional Chinese calendar) and hebrew (the Hebrew calendar).

ECMA-262 and ECMA-402

ECMA-262 is the core specification of JavaScript, defining almost all of its core language features. On the other hand, ECMA-402 defines internationalization features, primarily the APIs under the Intl namespace. The specification for Temporal spans both ECMA-262 and ECMA-402, because Temporal deals heavily with domains closely tied to internationalization, particularly time zones and calendars.

The behavior of the iso8601 calendar in Temporal is explicitly specified in ECMA-262 with no implementation-defined behavior. For example, the date and time arithmetic algorithms are fully defined in ECMA-262. In fact, iso8601 is the only calendar defined in ECMA-262; all other calendars are implementation-defined in ECMA-262, and gregory is not mentioned there at all.

ECMA-402 defines the list of calendars that conforming implementations must support, which includes gregory. A conforming ECMA-402 implementation cannot omit any of these calendars or add arbitrary extra ones.

This distinction reflects the underlying design principle: iso8601 is a neutral model, whereas gregory is the Gregorian calendar as used in the real world. ECMA-262, as the core language specification, aims to remain culturally neutral, and iso8601 is the only calendar that satisfies this requirement.

How `iso8601` and `gregory` work in Temporal

While iso8601 is a very special calendar in Temporal's specification, gregory is treated just like any other calendar. This difference becomes apparent when using Temporal.PlainYearMonth and Temporal.PlainMonthDay, the two trickiest types in Temporal.

Dates can be converted between calendars, but isolated "year and month" or "month and day" values cannot. For example, Tamuz (M10) 5786 in the Hebrew calendar spans dates from 16 June to 14 July 2026, so there is no single corresponding "year and month" in the iso8601 calendar. This is why Temporal.PlainYearMonth and Temporal.PlainMonthDay do not have a withCalendar method.

2026-07[u-ca=hebrew] clearly makes no sense, whereas 2026-07 is a valid ISO 8601 string for July 2026 in the iso8601 calendar. A Temporal.PlainYearMonth representing Tamuz 5786 is serialized as an ISO date string representing the first day of that month (2026-06-16[u-ca=hebrew]). For consistency, Temporal.PlainYearMonth rejects 2026-07[u-ca=gregory] just as it rejects 2026-07[u-ca=hebrew]. For the same reason, both 07-01[u-ca=hebrew] and 07-01[u-ca=gregory] are invalid for Temporal.PlainMonthDay, whereas 07-01 is valid for 1 July in the iso8601 calendar.

Temporal.PlainYearMonth.from("2026-07");
// July 2026 in `iso8601`
Temporal.PlainMonthDay.from("07-01");
// 1st July in `iso8601`

Temporal.PlainYearMonth.from("2026-07[u-ca=gregory]");
Temporal.PlainMonthDay.from("07-01[u-ca=gregory]");
// parse error

You can create a Temporal.PlainMonthDay from a month number and day in iso8601, but you cannot do so for other calendars. You must provide either the year or the month code.

Temporal.PlainMonthDay.from({ month: 1, day: 1 });
// 1st January in `iso8601`

Temporal.PlainMonthDay.from({
  month: 1,
  day: 1,
  calendar: "gregory",
});
// error

Temporal.PlainMonthDay.from({
  year: 2026,
  month: 1,
  day: 1,
  calendar: "gregory",
});
// or...
Temporal.PlainMonthDay.from({
  monthCode: "M01",
  day: 1,
  calendar: "gregory",
});

This is because the month number for a given month can vary by year in calendars with leap months, such as the Hebrew and Chinese calendars. For example, the month of Tamuz in the Hebrew calendar is the 10th month in regular years, but the 11th month in leap years due to the insertion of an intercalary month (Adar I). When Temporal.PlainMonthDay.from receives a month number without year information, it throws an error for all calendars other than iso8601, rather than only throwing for calendars that have leap months. I guess this rule was chosen for consistency across non-ISO calendars.

Friction between Temporal and `Intl.DateTimeFormat`

Most developers will not need to use the gregory calendar directly in Temporal, so the differences described above rarely cause issues. However, friction does arise when formatting a Temporal.PlainYearMonth or Temporal.PlainMonthDay with toLocaleString or Intl.DateTimeFormat.

const formatter = new Intl.DateTimeFormat("en-GB");
formatter.format(Temporal.PlainDate.from("2026-07-01"));
// "01/07/2026"

formatter.format(Temporal.PlainYearMonth.from("2026-07"));
// error
Temporal.PlainYearMonth.from("2026-07").toLocaleString("en-GB");
// error

formatter.format(Temporal.PlainMonthDay.from("01-01"));
// error
Temporal.PlainMonthDay.from("01-01").toLocaleString("en-GB");
// error

Why does this happen?

While Temporal objects default to the iso8601 calendar, Intl.DateTimeFormat instances default to gregory for most locales.

new Intl.DateTimeFormat("ja").resolvedOptions().calendar;
// "gregory"

This mismatch does not cause an error when formatting a Temporal.PlainDate. Because iso8601 is the default and transparent calendar, the date in iso8601 is automatically converted to the calendar of the Intl.DateTimeFormat instance. This conversion applies to all calendars (not only for gregory), consistent with the principle that iso8601 is special while gregory is treated like any other calendar.

const date = Temporal.PlainDate.from("2026-07-01");
new Intl.DateTimeFormat("ja").format(date);
// "2026/7/1"
new Intl.DateTimeFormat("en-u-ca-hebrew").format(date);
// "16 Tamuz 5786"

However, because Temporal.PlainYearMonth and Temporal.PlainMonthDay are calendar-dependent and cannot be converted between calendars, a mismatch between the calendar on the Temporal object (iso8601) and the formatter (gregory) throws an error. One might argue that iso8601 and gregory are same and that JavaScript should simply overlook the difference, but such an exception would contradict the core design principle.

Formatting dates with the iso8601 calendar is usually not what developers want, so the proper workaround is to construct a Temporal.PlainYearMonth or Temporal.PlainMonthDay using the gregory calendar before formatting:

const pym = Temporal.PlainYearMonth.from("2026-07");
const pymGregory = Temporal.PlainYearMonth.from({
  year: pym.year,
  month: pym.month,
  calendar: "gregory",
});
new Intl.DateTimeFormat("ja").format(pymGregory);
// "2026/7"

Conclusion

iso8601: The Gregorian calendar as a culturally neutral data model, primarily used in Temporal.
gregory: The Gregorian calendar as used in the real world with cultural conventions and eras, primarily used in Intl.DateTimeFormat.

How to use markdown-exit (or another Markdown renderer) in Eleventy

2026-07-07T15:10:00Z

Problem

Eleventy uses markdown-it as its default Markdown renderer. However, markdown-it forces plugins to be synchronous, which makes it impossible to, for example, fetch Open Graph data or optimize images during Markdown rendering. Shiki, my favorite syntax highlighter, is also asynchronous by default. Shiki can be run synchronously, but we would have to load all languages in advance or manually specify the languages used in our Markdown files. Neither solution is ideal.

Several projects attempt to address this issue. markdown-it-async, a thin wrapper for markdown-it authored by one of the maintainers of Shiki, adds support for asynchronous syntax highlighting. markdown-exit is a drop-in replacement for markdown-it that addresses a broader set of markdown-it's issues, including support for asynchronous rendering.

I read the "Markdown" page of the official documentation and learned how to modify markdown-it options or add plugins. Since markdown-exit is compatible with markdown-it, we can replace the markdown-it instance with markdown-exit via setLibrary as described in the documentation, but this does not enable asynchronous rendering. Eleventy calls the render method of the library instance and expects it to return a string.

It took me a while to find a solution because I had been stuck on using the default setLibrary approach. In reality, the best solution doesn't even rely on compatibility between markdown-it and markdown-exit.

Solution

Actually, Eleventy does not crash and still generates HTML correctly even if the render method returns Promise<string>, so the following code accidentally works fine. Of course, this behavior is undocumented and could change at any time.

// It works, but...
eleventyConfig.setLibrary("md", { render: md.renderAsync.bind(md) });

Fortunately, Eleventy is flexible enough to allow us to use a completely different Markdown renderer. This behavior is explicitly documented.

Custom — Eleventy

import shikiPlugin from "@shikijs/markdown-exit";
import { createMarkdownExit } from "markdown-exit";

// Eleventy enables the `html` option by default
const md = createMarkdownExit({ html: true });
md.use(shikiPlugin({ theme: "nord" }));

eleventyConfig.addExtension("md", {
  async compile(input, path) {
    return async (data) => await md.renderAsync(input);
  },
});

It is worth noting that we could even choose a library that is not compatible with markdown-it, such as Remark or Marked. However, I still use markdown-exit because it is the fastest Markdown renderer that Shiki officially supports; it is noticeably faster than Remark & Rehype.

Source code

This blog is built using Eleventy v4 alpha and markdown-exit. Note that the blog's technology stack may change in the future.

eleventy.config.ts at 9d18664

I made another Temporal polyfill from scratch

2026-04-29T17:45:00Z

It's because existing polyfills were insufficient for me.

Brief summary

I created temporal-polyfill-lite, a lightweight Temporal polyfill.
It supports the final spec of Temporal and is compatible with the official TypeScript type definition.
For the majority of developers (those who only need the Gregorian calendar), it's the smallest Temporal polyfill available as of April 2026.

The state of ECMAScript Temporal

The Temporal proposal recently reached Stage 4. Firefox shipped it in May of last year, and Chrome followed suit this January. Node.js is planning to ship Temporal in its next major version (v26), which is set for release this May^[1]. Safari is lagging a bit behind, but implementation is underway, so it's only a matter of time^[2]. We can finally start using Temporal!

Well, we still need a polyfill for now. Until recently, there were only two polyfills: @js-temporal/polyfill and temporal-polyfill.

Existing polyfills

`@js-temporal/polyfill`

@js-temporal/polyfill is based on the reference polyfill from the Temporal proposal repository and is maintained by some of the proposal's champions. The reference polyfill itself is mainly for spec verification and doesn't aim to be production-ready, so several performance optimizations were added to make it suitable for real-world use. Sounds good so far, right?

The downside, however, is the massive bundle size: 160 kB minified and 45 kB gzipped. For comparison, the core of Moment.js is 60 kB minified and 18.5 kB gzipped. Compared to other date and time libraries, this polyfill is excessively large for frontend projects. The original code is a literal, word-for-word reference implementation of the spec and wasn't built with bundle size in mind. While it's relatively easy to optimize performance later, optimizing bundle size is much more difficult.

Moreover, while the upstream reference polyfill is actively maintained, @js-temporal/polyfill wasn't for a while. The champions always fix reported bugs quickly and reflect spec changes immediately in the proposal repository, but those changes hadn't been merged into @js-temporal/polyfill for ten months (though merging has recently resumed, e.g., js-temporal/temporal-polyfill#361). I want to clarify that I am not blaming the maintainers. Maintaining both the upstream and the fork is tough work, and the champions have a massive number of tasks to handle during the standardization process.

`temporal-polyfill`

On the other hand, temporal-polyfill has a much smaller bundle size: 57 kB minified and 20 kB gzipped. It's still a bit large but acceptable, considering the Temporal spec is over 10,000 lines long. Unfortunately, like @js-temporal/polyfill, it refers to an outdated version of the spec. Consequently, various bugs and confusing behaviors that were resolved in the final spec have remained for months (note: updates seem to be in progress now, but aren't finished yet). Some issues are rare edge cases, but others can bite anyone using Temporal in the real world. Here are a few examples:

// regular DST change:
Temporal.ZonedDateTime.from(
  "2025-11-02T01:01:00-07:00[America/Vancouver]",
).until("2025-11-02T01:00:00-08:00[America/Vancouver]", {
  largestUnit: "days",
});
// Throws `RangeError` in both polyfills,
// but should be PT59M (59 minutes) per the final spec

Temporal.PlainYearMonth.from("2024-02").subtract(
  { years: 1 },
  { overflow: "reject" },
);
// Throws `RangeError` in both polyfills,
// but should be 2023-02 (February 2023) per the final spec

In particular, era definitions for calendars were finalized relatively recently, and existing polyfills haven't caught up yet. Developers working with non-ISO calendars will likely run into trouble here:

Temporal.PlainDate.from("2026-04-01[u-ca=gregory]").era;
// Returns "gregory" in both polyfills, but "ce" per the final spec

Temporal.PlainDate.from("2026-04-01[u-ca=hebrew]").era;
// Returns undefined in both polyfills, but "am" per the final spec

temporal-polyfill also has some bugs related to time zones and date arithmetic. While bugs are inevitable, they haven't been fixed for a while, which can hinder the adoption of Temporal. For me, these were deal-breakers; I believe that reliable date arithmetic and time zone calculations are exactly the reason for being of Temporal. I didn't want to implement workarounds just because of a polyfill.

Once again, I don't want to blame the maintainer. Maintaining a Temporal polyfill is incredibly hard work (likely harder than you'd imagine), and criticizing OSS maintainers for a lack of bandwidth or time goes against the spirit of open source.

Why is it so hard to implement a polyfill?

Generally, while writing a polyfill requires specialized knowledge, it is not as hard as you might think: read the spec and implement it word for word. If you're interested in ECMAScript, writing a polyfill is usually a great place to start.

Temporal, however, is a clear exception. It's a gigantic proposal with 13,000 lines of spec text. For context, ECMA-262 (the core JS spec) is 53,000 lines, and ECMA-402 (the i18n spec) is 10,000 lines before Temporal is merged. It is the largest addition in the history of ECMAScript. Let alone implementation, even understanding the structure of such a huge spec is difficult. It requires deep knowledge of ECMA-402 and i18n, especially time zones, calendars, and Intl.DateTimeFormat, in addition to knowledge necessary for typical polyfill authors.

The options

temporal-polyfill was virtually my only option, but it had critical issues, and it seemed like nobody was working on them at the time. Literally nobody. That's understandable because not many developers have the ability, willingness, and time to fix temporal-polyfill.

I'm just a graduate student^[3] who loves web technologies; I don't belong to any standards bodies or browser vendors. However, to make a long story short, I had some knowledge of Temporal and i18n, the ability to dive into the spec, and plenty of enthusiasm for the JavaScript ecosystem. I felt like I had an obligation to do something useful instead of just posting "any updates?" comments on GitHub.

At first, I tried to fix the bugs in temporal-polyfill and sent a pull request. Unfortunately, it's been open for six months and hasn't been merged yet. I wanted to fix the remaining time zone bugs too, but I found it hard to do so while respecting the original author's architectural decisions. It would have been even harder to debate design on GitHub for me. Furthermore, the project's structure differed from the spec, making it difficult for me to track down the root cause of the arithmetic bugs. I just wasn't smart enough to map the spec text to the existing code.

Eventually, I started considering a "crazier" option: building a polyfill from scratch. It was not only because there was no other option for me. I had been curious to see how small a polyfill could be if it only supported the Gregorian calendar. I suspected that a lot of the bulk in existing polyfills came from complex non-Gregorian calendars that only a tiny fraction of developers actually need.

Requirements and design decisions

I started building temporal-polyfill-lite with a different set of design principles.

Project structure

temporal-polyfill-lite is almost a word-for-word implementation of the spec. This allows the project to benefit directly from the work of spec writers and implementers.

The spec text is extremely well-maintained pseudocode that has been reviewed and debugged by many people (including myself). Following it closely reduces bugs. It also makes debugging easier because I can compare my code directly to the reference polyfill.

If the spec text is simplified upstream, I can easily apply those simplifications to my code. Conversely, if I find a way to simplify my code, I might even be able to contribute that change back to the spec.

No protection against global namespace mutation

temporal-polyfill-lite won't work if built-in methods (like String.prototype.replace or Array.prototype.map) are deleted or modified. While this isn't strictly spec-compliant, does it really matter? If someone invasively mutates the global namespace, your entire application is going to break anyway. Protecting a polyfill from such mutations (using the "primordials" trick) sacrifices both bundle size and performance for very little practical gain.

For more on this, I recommend the excellent article "The Three Pillars of JavaScript Bloat".

Bundle size

From the start, temporal-polyfill-lite was built with bundle size as a priority. I've applied various reduction techniques throughout the codebase.

Internal representation of large integers

Temporal supports timestamps and durations with nanosecond precision. "Epoch nanoseconds" and "time durations" can exceed JavaScript's maximum safe integer (53-bit) or even a 64-bit integer.

temporal-polyfill-lite represents these large integers as an array of two numbers (a quotient and a remainder of x / 8.64e13) internally, rather than using BigInt. I borrowed this clever idea from temporal-polyfill.

Browser support

temporal-polyfill-lite works in any browser released after 2020 (it uses features from "Baseline 2020").

Since it doesn't rely on BigInt internally, it could work in older browsers if you transpile temporal-polyfill-lite and inject polyfills for APIs used internally (since code using BigInt can't be transpiled or polyfilled at all).

Time zones

temporal-polyfill-lite supports all time zones. This is definitely a long-awaited feature. Who wants to use Temporal without proper time zone support?

Calendars

By default, it only supports iso8601 and gregory calendars, which keeps the bundle small for most developers. Support for gregory is actually required if you want to format Temporal.PlainMonthDay or Temporal.PlainYearMonth using Intl.DateTimeFormat or toLocaleString, due to some quirks in those classes:

Temporal.PlainYearMonth.from("2026-04").toLocaleString("en-US", {
  dateStyle: "long",
});
// Throws a confusing "calendar mismatch" error

Temporal.PlainYearMonth.from("2026-04").toLocaleString("en-US", {
  calendar: "iso8601",
  dateStyle: "long",
});
// Returns "2026 April" in Chrome/Firefox, which isn't usually what you want
// (this format is not used in America).
// Node.js v25 returns a broken result: "2026 "

Temporal.PlainYearMonth.from("2026-04-01[u-ca=gregory]").toLocaleString(
  "en-US",
  { dateStyle: "long" },
);
// "April 2026" (exactly what you'd expect)

Implementation

It was a long, tough journey.

I started the project in June 2025, but it stalled for months because I didn't have the time to commit to it. I restarted it from zero in December 2025 (reusing many parts of the old code) and finally released the initial version in late January 2026. It took about seven weeks from the "reboot" to the first release.

Thanks to the enormous effort of the champions and implementers to expand test262, Temporal has almost 100% test coverage in test262 now. A fast test runner developed by the champions (temporal-test262-runner) was a lifesaver, significantly reducing test execution time. The Temporal proposal repository also has "thorough tests", scripts for testing implementation against a vast number of test cases. I found various bugs in my implementation with the aid of these tests.

I should mention that I was a latecomer. Unlike other polyfill authors, I implemented the polyfill based on the almost finalized spec. I didn't have to navigate the major normative changes (like the big scope reduction in June 2024) that the pioneers had to deal with. I have immense respect for those who kept their polyfills updated for years as the spec evolved.

As a side effect of building this, I found and reported several bugs and errors in the spec text and even submitted a pull request to improve it (tc39/proposal-temporal#3271). I'm very happy to have contributed to the proposal in some small way.

I know some people think human coding is obsolete. Claude Code or Codex could probably write a Temporal polyfill in days or even hours. But I wrote every line by hand, and I don't regret it. It was a "desirable difficulty" that expanded my knowledge. Understanding the details of the spec and implementation, such as how to deal with an unusual time zone transition in Canada 100 years ago or the quirks of floating-point arithmetic in JavaScript, isn't a "boring task" I want to outsource to an agent; it's exactly what I find interesting. For me, coding is like DIY and isn't something I have to "streamline" at the expense of the joy of understanding how things work^[4].

Time zone calculations

The only way to access the time zone database in JavaScript engines is by parsing the output of Intl.DateTimeFormat with the timeZone option. Parsing localized strings is usually a terrible idea, as formats vary between engines and versions, but there's no other choice. Fortunately, the formatToParts method returns structured data that is relatively reliable to parse.

new Intl.DateTimeFormat("en", {
  year: "numeric",
  month: "numeric",
  day: "numeric",
  hour: "numeric",
  minute: "numeric",
  second: "numeric",
  hour12: false,
  timeZone: "Asia/Tokyo",
}).formatToParts(0);
// Result:
[
  { type: "month", value: "1" },
  { type: "literal", value: "/" },
  { type: "day", value: "1" },
  { type: "literal", value: "/" },
  { type: "year", value: "1970" },
  { type: "literal", value: ", " },
  { type: "hour", value: "09" },
  { type: "literal", value: ":" },
  { type: "minute", value: "00" },
  { type: "literal", value: ":" },
  { type: "second", value: "00" },
];

Essentially, we can calculate the UTC offset by comparing the formatted parts to the original timestamp. Most date and time libraries (Luxon, Day.js with tz plugin, @date-fns/tz, etc.) and other Temporal polyfills use a similar approach too.

function getOffsetMilliseconds(epochSeconds: number, timeZone: string) {
  const parts = new Intl.DateTimeFormat("en", {
    year: "numeric",
    month: "numeric",
    day: "numeric",
    hour: "numeric",
    minute: "numeric",
    second: "numeric",
    hour12: false,
    timeZone,
  }).formatToParts(epochSeconds * 1000);
  const units = ["year", "month", "day", "hour", "minute", "second"];
  const [localYear, localMonth, localDay, localHour, localMinute, localSecond] =
    units.map((unit) => parseInt(parts.find((p) => p.type === unit)!.value));
  return (
    Date.UTC(
      localYear,
      localMonth - 1,
      localDay,
      localHour,
      localMinute,
      localSecond,
    ) -
    epochSeconds * 1000
  );
}
getOffsetMilliseconds(0, "Europe/London"); // 3600000 (UTC+1)
getOffsetMilliseconds(0, "America/New_York"); // -18000000 (UTC-5)
getOffsetMilliseconds(0, "Asia/Tokyo"); // 32400000 (UTC+9)
getOffsetMilliseconds(0, "Africa/Monrovia"); // -2670000 (UTC-0:44:30)

Because Intl.DateTimeFormat is slow, the polyfill uses an LRU cache. However, the current mechanism is far from ideal. It caches offsets for every second, even though offsets rarely change. Most countries and regions don't use DST (daylight saving time), and time zone offsets change at most twice per year in time zones where DST is observed. Time zone offset transitions for political reasons are even less common. I'm currently working on a more efficient caching algorithm (issue).

Reducing bundle size

One of my main goals was a small bundle size. I wrote a script to measure the size (with and without compression) to ensure every optimization actually worked. You can't optimize what you don't measure.

If you look at minified JavaScript code, you'll notice many long property names. That's because mangling properties is unsafe; it can easily break your code. Properties in public APIs or internal properties accessed by the bracket operator can't be mangled.

// original:
const foo = { fooBarBaz: 0 };
const prop = "fooBarBaz";
Object.keys(foo); // ["fooBarBaz"]
foo[prop]; // 0

// after mangling properties:
const foo = { a: 0 };
const prop = "fooBarBaz";
Object.keys(foo); // ["a"]
foo[prop]; // undefined

Initially, I tried to write the whole polyfill using tuples instead of objects, but that was almost impossible to maintain. No one wants to remember that isoDateTime[0][1] actually means isoDateTime.date.month. So, I decided to introduce property mangling when I "rebooted" the project.

Instead of making a long list of properties we want to preserve, I introduced a simple naming convention: every internal property that should be mangled starts with a $ (e.g., $isoDate) or _. This allows the minifier to safely mangle internal properties while leaving the public API intact. I picked up this idea from this article (English version available too) on JavaScript minification.

I also prioritized expressions over statements. Multiple function calls can be merged using the comma operator, and if statements can be converted into conditional or logical operators if the block doesn't contain any statements.

if (foo) {
  bar();
  baz();
}

// after minification:
foo && (bar(), baz());

It might seem weird to replace throw statements with function calls that throw errors, but it actually reduced the bundle size significantly because it allowed the minifier to optimize the code further. I also removed intermediate variables wherever possible to keep the code as a series of expressions.

// before:
function aaaaa(foo) {
  if (foo) {
    throw new RangeError("foo");
  }
  const bar = baz();
  return qux(bar);
}
// code above is minified like below:
function aaaaa(e) {
  if (e) throw RangeError("foo");
  let t = baz();
  return qux(t);
}

// after:
function throwRangeError(message) {
  throw RangeError(message);
}
function aaaaa(foo) {
  if (foo) {
    throwRangeError("foo");
  }
  return qux(baz());
}
// code above is minified like below:
function aaaaa(e) {
  // Note that `throwRangeError` will be also mangled in the production build.
  return (e && throwRangeError("foo"), qux(baz()));
}

Compared to the initial release, the bundle size has dropped by 15% (from 60 kB to 52 kB) minified, and 10% (from 19.7 kB to 18 kB) gzipped. What a huge win!

Support for non-Gregorian calendars

After spending a few weeks to reduce the bundle size, I became confident that the whole codebase was optimized enough. As a next step, I looked into adding non-Gregorian calendars without increasing the bundle size for the majority of users (issue). It had been in my backlog for months, but I hadn't figured out yet how to implement it.

I wanted something like Rust's feature flags, but that doesn't really exist in the JavaScript ecosystem. After human deep research and ultrathinking, I decided to use custom conditions for conditional exports and imports. Fortunately, all toolchains I use in this project (Node.js, TypeScript compiler, and Rolldown) support this.

The package.json looks like this:

{
  "exports": {
    ".": "./dist/index.js",
    "./calendars-full": "./dist/calendars/index.js"
  },
  "imports": {
    "#calendricalCalculations": {
      "nonIsoCalendars": "./src/internal/calendars/all.ts",
      "default": "./src/internal/calendars/basic.ts"
    }
  }
}

The polyfill has two entrypoints. The standard one is built without the nonIsoCalendars condition, while calendars-full includes it. Both all.ts and basic.ts export identical functions with different sets of supported calendars (see fabon-f/temporal-polyfill-lite#7 for details).

Calendrical calculations

While JavaScript engines can calculate non-Gregorian dates internally, there's no direct API to access those results (this is exactly what Temporal does). Unlike time zone calculations, parsing the output of Intl.DateTimeFormat for non-Gregorian calendars is theoretically possible but unreliable, because formats produced by Intl.DateTimeFormat for those calendars are far more inconsistent than for Gregorian across JavaScript engines or even operating systems (cf. js-temporal/temporal-polyfill#284).

Instead, I implemented the calendrical calculations myself for rule-based calendars. In particular, the hebrew calendar is purely arithmetic but incredibly complex, so I tested my implementation against ICU4X to ensure accuracy. For calendars that require astronomical simulation or historical calendar data (i.e., islamic-umalqura, persian, chinese, and dangi), the polyfill defers to the native Intl.DateTimeFormat.

The result

temporal-polyfill-lite is currently the only Temporal polyfill that follows the final spec and is compatible with the official TypeScript type definitions in v6.0. In my opinion, it's also the most reliable one for now. These points are important for developers who want to use Temporal right now, but will be irrelevant in the near future since other polyfills will eventually be updated too. I'm not sure when, but I hope so.

Instead, the real advantage of temporal-polyfill-lite is the bundle size. The table below shows the comparison as of April 2026. Note that the result can change in the future, in particular when temporal-polyfill and @js-temporal/polyfill reflect the final spec (see comparison repository for the latest result). While I'm happy with the results, I still think the calendars-full version could be a bit smaller.

	minified	gzip	brotli	zstd
native	0 kB	0 kB	0 kB	0 kB
`temporal-polyfill-lite`	52.1 kB	17.9 kB	15.9 kB	18.6 kB
`temporal-polyfill-lite/calendars-full`	63.6 kB	22.2 kB	19.6 kB	23.2 kB
`temporal-polyfill`	57.0 kB	20.3 kB	18.2 kB	21.2 kB
`@js-temporal/polyfill`	159.7 kB	45.3 kB	39.3 kB	47.2 kB

I haven't checked the runtime performance, so perhaps there is room for optimization. Of course I want to speed up the polyfill while not bloating the bundle size.

Which polyfill should we use?

I'll try to be as objective and honest as I can.

Backend projects

Introducing Temporal to backend projects sounds very reasonable and promising, because Temporal enables us to handle dates and times in a reliable manner.

You don't have to mind bundle size too much for backend. Rather, the primary requirement for these projects is robustness. I believe temporal-polyfill-lite is the best polyfill for now, but @js-temporal/polyfill would also be a good option after it is updated (I hope the update will be done in a few weeks). Both polyfills have very few bugs.

Anyway, Node.js v26 with support for Temporal will move to LTS this October, so we can remove a Temporal polyfill from backend projects soon.

Frontend projects

Honestly, it would be too early to use Temporal for most frontend projects since it isn't even "Baseline Newly available" yet and a Temporal polyfill isn't tiny. However, Temporal is no longer unstable or experimental, so you can try it. In particular, projects using SSG frameworks such as Astro can benefit from Temporal without increasing JavaScript size.

In my opinion, temporal-polyfill-lite is the least painful polyfill for frontend projects, because it is up-to-date, least buggy, and the smallest for most developers, at least for now. temporal-polyfill can be another option after it is fixed and updated.

Conclusion

I've been following the Temporal proposal for the last two years, always wondering when it would be ready for production. Now I can answer that question with confidence: you can use it today if you really want. If you want to start using Temporal right now, temporal-polyfill-lite is exactly what you need for the foreseeable future (for a few years at most, I believe).

If you find any bugs, please feel free to report them on GitHub. I'll fix them as soon as possible.

In closing, it's a great honor to contribute to Temporal, the unparalleled project in the history of ECMAScript. Long live web standards! Long live ECMAScript!

The release is originally planned in 22nd April, but it has been postponed until 4th May due to build issues, mainly caused by Temporal implementation. V8 introduced Rust dependencies (ICU4X and temporal_rs) for the first time to implement Temporal (cf. nodejs/node#58730), therefore Node.js have to add Rust toolchains to build pipeline. The work is basically done, but Node.js developers are still struggling with build errors. ↩︎
I agree about the part that it's a matter of time, but I can't say irresponsibly that Safari will ship Temporal soon. Honestly, I think it can't happen in this year. There is still great uncertainty, especially problems of calendrical calculations in ICU4C. I even suspect communication between Igalia and Apple doesn't work well, or implementation of Temporal has low priority, but I hope I'm wrong. ↩︎
Actually, I'm not even a STEM student. I'm currently studying modern Russian history at the University of Tokyo. ↩︎
That being said, I'm still exploring how to integrate coding agents into my workflow without losing the parts of coding I find fun. ↩︎

fabon's blog

The difference between `gregory` and `iso8601` calendars in ECMAScript

iso8601 as a calendar

iso8601 as a culturally neutral data model

Intl.DateTimeFormat

Temporal

ECMA-262 and ECMA-402

How iso8601 and gregory work in Temporal

Friction between Temporal and Intl.DateTimeFormat

Conclusion

How to use markdown-exit (or another Markdown renderer) in Eleventy

Problem

Solution

Source code

I made another Temporal polyfill from scratch

Brief summary

The state of ECMAScript Temporal

Existing polyfills

@js-temporal/polyfill

temporal-polyfill

Why is it so hard to implement a polyfill?

The options

Requirements and design decisions

Project structure

No protection against global namespace mutation

Bundle size

Internal representation of large integers

Browser support

Time zones

Calendars

Implementation

Time zone calculations

Reducing bundle size

Support for non-Gregorian calendars

Calendrical calculations

The result

Which polyfill should we use?

Backend projects

Frontend projects

Conclusion

`iso8601` as a calendar

`iso8601` as a culturally neutral data model

`Intl.DateTimeFormat`

How `iso8601` and `gregory` work in Temporal

Friction between Temporal and `Intl.DateTimeFormat`

`@js-temporal/polyfill`

`temporal-polyfill`