Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On Aug 23, 2014 2:11 PM, "James Graham" wrote: > > On 22/08/14 19:29, Brian Kardell wrote: > > On Fri, Aug 22, 2014 at 1:52 PM, Anne van Kesteren wrote: > >> On Fri, Aug 22, 2014 at 7:15 PM, Brian Kardell wrote: > >>> I still think that calling it bodyStream actually helps understanding > >>> all you need and it's short/portable... > >>> > >>> response.bodyStream.asJSON() > >>> > >>> seems to at least give the hint that it is a stream that is consumed > >>> without getting too crazy. > >> > >> Well 1), > >> > >> response.json() > >> > >> is short too, much shorter in fact. > >> > > > > It is, but there was concern that is was too short to be clear/might > > actually be confusing before it was further shortened. Making it > > shorter doesn't help that objection - it doesn't make it clearer, does > > it? I'm not saying "this is best" I'm offering a proposal that tries > > to strike the balance with this fact - that's all there is to my > > comment. > > So my opinion is that there are two possible scenarios: > > 1) The API is consistent and friendly enough that, after an initial > period of learning how it works, developers will internalize the > semantics. In this case the short names are sufficient to describe the > functionality and should be preferred because they increase the signal / > noise ratio when reading and writing the code. > > 2) The API has semantics that are so liable to trip up developers that, > without reminder of the behaviour, they will constantly make mistakes. > In this case we should be working out how to design a less unfriendly > API, not bikeshedding which function naming scheme will make the problem > least bad. > > I am slightly concerned that the amount of discussion around naming here > belies a belief that the underlying model is going to cause frustration > for developers. Is that the case? > Speculation on this is tough and has IMO really stymied standards efforts. The best way to know is to put something we think is a good effort out there for real use and get feedback. We're much better of when we can base decisions on data rather than guesswork. Ideally we could reasonably prolyfill the API surface, but for low level primitives, this is tricky. Is there any way we can, even if under the covers it didn't have quite the same implications? If so, let's try. If not, it seems next best would be to get in in a browser or two ASAP and leave it behind a flag until we can collect some. In not sure how negatively this would affect other things like service workers in terms of delays and frustrations though.
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On 22/08/14 19:29, Brian Kardell wrote: > On Fri, Aug 22, 2014 at 1:52 PM, Anne van Kesteren wrote: >> On Fri, Aug 22, 2014 at 7:15 PM, Brian Kardell wrote: >>> I still think that calling it bodyStream actually helps understanding >>> all you need and it's short/portable... >>> >>> response.bodyStream.asJSON() >>> >>> seems to at least give the hint that it is a stream that is consumed >>> without getting too crazy. >> >> Well 1), >> >> response.json() >> >> is short too, much shorter in fact. >> > > It is, but there was concern that is was too short to be clear/might > actually be confusing before it was further shortened. Making it > shorter doesn't help that objection - it doesn't make it clearer, does > it? I'm not saying "this is best" I'm offering a proposal that tries > to strike the balance with this fact - that's all there is to my > comment. So my opinion is that there are two possible scenarios: 1) The API is consistent and friendly enough that, after an initial period of learning how it works, developers will internalize the semantics. In this case the short names are sufficient to describe the functionality and should be preferred because they increase the signal / noise ratio when reading and writing the code. 2) The API has semantics that are so liable to trip up developers that, without reminder of the behaviour, they will constantly make mistakes. In this case we should be working out how to design a less unfriendly API, not bikeshedding which function naming scheme will make the problem least bad. I am slightly concerned that the amount of discussion around naming here belies a belief that the underlying model is going to cause frustration for developers. Is that the case?
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On Fri, Aug 22, 2014 at 1:52 PM, Anne van Kesteren wrote: > On Fri, Aug 22, 2014 at 7:15 PM, Brian Kardell wrote: >> I still think that calling it bodyStream actually helps understanding >> all you need and it's short/portable... >> >> response.bodyStream.asJSON() >> >> seems to at least give the hint that it is a stream that is consumed >> without getting too crazy. > > Well 1), > > response.json() > > is short too, much shorter in fact. > It is, but there was concern that is was too short to be clear/might actually be confusing before it was further shortened. Making it shorter doesn't help that objection - it doesn't make it clearer, does it? I'm not saying "this is best" I'm offering a proposal that tries to strike the balance with this fact - that's all there is to my comment. > 2) We have no idea what the design of what bodyStream's getter returns > is or should be. There was a body property, I merely proposed renaming it to bodyStream. If you're saying that we've definitely decided to not directly expose the stream, merely means of consuming because of the open question of what streams look like, then yes, that's a good argument against what I'm saying... I might have missed that that decision was made, was it? > 3) As already indicated, after you use this once, you realize how it works. Yes and no... It's moderately easier to learn if the API is clearer about what is is, and it's definitely easier to recognize in code without searching for context when 'response' could be several things. It's all a balancing act of cost and benefit (see next comment) > 4) I don't see how yours is more portable than James' proposal. I didn't say it was, I just said it -was- portable... You could imagine carrying the lesson that stream based properties identify themselves as such across the platform - it's not overly long and they would be easily recognizable - maybe that's a good balance, maybe it's not You could definitely make the same argument with .json(), though it's different in the sense that there is no hint as to what you can .json() and what you can't. I'm definitely not saying "bodyStream or it's wrong", but the API when I suggested it as an option at least was discussing methods like response.body.consumeAsJSON which is longer, less clear to me and offers no kind of hints or portability of the idea that I can really see. > > > -- > http://annevankesteren.nl/ -- Brian Kardell :: @briankardell :: hitchjs.com
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On Fri, Aug 22, 2014 at 7:15 PM, Brian Kardell wrote: > I still think that calling it bodyStream actually helps understanding > all you need and it's short/portable... > > response.bodyStream.asJSON() > > seems to at least give the hint that it is a stream that is consumed > without getting too crazy. Well 1), response.json() is short too, much shorter in fact. 2) We have no idea what the design of what bodyStream's getter returns is or should be. 3) As already indicated, after you use this once, you realize how it works. 4) I don't see how yours is more portable than James' proposal. -- http://annevankesteren.nl/
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On Fri, Aug 22, 2014 at 5:26 AM, Anne van Kesteren wrote:
> On Fri, Aug 22, 2014 at 10:32 AM, Jake Archibald
> wrote:
>> On 22 August 2014 07:20, Anne van Kesteren wrote:
>>> That works for me too. I agree that developers will likely learn what
>>> is going on here quickly enough. And that if anything should have long
>>> names, it would be some new API that would use more memory. Jake?
>>
>> Reading a url as some format is really common, so I'm in favour of shorter
>> method names.
>>
>> var data = await (await fetch('/whatever')).asJSON();
>>
>> The consuming behaviour may catch some developers out, once, in their
>> development environment.
>>
>> I don't think Alex & Domenic were as keen & wanted something in the name to
>> represent consuming/taking.
>
> James pointed out on IRC we could simply have this:
>
> response.json()
> response.text()
> request.formData()
>
> I did not like this at first. However, if we care about brevity, and
> we often said we do and act in that manner (see e.g. querySelector ->
> query), he is right. "as" does not really add anything. "bodyAsJSON"
> is a bit more descriptive and "takeBodyAsJSON" is even more, but in
> the end everyone will know very quickly that response/request can only
> have their body read once and will dislike us for having to type those
> extra characters (and will then type another couple to complain about
> it on Twitter).
>
> I checked and none of the existing properties clash with data types we
> might want to add in the future. I think those, combined with exposing
> state through hasBody should be the way forward.
>
>
> --
> http://annevankesteren.nl/
I still think that calling it bodyStream actually helps understanding
all you need and it's short/portable...
response.bodyStream.asJSON()
seems to at least give the hint that it is a stream that is consumed
without getting too crazy.
--
Brian Kardell :: @briankardell :: hitchjs.com
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On Fri, Aug 22, 2014 at 10:32 AM, Jake Archibald wrote:
> On 22 August 2014 07:20, Anne van Kesteren wrote:
>> That works for me too. I agree that developers will likely learn what
>> is going on here quickly enough. And that if anything should have long
>> names, it would be some new API that would use more memory. Jake?
>
> Reading a url as some format is really common, so I'm in favour of shorter
> method names.
>
> var data = await (await fetch('/whatever')).asJSON();
>
> The consuming behaviour may catch some developers out, once, in their
> development environment.
>
> I don't think Alex & Domenic were as keen & wanted something in the name to
> represent consuming/taking.
James pointed out on IRC we could simply have this:
response.json()
response.text()
request.formData()
I did not like this at first. However, if we care about brevity, and
we often said we do and act in that manner (see e.g. querySelector ->
query), he is right. "as" does not really add anything. "bodyAsJSON"
is a bit more descriptive and "takeBodyAsJSON" is even more, but in
the end everyone will know very quickly that response/request can only
have their body read once and will dislike us for having to type those
extra characters (and will then type another couple to complain about
it on Twitter).
I checked and none of the existing properties clash with data types we
might want to add in the future. I think those, combined with exposing
state through hasBody should be the way forward.
--
http://annevankesteren.nl/
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On 22 August 2014 07:20, Anne van Kesteren wrote:
> On Fri, Aug 22, 2014 at 12:27 AM, James Graham
> wrote:
> > I think that adding an extra verb to the names to describe a consistent
> > feature of the API is a mistake; it seems important when designing the
> > API because it's a choice that you have to make, but for the user it's
> > just part of how the API works and not something that needs to be
> > reemphasized in the name of every piece of API surface. For example
> > given a language with immutable strings it would be pure noise to call a
> > method "appendAsNewString" compared to just "append" because all
> > "mutation" methods would consistently create new strings.
>
> So you argue for asX()? Perhaps bodyAsX() to make it clear what field
> of request/response we're talking about. And then hasBody as property
> or some such?
>
> That works for me too. I agree that developers will likely learn what
> is going on here quickly enough. And that if anything should have long
> names, it would be some new API that would use more memory. Jake?
>
Reading a url as some format is really common, so I'm in favour of shorter
method names.
var data = await (await fetch('/whatever')).asJSON();
The consuming behaviour may catch some developers out, once, in their
development environment.
I don't think Alex & Domenic were as keen & wanted something in the name to
represent consuming/taking.
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On Fri, Aug 22, 2014 at 12:27 AM, James Graham wrote: > I think that adding an extra verb to the names to describe a consistent > feature of the API is a mistake; it seems important when designing the > API because it's a choice that you have to make, but for the user it's > just part of how the API works and not something that needs to be > reemphasized in the name of every piece of API surface. For example > given a language with immutable strings it would be pure noise to call a > method "appendAsNewString" compared to just "append" because all > "mutation" methods would consistently create new strings. So you argue for asX()? Perhaps bodyAsX() to make it clear what field of request/response we're talking about. And then hasBody as property or some such? That works for me too. I agree that developers will likely learn what is going on here quickly enough. And that if anything should have long names, it would be some new API that would use more memory. Jake? -- http://annevankesteren.nl/
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On 21/08/14 18:52, Jake Archibald wrote: > "take" was suggested in IRC as an alternative to "consume", which has > precedence http://dom.spec.whatwg.org/#dom-mutationobserver-takerecords > > I'm still worried we're querySelectorAlling (creating long function names > for common actions), but I can live with: > response.takeBodyAsJSON(). I think that adding an extra verb to the names to describe a consistent feature of the API is a mistake; it seems important when designing the API because it's a choice that you have to make, but for the user it's just part of how the API works and not something that needs to be reemphasized in the name of every piece of API surface. For example given a language with immutable strings it would be pure noise to call a method "appendAsNewString" compared to just "append" because all "mutation" methods would consistently create new strings.
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
"take" was suggested in IRC as an alternative to "consume", which has precedence http://dom.spec.whatwg.org/#dom-mutationobserver-takerecords I'm still worried we're querySelectorAlling (creating long function names for common actions), but I can live with: response.takeBodyAsJSON(). On 21 August 2014 18:27, Jake Archibald wrote: > On 21 August 2014 13:27, Anne van Kesteren wrote: > >> On Thu, Aug 21, 2014 at 11:02 AM, Jake Archibald >> wrote: >> > * The as* methods should be directly on the response, and named >> consumeAs*, >> > so response.consumeAsJSON() >> >> Would it be really bad to have these names four characters longer to >> indicate they are about the body of the response? Then we'd have: >> >> consumeBodyAsJSON() >> consumeBodyAsText() >> > > Worried we're making common functions really long here, like > querySelectorAll. > > Going from > > response.body.asJSON() > to > response.consumeAsJSON() > wasn't *too* bad, but > response.consumeBodyAsJSON() > is getting a bit proxyfactorybeangenerator. > > >> >> and >> >> canConsumeBody >> > > This isn't too bad. >
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On 21 August 2014 13:27, Anne van Kesteren wrote: > On Thu, Aug 21, 2014 at 11:02 AM, Jake Archibald > wrote: > > * The as* methods should be directly on the response, and named > consumeAs*, > > so response.consumeAsJSON() > > Would it be really bad to have these names four characters longer to > indicate they are about the body of the response? Then we'd have: > > consumeBodyAsJSON() > consumeBodyAsText() > Worried we're making common functions really long here, like querySelectorAll. Going from response.body.asJSON() to response.consumeAsJSON() wasn't *too* bad, but response.consumeBodyAsJSON() is getting a bit proxyfactorybeangenerator. > > and > > canConsumeBody > This isn't too bad.
Re: [whatwg] [Fetch] API changes to make stream depletion clearer/easier
On Thu, Aug 21, 2014 at 11:02 AM, Jake Archibald wrote: > * The as* methods should be directly on the response, and named consumeAs*, > so response.consumeAsJSON() Would it be really bad to have these names four characters longer to indicate they are about the body of the response? Then we'd have: consumeBodyAsJSON() consumeBodyAsText() and canConsumeBody as indication whether or body is still available for consumption. All other members of the Request object explicitly name what they are about, seems a bit of a miss to not do that there. -- http://annevankesteren.nl/
