Merge pull request #1151 from zloirock/explicit-resource-management

Author: zloirock

CHANGELOG.md

@@ -59,6 +59,30 @@
     - `String.prototype.toWellFormed`
   - Moved to Stage 3, [November 2022 TC39 meeting](https://github.com/babel/proposals/issues/85#issuecomment-1332180862)
   - Added `/actual/` entries, disabled unconditional forced replacement
+- [Explicit resource management](https://github.com/tc39/proposal-explicit-resource-management) Stage 3 and [Async explicit resource management](https://github.com/tc39/proposal-async-explicit-resource-management) Stage 2 proposals:
+  - Renamed from "`using` statement" and [splitted into 2 (sync and async) proposals](https://github.com/tc39/proposal-explicit-resource-management/pull/131)
+  - In addition to already present well-known symbols, added new built-ins:
+    - `Symbol.dispose`
+    - `Symbol.asyncDispose`
+    - `SuppressedError`
+    - `DisposableStack`
+      - `DisposableStack.prototype.dispose`
+      - `DisposableStack.prototype.use`
+      - `DisposableStack.prototype.adopt`
+      - `DisposableStack.prototype.defer`
+      - `DisposableStack.prototype.move`
+      - `DisposableStack.prototype[@@dispose]`
+    - `AsyncDisposableStack`
+      - `AsyncDisposableStack.prototype.disposeAsync`
+      - `AsyncDisposableStack.prototype.use`
+      - `AsyncDisposableStack.prototype.adopt`
+      - `AsyncDisposableStack.prototype.defer`
+      - `AsyncDisposableStack.prototype.move`
+      - `AsyncDisposableStack.prototype[@@asyncDispose]`
+    - `Iterator.prototype[@@dispose]`
+    - `AsyncIterator.prototype[@@asyncDispose]`
+  - Sync version of this proposal moved to Stage 3, [November 2022 TC39 meeting](https://github.com/babel/proposals/issues/85#issuecomment-1333747094)
+  - Added `/actual/` namespace entries for Stage 3 proposal
 - [Compat data targets](/packages/core-js-compat#targets-option) improvements:
   - [React Native from 0.70 shipped with Hermes as the default engine.](https://reactnative.dev/blog/2022/07/08/hermes-as-the-default) However, bundled Hermes versions differ from standalone Hermes releases. So added **`react-native`** target for React Native with bundled Hermes.
   - [According to the documentation](https://developer.oculus.com/documentation/web/browser-intro/), Oculus Browser was renamed to Meta Quest Browser, so `oculus` target was renamed to **`quest`**.

README.md

@@ -130,11 +130,12 @@ queueMicrotask(() => console.log('called as microtask'));
       - [`Array` grouping](#array-grouping)
       - [Change `Array` by copy](#change-array-by-copy)
       - [New `Set` methods](#new-set-methods)
+      - [Explicit resource management](#explicit-resource-management)
       - [Well-formed unicode strings](#well-formed-unicode-strings)
     - [Stage 2 proposals](#stage-2-proposals)
       - [`Map.prototype.emplace`](#mapprototypeemplace)
       - [`Array.isTemplateObject`](#arrayistemplateobject)
-      - [`Symbol.{ asyncDispose, dispose }` for `using` statement](#symbol-asyncdispose-dispose--for-using-statement)
+      - [Async explicit resource management](#async-explicit-resource-management)
       - [`Symbol.metadataKey` for decorators metadata proposal](#symbolmetadatakey-for-decorators-metadata-proposal)
     - [Stage 1 proposals](#stage-1-proposals)
       - [`Observable`](#observable)
@@ -593,10 +594,11 @@ class [
   constructor(message: string, { cause: any }): %Error%;
 }
 
-class AggregateError {
-  constructor(errors: Iterable, message: string, { cause: any }): AggregateError;
+class AggregateError extends Error {
+  constructor(errors: Iterable, message?: string, { cause: any }?): AggregateError;
   errors: Array<any>;
   message: string;
+  cause: any;
 }
 
 class Error {
@@ -2311,6 +2313,45 @@ new Set([1, 2, 3]).isDisjointFrom(new Set([4, 5, 6]));      // => true
 new Set([1, 2, 3]).isSubsetOf(new Set([5, 4, 3, 2, 1]));    // => true
 new Set([5, 4, 3, 2, 1]).isSupersetOf(new Set([1, 2, 3]));  // => true
 ```
+##### [Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management)[⬆](#index)
+Note: **This is only built-ins for this proposal, `using` syntax support requires transpiler support.**
+
+Modules [`esnext.symbol.dispose`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.symbol.dispose.js), [`esnext.disposable-stack.constructor`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.disposable-stack.constructor.js), [`esnext.suppressed-error.constructor`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.suppressed-error.constructor.js), [`esnext.iterator.dispose`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.iterator.dispose.js).
+```js
+class Symbol {
+  static dispose: @@dispose;
+}
+
+class DisposableStack {
+  constructor(): DisposableStack;
+  dispose(): undefined;
+  use(value: Disposable): value;
+  adopt(value: object, onDispose: Function): value;
+  defer(onDispose: Function): undefined;
+  @@dispose(): undefined;
+  @@toStringTag: 'DisposableStack';
+}
+
+class SuppressedError extends Error {
+  constructor(error: any, suppressed: any, message?: string, { cause: any }?): SuppressedError;
+  error: any;
+  suppressed: any;
+  message: string;
+  cause: any;
+}
+
+class Iterator {
+  @@dispose(): undefined;
+}
+```
+[*CommonJS entry points:*](#commonjs-api)
+```js
+core-js/proposals/explicit-resource-management
+core-js(-pure)/full/symbol/dispose
+core-js(-pure)/full/disposable-stack
+core-js(-pure)/full/suppressed-error
+core-js(-pure)/full/iterator/dispose
+```
 ##### [Well-formed unicode strings](https://github.com/tc39/proposal-is-usv-string)[⬆](#index)
 Modules [`esnext.string.is-well-formed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.string.is-well-formed.js) and [`esnext.string.to-well-formed`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.string.to-well-formed.js)
 ```js
@@ -2382,19 +2423,35 @@ core-js(-pure)/full/array/is-template-object
 ```js
 console.log(Array.isTemplateObject((it => it)`qwe${ 123 }asd`)); // => true
 ```
-##### [`Symbol.{ asyncDispose, dispose }` for `using` statement](https://github.com/tc39/proposal-using-statement)[⬆](#index)
-Modules [`esnext.symbol.dispose`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.symbol.dispose.js) and [`esnext.symbol.async-dispose`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.symbol.async-dispose.js).
+##### [Async Explicit Resource Management](https://github.com/tc39/proposal-async-explicit-resource-management)[⬆](#index)
+Note: **This is only built-ins for this proposal, `using` syntax support requires transpiler support.**
+
+Modules [`esnext.symbol.async-dispose`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.symbol.async-dispose.js), [`esnext.async-disposable-stack.constructor`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.async-disposable-stack.constructor.js), [`esnext.async-iterator.async-dispose`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.async-iterator.async-dispose.js).
 ```js
 class Symbol {
   static asyncDispose: @@asyncDispose;
-  static dispose: @@dispose;
+}
+
+class AsyncDisposableStack {
+  constructor(): AsyncDisposableStack;
+  disposeAsync(): Promise<undefined>;
+  use(value: AsyncDisposable | Disposable): value;
+  adopt(value: object, onDispose: Function): value;
+  defer(onDispose: Function): undefined;
+  @@asyncDispose(): Promise<undefined>;
+  @@toStringTag: 'AsyncDisposableStack';
+}
+
+class AsyncIterator {
+  @@asyncDispose(): Promise<undefined>;
 }
 ```
 [*CommonJS entry points:*](#commonjs-api)
 ```js
-core-js/proposals/using-statement
+core-js/proposals/async-explicit-resource-management
 core-js(-pure)/full/symbol/async-dispose
-core-js(-pure)/full/symbol/dispose
+core-js(-pure)/full/async-disposable-stack
+core-js(-pure)/full/async-iterator/async-dispose
 ```
 ##### [`Symbol.metadataKey` for decorators metadata proposal](https://github.com/tc39/proposal-decorator-metadata)[⬆](#index)
 Module [`esnext.symbol.metadata-key`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.symbol.metadata-key.js).

packages/core-js-compat/src/data.mjs

@@ -1802,6 +1802,8 @@ export const data = {
   },
   // TODO: Remove from `core-js@4`
   'esnext.aggregate-error': null,
+  'esnext.suppressed-error.constructor': {
+  },
   'esnext.array.from-async': {
     bun: '0.3.0',
   },
@@ -1858,11 +1860,15 @@ export const data = {
     deno: '1.27',
     safari: '16.0',
   },
+  'esnext.async-disposable-stack.constructor': {
+  },
   'esnext.async-iterator.constructor': {
   },
   // TODO: Remove from `core-js@4`
   'esnext.async-iterator.as-indexed-pairs': {
   },
+  'esnext.async-iterator.async-dispose': {
+  },
   'esnext.async-iterator.drop': {
   },
   'esnext.async-iterator.every': {
@@ -1895,6 +1901,8 @@ export const data = {
   },
   'esnext.composite-symbol': {
   },
+  'esnext.disposable-stack.constructor': {
+  },
   'esnext.function.is-callable': {
   },
   'esnext.function.is-constructor': {
@@ -1908,6 +1916,8 @@ export const data = {
   // TODO: Remove from `core-js@4`
   'esnext.iterator.as-indexed-pairs': {
   },
+  'esnext.iterator.dispose': {
+  },
   'esnext.iterator.drop': {
   },
   'esnext.iterator.every': {

packages/core-js-compat/src/modules-by-versions.mjs

@@ -163,6 +163,11 @@ export default {
     'web.self',
   ],
   3.27: [
+    'esnext.suppressed-error.constructor',
+    'esnext.async-disposable-stack.constructor',
+    'esnext.async-iterator.async-dispose',
+    'esnext.disposable-stack.constructor',
+    'esnext.iterator.dispose',
     'esnext.set.difference.v2',
     'esnext.set.intersection.v2',
     'esnext.set.is-disjoint-from.v2',

packages/core-js/actual/disposable-stack/constructor.js

@@ -0,0 +1,7 @@
+require('../../modules/es.error.cause');
+require('../../modules/es.object.to-string');
+require('../../modules/esnext.suppressed-error.constructor');
+require('../../modules/esnext.disposable-stack.constructor');
+var path = require('../../internals/path');
+
+module.exports = path.DisposableStack;

packages/core-js/actual/disposable-stack/index.js

@@ -0,0 +1,7 @@
+require('../../modules/es.error.cause');
+require('../../modules/es.object.to-string');
+require('../../modules/esnext.suppressed-error.constructor');
+require('../../modules/esnext.disposable-stack.constructor');
+var path = require('../../internals/path');
+
+module.exports = path.DisposableStack;

packages/core-js/actual/iterator/dispose.js

@@ -0,0 +1 @@
+require('../../modules/esnext.iterator.dispose');

packages/core-js/actual/iterator/index.js

@@ -3,6 +3,7 @@ require('../../modules/es.object.to-string');
 require('../../modules/es.promise');
 require('../../modules/es.string.iterator');
 require('../../modules/esnext.iterator.constructor');
+require('../../modules/esnext.iterator.dispose');
 require('../../modules/esnext.iterator.drop');
 require('../../modules/esnext.iterator.every');
 require('../../modules/esnext.iterator.filter');

packages/core-js/actual/suppressed-error.js

@@ -0,0 +1,5 @@
+require('../modules/es.error.cause');
+require('../modules/esnext.suppressed-error.constructor');
+var path = require('../internals/path');
+
+module.exports = path.SuppressedError;

packages/core-js/actual/symbol/dispose.js

@@ -0,0 +1,4 @@
+require('../../modules/esnext.symbol.dispose');
+var WrappedWellKnownSymbolModule = require('../../internals/well-known-symbol-wrapped');
+
+module.exports = WrappedWellKnownSymbolModule.f('dispose');

packages/core-js/actual/symbol/index.js

@@ -1,3 +1,5 @@
 var parent = require('../../stable/symbol');
 
+require('../../modules/esnext.symbol.dispose');
+
 module.exports = parent;

packages/core-js/full/async-disposable-stack/constructor.js

@@ -0,0 +1,8 @@
+require('../../modules/es.error.cause');
+require('../../modules/es.object.to-string');
+require('../../modules/es.promise');
+require('../../modules/esnext.suppressed-error.constructor');
+require('../../modules/esnext.async-disposable-stack.constructor');
+var path = require('../../internals/path');
+
+module.exports = path.AsyncDisposableStack;

packages/core-js/full/async-disposable-stack/index.js

@@ -0,0 +1,8 @@
+require('../../modules/es.error.cause');
+require('../../modules/es.object.to-string');
+require('../../modules/es.promise');
+require('../../modules/esnext.suppressed-error.constructor');
+require('../../modules/esnext.async-disposable-stack.constructor');
+var path = require('../../internals/path');
+
+module.exports = path.AsyncDisposableStack;

packages/core-js/full/async-iterator/async-dispose.js

@@ -0,0 +1,3 @@
+require('../../modules/es.object.to-string');
+require('../../modules/es.promise');
+require('../../modules/esnext.async-iterator.async-dispose');

packages/core-js/full/async-iterator/index.js

@@ -1,4 +1,5 @@
 var parent = require('../../actual/async-iterator');
+require('../../modules/esnext.async-iterator.async-dispose');
 // TODO: Remove from `core-js@4`
 require('../../modules/esnext.async-iterator.as-indexed-pairs');
 require('../../modules/esnext.async-iterator.indexed');

packages/core-js/full/async-iterator/indexed.js

@@ -1,3 +1,4 @@
+// TODO: Remove from `core-js@4`
 require('../../modules/es.object.to-string');
 require('../../modules/es.promise');
 require('../../modules/esnext.async-iterator.constructor');

packages/core-js/full/disposable-stack/constructor.js

@@ -0,0 +1,3 @@
+var parent = require('../../actual/disposable-stack/constructor');
+
+module.exports = parent;

packages/core-js/full/disposable-stack/index.js

@@ -0,0 +1,3 @@
+var parent = require('../../actual/disposable-stack');
+
+module.exports = parent;

packages/core-js/full/iterator/dispose.js

@@ -0,0 +1,3 @@
+var parent = require('../../actual/iterator/dispose');
+
+module.exports = parent;

packages/core-js/full/iterator/indexed.js

@@ -1,3 +1,4 @@
+// TODO: Remove from `core-js@4`
 require('../../modules/es.object.to-string');
 require('../../modules/esnext.iterator.constructor');
 require('../../modules/esnext.iterator.indexed');

packages/core-js/full/suppressed-error.js

@@ -0,0 +1,3 @@
+var parent = require('../actual/suppressed-error');
+
+module.exports = parent;

packages/core-js/full/symbol/dispose.js

@@ -1,4 +1,3 @@
-require('../../modules/esnext.symbol.dispose');
-var WrappedWellKnownSymbolModule = require('../../internals/well-known-symbol-wrapped');
+var parent = require('../../actual/symbol/dispose');
 
-module.exports = WrappedWellKnownSymbolModule.f('dispose');
+module.exports = parent;

packages/core-js/full/symbol/index.js

@@ -1,6 +1,5 @@
 var parent = require('../../actual/symbol');
 require('../../modules/esnext.symbol.async-dispose');
-require('../../modules/esnext.symbol.dispose');
 require('../../modules/esnext.symbol.matcher');
 require('../../modules/esnext.symbol.metadata-key');
 require('../../modules/esnext.symbol.observable');

packages/core-js/internals/disposable-stack-helpers.js

@@ -0,0 +1,40 @@
+var uncurryThis = require('../internals/function-uncurry-this');
+var bind = require('../internals/function-bind-context');
+var anObject = require('../internals/an-object');
+var isNullOrUndefined = require('../internals/is-null-or-undefined');
+var getMethod = require('../internals/get-method');
+var wellKnownSymbol = require('../internals/well-known-symbol');
+
+var ASYNC_DISPOSE = wellKnownSymbol('asyncDispose');
+var DISPOSE = wellKnownSymbol('dispose');
+
+var push = uncurryThis([].push);
+
+var getDisposeMethod = function (V, hint) {
+  if (hint == 'async-dispose') {
+    return getMethod(V, ASYNC_DISPOSE) || getMethod(V, DISPOSE);
+  } return getMethod(V, DISPOSE);
+};
+
+var createDisposableResource = function (V, hint, method) {
+  return bind(method || getDisposeMethod(V, hint), V);
+};
+
+var addDisposableResource = function (disposable, V, hint, method) {
+  var resource;
+  if (!method) {
+    if (isNullOrUndefined(V)) return;
+    resource = createDisposableResource(V, hint);
+  } else if (isNullOrUndefined(V)) {
+    resource = createDisposableResource(undefined, hint, method);
+  } else {
+    resource = createDisposableResource(anObject(V), hint, method);
+  }
+
+  push(disposable.stack, resource);
+};
+
+module.exports = {
+  getDisposeMethod: getDisposeMethod,
+  addDisposableResource: addDisposableResource
+};