Early draft of WritableStream "Design Philosophy" section #718

ricea · 2017-03-29T09:44:48Z

This is supposed to help implementors and others understand the design
principles.

Markup isn't done properly yet, so please evaluate the text only.

This is supposed to help implementors and others understand the design principles. Markup isn't done properly yet, so please evaluate the text only.

ricea · 2017-03-29T09:47:52Z

@domenic @tyoshino Suggestions, comments, radical changes all welcome.

I uploaded it as a whatwg/streams branch to make it easy to look at the preview, which should show up at
https://streams.spec.whatwg.org/branch-snapshots/writable-streams-design-philosophy/ eventually.

Also about developer predictability > implementation simplicity.

domenic · 2017-03-30T04:04:37Z

index.bs

+
+<ul>
+  <li><p>Only one sink method can ever be executing at a time.
+  <li><p>Sink methods are treated as atomic.


IMO this can be one paragraph instead of sub-bullets

Should I use paragraphs for everything instead of sub-bullets? I quite like the sub-bullets to be honest.

domenic · 2017-03-30T04:05:07Z

index.bs

+  <li><p>Sink methods are treated as atomic.
+    <ul>
+      <li><p>"Atomic" here means that the time between a sink method being called and the returned Promise resolving or
+        rejecting is treated as indivisible.


This doesn't really clarify. What would divide them? I think the next bullet points actually state what atomic means.

I just took this out.

domenic · 2017-03-30T04:06:13Z

index.bs

+      <li><p>"Atomic" here means that the time between a sink method being called and the returned Promise resolving or
+        rejecting is treated as indivisible.
+      <li><p>A new sink method will never be called until the Promise from the previous one has resolved.
+      <li><p>State changes do not take effect until any in-flight sink method has completed.


"State changes" isn't too clear here, especially given the next two bullet points worth of exceptions.

Reworded a bit.

domenic · 2017-03-30T04:06:49Z

index.bs

+  now would be effective.
+      <ul>
+        <li>writer.ready and writer.desiredSize will change even in the middle of executing a sink method, as soon as we
+        know that calling writer.write() won't work any more.


They also change in cases besides "won't work" though

Reworded a bit.

domenic · 2017-03-30T04:07:25Z

index.bs

+          <div class=note>Because promises are dispatched asynchronously, the state can still change between
+          writer.ready becoming fulfilled and write() being called.</div>
+        <li>The value of writer.desiredSize decreases synchronously with every call to writer.write(). This implies that
+        strategy.size() is executed synchronously.


Given how we're not calling strategy.size as a method, I'd state this as "the queuing strategy's size() function is executed..."

domenic · 2017-03-30T04:08:02Z

index.bs

+   <li><p>The writer.closed promise and the promises returned by writer.close() and writer.abort() do not resolve or
+   reject until no sink methods are executing and no further sink methods will be executing.
+       <ul>
+         <li>If the user of the WritableStream wants to retry against the same underlying data item, it is important to


"data item" = chunk?

"Retry against" is a bit confusing to me.

I tried to clarify by using the example of a file, rather than try to come up with a general term for "named or otherwise identifiable entities which can be retried independently of the lifetime of any particular stream".

domenic · 2017-03-30T04:08:29Z

index.bs

+         have confidence that all other operations have ceased.
+         <li>This principle also applies to the ReadableStream pipeTo() method.
+       </ul>
+    <li><p>Promises resolve or reject in consistent order. In particular, writer.ready always resolves before


I think "fulfill" is more informative here (although both are technically accurate)

domenic · 2017-03-30T04:08:51Z

index.bs

+         <li>This principle also applies to the ReadableStream pipeTo() method.
+       </ul>
+    <li><p>Promises resolve or reject in consistent order. In particular, writer.ready always resolves before
+    writer.closed, even in cases where they both resolve "at the same time".


I'd state this as "where both are fulfilling in reaction to the same occurrence"

Great! Thanks.

domenic · 2017-03-30T04:09:32Z

index.bs

+    writer.closed, even in cases where they both resolve "at the same time".
+</ul>
+
+<div>Some of these design decisions improve predictability, ease-of-use and safety for developers at the expense of


Oxford comma please (after "ease-of-use")

I know it's not markup-critiquing time yet but this <div> seems pretty unnecessary :)

I think this could move up to merge with the intro actually.

Moved it up and made it a paragraph.

domenic · 2017-03-30T04:11:35Z

index.bs

+<h3 id="ws-design-philosopy">Design Philosophy</h3>
+
+<div>While sharing the principles for streams in general, a number of additional principles have informed the design of
+the WritableStream class.</div>


I wonder if we can make clearer the "scope" of this section. It's got great info but it's of a very specific kind. It's not about the philosophy behind writable streams in general (of the type of stuff covered by the "Model" section). It's more about the details of its API surface and the interactions between the sink, controller, and writer APIs. Not sure on the exact phrasing, but that might be a start.

I changed the name to "Design Of The State Machine" which may or may not be helpful.

ricea · 2017-03-30T05:44:33Z

I added another item, "Queued calls to writer methods such as write() are not cancelled when writer.releaseLock() is called. This makes them easy to use in a "fire and forget" style." which raises the question of exactly how much detail belongs in this section.

Personally I'm happy with it being quite inclusive, but I don't think it should be an exhaustive list of every design decision we ever made.

Maybe I should rephrase it as "Fire-and-forget style usage is supported. Therefore..."

ricea · 2018-03-08T05:41:22Z

index.bs

@@ -2568,6 +2568,45 @@ nothrow>ReadableByteStreamControllerShouldCallPull ( <var>controller</var> )</h4
  writeRandomBytesForever(myWritableStream).catch(e => console.error("Something broke", e));
  </code></pre>
 </div>
+
+<h3 id="ws-design-of-the-state-machine">Design Of The State Machine</h3>
+


(Needs to be marked non-normative)

Ansiic112

http://index.bs

Early draft of WritableStream "Design Philosophy" section

aacefe1

This is supposed to help implementors and others understand the design principles. Markup isn't done properly yet, so please evaluate the text only.

Add note about consistent order of promise resolution

0957442

Also about developer predictability > implementation simplicity.

domenic reviewed Mar 30, 2017

View reviewed changes

domenic added documentation writable streams labels Mar 30, 2017

ricea added 2 commits March 30, 2017 14:37

Changes to the text

333f6ae

Change the id of the title to match

c32b030

ricea commented Mar 8, 2018

View reviewed changes

ricea added the do not merge yet Pull request must not be merged per rationale in comment label Mar 8, 2018

Base automatically changed from master to main January 15, 2021 07:25

Ansiic112 reviewed May 14, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Early draft of WritableStream "Design Philosophy" section #718

Early draft of WritableStream "Design Philosophy" section #718

ricea commented Mar 29, 2017 •

edited by pr-preview bot

ricea commented Mar 29, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

domenic Mar 30, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

domenic Mar 30, 2017

ricea Mar 30, 2017

ricea commented Mar 30, 2017

ricea Mar 8, 2018

Ansiic112 left a comment

Early draft of WritableStream "Design Philosophy" section #718

Are you sure you want to change the base?

Early draft of WritableStream "Design Philosophy" section #718

Conversation

ricea commented Mar 29, 2017 • edited by pr-preview bot

ricea commented Mar 29, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ricea commented Mar 30, 2017

Choose a reason for hiding this comment

Ansiic112 left a comment

Choose a reason for hiding this comment

ricea commented Mar 29, 2017 •

edited by pr-preview bot