fs: add writev() promises version

doc/api/fs.md

@@ -4274,6 +4274,32 @@ If one or more `filehandle.write()` calls are made on a file handle and then a
 current position till the end of the file. It doesn't always write from the
 beginning of the file.
 
+#### filehandle.writev(buffers[, position])
+<!-- YAML
+added: REPLACEME
+-->
+
+* `buffers` {ArrayBufferView[]}
+* `position` {integer}
+* Returns: {Promise}
+
+Write an array of `ArrayBufferView`s to the file.
+
+The `Promise` is resolved with an object containing a `bytesWritten` property
+identifying the number of bytes written, and a `buffers` property containing
+a reference to the `buffers` input.
+
+`position` is the offset from the beginning of the file where this data
+should be written. If `typeof position !== 'number'`, the data will be written
+at the current position.
+
+It is unsafe to call `writev()` multiple times on the same file without waiting
+for the previous operation to complete.
+
+On Linux, positional writes don't work when the file is opened in append mode.
+The kernel ignores the position argument and always appends the data to
+the end of the file.
+
 ### fsPromises.access(path[, mode])
 <!-- YAML
 added: v10.0.0

lib/fs.js

@@ -72,6 +72,7 @@ const {
  stringToFlags,
  stringToSymlinkType,
  toUnixTimestamp,
+ validateBufferArray,
  validateOffsetLengthRead,
  validateOffsetLengthWrite,
  validatePath,
@@ -142,19 +143,6 @@ function maybeCallback(cb) {
  throw new ERR_INVALID_CALLBACK(cb);
 }
 
-function isBuffersArray(value) {
- if (!Array.isArray(value))
- return false;
-
- for (var i = 0; i < value.length; i += 1) {
- if (!isArrayBufferView(value[i])) {
- return false;
- }
- }
-
- return true;
-}
-
 // Ensure that callbacks run in the global context. Only use this function
 // for callbacks that are passed to the binding layer, callbacks that are
 // invoked from JS already run in the proper scope.
@@ -626,10 +614,7 @@ function writev(fd, buffers, position, callback) {
  }
 
  validateInt32(fd, 'fd', 0);
-
- if (!isBuffersArray(buffers)) {
- throw new ERR_INVALID_ARG_TYPE('buffers', 'ArrayBufferView[]', buffers);
- }
+ validateBufferArray(buffers);
 
  const req = new FSReqCallback();
  req.oncomplete = wrapper;
@@ -647,15 +632,11 @@ Object.defineProperty(writev, internalUtil.customPromisifyArgs, {
  enumerable: false
 });
 
-// fs.writevSync(fd, buffers[, position]);
 function writevSync(fd, buffers, position) {
-
  validateInt32(fd, 'fd', 0);
- const ctx = {};
+ validateBufferArray(buffers);
 
- if (!isBuffersArray(buffers)) {
- throw new ERR_INVALID_ARG_TYPE('buffers', 'ArrayBufferView[]', buffers);
- }
+ const ctx = {};
 
  if (typeof position !== 'number')
  position = null;

lib/internal/fs/promises.js

@@ -29,6 +29,7 @@ const {
  stringToFlags,
  stringToSymlinkType,
  toUnixTimestamp,
+ validateBufferArray,
  validateOffsetLengthRead,
  validateOffsetLengthWrite,
  warnOnNonPortableTemplate
@@ -104,6 +105,10 @@ class FileHandle {
  return write(this, buffer, offset, length, position);
  }
 
+ writev(buffers, position) {
+ return writev(this, buffers, position);
+ }
+
  writeFile(data, options) {
  return writeFile(this, data, options);
  }
@@ -263,6 +268,18 @@ async function write(handle, buffer, offset, length, position) {
  return { bytesWritten, buffer };
 }
 
+async function writev(handle, buffers, position) {
+ validateFileHandle(handle);
+ validateBufferArray(buffers);
+
+ if (typeof position !== 'number')
+ position = null;
+
+ const bytesWritten = (await binding.writeBuffers(handle.fd, buffers, position,
+ kUsePromises)) || 0;
+ return { bytesWritten, buffers };
+}
+
 async function rename(oldPath, newPath) {
  oldPath = getValidatedPath(oldPath, 'oldPath');
  newPath = getValidatedPath(newPath, 'newPath');

lib/internal/fs/utils.js

@@ -15,6 +15,7 @@ const {
  hideStackFrames
 } = require('internal/errors');
 const {
+ isArrayBufferView,
  isUint8Array,
  isDate,
  isBigUint64Array
@@ -500,6 +501,18 @@ const getValidatedPath = hideStackFrames((fileURLOrPath, propName = 'path') => {
  return path;
 });
 
+const validateBufferArray = hideStackFrames((buffers, propName = 'buffers') => {
+ if (!Array.isArray(buffers))
+ throw new ERR_INVALID_ARG_TYPE(propName, 'ArrayBufferView[]', buffers);
+
+ for (let i = 0; i < buffers.length; i++) {
+ if (!isArrayBufferView(buffers[i]))
+ throw new ERR_INVALID_ARG_TYPE(propName, 'ArrayBufferView[]', buffers);
+ }
+
+ return buffers;
+});
+
 let nonPortableTemplateWarn = true;
 
 function warnOnNonPortableTemplate(template) {
@@ -528,6 +541,7 @@ module.exports = {
  stringToSymlinkType,
  Stats,
  toUnixTimestamp,
+ validateBufferArray,
  validateOffsetLengthRead,
  validateOffsetLengthWrite,
  validatePath,

test/parallel/test-fs-writev-promises.js

@@ -0,0 +1,51 @@
+'use strict';
+
+require('../common');
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs').promises;
+const tmpdir = require('../common/tmpdir');
+const expected = 'ümlaut. Лорем 運務ホソモ指及 आपको करने विकास 紙読決多密所 أضف';
+let cnt = 0;
+
+function getFileName() {
+ return path.join(tmpdir.path, `writev_promises_${++cnt}.txt`);
+}
+
+tmpdir.refresh();
+
+(async () => {
+ {
+ const filename = getFileName();
+ const handle = await fs.open(filename, 'w');
+ const buffer = Buffer.from(expected);
+ const bufferArr = [buffer, buffer];
+ const expectedLength = bufferArr.length * buffer.byteLength;
+ let { bytesWritten, buffers } = await handle.writev([Buffer.from('')],
+ null);
+ assert.deepStrictEqual(bytesWritten, 0);
+ assert.deepStrictEqual(buffers, [Buffer.from('')]);
+ ({ bytesWritten, buffers } = await handle.writev(bufferArr, null));
+ assert.deepStrictEqual(bytesWritten, expectedLength);
+ assert.deepStrictEqual(buffers, bufferArr);
+ assert(Buffer.concat(bufferArr).equals(await fs.readFile(filename)));
+ handle.close();
+ }
+
+ // fs.promises.writev() with an array of buffers without position.
+ {
+ const filename = getFileName();
+ const handle = await fs.open(filename, 'w');
+ const buffer = Buffer.from(expected);
+ const bufferArr = [buffer, buffer, buffer];
+ const expectedLength = bufferArr.length * buffer.byteLength;
+ let { bytesWritten, buffers } = await handle.writev([Buffer.from('')]);
+ assert.deepStrictEqual(bytesWritten, 0);
+ assert.deepStrictEqual(buffers, [Buffer.from('')]);
+ ({ bytesWritten, buffers } = await handle.writev(bufferArr));
+ assert.deepStrictEqual(bytesWritten, expectedLength);
+ assert.deepStrictEqual(buffers, bufferArr);
+ assert(Buffer.concat(bufferArr).equals(await fs.readFile(filename)));
+ handle.close();
+ }
+})();