Skip to content

Latest commit

 

History

History
175 lines (118 loc) · 4.85 KB

README.md

File metadata and controls

175 lines (118 loc) · 4.85 KB

lzbase62

NPM Version GitHub Actions Build Status Bundle Size (minified) GitHub License

lzbase62 is a JavaScript library that compresses strings into ASCII strings composed solely of base62 (0-9, a-z, A-Z) characters, using the LZ77 based original algorithm.

It can compress and decompress any Unicode string that JavaScript can handle.

This can be particularly useful when storing large amounts of data in storage with size limitations, such as localStorage or cookies. And, since the compressed strings are composed solely of base62 characters, they can be used as string parameters, like GET parameters, without the risk of control characters or symbols.

Installation

npm

npm install --save lzbase62

Using ES6 import

import lzbase62 from 'lzbase62';

Using CommonJS require

const lzbase62 = require('lzbase62');

Browser (standalone)

You can install the library via npm or download it from the release list. Use the lzbase62.js or lzbase62.min.js files included in the package.
*Please note that if you use git clone, even the master branch may be under development.

<script src="lzbase62.js"></script>

or the minified lzbase62.min.js:

<script src="lzbase62.min.js"></script>

When the script is loaded, the lzbase62 object is defined in the global scope (i.e., window.lzbase62).

Usage

Example of compressing and decompressing a string:

const data = 'hello hello hello';
console.log(data.length); // 17

const compressed = lzbase62.compress(data);
console.log(compressed); // 'tYVccfxGM'
console.log(compressed.length); // 9

const decompressed = lzbase62.decompress(compressed);
console.log(decompressed); // 'hello hello hello'
console.log(decompressed === data); // true

Demo

API


lzbase62.compress(data, [options])

Compresses data into a base62 [0-9a-zA-Z] encoded string.

Parameters

  • data (string) : Input data
  • [options] (object) : Compression options
    • onData (function (chunk: string) {}) : Called when a data is chunked
    • onEnd (function () {}) : Called when process ends

Return value

(string) : Compressed data

Examples

Example of compressing a string:

const compressed = lzbase62.compress('abcabcabcabcabc');
console.log(compressed); // 'tRSTxDM'

Compresses data using onData and onEnd events:

const string = 'hello hello hello';
const compressedChunks = [];

lzbase62.compress(string, {
  onData: (chunk) => {
    compressedChunks.push(chunk);
  },
  onEnd: () => {
    console.log(compressedChunks.join('')); // 'tYVccfxGM'
  }
});

lzbase62.decompress(data, [options])

Decompresses a string that has been compressed with lzbase62.compress().

Parameters

  • data (string) : Input data
  • [options] (object) : Decompression options
    • onData (function (chunk: string) {}) : Called when a data is chunked
    • onEnd (function () {}) : Called when process ends

Return value

(string) : Decompressed data

Examples

Example of decompressing a string that has been compressed with lzbase62.compress():

const decompressed = lzbase62.decompress('tRSTxDM');
console.log(decompressed); // 'abcabcabcabcabc'

Decompress data using onData and onEnd events:

const compressed = 'tYVccfxGM';
const decompressedChunks = [];

lzbase62.decompress(compressed, {
  onData: (chunk) => {
    decompressedChunks.push(chunk);
  },
  onEnd: () => {
    console.log(decompressedChunks.join('')); // 'hello hello hello'
  }
});

Contributing

We welcome contributions from everyone. For bug reports and feature requests, please create an issue on GitHub.

Pull Requests

Before submitting a pull request, please run $ npm run test to ensure there are no errors. We only accept pull requests that pass all tests.

License

This project is licensed under the terms of the MIT license. See the LICENSE file for details.