Migration to TypeScript

[kossnocorp]

TL;DR; from this moment, the date-fns codebase is migrating to TypeScript. It's going to be a gradual transition, so all new code has to be written in TypeScript. It will help make the library for lightweight, simplify the maintenance and make typing definitions robust.

Why?

In v2, we introduced many safeguards to help people use date-fns correctly. We added runtime checks of arguments. We've removed implicit string conversion that was an endless stream on complaints and mistakes.

Unfortunately, it didn't help, and people kept converting incorrect strings, this time outside of date-fns. On top of that, these safeguards made the library more heavyweight. Even though we put a lot of effort into optimizing the minimal build, which now is mere hundreds of bytes, this is the ceiling of what we can do. It also adds unnecessary performance overhead.

Another issue is that all that code is only helpful to people that are mistaken and only at the moment when they are mistaken and force others to do extra steps.

There's a better way. Developers that want to have type safety opt to use TypeScript and Flow. The others don't mind occasionally failing and don't want to be told what arguments (i.e., strings 😉) they can't use.

Unfortunately, our TypeScript definitions don't live up to expectations. Many types, like callbacks, are shallow, the definitions themselves are unnecessarily heavy and add more work to the TypeScript server and make the npm package bulky.

The main reason for that is that we generate definitions from JSDoc, and there's only so much we can do. Another issue is that we've written the definitions generation code when we had no idea how TypeScript works and how good types look like. Even though the build system is an impressive piece of software, it adds a toll on maintenance.

What's next?

From now on, all the new code must be written in TypeScript. The existing functions will be gradually migrated.

Once the migration is complete, we'll switch gears and remove all safeguards, switch the build system to use the TypeScript definitions as the source of truth instead of JSDoc and release v3.

But it's still a long way before we can call it a day. Besides migrating the source code, we have to:

• Switch to generating Flow from TypeScript.
• Rewrite docs generation to use TSDoc instead of JSDoc.
• Update the website to use the new documentation format.
• Small details like updating the linter rules, altering contributing documentation, etc.

It's all a ton of work, and your help is not only welcome, but much needed. Rewrite a function, improve a doc, contribute ideas.

Why not migrate all at once?

That is the question we've asked ourselves when we just started thinking about the problem. The answer was "why the hell not," and we did indeed attempted that. It didn't take much to convert a big chunk of the code to TypeScript, but it was tedious to polish the changes, fix endless type errors, and it was only beginning because before release, we had to adjust the build system. And all that given that PRs are keep coming meaning, more code to convert, adapt, and rebase.

To avoid the situation we did put ourselves with v2, I decided to opt for gradual migration.

It will take more time before we finish and will be able to benefit from the migration, but it will ensure that we can proceed with adding new functions, introducing fixes, and not burning out in the process.

Recap

After we have done, date-fns will become lighter, faster, and safer.

Unfortunately, it will raise a bar for new contributors not familiar with TypeScript, but that's a tradeoff I think worth making.

Please don't hesitate to ask any questions or sharing your opinion.

[numToStr]

date-fns will become lighter, faster, and safer.

This line made my day ❤️. I love to use date-fns and seeing it lagging behind moment in performance is kinda sad. But anyways, I think v3 is gonna be 🔥.

[kossnocorp]

Thank you for saying it!

Btw, date-fns should be faster than Moment.js in most cases, and if you know when it's behind - please share so that we can investigate.

[numToStr]

I read this thread by material-ui-pickers maintainer. And some benchmarks he showed.

IDK how much these saying are based on real-world use cases.

[kossnocorp]

Thank you for sharing it.

Even though the thread is very biased and attempts to bash date-fns no matter what (e.g., argument that the build size is large is invalid, but I don't care enough to argue), the benchmark seems alright. Like you, I'm not sure how it applies to the real-life and how much of an issue is that. Either way, formatting is behind (yet still proud second), but in the rest category is the first.

[imballinst]

Yay! I think this is a really good move, and I'm also excited to see it happen. 🎉

Unfortunately, it will raise a bar for new contributors not familiar with TypeScript, but that's a tradeoff I think worth making.

Agree. But, I guess we will not be heading to a-very-advanced TypeScript approach (like generics and stuff)? So probably it's not going to be that... high (?) What do you think?

[kossnocorp]

No, I don't expect the codebase to have generics, at least in the draft version, there was none. So it will be pretty basic, but I still think that it will turn off some people.

[Brianzchen]

@kossnocorp With this move, date-fns current ships flow definitions for consumers of the lib. Is the expectation that you will continue to ship these or will we need to migrate to defs coming from flow-typed eventually?

[kossnocorp]

We'll continue generating flow definitions, this time from TypeScript, which will make those only better.

(posted this before via email client and GH discussions didn't attach my reply properly)