“We will be able to quickly migrate to TypeScript, after which. . . ” How steadily do you listen this word? Possibly, for those who principally paintings inside of a unmarried challenge or most commonly simply get started new tasks from scratch, this can be a quite uncommon expression so that you can listen. For me, as any person running in an outsourcing corporate, who, along with my primary challenge, sees dozens of more than a few different tasks each month, this is a moderately not unusual word from the advance crew or a consumer who want to improve their challenge stack for more straightforward crew collaboration. Spoiler alert: it may not be going to be as quickly of a transition as you suppose (possibly, by no means).

Whilst it’ll sound drastic, in maximum circumstances, this may occasionally certainly be the case. Most of the people who’ve no longer passed through the sort of transition might not be conscious about the handfuls of nuances that may stand up all the way through a challenge migration to TypeScript. For example, are you ready for the likelihood that your challenge construct, which took tens of seconds in natural JavaScript, may unexpectedly get started taking tens of mins when the use of TypeScript? After all, it depends upon your challenge’s measurement, your pipeline configuration, and many others., however those situations aren’t fabricated. You, as a developer, may well be ready for this inevitability, however what is going to your consumer suppose whilst you inform them that the price range for the server example must be larger for the reason that challenge construct is now failing because of a heap out-of-memory error after including TypeScript to the challenge? Sure, TypeScript, like another device, isn’t unfastened.

At the Web, you’ll in finding a lot of articles about how main firms effectively migrated their tasks from natural JavaScript to TypeScript. Whilst they normally describe a large number of the problems they’d all the way through the transition and the way they overcame them, there are nonetheless many unstated hindrances that individuals can come across which is able to change into vital in your migration.

Regardless of the attention amongst maximum groups that including typing to their tasks via migration to TypeScript may no longer continue as easily as depicted in more than a few articles, they nonetheless imagine TypeScript because the unique and definitive way to cope with typing problems of their tasks. This mindset may end up in tasks last in natural JavaScript for prolonged sessions, and the eagerly expected typing stays confined to the world of goals. Whilst choice equipment for introducing typing to JavaScript code do exist, TypeScript’s overwhelming reputation steadily casts them into the shadows. This in style acclaim, justified via the TypeScript crew’s energetic building, would possibly, then again, turn out disadvantageous to builders. Builders generally tend to lean against the belief that TypeScript is the best way to typing demanding situations in a challenge, neglecting different choices.

Subsequent, we will be able to imagine JSDoc as a device that, when used accurately and understood along with different equipment (like TypeScript), can lend a hand cope with the typing factor in a challenge nearly at no cost. Many may suppose that the capability of JSDoc pales compared to TypeScript, and evaluating them is arbitrary. To a point, this is true, however however, it depends upon the standpoint. Each and every generation has its professionals and cons, counterbalancing the opposite.

Code examples will illustrate a type of swish degradation from TypeScript to JavaScript whilst keeping up typing capability. Whilst for some, this may seem as a type of innovative enhancement, once more, all of it depends upon the way you take a look at it.

JSDoc and Its Extensions

JSDoc is a specification for the remark layout in JavaScript. This specification permits builders to explain the construction in their code, information sorts, operate parameters, and a lot more the use of particular feedback. Those feedback can then be reworked into documentation the use of suitable equipment.

/**
 * Provides two numbers.
 * @param {quantity} a - The primary quantity.
 * @param {quantity} b - The second one quantity.
 * @returns {quantity} The sum of the 2 numbers.
 */
const getSum = (a, b) => {
  go back a + b
}

Essentially the most well known equipment that depend on JSDoc are Closure Compiler (to not be puzzled with the Closure programming language) and TypeScript. Either one of those equipment can help in making your JavaScript typed, however they means it otherwise. Closure Compiler basically specializes in improving your .js information via including typing via JSDoc annotations (in the end, they’re simply feedback), whilst TypeScript is designed for .ts information, introducing its personal well known TypeScript constructs similar to variety, interface, enum, namespace, and so forth.

Now not from its inception, however ranging from model 2.3, TypeScript started permitting one thing very similar to Closure Compiler – checking variety annotations in .js information in keeping with the usage of JSDoc syntax. With this model, and with each and every next model, TypeScript no longer best added make stronger for JSDoc but additionally integrated lots of the core tags and constructs provide within the Closure Compiler. This made migration to TypeScript more uncomplicated. Whilst Closure Compiler remains to be being up to date, utilized by some groups, and stays top-of-the-line device for code compression in JavaScript (if its laws are adopted), because of make stronger for checking .js information and more than a few different updates introduced via the TypeScript crew, Closure Compiler ultimately misplaced to TypeScript.

From the implementation standpoint, incorporating an figuring out of JSDoc notation into TypeScript isn’t a basic exchange. If it is TypeScript sorts or JSDoc sorts, in the end, they each change into a part of the AST (Summary Syntax Tree) of the completed program. That is handy for us as builders as a result of all our on a regular basis equipment, similar to ESLint (together with all its plugins), Prettier, and others basically depend at the AST. Due to this fact, irrespective of the report extensions we use, our favourite plugins can proceed to paintings in each .js and .ts information (with some exceptions, in fact).

Developer Revel in

When including typing to JavaScript code the use of JSDoc, you’ll want to use further equipment that strengthen the advance revel in.

eslint-plugin-jsdoc is a JSDoc plugin for ESLint. This plugin stories mistakes in case of invalid JSDoc syntax utilization and is helping standardize the written JSDoc. Crucial environment for this plugin is the mode possibility, which provides some of the following values: typescript, closure (regarding Closure Compiler), or jsdoc. As discussed previous, JSDoc can range, and this feature means that you can specify which JSDoc tags and syntax to make use of. The default price is typescript (despite the fact that this has no longer at all times been the case), which, given TypeScript’s dominance over different equipment that paintings with JSDoc, turns out like a good selection.

It’s also essential to make a choice a device for inspecting the sort annotations written in JSDoc, and on this case, it’ll be TypeScript. This may sound bizarre as a result of, on this article, it kind of feels like we’re discussing its substitute. Then again, we aren’t the use of TypeScript for its number one objective – our information nonetheless have the .js extension. We will be able to best use TypeScript as a kind checking linter. In maximum tasks the place TypeScript is used totally, there may be usually a construct script chargeable for compiling .ts information into .js. Relating to the use of TypeScript as a linting device, as an alternative of a constructcommand dealing with compilation, you’re going to have a command for linting your sorts.

// bundle.json

{
  "scripts": {
       "lint:variety": "tsc --noEmit"
  }
}

To make this script paintings accurately, you wish to have to create a tsconfig.json report for your challenge or upload further parameters to this script. Those parameters come with allowJs and checkJs, which permit TypeScript to test code written in .js information. Along with those parameters, you’ll allow many others. For instance, to make variety checking stricter, you’ll use strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, noPropertyAccessFromIndexSignature, and extra. TypeScript will carefully take a look at your code despite the fact that you might be the use of .js information.

The TypeScript crew persistently complements the capability of TypeScript when running with JSDoc. With nearly each liberate, they introduce each fixes and new options. The similar applies to code editors. Syntax highlighting and different DX options supplied via TypeScript when running with .ts information additionally paintings when coping with .js information the use of JSDoc. Even if there are occasional cases the place make stronger for sure JSDoc options would possibly come later, many GitHub problems categorised with JSDoc within the TypeScript backlog point out that the TypeScript crew continues to paintings on bettering JSDoc make stronger.

Many may point out the nuance that after the use of TypeScript only for .js information, you might be disadvantaged of the power to make use of further constructs supplied via TypeScript; for instance, Enums, Namespaces, Elegance Parameter Homes, Summary Categories and Contributors, Experimental (!) Decorators, and others, as their syntax is best to be had in information with the .ts extension.

Once more, for some, this may occasionally appear to be an obstacle, however for others, it might be thought to be a receive advantages, as a majority of these constructs have their drawbacks. Essentially, all the way through TypeScript compilation to JavaScript, anything else associated with sorts merely disappears. Relating to the use of the aforementioned constructs, they all are translated into less-than-optimal JavaScript code. If this doesn’t sound compelling sufficient so that you can chorus from the use of them, you’ll discover the downsides of each and every of those constructs by yourself, as there are many articles at the Web discussing those problems.

Total, the usage of those constructs is in most cases thought to be an anti-pattern. On maximum of my tasks the place I exploit TypeScript to its complete extent (with all my code living in .ts information), I at all times use a customized ESLint rule:

// eslint.config.js

/** @variety {import('eslint').Linter.FlatConfig} */
const config = {
  laws: {
    'no-restricted-syntax': [
      'error',
      {
        selector: 'TSEnumDeclaration,TSModuleDeclaration,TSParameterProperty,ClassDeclaration[abstract=true],Decorator',
        message: 'TypeScript shit is forbidden.',
      },
    ],
  },
}

This rule prohibits the usage of TypeScript constructs that carry issues.

When bearing in mind what stays of TypeScript when making use of this ESLint rule, necessarily, best the typing side stays. On this context, when the use of this rule, leveraging JSDoc tags and syntax supplied via TypeScript for including typing to .js information is nearly indistinguishable from the use of TypeScript with .ts information.

As discussed previous, maximum equipment depend on AST for his or her operations, together with TypeScript. TypeScript does no longer care whether or not you outline sorts the use of TypeScript’s key phrases and syntax or JSDoc tags supported via TypeScript. This idea additionally applies to ESLint and its plugins, together with the typescript-eslint plugin. Because of this we will be able to use this plugin and its tough laws to test typing despite the fact that all of the code is written in .js information (supplied you enabled the suitable parser).

Sadly, an important problem when the use of those equipment with .js information is that some portions of those equipment, similar to explicit laws in typescript-eslint, depend on the usage of explicit TypeScript key phrases. Examples of such laws come with explicit-function-return-type, explicit-member-accessibility, no-unsafe-return, and others which might be tied explicitly to TypeScript key phrases. Thankfully, there aren’t many such laws. Even if those laws might be rewritten to make use of AST, the advance groups at the back of those laws are these days reluctant to take action because of the larger complexity of make stronger when transitioning from the use of key phrases to AST.

Conclusion

JSDoc, when used along TypeScript as a linting device, supplies builders with a formidable manner of typing .js information. Its capability does no longer lag considerably at the back of TypeScript when used to its complete possible, retaining the entire code in .ts information. Using JSDoc permits builders to introduce typing right into a natural JavaScript challenge presently, with out delaying it as dream of a complete migration to TypeScript (which possibly won’t ever occur).

Many mistakenly spend an excessive amount of time critiquing the JSDoc syntax, deeming it unsightly, particularly when in comparison to TypeScript. It’s onerous to argue differently, TypeScript’s syntax does certainly glance a lot more concise. Then again, what’s really a mistake is enticing in empty discussions about syntax as an alternative of taking any motion. Finally, you’re going to most definitely wish to succeed in a identical end result, as proven within the screenshot underneath. Acting the sort of migration is considerably more straightforward and extra possible when transitioning from code that already has typing written in JSDoc.

Through the way in which, many that label the JSDoc syntax as unsightly, whilst the use of TypeScript as their sole number one device, after such remarks, nonchalantly go back to their .ts information, totally embracing TS Enums, TS Parameter Homes, TS Experimental (!) Decorators, and different TS constructs that may carry questions. Do they really imagine they’re at the proper facet?

Many of the screenshots had been taken from the migration of .ts information to .js whilst keeping variety capability in my library form-payload (this is the PR). Why did I make a decision to make this migration? As a result of I sought after to. Even if that is a ways from my best revel in with such migrations. Curiously, the perimeters of migrations steadily exchange (migrations from .js to .ts for sure happen extra incessantly). Regardless of my affection for TypeScript and its concise syntax, after a number of dozen information written/rewritten the use of JSDoc, I finished feeling any specific aversion to the JSDoc syntax, as it’s simply syntax.

Summing Up

JSDoc supplies builders with actual alternatives for regularly bettering the codebase with out requiring a whole transition to TypeScript from the beginning of migration. It is very important to understand that the hot button is to not pray to the TypeScript-god however to begin taking motion. Without equal transition to the use of TypeScript totally is imaginable, however you may additionally notice that JSDoc is greater than enough for a hit building, because it has its benefits. For instance, here’s what a “JSDoc-compiler” may seem like:

// bundler.js

anticipate esbuild.construct({
  entryPoints: [jsMainEntryPoint],
  minify: true, // ✓
})