177 lines
4.9 KiB
Markdown
177 lines
4.9 KiB
Markdown
# Unibabel
|
||
|
||
Minimalistic **Base64**, **TypedArrays**, and **UTF-8** / **Unicode** conversions in Browser (and Node) JavaScript.
|
||
Optional add-on support for **hex** and **base32**.
|
||
|
||
See <https://coolaj86.com/articles/base64-unicode-utf-8-javascript-and-you/>
|
||
|
||
See also
|
||
|
||
- [TextEncoder](https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder/encode) / [TextDecoder](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoder/decode)
|
||
- [DateView](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView)
|
||
- [text-encoding](https://github.com/inexorabletash/text-encoding)
|
||
- [TextEncoderLite (based on Buffer)](https://github.com/coolaj86/TextEncoderLite/tree/litest)
|
||
- [TextEncoderLite (based on text-encoding)](https://github.com/coolaj86/TextEncoderLite/tree/lite)
|
||
- [Beatgammit's base64-js](https://github.com/beatgammit/base64-js)
|
||
|
||
# Example (Unicode to ArrayBuffer):
|
||
|
||
```js
|
||
var unicodeString = "I'm a ☢ ☃ that plays 𝄢 guitar and spea̧͈͖ks Ar̽̾̈́͒͑ ̶̧̨̱̹̭̯ͧ̾ͬC̷̙̲̝͖ͭ̏ͥͮ͟Oͮ͏̮̪̝͍M̲̖͊̒ͪͩͬ̚̚͜!";
|
||
var buf = Unibabel.utf8ToBuffer(unicodeString);
|
||
```
|
||
|
||
## Supported Environments
|
||
|
||
- VanillaJS
|
||
- Node.js
|
||
- CommonJS
|
||
- WebPack
|
||
- ... everything?
|
||
|
||
# Browser Usage
|
||
|
||
## CDN
|
||
|
||
- <https://unpkg.com/unibabel@3.0.0/dist/unibabel.all.js>
|
||
- <https://unpkg.com/unibabel@3.0.0/dist/unibabel.all.min.js>
|
||
|
||
## Bower
|
||
|
||
```bash
|
||
bower install --save unibabel
|
||
```
|
||
|
||
```html
|
||
<script src="/bower_components/unibabel/dist/unibabel.all.js"></script>
|
||
```
|
||
|
||
# Node Usage
|
||
|
||
You don't _need_ this module, as you already have
|
||
[`Buffer`](https://nodejs.org/api/buffer.html) and [`thirty-two`](https://github.com/chrisumbel/thirty-two):
|
||
|
||
For example:
|
||
|
||
```javascript
|
||
var buf = Buffer.from('I ½ ♥ 💩', 'utf8');
|
||
buf.toString('hex');
|
||
buf.toString('base64');
|
||
buf.toString('ascii');
|
||
buf.toString('utf8');
|
||
buf.toString('binary'); // deprecated, do not use
|
||
```
|
||
|
||
However, you _can_ use it (perhaps for isomorphic js?)
|
||
|
||
# API
|
||
|
||
```javascript
|
||
// TypedArray <--> UTF8
|
||
var uint8Array = Unibabel.strToUtf8Arr(str);
|
||
var str = Unibabel.utf8ArrToStr(uint8Array);
|
||
|
||
// TypedArray <--> Base64
|
||
var base64 = Unibabel.arrToBase64(uint8Array);
|
||
var uint8Array = Unibabel.base64ToArr(base64);
|
||
```
|
||
|
||
**Normal APIs**
|
||
|
||
`unibabel.js`
|
||
|
||
- utf8ToBuffer(utf8str) => array
|
||
- bufferToUtf8(array) => string
|
||
- utf8ToBase64(utf8str) => base64
|
||
- base64ToUtf8(base64) => string
|
||
- bufferToBase64(array) => base64
|
||
- base64ToBuffer(base64) => array
|
||
|
||
**Hex APIs**
|
||
|
||
`unibabel.hex.js`
|
||
|
||
- hexToBuffer(hexstr) => array
|
||
- bufferToHex(array) => hexstr
|
||
|
||
**Base32 APIs**
|
||
|
||
`unibabel.base32.js`
|
||
|
||
- base32ToBuffer(b32str) => array
|
||
- bufferToBase32(array) => b32str
|
||
|
||
**Helper APIs**
|
||
|
||
- utf8ToBinaryString(utf8str) => binstr
|
||
- binaryStringToUtf8(binstr) => utf8str
|
||
- bufferToBinaryString(buffer) => binstr
|
||
- binaryStringToBuffer(binstr) => array
|
||
|
||
# Examples
|
||
|
||
```javascript
|
||
// Base64
|
||
|
||
var myArray = Unibabel.base64ToArr(
|
||
'QmFzZSA2NCDigJQgTW96aWxsYSBEZXZlbG9wZXIgTmV0d29yaw=='
|
||
); // "Base 64 \u2014 Mozilla Developer Network"
|
||
var myBuffer = Unibabel.base64ToArr(
|
||
'QmFzZSA2NCDigJQgTW96aWxsYSBEZXZlbG9wZXIgTmV0d29yaw=='
|
||
).buffer; // "Base 64 \u2014 Mozilla Developer Network"
|
||
|
||
console.log(myBuffer.byteLength);
|
||
|
||
// Crazy Unicode
|
||
|
||
var sMyInput = "I'm a ☢ ☃ that plays 𝄢 guitar and spea̧͈͖ks Ar̽̾̈́͒͑ ̶̧̨̱̹̭̯ͧ̾ͬC̷̙̲̝͖ͭ̏ͥͮ͟Oͮ͏̮̪̝͍M̲̖͊̒ͪͩͬ̚̚͜!";
|
||
var aMyUTF8Input = Unibabel.strToUtf8Arr(sMyInput);
|
||
var sMyBase64 = Unibabel.arrToBase64(aMyUTF8Input);
|
||
|
||
alert(sMyBase64);
|
||
|
||
var aMyUTF8Output = Unibabel.base64ToArr(sMyBase64);
|
||
var sMyOutput = Unibabel.utf8ArrToStr(aMyUTF8Output);
|
||
|
||
alert(sMyOutput);
|
||
```
|
||
|
||
# License
|
||
|
||
- `index.js` and `unibabel.hex.js` are dual-licensed as Apache 2.0 and MIT.
|
||
- `unibabel.base32.js` is a modified version of [thirty-two](https://github.com/chrisumbel/thirty-two) and is therefore licensed MIT.
|
||
|
||
Some parts of the code were taken from MDN, which Mozilla has licensed in the Public Domain,
|
||
which means that I am at liberty to re-license my copy under the Apache 2 and MIT licenses.
|
||
|
||
See <https://developer.mozilla.org/en-US/docs/MDN/About#Copyrights_and_licenses>
|
||
|
||
# ChangeLog
|
||
|
||
## v3.0.0
|
||
|
||
- Proper node support (`unibabel.node.js`)
|
||
- Various minor updates
|
||
|
||
## v2.1.0
|
||
|
||
Added `unibabel.base32.js`
|
||
|
||
## v2.0.0
|
||
|
||
The new implementation is binary compatible with node.js, TextEncoder,
|
||
and other more-common UTF-8 encodings.
|
||
|
||
It is also based on DOM APIs which result in much less code and are still
|
||
backwards compatible all the way back to IE6 (not on purpose, just that
|
||
it happens to work).
|
||
|
||
See <https://coolaj86.com/articles/base64-unicode-utf-8-javascript-and-you/>
|
||
|
||
## v1.0.0
|
||
|
||
This version was based on the work by good folks at the MDN, however,
|
||
the UTF-8 conversion was not byte-compatible with other UTF-8 conversions
|
||
(such as node.js and TextEncoder), so don't use it.
|
||
See <https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding>
|