Typescript types for external types

[vonagam]

Right now this from stdlib:

pub type Map(key, value)

Generates this in ts:

export type Map$<MA, LZ> = any;

Making those descriptions for functions:

export function get<OA, OB>(from: Map$<OA, OB>, get: OA): _.Result<OB, null>;

The same as:

export function get(from: any, get: any): _.Result<any, null>;

So losing most of the gains of typing.

I think it makes sense to have some way to provide typescript type for external js implementation. As an example it can be something like this with existing annotation:

@external(javascript, "../gleam_stdlib.d.ts", "Map")
pub type Map(key, value)

Where instead of generating a type definition of any, an external specified type will be imported and aliased with gleam's expected name. So for Map it will be:

import type {Map as Map$} from "../gleam_stdlib.d.ts"

Thoughts?

[yoshi-monster]

Picking this thread over the other one (#3801) since it's more narrow.

I would very much like this feature, not just for Javascript but for Erlang as well. I think one of the most powerful features it would enable is for FFI types to "survive" calls to Gleam functions. Lots of types in gleam_erlang and gleam_javascript for example could be annotated to reflect their native counterparts (Pid, Monitor, Atom, Reference, Promise, Array, etc), improving FFI and consuming Gleam code from both targets.

Good FFI interop is crucial to Gleam. Gleam programs can not run by themselves, but need external code to call their entry point. Gleam programs cannot do anything "useful" (except echo) without calling back into FFI code.

For Erlang, I would expect the annotation to work similarly:

@external(javascript, "./dict.d.ts", "Dict")
@external(erlang, "gleam_stdlib", "dict")
pub type Dict(key, value)

would be translated to

import type { Dict$ } from './dict.d.ts'
export type Dict<key, value> = Dict$<key, value>

// dict.d.ts
export interface Dict<TKey, TValue> {
  get(key: TKey): gleam.Result<TValue>;
  // ...
}

and

-export_type([dict/2]).
-type dict(Key, Value) :: gleam_stdlib:dict(Key, Value).

% gleam_stdlib:
-export_type([dict/2]).
-type dict(Key, Value) -> #{Key => Value}.

respectively. It's an open question whether supporting Typescript at all is good, and if JSDoc syntax should be used instead or in addition as well. Since the compiler already outputs typescript declarations, I assume there's at least some intention in allowing typescript to consume Gleam (despite some folks saying otherwise); Since the compiler already supports Typescript, I think focusing on that makes the most sense.

[lpil]

This is a very cool design! I like how the external annotation is a pointer to a definition in the external code, the same as functions.