Allow to manually specify typescript function signatures

[Vlad-Shcherbina]

Motivation

TypeScript has a very expressive type system.
Some of its features have no counterparts in the Rust type system, and in any case wasm-bindgen is unlikely to ever support it in full.
This matters for making high-quality TypeScript APIs for wasm modules, so maybe there should be an escape hatch to manually specify more subtle types than wasm-bindgen could infer.

Example:

// .rs
#[wasm_bindgen]
pub fn find_root(f: &js_sys::Function) -> f64 { ... }

// .d.ts
export function find_root(f: Function): number;  // inferred by wasm-bindgen, bad
export function find_root(f: (x: number) => number): number;  // good

Proposed Solution

Support the following syntax on exported Rust functions:

#[wasm_bindgen(typescript_signature="(x: number): -1 | 0 | 1")]
pub fn sign(x: i32) -> i32 { ... }

When typescript_signature is specified, wasm-bindgen should uncritically use it in the generated .d.ts:

export function sign(x: number): -1 | 0 | 1;
// instead of the default 'export function sign(x: number): number;'

The responsibility to ensure that it matches the actual implementation is on the programmer.

Additional Context

This feature could also serve as a workaround for #1591 and #1197 .

[Pauan]

This is already possible by using typescript_type, like this:

#[wasm_bindgen]
extern "C" {
    #[wasm_bindgen(typescript_type = "-1 | 0 | 1")]
    type Order;
}

And now your functions can accept/return Order:

use wasm_bindgen::JsCast;

#[wasm_bindgen]
pub fn sign(x: f64) -> Order {
    JsValue::from(x).unchecked_into::<Order>()
}

Note the usage of unchecked_into to cast it into the Order type.

This also works for putting Order into structs:

#[wasm_bindgen]
pub struct Foo {
    pub order: Order,
}