[RFC/Proposal]: Add types for modules

[RichDom2185]

Background

With Source Typed, it is now possible to teach strong typing at an introductory level. Naturally, it extends to modules, something that students interact with a lot in Source Academy.

Possible Considerations

The "exposed" type should be separate from the actual implemented type

To enforce abstraction principles. For example, while runes are by no means a primitive type in its implementation (using higher order functions, etc.), we should treat them as such.

Ideally, types should be inlined

https://github.com/source-academy/js-slang/pull/1467/files#diff-2e2aa2db6619eec1be92cd4c227f51bafd0c3e8a0ba28a58c105e5e08944ec5d gave a proposed method of defining types for modules. However, not only are they located in a separate file, they are located in an entirely different repository (and NPM package). This makes keeping consistent type definitions difficult.

Ideally, we should be able to define the types of members we want to type, as well as "type aliases", inline, as much as possible.

Proposal

We propose writing a custom esbuild plugin to handle this use-case. It will be transparent, requiring minimal-if-no changes to existing modules to leave them untyped.

Using decorators attached to each name we want to type, the hope is we can generate the metadata/type definitions not unlike the one above, during build/bundle time, based on the values supplied in the decorator.

Feasiblity

Will need to investigate.

See also

source-academy/js-slang#1400 (and related hyperlinks within)

[leeyi45]

Currently there's a bunch of typing information provided by typedoc through the JSONs. Is that sufficient? Should we look into using typescript declaration files?

I'm not sure if esbuild is capable of/the appropriate tool for doing this because it was designed to ignore type information.

[RichDom2185]

Currently there's a bunch of typing information provided by typedoc through the JSONs. Is that sufficient? Should we look into using typescript declaration files?

I'm not sure if esbuild is capable of/the appropriate tool for doing this because it was designed to ignore type information.

@tohlh is trying to work on it for his FYP. Type information is ignored by ESBuild yes, but we don't want the actual types of the implementation anyway (i.e. to students, heart is a primitive of type <Rune>, instead of a function).

Last time I followed up, I think we just create a context where we can declare inline what types we want the functions to have, and ESBuild output a separate object that can be read as the "type declaration" for these bundles.