Proposal: Support for registering custom TypeScript type strings in Embind

[mkl-ableton]

Hi all,

I’d like to propose adding a way to provide custom TypeScript type strings in Embind. At the moment, the generated .d.ts output is useful, but there’s no mechanism to override or extend the type definitions when the default modeling isn’t sufficient.

For example, I’m not satisfied with the behavior of enum_ and have created my own helper registerEnumType that maps a C++ enum to runtime values. On the TypeScript side, I’d like this to generate a declaration such as:

type TestEnum = "A" | "B" | "C";

I can handle the runtime mapping by specializing BindingType and TypeID, but there’s currently no way to inject the corresponding type string into the generated definitions.

What I’m suggesting is a simple hook or API like:

emscripten::register_type_string(
  "type TestEnum = \"A\" | \"B\" | \"C\""
);

This would not affect existing users or change default behavior, but it would give developers a way to supply precise type strings where needed.

Would such an extension point be acceptable? If yes, I can prepare a patch. If not, is there another mechanism that could achieve this?

Thanks!

[sbc100]

@brendandahl

[brendandahl]

You could potentially use the currentregister_type. Though that will associate the type with a val, but I think it will be auto unwrapped (can't remember off the top of my head).

[mkl-ableton]

Thanks for the reply. AFAICT, register_type isn't enough here.

Problem

register_type only emits a type when it’s referenced; it doesn’t create a top-level alias in the generated .d.ts. For enums (and other named types) I need a free-standing definition like type A = ... so that client code can reference a stable name.

What I want

Given:

enum class SomeEnum { a, b };

struct SomeClassWithEnum {
  SomeEnum someEnum;
};

registerEnumType<SomeEnum>("SomeEnum", {"a", "b"});

class_<SomeClassWithEnum>("SomeClassWithEnum")
  .property(&SomeClassWithEnum::someEnum);

I’d like the generated typings to include:

type SomeEnum = "a" | "b";

export interface SomeClassWithEnum extends ClassHandle {
  readonly someEnum: SomeEnum;
}

What I did before

In 4.0.8 I (hackily) printed into the type file via stdout:

template <typename T>
void registerEnumType(const char* name, const std::vector<std::string>& strings) {
  if (isRunAsPartOfCompiling()) {
    fmt::print("type {} = \"{}\";\n", name, fmt::join(strings, "\" | \""));
  }
  emscripten::register_type<detail::EnumOf<T>>(name);
}

4.0.9 broke this approach by stopping stdout from ending up in the typings.

Proposal

Provide an official API to append raw TypeScript to the generated definitions, e.g.:

// Hypothetical API
namespace emscripten {
  template <typename... Args>
  void print_type_string(fmt::format_string<Args...> fmt, Args&&... args);
}

Then registerEnumType can become:

template <typename T>
void registerEnumType(const char* name, const std::vector<std::string>& strings) {
  emscripten::print_type_string("type {} = \"{}\";\n", name, fmt::join(strings, "\" | \""));
  emscripten::register_type<detail::EnumOf<T>>(name);
  // ...
}

Alternative

Change register_type so that, when given a name, it emits a top-level alias (e.g., for enums: type SomeEnum = "a" | "b";) and uses that top-level alias when the type is referenced. That would let properties reference SomeEnum without the extra printing step.

Either solution would cover the core need: a stable, free-standing alias in .d.ts that properties can point to.