Feedback for “Express Integration” (docs/500-integrations/100-express.mdx)

[Markyiptw]

Hi, I've been following the hype for effect-ts for a while, and I'm conviced that it would be the standard library for Typescript. While I have spent reasonable amount of effort on learning the basic's (few weekends on reading the docs, different blog posts, and let's say like I understand 80% from "the Beginner / Intermediate Workshop" video), I still don't understand code provided on this page, and I find that frustrating and overwhelming. I mean I have been writing express app for years yet I can't recognize an express hello app?

The reasons I find the example difficult to understand:

1. The apis covered. Layer.scopedDiscard, Layer.effectDiscard, Runtime.runFork, Layer.launch, Effect.runtime just to name a few. Most of them are not covered by the doc's guide, and one have to dig through the api reference, which is not a good experience I would say. Imagine one reading through the guides, feeling "yea I got some building blocks to write an app", but then when they jump into an "hello world" example, it's full of apis that are not covered before.

2. No mentioning on reason why such api is used. For example I undertand that Layer.discard is for side effects, but how is it different from scopedDiscard and effectDiscard? Or say why one have to create const runFork = Runtime.runFork(yield* Effect.runtime<never>()) insdead of just using Effect.runFork?

I suggest to start with an example that only uses apis covered in the guide, then maybe introduce more advanced apis one at the time, where each time replace a "simple" api, and give explanation on how the advanced apis are better.

I am willing to help, beginning by writing a hello world app with my understanding of effect, and being pointed out why such way won't work, and gather those points into the guide and move to a next example, just that I need a place / people for me to ask questions with, like a lot of questions. What do you think?