[whatwg/streams] Guideline for where to factor out logic (#437)

I'd like to write down a clear well-discussed guidance for at which point we factor out logic and for what purpose.

- make it clear which point is defining semantics and which point is left up to implementors of the API
  - Example: `ReadableStreamAddReadIntoRequest()` (ones listed in the block with the comment "// ReadableStream API exposed for controllers")
- allow optimized invocation with the following logic skipped
  - skip brand checking
    - Example: the `if (IsReadableStream(this) === false)` block in `ReadableStream.getReader()`
  - argument validation
    - Example: `read(view)` with non typed array `view`
  - argument parsing
    - Example: calling `AcquireReadableStreamBYOBReader()` directly than calling `getReader()` (only when the user is sure that it's byte stream)
  - state checking
    - Example: calling `ReadableStreamDefaultReaderRead()` directly than calling `read()`
    - Example (no case): `ReadableStreamDefaultReaderRead()` checks `stream._state` in itself as it's less common that the user is sure in which state the stream is.
    - Example: calling `ReadableStreamDefaultControllerClose()` directly than calling `close()`. The user can know unsolicited closure by listening to cancel() call on the underlying source.
  - result packing
    - Example: calling `ReadableStreamTee()` directly than calling `tee()`
- readability and code simplification


---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/whatwg/streams/issues/437