Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

stream: add isDisturbed helper #39628

Closed
wants to merge 6 commits into from
Closed

stream: add isDisturbed helper #39628

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d363920
stream: add isDisturbed helper
ronag Aug 2, 2021
ac0a1df
fixup
ronag Aug 2, 2021
8673e33
fixup
ronag Aug 3, 2021
caa8e3b
fixup: readableDidRead readableAborted
ronag Aug 3, 2021
13123c4
fixup
ronag Aug 3, 2021
0dda118
fixup
ronag Aug 3, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions doc/api/stream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2046,6 +2046,18 @@ added: REPLACEME
* `signal` {AbortSignal}
* Returns: {stream.Readable}

### `stream.Readable.isDisturbed(stream)`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the name here could be more expressive, maybe .hasEmittedStreamEvents()? I know it's generic, but so is "disturbed", and it's a bit more precise.

We should also add to the documentation that this only starts being true when data has been emitted (i.e. stream.on('data'), not when data has been requested from the underlying resource (i.e. stream._read()) or made available to the stream implementation (i.e. stream.push()).

Copy link
Member Author

@ronag ronag Aug 3, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the name here could be more expressive, maybe .hasEmittedStreamEvents()? I know it's generic, but so is "disturbed", and it's a bit more precise.

I disagree. It's not just when it has been read, it's also when it has been cancelled/aborted. The WHATWG spec calls this state disturbed. Why make up a different name?

We should also add to the documentation that this only starts being true when data has been emitted (i.e. stream.on('data'), not when data has been requested from the underlying resource (i.e. stream._read()) or made available to the stream implementation (i.e. stream.push()).

I think that it is kind of clear. Neither push nor _read "reads" from the Readable interface. Anyway I'm open for suggestions...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why make up a different name?

The argument is: Because the spec naming isn't typically meant for end-users and streams are very confusing to most of our users anyway basically.

<!-- YAML
added: REPLACEME
-->

> Stability: 1 - Experimental

* `stream` {stream.Readable|ReadableStream}
* Returns: `boolean`

Returns whether the stream has been read from.
ronag marked this conversation as resolved.
Show resolved Hide resolved

### `stream.Readable.toWeb(streamReadable)`
<!-- YAML
added: REPLACEME
Expand Down
2 changes: 1 addition & 1 deletion lib/internal/streams/readable.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1185,7 +1185,7 @@ ObjectDefineProperties(Readable.prototype, {
readableDidRead: {
enumerable: false,
get: function() {
return (
return !!(
ronag marked this conversation as resolved.
Show resolved Hide resolved
this._readableState.dataEmitted ||
this._readableState.endEmitted ||
this._readableState.errorEmitted ||
Expand Down
13 changes: 13 additions & 0 deletions lib/internal/streams/utils.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ const {
} = primordials;

const kDestroyed = Symbol('kDestroyed');
const kIsDisturbed = Symbol('kIsDisturbed');

function isReadableNodeStream(obj) {
return !!(
Expand Down Expand Up @@ -195,8 +196,20 @@ function willEmitClose(stream) {
);
}

function isDisturbed(stream) {
const state = stream && stream._readableState;
return !!(stream && (
stream.readableDidRead ||
isDestroyed(stream) ||
stream[kIsDisturbed] ||
(state && state.endEmitted)
));
}

module.exports = {
kDestroyed,
isDisturbed,
kIsDisturbed,
isClosed,
isDestroyed,
isFinished,
Expand Down
9 changes: 9 additions & 0 deletions lib/internal/webstreams/readablestream.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,10 @@ const {
queueMicrotask,
} = require('internal/process/task_queues');

const {
kIsDisturbed,
} = require('internal/streams/utils');

const {
ArrayBufferViewGetBuffer,
ArrayBufferViewGetByteLength,
Expand Down Expand Up @@ -200,6 +204,7 @@ class ReadableStream {
promise: undefined,
}
};

// The spec requires handling of the strategy first
// here. Specifically, if getting the size and
// highWaterMark from the strategy fail, that has
Expand Down Expand Up @@ -232,6 +237,10 @@ class ReadableStream {
return makeTransferable(this);
}

get [kIsDisturbed]() {
return this[kState].disturbed;
}

/**
* @readonly
* @type {boolean}
Expand Down
1 change: 1 addition & 0 deletions lib/stream.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ const internalBuffer = require('internal/buffer');
const promises = require('stream/promises');

const Stream = module.exports = require('internal/streams/legacy').Stream;
Stream.isDisturbed = require('internal/streams/utils').isDisturbed;
Stream.Readable = require('internal/streams/readable');
Stream.Writable = require('internal/streams/writable');
Stream.Duplex = require('internal/streams/duplex');
Expand Down
4 changes: 3 additions & 1 deletion test/parallel/test-stream-readable-didRead.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
'use strict';
const common = require('../common');
const assert = require('assert');
const Readable = require('stream').Readable;
const { isDisturbed, Readable } = require('stream');

function noop() {}

function check(readable, data, fn) {
assert.strictEqual(readable.readableDidRead, false);
assert.strictEqual(isDisturbed(readable), false);
if (data === -1) {
readable.on('error', common.mustCall());
readable.on('data', common.mustNotCall());
Expand All @@ -28,6 +29,7 @@ function check(readable, data, fn) {
fn();
setImmediate(() => {
assert.strictEqual(readable.readableDidRead, true);
assert.strictEqual(isDisturbed(readable), true);
});
}

Expand Down
50 changes: 50 additions & 0 deletions test/parallel/test-whatwg-readablestream.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
'use strict';

const common = require('../common');
const { isDisturbed } = require('stream');
const assert = require('assert');
const {
isPromise,
Expand Down Expand Up @@ -1520,3 +1521,52 @@ class Source {
readableByteStreamControllerClose(controller);
readableByteStreamControllerEnqueue(controller);
}

{
const stream = new ReadableStream({
start(controller) {
controller.enqueue('a');
controller.close();
},
pull: common.mustNotCall(),
});

const reader = stream.getReader();
(async () => {
isDisturbed(stream, false);
await reader.read();
isDisturbed(stream, true);
})().then(common.mustCall());
}

{
const stream = new ReadableStream({
start(controller) {
controller.close();
},
pull: common.mustNotCall(),
});

const reader = stream.getReader();
(async () => {
isDisturbed(stream, false);
await reader.read();
isDisturbed(stream, true);
})().then(common.mustCall());
}

{
const stream = new ReadableStream({
start(controller) {
},
pull: common.mustNotCall(),
});
stream.cancel();

const reader = stream.getReader();
(async () => {
isDisturbed(stream, false);
await reader.read();
isDisturbed(stream, true);
})().then(common.mustCall());
}