Omission in the fs doc

[vsemozhetbyt]

• Version: 6.2.0
• Platform: Windows 7
• Subsystem: doc, fs

Sometimes I use the same file descriptor for writing and then reading by readline (possible case: write some data line by line, then reread it into an array to sort and rewrite).

It seems fs doc lacks for some point concerning these cases.

fs.createReadStream(path[, options]):

options can include start and end values to read a range of bytes from the file instead of the entire file. Both start and end are inclusive and start at 0.

Maybe it should be mentioned that start is set by default to the file end (or to the write position) for fd that has been previously written into.

Test:

const fs = require('fs');
const rl = require('readline');

const file = fs.openSync('test.txt', 'w+');

fs.writeSync(file, '1\n2\n3\n');

rl.createInterface({
  input: fs.createReadStream(null, {fd: file})
}).on('line', line => {
  console.log(line);
}).on('close', () => {
  console.log('Closed');
});

The output is only

Closed

const fs = require('fs');
const rl = require('readline');

const file = fs.openSync('test.txt', 'w+');

fs.writeSync(file, '1\n2\n3\n');

rl.createInterface({
  input: fs.createReadStream(null, {fd: file, start: 0})
}).on('line', line => {
  console.log(line);
}).on('close', () => {
  console.log('Closed');
});

The output contains all the file:

1
2
3
Closed

[vsemozhetbyt]

Is arm label added by mistake?

[bnoordhuis]

Both start and end are inclusive and start at 0.

I think that should be understood as, when set, they start counting from zero, not one.

Maybe it should be mentioned that start is set by default to the file end (or to the write position) for fd that has been previously written into.

I agree. @nodejs/documentation: when fd is specified and start is omitted or undefined, fs.createReadStream() reads sequentially from the current file position. start corresponds to the position argument to fs.read(), which is documented to behave that way.

Mixing sequential reads and writes with concurrent asynchronous file operations is usually unwise because there is no telling in which order they run. Not an issue in the OP's example but replacing fs.writeSync() with fs.write(), for example, would introduce randomness.

[WesTyler]

@bnoordhuis / @nodejs/documentation: before I commit/PR, can I get feedback on wording updates? How's this?

Updated wording below:

options can include start and end values to read a range of bytes from
the file instead of the entire file. Both start and end are inclusive and
start counting at 0. If fd is specified and start is omitted or undefined,
fs.createReadStream() reads sequentially from the current file position.
The encoding can be any one of those accepted by [Buffer][].

[bnoordhuis]

@WesTyler Sounds good to me.