Merge pull request #984 from BasixKOR/structured-clone

.eslintrc.js

@@ -108,7 +108,7 @@ const base = {
   // disallow unnecessary labels
   'no-extra-label': ERROR,
   // disallow fallthrough of case statements
-  'no-fallthrough': ERROR,
+  'no-fallthrough': [ERROR, { commentPattern: 'break omitted' }],
   // disallow the use of leading or trailing decimal points in numeric literals
   'no-floating-decimal': ERROR,
   // disallow reassignments of native objects
@@ -1119,11 +1119,12 @@ module.exports = {
         'tests/compat/**',
       ],
       globals: {
-        compositeKey: READONLY,
-        compositeSymbol: READONLY,
         AsyncIterator: READONLY,
         Iterator: READONLY,
         Observable: READONLY,
+        compositeKey: READONLY,
+        compositeSymbol: READONLY,
+        structuredClone: READONLY,
       },
     },
     {

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Changelog
 ##### Unreleased
+- Added `structuredClone` method [from the HTML spec](https://html.spec.whatwg.org/multipage/structured-data.html#dom-structuredclone), [see MDN](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone)
+  - Includes all cases of cloning and transferring of required ECMAScript and platform types that can be polyfilled, for the details see [the caveats](https://github.com/zloirock/core-js#caveats-when-using-structuredclone-polyfill)
+  - Uses native structured cloning algorithm implementations where it's possible
+  - Includes the new semantic of errors cloning from [`html/5749`](https://github.com/whatwg/html/pull/5749)
 - Added `DOMException` polyfill, [the Web IDL spec](https://webidl.spec.whatwg.org/#idl-DOMException), [see MDN](https://developer.mozilla.org/en-US/docs/Web/API/DOMException)
   - Includes `DOMException` and its attributes polyfills with fixes of many different engines bugs
   - Includes `DOMException#stack` property polyfill in engines that should have it

README.md

@@ -130,6 +130,7 @@ Promise.resolve(32).then(x => console.log(x)); // => 32
     - [Pre-stage 0 proposals](#pre-stage-0-proposals)
       - [`Reflect` metadata](#reflect-metadata)
   - [Web standards](#web-standards)
+    - [`structuredClone`](#structuredclone)
     - [`setTimeout` and `setInterval`](#settimeout-and-setinterval)
     - [`setImmediate`](#setimmediate)
     - [`queueMicrotask`](#queuemicrotask)
@@ -2865,6 +2866,51 @@ Reflect.getOwnMetadata('foo', object); // => 'bar'
 ```js
 core-js(-pure)/web
 ```
+#### `structuredClone`[⬆](#index)
+[Spec](https://html.spec.whatwg.org/multipage/structured-data.html#dom-structuredclone), module [`web.structured-clone`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/web.structured-clone.js)
+```js
+function structuredClone(value: Serializable, { transfer?: Sequence<Transferable> }): any;
+```
+[*CommonJS entry points:*](#commonjs-api)
+```js
+core-js/web/structured-clone
+core-js(-pure)/stable|features/structured-clone
+```
+[*Examples*](t.ly/dBEC):
+```js
+const structured = [{ a: 42 }];
+const sclone = structuredClone(structured);
+console.log(sclone);                      // => [{ a: 42 }]
+console.log(structured !== sclone);       // => true
+console.log(structured[0] !== sclone[0]); // => true
+
+const circular = {};
+circular.circular = circular;
+const cclone = structuredClone(circular);
+console.log(cclone.circular === cclone);  // => true
+
+structuredClone(42);                                            // => 42
+structuredClone({ x: 42 });                                     // => { x: 42 }
+structuredClone([1, 2, 3]);                                     // => [1, 2, 3]
+structuredClone(new Set([1, 2, 3]));                            // => Set{ 1, 2, 3 }
+structuredClone(new Map([['a', 1], ['b', 2]]));                 // => Map{ a: 1, b: 2 }
+structuredClone(new Int8Array([1, 2, 3]));                      // => new Int8Array([1, 2, 3])
+structuredClone(new AggregateError([1, 2, 3], 'message'));      // => new AggregateError([1, 2, 3], 'message'))
+structuredClone(new TypeError('message', { cause: 42 }));       // => new TypeError('message', { cause: 42 })
+structuredClone(new DOMException('message', 'DataCloneError')); // => new DOMException('message', 'DataCloneError')
+structuredClone(document.getElementById('myfileinput'));        // => new FileList
+structuredClone(new DOMPoint(1, 2, 3, 4));                      // => new DOMPoint(1, 2, 3, 4)
+structuredClone(new Blob(['test']));                            // => new Blob(['test'])
+structuredClone(new ImageData(8, 8));                           // => new ImageData(8, 8)
+// etc.
+
+structuredClone(new WeakMap()); // => DataCloneError on non-serializable types
+```
+##### Caveats when using `structuredClone` polyfill:[⬆](#index)
+
+* `ArrayBuffer` instances and many platform types cannot be transferred in most engines since we have no way to polyfill this behavior, however `.transfer` option works for some platform types. I recommend avoiding this option.
+* Some specific platform types can't be cloned in old engines. Mainly it's very specific types or very old engines, but here are some exceptions. For example, we have no sync way to clone `ImageBitmap` in Safari 14.0- or Firefox 83-, so it's recommended to look to the [polyfill source](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/web.structured-clone.js) if you wanna clone something specific.
+
 #### `setTimeout` and `setInterval`[⬆](#index)
 Module [`web.timers`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/web.timers.js). Additional arguments fix for IE9-.
 ```js

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

@@ -1850,6 +1850,13 @@ export const data = {
     node: '12.0', // '11.0',
     safari: '12.1',
   },
+  'web.structured-clone': {
+    // https://github.com/whatwg/html/pull/5749
+    // deno: '1.14',
+    // current FF implementation can't clone errors
+    // firefox: '94',
+    // node: '17.0',
+  },
   'web.timers': {
     android: '1.5',
     chrome: '1',

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

@@ -133,5 +133,6 @@ export default {
     'web.dom-exception.constructor',
     'web.dom-exception.stack',
     'web.dom-exception.to-string-tag',
+    'web.structured-clone',
   ],
 };

packages/core-js/es/array-buffer/constructor.js

@@ -1,4 +1,5 @@
 require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.object.to-string');
 var path = require('../../internals/path');
 

packages/core-js/es/data-view/index.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.data-view');
 require('../../modules/es.object.to-string');
 var path = require('../../internals/path');

packages/core-js/es/typed-array/float32-array.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.typed-array.float32-array');
 require('./methods');
 var global = require('../../internals/global');

packages/core-js/es/typed-array/float64-array.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.typed-array.float64-array');
 require('./methods');
 var global = require('../../internals/global');

packages/core-js/es/typed-array/int16-array.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.typed-array.int16-array');
 require('./methods');
 var global = require('../../internals/global');

packages/core-js/es/typed-array/int32-array.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.typed-array.int32-array');
 require('./methods');
 var global = require('../../internals/global');

packages/core-js/es/typed-array/int8-array.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.typed-array.int8-array');
 require('./methods');
 var global = require('../../internals/global');

packages/core-js/es/typed-array/uint16-array.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.typed-array.uint16-array');
 require('./methods');
 var global = require('../../internals/global');

packages/core-js/es/typed-array/uint32-array.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.typed-array.uint32-array');
 require('./methods');
 var global = require('../../internals/global');

packages/core-js/es/typed-array/uint8-array.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.typed-array.uint8-array');
 require('./methods');
 var global = require('../../internals/global');

packages/core-js/es/typed-array/uint8-clamped-array.js

@@ -1,3 +1,5 @@
+require('../../modules/es.array-buffer.constructor');
+require('../../modules/es.array-buffer.slice');
 require('../../modules/es.typed-array.uint8-clamped-array');
 require('./methods');
 var global = require('../../internals/global');

packages/core-js/features/structured-clone.js

@@ -0,0 +1,3 @@
+var parent = require('../stable/structured-clone');
+
+module.exports = parent;