fs,net: standardize pending stream property

Use the same property name as http2 does to indicate that
the stream is in the state before the `ready` event is emitted.

PR-URL: #24067
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Minwoo Jung <[email protected]>
Reviewed-By: James M Snell <[email protected]>

Author: addaleax

doc/api/fs.md

@@ -488,6 +488,16 @@ argument to `fs.createReadStream()`. If `path` is passed as a string, then
 `readStream.path` will be a string. If `path` is passed as a `Buffer`, then
 `readStream.path` will be a `Buffer`.
 
+### readStream.pending
+<!-- YAML
+added: REPLACEME
+-->
+
+* {boolean}
+
+This property is `true` if the underlying file has not been opened yet,
+i.e. before the `'ready'` event is emitted.
+
 ## Class: fs.Stats
 <!-- YAML
 added: v0.1.21
@@ -833,6 +843,16 @@ argument to [`fs.createWriteStream()`][]. If `path` is passed as a string, then
 `writeStream.path` will be a string. If `path` is passed as a `Buffer`, then
 `writeStream.path` will be a `Buffer`.
 
+### writeStream.pending
+<!-- YAML
+added: REPLACEME
+-->
+
+* {boolean}
+
+This property is `true` if the underlying file has not been opened yet,
+i.e. before the `'ready'` event is emitted.
+
 ## fs.access(path[, mode], callback)
 <!-- YAML
 added: v0.11.15

doc/api/net.md

@@ -724,6 +724,17 @@ The numeric representation of the local port. For example, `80` or `21`.
 Pauses the reading of data. That is, [`'data'`][] events will not be emitted.
 Useful to throttle back an upload.
 
+### socket.pending
+<!-- YAML
+added: REPLACEME
+-->
+
+* {boolean}
+
+This is `true` if the socket is not connected yet, either because `.connect()`
+has not yet been called or because it is still in the process of connecting
+(see [`socket.connecting`][]).
+
 ### socket.ref()
 <!-- YAML
 added: v0.9.1
@@ -1168,6 +1179,7 @@ Returns `true` if input is a version 6 IP address, otherwise returns `false`.
 [`socket.connect(options)`]: #net_socket_connect_options_connectlistener
 [`socket.connect(path)`]: #net_socket_connect_path_connectlistener
 [`socket.connect(port, host)`]: #net_socket_connect_port_host_connectlistener
+[`socket.connecting`]: #net_socket_connecting
 [`socket.destroy()`]: #net_socket_destroy_exception
 [`socket.end()`]: #net_socket_end_data_encoding_callback
 [`socket.pause()`]: #net_socket_pause

lib/internal/fs/streams.js

@@ -212,6 +212,11 @@ ReadStream.prototype.close = function(cb) {
   this.destroy(null, cb);
 };
 
+Object.defineProperty(ReadStream.prototype, 'pending', {
+  get() { return this.fd === null; },
+  configurable: true
+});
+
 function WriteStream(path, options) {
   if (!(this instanceof WriteStream))
     return new WriteStream(path, options);
@@ -378,6 +383,11 @@ WriteStream.prototype.close = function(cb) {
 // There is no shutdown() for files.
 WriteStream.prototype.destroySoon = WriteStream.prototype.end;
 
+Object.defineProperty(WriteStream.prototype, 'pending', {
+  get() { return this.fd === null; },
+  configurable: true
+});
+
 module.exports = {
   ReadStream,
   WriteStream

lib/internal/http2/core.js

@@ -1824,7 +1824,7 @@ class Http2Stream extends Duplex {
 
   _final(cb) {
     const handle = this[kHandle];
-    if (this[kID] === undefined) {
+    if (this.pending) {
       this.once('ready', () => this._final(cb));
     } else if (handle !== undefined) {
       debug(`Http2Stream ${this[kID]} [Http2Session ` +

lib/net.js

@@ -341,7 +341,7 @@ Socket.prototype._unrefTimer = function _unrefTimer() {
 // sent out to the other side.
 Socket.prototype._final = function(cb) {
   // If still connecting - defer handling `_final` until 'connect' will happen
-  if (this.connecting) {
+  if (this.pending) {
     debug('_final: not yet connected');
     return this.once('connect', () => this._final(cb));
   }
@@ -480,6 +480,13 @@ Object.defineProperty(Socket.prototype, '_connecting', {
   }
 });
 
+Object.defineProperty(Socket.prototype, 'pending', {
+  get() {
+    return !this._handle || this.connecting;
+  },
+  configurable: true
+});
+
 
 Object.defineProperty(Socket.prototype, 'readyState', {
   get: function() {

test/parallel/test-fs-ready-event-stream.js

@@ -1,13 +1,20 @@
 'use strict';
 const common = require('../common');
+const assert = require('assert');
 const fs = require('fs');
 const path = require('path');
 const tmpdir = require('../common/tmpdir');
 
 const readStream = fs.createReadStream(__filename);
-readStream.on('ready', common.mustCall(() => {}, 1));
+assert.strictEqual(readStream.pending, true);
+readStream.on('ready', common.mustCall(() => {
+  assert.strictEqual(readStream.pending, false);
+}));
 
 const writeFile = path.join(tmpdir.path, 'write-fsreadyevent.txt');
 tmpdir.refresh();
 const writeStream = fs.createWriteStream(writeFile, { autoClose: true });
-writeStream.on('ready', common.mustCall(() => {}, 1));
+assert.strictEqual(writeStream.pending, true);
+writeStream.on('ready', common.mustCall(() => {
+  assert.strictEqual(writeStream.pending, false);
+}));

test/parallel/test-net-connect-buffer.js

@@ -44,8 +44,10 @@ tcp.listen(0, common.mustCall(function() {
   const socket = net.Stream({ highWaterMark: 0 });
 
   let connected = false;
+  assert.strictEqual(socket.pending, true);
   socket.connect(this.address().port, common.mustCall(() => connected = true));
 
+  assert.strictEqual(socket.pending, true);
   assert.strictEqual(socket.connecting, true);
   assert.strictEqual(socket.readyState, 'opening');
 
@@ -87,6 +89,10 @@ tcp.listen(0, common.mustCall(function() {
     console.error('write cb');
     assert.ok(connected);
     assert.strictEqual(socket.bytesWritten, Buffer.from(a + b).length);
+    assert.strictEqual(socket.pending, false);
+  }));
+  socket.on('close', common.mustCall(() => {
+    assert.strictEqual(socket.pending, true);
   }));
 
   assert.strictEqual(socket.bytesWritten, Buffer.from(a).length);