Is runFork really the preferred method for running effects?

[tmcw]

What is the type of issue?

Documentation is confusing

What is the issue?

The docs for runFork say that

Unless you have a specific need for a Promise or a synchronous operation, Effect.runFork is the recommended choice.

This is confusing to me:

• I'd expect the documentation to mention runFork more than runPromise, but it mentions runFork 11 times and barely documents it, and mentions runPromise 62 times.
• If runFork is a core, recommended way to run code, I'd expect it to have documentation in the API Reference, but it is undocumented with no JSDoc description or anything, just a type signature.

The only example of using runFork in the running effects documentation is extremely contrived - if I wanted to, say, "get the result of the effect," I have no idea how to do that. It seems like i'd interrupt the fiber intermittently until it returns, but that seems weird, inefficient, and very different from the norms of promises or async/await or anything else in TS, and there are no examples of doing that.

Where did you find it?

https://effect.website/docs/guides/essentials/running-effects#runfork