| [d24f17c] | 1 | # web-streams-polyfill
|
|---|
| 2 |
|
|---|
| 3 | Web Streams, based on the WHATWG spec reference implementation.
|
|---|
| 4 |
|
|---|
| 5 | [](https://travis-ci.com/MattiasBuelens/web-streams-polyfill)
|
|---|
| 6 | [](https://www.npmjs.com/package/web-streams-polyfill)
|
|---|
| 7 | [](https://github.com/MattiasBuelens/web-streams-polyfill/blob/master/LICENSE)
|
|---|
| 8 | [](https://gitter.im/web-streams-polyfill/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
|---|
| 9 |
|
|---|
| 10 | ## Links
|
|---|
| 11 |
|
|---|
| 12 | - [Official spec][spec]
|
|---|
| 13 | - [Reference implementation][ref-impl]
|
|---|
| 14 |
|
|---|
| 15 | ## Usage
|
|---|
| 16 |
|
|---|
| 17 | This library comes in multiple variants:
|
|---|
| 18 | * `web-streams-polyfill`: a polyfill that replaces the native stream implementations.
|
|---|
| 19 | Recommended for use in web apps supporting older browsers through a `<script>` tag.
|
|---|
| 20 | * `web-streams-polyfill/es6`: a polyfill targeting ES2015+ environments.
|
|---|
| 21 | Recommended for use in web apps supporting modern browsers through a `<script>` tag.
|
|---|
| 22 | * `web-streams-polyfill/es2018`: a polyfill targeting ES2018+ environments.
|
|---|
| 23 | * `web-streams-polyfill/ponyfill`: a [ponyfill] that provides
|
|---|
| 24 | the stream implementations without replacing any globals.
|
|---|
| 25 | Recommended for use in legacy Node applications, or in web libraries supporting older browsers.
|
|---|
| 26 | * `web-streams-polyfill/ponyfill/es6`: a ponyfill targeting ES2015+ environments.
|
|---|
| 27 | Recommended for use in Node 6+ applications, or in web libraries supporting modern browsers.
|
|---|
| 28 | * `web-streams-polyfill/ponyfill/es2018`: a ponyfill targeting ES2018+ environments.
|
|---|
| 29 | Recommended for use in Node 10+ applications.
|
|---|
| 30 |
|
|---|
| 31 | Each variant also includes TypeScript type definitions, compatible with the DOM type definitions for streams included in TypeScript.
|
|---|
| 32 |
|
|---|
| 33 | Usage as a polyfill:
|
|---|
| 34 | ```html
|
|---|
| 35 | <!-- option 1: hosted by unpkg CDN -->
|
|---|
| 36 | <script src="https://unpkg.com/web-streams-polyfill/dist/polyfill.min.js"></script>
|
|---|
| 37 | <!-- option 2: self hosted -->
|
|---|
| 38 | <script src="/path/to/web-streams-polyfill/dist/polyfill.min.js"></script>
|
|---|
| 39 | <script>
|
|---|
| 40 | var readable = new ReadableStream();
|
|---|
| 41 | </script>
|
|---|
| 42 | ```
|
|---|
| 43 | Usage as a Node module:
|
|---|
| 44 | ```js
|
|---|
| 45 | var streams = require("web-streams-polyfill/ponyfill");
|
|---|
| 46 | var readable = new streams.ReadableStream();
|
|---|
| 47 | ```
|
|---|
| 48 | Usage as a ES2015 module:
|
|---|
| 49 | ```js
|
|---|
| 50 | import { ReadableStream } from "web-streams-polyfill/ponyfill";
|
|---|
| 51 | const readable = new ReadableStream();
|
|---|
| 52 | ```
|
|---|
| 53 |
|
|---|
| 54 | ## Compatibility
|
|---|
| 55 |
|
|---|
| 56 | The `polyfill` and `ponyfill` variants work in any ES5-compatible environment that has a global `Promise`.
|
|---|
| 57 | If you need to support older browsers or Node versions that do not have a native `Promise` implementation
|
|---|
| 58 | (check the [support table][promise-support]), you must first include a `Promise` polyfill
|
|---|
| 59 | (e.g. [promise-polyfill][promise-polyfill]).
|
|---|
| 60 |
|
|---|
| 61 | The `polyfill/es6` and `ponyfill/es6` variants work in any ES2015-compatible environment.
|
|---|
| 62 |
|
|---|
| 63 | The `polyfill/es2018` and `ponyfill/es2018` variants work in any ES2018-compatible environment.
|
|---|
| 64 |
|
|---|
| 65 | [Async iterable support for `ReadableStream`][rs-asynciterator] is available in all variants, but requires an ES2018-compatible environment or a polyfill for `Symbol.asyncIterator`.
|
|---|
| 66 |
|
|---|
| 67 | [`WritableStreamDefaultController.signal`][ws-controller-signal] is available in all variants, but requires a global `AbortController` constructor. If necessary, consider using a polyfill such as [abortcontroller-polyfill].
|
|---|
| 68 |
|
|---|
| 69 | [Reading with a BYOB reader][mdn-byob-read] is available in all variants, but requires `ArrayBuffer.prototype.transfer()` or `structuredClone()` to exist in order to correctly transfer the given view's buffer. If not available, then the buffer won't be transferred during the read.
|
|---|
| 70 |
|
|---|
| 71 | ## Compliance
|
|---|
| 72 |
|
|---|
| 73 | The polyfill implements [version `4dc123a` (13 Nov 2023)][spec-snapshot] of the streams specification.
|
|---|
| 74 |
|
|---|
| 75 | The polyfill is tested against the same [web platform tests][wpt] that are used by browsers to test their native implementations.
|
|---|
| 76 | The polyfill aims to pass all tests, although it allows some exceptions for practical reasons:
|
|---|
| 77 | * The `es2018` variant passes all of the tests.
|
|---|
| 78 | * The `es6` variant passes the same tests as the `es2018` variant, except for the [test for the prototype of `ReadableStream`'s async iterator][wpt-async-iterator-prototype].
|
|---|
| 79 | Retrieving the correct `%AsyncIteratorPrototype%` requires using an async generator (`async function* () {}`), which is invalid syntax before ES2018.
|
|---|
| 80 | Instead, the polyfill [creates its own version][stub-async-iterator-prototype] which is functionally equivalent to the real prototype.
|
|---|
| 81 | * The `es5` variant passes the same tests as the `es6` variant, except for various tests about specific characteristics of the constructors, properties and methods.
|
|---|
| 82 | These test failures do not affect the run-time behavior of the polyfill.
|
|---|
| 83 | For example:
|
|---|
| 84 | * The `name` property of down-leveled constructors is incorrect.
|
|---|
| 85 | * The `length` property of down-leveled constructors and methods with optional arguments is incorrect.
|
|---|
| 86 | * Not all properties and methods are correctly marked as non-enumerable.
|
|---|
| 87 | * Down-leveled class methods are not correctly marked as non-constructable.
|
|---|
| 88 |
|
|---|
| 89 | The type definitions are compatible with the built-in stream types of TypeScript 3.3.
|
|---|
| 90 |
|
|---|
| 91 | ## Contributors
|
|---|
| 92 |
|
|---|
| 93 | Thanks to these people for their work on [the original polyfill][creatorrr-polyfill]:
|
|---|
| 94 |
|
|---|
| 95 | - Diwank Singh Tomer ([creatorrr](https://github.com/creatorrr))
|
|---|
| 96 | - Anders Riutta ([ariutta](https://github.com/ariutta))
|
|---|
| 97 |
|
|---|
| 98 | [spec]: https://streams.spec.whatwg.org
|
|---|
| 99 | [ref-impl]: https://github.com/whatwg/streams
|
|---|
| 100 | [ponyfill]: https://github.com/sindresorhus/ponyfill
|
|---|
| 101 | [promise-support]: https://kangax.github.io/compat-table/es6/#test-Promise
|
|---|
| 102 | [promise-polyfill]: https://www.npmjs.com/package/promise-polyfill
|
|---|
| 103 | [rs-asynciterator]: https://streams.spec.whatwg.org/#rs-asynciterator
|
|---|
| 104 | [ws-controller-signal]: https://streams.spec.whatwg.org/#ws-default-controller-signal
|
|---|
| 105 | [abortcontroller-polyfill]: https://www.npmjs.com/package/abortcontroller-polyfill
|
|---|
| 106 | [mdn-byob-read]: https://developer.mozilla.org/en-US/docs/Web/API/ReadableStreamBYOBReader/read
|
|---|
| 107 | [spec-snapshot]: https://streams.spec.whatwg.org/commit-snapshots/4dc123a6e7f7ba89a8c6a7975b021156f39cab52/
|
|---|
| 108 | [wpt]: https://github.com/web-platform-tests/wpt/tree/2a298b616b7c865917d7198a287310881cbfdd8d/streams
|
|---|
| 109 | [wpt-async-iterator-prototype]: https://github.com/web-platform-tests/wpt/blob/2a298b616b7c865917d7198a287310881cbfdd8d/streams/readable-streams/async-iterator.any.js#L24
|
|---|
| 110 | [stub-async-iterator-prototype]: https://github.com/MattiasBuelens/web-streams-polyfill/blob/v2.0.0/src/target/es5/stub/async-iterator-prototype.ts
|
|---|
| 111 | [creatorrr-polyfill]: https://github.com/creatorrr/web-streams-polyfill
|
|---|
