feat: add module declaration support

[lachieh]

Adds a jco guest-types command to output module definitions to be used when implementing guest components.

For example, the types for wasi:http/incoming-handler are output like this

declare module 'wasi:http/[email protected]' {
  export function handle(request: IncomingRequest, responseOut: ResponseOutparam): void;
}

which means that you can import get IDE suggestions for

import {handle} from 'wasi:http/[email protected]'

Closes #439

[lachieh]

@guybedford updated to --guest. The windows tests seems to be failing for another reason as far as I can tell.

[guybedford]

This looks like a great start, thanks.

I'm okay for us to land this as experimental to start even if it's not completely comprehensive. But I'm still wondering if there are other cases we should test though, perhaps some multi-import / multi-interface / resource generation or WASI worlds or otherwise?

[vados-cosmonic]

Hey @lachieh thanks for contributing this -- I guess this is for both you and @guybedford at the same time but what do y'all think about having a more explicit name for the feature?

I can think of at least two ways this would work -- removing the namespace and exporting a module "instead" of namespaces. So concretely something like --disable-namespace or --no-namespace-wrapper or --use-module-wrapper. Then if we have some sort of "suite" of guest-related options we want to set we can re-introduce --preset-guest that kind of wraps a bunch of them.

Also, I was really hoping that this would turn into the default over time as we know it's not likely to break people/works with most things. The ease of use is dramatically better "out of the box" when exporting the module instead of the namespace for guests.

I'm happy to help add tests in a follow up (along with some more examples that need to be added to jco which I'm working on)

[lachieh]

This aligns with the experience I detailed in the issue thread.

As far as I understand it, the types now are used mostly used for transpiling. I haven't read that code yet so forgive if this is not the right question; would switching to namespaces affect how transpiling works? Should module declarations for guest components be a net-new feature?

[guybedford]

We discussed this in the meeting today - and if there may be potential for wanting to configure whether to use module declarations or namespaces within guest generation then I think this should be guest-specific ie jco types --guest --use-namespace. Conversely if we did want to configure for host type generation to use module declarations for some reason then we should have a flag for that on the jco types --module-declarations or otherwise.

This does have me thinking though - since the flag options may end up being specific to the host or guest path, it might even be worth considering treating this as a new top-level command - jco guest-types or jco types-componentize or otherwise?

[vados-cosmonic]

This does have me thinking though - since the flag options may end up being specific to the host or guest path, it might even be worth considering treating this as a new top-level command - jco guest-types or jco types-componentize or otherwise?

A bit late responding here but yeah this actually does seem like a good idea... BUT with the documentation burden it would cause... maybe we hold of on that for now :)

[lachieh]

@guybedford I'm in agreement there. Since the behavior of jco types --guest --use-namespace would be the same as jco types can we add that second flag if it is requested?

Spoke with @vados-cosmonic today and found a couple of reasons we may indeed want to split the command into a new one, though it will require a bit more discussion—mostly around what you envision the JS/TS experience look like long term. I'm synthesizing some notes on that and will likely post a couple of issues.

Are we able to get this one in as is to get some feedback and then continue the discussion on the next phase?

[guybedford]

Thanks for your patience, will aim to land this this week - just wondering if we should switch over to a new command here or in a follow up?

[guybedford]

I realise we skipped over the discussion on this one this morning - please do let me know if there is more to discuss here.

Marking as request changes for now based on the agreement on using the jco guest-types command name, and not to miss that for review further. Happy to discuss alternatives as well.

[lachieh]

Thanks, @guybedford! Not a worry—not much to discuss. I'll get this updated to the new command tomorrow, most likely.

[guybedford]

This is a great start, thank you.

In the main README we usually keep the CLI information up to date in https://github.com/bytecodealliance/jco?tab=readme-ov-file#cli (pending better docs here).

Just would be good to have an experimental note while this feature is not yet stable.