diff --git a/doc/api/fs.md b/doc/api/fs.md index fbc6ca03046f88..597f4f16f5fa92 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -4212,6 +4212,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 diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js index 42dbbcc361ad99..171fec6e65a99c 100644 --- a/lib/internal/fs/promises.js +++ b/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); } @@ -255,6 +260,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'); diff --git a/lib/internal/fs/utils.js b/lib/internal/fs/utils.js index 3a12b1b281ce80..81b5cfaa30a50c 100644 --- a/lib/internal/fs/utils.js +++ b/lib/internal/fs/utils.js @@ -15,6 +15,7 @@ const { hideStackFrames } = require('internal/errors'); const { + isArrayBufferView, isUint8Array, isDate } = require('internal/util/types'); @@ -439,6 +440,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) { @@ -466,6 +479,7 @@ module.exports = { stringToSymlinkType, Stats, toUnixTimestamp, + validateBufferArray, validateOffsetLengthRead, validateOffsetLengthWrite, validatePath, diff --git a/test/parallel/test-fs-writev-promises.js b/test/parallel/test-fs-writev-promises.js new file mode 100644 index 00000000000000..ea349796cc6158 --- /dev/null +++ b/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(); + } +})();