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.

Commencez par l’exemple foo.js et comparez-le au workflow adjacent de foo.d.ts décrit dans l’issue. Définissez la portée proposée de @tsdeclare pour les types importés, les interfaces et les autres déclarations non triviales, tout en conservant les annotations de symboles dans les balises JSDoc existantes. Le travail est terminé lorsque la conception et l’implémentation prennent en charge le cas d’utilisation checkJS indiqué sans modifier le JavaScript émis.