Typescript Generic Types

[rouzwelt]

Motivation

resolves #4451
Currently if a function/method has a generic return or arguments type like:

pub fn some_fn(arg: SomeType<String>) -> SomeType<u8> {}
// or
pub fn some_fn(arg: SomeType<String>) -> Result<SomeType<u8>, JsValue> {}

where SomeType is just plain struct that impls wasm traits manually (not using wasm_bindgen macro on its definition, ie not js class) the generated typescript bindings wont correctly map the generic types and doesnt actually include them:

// for both cases above
export function some_fn(arg: SomeType): SomeType

Although user can use unchecked_return_type and unchecked_param_type attribute to specify them, but this is not really ideal, it is fine and ok if there are a couple of functions to apply those attrs to, but if there are tons of functions and methods, it wont really end up good as they are unchecked and bug prone, however if the nested types can be processed regularly like the main type, this can simply be resolved, so on typescript we would get:

// for both cases above
export function some_fn(arg: SomeType<string>): SomeType<number>

---

Proposed Solution

Implement some logic to parse and map the types deeply, possibly recursively, until all nested types are parsed and accounted for in generated typescript.
There is a mapper currently that maps the rust return types to their equivalent js/ts types, but looks like it just checks 1 level deep, and doesnt go deeper than that, however with some tweaks, the same logic can be applied on nested types to correctly map the return type for the js/ts bindings.

We need to parse the args/return syn::Types separately and map them with their nested syn::Types into their corresponding WasmDescribe which later on can be encoded and then decoded into Descriptor and next into AdapterType so can be appended lastly to the parent TS type as generic if they happen to be generic.

---

High-Level Implementation Details

We we would use native encoded/decoded WasmDescribe::inform() for return and arguments types, meaning we will encode their wasm informs in the backend::codegen for Export and then decode it at cli-support::descriptor::Function which now has 2 new more fields:
inner_ret_map and args_ty_map, these 2 field hold the Descriptor which now has 1 more variant called Descriptor::Generic which exclusively added for this purpose and doesnt have any effect on any previous functionalities:

Descriptor::Generic {
    ty: Box<Descriptor>,
    args: Box<[Descriptor]>,
}

that can hold the type map for both args and return type, now at cli-support::wit::register_export_adapter we convert those inner_ret_map and args_ty_map fields into AdapterType using a newly added function called describe_map_to_adapter where it just maps the given Descriptor to its AdapterType by also handling of nested generic types.
Lastly when building the ts signature and js doc for the binding function/method, we will convert those generic AdapterTypes into their corresponding js/ts types and append them to the main parent type.

New tests are added under typescript-tests crate testing complex nested generic types to be correctly mapped to their ts signature.
This feature doesnt change any of the previous functionalities and logic, it simply is a new piece of logic that separately maps a syn::Type with any of its nested syn::Types to their WasmDescribe and then Descriptor and after that to AdapterType completely separate to the how args and return type are resolved, and at the very last step of generating the ts signature, if the arg/return type is a generic, it will just append the generic to the actual parent type.

---

Note

An attribute can be added to be able to turn this off for a given function/method, I have not added such attribute in this PR, but if that's desired, I can add it.

[guybedford]

@rouzwelt new maintainer here, this is an interesting direction, I would like to review it more carefully soon. It would be great if you could be clear about the limitations of the approach as well.

[rouzwelt]

@rouzwelt new maintainer here, this is an interesting direction, I would like to review it more carefully soon. It would be great if you could be clear about the limitations of the approach as well.

hey there, great to have you on
regarding limitations, I haven't really noticed any meaningful limitations so far, that's because for a type to be able to be compatible with wasm boundary, it should have full implementations of the traits, even generic ones, the inner generic types they themselves should have all the wasm traits implemented even if they don't get parsed/show up ins the final generated dts as generics, because for rust side of things to get compiled, those traits should be implemented for all of the inner types of a generic type,
so this PR just makes the generics to become available in the final generated dts

[daxpedda]

Please stop pinging maintainers repeatedly. Your PR hasn't been forgotten, we just don't have the necessary bandwidth.

FWIW we will be discussing generic support next week and try to come up with a design we want to support. Your PR will definitely help in that discussion so it is much appreciated!

[guybedford]

Thanks for your patience on this review, I finally was able to take a brief look at this.

I really like the work here and would love to see this landed, we just have to be very methodical about the approach and review process. I'm up for it though if you are.

[guybedford]

All types here seem to be exported types. Can we extend the coverage here to imported types as well?

We would also need to cover interactions with js_name and js_namespace renaming to ensure aliasing is supported.

[guybedford]

I don't follow why we need two separate serializations here. The first-level cut-off of the generics is the function type, so we should just fold the data into describe_args and describe_ret instead of duplicating here.

[guybedford]

If we were writing this from scratch today, surely we wouldn't have a separate Generic, and would instead deeply nest all types properly? This seems like the right approach to properly integrate with other generics work in progress as well (such as generic enums - #4734, which had to deal with similar problems here in its own way).

I think we should try and generalize the approach a little better instead of stapling it on here.

So:

1. If using a separate generic type, generalizing it to not be function-specific?
2. Or, ideally, just making functions encode their deep tree to begin with?

[rouzwelt]

@guybedford thanks for the review, well I submitted this a few months ago, and I believe there has been some changes and some generic features added since then as you mentioned, so I guess I first need to update myself with the new changes as I don't really remember the details of this PR 😄
I read your review as you asked some questions, tbh I don't really remember why I made some of those decisions at the time of preparing this PR, so I need to review it myself again.

so I'll try to free up some time and resolve the conflicts first and then address your review if that's ok with you, plz let me know

[guybedford]

@rouzwelt none of the generics changes have landed yet, but it would be nice to know work done here can align well with #4734 and #4746 for if/when they land.

Thanks for taking another look - just let me know when you're ready to discuss again and I'm happy to do another review.