1 | [![build status](https://app.travis-ci.com/dankogai/js-base64.svg)](https://app.travis-ci.com/github/dankogai/js-base64)
|
2 |
|
3 | # base64.js
|
4 |
|
5 | Yet another [Base64] transcoder.
|
6 |
|
7 | [Base64]: http://en.wikipedia.org/wiki/Base64
|
8 |
|
9 | ## Install
|
10 |
|
11 | ```shell
|
12 | $ npm install --save js-base64
|
13 | ```
|
14 |
|
15 | ## Usage
|
16 |
|
17 | ### In Browser
|
18 |
|
19 | Locally…
|
20 |
|
21 | ```html
|
22 | <script src="base64.js"></script>
|
23 | ```
|
24 |
|
25 | … or Directly from CDN. In which case you don't even need to install.
|
26 |
|
27 | ```html
|
28 | <script src="https://cdn.jsdelivr.net/npm/js-base64@3.7.2/base64.min.js"></script>
|
29 | ```
|
30 |
|
31 | This good old way loads `Base64` in the global context (`window`). Though `Base64.noConflict()` is made available, you should consider using ES6 Module to avoid tainting `window`.
|
32 |
|
33 | ### As an ES6 Module
|
34 |
|
35 | locally…
|
36 |
|
37 | ```javascript
|
38 | import { Base64 } from 'js-base64';
|
39 | ```
|
40 |
|
41 | ```javascript
|
42 | // or if you prefer no Base64 namespace
|
43 | import { encode, decode } from 'js-base64';
|
44 | ```
|
45 |
|
46 | or even remotely.
|
47 |
|
48 | ```html
|
49 | <script type="module">
|
50 | // note jsdelivr.net does not automatically minify .mjs
|
51 | import { Base64 } from 'https://cdn.jsdelivr.net/npm/js-base64@3.7.2/base64.mjs';
|
52 | </script>
|
53 | ```
|
54 |
|
55 | ```html
|
56 | <script type="module">
|
57 | // or if you prefer no Base64 namespace
|
58 | import { encode, decode } from 'https://cdn.jsdelivr.net/npm/js-base64@3.7.2/base64.mjs';
|
59 | </script>
|
60 | ```
|
61 |
|
62 | ### node.js (commonjs)
|
63 |
|
64 | ```javascript
|
65 | const {Base64} = require('js-base64');
|
66 | ```
|
67 |
|
68 | Unlike the case above, the global context is no longer modified.
|
69 |
|
70 | You can also use [esm] to `import` instead of `require`.
|
71 |
|
72 | [esm]: https://github.com/standard-things/esm
|
73 |
|
74 | ```javascript
|
75 | require=require('esm')(module);
|
76 | import {Base64} from 'js-base64';
|
77 | ```
|
78 |
|
79 | ## SYNOPSIS
|
80 |
|
81 | ```javascript
|
82 | let latin = 'dankogai';
|
83 | let utf8 = '小飼弾'
|
84 | let u8s = new Uint8Array([100,97,110,107,111,103,97,105]);
|
85 | Base64.encode(latin); // ZGFua29nYWk=
|
86 | Base64.encode(latin, true)); // ZGFua29nYWk skips padding
|
87 | Base64.encodeURI(latin)); // ZGFua29nYWk
|
88 | Base64.btoa(latin); // ZGFua29nYWk=
|
89 | Base64.btoa(utf8); // raises exception
|
90 | Base64.fromUint8Array(u8s); // ZGFua29nYWk=
|
91 | Base64.fromUint8Array(u8s, true); // ZGFua29nYW which is URI safe
|
92 | Base64.encode(utf8); // 5bCP6aO85by+
|
93 | Base64.encode(utf8, true) // 5bCP6aO85by-
|
94 | Base64.encodeURI(utf8); // 5bCP6aO85by-
|
95 | ```
|
96 |
|
97 | ```javascript
|
98 | Base64.decode( 'ZGFua29nYWk=');// dankogai
|
99 | Base64.decode( 'ZGFua29nYWk'); // dankogai
|
100 | Base64.atob( 'ZGFua29nYWk=');// dankogai
|
101 | Base64.atob( '5bCP6aO85by+');// 'å°é£¼å¼¾' which is nonsense
|
102 | Base64.toUint8Array('ZGFua29nYWk=');// u8s above
|
103 | Base64.decode( '5bCP6aO85by+');// 小飼弾
|
104 | // note .decodeURI() is unnecessary since it accepts both flavors
|
105 | Base64.decode( '5bCP6aO85by-');// 小飼弾
|
106 | ```
|
107 |
|
108 | ```javascript
|
109 | Base64.isValid(0); // false: 0 is not string
|
110 | Base64.isValid(''); // true: a valid Base64-encoded empty byte
|
111 | Base64.isValid('ZA=='); // true: a valid Base64-encoded 'd'
|
112 | Base64.isValid('Z A='); // true: whitespaces are okay
|
113 | Base64.isValid('ZA'); // true: padding ='s can be omitted
|
114 | Base64.isValid('++'); // true: can be non URL-safe
|
115 | Base64.isValid('--'); // true: or URL-safe
|
116 | Base64.isValid('+-'); // false: can't mix both
|
117 | ```
|
118 |
|
119 | ### Built-in Extensions
|
120 |
|
121 | By default `Base64` leaves built-in prototypes untouched. But you can extend them as below.
|
122 |
|
123 | ```javascript
|
124 | // you have to explicitly extend String.prototype
|
125 | Base64.extendString();
|
126 | // once extended, you can do the following
|
127 | 'dankogai'.toBase64(); // ZGFua29nYWk=
|
128 | '小飼弾'.toBase64(); // 5bCP6aO85by+
|
129 | '小飼弾'.toBase64(true); // 5bCP6aO85by-
|
130 | '小飼弾'.toBase64URI(); // 5bCP6aO85by- ab alias of .toBase64(true)
|
131 | '小飼弾'.toBase64URL(); // 5bCP6aO85by- an alias of .toBase64URI()
|
132 | 'ZGFua29nYWk='.fromBase64(); // dankogai
|
133 | '5bCP6aO85by+'.fromBase64(); // 小飼弾
|
134 | '5bCP6aO85by-'.fromBase64(); // 小飼弾
|
135 | '5bCP6aO85by-'.toUint8Array();// u8s above
|
136 | ```
|
137 |
|
138 | ```javascript
|
139 | // you have to explicitly extend Uint8Array.prototype
|
140 | Base64.extendUint8Array();
|
141 | // once extended, you can do the following
|
142 | u8s.toBase64(); // 'ZGFua29nYWk='
|
143 | u8s.toBase64URI(); // 'ZGFua29nYWk'
|
144 | u8s.toBase64URL(); // 'ZGFua29nYWk' an alias of .toBase64URI()
|
145 | ```
|
146 |
|
147 | ```javascript
|
148 | // extend all at once
|
149 | Base64.extendBuiltins()
|
150 | ```
|
151 |
|
152 | ## `.decode()` vs `.atob` (and `.encode()` vs `btoa()`)
|
153 |
|
154 | Suppose you have:
|
155 |
|
156 | ```
|
157 | var pngBase64 =
|
158 | "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=";
|
159 | ```
|
160 |
|
161 | Which is a Base64-encoded 1x1 transparent PNG, **DO NOT USE** `Base64.decode(pngBase64)`. Use `Base64.atob(pngBase64)` instead. `Base64.decode()` decodes to UTF-8 string while `Base64.atob()` decodes to bytes, which is compatible to browser built-in `atob()` (Which is absent in node.js). The same rule applies to the opposite direction.
|
162 |
|
163 | Or even better, `Base64.toUint8Array(pngBase64)`.
|
164 |
|
165 | ### If you really, really need an ES5 version
|
166 |
|
167 | You can transpiles to an ES5 that runs on IEs before 11. Do the following in your shell.
|
168 |
|
169 | ```shell
|
170 | $ make base64.es5.js
|
171 | ```
|
172 |
|
173 | ## Brief History
|
174 |
|
175 | * Since version 3.3 it is written in TypeScript. Now `base64.mjs` is compiled from `base64.ts` then `base64.js` is generated from `base64.mjs`.
|
176 | * Since version 3.7 `base64.js` is ES5-compatible again (hence IE11-compabile).
|
177 | * Since 3.0 `js-base64` switch to ES2015 module so it is no longer compatible with legacy browsers like IE (see above)
|