ReadableStream.from() static method

[hamishwillee]

This adds docs for the new ReadableStream.from() static method, added in FF117 in https://bugzilla.mozilla.org/show_bug.cgi?id=1772772

Related docs work can be tracked in #28282

[github-actions]

Preview URLs

• /en-US/docs/Web/API/ReadableStream/from_static
• /en-US/docs/Web/API/ReadableStream

(comment last updated: 2023-08-21 00:58:16)

[wbamberg]

We have a template structure for live samples: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples#traditional_live_samples. Although technically authors have a lot of flexibility in how to organize them, I'd prefer us to use a much more consistent approach, because it might make it possible for us to extract live samples and have them be usable in other contexts.

This would include having code blocks in a consistent order, with subheadings, and with prose in a consistent place (at the start of the example)

But maybe I'm fighting a losing battle here.

[hamishwillee]

But maybe I'm fighting a losing battle here.

@wbamberg I did it this way, in particular, because I understood that now the code blocks include their "type" the headings are not needed or wanted. With their removal I find the documentation easier to parse, because the isn't quite so much scrolling between the relevant bits.

If you tell me I must change, then I will, but I'm not keen :-)

[hamishwillee]

Ah, I see you marked this as requiring approval, so you do need it changed. Bah. Will do.

[wbamberg]

I can't really tell you you must change. I can say that unless examples are consistently organized then it won't be possible to include them in other contexts, and any tool which tries to do that will most likely throw them out (or maybe we will just throw out the explanatory prose, and hope the example still makes sense).

But I don't know if this use case is important enough to be worth the cost of imposing more constraints on authors. I think it is, but maybe others don't.

[hamishwillee]

I've added the sections in for the first example, unhiding the code that shows how logging works. In the second section I just have the JavaScript section: showing it once perhaps makes sense so there is no "magic" involved in the description, but showing it twice in the page when it is not central to the example seems unhelpful.

I "fairly" strongly feel that this use case is not workable, or even all that useful, and certainly not worth the constraint. Remember all the reasons we decided to remove the page inclusion macro - same problems. The "fairly" is because perhaps you have thought through some cases where content mismatch is not an issue.

I think these headings should be removed. But only after it's agree and https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Code_examples is updated :-)

[hamishwillee]

https://github.com/orgs/mdn/discussions/439

[wbamberg]

It would be great to have some kind of real-world usage example. I find the whole readable streams thing so abstract. In particular it's obviously weird to create a readable stream from an array...so you can iterate it like an array. But I expect this would be quite hard to do (all the other stream examples I've seen look incredibly complicated to me).

[hamishwillee]

You're not wrong - they are very abstract, which is why for readable byte stream examples I mocked the spec examples to pretend I had a read data socket.

In this case I couldn't find a real example in the spec or think of one myself. I mean I kind of can "I prefer readable streams to waiting on arrays of promises" so I do it this way. But it's not "really real".

Worth asking the spec authors?

[wbamberg]

Thanks Hamish. I think it would be good if the examples here followed a more standard organization, and I don't think we should hide significant code. Otherwise this looks great.

[wbamberg]

👍