TypeScript definitions are out of date

[eemeli]

CC @ikatyang @ColinBradley

See also DefinitelyTyped/DefinitelyTyped#33780

The DefinitelyTyped TS definitions haven't been updated since the 1.0 release last fall, and the library's API has expanded a bit since then. With the next minor release I'll be deprecating some of the endpoints and adding new ones thanks to #99.

Any suggestions for how to make it easier to keep these definitions up to date?

[joshuaavalon]

The best way is to rewrite the package in Typescript but it requires a huge effort. If you only want to keep the definitions up to date, you can actually include definitions in your own package. You can do this by add types in package.json, so you don't need to make a pull request every time.

{
   "types": "./lib/main.d.ts"
}

[akosyakov]

Any suggestions for how to make it easier to keep these definitions up to date?

Rewrite in typescript 😛

Actually ts is superset of js and it has allowJs property in configs, so maybe instead of rewriting you can annotate js code with jsdoc types and run tsc to generate typings.

[eemeli]

@akosyakov Would you be willing and/or interested in implementing a PoC of the JSDoc annotations? That sounds like a decent idea.

[eemeli]

Had a quick try at this, and immediately hit microsoft/TypeScript#7546. But it looks like this might finally be getting solved as a part of microsoft/TypeScript#30555?

[eemeli]

Yeah, I'm going to keep this open if someone that actually uses TS wants to have a go at it. With the following tsconfig.json I managed to get it down to just 160 errors, but then found at least the following specific pain points that I'm uninterested in fixing, at least for now:

• The AST Node does not initialise its fields, so that the undefined ones are never set. At least Pair makes use of this to allow using get/set for its commentBefore
• In particular at the CST level the library abuses labels for debug logging with babel-plugin-trace. Either that would need to get dropped, or the Babel plugin would need to run before the source goes to Typescript.

If someone's interested in setting it up, a possible workflow to generate the d.ts files could be something like *.js -> Babel -> *.ts -> tsc -> *.d.ts, presuming that JSDoc comments are also sufficient for typing TS files. I guess the alternative is that someone manually maintains the d.ts files?

{
  "compilerOptions": {
    "outDir": "./ts/",
    "strictNullChecks": false,
    "lib": ["es2017"],
    "module": "es6",
    "target": "es6",
    "allowJs": true,
    "checkJs": true,
    "types": []
  },
  "include": ["./src/**/*"]
}

[joshuaavalon]

I don't think others are doing like this. One of the common ways is to just create .d.ts files manually like what you do with the documentations. When there are public API update, update the related .d.ts files.

Using JSDoc seems to very difficult to maintain. At that point, you may as well write it in TypeScript.

[idantene]

Joining the party as I'm trying to use it on TypeScript, and for the time being I indeed have to work with either @ts-ignore, or alternatively use old definitions, which is terrible and does not match the documentation :(

[eemeli]

Ping @benjamingr, who said he might be interested in looking at this.

[benjamingr]

Sure, is the context generating the type information?

Would dts-gen not suffice for starters :] ?

[BurtHarris]

I've got background in Typescript and YAML, and this implementation interests me. I'd like to have a look at doing this by adding type annotations to the existing implementation, and having TSC generate the definitions file.

Made some progress with the approach enabled by Babel 7 using @babel/preset-typescript for code generation, and tsc for error checking. But there are a few parts of the code I don't understand. I'll post them as separate questions.