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.

Comienza con el ejemplo foo.js y compáralo con el flujo de trabajo adyacente de foo.d.ts descrito en el issue. Define el alcance propuesto de @tsdeclare para tipos importados, interfaces y otras declaraciones no triviales, manteniendo las anotaciones de símbolos en las etiquetas JSDoc existentes. Se considera completado cuando el diseño y la implementación admiten el caso de uso de checkJS indicado sin cambiar el JavaScript generado.