Skip to content

Commit 3af0b8f

Browse files
tyoshinotyoshino
committed
Merged into the spec at W3C site
1 parent eb16378 commit 3af0b8f

File tree

1 file changed

+8
-247
lines changed

1 file changed

+8
-247
lines changed

‎streams.html

+8-247
Original file line numberDiff line numberDiff line change
@@ -9,250 +9,11 @@
99

1010
<h1 class="head">Streams API (Promises version)</h1>
1111

12-
<dl>
13-
<dt>Participate:
14-
<dd>Send feedback to
15-
[email protected] (<a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>)
16-
17-
<dt>Editor:
18-
<dd>Takeshi Yoshino, Google
19-
</dl>
20-
21-
</div>
22-
23-
<h2 class="no-num no-toc" id="specabstract">Abstract</h3>
24-
25-
<p>This document proposes integration of <a href="https://github.com/domenic/promises-unwrapping/blob/master/README.md">Promises</a> and <a href="https://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm">Streams API</a>.
26-
27-
<h2 class="no-num no-toc" id="toc">Table of Contents</h2>
28-
29-
<!--toc-->
30-
31-
<h2>Interface <code title>Stream</code></h2>
32-
33-
<pre class="idl">
34-
enum <dfn>StreamReadType</dfn> {
35-
&quot;&quot;,
36-
&quot;blob&quot;,
37-
&quot;arraybuffer&quot;,
38-
&quot;text&quot;
39-
};
40-
41-
interface <dfn>StreamConsumeResult</dfn> {
42-
readonly attribute boolean eof;
43-
readonly any data;
44-
readonly unsigned long long size;
45-
};
46-
47-
[<span title="dom-Stream">Constructor</span>(optional DOMString <var>type</var>)]
48-
interface <dfn id="stream">Stream</dfn> {
49-
readonly attribute DOMString <span title="dom-Stream-type">type</span>;
50-
51-
Promise <span title="dom-Stream-write">write</span>((DOMString or ArrayBufferView or Blob)? <var>data</var>);
52-
void <span title="dom-Stream-close">close</span>();
53-
54-
attribute <span>StreamReadType</span> <span title="dom-Stream-readType">readType</span>;
55-
atrribute DOMString <span title="dom-Stream-readEncoding">readEncoding;
56-
57-
Promise <span title="dom-Stream-read">read</span>(optional [Clamp] unsigned long long <var>size</var>);
58-
Promise <span title="dom-Stream-skip">skip</span>(optional [Clamp] unsigned long long <var>size</var>);
59-
Promise <span title="dom-Stream-pipe">pipe</span>((Stream or Stream[]) <var>destinations</var>, optional [Clamp] unsigned long long <var>size</var>);
60-
};</pre>
61-
62-
<p>The
63-
<dfn title="dom-Stream-type"><code>type</code></dfn>
64-
attribute must return the MIME type of the stream.
65-
66-
<h3>Reading and writing</h3>
67-
68-
<p>To <dfn id="write-to-the-stream">write to the stream</dfn> (TBA). Note: success of write() doesn't guarantee that the written data has been read out successfully.
69-
70-
<p>To <dfn id="read-from-the-stream">read from the stream</dfn> (TBA). Written data is read on FIFO basis. Resource will be released as data is read.
71-
72-
<p>To <dfn id="write-close-the-stream">write close the stream</dfn> (TBA).
73-
74-
<h3>Constructor</h3>
75-
76-
<p>The <code>Stream</code> object has associated
77-
<dfn>type</dfn>,
78-
<dfn>write closed flag</dfn>,
79-
<dfn>write pending flag</dfn> and
80-
<dfn>read pending flag</dfn>.
81-
82-
<p>The <code>Stream</code> object represents a data sources for which the total size is unknown until EOF is reached. Using Promises, Streams provides read once access model. Data queued to a stream is read in FIFO order. Data pushed to a stream can be read out only once from it.
83-
84-
<dl class="domintro">
85-
<dt><code><var>stream</var> = new <span title="dom-Stream">Stream</span>()</code>
86-
<dd>
87-
<p>Returns a new <code>Stream</code> object.
88-
89-
<dt><code><var>stream</var> = new <span title="dom-Stream">Stream</span>(type)</code>
90-
<dd>
91-
<p>Returns a new <code>Stream</code> object with its <span>type</span> set to the given value.
92-
</dl>
93-
94-
<h3>The <code title>write()</code> method</h3>
95-
96-
<p>The <dfn title=dom-Stream-write><code>write(<var>data</var>)</code></dfn> method takes a <var>data</var>, and runs these steps:
97-
98-
<ol>
99-
<li>If has been neutered, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
100-
<li>If <span>write closed flag</span> is set, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
101-
<li>If <span>write pending flag</span> is set, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
102-
<li>Set <span>write pending flag</span>.
103-
<li>Let <var>writePromise</var> be a new promise.
104-
<li>Return the <span title=dom-Stream-read>write()</span> method with <var>writePromise</var>, but continue to process the steps in this algorithm.
105-
<li>Follow these rules, depending on <var>data</var>:
106-
<dl class="switch">
107-
<dt>a string
108-
<dd>Let <var>rawData</var> be the result of converting <var>data</var> to a (TBA)
109-
<dt><code>ArrayBufferView</code>
110-
<dd>Let <var>rawData</var> be the raw data represented by the <code>Blob</code> object.
111-
<dt><code>Blob</code>
112-
<dd>Let <var>rawData</var> be the data stored in the section of the buffer described by the <var>ArrayBuffer</var> object that the <code>ArrayBufferView</code> object references.
113-
</dl>
114-
<li><span title="write-to-the-stream">Write <var>rawData</var> to the stream</span>.
115-
<li>If any error has occurred during writing, neuter the stream, let <var>exception</var> be an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and run <code>Reject(<var>writePromise</var>, <var>exception</var>)</code> as specified in the promises spec and terminate these steps.
116-
<li>Unset <span>write pending flag</span> and run <code>Resolve(<var>writePromise</var>, <code>undefined</code>)</code> as specified in the promises spec. Implementations may delay this step if appropriate.
117-
</ol>
118-
119-
<h3>The <code title>close()</code> method</h3>
120-
121-
<p>The <dfn title=dom-Stream-close><code>close(<var>data</var>)</code></dfn> method takes a <var>data</var>, and runs these steps:
122-
123-
<ol>
124-
<li>If has been neutered, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
125-
<li>If <span>write closed flag</span> is set, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
126-
<li>If <span>write pending flag</span> is set, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
127-
<li>Set <span>write closed flag</span>.
128-
<li><span title="write-close-the-stream">Write close the stream</span>.
129-
<li>If any error has occurred during write close alrogithm, neuter the stream and terminate these steps.
130-
</ol>
131-
132-
<h3>The <code title>readType</code> attribute</h3>
133-
134-
<dl class=domintro>
135-
<dt><code><var>stream</var> . <span title=dom-Stream-readType>readType</span> [ = <var>value</var> ]</code>
136-
<dd>
137-
<p>Returns the read type.
138-
<p>Can be set to change the read type. Values are:
139-
the empty string (default),
140-
"<code>arraybuffer</code>",
141-
"<code>blob</code>" and
142-
"<code>text</code>".
143-
</dl>
144-
145-
<p>The
146-
<dfn title="dom-Stream-readType"><code>readType</code></dfn>
147-
attribute must return its value. Initially its value must be the empty string.
148-
149-
<p>Setting the
150-
<code title="dom-Stream-readType">readType</code>
151-
attribute must set its value to the given value.
152-
153-
<h3>The <code title>readEncoding</code> attribute</h3>
154-
155-
<dl class=domintro>
156-
<dt><code><var>stream</var> . <span title=dom-Stream-readEncoding>readEncoding</span> [ = <var>value</var> ]</code>
157-
<dd>
158-
<p>Returns the read encoding.
159-
<p>Can be set to change the read encoding.
160-
</dl>
161-
162-
<p>The
163-
<dfn title="dom-Stream-readEncoding"><code>readEncoding</code></dfn>
164-
attribute must return its value. Initially its value must be the empty string.
165-
166-
<p>Setting the
167-
<code title="dom-Stream-readEncoding">readEncoding</code>
168-
attribute must set its value to the given value.
169-
170-
<h3>The <code title>read()</code> method</h3>
171-
172-
<p>The <dfn title=dom-Stream-read><code>read(<var>size</var>)</code></dfn> method takes optionally a <var>size</var>, and runs these steps:
173-
174-
<ol>
175-
<li>If has been neutered, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
176-
<li>If <span>read pending flag</span> is set, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
177-
<li>If <var>size</var> is specified but is 0, throw a "<code data-anolis-spec=dom>SyntaxError</code>" exception and terminate these steps.
178-
<li>Set <span>read pending flag</span>.
179-
<li>Let <var>readPromise</var> be a new promise.
180-
<li>Return the <span title=dom-Stream-read>read()</span> method with <var>readPromise</var>, but continue to process the steps in this algorithm.
181-
<li>If <var>size</var> is specified, <span title="read-from-the-stream">read data from the stream</span> until <var>size</var> bytes are read.
182-
<li>Otherwise, <span title="read-from-the-stream">read data from the stream</span> until any non-zero bytes are read.
183-
<li>If any error has occurred during reading, neuter the stream, let <var>exception</var> be an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and run <code>Reject(<var>readPromise</var>, <var>exception</var>)</code> as specified in the promises spec and terminate these steps.
184-
<li>Let <var>result</var> be a newly created Object that uses <span>StreamConsumeResult</span> interface.
185-
<li>If EOF is reached, set <var>eof</var> attribute of <var>result</var> to true.
186-
<li>Otherwise, set <var>eof</var> attribute of <var>result</var> set to false.
187-
<li>Set <var>data</var> attribute of <var>result</var> to the result of running these steps.
188-
<dl class="switch">
189-
<dt>If <code title="dom-Stream-readType">readType</code> is the emtpry string or "<code title>text</code>"
190-
<dd>
191-
<ol>
192-
<li>Let charset be utf-8.
193-
<li>If type is (TBA)
194-
<li>If readEncoding is not null, (TBA)
195-
<li>Let <var>result</var> be result of running decode on the read data using fallback encoding charset.
196-
</ol>
197-
<dt>If <code title="dom-Stream-readType">readType</code> is the emtpry string or "<code title>blob</code>"
198-
<dd>Let <var>result</var> be a blob created from the read data
199-
<dt>If <code title="dom-Stream-readType">readType</code> is the emtpry string or "<code title>arraybuffer</code>"
200-
<dd>Let <var>result</var> be an array buffer created from the read data
201-
</dl>
202-
<li>Unset <span>read pending flag</span> and run <code>Resolve(<var>readPromise</var>, <var>result</var>)</code> as specified in the promises spec.
203-
</ol>
204-
205-
<h3>The <code title>skip()</code> method</h3>
206-
207-
<p>The <dfn title=dom-Stream-skip><code>skip(<var>size</var>)</code></dfn> method takes optionally a <var>size</var>, and runs these steps:
208-
209-
<ol>
210-
<li>If has been neutered, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
211-
<li>If <span>read pending flag</span> is set, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
212-
<li>If <var>size</var> is specified but is 0, throw a "<code data-anolis-spec=dom>SyntaxError</code>" exception and terminate these steps.
213-
<li>Set <span>read pending flag</span>.
214-
<li>Let <var>readPromise</var> be a new promise.
215-
<li>Return the <span title=dom-Stream-skip>skip()</span> method with <var>readPromise</var>, but continue to process the steps in this algorithm.
216-
<li>If <var>size</var> is specified, <span title="read-from-the-stream">read data from the stream</span> until <var>size</var> bytes are read.
217-
<li>Otherwise, <span title="read-from-the-stream">read data from the stream</span> until any non-zero bytes are read.
218-
<li>If any error has occurred during reading, neuter the stream, let <var>exception</var> be an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and run <code>Reject(<var>readPromise</var>, <var>exception</var>)</code> as specified in the promises spec and terminate these steps.
219-
<li>Let <var>result</var> be a newly created Object that uses <span>StreamConsumeResult</span> interface.
220-
<li>If EOF is reached, set <var>eof</var> attribute of <var>result</var> to true.
221-
<li>Otherwise, set <var>eof</var> attribute of <var>result</var> set to false.
222-
<li>Set <var>size</var> attribute of <var>result</var> to the size of the read data.
223-
<li>Unset <span>read pending flag</span> and run <code>Resolve(readPromise, result)</code> as specified in the promises spec.
224-
</ol>
225-
226-
<h3>The <code title>pipe()</code> method</h3>
227-
228-
<p>The <dfn title=dom-Stream-pipe><code>pipe(<var>destinations</var>, <var>size</var>)</code></dfn> method takes a <var>destinations</var> and optionally a <var>size</var>, and runs these steps:
229-
230-
<ol>
231-
<li>If has been neutered, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
232-
<li>If <span>read pending flag</span> is set, throw an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and terminate these steps.
233-
<li>If <var>size</var> is specified but is 0, throw a "<code data-anolis-spec=dom>SyntaxError</code>" exception and terminate these steps.
234-
<li>If <var>destinations</var> is a string, let <var>destinations</var> instead be an array consisting of just that string.
235-
<li>Set <span>read pending flag</span>.
236-
<li>Let <var>readPromise</var> be a new promise.
237-
<li>Return the <span title=dom-Stream-pipe>pipe()</span> method with <var>readPromise</var>, but continue to process the steps in this algorithm.
238-
<li>If <var>size</var> is specified, <span title="read-from-the-stream">read data from the stream</span> until <var>size</var> bytes are read.
239-
<li>Otherwise, <span title="read-from-the-stream">read data from the stream</span> until EOF is reached.
240-
<li>As read data becomes available, <span title="write-to-the-stream">write newly read data to <var>destinations</var></span>.
241-
<li>If any error has occurred during reading or writing to <var>destinations</var>, neuter the stream, let <var>exception</var> be an "<code data-anolis-spec=dom>InvalidStateError</code>" exception and run <code>Reject(<var>readPromise</var>, <var>exception</var>)</code> as specified in the promises spec and terminate these steps.
242-
<li>Once read is completed and write are both completed for all destination streams, run the following algorithm:
243-
<ol>
244-
<li>Let <var>result</var> be a newly created Object that uses <span>StreamConsumeResult</span> interface.
245-
<li>If EOF is reached, set <var>eof</var> attribute of <var>result</var> to true.
246-
<li>Otherwise, set <var>eof</var> attribute of <var>result</var> set to false.
247-
<li>Set <var>size</var> attribute of <var>result</var> to the total size of the read data.
248-
<li>Unset <span>read pending flag</span> and run <code>Resolve(<var>readPromise</var>, <var>result</var>)</code> as specified in the promises spec.
249-
</ol>
250-
</ol>
251-
252-
<h2 class=no-num>Acknowledgments</h2>
253-
254-
<p>Thanks to
255-
256-
(TBA mainly from http://lists.w3.org/Archives/Public/public-webapps/2013AprJun/0706.html)
257-
258-
for their useful comments.
12+
<p>
13+
Streams API proposal introduced here has been merged into W3C spec.
14+
Check out
15+
<a href="http://www.w3.org/TR/streams-api/">WD</a>
16+
<a href="https://dvcs.w3.org/hg/streams-api/raw-file/tip/Overview.htm">ED</a>
17+
and <a href="https://dvcs.w3.org/hg/streams-api/raw-file/tip/preview.html">Preview version</a>.
18+
Preview version is the bleeding edge version which incorporates most of suggestions made on the public-webapps@ mailing list experimentally.
19+
</p>

0 commit comments

Comments
 (0)