Skip to content

Latest commit

 

History

History
67 lines (42 loc) · 2.75 KB

Readme.md

File metadata and controls

67 lines (42 loc) · 2.75 KB
Raw

smol-string Zig Lib TS Lib

smol-string is a compression library designed for use with browsers' localStorage (and sessionStorage). It serves as a faster alternative to lz-string.

The library is composed of a core algorithm written in Zig and compiled to WebAssembly, wrapped in an easy to use TypeScript library.

Installation

npm install -S smol-string

Usage

import { compress, decompress } from "smol-string";

const input = "Any JS String";

const compressed = compress(input);
const decompressed = decompress(compressed);

An async version offloading the processing to a webworker is also available. API is identical, except that each function returns a promise:

import { compress, decompress } from "smol-string/worker";

const input = JSON.stringify({ imagine: "this is a large object" });

const compressed = await compress(input);
const decompressed = await decompress(compressed);

Build

zig build         # Builds the wasm modules to `zig-out/lib/` by default.
cd ts-lib
npm ci            # Installs dependencies.
npm run wasm-opt  # (Optional) Run wasm-opt on the wasm module generated by zig and copies it for the TS library. 
                  #   Only needed if you made changes to the zig library.
npm run build     # Builds the Typescript library to `ts-lib/dist`.

Comparison to lz-string

Performance

Here are some benchmark results comparing smol-string to lz-string in Chrome. You can run them yourself by visiting https://senryoku.github.io/smol-string/bench.

image

image

image

UTF-16 Compatibility

lz-string offers multiple output formats, including one producing only valid UTF-16 strings. This was done to ensure compatibility with localStorage in all browsers.

However, this was never an issue in all my testing, regardless of the browser. I chose to simplify the API and only kept a single pair of compress/decompress functions that can produce technically invalid UTF-16 strings. The library was originally written with this constraint in mind, meaning it would be trivial to introduce such constraints back in the future if needed.