Allow local .js/.ts files to be typed by their corresponding .d.ts file

Suggestion

If I have source/index.js which has:

function isObject(value) {
	// null is object, hence the extra check
	return value !== null && typeof value === 'object'
}

And then I supply a source/index.d.ts file which has:

/** Checks to see if a value is an object */
export function isObject(value: any): boolean

And I update package.json:types to source/index.d.ts.

Then I should not receive the following error in source/index.js:

[ts] Parameter 'value' implicitly has an 'any' type. [7006]
(parameter) value: any

And I should get complete intellisense.

Use Cases

This approach has the following benefits:

1. Source files can run without compilation, this has been incredibly useful for @bevry's hundreds of packages, which are all written in jsdoc'd esnext that runs on mostly node 4 and above, with compilation only for older node versions (but most of the time, it is our source code that is running, thanks to editions)
2. JSDoc types do not provide intellisense nor type checking for typescript consumers
3. TypeDoc for documentation seems nicer than JSDoc, especially with overloads
4. Going all in on TypeScript may be too much to ask for, for many module authors - as a typescript project requires types for all its dependencies, as well as accurate (rather than merely simplistic) mappings, which some of the time, is just too inconvenient to bother with - such as this, as well as eachr which a pure typescript conversion seems impossible to me (after days of effort, as typescript always whines about incorrect types)

Alternatives to this would be:

1. Have typescript projects support intellisense and type checking for jsdoc js files
2. Automatically generate .d.ts files for jsdoc js files

For now, the best workaround seems to be:

1. Spend weeks upon weeks converting your hundreds of modules to typescript to satisfy typescript's need for types for everything
2. Provide jsdoc .js files, and manual .d.ts files

Examples

• https://github.com/bevry/typechecker/tree/dev-typescript-dts
• https://github.com/bevry/eachr/tree/dev-typescript-dts

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

I haven't filled out this checklist as I do not know enough about typescript's inner workings to be able to fill it out.

source/index.js の例と対応する source/index.d.ts の例から始め、その後、package.json の types エントリがどのように解釈されるかを確認します。ローカルの JavaScript ファイルがパラメーターの型付けと IntelliSense に declaration file を使用し、implicit-any エラーなしで動作しながら、既存のランタイム動作が変更されていなければ作業完了です。