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.

[balupton]

You mean when you publish to npm?

Yes.

Take the package https://github.com/bevry/badges and the example consumption at https://github.com/balupton/typescript-consume-jsdoc

If I consume it via a .js file, I get intellisense with the typing and docs provided by its jsdoc comments:

However, if I do it via a .ts file, I get nothing:

Only an error whining that it needs a declaration file:

Could not find a declaration file for module 'badges'. '/Users/balupton/Projects/active/typescript-consume-jsdoc/node_modules/badges/index.js' implicitly has an 'any' type.
	Try`npm install @types/badges` if it exists or add a new declaration(.d.ts) file containing`declare module 'badges';`[7016]

Which is infuriating, especially as intellisense and type checking work fine for .js files with @ts-check:

Which means that .ts files are actually more crippled than their .js alternatives:

feature	.ts files	.js files
intellisense for jsdoc’d packages	no	yes
type checking for jsdoc’d packages	no	yes
intellisense for typescript packages	yes	yes
type checking for typescript packages	yes	yes
intellisense provided by a corresponding local .d.ts file	no	no
type checking provided by a corresponding local .d.ts file	no	no

I cannot figure out any technical reason why this should be the case, only a business reason, of typescript adoption requiring the conversion of all dependencies, to do a marketshare stronghold.

This is why I ended up on the path of attempting to document .js files via corresponding local .d.ts file, as I was thinking, well typescript can’t consume jsdocs, in which case, perhaps then I can work around this by writing .d.ts files for my .js files, however then I run into the first post’s issue, which is that javascript can’t get its type information from local .d.ts files. Meaning that either:

1. I have to convert everything to .ts files, enduring the compilation/adoption/conversion costs
2. I have to write packages that provide both .js files with jsdoc, and a corresponding.d.ts file
   1. jsdoc is necessary for local type checking and intellisense
   2. .d.ts file is necessary for consumed type checking and intellisense in typescript projects

[frank-dspeed]

If i understood that right this issue votes for making the d.ts file authoritative and i think that is not fully wrong in all scenarios it depends on if your a consumer or author. So i guess this issue should get reopned and renamed to something like

tsconfig.json setting types lookup priority there are cases where you want your .ts and .js to be authoritative to create the correct.d.ts and there are cases where your the consumer want to write something with the help of a d.ts file.

that is a chicken egg problem i guess which comes first. the declaration or the definition.

at present i have a combo of declaration false and including the d.ts file as source file in my head that could lead to the expected result without the error that the emitting of files will overwrite a source file. So allowJs CheckJs include d.ts noEmit should enable that