| 1 | # abab [](https://www.npmjs.com/package/abab) [](https://travis-ci.org/jsdom/abab)
|
|---|
| 2 |
|
|---|
| 3 | A JavaScript module that implements `window.atob` and `window.btoa` according the forgiving-base64 algorithm in the [Infra Standard](https://infra.spec.whatwg.org/#forgiving-base64). The original code was forked from [w3c/web-platform-tests](https://github.com/w3c/web-platform-tests/blob/master/html/webappapis/atob/base64.html).
|
|---|
| 4 |
|
|---|
| 5 | Compatibility: Node.js version 3+ and all major browsers.
|
|---|
| 6 |
|
|---|
| 7 | Install with `npm`:
|
|---|
| 8 |
|
|---|
| 9 | ```sh
|
|---|
| 10 | npm install abab
|
|---|
| 11 | ```
|
|---|
| 12 |
|
|---|
| 13 | ## API
|
|---|
| 14 |
|
|---|
| 15 | ### `btoa` (base64 encode)
|
|---|
| 16 |
|
|---|
| 17 | ```js
|
|---|
| 18 | const { btoa } = require('abab');
|
|---|
| 19 | btoa('Hello, world!'); // 'SGVsbG8sIHdvcmxkIQ=='
|
|---|
| 20 | ```
|
|---|
| 21 |
|
|---|
| 22 | ### `atob` (base64 decode)
|
|---|
| 23 |
|
|---|
| 24 | ```js
|
|---|
| 25 | const { atob } = require('abab');
|
|---|
| 26 | atob('SGVsbG8sIHdvcmxkIQ=='); // 'Hello, world!'
|
|---|
| 27 | ```
|
|---|
| 28 |
|
|---|
| 29 | #### Valid characters
|
|---|
| 30 |
|
|---|
| 31 | [Per the spec](https://html.spec.whatwg.org/multipage/webappapis.html#atob:dom-windowbase64-btoa-3), `btoa` will accept strings "containing only characters in the range `U+0000` to `U+00FF`." If passed a string with characters above `U+00FF`, `btoa` will return `null`. If `atob` is passed a string that is not base64-valid, it will also return `null`. In both cases when `null` is returned, the spec calls for throwing a `DOMException` of type `InvalidCharacterError`.
|
|---|
| 32 |
|
|---|
| 33 | ## Browsers
|
|---|
| 34 |
|
|---|
| 35 | If you want to include just one of the methods to save bytes in your client-side code, you can `require` the desired module directly.
|
|---|
| 36 |
|
|---|
| 37 | ```js
|
|---|
| 38 | const atob = require('abab/lib/atob');
|
|---|
| 39 | const btoa = require('abab/lib/btoa');
|
|---|
| 40 | ```
|
|---|
| 41 |
|
|---|
| 42 | ## Development
|
|---|
| 43 |
|
|---|
| 44 | If you're **submitting a PR** or **deploying to npm**, please use the [checklists in CONTRIBUTING.md](CONTRIBUTING.md#checklists).
|
|---|
| 45 |
|
|---|
| 46 | ## Remembering what `atob` and `btoa` stand for
|
|---|
| 47 |
|
|---|
| 48 | Base64 comes from IETF [RFC 4648](https://tools.ietf.org/html/rfc4648#section-4) (2006).
|
|---|
| 49 |
|
|---|
| 50 | - **`btoa`**, the encoder function, stands for **binary** to **ASCII**, meaning it converts any binary input into a subset of **ASCII** (Base64).
|
|---|
| 51 | - **`atob`**, the decoder function, converts **ASCII** (or Base64) to its original **binary** format.
|
|---|
