Here are some notable differences on how checking works in .js files compared to .ts files.
ES2015 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.
\njsclassTryC {\n constructor() {\n this.constructorOnly = 0;\n this.constructorUnknown =undefined ;\n }\nmethod () {\n this.constructorOnly = false;\nType 'boolean' is not assignable to type 'number'.2322Type 'boolean' is not assignable to type 'number'. this.constructorUnknown = \"plunkbat\"; // ok, constructorUnknown is string | undefined\n this.methodOnly = \"ok\"; // ok, but methodOnly could also be undefined\n }\nmethod2 () {\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\njsclassTryC {\n constructor() {\n /** @type {number | undefined} */\n this.prop =undefined ;\n /** @type {number | undefined} */\n this.count ;\n }\n}\n\nletc = newC ();\nc .prop = 0; // OK\nc .count = \"string\";\nType '\"string\"' is not assignable to type 'number | undefined'.2322Type '\"string\"' is not assignable to type '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\njsfunctionTryC () {\nthis .constructorOnly = 0;\n'this' implicitly has type 'any' because it does not have a type annotation.2683'this' implicitly has type 'any' because it does not have a type annotation.this .constructorUnknown =undefined ;\n'this' implicitly has type 'any' because it does not have a type annotation.2683'this' implicitly has type 'any' because it does not have a type annotation.}\nC .prototype .method = function () {\n this.constructorOnly = false;\nType 'boolean' is not assignable to type 'number'.2322Type 'boolean' is not assignable to type 'number'. 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:
\njsclassTryC {}\nC .D = class {};
And, for pre-ES2015 code, it can be used to simulate static methods:
\n\njsfunctionTryOuter () {\n this.y = 2;\n}\n\nOuter .Inner = function () {\n this.yy = 2;\n};\n\nOuter .innter ();
It can also be used to create simple namespaces:
\n\njsvarTryns = {};\nns .C = class {};\nns .func = function () {};\n\nns ;
Other variants are allowed as well:
\n\njs// IIFE\nvarTryns = (function (n ) {\n returnn || {};\n})();\nns .CONST = 1;\n\n// defaulting to global\nvarassign =\nassign ||\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:
\njsvarTryobj = {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}} */\nvarTryobj = {a : 1 };\nobj .= 2;\nProperty 'b' does not exist on type '{ a: number; }'.2339Property 'b' does not exist on type '{ a: number; }'. 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\njsfunctionTryFoo (i = null) {\n if (!i )i = 1;\n varj =undefined ;\nj = 2;\n this.l = [];\n}\n\nvarfoo = newFoo ();\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\njsfunctionTrybar (a ,b ) {\nconsole .log (a + \" \" +b );\n}\n\nbar (1); // OK, second argument considered optional\nbar (1, 2);\nbar (1, 2,3 ); // Error, too many arguments\nExpected 0-2 arguments, but got 3.2554Expected 0-2 arguments, but got 3.
JSDoc annotated functions are excluded from this rule.\nUse JSDoc optional parameter syntax ([ ]) to express optionality. e.g.:
\njs/**\n * @param {string} [somebody] - Somebody's name.\n */\nfunctionTrysayHello (somebody ) {\n if (!somebody ) {\nsomebody = \"John Doe\";\n }\nconsole .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 */\nfunctionTrysum (/* numbers */) {\n vartotal = 0;\n for (vari = 0;i <arguments .length ;i ++) {\ntotal +=arguments [i ];\n }\n returntotal ;\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} */\nvarTryx = [];\n\nx .push (1); // OK\nx .push (\"string\"); // OK, x is of type Array<any>\n\n/** @type{Array.<number>} */\nvary = [];\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>;
To learn all of the features available in JSDoc, see the reference.
","headings":[{"value":"Properties are inferred from assignments in class bodies","depth":2},{"value":"Constructor functions are equivalent to classes","depth":2},{"value":"CommonJS modules are supported","depth":2},{"value":"Classes, functions, and object literals are namespaces","depth":2},{"value":"Object literals are open-ended","depth":2},{"value":"null, undefined, and empty array initializers are of type any or any[]","depth":2},{"value":"Function parameters are optional by default","depth":2},{"value":"Var-args parameter declaration inferred from use of arguments","depth":2},{"value":"Unspecified type parameters default to any","depth":2},{"value":"In extends clause","depth":3},{"value":"In JSDoc references","depth":3},{"value":"In function calls","depth":3}],"frontmatter":{"permalink":"/docs/handbook/type-checking-javascript-files.html","title":"Type Checking JavaScript Files","disable_toc":null,"oneline":"How to add type checking to JavaScript files using TypeScript"}},"prev":{"childMarkdownRemark":{"frontmatter":{"title":"JS Projects Utilizing TypeScript","oneline":"How to add type checking to JavaScript files using TypeScript","permalink":"/docs/handbook/intro-to-js-ts.html"}}},"next":{"childMarkdownRemark":{"frontmatter":{"title":"JSDoc Reference","oneline":"What JSDoc does TypeScript-powered JavaScript support?","permalink":"/docs/handbook/jsdoc-supported-types.html"}}}},"pageContext":{"id":"type-checking-javascript-files","slug":"/docs/handbook/type-checking-javascript-files.html","repoPath":"/packages/documentation/copy/en/javascript/Type Checking JavaScript Files.md","previousID":"2ae8d451-c272-55d5-ba61-816453b84a6a","nextID":"d848604c-bb7a-5209-9b14-87b5d859b2fc","lang":"en","modifiedTime":"2020-08-18T13:59:43.508Z"}}}