Here's a #TypeScript API design challenge I'm working on: adding async support to #Optique (CLI argument parser) without breaking the existing sync API.

The tricky part is combinators—when you compose parsers with object() or or(), the combined parser should automatically become async if any child parser is async, but stay sync if all children are sync. This “mode propagation” needs to work at both type level and runtime.

I've prototyped two approaches and documented findings. If you've tackled similar dual-mode API designs, I'd love to hear how you approached it.

https://github.com/dahlia/optique/issues/52

@hongminhee is there a reason you don’t want to bifurcate the API into `suggest` and `suggestAsync`, `parse` and `parseAsync`, etc? I know it’s more verbose but it keeps the outermost types simple and composable. One of my least favorite parts of yargs is the way they make everything both sync and async. It can lead to really annoying intellisense and complex types.