Res stream example

[tbuchok]

this build off the previous PR #1269

merging in order should be fine, i made this difficult didn't i? ... sigh, time for the weekend 💥

• adds additional example for handling "response" events, copied from Can I detect the statusCode of the request and then pipe it to a stream? #1268

[tbuchok]

Todos before merging (I will do):

• use options => Shouldn't need encodeUriComponent
• add request#abort in error handling

[FredKSchott]

Looks cool! Definitely a great idea for an example.

[FredKSchott]

not sure what value this code block adds, it seems very confusing, especially to a newbie. Could you distill this down to a single, smaller concept?

[FredKSchott]

One thing that I remember I struggled with was how the 'response' event could work with piping. And how you could listen to the 'response' event to make whatever changes you needed to make and thennnn pipe it.

It would be nice to explain how the 'response' event and 'piping' can be used together.

[tbuchok]

thanks @FredKSchott. added a couple commits:

• cleaned up the to-dos i'd mentioned
• added yet a THIRD example, with the "response" event stuff you mentioned (see below)

i'm unclear on a couple things:

1. first item says "not sure what this is, can you condense to a single, smaller concept" -- which is listed on the smaller of the two examples.
2. second comment mentions "super-clear" on the longer example

happy to remove either/or/both/etc. -- any further thoughts after your initial pass reviewing? now we're at three examples, so culling this down a bit is +1 on my end. let me know which/if any we'd like to keep!

[tbuchok]

grrr -- i am now TOTALLY clear on your comments @FredKSchott. was reading them out of order. let's definitely remove the longer of the two original examples -- take a look at this third and see if you'd like to keep. got it. sorry for confusion. 🎱

[FredKSchott]

I like it, although there's a lot going on there. The user has to understand what the content type header is, how the mime module works, etc. Is there a way we could make that example simpler, without as many dependencies?

Also, the headers should explain the concept you're trying to introduce / give an example of, rather than the specifics of that example. A user looking for help with content types could want advice on 1000s of things, not just piping.

Love the extra resources though! Just remember to keep them simple, and understandable to as newbie of a person as possible.

[tbuchok]

thanks, @FredKSchott. do you have something else in mind that you might be able to point me in the right direction? the mime example is something i've personally used in the past, so that's why its there 💥

the intent was to react to your feedback:

It would be nice to explain how the 'response' event and 'piping' can be used together.

this PR currently contains three examples:

1. a simple one listening for the response then showing how to access statusCode and headers object
2. another showing how to handle different statusCodes and aborting
3. finally an example with "a lot going on" that shows how to use the response object directly as the readable stream

any / all / none -- we can close this if they're not hitting the mark. that's just fine. appreciate the input thus far.

if you have some other direction, happy to update -- otherwise not sure how much further i can take this swinging blindly. let me know!

[FredKSchott]

Hey @tbuchok, sorry for leaving you hanging with this PR. I'm not sure if you're still interested in pushing this through, but I'd love to get it in. If you still are, here is what I would need to merge:

Each section/example should have a single purpose, usually to introduce 1 concept.

So for a simple example of what I mean: your first example introduces the idea of listening for the response event, which is great. But the example is titled Responses: statusCode, headers, et. al which sounds like it is introducing lots of concepts. This could easily overwhelm a newbie, which is bad.

Another example: Your entire second code block is very overwhelming, even for me. What is your purpose for including it (what 1 concept do you want someone to learn from reading it) and whats the fewest number of lines you can convey that concept in?

[tbuchok]

agreed it's overwhelming. let's close and re-eval. there's mega discussions on docs right now, let's see where that lands and we can wiggle a couple smaller examples into place when ready. thanks again for the review, fred.

[FredKSchott]

@tbuchok Understood, thanks for taking the time!