Skip to content

Commit a80916c

Browse files
committed
doc: document stream/iter iterator results and from() identity
Some stream/iter iterators return iterator results that do not inherit from Object.prototype, and from() returns validated sources unchanged. Document both. Assisted-by: OpenCode
1 parent 472848e commit a80916c

1 file changed

Lines changed: 9 additions & 0 deletions

File tree

‎doc/api/stream_iter.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,10 @@ async function run() {
119119
}
120120
```
121121

122+
Some iterators of this module return iterator results (`{ done, value }`
123+
objects) that do not inherit from `Object.prototype`. Code should only rely on
124+
their `done` and `value` properties, as `for await...of` does.
125+
122126
### Transforms
123127

124128
Transforms come in two forms:
@@ -598,6 +602,10 @@ Objects implementing `Symbol.for('Stream.toAsyncStreamable')` or
598602
precedence over the iteration protocols (`Symbol.asyncIterator`,
599603
`Symbol.iterator`).
600604

605+
The readable of a [`push()`][] stream without transforms and the iterables
606+
returned by [`fromReadable()`][] already yield normalized batches, so `from()`
607+
returns them unchanged.
608+
601609
```mjs
602610
import { Buffer } from 'node:buffer';
603611
import { from, text } from 'node:stream/iter';
@@ -2339,6 +2347,7 @@ console.log(textSync(stream)); // 'hello world'
23392347
[`pipeTo()`]: #pipetosource-transforms-writer-options
23402348
[`pull()`]: #pullsource-transforms-options
23412349
[`pullSync()`]: #pullsyncsource-transforms
2350+
[`push()`]: #pushtransforms-options
23422351
[`share()`]: #sharesource-options
23432352
[`stream.Readable`]: stream.md#class-streamreadable
23442353
[`stream.Writable`]: stream.md#class-streamwritable

0 commit comments

Comments
 (0)