TypeScript 2.3 and later support type-checking and reporting errors in .js files with --checkJs.
You can skip checking some files by adding a // @ts-nocheck comment to them; conversely, you can choose to check only a few .js files by adding a // @ts-check comment to them without setting --checkJs.\nYou can also ignore errors on specific lines by adding // @ts-ignore on the preceding line.\nNote that if you have a tsconfig.json, JS checking will respect strict flags like noImplicitAny, strictNullChecks, etc.\nHowever, because of the relative looseness of JS checking, combining strict flags with it may be surprising.
Here are some notable differences on how checking works in .js files compared to .ts files:
In a .js file, types can often be inferred just like in .ts files.\nLikewise, when types can’t be inferred, they can be specified using JSDoc the same way that type annotations are used in a .ts file.\nJust like Typescript, --noImplicitAny will give you errors on the places that the compiler could not infer a type.\n(With the exception of open-ended object literals; see below for details.)
JSDoc annotations adorning a declaration will be used to set the type of that declaration. For example:
\n\njs/** @type {number} */\nvar x;\n\nx = 0; // OK\nx = false; // Error: boolean is not assignable to number
You can find the full list of supported JSDoc patterns below.
\nES2015 does not have a means for declaring properties on classes. Properties are dynamically assigned, just like object literals.
\nIn a .js file, the compiler infers properties from property assignments inside the class body.\nThe type of a property is the type given in the constructor, unless it’s not defined there, or the type in the constructor is undefined or null.\nIn that case, the type is the union of the types of all the right-hand values in these assignments.\nProperties defined in the constructor are always assumed to exist, whereas ones defined just in methods, getters, or setters are considered optional.
\njsclass C {\n constructor() {\n this.constructorOnly = 0;\n this.constructorUnknown = undefined;\n }\n method() {\n this.constructorOnly = false; // error, constructorOnly is a number\n this.constructorUnknown = \"plunkbat\"; // ok, constructorUnknown is string | undefined\n this.methodOnly = \"ok\"; // ok, but methodOnly could also be undefined\n }\n method2() {\n this.methodOnly = true; // also, ok, methodOnly's type is string | boolean | undefined\n }\n}
If properties are never set in the class body, they are considered unknown.\nIf your class has properties that are only read from, add and then annotate a declaration in the constructor with JSDoc to specify the type.\nYou don’t even have to give a value if it will be initialised later:
\n\njsclass C {\n constructor() {\n /** @type {number | undefined} */\n this.prop = undefined;\n /** @type {number | undefined} */\n this.count;\n }\n}\n\nlet c = new C();\nc.prop = 0; // OK\nc.count = \"string\"; // Error: string is not assignable to number|undefined
Before ES2015, Javascript used constructor functions instead of classes.\nThe compiler supports this pattern and understands constructor functions as equivalent to ES2015 classes.\nThe property inference rules described above work exactly the same way.
\n\njsfunction C() {\n this.constructorOnly = 0;\n this.constructorUnknown = undefined;\n}\nC.prototype.method = function() {\n this.constructorOnly = false; // error\n this.constructorUnknown = \"plunkbat\"; // OK, the type is string | undefined\n};
In a .js file, Typescript understands the CommonJS module format.\nAssignments to exports and module.exports are recognized as export declarations.\nSimilarly, require function calls are recognized as module imports. For example:
\njs// same as `import module \"fs\"`\nconst fs = require(\"fs\");\n\n// same as `export function readFile`\nmodule.exports.readFile = function(f) {\n return fs.readFileSync(f);\n};
The module support in Javascript is much more syntactically forgiving than Typescript’s module support.\nMost combinations of assignments and declarations are supported.
\nClasses are namespaces in .js files.\nThis can be used to nest classes, for example:
\njsclass C {}\nC.D = class {};
And, for pre-ES2015 code, it can be used to simulate static methods:
\n\njsfunction Outer() {\n this.y = 2;\n}\nOuter.Inner = function() {\n this.yy = 2;\n};
It can also be used to create simple namespaces:
\n\njsvar ns = {};\nns.C = class {};\nns.func = function() {};
Other variants are allowed as well:
\n\njs// IIFE\nvar ns = (function(n) {\n return n || {};\n})();\nns.CONST = 1;\n\n// defaulting to global\nvar assign =\n assign ||\n function() {\n // code goes here\n };\nassign.extra = 1;
In a .ts file, an object literal that initializes a variable declaration gives its type to the declaration.\nNo new members can be added that were not specified in the original literal.\nThis rule is relaxed in a .js file; object literals have an open-ended type (an index signature) that allows adding and looking up properties that were not defined originally.\nFor instance:
\njsvar obj = { a: 1 };\nobj.b = 2; // Allowed
Object literals behave as if they have an index signature [x:string]: any that allows them to be treated as open maps instead of closed objects.
Like other special JS checking behaviors, this behavior can be changed by specifying a JSDoc type for the variable. For example:
\n\njs/** @type {{a: number}} */\nvar obj = { a: 1 };\nobj.b = 2; // Error, type {a: number} does not have property b
Any variable, parameter or property that is initialized with null or undefined will have type any, even if strict null checks is turned on.\nAny variable, parameter or property that is initialized with [] will have type any[], even if strict null checks is turned on.\nThe only exception is for properties that have multiple initializers as described above.
\n\njsfunction Foo(i = null) {\n if (!i) i = 1;\n var j = undefined;\n j = 2;\n this.l = [];\n}\nvar foo = new Foo();\nfoo.l.push(foo.i);\nfoo.l.push(\"end\");
Since there is no way to specify optionality on parameters in pre-ES2015 Javascript, all function parameters in .js file are considered optional.\nCalls with fewer arguments than the declared number of parameters are allowed.
It is important to note that it is an error to call a function with too many arguments.
\nFor instance:
\n\njsfunction bar(a, b) {\n console.log(a + \" \" + b);\n}\n\nbar(1); // OK, second argument considered optional\nbar(1, 2);\nbar(1, 2, 3); // Error, too many arguments
JSDoc annotated functions are excluded from this rule.\nUse JSDoc optional parameter syntax to express optionality. e.g.:
\n\njs/**\n * @param {string} [somebody] - Somebody's name.\n */\nfunction sayHello(somebody) {\n if (!somebody) {\n somebody = \"John Doe\";\n }\n console.log(\"Hello \" + somebody);\n}\n\nsayHello();
argumentsA function whose body has a reference to the arguments reference is implicitly considered to have a var-arg parameter (i.e. (...arg: any[]) => any). Use JSDoc var-arg syntax to specify the type of the arguments.
\njs/** @param {...number} args */\nfunction sum(/* numbers */) {\n var total = 0;\n for (var i = 0; i < arguments.length; i++) {\n total += arguments[i];\n }\n return total;\n}
anySince there is no natural syntax for specifying generic type parameters in Javascript, an unspecified type parameter defaults to any.
For instance, React.Component is defined to have two type parameters, Props and State.\nIn a .js file, there is no legal way to specify these in the extends clause. By default the type arguments will be any:
\njsimport { Component } from \"react\";\n\nclass MyComponent extends Component {\n render() {\n this.props.b; // Allowed, since this.props is of type any\n }\n}
Use JSDoc @augments to specify the types explicitly. for instance:
\njsimport { Component } from \"react\";\n\n/**\n * @augments {Component<{a: number}, State>}\n */\nclass MyComponent extends Component {\n render() {\n this.props.b; // Error: b does not exist on {a:number}\n }\n}
An unspecified type argument in JSDoc defaults to any:
\n\njs/** @type{Array} */\nvar x = [];\n\nx.push(1); // OK\nx.push(\"string\"); // OK, x is of type Array<any>\n\n/** @type{Array.<number>} */\nvar y = [];\n\ny.push(1); // OK\ny.push(\"string\"); // Error, string is not assignable to number
A call to a generic function uses the arguments to infer the type parameters. Sometimes this process fails to infer any types, mainly because of lack of inference sources; in these cases, the type parameters will default to any. For example:
\njsvar p = new Promise((resolve, reject) => {\n reject();\n});\n\np; // Promise<any>;
The list below outlines which constructs are currently supported when using JSDoc annotations to provide type information in JavaScript files.
\nNote any tags which are not explicitly listed below (such as @async) are not yet supported.
@type@param (or @arg or @argument)@returns (or @return)@typedef@callback@template@class (or @constructor)@this@extends (or @augments)@enumThe meaning is usually the same, or a superset, of the meaning of the tag given at usejsdoc.org.\nThe code below describes the differences and gives some example usage of each tag.
\n@typeYou can use the “@type” tag and reference a type name (either primitive, defined in a TypeScript declaration, or in a JSDoc “@typedef” tag).\nYou can use any Typescript type, and most JSDoc types.
\n\njs/**\n * @type {string}\n */\nvar s;\n\n/** @type {Window} */\nvar win;\n\n/** @type {PromiseLike<string>} */\nvar promisedString;\n\n// You can specify an HTML Element with DOM properties\n/** @type {HTMLElement} */\nvar myElement = document.querySelector(selector);\nelement.dataset.myData = \"\";
@type can specify a union type — for example, something can be either a string or a boolean.
\njs/**\n * @type {(string | boolean)}\n */\nvar sb;
Note that parentheses are optional for union types.
\n\njs/**\n * @type {string | boolean}\n */\nvar sb;
You can specify array types using a variety of syntaxes:
\n\njs/** @type {number[]} */\nvar ns;\n/** @type {Array.<number>} */\nvar nds;\n/** @type {Array<number>} */\nvar nas;
You can also specify object literal types.\nFor example, an object with properties ‘a’ (string) and ‘b’ (number) uses the following syntax:
\n\njs/** @type {{ a: string, b: number }} */\nvar var9;
You can specify map-like and array-like objects using string and number index signatures, using either standard JSDoc syntax or Typescript syntax.
\n\njs/**\n * A map-like object that maps arbitrary `string` properties to `number`s.\n *\n * @type {Object.<string, number>}\n */\nvar stringToNumber;\n\n/** @type {Object.<number, object>} */\nvar arrayLike;
The preceding two types are equivalent to the Typescript types { [x: string]: number } and { [x: number]: any }. The compiler understands both syntaxes.
You can specify function types using either Typescript or Closure syntax:
\n\njs/** @type {function(string, boolean): number} Closure syntax */\nvar sbn;\n/** @type {(s: string, b: boolean) => number} Typescript syntax */\nvar sbn2;
Or you can just use the unspecified Function type:
\njs/** @type {Function} */\nvar fn7;\n/** @type {function} */\nvar fn6;
Other types from Closure also work:
\n\njs/**\n * @type {*} - can be 'any' type\n */\nvar star;\n/**\n * @type {?} - unknown type (same as 'any')\n */\nvar question;
Typescript borrows cast syntax from Closure.\nThis lets you cast types to other types by adding a @type tag before any parenthesized expression.
\njs/**\n * @type {number | string}\n */\nvar numberOrString = Math.random() < 0.5 ? \"hello\" : 100;\nvar typeAssertedNumber = /** @type {number} */ (numberOrString);
You can also import declarations from other files using import types.\nThis syntax is Typescript-specific and differs from the JSDoc standard:
\n\njs/**\n * @param p { import(\"./a\").Pet }\n */\nfunction walk(p) {\n console.log(`Walking ${p.name}...`);\n}
import types can also be used in type alias declarations:
\n\njs/**\n * @typedef { import(\"./a\").Pet } Pet\n */\n\n/**\n * @type {Pet}\n */\nvar myPet;\nmyPet.name;
import types can be used to get the type of a value from a module if you don’t know the type, or if it has a large type that is annoying to type:
\n\njs/**\n * @type {typeof import(\"./a\").x }\n */\nvar x = require(\"./a\").x;
@param and @returns@param uses the same type syntax as @type, but adds a parameter name.\nThe parameter may also be declared optional by surrounding the name with square brackets:
\njs// Parameters may be declared in a variety of syntactic forms\n/**\n * @param {string} p1 - A string param.\n * @param {string=} p2 - An optional param (Closure syntax)\n * @param {string} [p3] - Another optional param (JSDoc syntax).\n * @param {string} [p4=\"test\"] - An optional param with a default value\n * @return {string} This is the result\n */\nfunction stringsStringStrings(p1, p2, p3, p4) {\n // TODO\n}
Likewise, for the return type of a function:
\n\njs/**\n * @return {PromiseLike<string>}\n */\nfunction ps() {}\n\n/**\n * @returns {{ a: string, b: number }} - May use '@returns' as well as '@return'\n */\nfunction ab() {}
@typedef, @callback, and @param@typedef may be used to define complex types.\nSimilar syntax works with @param.
\njs/**\n * @typedef {Object} SpecialType - creates a new type named 'SpecialType'\n * @property {string} prop1 - a string property of SpecialType\n * @property {number} prop2 - a number property of SpecialType\n * @property {number=} prop3 - an optional number property of SpecialType\n * @prop {number} [prop4] - an optional number property of SpecialType\n * @prop {number} [prop5=42] - an optional number property of SpecialType with default\n */\n/** @type {SpecialType} */\nvar specialTypeObject;
You can use either object or Object on the first line.
\njs/**\n * @typedef {object} SpecialType1 - creates a new type named 'SpecialType1'\n * @property {string} prop1 - a string property of SpecialType1\n * @property {number} prop2 - a number property of SpecialType1\n * @property {number=} prop3 - an optional number property of SpecialType1\n */\n/** @type {SpecialType1} */\nvar specialTypeObject1;
@param allows a similar syntax for one-off type specifications.\nNote that the nested property names must be prefixed with the name of the parameter:
\njs/**\n * @param {Object} options - The shape is the same as SpecialType above\n * @param {string} options.prop1\n * @param {number} options.prop2\n * @param {number=} options.prop3\n * @param {number} [options.prop4]\n * @param {number} [options.prop5=42]\n */\nfunction special(options) {\n return (options.prop4 || 1001) + options.prop5;\n}
@callback is similar to @typedef, but it specifies a function type instead of an object type:
\njs/**\n * @callback Predicate\n * @param {string} data\n * @param {number} [index]\n * @returns {boolean}\n */\n/** @type {Predicate} */\nconst ok = s => !(s.length % 2);
Of course, any of these types can be declared using Typescript syntax in a single-line @typedef:
\njs/** @typedef {{ prop1: string, prop2: string, prop3?: number }} SpecialType */\n/** @typedef {(data: string, index?: number) => boolean} Predicate */
@templateYou can declare generic types with the @template tag:
\njs/**\n * @template T\n * @param {T} x - A generic parameter that flows through to the return type\n * @return {T}\n */\nfunction id(x) {\n return x;\n}
Use comma or multiple tags to declare multiple type parameters:
\n\njs/**\n * @template T,U,V\n * @template W,X\n */
You can also specify a type constraint before the type parameter name.\nOnly the first type parameter in a list is constrained:
\n\njs/**\n * @template {string} K - K must be a string or string literal\n * @template {{ serious(): string }} Seriousalizable - must have a serious method\n * @param {K} key\n * @param {Seriousalizable} object\n */\nfunction seriousalize(key, object) {\n // ????\n}
@constructorThe compiler infers constructor functions based on this-property assignments, but you can make checking stricter and suggestions better if you add a @constructor tag:
\njs/**\n * @constructor\n * @param {number} data\n */\nfunction C(data) {\n this.size = 0;\n this.initialize(data); // Should error, initializer expects a string\n}\n/**\n * @param {string} s\n */\nC.prototype.initialize = function(s) {\n this.size = s.length;\n};\n\nvar c = new C(0);\nvar result = C(1); // C should only be called with new
With @constructor, this is checked inside the constructor function C, so you will get suggestions for the initialize method and an error if you pass it a number. You will also get an error if you call C instead of constructing it.
Unfortunately, this means that constructor functions that are also callable cannot use @constructor.
@thisThe compiler can usually figure out the type of this when it has some context to work with. When it doesn’t, you can explicitly specify the type of this with @this:
\njs/**\n * @this {HTMLElement}\n * @param {*} e\n */\nfunction callbackForLater(e) {\n this.clientHeight = parseInt(e); // should be fine!\n}
@extendsWhen Javascript classes extend a generic base class, there is nowhere to specify what the type parameter should be. The @extends tag provides a place for that type parameter:
\njs/**\n * @template T\n * @extends {Set<T>}\n */\nclass SortableSet extends Set {\n // ...\n}
Note that @extends only works with classes. Currently, there is no way for a constructor function extend a class.
@enumThe @enum tag allows you to create an object literal whose members are all of a specified type. Unlike most object literals in Javascript, it does not allow other members.
\njs/** @enum {number} */\nconst JSDocState = {\n BeginningOfLine: 0,\n SawAsterisk: 1,\n SavingComments: 2\n};
Note that @enum is quite different from, and much simpler than, Typescript’s enum. However, unlike Typescript’s enums, @enum can have any type:
\njs/** @enum {function(number): number} */\nconst Math = {\n add1: n => n + 1,\n id: n => -n,\n sub1: n => n - 1\n};
\njsvar someObj = {\n /**\n * @param {string} param1 - Docs on property assignments work\n */\n x: function(param1) {}\n};\n\n/**\n * As do docs on variable assignments\n * @return {Window}\n */\nlet someFunc = function() {};\n\n/**\n * And class methods\n * @param {string} greeting The greeting to use\n */\nFoo.prototype.sayHi = greeting => console.log(\"Hi!\");\n\n/**\n * And arrow functions expressions\n * @param {number} x - A multiplier\n */\nlet myArrow = x => x * x;\n\n/**\n * Which means it works for stateless function components in JSX too\n * @param {{a: string, b: number}} test - Some param\n */\nvar fc = test => <div>{test.a.charAt(0)}</div>;\n\n/**\n * A parameter can be a class constructor, using Closure syntax.\n *\n * @param {{new(...args: any[]): object}} C - The class to register\n */\nfunction registerClass(C) {}\n\n/**\n * @param {...string} p1 - A 'rest' arg (array) of strings. (treated as 'any')\n */\nfunction fn10(p1) {}\n\n/**\n * @param {...string} p1 - A 'rest' arg (array) of strings. (treated as 'any')\n */\nfunction fn9(p1) {\n return p1.join();\n}
Referring to objects in the value space as types doesn’t work unless the object also creates a type, like a constructor function.
\n\njsfunction aNormalFunction() {}\n/**\n * @type {aNormalFunction}\n */\nvar wrong;\n/**\n * Use 'typeof' instead:\n * @type {typeof aNormalFunction}\n */\nvar right;
Postfix equals on a property type in an object literal type doesn’t specify an optional property:
\n\njs/**\n * @type {{ a: string, b: number= }}\n */\nvar wrong;\n/**\n * Use postfix question on the property name instead:\n * @type {{ a: string, b?: number }}\n */\nvar right;
Nullable types only have meaning if strictNullChecks is on:
\njs/**\n * @type {?number}\n * With strictNullChecks: true -- number | null\n * With strictNullChecks: off -- number\n */\nvar nullable;
Non-nullable types have no meaning and are treated just as their original type:
\n\njs/**\n * @type {!number}\n * Just has type number\n */\nvar normal;
Unlike JSDoc’s type system, Typescript only allows you to mark types as containing null or not.\nThere is no explicit non-nullability — if strictNullChecks is on, then number is not nullable.\nIf it is off, then number is nullable.