https://github.com/umamiappearance/baseexjs
A collection of classes for data representation from Base16 (hex) to Base2048 written in JavaScript.
https://github.com/umamiappearance/baseexjs
base16 base2048 base32 base58 base64 base85 base91 binary browser ecoji golden-ratio hex hexadecimal javascript leb128 nodejs phi standalone unary uuencode
Last synced: 3 months ago
JSON representation
A collection of classes for data representation from Base16 (hex) to Base2048 written in JavaScript.
- Host: GitHub
- URL: https://github.com/umamiappearance/baseexjs
- Owner: UmamiAppearance
- License: mit
- Created: 2021-08-19T20:43:09.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-07-09T11:49:43.000Z (11 months ago)
- Last Synced: 2025-02-26T13:39:14.728Z (3 months ago)
- Topics: base16, base2048, base32, base58, base64, base85, base91, binary, browser, ecoji, golden-ratio, hex, hexadecimal, javascript, leb128, nodejs, phi, standalone, unary, uuencode
- Language: JavaScript
- Homepage:
- Size: 2.27 MB
- Stars: 12
- Watchers: 1
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# BaseEx
[](./LICENSE)
[](https://www.npmjs.com/package/base-ex)
**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 **Ex**ponent (of n) or - as read out loud - for an **X**.
### Available converters/charsets:
converter
(external links)
charsets
(as required as argument)
standalone builds
>> CDN links
Base1/Unary
- all
- sequence
- default
- tmark
Base16
- default
Base32
- crockford
- rfc3548
- rfc4648
- zbase32
Base58
- default
- bitcoin
- flickr
Base64
- standard
- urlsafe
UUencode
- default
- original
- xx
Base85
- adobe
- ascii85
- rfc1924 (charset only)
- z85
Base91
- default
LEB128
- default
- hex
Ecoji
- emojis_v1
- emojis_v2
Base2048
- default
SimpleBase
(Base2-Base62)
- default
BasePhi (Golden Ratio Base)
- default
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
- base2
- ⋮
- base36
- ⋮
- base62
(complete builds)
_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](./CDN.md).
_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
propertyarguments
endiannessbele
paddingnopadpad
signunsignedsigned
caselowerupper
charset<various>
number-modenumber
decimal-modedecimal
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).