Consider using TypeScript for 4.0

The idea to use a transpiler (Babel) in 4.0 has been brought up numerous times (also as the idea of using coroutines). If Sequelize is going to use Babel, that would allow to use new features like classes without raising Node version requirement at the cost of an transpilation step and worse performance compared to native classes/arrow functions/etc. In my opinion that transpilation step is not worth it if it doesn’t provide any real benefit other than better BC. However, one transpiler would hugely benefit Sequelize, and that is TypeScript. Sequelize has a huge code base. Understanding it (especially for new contributors), preventing bugs (mistyped method name, types, members, params etc), and documenting all the options with JSDoc is extremely hard.

Why I think 4.0 should use TypeScript:

• Clear declaration of class members, exports and parameter types
• Catch errors like wrong methods, types or params at compile time
• Awesome Autocompletion support for contributors, maintainers and users of Sequelize
• Direct output of .d.ts files instead of third-party
• Beautiful documentation with typedoc
• Instead of specifying nested params in docblocks like @param {(string|Model)} options.include[].model over and over for every variation of the find() method, we could define interfaces that can be used for all the methods and documented individually. There will never be undocumented options, because to prevent a compile-time error that option has to be defined and then it will also appear in the docs.
• Supports async/await
• TypeScript is a superset of JavaScript. Every JS code is already valid TS code. The learning curve is very little, it’s just JS with typing on top
• The type system is extremely flexible, even the association mixins can be modeled

What do you think?

[janmeier]

While I definitely see the merits of more magic documentation, and making it easier for typescript users to use sequelize, we have opted not to have a transpilation step in 4.0 - neither babel nor typescript.

The reasoning is two-fold - for one, it creates a lower barrier of entry for new developers, they don’t have to learn new syntax (I know typescript is a superset, so they could still write in plain JS, but they would still have to understand existing ts code). Secondly, we want to make it possible users to install directly from git (i.e. poiniting their package.json file directly at a specific commit) - which is not possible if we have a transpilation step.

[SimonSchick]

The main difference would be that the typings are always (or almost always) completely up to date with the sequelize implementation.

In 99% of the cases adding new types is also really trivial, I’ve not seen any recent changes (ignoring v4) that require complex typings.

I do agree that some of the current API is difficult to type, especially the magic association functions that are added on the fly, but ~95% of the sequelize API is relatively trivial to define in typescript, when in doubt you can always any that and let a contributor deal with it, worst case you have the same type safety as using JS.

It also should be noted that @types/sequelize doesn’t play well with v4 as they do not have any class definitions. https://github.com/types/sequelize/commits/master are the de-facto v4 typings (however they conflict with the typings of umzug as these depend of @types). I’ve seen numerous people trying to use @types/sequelize with v4 which lead to really confusing results at times.