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.

[KazimirPodolski]

Luxon is WAY more ergonomic than Temporal and seeing Luxon getting dumped in favor of Temporal would be a DX disaster for thousands of people.

[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!

[KazimirPodolski]

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.

May I ask you to reconsider? Reasons:

• It's convenient to do code like

  const moveDate = (forward: boolean) => {
     const mult = (forward ? 1 : -1)
  
     switch (calendarMode) {
       case 'month':
         return luxon.plus({month: 1 * mult})
       case 'week':
         return luxon.plus({week: 1 * mult})
       case 'day':
         return luxon.plus({day: 1 * mult})
    }
  }

  I would assume there is quite some code like this in the wild already.
• It would be near-impossible to make the upgrade in a typesafe way, such that the code using mixed signs breaks on compilation.

[diesieben07]

Thank you for your feedback!
The code you have showed would continue to work as-is, as there are no mixed durations involved. Since the durations in your code only have one unit each, they cannot be mixed in the first place. The only thing that will be removed is durations with multiple units where the units have different signs, e.g. "-3 months and 5 years". "-3 months and -5 years" is still allowed, same as "3 months and 5 years" or just "-3 months".
I hope this satisfies your concerns, if not please do let me know!

You are correct that this cannot be stopped by the type system. But there are many things that cannot. DateTime.fromObject({ years: 4.5 }) is correct from a type system perspective, but already throws today. No type system can catch all problems at compile time.

[KazimirPodolski]

Ah, I misread. Fine then!

[KazimirPodolski]

Aaactually...

[diesieben07]

Aaactually...

Sure, but this only works for values which are statically known to the compiler. If you read something from an API response it'll be number and the compiler will not be able to know if it is an integer or not.

[XhstormR]

Is there a timeline for the release of version 4.0?

[pwilder-sig]

Appreciate that there is no fixed timeline for 4.0 but are there any updates here?

[diesieben07]

I'll use this comment to give an update and I apologize for the silence. Basically, what happened is the classic "developer starts on a project without planning and gets distracted" issue.
I have to say that this is the first project that I maintain with actual users, so I did not notice I fell into this trap before it was already too late.
I started working on Luxon 4, excited to play with all the fancy tools. I installed TypeScript and Vite and Vitest. But I failed to give myself a proper roadmap and I failed to actually plan things. So the result was that I started rewriting random things, because when I came across them I went "well, this is not optimal...", but then suddenly I am working on 5 things at once. And then I procrastinated on actually solving the issues, because solving issues is hard and "playing with new shiny stuff" is easy.
So, currently, the timeline is unfortunately "later than expected", because I basically need to start over, but with a good plan this time.

The first step is to convert Luxon to TypeScript, but not change any functionality.
Then I can start from a codebase that works and passes all tests and start working on the changes and features I have planned for Luxon 4.

Additionally, I want to go through and merge some of the recent feature PRs and release a new minor version of Luxon 3, so those can be used.

I am sorry for this "bad news", but it is what it is.

[mahnunchik]

Haha, rewriting to TypeScript just for the sake of rewriting to TypeScript.

Maybe it would be better to rewrite it using modern ECMAScript 2026 instead?

Luxon is one of the few projects that hasn’t been eaten by this TypeScript brain rot.

[diesieben07]

Haha, rewriting to TypeScript just for the sake of rewriting to TypeScript.

It's not "just for the sake of rewriting to TypeScript". Luxon already uses fairly modern ECMAScript, the only thing that could be changed there is to use "real private fields".
There are bugs that exist(ed) in Luxon which would have been caught by TypeScript.

You may or may not like TypeScript, but personally I really value the assistance of a type-safe language.

[mahnunchik]

Good old JSDoc comments (already in the project) and tsc --noEmit solve the "type-safe language" problem without rewriting everything just to rewrite

#privateField