Publish type declarations for included globals

[jsejcksn]

Refs:

• Transpile console.log(...) as print(...) #439

Hello! This is my first engagement with TSTL, so if it turns out that I've overlooked something, please bear with me.

TypeScript has a long and messy history regarding the topic of isolated declarations and ambient vs modular types. There's not a simple mechanism to "extract a subset of a library" in the case that only some of its API is available and that library is published as a group of global/ambient declarations (e.g. @types/node, @types/web).

In the case of TSTL, it was identified as useful to transform invocations of console.log and a few similar methods (see referenced issue above), but the Console API is not part of the ECMAScript spec, so these types are not available when compiling programs without library definitions — for example:

tsconfig.json:

{
  "compilerOptions": {
    // ...
    "lib": ["esnext"],
    // ...
  }
  // ...
}

Although I didn't find any relevant GitHub issues results when searching for console.log, I did find quite a few messages in the Discord server while searching for context regarding this issue — a common suggestion was to install one of the aforementioned runtime environment libraries. While doing so might fix a specific compiler diagnostic error such as the following:

error TS2584: Cannot find name 'console'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'.

it also introduces many global types which aren't actually available in a target Lua environment (and aren't transformed by TSTL), and so it suppresses many useful compiler diagnostics relating to unavailable references.

One could instead include a console.d.dts file in their project with the following content:

// Copied from https://github.com/microsoft/TypeScript-DOM-lib-generator/blob/%40types/web%400.0.114/baselines/dom.generated.d.ts#L26452-L26495

/** [MDN Reference](https://developer.mozilla.org/docs/Web/API/console) */
interface Console {
  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/assert) */
  assert(condition?: boolean, ...data: any[]): void;
  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log) */
  log(...data: any[]): void;
  /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/console/trace) */
  trace(...data: any[]): void;
}

declare var console: Console;

which would much more accurately represent the available console method transforms (according to the linked issue), without polluting the environment. For experienced TS developers, this might be obvious, but for the overwhelming majority of less experienced users who discover this project, this is not understood and is not a simple problem to solve, and — even for experienced devs — it would take work to search GitHub/Discord (like I did) and learn which console methods are available. There's an opportunity for this project to prevent such duplicated effort.

Side note: the additional console methods (e.g. error, warn, debug, table, clear, etc.) aren't listed as missing features. And are there other global transforms in place? I didn't find this general topic discussed in the documentation.

I think that a productive solution for all users would be for this project to include type declarations for all available references (included globals/transforms) which aren't part of ECMAScript. That way, individual devs won't need to spend time duplicating their efforts searching for all of these details, and no one will need to pollute their projects' scopes with all of the unrelated types in the node or web libraries. Instead they'd be able to do something much simpler like configure this package as a types source:

{
  "compilerOptions": {
    // ...
    "lib": ["esnext"],
    "types": ["typescript-to-lua"],
    // ...
  }
  // ...
}

I think it makes sense for TSTL to provide type declarations for the specific references that it recognizes.