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.

Start with the foo.js example and compare it with the adjacent foo.d.ts workflow described in the issue. Define the proposed @tsdeclare scope for imported types, interfaces, and other non-trivial declarations, while keeping symbol annotations in existing JSDoc tags. Done means the design and implementation support the stated checkJS use case without changing emitted JavaScript.