[Design Policy] Consider JSDoc feature parity with Typescript

Search Terms

jsdoc parity, jsdoc equivalence, jsdoc

Suggestion

The JSDoc mode of TypeScript is very useful in cases where a build step (esp for node libraries for example) isn’t desired or when other constraints prevent not writing in JS. However it can be annoying when trying to implement something that can’t be expressed in JSDoc mode due to requiring Typescript syntax.

As such I would like to propose that TypeScript ensures that anything that can be written inside a .ts file can be expressed (in at least some way) within a pure javascript + jsdoc file.

In order to get an idea of the current scope needed for feature parity this is a list of issues and features that break parity between the two modes (if any are missing just say and I’ll add to the list):

• [Bug?] No way to express the object type
  • Currently in JSDoc /** @type {object} */ is equivalent to /** @type {any} */, there doesn’t seem to be any way to represent const x: object purely in JS + JSDoc, this seems like a bug. Fixed
• interface
• abstract class
• protected/private members Fixed
• function overloading
  • open issue
• ~defaults for generics~
  • ~open issue~
• declare syntax in it’s various forms and declaration merging
  • declare global { ... }
  • declare module "moduleName"
  • declare class Foo
  • declare interface
  • declare namespace
• namespace
• enum
  • /** @enum */ is not quite equivalent
• ~as const~ v4.5
  • ~open issue~
• non-null assertion expr!

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.

[weswigham]

@AlCalzone function overloads only affect usages of the function, not parameter types within a function - this is true in TS, too. You need to actually annotate parameter types on the implementation (compatible with the overloads) to get checking in the function body.

[ExE-Boss]

Function overloading can be done using:

/** @type {((name: string) => Buffer) & ((name: string, encoding: string) => string))} */
const readFile = (name, encoding = null) => { … }

I discovered this purely by accident.