checkJS + JSDoc + inline d.ts syntax

Search Terms

jsdoc, interface, import, inline, d.ts file, checkJs

Suggestion

Improve the user experience for checkJS users. Currently TypeScript checkJS supports 99% of the use cases of TypeScript and that's an amazing feat as it stands.

The support for @typedef with import(...) helps a lot !

It would be amazing if there was support for something like @tsdeclare

// foo.js
/**
 * @tsdeclare {
 * import type {
 *     LogStream
 * } from 'aws-sdk/clients/cloudwatchlogs';
 *
 *  interface Dictionary<T> {
 *    [key: string]: T | undefined;
 *  }
 * }
 */

class FakeCloudwatchLogs {
  constructor () {
    /** @type {Dictionary<LogStream[]>} */
    this.rawStreams = {}
  }
}

If I could declare statements that are valid in a foo.d.ts file but instead inline in my javascript file withing a @tsdeclare block.

This is very similar to https://github.com/microsoft/TypeScript/issues/9694#issuecomment-409158590 but it's even smaller in scope.

The scope of the @tsdeclare block is only about importing types and declaring interfaces and other non trivial types that can then be used in the file.

Actually annotating types of javascript symbols is left for @param ; @type & @returns etc.

The @tsdeclare is a more powerful version of @typedef

Use Cases

I want to check my JavaScript files with TypeScript and I am currently declaring type definitions and interfaces in a foo.d.ts file next to my JS file.

Examples

I want to use this for declaring interface in a JS file.

The existing approach requires two files, a js file and a .d.ts file.

https://github.com/microsoft/TypeScript/issues/9694#issuecomment-500619014

I know that its possible to split the code across two files. with more advanced types in a d.ts file but that's a frustrating user experience of splitting the documentation of my code across two files.

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.

foo.js の例から始め、issue で説明されている隣接する foo.d.ts ワークフローと比較します。インポートされた型、インターフェイス、その他の自明でない宣言に対する、提案されている @tsdeclare のスコープを定義し、シンボルのアノテーションは既存の JSDoc タグ内に維持します。設計と実装が、出力される JavaScript を変更せずに、記載された checkJS のユースケースをサポートすれば完了です。