From 8a253973765606fc9835ff871372d1ecf2b02695 Mon Sep 17 00:00:00 2001
From: Moshe Atlow <moshe@atlow.co.il>
Date: Thu, 22 Jun 2023 12:04:01 +0300
Subject: [PATCH 01/10] fs, stream: initial `Symbol.dispose` and
 `Symbol.asyncDispose` support

Co-authored-by: Benjamin Gruenbaum <benjamingr@gmail.com>
---
 doc/api/fs.md                                 |  8 +++++++
 doc/api/stream.md                             |  8 +++++++
 lib/internal/fs/promises.js                   |  5 ++++
 lib/internal/per_context/primordials.js       |  5 ++++
 lib/internal/process/pre_execution.js         | 11 +++++++++
 lib/internal/streams/readable.js              |  8 +++++++
 .../test-fs-promises-file-handle-dispose.js   | 12 ++++++++++
 test/parallel/test-stream-readable-dispose.js | 23 +++++++++++++++++++
 typings/primordials.d.ts                      |  2 ++
 9 files changed, 82 insertions(+)
 create mode 100644 test/parallel/test-fs-promises-file-handle-dispose.js
 create mode 100644 test/parallel/test-stream-readable-dispose.js

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 01abd668c499b0..5ddc2a5b2d0977 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -817,6 +817,14 @@ 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.
 
+#### `filehandle[Symbol.asyncDispose]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+An alias for `filehandle.close()`.
+
 ### `fsPromises.access(path[, mode])`
 
 <!-- YAML
diff --git a/doc/api/stream.md b/doc/api/stream.md
index 46cbf7965aebc1..22d0178389ffe0 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -1904,6 +1904,14 @@ option. In the code example above, data will be in a single chunk if the file
 has less then 64 KiB of data because no `highWaterMark` option is provided to
 [`fs.createReadStream()`][].
 
+##### `readable[Symbol.asyncDispose]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+An alias for [`readable.destroy()`][readable-destroy] with an `AbortError`.
+
 ##### `readable.compose(stream[, options])`
 
 <!-- YAML
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index caea9592e14fd7..1a5618b6955bb8 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -14,6 +14,7 @@ const {
   SafeArrayIterator,
   SafePromisePrototypeFinally,
   Symbol,
+  SymbolAsyncDispose,
   Uint8Array,
   FunctionPrototypeBind,
 } = primordials;
@@ -246,6 +247,10 @@ class FileHandle extends EventEmitterMixin(JSTransferable) {
     return this[kClosePromise];
   };
 
+  async [SymbolAsyncDispose]() {
+    return this.close();
+  }
+
   /**
    * @typedef {import('../webstreams/readablestream').ReadableStream
    * } ReadableStream
diff --git a/lib/internal/per_context/primordials.js b/lib/internal/per_context/primordials.js
index cd23e8aa804989..fcc1dba394910d 100644
--- a/lib/internal/per_context/primordials.js
+++ b/lib/internal/per_context/primordials.js
@@ -228,6 +228,11 @@ function copyPrototype(src, dest, prefix) {
   copyPrototype(original.prototype, primordials, `${name}Prototype`);
 });
 
+// Define Symbol.Disposed and Symbol.AsyncDispose
+// Until these are defined by the environment.
+primordials.SymbolDispose ??= primordials.SymbolFor('nodejs.dispose');
+primordials.SymbolAsyncDispose ??= primordials.SymbolFor('nodejs.asyncDispose');
+
 // Create copies of intrinsic objects that require a valid `this` to call
 // static methods.
 // Refs: https://www.ecma-international.org/ecma-262/#sec-promise.all
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index 678bd05164f99a..3b201ac2930e5a 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -8,6 +8,9 @@ const {
   ObjectGetOwnPropertyDescriptor,
   SafeMap,
   StringPrototypeStartsWith,
+  Symbol,
+  SymbolDispose,
+  SymbolAsyncDispose,
   globalThis,
 } = primordials;
 
@@ -82,6 +85,8 @@ function prepareExecution(options) {
 
   require('internal/dns/utils').initializeDns();
 
+  setupSymbolDisposePolyfill();
+
   if (isMainThread) {
     assert(internalBinding('worker').isMainThread);
     // Worker threads will get the manifest in the message handler.
@@ -119,6 +124,12 @@ function prepareExecution(options) {
   }
 }
 
+function setupSymbolDisposePolyfill() {
+  Symbol.dispose ??= SymbolDispose;
+  Symbol.asyncDispose ??= SymbolAsyncDispose;
+}
+
+
 function setupUserModules(isLoaderWorker = false) {
   initializeCJSLoader();
   initializeESMLoader(isLoaderWorker);
diff --git a/lib/internal/streams/readable.js b/lib/internal/streams/readable.js
index 7a2aad41ee2baa..deac7a040fe79e 100644
--- a/lib/internal/streams/readable.js
+++ b/lib/internal/streams/readable.js
@@ -31,6 +31,7 @@ const {
   ObjectSetPrototypeOf,
   Promise,
   SafeSet,
+  SymbolAsyncDispose,
   SymbolAsyncIterator,
   Symbol,
 } = primordials;
@@ -67,6 +68,7 @@ const {
     ERR_STREAM_UNSHIFT_AFTER_END_EVENT,
     ERR_UNKNOWN_ENCODING,
   },
+  AbortError,
 } = require('internal/errors');
 const { validateObject } = require('internal/validators');
 
@@ -234,6 +236,12 @@ Readable.prototype[EE.captureRejectionSymbol] = function(err) {
   this.destroy(err);
 };
 
+Readable.prototype[SymbolAsyncDispose] = function() {
+  const error = new AbortError();
+  this.destroy(error);
+  return new Promise((resolve, reject) => eos(this, (err) => (err !== error ? reject(err) : resolve(null))));
+};
+
 // Manually shove something into the read() buffer.
 // This returns true if the highWaterMark has not been hit yet,
 // similar to how Writable.write() returns true if you should
diff --git a/test/parallel/test-fs-promises-file-handle-dispose.js b/test/parallel/test-fs-promises-file-handle-dispose.js
new file mode 100644
index 00000000000000..406430eef4a204
--- /dev/null
+++ b/test/parallel/test-fs-promises-file-handle-dispose.js
@@ -0,0 +1,12 @@
+'use strict';
+
+const common = require('../common');
+const { promises: fs } = require('fs');
+
+async function doOpen() {
+  const fh = await fs.open(__filename);
+  fh.on('close', common.mustCall());
+  await fh[Symbol.asyncDispose]();
+}
+
+doOpen().then(common.mustCall());
diff --git a/test/parallel/test-stream-readable-dispose.js b/test/parallel/test-stream-readable-dispose.js
new file mode 100644
index 00000000000000..e940bf1688f2bf
--- /dev/null
+++ b/test/parallel/test-stream-readable-dispose.js
@@ -0,0 +1,23 @@
+'use strict';
+
+const common = require('../common');
+const { Readable } = require('stream');
+const assert = require('assert');
+
+{
+  const read = new Readable({
+    read() {}
+  });
+  read.resume();
+
+  read.on('end', common.mustNotCall('no end event'));
+  read.on('close', common.mustCall());
+  read.on('error', common.mustCall((err) => {
+    assert.strictEqual(err.name, 'AbortError');
+  }));
+
+  read[Symbol.asyncDispose]().then(common.mustCall(() => {
+    assert.strictEqual(read.errored.name, 'AbortError');
+    assert.strictEqual(read.destroyed, true);
+  }));
+}
diff --git a/typings/primordials.d.ts b/typings/primordials.d.ts
index e1aa6419031115..b0a8c506a214a8 100644
--- a/typings/primordials.d.ts
+++ b/typings/primordials.d.ts
@@ -480,6 +480,8 @@ declare namespace primordials {
   export const SymbolFor: typeof Symbol.for
   export const SymbolKeyFor: typeof Symbol.keyFor
   export const SymbolAsyncIterator: typeof Symbol.asyncIterator
+  export const SymbolDispose: typeof Symbol
+  export const SymbolAsyncDispose: typeof Symbol
   export const SymbolHasInstance: typeof Symbol.hasInstance
   export const SymbolIsConcatSpreadable: typeof Symbol.isConcatSpreadable
   export const SymbolIterator: typeof Symbol.iterator

From 8dc2ee76069b755abdb1e6ecfed138ae1b012c0d Mon Sep 17 00:00:00 2001
From: Moshe Atlow <moshe@atlow.co.il>
Date: Thu, 22 Jun 2023 12:51:11 +0300
Subject: [PATCH 02/10] Update lib/internal/process/pre_execution.js

Co-authored-by: Robert Nagy <ronagy@icloud.com>
---
 lib/internal/process/pre_execution.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index 3b201ac2930e5a..6d25c6f49414a0 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -129,7 +129,6 @@ function setupSymbolDisposePolyfill() {
   Symbol.asyncDispose ??= SymbolAsyncDispose;
 }
 
-
 function setupUserModules(isLoaderWorker = false) {
   initializeCJSLoader();
   initializeESMLoader(isLoaderWorker);

From 223a2d833a94899528dbd9e0f7953fd92010cd0b Mon Sep 17 00:00:00 2001
From: Moshe Atlow <moshe@atlow.co.il>
Date: Thu, 22 Jun 2023 12:51:42 +0300
Subject: [PATCH 03/10] Update lib/internal/streams/readable.js

Co-authored-by: Robert Nagy <ronagy@icloud.com>
---
 lib/internal/streams/readable.js | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/lib/internal/streams/readable.js b/lib/internal/streams/readable.js
index deac7a040fe79e..34af7ede9c2630 100644
--- a/lib/internal/streams/readable.js
+++ b/lib/internal/streams/readable.js
@@ -237,8 +237,11 @@ Readable.prototype[EE.captureRejectionSymbol] = function(err) {
 };
 
 Readable.prototype[SymbolAsyncDispose] = function() {
-  const error = new AbortError();
-  this.destroy(error);
+  let error
+  if (!this.destroyed) {
+    error = new AbortError();
+    this.destroy(error);
+  }
   return new Promise((resolve, reject) => eos(this, (err) => (err !== error ? reject(err) : resolve(null))));
 };
 

From 40ba972930943350b51da59c2dc2f6789efe435b Mon Sep 17 00:00:00 2001
From: Moshe Atlow <moshe@atlow.co.il>
Date: Thu, 22 Jun 2023 12:52:20 +0300
Subject: [PATCH 04/10] lint

---
 lib/internal/streams/readable.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/internal/streams/readable.js b/lib/internal/streams/readable.js
index 34af7ede9c2630..c47eb0edfd9ba3 100644
--- a/lib/internal/streams/readable.js
+++ b/lib/internal/streams/readable.js
@@ -237,7 +237,7 @@ Readable.prototype[EE.captureRejectionSymbol] = function(err) {
 };
 
 Readable.prototype[SymbolAsyncDispose] = function() {
-  let error
+  let error;
   if (!this.destroyed) {
     error = new AbortError();
     this.destroy(error);

From e8a014ff37b920c8486cdd1ba3d5839cab7c19b0 Mon Sep 17 00:00:00 2001
From: Benjamin Gruenbaum <inglor@gmail.com>
Date: Thu, 22 Jun 2023 13:37:19 +0300
Subject: [PATCH 05/10] Update lib/internal/streams/readable.js

Co-authored-by: Robert Nagy <ronagy@icloud.com>
---
 lib/internal/streams/readable.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/internal/streams/readable.js b/lib/internal/streams/readable.js
index c47eb0edfd9ba3..9d230f879df684 100644
--- a/lib/internal/streams/readable.js
+++ b/lib/internal/streams/readable.js
@@ -239,7 +239,7 @@ Readable.prototype[EE.captureRejectionSymbol] = function(err) {
 Readable.prototype[SymbolAsyncDispose] = function() {
   let error;
   if (!this.destroyed) {
-    error = new AbortError();
+    error = this.readableEnded ? null : new AbortError();
     this.destroy(error);
   }
   return new Promise((resolve, reject) => eos(this, (err) => (err !== error ? reject(err) : resolve(null))));

From 48602bb25188be460f45f55565b97944f49ea433 Mon Sep 17 00:00:00 2001
From: Benjamin Gruenbaum <inglor@gmail.com>
Date: Thu, 22 Jun 2023 13:37:40 +0300
Subject: [PATCH 06/10] Update lib/internal/streams/readable.js

Co-authored-by: Robert Nagy <ronagy@icloud.com>
---
 lib/internal/streams/readable.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/internal/streams/readable.js b/lib/internal/streams/readable.js
index 9d230f879df684..b282f51b4e885e 100644
--- a/lib/internal/streams/readable.js
+++ b/lib/internal/streams/readable.js
@@ -242,7 +242,7 @@ Readable.prototype[SymbolAsyncDispose] = function() {
     error = this.readableEnded ? null : new AbortError();
     this.destroy(error);
   }
-  return new Promise((resolve, reject) => eos(this, (err) => (err !== error ? reject(err) : resolve(null))));
+  return new Promise((resolve, reject) => eos(this, (err) => (err && err !== error ? reject(err) : resolve(null))));
 };
 
 // Manually shove something into the read() buffer.

From 39b6acec206a46eca4af9867739471d8d8c33f32 Mon Sep 17 00:00:00 2001
From: Moshe Atlow <moshe@atlow.co.il>
Date: Thu, 22 Jun 2023 14:40:38 +0300
Subject: [PATCH 07/10] eslint disable

---
 lib/internal/process/pre_execution.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index 6d25c6f49414a0..fb445cbc030c21 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -125,7 +125,9 @@ function prepareExecution(options) {
 }
 
 function setupSymbolDisposePolyfill() {
+  // eslint-disable-next-line node-core/prefer-primordials
   Symbol.dispose ??= SymbolDispose;
+  // eslint-disable-next-line node-core/prefer-primordials
   Symbol.asyncDispose ??= SymbolAsyncDispose;
 }
 

From a6d798dc405cc139bbbee91012930cbdd659c22b Mon Sep 17 00:00:00 2001
From: Moshe Atlow <moshe@atlow.co.il>
Date: Thu, 22 Jun 2023 18:55:32 +0300
Subject: [PATCH 08/10] CR

---
 lib/internal/per_context/primordials.js | 3 ++-
 lib/internal/process/pre_execution.js   | 1 +
 typings/primordials.d.ts                | 4 ++--
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/lib/internal/per_context/primordials.js b/lib/internal/per_context/primordials.js
index fcc1dba394910d..98e9a0754a8a76 100644
--- a/lib/internal/per_context/primordials.js
+++ b/lib/internal/per_context/primordials.js
@@ -228,8 +228,9 @@ function copyPrototype(src, dest, prefix) {
   copyPrototype(original.prototype, primordials, `${name}Prototype`);
 });
 
-// Define Symbol.Disposed and Symbol.AsyncDispose
+// Define Symbol.Dispose and Symbol.AsyncDispose
 // Until these are defined by the environment.
+// TODO(MoLow): Remove this polyfill once Symbol.dispose and Symbol.asyncDispose are available in V8.
 primordials.SymbolDispose ??= primordials.SymbolFor('nodejs.dispose');
 primordials.SymbolAsyncDispose ??= primordials.SymbolFor('nodejs.asyncDispose');
 
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index fb445cbc030c21..5f8569b1531c92 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -125,6 +125,7 @@ function prepareExecution(options) {
 }
 
 function setupSymbolDisposePolyfill() {
+  // TODO(MoLow): Remove this polyfill once Symbol.dispose and Symbol.asyncDispose are available in V8.
   // eslint-disable-next-line node-core/prefer-primordials
   Symbol.dispose ??= SymbolDispose;
   // eslint-disable-next-line node-core/prefer-primordials
diff --git a/typings/primordials.d.ts b/typings/primordials.d.ts
index b0a8c506a214a8..45e63d2da89a7d 100644
--- a/typings/primordials.d.ts
+++ b/typings/primordials.d.ts
@@ -480,8 +480,8 @@ declare namespace primordials {
   export const SymbolFor: typeof Symbol.for
   export const SymbolKeyFor: typeof Symbol.keyFor
   export const SymbolAsyncIterator: typeof Symbol.asyncIterator
-  export const SymbolDispose: typeof Symbol
-  export const SymbolAsyncDispose: typeof Symbol
+  export const SymbolDispose: typeof Symbol // TODO(MoLow): use typeof Symbol.dispose when it's available
+  export const SymbolAsyncDispose: typeof Symbol // TODO(MoLow): use typeof Symbol.asyncDispose when it's available
   export const SymbolHasInstance: typeof Symbol.hasInstance
   export const SymbolIsConcatSpreadable: typeof Symbol.isConcatSpreadable
   export const SymbolIterator: typeof Symbol.iterator

From 98285ae7b3cf8f1b054c5fb90439ad0deac96440 Mon Sep 17 00:00:00 2001
From: Moshe Atlow <moshe@atlow.co.il>
Date: Fri, 23 Jun 2023 09:12:39 +0300
Subject: [PATCH 09/10] docs: add experimental

---
 doc/api/fs.md     | 2 ++
 doc/api/stream.md | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 5ddc2a5b2d0977..093bf7dbe6f72a 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -823,6 +823,8 @@ the end of the file.
 added: REPLACEME
 -->
 
+> Stability: 1 - Experimental
+
 An alias for `filehandle.close()`.
 
 ### `fsPromises.access(path[, mode])`
diff --git a/doc/api/stream.md b/doc/api/stream.md
index 22d0178389ffe0..c8a7544fa2b1d3 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -1910,6 +1910,8 @@ has less then 64 KiB of data because no `highWaterMark` option is provided to
 added: REPLACEME
 -->
 
+> Stability: 1 - Experimental
+
 An alias for [`readable.destroy()`][readable-destroy] with an `AbortError`.
 
 ##### `readable.compose(stream[, options])`

From 5d0d435eb6fa6655b0519c5effa214e5e1706834 Mon Sep 17 00:00:00 2001
From: Benjamin Gruenbaum <inglor@gmail.com>
Date: Fri, 23 Jun 2023 14:05:00 +0300
Subject: [PATCH 10/10] Update doc/api/stream.md

---
 doc/api/stream.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/api/stream.md b/doc/api/stream.md
index c8a7544fa2b1d3..72ccfe50aeee18 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -1912,7 +1912,8 @@ added: REPLACEME
 
 > Stability: 1 - Experimental
 
-An alias for [`readable.destroy()`][readable-destroy] with an `AbortError`.
+Calls [`readable.destroy()`][readable-destroy] with an `AbortError` and returns
+a promise that fulfills when the stream is finished.
 
 ##### `readable.compose(stream[, options])`