SoFunction
Updated on 2025-03-04

Question analysis Do TypeScript still need if there is JSDoc?

introduction

Does this sound familiar: you want to write a small script, whether it is for a page, a command line tool, or something else. You start with JavaScript until you think of how painful it is to not have a type when writing code. So you put the file from.jsRename to.ts. Then realize that you have turned on a troublesome thing.

If you are writing code for a website or library, you need to introduce compilation steps. If you're writing CLI scripts, you can turn to Deno (it supports TypeScript and works out of the box), but you need to set up your IDE to understand Deno's API, and mixing and matching Deno and nodes isn't always that easy.

Once you have done all the work locally, you need to think about how to distribute your code. You'll check what you compiled.jsFile? You will create a CI pipeline to automatically compile your.tsFile? If you are writing a library, how do you publish your library so that it can be used by other projects?

You don't actually need TypeScript

The problem is...you don't need to write TypeScript to get static type analysis!

You can get all the benefits of TypeScript in JavaScript by using JSDoc

TypeScript provides a static type system. This means that the type information has no effect in running the code. When your TypeScript is executed, all type information is completely lost (this is why you can't test whether a variable is a certain type without writing a type guard).

This also means that TypeScript is just extra type information provided to the TypeScript analyzer and has no meaning to the JavaScript engine that runs your code. When you compile TypeScript into JavaScript, it basically just removes all the type information from your code, so it becomes valid JavaScript code again.

JSDoc

More than 25 years after JavaScript was born, JSDoc was introduced as a way to annotate JavaScript code. It is a formal markup language that allows the IDE to provide additional context when the developer sees a function.

Similar comment tags exist in most languages, and I believe you already know it. This is what it looks like:

/**
 * This is the JSDOC block. IDEs will show this text when you hover the
 * printName function.
 *
 * @param {string} name
 */
function printName(name) {
  (name)
}

TypeScript and JSDoc

What few people know is that JSDoc is what you need to use TypeScript as a fuller. TypeScript analyzer can understand the types written in JSDoc and provide you with.tsFiles are the same static analysis.

I won't provide the full syntax documentation here. The most important thing is that you know that almost all you can do in.tsYou can do everything in the file with JSDoc. But here are a few examples:

Function parameters with native type:

/**
 * @param {string} a
 * @param {number} b
 */
function foo(a, b) {}

Use the types out of the box provided by TypeScript:

/**
 * @param {HTMLElement} element
 * @param {Window} window
 */
function foo(element, window) {}

/** @type {number[]} */
let years

Define object literals and functions:

/** @type {{ name: string; age: number }} */
let person
/** @type {(s: string, b: boolean) => void} */
let myCallback

from*.Import type in the file:

/** @param {import('./types').User} user */
const deleteUser = (user) => {}

Define a type for later use:

/**
 * @typedef {object} Color
 * @property {number} chroma
 * @property {number} hue
 */

/** @type {Color[]} */
const colors = [
  { chroma: 0.2, hue: 262 },
  { chroma: 0.2, hue: 28.3 },
]

See the official TypeScript JSDocdocumentfor a detailed list.

If you have complex types, you can still write yours*.and import them in your JSDoc comments.

Note that you still need to set up your project (and IDE) for typescript, you need to create oneFile, compiler optionsallowJsandcheckJsSet astrue：

// 
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true
    // ...
  }
}

When to write TypeScript

While it is possible to use JSDoc for type declarations entirely, this is not the most convenient. TypeScript's syntax is much better and less repetitive.

The TypeScript team created a "type as annotation"ECMAScript Proposal, allowing you to write TypeScript and run it in the JavaScript engine without modification (the JavaScript engine will treat these types of comments as comments.)

But before this proposal is accepted, we can only decide to use JSDoc or TypeScript toolchain.

suggestion

So now my suggestion is this:

  • There is no harm in using TypeScript when you are working on a project with compilation steps
  • But if you don't need the compilation steps, it may be easier to stick to JSDoc type annotations.

Original translation from/blog/full-type-support-with-plain-javascript

The above is the detailed content of the problem analysis whether JSDoc still needs TypeScript. For more information about JSDoc TypeScript analysis, please pay attention to my other related articles!