js-base64

What is js-base64?

The js-base64 npm package is a simple, fast, and consistent library for encoding and decoding to and from Base64, a group of binary-to-text encoding schemes that represent binary data in an ASCII string format by translating it into a radix-64 representation. It can be used in both browser and Node.js environments.

What are js-base64's main functionalities?

Encoding to Base64

This feature allows you to encode a string into Base64 format.

const { Base64 } = require('js-base64');
const encoded = Base64.encode('Hello, World!');
console.log(encoded); // Outputs: SGVsbG8sIFdvcmxkIQ==

Decoding from Base64

This feature allows you to decode a Base64 encoded string back to its original format.

const { Base64 } = require('js-base64');
const decoded = Base64.decode('SGVsbG8sIFdvcmxkIQ==');
console.log(decoded); // Outputs: Hello, World!

Safe URL Base64 Encoding and Decoding

This feature provides methods for encoding and decoding Base64 in a URL-safe manner, which means it can be used in URL query parameters without needing additional encoding.

const { Base64 } = require('js-base64');
const urlEncoded = Base64.encodeURI('https://www.example.com/?search=js-base64');
console.log(urlEncoded); // Outputs a URL-safe Base64 string
const urlDecoded = Base64.decode(urlEncoded);
console.log(urlDecoded); // Outputs the original URL

No Padding Option

This feature allows you to encode in Base64 without any padding characters ('='), which might be necessary in certain contexts where padding is not supported or desired.

const { Base64 } = require('js-base64');
const noPaddingEncoded = Base64.encode('Hello, World!', true); // The second argument indicates no padding
console.log(noPaddingEncoded); // Outputs: SGVsbG8sIFdvcmxkIQ

Other packages similar to js-base64

btoa

The btoa package provides a polyfill for the btoa() function, which converts binary data to a Base64-encoded string. It is primarily intended for use in environments where the window.btoa function is not available, such as Node.js. It does not offer decoding functionality.

atob

The atob package is the counterpart to btoa, providing a polyfill for the atob() function, which decodes a Base64-encoded string. Like btoa, it is intended for environments where the window.atob function is not available, and it only offers decoding functionality.

base64-js

The base64-js package provides functions to encode and decode Base64 in a way that is highly compatible with the browser's built-in btoa and atob functions. It is designed to be more efficient by working with Typed Arrays, making it suitable for performance-critical applications that handle binary data.

buffer

The buffer package is a Node.js module that provides additional functionalities for manipulating binary data. It includes methods for encoding and decoding Base64 as part of its API. While it is more comprehensive than js-base64, it is also more complex and Node.js specific.

README

base64.js

Yet another Base64 transcoder

HEADS UP: ES2015 support required since version 3

Version 3 is completely rewritten with ES2015 features like arrow functions. All modern browsers and node 12 or up are directly supported. Your codes should run unchanged. IE is no longer supported directly but you can transpile the script to use it (see below).

The hardest part of maintaing this module was not Base64 features, but cross-platform support (eg. nodejs vs web browsers). By making ES2015 mandatory virtually all codes are common (except atob() and btoa()).

If you need to support legacy browsers like IE, use version 2 or transpile.

Ironically ES6 export is not used to keep the API compatible.

Usage

Install

$ npm install --save js-base64

Transpile to ES5

Since base64.js is now written in ES2015 (aka ES6), It no longer runs on IE. Yet you can still transpile it to ES5 and the resulting script does run on IE. just

$ npm run build

which does

$ babel base64.js -o base64-es5.js

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/js-base64@3.0.4/base64.min.js">

node.js

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

As a ES6 Module (via babel, et al.)

import { Base64 } from 'js-base64';

SYNOPSIS

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

Base64.decode('ZGFua29nYWk=');  // dankogai
Base64.atob(  'ZGFua29nYWk=');  // dankogai
Base64.toUint8Array(            // new Uint8Array([100,97,110,107,111,103,97,105])
    'ZGFua29nYWk='
);
Base64.decode('5bCP6aO85by+');  // 小飼弾
// note .decodeURI() is unnecessary since it accepts both flavors
Base64.decode('5bCP6aO85by-');  // 小飼弾
Base64.atob(  '5bCP6aO85by+');  // '小飼弾' which is nonsense

String Extension for ES5

// 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();// new Uint8Array([100,97,110,107,111,103,97,105])

// you have to explicitly extend String.prototype
Base64.extendString();
// once extended, you can do the following
const u8s =  new Uint8Array([100,97,110,107,111,103,97,105]);
u8s.toBase64();     // 'ZGFua29nYWk='
u8s.toBase64URI();  // 'ZGFua29nYWk'
u8s.toBase64URL();  // 'ZGFua29nYWk' an alias of .toBase64URI()

You can extend both via Base64.extendBuiltin().

TypeScript

TypeScript 2.0 type definition was added to the DefinitelyTyped repository.

$ npm install --save @types/js-base64

.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