├── CODE_OF_CONDUCT.md ├── DIVERGENCES.md ├── GLOBALS.md ├── IMPORTMETA.md ├── LICENSE └── README.md /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | This repository is a TC39 project and subscribes to its [code of conduct](https://tc39.github.io/code-of-conduct/). It is available at [https://tc39.github.io/code-of-conduct/](https://tc39.github.io/code-of-conduct/). 2 | 3 | To ask a question or report an issue, please email [tc39-conduct-reports@googlegroups.com](mailto:tc39-conduct-reports@googlegroups.com). 4 | -------------------------------------------------------------------------------- /DIVERGENCES.md: -------------------------------------------------------------------------------- 1 | This document aims to list places where an API to address similar use cases is developed differently in different environments. These differences sometimes make it hard to write code which spans environments, and sometimes justify investigation into a shared solution. 2 | 3 | This initial document includes Node and Web APIs, but PRs are welcome to document additional environments as well. Some of the entries here may be poor analogies--if so, please make a PR to clarify things! 4 | 5 | For interfaces to be considered analogous, there should be some evidence that developers today are using them in a shared way today, e.g., a widely-used polyfill of one in terms of the other, or a widely-used higher-level API based on them both. 6 | 7 | ## Event handling 8 | 9 | - **Purpose**: Register callbacks for certain events 10 | - **Web API**: [EventTarget](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget) 11 | - **Node.js API**: [EventEmitter](https://nodejs.org/api/events.html) 12 | - **Mitigation strategies**: TODO (Observables? Polyfills? How do programmers write isomorphic code today?) 13 | 14 | ## Streams 15 | 16 | - **Purpose**: Incremental access to binary data, e.g., from over the network 17 | - **Web API**: [WHATWG Streams API](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) 18 | - **Node.js API**: [Node Streams](https://nodejs.org/api/stream.html) 19 | - **Mitigation strategies**: [whatwg-stream](https://github.com/nodejs/whatwg-stream) effort to implement WHATWG Streams as a Node.js module; [`readable-stream`](https://www.npmjs.com/package/readable-stream) provides Node streams for the Web 20 | 21 | ## Buffers 22 | 23 | - **Purpose**: Interaction with octet streams 24 | - **Web API**: [ArrayBuffer API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) 25 | - **Node.js API** [Buffer API](https://nodejs.org/api/buffer.html) 26 | - **Mitigation strategies**: Newer versions of Node.js have [Buffer.from(arrayBuffer)](https://nodejs.org/api/buffer.html#buffer_class_method_buffer_from_arraybuffer_byteoffset_length) method and the `Buffer` is an instance of a [TypedArray](https://nodejs.org/api/buffer.html#buffer_buffers_and_typedarray) with a few caveats. 27 | 28 | ## HTTP access 29 | 30 | - **Purpose**: Open, read and write to an HTTP, HTTPS, HTTP2 connection 31 | - **Web API**: [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) 32 | - **Node.js API**: [http](https://nodejs.org/api/http.html), [https](https://nodejs.org/api/https.html), [http2](https://nodejs.org/api/http2.html) 33 | - **Mitigation strategies**: [node-fetch](https://www.npmjs.com/package/node-fetch) polyfill to support fetch from Node.js, [stream-http](https://www.npmjs.com/package/stream-http) implementation of the Node HTTP module for browsers 34 | 35 | ## Cryptography 36 | 37 | - **Purpose**: Basic cryptography algorithms, available as a standard library 38 | - **Web API**: WebCrypto's [`crypto.subtle` SubtleCrypto](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto) 39 | - **Node.js API**: The [`crypto` module](https://nodejs.org/api/crypto.html) 40 | - **Mitigation strategies**: npm packages like [uuid](https://www.npmjs.com/package/uuid) detect where they are running and use whatever APIs are available. There are various WebCrypto polyfills/shims in npm, but none seem to be very widely used. 41 | 42 | ## Filesystem access 43 | 44 | - **Purpose**: Read and write files on the filesystem 45 | - **Web API**: [File API](https://developer.mozilla.org/en-US/docs/Web/API/File), in-progress [WritableFile](https://github.com/WICG/writable-files/blob/master/EXPLAINER.md) proposal 46 | - **Node.js API**: [`fs` module](https://nodejs.org/api/fs.html) 47 | - **Mitigation strategies**: TODO (Unclear if these are analogous enough to actually ever be bridged in practice) 48 | 49 | ## Cancel[l]ation 50 | 51 | - **Purpose**: Provide APIs which cancel asynchronous processes, asynchronous requests, promises, etc. 52 | - **Web API**: [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) 53 | - **Node API**: ?? 54 | - **Mitigation strategies**: ?? 55 | -------------------------------------------------------------------------------- /GLOBALS.md: -------------------------------------------------------------------------------- 1 | ## Multi-environment properties of the global object 2 | 3 | Properties of the global object are the entry-point to the web's current JavaScript APIs, as built-in modules are not yet exposed. This page documents properties of the global object that are shared between embedders, and the level of compatibility between them. 4 | 5 | Note, information about Node.js compatibility [is welcome](https://github.com/mdn/browser-compat-data/issues/3280#issuecomment-453486379) in MDN. 6 | 7 | ### Conventions 8 | - Only include APIs which have built-in support in at least two environments, at least one of which is the Web. 9 | - Link to MDN for browser compatibility data (there is a multivendor effort to keep this data in good shape). 10 | - Include at most a short note about compatibility inline, and use a separate Markdown file for more extensive notes. 11 | - When possible, include information about support in the following embedding environments: 12 | - [Web](https://developer.mozilla.org/en-US/docs/Web/API) 13 | - [Node.js](https://nodejs.org/api/) 14 | - (please make PRs to add to this list! Should we add CloudFlare Workers, Windows Universal Apps, Moddable XS, etc?) 15 | 16 | ### URL 17 | 18 | Spec: https://url.spec.whatwg.org 19 | 20 | Environments supported: 21 | - [Web](https://developer.mozilla.org/en-US/docs/Web/API/URL#Browser_compatibility) 22 | - Node.js: [URL](https://nodejs.org/api/url.html) and [URLSearchParams](https://nodejs.org/api/url.html#url_class_urlsearchparams) 23 | 24 | Compatibility: Node.js implements the same interface, modulo brand checks and IDL mistakes in Node.js (TODO: be more specific) 25 | 26 | ### Encoding standard 27 | 28 | Spec: https://encoding.spec.whatwg.org 29 | 30 | Environments supported: 31 | - [Web](https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API) 32 | - Node.js: [TextEncoder](https://nodejs.org/api/util.html#util_class_util_textencoder) and [TextDecoder](https://nodejs.org/api/util.html#util_class_util_textdecoder) 33 | 34 | Compatibility: Node.js does not support the `*Stream` encoding interfaces. The set of encoding supported by Node is dependent on compilation options; see Node documentation for more details. 35 | 36 | ### WebAssembly JS API 37 | 38 | Spec: https://www.w3.org/TR/wasm-js-api-1/ 39 | 40 | Environments supported: 41 | - [Web](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly) 42 | - Node.js: not documented yet 43 | 44 | ### Console API 45 | 46 | Spec: https://console.spec.whatwg.org 47 | 48 | Environments supported: 49 | - [Web](https://developer.mozilla.org/en-US/docs/Web/API/console) 50 | - [Node.js](https://nodejs.org/api/console.html) 51 | -------------------------------------------------------------------------------- /IMPORTMETA.md: -------------------------------------------------------------------------------- 1 | ## `import.meta` properties 2 | 3 | The TC39 [import.meta](https://github.com/tc39/proposal-import-meta) 4 | 5 | ### `url` 6 | 7 | [From the HTML specification](https://html.spec.whatwg.org/#hostgetimportmetaproperties), 8 | > the module script's base URL, serialized 9 | At a high level, roughly, this means: the directory where the running module came from. 10 | 11 | Environment support: 12 | - [Shipping on the Web](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import.meta#Browser_compatibility) 13 | - [Shipping in Node.js](https://nodejs.org/api/esm.html#esm_import_meta) (Still experimental, modules are being re-considered by the Modules Team) 14 | 15 | ### `resolveURL` 16 | 17 | Status: [Proposed](https://github.com/whatwg/html/issues/3871) for the web 18 | 19 | ### `require` 20 | 21 | Status: Proposed for Node.js (TODO: link?) 22 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2018 Daniel Ehrenberg 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Many JavaScript APIs, originally created for the Web Platform, are being implemented in other JavaScript environments. These shared interfaces assist the usage of the same JS code in various different places, sometimes called "isomorphic code". This repository attempts to document which JavaScript APIs are shared and on which platforms. 2 | 3 | ### Sections 4 | 5 | - [Global object](https://github.com/littledan/js-shared-interfaces/blob/master/GLOBALS.md): Globals implemented in multiple environments 6 | - [import.meta](https://github.com/littledan/js-shared-interfaces/blob/master/IMPORTMETA.md): Shipping and proposed properties of the `import.meta` object 7 | - [Divergences](https://github.com/littledan/js-shared-interfaces/blob/master/DIVERGENCES.md): Places where multiple environments ship analogous APIs, and JavaScript programmers have been picking up the pieces to bridge them 8 | 9 | ### Goals 10 | 11 | - Help JavaScript programmers target multiple environments while using a broad range of APIs 12 | - Enable more effective and rapid standards development by surfacing factors from non-Web environments early 13 | - Expose and help prioritize opportunities for supporting shared interfaces to embedding environment maintainers 14 | - Provide the underlying data which might be used some day to consider describing a standard JavaScript base library 15 | 16 | ### Non-goals 17 | 18 | - Add any procedural requirements/blockers in standards development, or slow anything down (there's already enough paperwork! many APIs don't make sense in other environments, or people may be unavailable for feedback) 19 | - List globals which are only implemented in a single environment (there are too many; use that environment's documentation) 20 | - Document compatibility among browsers for global objects (see MDN, ChromeStatus, caniuse, etc.) 21 | - Include any interfaces exposed by TC39 standards (which are already presumed to be cross-environment) 22 | - Include polyfills (may make sense in the future, but keep scope minimal at first) 23 | 24 | ### Why is this a personal repository? 25 | 26 | I don't want to have this as a personal repository forever, but it's unclear whether this repository will evolve into any document which requires standardization as such. To encourage freely shared development, I hope to move ownership to a larger, neutral organization, such as a foundation, or W3C [WICG](https://github.com/WICG). 27 | --------------------------------------------------------------------------------