{"action":"created","issue":{"url":"https://api.github.com/repos/whatwg/streams/issues/295","labels_url":"https://api.github.com/repos/whatwg/streams/issues/295/labels{/name}","comments_url":"https://api.github.com/repos/whatwg/streams/issues/295/comments","events_url":"https://api.github.com/repos/whatwg/streams/issues/295/events","html_url":"https://github.com/whatwg/streams/issues/295","id":60681378,"number":295,"title":"What types does ReadableByteStream's reader's read(x) accept and return?","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},"labels":[{"url":"https://api.github.com/repos/whatwg/streams/labels/byte%20streams","name":"byte streams","color":"5319e7"}],"state":"open","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/whatwg/streams/milestones/3","html_url":"https://github.com/whatwg/streams/milestones/Async%20read%20final%20public%20API","labels_url":"https://api.github.com/repos/whatwg/streams/milestones/3/labels","id":1016689,"number":3,"title":"Async read final public API","description":null,"creator":{"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},"open_issues":2,"closed_issues":0,"state":"open","created_at":"2015-03-11T15:45:33Z","updated_at":"2015-06-04T04:51:47Z","due_on":null,"closed_at":null},"comments":21,"created_at":"2015-03-11T15:58:51Z","updated_at":"2015-06-04T05:35:24Z","closed_at":null,"body":"Per #253 the \"bring your own buffer\" reader for ReadableByteStream will generally be of the form\r\n\r\n```\r\nbyobReader.read(view : ArrayBufferView) -> Promise<ArrayBufferView>\r\n```\r\n\r\nThe reason for an ArrayBufferView for the argument is that it allows authors to supply the (buffer, offset, maxLength) trio all at once. The reason for the ArrayBufferView for the return type is that it gives back (buffer, bytesRead), plus the offset if one was supplied, all at once.\r\n\r\nFor the input, there are a few possibilities:\r\n\r\n- Only allow a specific type: `Uint8Array` and `DataView` are the big candidates\r\n- Allow any array buffer view (including `DataView`), with nominal typing\r\n- Allow any `{ buffer, byteOffset, byteLength }` structure; all array buffer views match this, but it would also allow user-supplied structures if they only have a buffer handy (and we could even default byteOffset = 0 and byteLength = buffer.byteLength).\r\n- Allow any array buffer view (either nominal or structural), but *also* allow array buffers directly.\r\n\r\nI think the most lenient option here is probably best: allow structural array buffer views or array buffers directly. Alternately we could just allow structural array buffer views. The only difference is that the former allows `.read(ab)` whereas the latter requires `.read({ buffer: ab })`.\r\n\r\nFor the return type, I think our choices are: `Uint8Array` or `DataView`. Here `DataView` feels a bit more general---less like \"picking favorites\". (Why not `Int8Array`? Why not `Uint8ClampedArray`?) But it is also less useful, I think---it doesn't have the nice array methods like `map`/`filter`/etc., or the typed array methods like `set`, and it exposes you to endianness concerns (I think)...\r\n\r\nI think `Uint8Array` is best here."},"comment":{"url":"https://api.github.com/repos/whatwg/streams/issues/comments/108732963","html_url":"https://github.com/whatwg/streams/issues/295#issuecomment-108732963","issue_url":"https://api.github.com/repos/whatwg/streams/issues/295","id":108732963,"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},"created_at":"2015-06-04T05:35:23Z","updated_at":"2015-06-04T05:35:23Z","body":"I also considered to return (fulfill the returned promise with) a tuple of the view and the number of filled bytes.\r\n\r\nBut, ... if the consumer wants to fill only part (not aligned to the boundaries of elements) of a TypedArray with non-1 BYTES_PER_ELEMENT, they can still choose to extract the underlying buffer and pass wrapped with a Uint8Array to the BYOB interface. So, maybe, it makes more sense to give a functionality of aligned filling (i.e. returns only when at least one element is fully filled, and with no partially filled elements) to invocation of read(view) with a TypedArray with non-1 BYTES_PER_ELEMENT."}}