使javascript文件知道其打字稿定义文件

Question

Typescript allows you to write .d.ts definition files for your local javascript files like so:

src/
  main.js
  imported.js
  imported.d.ts

main.js

import { func } from './imported';
console.log(func("1", "1"));

imported.js

export const func = (numVal, strVal) =>
  `The number is ${numVal}, the string is ${strVal}`;

imported.d.ts

export const func: (numVal: number, strVal: string) => string;

This gives the following errors, with the option noImplicitAny :

src/imported.js(1,22): error TS7006: Parameter 'numVal' implicitly has an 'any' type.
src/imported.js(1,30): error TS7006: Parameter 'strVal' implicitly has an 'any' type.
src/main.js(3,18): error TS2345: Argument of type '"1"' is not assignable to parameter of type 'number'.

The last error is good, that's stopping us from passing a string when we should have passed a number as the first parameter. But for the first two, within the imported javascript file, it's not aware that the type of the parameter has been defined. This prevents you from being able to use noImplicitAny, but also stops you from errors when you, for example, pass in numValue to a function expecting a string.

Is it possible to make javascript files aware of their definitions within typescript, preferably without modifying the original javascript.

Answer 1

While javascript files can't be made aware of their definition files, Typescript 2.3 added support for type checking using JSDoc comments.

Changing the project to:

src/
  main.js
  imported.js

imported.js

/**
 * @return {string} 
 * @param {number} numVal 
 * @param {string} strVal 
 */
export const func = (numVal, strVal) =>
  `The number is ${funcs.func3(numVal)}, the string is ${strVal}`;

main.js

import { func } from './imported';

/**
 * Works fine
 * @param {number} number 
 */
const mainFunc1 = (number) =>
  func(number, "Hello");      

/**
 * Argument of type 'string' is not assignable to parameter of type 'number'
 * @param {string} string 
 */
const mainFunc2 = (string) =>
  func(string, "Hello");

Now the typescript compiler is aware that numVal is a number, and strVal is a string. Trying to pass numVal to a function that doesn't accept a number while result in an error. The @return in func is technically redundant here, as it knows it's returning string (it would know that even without the JSDoc), but it's good for consistency.

While this does require modifying the original javascript, it only uses comments to do so.

Limitations

This doesn't have all of the features of full Typescript type checking, but it's most of the way there. For example, if you have a module that returns an object, containing typed keys:

/**
 * @param {number} num 
 */
const func1 = (num) => num * 2;

export default {
  func1,
}

And then consume it with:

import imported from './module';

imported.func1(3);    // This is okay
imported.func1("3");  // This is an error
imported.func2(3);    // This is also okay, but it shouldn't be

With javascript files, this won't error, as it hasn't generated a type for the default export, so it can't confirm that func2 doesn't exist. Whereas in Typescript, it would tell you Property 'func2' does not exist on type '{ func: (num: number) => number; }'. Did you mean 'func'? Property 'func2' does not exist on type '{ func: (num: number) => number; }'. Did you mean 'func'? , without having to explicitly declare the type of the default export.

Typescript 2.5

Typescript 2.5 also added support for type assertion with JSDoc, for example:

// Argument of type 'string | number' is not assignable to parameter of type 'number'.
const func1 = () =>
  func(funcReturnsNumberOrString(true), "Hi");

// Fine
const func2 = () =>
  func(/** @type {number} */ (funcReturnsNumberOrString(true)), "Hi");

/**
 * @returns { number | string }
 * @param {boolean} bool
 */
const funcReturnsNumberOrString = (bool) =>
  bool ? 2 : "2";

In this case we know that funcReturnsNumberOrString returns a number, so we can tell Typescript as such.