michsior14/js-base64

Base64 implementation for JavaScript

base64.js

Yet another Base64 transcoder

HEADS UP: switch to TypeScript since version 3.3

In version 3.0 js-base64 switch to ES2015 module. That made it easy to switch to TypeScript(just renaming base64.mjs to base64.ts was almost enough). Now base64.mjs is compiled from base64.ts then base64.js is generated from base64.mjs.

Install

$ npm install --save js-base64

Usage

In Browser

Locally…

<script src="base64.js"></script>

… or Directly from CDN. In which case you don't even need to install.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/base64.min.js"></script>

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.

node.js (commonjs)

const Base64 = require('js-base64').Base64;

Unlike the case above, the global context is no longer modified.

As a ES6 Module

locally…

import { Base64 } from 'js-base64';

// or if you prefer no Base64 namespace
import { encode, decode } from 'js-base64';

or even remotely.

<script type="module">
// note jsdelivr.net does not automatically minify .mjs
import { Base64 } from 'https://cdn.jsdelivr.net/npm/[email protected]/base64.mjs';
</script>

<script type="module">
// or if you prefer no Base64 namespace
import { encode, decode } from 'https://cdn.jsdelivr.net/npm/[email protected]/base64.mjs';
</script>

SYNOPSIS

let latin = 'dankogai';
let utf8  = '小飼弾'
let u8s   =  new Uint8Array([100,97,110,107,111,103,97,105]);
Base64.encode(latin);       // ZGFua29nYWk=
Base64.btoa(latin);         // ZGFua29nYWk=
Base64.btoa(utf8);          // raises exception 
Base64.fromUint8Array(u8s); // ZGFua29nYWk=
Base64.fromUint8Array(u8s); // ZGFua29nYW which is URI safe
Base64.encode(utf8);        // 5bCP6aO85by+
Base64.encode(utf8, true)   // 5bCP6aO85by-
Base64.encodeURI(utf8);     // 5bCP6aO85by-

Base64.decode(      'ZGFua29nYWk=');// dankogai
Base64.atob(        'ZGFua29nYWk=');// dankogai
Base64.atob(        '5bCP6aO85by+');// '�飼弾' which is nonsense
Base64.toUint8Array('ZGFua29nYWk=');// u8s above
Base64.decode(      '5bCP6aO85by+');// 小飼弾
// note .decodeURI() is unnecessary since it accepts both flavors
Base64.decode(      '5bCP6aO85by-');// 小飼弾

Built-in Extensions

By default Base64 leaves built-in prototypes untouched. But you can extend them as below.

// you have to explicitly extend String.prototype
Base64.extendString();
// once extended, you can do the following
'dankogai'.toBase64();        // ZGFua29nYWk=
'小飼弾'.toBase64();           // 5bCP6aO85by+
'小飼弾'.toBase64(true);       // 5bCP6aO85by-
'小飼弾'.toBase64URI();        // 5bCP6aO85by-
'小飼弾'.toBase64URL();        // 5bCP6aO85by- an alias of .toBase64URI()
'ZGFua29nYWk='.fromBase64();  // dankogai
'5bCP6aO85by+'.fromBase64();  // 小飼弾
'5bCP6aO85by-'.fromBase64();  // 小飼弾
'5bCP6aO85by-'.toUint8Array();// u8s above

// you have to explicitly extend String.prototype
Base64.extendString();
// once extended, you can do the following
u8s.toBase64();     // 'ZGFua29nYWk='
u8s.toBase64URI();  // 'ZGFua29nYWk'
u8s.toBase64URL();  // 'ZGFua29nYWk' an alias of .toBase64URI()

// extend all at once
Base64.extendBuiltins()

.decode() vs .atob (and .encode() vs btoa())

Suppose you have:

var pngBase64 = 
  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=";

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.

Or even better, Base64.toUint8Array(pngBase64).

SEE ALSO

• http://en.wikipedia.org/wiki/Base64