Skip to content

Commit e5f9033

Browse files
clueclue
committed
Improve promise and type documentation
1 parent bb0ad52 commit e5f9033

File tree

2 files changed

+104
-100
lines changed

2 files changed

+104
-100
lines changed

‎README.md

Lines changed: 51 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -46,28 +46,28 @@ Stream\buffer(…);
4646

4747
### buffer()
4848

49-
The `buffer(ReadableStreamInterface<string> $stream, ?int $maxLength = null): PromiseInterface<string,Exception>` function can be used to
50-
create a `Promise` which resolves with the stream data buffer.
49+
The `buffer(ReadableStreamInterface<string> $stream, ?int $maxLength = null): PromiseInterface<string,RuntimeException>` function can be used to
50+
create a `Promise` which will be fulfilled with the stream data buffer.
5151

5252
```php
5353
$stream = accessSomeJsonStream();
5454

55-
React\Promise\Stream\buffer($stream)->then(function ($contents) {
55+
React\Promise\Stream\buffer($stream)->then(function (string $contents) {
5656
var_dump(json_decode($contents));
5757
});
5858
```
5959

60-
The promise will resolve with all data chunks concatenated once the stream closes.
60+
The promise will be fulfilled with a `string` of all data chunks concatenated once the stream closes.
6161

62-
The promise will resolve with an empty string if the stream is already closed.
62+
The promise will be fulfilled with an empty `string` if the stream is already closed.
6363

64-
The promise will reject if the stream emits an error.
64+
The promise will be rejected with a `RuntimeException` if the stream emits an error.
6565

66-
The promise will reject if it is cancelled.
66+
The promise will be rejected with a `RuntimeException` if it is cancelled.
6767

6868
The optional `$maxLength` argument defaults to no limit. In case the maximum
6969
length is given and the stream emits more data before the end, the promise
70-
will be rejected with an `\OverflowException`.
70+
will be rejected with an `OverflowException`.
7171

7272
```php
7373
$stream = accessSomeToLargeStream();
@@ -83,75 +83,77 @@ React\Promise\Stream\buffer($stream, 1024)->then(function ($contents) {
8383

8484
### first()
8585

86-
The `first(ReadableStreamInterface|WritableStreamInterface $stream, string $event = 'data'): PromiseInterface<mixed,Exception>` function can be used to
87-
create a `Promise` which resolves once the given event triggers for the first time.
86+
The `first(ReadableStreamInterface|WritableStreamInterface $stream, string $event = 'data'): PromiseInterface<mixed,RuntimeException>` function can be used to
87+
create a `Promise` which will be fulfilled once the given event triggers for the first time.
8888

8989
```php
9090
$stream = accessSomeJsonStream();
9191

92-
React\Promise\Stream\first($stream)->then(function ($chunk) {
92+
React\Promise\Stream\first($stream)->then(function (string $chunk) {
9393
echo 'The first chunk arrived: ' . $chunk;
9494
});
9595
```
9696

97-
The promise will resolve with whatever the first event emitted or `null` if the
98-
event does not pass any data.
97+
The promise will be fulfilled with a `mixed` value of whatever the first event
98+
emitted or `null` if the event does not pass any data.
9999
If you do not pass a custom event name, then it will wait for the first "data"
100-
event and resolve with a string containing the first data chunk.
100+
event.
101+
For common streams of type `ReadableStreamInterface<string>`, this means it will be
102+
fulfilled with a `string` containing the first data chunk.
101103

102-
The promise will reject if the stream emits an error – unless you're waiting for
103-
the "error" event, in which case it will resolve.
104+
The promise will be rejected with a `RuntimeException` if the stream emits an error
105+
– unless you're waiting for the "error" event, in which case it will be fulfilled.
104106

105-
The promise will reject once the stream closes – unless you're waiting for the
106-
"close" event, in which case it will resolve.
107+
The promise will be rejected with a `RuntimeException` once the stream closes
108+
– unless you're waiting for the "close" event, in which case it will be fulfilled.
107109

108-
The promise will reject if the stream is already closed.
110+
The promise will be rejected with a `RuntimeException` if the stream is already closed.
109111

110-
The promise will reject if it is cancelled.
112+
The promise will be rejected with a `RuntimeException` if it is cancelled.
111113

112114
### all()
113115

114-
The `all(ReadableStreamInterface|WritableStreamInterface $stream, string $event = 'data'): PromiseInterface<array,Exception>` function can be used to
115-
create a `Promise` which resolves with an array of all the event data.
116+
The `all(ReadableStreamInterface|WritableStreamInterface $stream, string $event = 'data'): PromiseInterface<array,RuntimeException>` function can be used to
117+
create a `Promise` which will be fulfilled with an array of all the event data.
116118

117119
```php
118120
$stream = accessSomeJsonStream();
119121

120-
React\Promise\Stream\all($stream)->then(function ($chunks) {
122+
React\Promise\Stream\all($stream)->then(function (array $chunks) {
121123
echo 'The stream consists of ' . count($chunks) . ' chunk(s)';
122124
});
123125
```
124126

125-
The promise will resolve with an array of whatever all events emitted or `null` if the
126-
events do not pass any data.
127+
The promise will be fulfilled with an `array` once the stream closes. The array
128+
will contain whatever all events emitted or `null` values if the events do not pass any data.
127129
If you do not pass a custom event name, then it will wait for all the "data"
128-
events and resolve with an array containing all the data chunks.
130+
events.
131+
For common streams of type `ReadableStreamInterface<string>`, this means it will be
132+
fulfilled with a `string[]` array containing all the data chunk.
129133

130-
The promise will resolve with an array once the stream closes.
134+
The promise will be fulfilled with an empty `array` if the stream is already closed.
131135

132-
The promise will resolve with an empty array if the stream is already closed.
136+
The promise will be rejected with a `RuntimeException` if the stream emits an error.
133137

134-
The promise will reject if the stream emits an error.
135-
136-
The promise will reject if it is cancelled.
138+
The promise will be rejected with a `RuntimeException` if it is cancelled.
137139

138140
### unwrapReadable()
139141

140-
The `unwrapReadable(PromiseInterface<ReadableStreamInterface,Exception> $promise): ReadableStreamInterface` function can be used to
141-
unwrap a `Promise` which resolves with a `ReadableStreamInterface`.
142+
The `unwrapReadable(PromiseInterface<ReadableStreamInterface<T>,Exception> $promise): ReadableStreamInterface<T>` function can be used to
143+
unwrap a `Promise` which will be fulfilled with a `ReadableStreamInterface<T>`.
142144

143-
This function returns a readable stream instance (implementing `ReadableStreamInterface`)
145+
This function returns a readable stream instance (implementing `ReadableStreamInterface<T>`)
144146
right away which acts as a proxy for the future promise resolution.
145-
Once the given Promise resolves with a `ReadableStreamInterface`, its data will
146-
be piped to the output stream.
147+
Once the given Promise will be fulfilled with a `ReadableStreamInterface<T>`, its
148+
data will be piped to the output stream.
147149

148150
```php
149151
//$promise = someFunctionWhichResolvesWithAStream();
150152
$promise = startDownloadStream($uri);
151153

152154
$stream = React\Promise\Stream\unwrapReadable($promise);
153155

154-
$stream->on('data', function ($data) {
156+
$stream->on('data', function (string $data) {
155157
echo $data;
156158
});
157159

@@ -176,9 +178,8 @@ $stream->on('error', function (Exception $error) {
176178

177179
The given `$promise` SHOULD be pending, i.e. it SHOULD NOT be fulfilled or rejected
178180
at the time of invoking this function.
179-
If the given promise is already settled and does not resolve with an
180-
instance of `ReadableStreamInterface`, then you will not be able to receive
181-
the `error` event.
181+
If the given promise is already settled and does not fulfill with an instance of
182+
`ReadableStreamInterface`, then you will not be able to receive the `error` event.
182183

183184
You can `close()` the resulting stream at any time, which will either try to
184185
`cancel()` the pending promise or try to `close()` the underlying stream.
@@ -195,14 +196,16 @@ $loop->addTimer(2.0, function () use ($stream) {
195196

196197
### unwrapWritable()
197198

198-
The `unwrapWritable(PromiseInterface<WritableStreamInterface,Exception> $promise): WritableStreamInterface` function can be used to
199-
unwrap a `Promise` which resolves with a `WritableStreamInterface`.
199+
The `unwrapWritable(PromiseInterface<WritableStreamInterface<T>,Exception> $promise): WritableStreamInterface<T>` function can be used to
200+
unwrap a `Promise` which will be fulfilled with a `WritableStreamInterface<T>`.
200201

201-
This function returns a writable stream instance (implementing `WritableStreamInterface`)
202+
This function returns a writable stream instance (implementing `WritableStreamInterface<T>`)
202203
right away which acts as a proxy for the future promise resolution.
203-
Any writes to this instance will be buffered in memory for when the promise resolves.
204-
Once the given Promise resolves with a `WritableStreamInterface`, any data you
205-
have written to the proxy will be forwarded transparently to the inner stream.
204+
Any writes to this instance will be buffered in memory for when the promise will
205+
be fulfilled.
206+
Once the given Promise will be fulfilled with a `WritableStreamInterface<T>`, any
207+
data you have written to the proxy will be forwarded transparently to the inner
208+
stream.
206209

207210
```php
208211
//$promise = someFunctionWhichResolvesWithAStream();
@@ -234,9 +237,8 @@ $stream->on('error', function (Exception $error) {
234237

235238
The given `$promise` SHOULD be pending, i.e. it SHOULD NOT be fulfilled or rejected
236239
at the time of invoking this function.
237-
If the given promise is already settled and does not resolve with an
238-
instance of `WritableStreamInterface`, then you will not be able to receive
239-
the `error` event.
240+
If the given promise is already settled and does not fulfill with an instance of
241+
`WritableStreamInterface`, then you will not be able to receive the `error` event.
240242

241243
You can `close()` the resulting stream at any time, which will either try to
242244
`cancel()` the pending promise or try to `close()` the underlying stream.

0 commit comments

Comments
 (0)