fileHandle.read argument defaults don’t seem to work

[lydell]

• Version: v16.1.0
• Platform: Darwin 20.5.0 x86_64
• Subsystem: fs/promises

What steps will reproduce the bug?

const fs = require("fs");
const fsPromises = require("fs/promises");

async function run() {
  const fileHandle = await fsPromises.open(__filename);
  const buffer = Buffer.alloc(16);

  // Logs `{ bytesRead: 0, buffer: ... }`:
  console.log(await fileHandle.read(buffer));

  // Logs `{ bytesRead: 16, buffer: ... }`:
  console.log(await fileHandle.read(buffer, 0, buffer.byteLength));

  // According to the docs, the first call should read 16 bytes too, because
  // the parameters left out default to the values in the second call.
  // `fs.readSync` works that way:

  // Logs `16`.
  console.log(fs.readSync(fs.openSync(__filename), buffer));
}

run().catch(console.error);

Save the above as test.cjs and run node test.cjs.

How often does it reproduce? Is there a required condition?

Always.

What is the expected behavior?

https://nodejs.org/api/fs.html#fs_filehandle_read_buffer_offset_length_position

filehandle.read(buffer, offset, length, position)

• buffer <Buffer> | <TypedArray> | <DataView> A buffer that will be filled with the file data read.
• offset <integer> The location in the buffer at which to start filling. Default: 0
• length <integer> The number of bytes to read. Default: buffer.byteLength
• position <integer> The location where to begin reading data from the file. If null, data will be read from the current file position, and the position will be updated. If position is an integer, the current file position will remain unchanged.

Calling fileHandle.read(buffer) should work like fileHandle.read(buffer, 0, buffer.byteLength).

What do you see instead?

0 bytes are read.

Additional information

fs.readSync has similar documentation and works as expected.

Potential problems:

• I’m misunderstanding the docs.
• The docs are wrong.
• There’s a bug.

[Linkgoron]

This is IMO an issue with the docs. The readSync call works as the overload that's called is actually as if you called the [options] overload, as buffer is not part of the options in readSync.

For fileHandle.read the parameters are not marked as optional, and length actually defaults to 0 when it's not specifically provided. The change to the docs is a relatively recent change, and I believe that it was done by mistake and the defaults accidentally copied from the options overload. The docs for the callback version are wrong as well, in a similar way.

[rbrishabh]

I can help with this!

[Nazeeh21]

I want to work on this issue.

[dasdeo]

Unless I'm missing something here, the docs still show the wrong description: