[pull] main from nodejs:main

doc/api/fs.md

@@ -196,7 +196,7 @@
                  strings anymore.
 -->
 
-* `data` {string|Buffer|TypedArray|DataView|AsyncIterable|Iterable|Stream}
+* `data` {string|Buffer|TypedArray|DataView|AsyncIterable|Iterable}
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `signal` {AbortSignal|undefined} allows aborting an in-progress writeFile. **Default:** `undefined`
@@ -1007,7 +1007,7 @@
                  strings anymore.
 -->
 
-* `data` {string|Buffer|TypedArray|DataView|AsyncIterable|Iterable|Stream}
+* `data` {string|Buffer|TypedArray|DataView|AsyncIterable|Iterable}
 * `options` {Object|string}
   * `encoding` {string|null} The expected character encoding when `data` is a
     string. **Default:** `'utf8'`
@@ -1238,10 +1238,15 @@
     - v20.10.0
     pr-url: https://github.com/nodejs/node/pull/50095
     description: The `flush` option is now supported.
+  - version:
+      - v15.14.0
+      - v14.18.0
+    pr-url: https://github.com/nodejs/node/pull/37490
+    description: The `data` argument supports `AsyncIterable`, `Iterable`, and `Stream`.
 -->
 
 * `path` {string|Buffer|URL|FileHandle} filename or {FileHandle}
-* `data` {string|Buffer}
+* `data` {string|Buffer|TypedArray|DataView|AsyncIterable|Iterable}
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`
@@ -1251,7 +1256,7 @@
 * Returns: {Promise} Fulfills with `undefined` upon success.
 
 Asynchronously append data to a file, creating the file if it does not yet
-exist. `data` can be a string or a {Buffer}.
+`data` can be a string, a buffer, an {AsyncIterable}, or an {Iterable} object.
 
 If `options` is a string, then it specifies the `encoding`.
 
@@ -2265,7 +2270,7 @@
 -->
 
 * `file` {string|Buffer|URL|FileHandle} filename or `FileHandle`
-* `data` {string|Buffer|TypedArray|DataView|AsyncIterable|Iterable|Stream}
+* `data` {string|Buffer|TypedArray|DataView|AsyncIterable|Iterable}
 * `options` {Object|string}
   * `encoding` {string|null} **Default:** `'utf8'`
   * `mode` {integer} **Default:** `0o666`

doc/api/tls.md

@@ -2321,7 +2321,7 @@ The certificates will be deduplicated before being set as the default.
 
 This function only affects the current Node.js thread. Previous
 sessions cached by the HTTPS agent won't be affected by this change, so
-this method should be called before any unwanted cachable TLS connections are
+this method should be called before any unwanted cacheable TLS connections are
 made.
 
 To use system CA certificates as the default:

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

@@ -0,0 +1,191 @@
+'use strict';
+
+const common = require('../common');
+const fs = require('fs');
+const fsPromises = fs.promises;
+const path = require('path');
+const tmpdir = require('../common/tmpdir');
+const assert = require('assert');
+const tmpDir = tmpdir.path;
+const { Readable } = require('stream');
+
+tmpdir.refresh();
+
+const buffer = Buffer.from('abc'.repeat(1000));
+const stream = Readable.from(['a', 'b', 'c']);
+const stream2 = Readable.from(['ümlaut', ' ', 'sechzig']);
+const iterable = {
+  expected: 'abc',
+  *[Symbol.iterator]() {
+    yield 'a';
+    yield 'b';
+    yield 'c';
+  }
+};
+
+const veryLargeIterable = {
+  expected: 'dogs running'.repeat(512 * 1024),
+  *[Symbol.iterator]() {
+    yield Buffer.from('dogs running'.repeat(512 * 1024), 'utf8');
+  }
+};
+
+function iterableWith(value) {
+  return {
+    *[Symbol.iterator]() {
+      yield value;
+    }
+  };
+}
+const bufferIterable = {
+  expected: 'abc',
+  *[Symbol.iterator]() {
+    yield Buffer.from('a');
+    yield Buffer.from('b');
+    yield Buffer.from('c');
+  }
+};
+const asyncIterable = {
+  expected: 'abc',
+  async* [Symbol.asyncIterator]() {
+    yield 'a';
+    yield 'b';
+    yield 'c';
+  }
+};
+
+let counter = 0;
+
+async function doAppendString() {
+  const string = 'x~yz'.repeat(100);
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await fsPromises.appendFile(dest, string);
+  const data = fs.readFileSync(dest);
+  const stringAsBuffer = Buffer.from(string, 'utf8');
+  assert.deepStrictEqual(stringAsBuffer, data);
+}
+
+async function doAppendBuffer() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await fsPromises.appendFile(dest, buffer);
+  const data = fs.readFileSync(dest);
+  assert.deepStrictEqual(data, buffer);
+}
+
+async function doAppendStream() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await fsPromises.appendFile(dest, stream);
+  const expected = 'abc';
+  const data = fs.readFileSync(dest, 'utf-8');
+  assert.deepStrictEqual(data, expected);
+}
+
+async function doAppendStreamWithCancel() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  const controller = new AbortController();
+  const { signal } = controller;
+  process.nextTick(() => controller.abort());
+  await assert.rejects(
+    fsPromises.appendFile(dest, stream, { signal }),
+    { name: 'AbortError' }
+  );
+}
+
+async function doAppendIterable() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await fsPromises.appendFile(dest, iterable);
+  const data = fs.readFileSync(dest, 'utf-8');
+  assert.deepStrictEqual(data, iterable.expected);
+}
+
+async function doAppendInvalidIterable() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await Promise.all(
+    [42, 42n, {}, Symbol('42'), true, undefined, null, NaN].map((value) =>
+      assert.rejects(fsPromises.appendFile(dest, iterableWith(value)), {
+        code: 'ERR_INVALID_ARG_TYPE',
+      })
+    )
+  );
+}
+
+async function doAppendIterableWithEncoding() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await fsPromises.appendFile(dest, stream2, 'latin1');
+  const expected = 'ümlaut sechzig';
+  const data = fs.readFileSync(dest, 'latin1');
+  assert.deepStrictEqual(data, expected);
+}
+
+async function doAppendBufferIterable() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await fsPromises.appendFile(dest, bufferIterable);
+  const data = fs.readFileSync(dest, 'utf-8');
+  assert.deepStrictEqual(data, bufferIterable.expected);
+}
+
+async function doAppendAsyncIterable() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await fsPromises.appendFile(dest, asyncIterable);
+  const data = fs.readFileSync(dest, 'utf-8');
+  assert.deepStrictEqual(data, asyncIterable.expected);
+}
+
+async function doAppendLargeIterable() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await fsPromises.appendFile(dest, veryLargeIterable);
+  const data = fs.readFileSync(dest, 'utf-8');
+  assert.deepStrictEqual(data, veryLargeIterable.expected);
+}
+
+async function doAppendInvalidValues() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  await Promise.all(
+    [42, 42n, {}, Symbol('42'), true, undefined, null, NaN].map((value) =>
+      assert.rejects(fsPromises.appendFile(dest, value), {
+        code: 'ERR_INVALID_ARG_TYPE',
+      })
+    )
+  );
+}
+
+async function doAppendBufferAndCancel() {
+  const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+  const controller = new AbortController();
+  const { signal } = controller;
+  process.nextTick(() => controller.abort());
+  await assert.rejects(
+    fsPromises.appendFile(dest, buffer, { signal }),
+    { name: 'AbortError' }
+  );
+}
+
+async function doAppendTypedArrays() {
+  for (const Constructor of [Uint8Array, Uint16Array, Uint32Array]) {
+    const dest = path.resolve(tmpDir, `tmp-${counter++}.txt`);
+
+    // Use a file size larger than `kReadFileMaxChunkSize`.
+    const buffer = Buffer.from('012'.repeat(2 ** 14));
+
+    const array = new Constructor(buffer.buffer);
+    await fsPromises.appendFile(dest, array);
+    const data = await fsPromises.readFile(dest);
+    assert.deepStrictEqual(data, buffer);
+  }
+}
+
+(async () => {
+  await doAppendBuffer();
+  await doAppendBufferAndCancel();
+  await doAppendString();
+  await doAppendStream();
+  await doAppendStreamWithCancel();
+  await doAppendIterable();
+  await doAppendInvalidIterable();
+  await doAppendIterableWithEncoding();
+  await doAppendBufferIterable();
+  await doAppendAsyncIterable();
+  await doAppendLargeIterable();
+  await doAppendInvalidValues();
+  await doAppendTypedArrays();
+})().then(common.mustCall());