Roadmap for Luxon 4

[diesieben07]

Luxon 4 Roadmap

Luxon has been around for a relatively long time and most of it has not changed that much since its first inception.

In January 2025 I took over maintenance of Luxon and I have used the time until now to gather some ideas and plans for the next major version of Luxon.

Luxon 4 will not be fundamentally different from Luxon 3, however there are some quirks and long-standing issues that will be addressed, some of which require breaking changes.

None of the items below are set in stone. I am looking for feedback and suggestions.

I will update this post with updates as things progress.

Invalid objects

Luxon's objects can be in a state called "invalid". Invalid objects will be returned when invalid input is provided to a factory function or other invalid operations are performed. For example, DateTime.fromISO("not ISO") will return an invalid DateTime. Invalid objects are somewhat similar to NaN in floating point numbers, they "persist". For example, adding a duration to an invalid DateTime will again yield an invalid DateTime.

However, an invalid DateTime is pretty useless, you can't do anything with it, except ask if it's invalid. Most methods on it (e.g. toISO) will simply return null. Others (mostly those intended for "display purposes" like toLocaleString) will return "Invalid DateTime".

This requires you to either

1. Add checks like this throughout your code-base

   if (dt.isValid) {
      // do the actual thing 
   } else {
      // do something else, a fallback or just nothing
   }

2. Always check for invalidity immediately after parsing/changing/creating a Luxon object.

This can be changed through Settings.throwOnInvalid. If this setting is turned on, Luxon's API contract is changed. Now any method that would return an invalid object will instead throw an error.

This is better, however you might want to pick on a call-by-call basis which of the two behaviors you want. Even worse, you might be writing a library that uses Luxon. Now you have to handle both settings, because you cannot control how the users of your library use Luxon.

Luxon 4 will remove the concept of an "invalid object". When receiving a DateTime or Duration or other object in Luxon 4, your code can be sure that it is valid. You can think of this as throwOnInvalid being true by default.

To address the common use-case of trying to parse an input, where applicable additional try### methods will be added. For example:

class DateTime {
  
  // throws when passed an invalid input
  fromISO(text: string): DateTime;
  
  // returns ParseError when passed an invalid input
  tryFromISO(text: string): DateTime | ParseError;
  
}

Error handling

Luxon 3's behavior when passed an invalid input is not always consistent.
In Luxon 4:

• All methods will unconditionally throw an error when passed invalid data as per the API contract. For example, fromISO(123) will always throw and so will tryFromISO(123). Both invocations are a violation of Luxon's API (fromISO expects a string).
• Parsing methods like fromISO will throw an error when given an input that cannot be parsed. This error will be distinct from the above.

Durations

Ambiguous conversions

Currently, Luxon's Duration allows ambiguous conversions. For example, you can write Duration.fromObject({ years: 2 }).as("days"). This conversion however is ambiguous, because a year could be 365 or 366 days long. Such ambiguous conversions will no longer be allowed in Luxon 4.
If you want to convert from years to days (or perform other ambiguous conversions), a reference must be provided in the form of a DateTime. This DateTime will be taken as the start of the Duration and thus the conversion is no longer ambiguous.
This technique is borrowed from JavaScript's Temporal API, however it allows more flexibility. For example, conversion from years to months will not be ambiguous in Luxon and does not require a reference date.

This also means that the concepts of "conversion matrix" and "conversion accuracy" will be removed.

Mixed signs

Currently, Luxon's Duration allows mixed signs, for example Duration.fromObject({ years: 2, months: -2 }). Such durations can be confusing and will no longer be allowed in Luxon 4.

Fractional values

Values in a Duration will only accept integers in Luxon 4. When converting between units, any fractional values will be rounded.

An exception is made for formatting. When formatting a duration, a different set of units may be provided. The Duration's values will be converted into those units while allowing fractional values for formatting.

This change prevents issues with floating point precision when doing math on durations, but still allows formatting a Duration like 1.5 minutes.

Performance

Luxon currently has no serious performance benchmarks. I plan to add at least something here.

Additionally, I plan to try and find low-hanging fruit for improvements (e.g. making fromISO faster for common cases).

In some cases, Luxon's caching strategies are not optimal, resulting in extra calls to the (relatively slow) Intl API. I will look into improving this.

If possible, I will also look into improving Luxon's tree-shakability, although this is not a priority.

Immutability

Luxon's objects are designed to be immutable. However, they aren't truly immutable, because they have private, internal caches. Luxon 4 will start using native private class fields for such caches and any publicly accessibly properties will be immutable. This has the benefit of allowing Luxon's objects to be frozen with Object.freeze and still operate.

Infrastructure

These are mostly internal changes which serve to make development of Luxon easier, more stable and more future-proof.

Build system

Currently, Luxon uses some bespoke build scripts based on Rollup to build various distributions. Most of these are either redundant or no longer relevant.
Luxon 4 will switch to using Vite for building.

Shipped Distributions

Luxon 4 will ship 3 different build flavors:

• ESM, for most modern use-cases
• CommonJS if you still want to use it, e.g. in Node.js
• UMD, for direct use in the browser, e.g. via the luxon global.

Runtime support

Luxon 4 will support:

• Any currently supported Node.js LTS versions. At the time of writing this is 20, 22 and 24.
• Browsers falling into "Baseline Widely Available".

Other JavaScript runtimes like Deno, Bun, etc. will probably work and I may look into running automated tests on these as well.

Tests

Luxon currently uses Jest for testing. Jest is great, but it only allows running tests in Node.js. Luxon 4 will use Vitest. This allows us to keep the testsuite almost unchanged, because Vitest is Jest compatible. However through Vitest's browser mode we can now run tests in Browsers as well, making sure Luxon works across Chromium, Firefox and Webkit.

TypeScript

Most likely, Luxon will be converted to use TypeScript. This should not change anything for users, except that you no longer need @types/luxon.

[dasa]

I'm curious on your thoughts regarding the future of Luxon and Temporal. Would it add support for Temporal, or would a new package be better that included the parts of Luxon that Temporal is missing? There has been some discussion on this topic at #970.

[diesieben07]

Firstly, Temporal is great. I am sure there will eventually be people who drop libraries like Luxon, Moment, date-fns, etc. in favor of just using Temporal.

As for what this means for Luxon, I don't think it will go away any time soon. Once Temporal is widely supported, Luxon can start using it internally and get rid of a bunch of hacks that are currently necessary to extract the info we need from Intl.DateTimeFormat. This will mean people can keep using the same familiar Luxon API, but benefit from a smaller bundle and faster performance.

[abdelfattahradwan]

I look forward to Luxon 4! I like the upcoming changes, especially the switch to throw-by-default behaviour!

[1valdis]

CommonJS if you still want to use it, e.g. in Node.js

I'd like to point out that all currently Active and LTS Node versions support require(ESM). So if you only have CJS for the sake of Node compatibility, and don't use some ESM only features like top-level await, you can drop that. In fact, this is exactly why I'm about to drop CJS build for the next version of a library that I'm maintaining.

[diesieben07]

Sure, but there is not just Node. I have no idea what kind of setups people are running out there. And enabling CJS output in Vite is trivial, so might as well keep it.

[1valdis]

Now I'm curious what else other than Node uses CJS 👀

[diesieben07]

Old bundlers before ESM, for example.

[mahnunchik]

I believe that the next major version can be released in ESM-only format, because as mentioned above, all supported NodeJS versions already support it. All modern browsers support ESM, and modern bundlers definitely support it in 2025 (to be honest in 2026)

[blake-mealey]

Love to see that errors will become the default in v4. Something I ran into today with errors though is that they don't have an error code property to check unlike the invalid date. It would be great to add an error code property to the luxon error class with the stable error code that is already available on the invalid date object under invalidReason: https://moment.github.io/luxon/#/validity?id=invalidreason-and-invalidexplanation

[diesieben07]

Absolutely, this is on the list of things to do!