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:
converter
(external links)
|
charsets</br>
(as required as argument)
|
standalone builds
>> CDN links
</th>
</tr>
</thead>
| Base1/Unary |
- all
- sequence
- default
- tmark
|
|
| Base16 |
|
|
| Base32 |
- crockford
- rfc3548
- rfc4648
- zbase32
|
|
| Base58 |
|
|
| Base64 |
|
|
| UUencode |
|
|
| Base85 |
- adobe
- ascii85
- rfc1924 (charset only)
- z85
|
|
| Base91 |
|
|
| LEB128 |
|
|
| Ecoji |
|
|
| Base2048 |
|
|
SimpleBase
(Base2-Base62)
|
|
|
| BasePhi (Golden Ratio Base)</td>
|
|
|
</tr>
| ByteConverter |
---
|
|
| BaseEx |
Ready to use instances of the above converters:
- base1
- base16
- base32_crockford
- base32_rfc3548
- base32_rfc4648
- base32_zbase32
- base58
- base58_bitcoin
- base58_flickr
- base64
- base64_urlsafe
- uuencode
- uuencode_original
- xxencode
- base85_adobe
- base85_ascii
- base85_z85
- base91
- leb128
- ecoji_v1
- ecoji_v2
- base2048
- byteConverter
- simpleBase
|
(complete builds)
|
</tbody>
</table>
_Additional charsets can be added. Watch this [live example](https://umamiappearance.github.io/BaseExJS/examples/live-examples.html#charsets)._
## Installation
### GitHub
```console
git clone https://github.com/UmamiAppearance/BaseExJS.git
```
### npm
```console
nmp install base-ex
```
## Builds
There are multiple builds available which are always grouped as [esm](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) and [iife](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), plus a minified version of each. The full build with all converters included can be found at [dist](https://github.com/UmamiAppearance/BaseExJS/tree/main/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](https://github.com/UmamiAppearance/BaseExJS/tree/main/dist/converters). Or at the table [above](#available-converterscharsets). Ready to use CDN-links are listed [here](/BaseExJS/CDN.html).
_Note that standalone converters are exported as default._
## Usage
### Importing
#### Browser
```html
```
```js
// 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
```js
// 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](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](https://developer.mozilla.org/en-US/docs/Glossary/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](#available-converterscharsets))_
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:
```js
// 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
| property | arguments |
|---|
| endianness | be | le |
|---|
| padding | nopad | pad |
|---|
| sign | unsigned | signed |
|---|
| case | lower | upper |
|---|
| charset | <various> |
|---|
| number-mode | number |
|---|
| decimal-mode | decimal |
|---|
| IO handler |
- bytesIn >> accept only bytes as input
- bytesOut >> limits output to byte-like values
- bytesInOut >> in- and output limited to bytes
|
| output types |
- bigint64
- bigint_n
- biguint64
- buffer
- bytes
- float32
- float64
- float_n
- int8
- int16
- int32
- int_n
- str
- uint8
- uint16
- uint32
- uint_n
- view
|
### En- and Decoding
Example:
_(Ecoji is simply picked, because of its picturesque appearance, any other converter works the same)_
```js
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](https://umamiappearance.github.io/BaseExJS/examples/live-examples.html). Also try out the [Online Base Converter](https://umamiappearance.github.io/BaseExJS/examples/demo.html) for additional code examples.
___
You can play with the Examples on your local machine by running:
```console
npm start
```
_(``devDependencies`` required, run ``npm install`` from the package folder first)_
## License
[MIT](https://opensource.org/licenses/MIT)
Copyright (c) 2023, UmamiAppearance
### [Third Party Licenses](https://github.com/UmamiAppearance/BaseExJS/tree/main/third-party-licenses)
* The **basE91** en-/decoder relies on the work of _Joachim Henke_. The original code is licensed under [BSD-3-Clause](https://opensource.org/licenses/BSD-3-Clause). His method was transpiled to JavaScript with small adjustments.
* The [test files](https://github.com/UmamiAppearance/BaseExJS/tree/main/test/fixtures/ecoji) for the **Ecoji** decoder ([ecoji-orig.test.js](https://github.com/UmamiAppearance/BaseExJS/blob/main/test/ecoji-orig.test.js)) are copied from the [Ecoji repository](https://github.com/keith-turner/ecoji/tree/main/test_scripts/data) and are created by [_Keith Turner_](https://github.com/keith-turner). These are licensed under [Apache-2.0](https://opensource.org/licenses/APACHE-2.0)
* The **Base2048** Decoder relies on the work of [_qntm_](https://github.com/qntm). The original code is licensed under the [MIT-License](https://opensource.org/licenses/MIT). 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](https://github.com/MikeMcl/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_](https://github.com/MikeMcl), is licensed under the [MIT-License](https://opensource.org/licenses/MIT).
|