https://github.com/senryoku/smol-string

Compression for browsers' localStorage. Alternative to lz-string written in Zig.
https://github.com/senryoku/smol-string

browser compression localstorage typescript web zig

Last synced: 2 days ago
JSON representation

Compression for browsers' localStorage. Alternative to lz-string written in Zig.

• Host: GitHub
• URL: https://github.com/senryoku/smol-string
• Owner: Senryoku
• License: mit
• Created: 2023-10-31T06:25:03.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-11-10T08:15:16.000Z (3 months ago)
• Last Synced: 2025-02-19T01:11:57.958Z (2 days ago)
• Topics: browser, compression, localstorage, typescript, web, zig
• Language: Zig
• Homepage: https://senryoku.github.io/smol-string/
• Size: 5.5 MB
• Stars: 40
• Watchers: 2
• Forks: 1
• Open Issues: 1
• Metadata Files:
  • Readme: Readme.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

        
# smol-string [![Zig Lib](https://github.com/Senryoku/smol-string/actions/workflows/zig.yml/badge.svg)](https://github.com/Senryoku/smol-string/actions/workflows/zig.yml) [![TS Lib](https://github.com/Senryoku/smol-string/actions/workflows/ts-lib.yml/badge.svg)](https://github.com/Senryoku/smol-string/actions/workflows/ts-lib.yml)

`smol-string` is a compression library designed for use with browsers' `localStorage` (and `sessionStorage`). It serves as a faster alternative to [`lz-string`](https://github.com/pieroxy/lz-string).

The library is composed of a core algorithm written in [Zig](https://ziglang.org/) and compiled to WebAssembly, wrapped in an easy to use TypeScript library.

## Installation

```

npm install -S smol-string

```

## Usage

```ts

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:

```ts

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

```sh

zig build         # Builds the wasm modules to `zig-out/lib/` by default.

```

```sh

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](https://github.com/Senryoku/smol-string/assets/1338143/20df3f76-959a-428b-8c50-c8f9fbcf1020)

![image](https://github.com/Senryoku/smol-string/assets/1338143/38d7ca8a-7ef5-4516-b5c1-02db2cdae6b7)

![image](https://github.com/Senryoku/smol-string/assets/1338143/235683f0-75e8-4c4c-a2e1-2b89e50cc549)

### 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.