JSDoc as an alternative TypeScript syntaxFebruary 24, 2024As web development has embraced static typing during the past decade, TypeScript has become the default language of choice. I think this is great—I love working with TypeScript!But what if you can’t use TypeScript? You may encounter circumstances where you need to work in plain JavaScript, be it tooling constraints or a team member who does not like static typing.Under these circumstances, look to JSDoc for salvation:/** * @param {number} a * @param {number} b * @returns {number} */function add(a, b) { return a + b;}I was surprised when I learned that the TypeScript compiler actually understands JSDoc comments. This fact allows you to type your entire codebase without creating a single .ts file.Think of this post as your crash course in using JSDoc as an alternative syntax for TypeScript. We’ll cover all the important TypeScript-related features JSDoc has to offer—and their limitations.JSDocJSDoc is expressed through block comments in the form /** */, which may contain block tags such as @param and @type. Normal // and /* */ comments don’t work:// @type {number}let a; // Doesn't work
/* @type {number} */let b; // Doesn't work
/*** @type {number} */let c; // Doesn't work
/** @type {number} */let d; // Works!The majority of your JSDoc block tags will be used for typing variables, arguments, and return types. The block tags for those are @type, @param, and @returns./** * @param {string} message * @returns {number} */function len(message) { return message.length;}
/** @type {{ name: string, age: number }} */const user = { name: "Alex", age: 26,};Type castingType casting in TypeScript can be done using expression as T or <T>expression:function example(arg: unknown) { const num = arg as number; const str = <string>arg;}Type casting in JSDoc is done by wrapping the expression in parentheses and adding a preceding @type comment:/** @param {number} num */const square = (num) => num * num;
/** @param {unknown} arg */function example(arg) { const num = /** @type {number} */ (arg); return square(num); // OK!}The parentheses are required. If they are missing the cast will not work:/** @param {number} num */const square = (num) => num * num;
/** @param {unknown} arg */function example(arg) { const num = /** @type {number} */ arg; return square(num); // Argument of type 'unknown' is not assignable to parameter of type 'number'.}Missing parentheses are a really easy mistake to make, which can easily lead to bugs when casting from any. Be careful with casts in JSDoc!Const assertionsTypeScript supports const assertions, which can be quite useful.function resize(options: { size: 1 | 2 }) { // ...}
const a = { size: 1 as const };const b = { size: 2 };
resize(a); // OKresize(b); // Types of property 'size' are incompatible. // Type 'number' is not assignable to type '1 | 2'.You can also use const assertions in JSDoc, they’re just a type cast:/** * @param {{ size: 1 | 2 }} options */function resize(options) { // ...}
const a = { size: /** @type {const} */ (1) };const b = { size: 2 };
resize(a); // OKresize(b); // Types of property 'size' are incompatible. // Type 'number' is not assignable to type '1 | 2'.Declaring typesIn TypeScript, you can declare types using the