--instantiation help suggests default async, but -I without value errors

[ritalin]

I have a question about the expected behavior of jco transpile --instantiation.

The help shows:

-I, --instantiation [mode]
output for custom module instantiation (choices: "async", "sync", preset: "async")

From this, I expected the behavior to be:

• -I async => generate instantiate function (async)
• -I sync => generate instantiate function (sync)
• -I => generate instantiate function (async)
• (no -I) => ESM output

However, in practice -I without a value results in an error because the next argument is treated as the mode:

$ jco transpile ... -I foo.wasm
error: option '-I, --instantiation [mode]' argument 'foo.wasm' is invalid. Allowed choices are async, sync.

Is this the expected behavior?

[ritalin]

I found another interesting behavior that might be related.
this does not fail:

jco transpile ... -I --no-nodejs-compat foo.wasm

This might indicate an argument parsing edge case.

[vados-cosmonic]

Hey @ritalin thanks for submitting this issue -- those are definitely some unintended consequences of our arg parsing library (we use commander)/how the arguments are currently set up.

Would you like to take a look at this? Certainly happy to take contributions on this!

[ritalin]

@vados-cosmonic

I’m happy to take a stab at fixing this, but before sending a PR I’d like to confirm the preferred direction.

Based on the current behavior and the commander limitations, it seems the core issue is that --instantiation is currently trying to act as both a feature flag and a mode selector, which creates ambiguity and parsing edge cases.

Possible directions I see are:

Option A (minimal change, but potentially breaking)

• Remove the preset: "async" wording from the help text
• Treat --instantiation <mode> as always requiring an explicit value
• Remove the implicit default so there is no hidden async preset

Note: this would be breaking for users relying on -I alone (including via edge cases)

Option B (clearer CLI design)

• Make --instantiation a pure flag that always means async instantiation
• Introduce --instantiation-mode <mode> for explicit mode selection
• Disallow using both together to avoid ambiguity

The motivation for this option is that both Node.js and browsers now support top-level await, so async instantiation is likely the common/default case. The separate mode flag would mainly serve users who explicitly need sync.

Example behavior for Option B:

• (no flags) -> ESM output
• --instantiation -> instantiate (async)
• --instantiation-mode async -> instantiate (async)
• --instantiation-mode sync -> instantiate (sync)
• Using both flags together -> error

Let me know which direction you’d prefer, or if there’s another approach you have in mind.

[ritalin]

Personally I lean toward Option A.

• I don’t expect this to be merged without tests anyway, so accidental breakage risk should be low.
• I’m a bit worried that adding another CLI option could slowly lead to too many options over time.

That said, I don’t feel strongly — just sharing my bias.

[vados-cosmonic]

Thanks for laying out these options -- so Id' like to avoid the breaking change -- there are a few more changes I'd like to get in before we have a Jco 2.x!

To be clear, the following work for me:

 # the following do not error
npx jco transpile --instantiation -o out <path to wasm>
npx jco transpile --instantiation sync -o out <path to wasm>
npx jco transpile -I -o out <path to wasm>
npx jco transpile -I sync -o out <path to wasm>

 # broken
npx jco transpile -o out -I <path to wasm>
npx jco transpile -o out --instantiation <path to wasm>

I'd prefer an option where we fixed only the edge case here -- it looks like in particular this happens when the instantiation argument is the last one entered before the component path, so if we can detect that, we can solve this case at the very least.