[Suggestion]: An examples directory would be great

[awareness481]

An examples directory which some implementations of common usages would be great.

For example, I was trying to implement get a basic api fetch to give the library a test-ride but I couldn't get it working. Hopefully, if I ever get a hang of the library, I could contribute examples myself but that is not something I can do right now.

Btw, I wanted to say that the library looks great!

(P.S Since I'm here, could some github tags be added so the library is more discoverable? I couldn't recall its name once and I couldn't find it when I was searching for functional monad etc)

[supermacro]

Hey awareness481,

I think that's a great idea.

I think the structure in this repo could be:

|
| -- src/  <-- same src directory as before
|
| -- examples/
     |
     | -- http-client/
           |
           | -- package.json <-- install a specific version of neverthrow
           |
           | -- index.ts
           |
           | -- README.md

Something along those lines. There would probably need to be a shared tsconfig.json file.

Are you open to leading this effort? I could also provide code review on how to go about creating an http client that uses neverthrow since you were having some difficulties implementing that.

---

Regarding tags, I've gone ahead and added two tags:

• typescript
• functional-programming

But in general, I like to stay clear of theoretical terms such as Algebraic Data Types and Monad because it tends to scare people away sometimes. A design goal for this package has always been to use as little theoretical concepts as possible and make pragmatic tradeoffs in exchange for adoption and lowering learning curve.

[pandu-supriyono]

Late to the party, and I feel like the examples in the API docs are quite good already.

Though I can understand that someone might need more contextually rich examples.

I've been playing around with the library and checking out the source and am feeling quite comfortable enough to work on this if you feel this is necessary.

[supermacro]

This would be a much-appreciated contribution!

[pandu-supriyono]

Great, in that case I'm on it. Did you already happen to have something in mind with regards to how the examples should look?

I'm thinking something to the likes of:

|
| -- src/
| -- examples/
    | -- package.json
    | -- README.md
    | -- synchronous.ts
    | -- asynchronous.ts
    | -- http-client.ts <-- a more integrated/contextually rich example combining sync and async functions, 
                            as well as some utility functions in a trivial Koa or Express app?

I'll keep in mind to leave the FP terms behind considering the design philosophy of this lib.
In my opinion, the idea of composing safe functions deserves quite some attention and I would emphasize that in the examples.

[supermacro]

Yes that's perfect. No need to have nested subprojects.

If I understand correctly, each file is a self-contained example - which is great.

I could contribute an http-server.ts example with express under the hood that enforces request handlers to return a ResultAsync<AppData<T>, RouteError> type.

[caschbre]

More concrete examples would definitely be useful, especially for some of us who are new to the monad concepts and typescript. I've read through the wiki, watched the Railway video, etc. and overall I love the idea and approach... but I'm struggling to turn it into practical code.

I'd also suggest that with each example, show the traditional (non neverthrow) example and then show how you would convert it to use neverthrow.

I'd also add that start with simple examples and then have some examples build upon others. Some of the few examples I've seen seem like they're demonstrating multiple capabilities so I'm stuck figuring out what is required, what's extra, etc.