Base-ex NPM | npm.io

BaseEx

BaseEx is a collection of classes for data representation from Base16 (hex) to Base2048 or even BasePhi. BaseEx is completely standalone and works client and server side. There are other good solutions for e.g. Base32, Base64, Base85, but BaseEx has them all in one place. The Ex in the name stands for Exponent (of n) or - as read out loud - for an X.

Available converters/charsets:

Additional charsets can be added. Watch this live example.

Installation

GitHub

git clone https://github.com/UmamiAppearance/BaseExJS.git

npm

nmp install base-ex

Builds

There are multiple builds available which are always grouped as esm and iife, plus a minified version of each. The full build with all converters included can be found at dist, which contains:

base-ex.esm.js
base-ex.esm.min.js
base-ex.iife.js
base-ex.iife.min.js

Apart from the full build, every converter can be used standalone. The associated builds can be found at dist/converters. Or at the table above. Ready to use CDN-links are listed here.

Note that standalone converters are exported as default.

Usage

Importing

Browser

<!-- the classic -->
<script src="path/base-ex.iife.min.js"></script>

// ESM6 module

// main class
import { BaseEx } from "./path/BaseEx.esm.min.js"

// explicit converter (e.g. Base32)
import { Base32 } from "./path/BaseEx.esm.min.js"

// explicit converter from a standalone build
import Base32 from "./path/base-32.esm.min.js"

Node

// ESM6 Module

// main class
import { BaseEx } from "base-ex"

// explicit converter (e.g. Base64)
import { Base64 } from "base-ex"

// CommonJS
const BaseEx = require("base-ex");

Command Line Interface

A CLI can be found at: https://github.com/UmamiAppearance/BaseExCLI.

Available imports Browser/Node

The classic import via script tag has them all available without further ado. As it is a iife, everything is available under the scope of BaseEx.

BaseEx.Base1
BaseEx.Base16
BaseEx.Base32
...
BaseEx.BaseEx

(Which is not true for standalone builds, which are directly accessible, eg: Base16, Base32, ... See list)

The same goes for the CommonJS import from Node. The only difference is, that the scope is not necessarily named BaseEx, as this is defined by the user (const myName = require("base-ex") --> myName.Base16...).

Full import for ES6 modules:

// browser
import {
    Base1,
    Base16,
    Base32,
    Base58,
    Base64,
    UUencode,
    Base85,
    Base91,
    LEB128,
    Ecoji,
    Base2048,
    SimpleBase,
    BasePhi,
    ByteConverter,
    BaseEx 
} from "./path/BaseEx.esm.min.js"

// node
import { ... } from "base-ex"

Creating an instance

Regardless of the environment, at instance of a converter gets created like so:

const b32 = new Base32();

The constructor takes some arguments/options (which may differ between different encoder types). Those can also can be passed ephemeral to the encoder and/or decoder.

Options

En- and Decoding

Example:
(Ecoji is simply picked, because of its picturesque appearance, any other converter works the same)

const ecoji = new Ecoji();
ecoji.encode("Hello World!");
// result: 🏯🔩🚗🌷🍉👇🦒🪁👡📢☕

// default output is an ArrayBuffer, pass 'str' to convert to string
ecoji.decode("🏯🔩🚗🌷🍉👇🦒🪁👡📢☕", "str");
// result: "Hello World!"

Demonstration

More explanation is shown at the LiveExamples. Also try out the Online Base Converter for additional code examples.

You can play with the Examples on your local machine by running:

npm start

(devDependencies required, run npm install from the package folder first)

License

MIT

Third Party Licenses

The basE91 en-/decoder relies on the work of Joachim Henke. The original code is licensed under BSD-3-Clause. His method was transpiled to JavaScript with small adjustments.
The test files for the Ecoji decoder (ecoji-orig.test.js) are copied from the Ecoji repository and are created by Keith Turner. These are licensed under Apache-2.0
The Base2048 Decoder relies on the work of qntm. The original code is licensed under the MIT-License. The original code is already written in JavaScript and was slightly adjusted.
Non Integer Bases can only work with a high decimal precision, this is done with the help of Big.js. The code is reduced to the requirements of the converters (at the moment this is only BasePhi). Big.js, created by Michael Mclaughlin, is licensed under the MIT-License.