{"action":"created","issue":{"url":"https://api.github.com/repos/whatwg/streams/issues/437","repository_url":"https://api.github.com/repos/whatwg/streams","labels_url":"https://api.github.com/repos/whatwg/streams/issues/437/labels{/name}","comments_url":"https://api.github.com/repos/whatwg/streams/issues/437/comments","events_url":"https://api.github.com/repos/whatwg/streams/issues/437/events","html_url":"https://github.com/whatwg/streams/issues/437","id":148268000,"number":437,"title":"[Guideline] Where to factor out logic","user":{"login":"tyoshino","id":4511440,"avatar_url":"https://avatars.githubusercontent.com/u/4511440?v=3","gravatar_id":"","url":"https://api.github.com/users/tyoshino","html_url":"https://github.com/tyoshino","followers_url":"https://api.github.com/users/tyoshino/followers","following_url":"https://api.github.com/users/tyoshino/following{/other_user}","gists_url":"https://api.github.com/users/tyoshino/gists{/gist_id}","starred_url":"https://api.github.com/users/tyoshino/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tyoshino/subscriptions","organizations_url":"https://api.github.com/users/tyoshino/orgs","repos_url":"https://api.github.com/users/tyoshino/repos","events_url":"https://api.github.com/users/tyoshino/events{/privacy}","received_events_url":"https://api.github.com/users/tyoshino/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/whatwg/streams/labels/editorial","name":"editorial","color":"c7def8"},{"url":"https://api.github.com/repos/whatwg/streams/labels/reference%20implementation","name":"reference implementation","color":"d4c5f9"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2016-04-14T06:53:11Z","updated_at":"2016-04-15T21:35:44Z","closed_at":null,"body":"I'd like to write down a clear well-discussed guidance for at which point we factor out logic and for what purpose.\r\n\r\n- make it clear which point is defining semantics and which point is left up to implementors of the API\r\n  - Example: `ReadableStreamAddReadIntoRequest()` (ones listed in the block with the comment \"// ReadableStream API exposed for controllers\")\r\n- allow optimized invocation with the following logic skipped\r\n  - skip brand checking\r\n    - Example: the `if (IsReadableStream(this) === false)` block in `ReadableStream.getReader()`\r\n  - argument validation\r\n    - Example: `read(view)` with non typed array `view`\r\n  - argument parsing\r\n    - Example: calling `AcquireReadableStreamBYOBReader()` directly than calling `getReader()` (only when the user is sure that it's byte stream)\r\n  - state checking\r\n    - Example: calling `ReadableStreamDefaultReaderRead()` directly than calling `read()`\r\n    - 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.\r\n    - Example: calling `ReadableStreamDefaultControllerClose()` directly than calling `close()`. The user can know unsolicited closure by listening to cancel() call on the underlying source.\r\n  - result packing\r\n    - Example: calling `ReadableStreamTee()` directly than calling `tee()`\r\n- readability and code simplification\r\n"},"comment":{"url":"https://api.github.com/repos/whatwg/streams/issues/comments/210656885","html_url":"https://github.com/whatwg/streams/issues/437#issuecomment-210656885","issue_url":"https://api.github.com/repos/whatwg/streams/issues/437","id":210656885,"user":{"login":"domenic","id":617481,"avatar_url":"https://avatars.githubusercontent.com/u/617481?v=3","gravatar_id":"","url":"https://api.github.com/users/domenic","html_url":"https://github.com/domenic","followers_url":"https://api.github.com/users/domenic/followers","following_url":"https://api.github.com/users/domenic/following{/other_user}","gists_url":"https://api.github.com/users/domenic/gists{/gist_id}","starred_url":"https://api.github.com/users/domenic/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/domenic/subscriptions","organizations_url":"https://api.github.com/users/domenic/orgs","repos_url":"https://api.github.com/users/domenic/repos","events_url":"https://api.github.com/users/domenic/events{/privacy}","received_events_url":"https://api.github.com/users/domenic/received_events","type":"User","site_admin":false},"created_at":"2016-04-15T21:35:44Z","updated_at":"2016-04-15T21:35:44Z","body":"So, my guidelines have been mainly:\r\n\r\n- Factor out when used more than once to avoid duplication\r\n- Factor out when it might be called by external specs (\"General Readable Stream Abstract Operations\" plus ReadableStreamDefaultController{Close,Enqueue,Error,GetDesiredSize}, ReadableStreamDefaultReaderRead, etc.)\r\n  - This covers skipping brand checking, argument validation, argument parsing, and state checking largely; we assume other specs preserve the appropriate invariants and so we don't need to check them and throw errors. That is, only author code is potentially \"malicious\" in this way.\r\n\r\nThe \"Readable Stream Abstract Operations Used by Controllers\" separation also drives things somewhat.\r\n\r\nHope this helps?"}}