Ways to avoid any in generated TypeScript declarations

[richard-viney]

Currently the following Gleam code:

pub type Wibble

generates this TypeScript declaration:

export type Wibble$ = any;

This occurs frequently in the stdlib, e.g. for Dict, Dynamic, Regex, and StringBuilder, as well as in other common libraries like the json.Json type.

I'd like to find a way to avoid any in generated TypeScript declarations so that:

1. TypeScript code using these types has some/better type safety enforced.
2. They don't trigger warnings when used in TypeScript codebases with strict configs that error on use of the any type.

These were both points of friction during my initial foray into using the generated TypeScript declarations in a real-world project that imports several Gleam libraries.

Option 1 - Use the unknown type

The any type could be changed to unknown to better reflect what the compiler knows about the type (i.e. nothing), and to give meaningful additional safety. It's not perfect though, as such types would be interchangeable due to all being unknown, e.g. in TypeScript a Dict could be passed where only a Regex is valid. But it's still a big improvement.

Changing any to unknown would also not be backwards compatible with TypeScript code that accesses properties or calls methods on one of these any types, or relies on it being implicitly converted to another type. However, if these types are opaque (as I understand them to be), then the underlying TypeScript type is a private implementation detail that users shouldn't depend on, so any such existing TypeScript code was never actually well-formed to begin with.

Option 2 - Allow the TypeScript type to be provided via @external

Alternatively, we could allow Gleam code to optionally provide a TypeScript type by allowing @external on a type declaration:

@external(typescript, "./regex_ffi.d.mts", "Regex")
pub type Regex

// regex_ffi.d.mts

export type Regex = RegExp;

Which generates the following TypeScript declaration:

import type { Regex as Regex_ExternalType } from "./regex_ffi.d.mts";

export type Regex = Regex_ExternalType;

This option gives authors complete control over how these Gleam types are exposed in TypeScript, and it's no longer a concern of the Gleam compiler.

---

The two options outlined above aren't mutually exclusive. Each could be adopted individually, or both/neither could be adopted. If there are any other approaches for avoiding any in the TypeScript declarations that I haven't considered then please let me know - thanks!

[lpil]

It cannot be unknown because the type is not unknown.

Perhaps an annotation is an option, though I'm not yet sold on this approach.

Overall this is extremely low value so I'm unlikely to dedicate much time to the design and review work here.