Improve type-checking inside the engine source code

[mvaligursky]

In the engine source code, we only import modules that are required in order to build the engine. This leaves many types unknown to Visual Studio Code (or similar JS editor), and we see the type with red underscore, and when typing this.device. we don't get any code-completion aids. This is what we see:

We could adopt the use of typescript typedef imports to improve the situation. First, we'd need to import the type this way:

Then declare this.device to be of type GraphicsDevice

And then Visual Studio gives us code-completion and understands and validates the function signatures.

(Thanks to @vkalpias who's started to use it in Editor API he's working on)

[yaustar]

Does this mean we add a bunch of typedefs to a lot of the files? Does this affect JS docs in any way? Should we include all types that are needed anyway? Not just the minimum to build the engine?

As a side note, Webstorm shows this as:

[mvaligursky]

I don't believe it has any effect apart from improving our coding experience. These imports are only for parsing of code for intellisense, nothing else.

We cannot import all types, as that would create circular dependencies. You only need to import types you need to know a type of in the code (because you call constructor, or call static function on the type, or do typeof .. and similar). Otherwise imports are marked as not needed anyways.

[mvaligursky]

It would be also great to find a way we can have all typefeds in a single file for the project, that gets included using a single line into any source files. Perhaps something like this:
https://github.com/polyforest/jsdoc-tsimport-plugin

[kungfooman]

We cannot import all types, as that would create circular dependencies.

TypeScript is analyzing code dependencies and removes dispensable (type) imports, so technically you probably just need to put typescript() before the JavaScript code is processed by rollup (at least I imagine that would work).

I did a little test for just this one file example of yours:

I added this line:

import { GraphicsDevice } from 'src/graphics/graphics-device.js';

And type definitions where TS/VSCode expects them (differs from strange JSDoc style over the class itself):

class ForwardRenderer {
    /**
     * @type {GraphicsDevice}
     */
    device;

    /**
     * 
     * @param {GraphicsDevice} graphicsDevice 
     */
    constructor(graphicsDevice) {
        this.device = graphicsDevice;
        var device = this.device;

And then just compile it for comparison: npx tsc --allowJs --outDir tsctest -m ESNext src/scene/renderer/forward-renderer.js