octify/README.md

Base8 Encoder

# Octify - Base8 Encoder

**Octify** is a JavaScript library that transforms any data into a numerical string, optionally applying **compression** to reduce the size of the encoded data.

## Features

- **Encodes** strings and objects into a compact, custom string format made of 8 number characters.
- **Optional compression** using the **Deflate** algorithm (via the **Pako** library).
- **Decodes** the data back into its original form with or without decompression.
- Full **UTF-8** charset support, including all alphabets and most emogis.
- Runs on the **Browser** and in **NodeJS**.

## Usage

### `encode(data, compression = true)`

Encodes a string, object, number or boolean into a custom compact string format. Optionally compresses the data.

#### Parameters:
- `data` (string | object | number | boolean): The data to encode (either a string or an object).
- `compression` (boolean, default `true`): Whether to apply compression. If set to `false`, no compression is applied.

#### Returns:
- A string representing the encoded data.

#### Example:

```js
const { encode } = require('octify');

// Encoding an object with compression (default)
const obj = { age: 30, text: "Hi, I'm John a computer engineer."};
const encodedData = encode(obj);
console.log(encodedData); // "01360470526254224230236252544144154640242124222532120242544244744620650242740250636252740624637202462202502206346361321201332213344220633273730226232132644246524012000532152040734"

// Encoding a string without compression
const str = "Hello, World!";
const encodedDataNoCompression = encode(str, false);
console.log(encodedDataNoCompression); // "0036047074622063262262265624202063613724223420110176474010324"
```

### `decode(data)`

Decodes a custom encoded string back into its original form. Handles decompression if the data was compressed during encoding.

#### Parameters:
- `data` (string): The encoded string to decode.

#### Returns:
- The decoded data (string | object | number | boolean).

#### Example:

```js
const { decode } = require('octify');

// Decoding compressed encoded data
const encodedData = "0036047074622063262262265624202063613724223420110176474010324";
const decodedData = decode(encodedData);
console.log(decodedData); // "Hello, World!"

```

## Compression Details

**Octify** uses **Deflate** compression via the **Pako** library to optionally compress the data, which can help reduce the size of the encoded data, especially for large datasets. However, for small datasets, compressing the data might actually result in a larger output due to the compression overhead. For that reason, compression is always disabled on number and boolean.

## Encoding Details

Octify encodes data using only 8 unique digits, effectively performing base8 encoding. While it attempts to skip repeated bits during encoding, you can expect the output to be significantly larger than the original data. In the worst-case scenario, the output may be more than four times the size of the input.

## API

### `encode(data, compression = true)`

Encodes the input data into a custom compact string format with optional compression.

- **Parameters**:
  - `data` (string | object | number | boolean): The data to encode.
  - `compression` (boolean, default `true`): Whether to apply compression.
  
- **Returns**: A string representing the encoded data.

### `decode(data)`

Decodes the custom encoded string back into its original form, with optional decompression.

- **Parameters**:
  - `data` (string): The encoded string.
  
- **Returns**: The decoded data (string | object | number | boolean).