fs: add read(buffer[, options]) versions

This adds the following: - `fs.read(fd, buffer[, options], callback)`. - `filehandle.read(buffer[, options])`. PR-URL: #42768 Refs: #42601 Reviewed-By: Antoine du Hamel <[email protected]>

Author: LiviaMedeiros

doc/api/fs.md

@@ -417,6 +417,33 @@ Reads data from the file and stores that in the given buffer.
 If the file is not modified concurrently, the end-of-file is reached when the
 number of bytes read is zero.
 
+#### `filehandle.read(buffer[, options])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `buffer`{Buffer|TypedArray|DataView} A buffer that will be filled with the
+ file data read.
+* `options`{Object}
+ * `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- offset`
+ * `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. **Default:**: `null`
+* Returns:{Promise} Fulfills upon success with an object with two properties:
+ * `bytesRead`{integer} The number of bytes read
+ * `buffer`{Buffer|TypedArray|DataView} A reference to the passed in `buffer`
+ argument.
+
+Reads data from the file and stores that in the given buffer.
+
+If the file is not modified concurrently, the end-of-file is reached when the
+number of bytes read is zero.
+
 #### `filehandle.readableWebStream()`
 
 <!-- YAML
@@ -3243,6 +3270,28 @@ Similar to the [`fs.read()`][] function, this version takes an optional
 `options` object. If no `options` object is specified, it will default with the
 above values.
 
+### `fs.read(fd, buffer[, options], callback)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `fd`{integer}
+* `buffer`{Buffer|TypedArray|DataView} The buffer that the data will be
+ written to.
+* `options`{Object}
+ * `offset`{integer} **Default:** `0`
+ * `length`{integer} **Default:** `buffer.byteLength- offset`
+ * `position`{integer|bigint} **Default:** `null`
+* `callback`{Function}
+ * `err`{Error}
+ * `bytesRead`{integer}
+ * `buffer`{Buffer}
+
+Similar to the [`fs.read()`][] function, this version takes an optional
+`options` object. If no `options` object is specified, it will default with the
+above values.
+
 ### `fs.readdir(path[, options], callback)`
 
 <!-- YAML

lib/fs.js

@@ -136,6 +136,7 @@ const{
  validateEncoding,
  validateFunction,
  validateInteger,
+ validateObject,
  validateString,
 }=require('internal/validators');
 
@@ -595,7 +596,7 @@ function openSync(path, flags, mode){
  * Reads file from the specified `fd` (file descriptor).
  * @param{number} fd
  * @param{Buffer | TypedArray | DataView} buffer
- * @param{number} offset
+ * @param{number} offsetOrOptions
  * @param{number} length
  * @param{number | bigint | null} position
  * @param{(
@@ -605,30 +606,36 @@ function openSync(path, flags, mode){
  * ) => any} callback
  * @returns{void}
  */
-functionread(fd,buffer,offset,length,position,callback){
+functionread(fd,buffer,offsetOrOptions,length,position,callback){
 fd=getValidatedFd(fd);
 
-if(arguments.length<=3){
-// Assume fs.read(fd, options, callback)
-letoptions=ObjectCreate(null);
-if(arguments.length<3){
+letoffset=offsetOrOptions;
+letparams=null;
+if(arguments.length<=4){
+if(arguments.length===4){
+// This is fs.read(fd, buffer, options, callback)
+validateObject(offsetOrOptions,'options',{nullable: true});
+callback=length;
+params=offsetOrOptions;
+}elseif(arguments.length===3){
+// This is fs.read(fd, bufferOrParams, callback)
+if(!isArrayBufferView(buffer)){
+// This is fs.read(fd, params, callback)
+params=buffer;
+({ buffer =Buffer.alloc(16384)}=params??ObjectCreate(null));
+}
+callback=offsetOrOptions;
+}else{
 // This is fs.read(fd, callback)
-// buffer will be the callback
 callback=buffer;
-}else{
-// This is fs.read(fd,{}, callback)
-// buffer will be the options object
-// offset is the callback
-options=buffer;
-callback=offset;
+buffer=Buffer.alloc(16384);
 }
 
 ({
- buffer =Buffer.alloc(16384),
  offset =0,
  length =buffer.byteLength-offset,
  position =null
-}=options);
+}=params??ObjectCreate(null));
 }
 
 validateBuffer(buffer);

lib/internal/fs/promises.js

@@ -508,20 +508,29 @@ async function open(path, flags, mode){
 flagsNumber,mode,kUsePromises));
 }
 
-asyncfunctionread(handle,bufferOrOptions,offset,length,position){
-letbuffer=bufferOrOptions;
+asyncfunctionread(handle,bufferOrParams,offset,length,position){
+letbuffer=bufferOrParams;
 if(!isArrayBufferView(buffer)){
-bufferOrOptions??=ObjectCreate(null);
+// This is fh.read(params)
 ({
  buffer =Buffer.alloc(16384),
  offset =0,
  length =buffer.byteLength-offset,
  position =null
-}=bufferOrOptions);
+}=bufferOrParams??ObjectCreate(null));
 
 validateBuffer(buffer);
 }
 
+if(offset!==null&&typeofoffset==='object'){
+// This is fh.read(buffer, options)
+({
+ offset =0,
+ length =buffer.byteLength-offset,
+ position =null
+}=offset??ObjectCreate(null));
+}
+
 if(offset==null){
 offset=0;
 }else{

test/parallel/test-fs-read-offset-null.js

@@ -14,29 +14,51 @@ const filepath = fixtures.path('x.txt');
 constbuf=Buffer.alloc(1);
 // Reading only one character, hence buffer of one byte is enough.
 
-// Test for callback API.
+// Tests are done by making sure the first letter in buffer is
+// same as first letter in file.
+// 120 is the ascii code of letter x.
+
+// Tests for callback API.
 fs.open(filepath,'r',common.mustSucceed((fd)=>{
 fs.read(fd,{offset: null,buffer: buf},
 common.mustSucceed((bytesRead,buffer)=>{
-// Test is done by making sure the first letter in buffer is
-// same as first letter in file.
-// 120 is the hex for ascii code of letter x.
+assert.strictEqual(buffer[0],120);
+fs.close(fd,common.mustSucceed(()=>{}));
+}));
+}));
+
+fs.open(filepath,'r',common.mustSucceed((fd)=>{
+fs.read(fd,buf,{offset: null},
+common.mustSucceed((bytesRead,buffer)=>{
 assert.strictEqual(buffer[0],120);
 fs.close(fd,common.mustSucceed(()=>{}));
 }));
 }));
 
 letfilehandle=null;
 
-// Test for promise api
+// Tests for promises api
+(async()=>{
+filehandle=awaitfsPromises.open(filepath,'r');
+constreadObject=awaitfilehandle.read(buf,{offset: null});
+assert.strictEqual(readObject.buffer[0],120);
+})()
+.finally(()=>filehandle?.close())
+.then(common.mustCall());
+
+// Undocumented: omitted position works the same as position === null
 (async()=>{
 filehandle=awaitfsPromises.open(filepath,'r');
 constreadObject=awaitfilehandle.read(buf,null,buf.length);
 assert.strictEqual(readObject.buffer[0],120);
 })()
-.then(common.mustCall())
-.finally(async()=>{
-// Close the file handle if it is opened
-if(filehandle)
-awaitfilehandle.close();
-});
+.finally(()=>filehandle?.close())
+.then(common.mustCall());
+
+(async()=>{
+filehandle=awaitfsPromises.open(filepath,'r');
+constreadObject=awaitfilehandle.read(buf,null,buf.length,0);
+assert.strictEqual(readObject.buffer[0],120);
+})()
+.finally(()=>filehandle?.close())
+.then(common.mustCall());

test/parallel/test-fs-read-optional-params.js

@@ -5,32 +5,34 @@ const fixtures = require('../common/fixtures');
 constfs=require('fs');
 constassert=require('assert');
 constfilepath=fixtures.path('x.txt');
-constfd=fs.openSync(filepath,'r');
 
 constexpected=Buffer.from('xyz\n');
 constdefaultBufferAsync=Buffer.alloc(16384);
-constbufferAsOption=Buffer.allocUnsafe(expected.length);
+constbufferAsOption=Buffer.allocUnsafe(expected.byteLength);
 
-// Test not passing in any options object
-fs.read(fd,common.mustCall((err,bytesRead,buffer)=>{
-assert.strictEqual(bytesRead,expected.length);
-assert.deepStrictEqual(defaultBufferAsync.length,buffer.length);
-}));
+functiontestValid(message, ...options){
+constparamsMsg=`${message} (as params)`;
+constparamsFilehandle=fs.openSync(filepath,'r');
+fs.read(paramsFilehandle, ...options,common.mustSucceed((bytesRead,buffer)=>{
+assert.strictEqual(bytesRead,expected.byteLength,paramsMsg);
+assert.deepStrictEqual(defaultBufferAsync.byteLength,buffer.byteLength,paramsMsg);
+fs.closeSync(paramsFilehandle);
+}));
 
-// Test passing in an empty options object
-fs.read(fd,{position: 0},common.mustCall((err,bytesRead,buffer)=>{
-assert.strictEqual(bytesRead,expected.length);
-assert.deepStrictEqual(defaultBufferAsync.length,buffer.length);
-}));
+constoptionsMsg=`${message} (as options)`;
+constoptionsFilehandle=fs.openSync(filepath,'r');
+fs.read(optionsFilehandle,bufferAsOption, ...options,common.mustSucceed((bytesRead,buffer)=>{
+assert.strictEqual(bytesRead,expected.byteLength,optionsMsg);
+assert.deepStrictEqual(bufferAsOption.byteLength,buffer.byteLength,optionsMsg);
+fs.closeSync(optionsFilehandle);
+}));
+}
 
-// Test passing in options
-fs.read(fd,{
-buffer: bufferAsOption,
+testValid('Not passing in any object');
+testValid('Passing in a null',null);
+testValid('Passing in an empty object',{});
+testValid('Passing in an object',{
 offset: 0,
-length: bufferAsOption.length,
-position: 0
-},
-common.mustCall((err,bytesRead,buffer)=>{
-assert.strictEqual(bytesRead,expected.length);
-assert.deepStrictEqual(bufferAsOption.length,buffer.length);
-}));
+length: bufferAsOption.byteLength,
+position: 0,
+});

test/parallel/test-fs-read-promises-optional-params.js

@@ -10,10 +10,18 @@ const fd = fs.openSync(filepath, 'r');
 
 constexpected=Buffer.from('xyz\n');
 constdefaultBufferAsync=Buffer.alloc(16384);
+constbufferAsOption=Buffer.allocUnsafe(expected.byteLength);
 
 read(fd,{})
 .then(function({ bytesRead, buffer }){
-assert.strictEqual(bytesRead,expected.length);
-assert.deepStrictEqual(defaultBufferAsync.length,buffer.length);
+assert.strictEqual(bytesRead,expected.byteLength);
+assert.deepStrictEqual(defaultBufferAsync.byteLength,buffer.byteLength);
+})
+.then(common.mustCall());
+
+read(fd,bufferAsOption,{position: 0})
+.then(function({ bytesRead, buffer }){
+assert.strictEqual(bytesRead,expected.byteLength);
+assert.deepStrictEqual(bufferAsOption.byteLength,buffer.byteLength);
 })
 .then(common.mustCall());