Wrapper for lz-string C++ Library • lzstring

The goal of lzstring-r is to provide an R wrapper for the lz-string C++ library. lz-string is originally a JavaScript library that provides string compression and decompression using an LZ-based algorithm.

Credit goes to Winston Chang for spotting this missing R package and guiding me over at the R Shinylive repo—check out his awesome contributions which this repo is based on here and here. Also, shoutout to Andy Kras for his implementation in C++ of lzstring, which you can find right here, and pieroxy, the original brain behind lzstring in JavaScript—peek at his work over here.

Installation

You can install the released version of lzstring from CRAN with:

install.packages("lzstring")

Or the development version from GitHub:

# install.packages("devtools")
devtools::install_github("parmsam/lzstring-r")

Usage

Basic Example

library(lzstring)

# Text data
message <- "The quick brown fox jumps over the lazy dog!"
compressed <- lzstring::compressToBase64(message)
compressed
#> [1] "CoCwpgBAjgrglgYwNYQEYCcD2B3AdhAM0wA8IArGAWwAcBnCTANzHQgBdwIAbAQwC8AnhAAmmAOYBCIA"

decompressed <- lzstring::decompressFromBase64(compressed)
cat(decompressed)
#> The quick brown fox jumps over the lazy dog!

Compressing and Decompressing JSON

json_data <- list(name = "John Doe", age = 30, email = "john.doe@example.com")
json_string <- jsonlite::toJSON(json_data)

compressed <- lzstring::compressToBase64(json_string)
compressed
#> [1] "N4IgdghgtgpiBcBtEApA9gCzAAgCJrgF0AaECAcziQGYAGEkGKCASwBsFkArTMAOgAmBAAIwAHtAAObGHwDGaKCEIBfIA==="

decompressed <- lzstring::decompressFromBase64(compressed)
identical(json_string, decompressed)
#> [1] FALSE
cat(decompressed)
#> {"name":["John Doe"],"age":[30],"email":["john.doe@example.com"]}

Round-Trip for Complex R Objects

Note: Always serialize complex R objects (lists, data frames, etc.) to JSON before compressing. After decompression, deserialize back to R.

obj <- list(a = 1, b = "text", c = list(x = 1:3))
json <- jsonlite::serializeJSON(obj)
lz <- lzstring::compressToBase64(json)
json2 <- lzstring::decompressFromBase64(lz)
obj2 <- jsonlite::unserializeJSON(json2)
identical(obj, obj2) # TRUE
#> [1] TRUE

R Code Example

r_code <- '
library(dplyr)

data <- data.frame(
  name = c("John", "Jane", "Jake"),
  age = c(28, 22, 32),
  salary = c(50000, 60000, 55000)
)

# Filter data for age greater than 25
filtered_data <- filter(data, age > 25)

# Add a new column with updated salary
data <- mutate(data, updated_salary = salary * 1.05)
'
compressed <- lzstring::compressToBase64(r_code)
compressed
#> [1] "FAGwlgRgTghlCeAKAJgBxPKBKYxkwBcYACAHgFpj8iA6AM1gFsBTRYY4gOxheIF5iAY0QAiAFIB7ABacRAGmLiYnZvMViYAa1VY57YjADmzfkMQAmABwLz5hQGZzu/QGcYIOPFPCArAAYAvwUANkCg4h9/AJwcYABiYgAxMBACZigqQhI6CQyjE0MoZkJ04gIpZWJzH2A6FLSi5AB9ahIKYjrU9JQshXziAD4qn1iEgEFkZAMuZgB3IQkQAFdGTmJZsHLiJdRqZim3DwQ8LLJKRiWiNJ6iBR295sPPUyeEYgAqYgBGGj8R4CAA=="
decompose <- lzstring::decompressFromBase64(compressed)
cat(decompose)
#> 
#> library(dplyr)
#> 
#> data <- data.frame(
#>   name = c("John", "Jane", "Jake"),
#>   age = c(28, 22, 32),
#>   salary = c(50000, 60000, 55000)
#> )
#> 
#> # Filter data for age greater than 25
#> filtered_data <- filter(data, age > 25)
#> 
#> # Add a new column with updated salary
#> data <- mutate(data, updated_salary = salary * 1.05)

Compress Shinylive Hashes

code <- 'library(shiny)
ui <- fluidPage(
  "Hello, world!"
)
server <- function(input, output, session) {
}
shinyApp(ui, server)'
files <- list(
  name = jsonlite::unbox("app.R"),
  content = jsonlite::unbox(code)
)
files_json <- jsonlite::toJSON(list(files))
files_lz <- lzstring::compressToEncodedURIComponent(as.character(files_json))
cat(paste0("https://shinylive.io/r/app/#code=", files_lz))
#> https://shinylive.io/r/app/#code=NobwRAdghgtgpmAXGKAHVA6ASmANGAYwHsIAXOMpMAGwEsAjAJykYE8AKAZwAtaJWAlAB0IAV1oACADwBaCQDNq4gCYAFKAHM47ERIlCwACTjVqRXBIDuRRtWUBCAyOEROcRgDd30ufNEQCUloSdj5UUVILIgjwyIk3Tk5giAEJEBEAXxEePlYAQXR2cQs3T3cBMAyAXSA

Decompress Shinylive Hashes

x <- lzstring::decompressFromEncodedURIComponent("NobwRAdghgtgpmAXGKAHVA6VBPMAaMAYwHsIAXOcpMAMwCdiYACAZwAsBLCbDOAD1R04LFkw4xUxOmTERUAVzJ4mQiABM4dZfI4AdCPp0YuCsgH0WAGw4a6ACl2RHyxwDlnTAAzKAjJ+9MAEyeAJT64RAAAqq2GBR8ZPoaNExkCXYhiPpMOSpwZPJ0EEw0jhAAVIFioiAmihgQGUzlQQC+jvpgrQC6QA")
y <- jsonlite::fromJSON(x)
cat(y$name)
#> app.py
cat(y$content)
#> from shiny.express import input, render, ui
#> 
#> ui.input_slider("n", "N", 0, 100, 20)
#> 
#> 
#> @render.text
#> def txt():
#>     return f"n*2 is {input.n() * 2}"

Encoding and Limitations

lzstring operates on strings. For non-string or binary data, encode as JSON or base64 first.
Always ensure your input is UTF-8 encoded.
If you compress an R object directly (without serialization), the result may not decompress as expected.

Troubleshooting

Why do I get an empty string after decompressing?
This may happen if the input was not properly encoded, or if the compressed string is corrupted.
Why does my decompressed JSON fail to parse?
Ensure you serialize your R object to JSON (or use serializeJSON) before compressing.
Can I compress binary data?
Encode it as base64 or hex first, then compress the resulting string.

Use Cases

Sharing Shiny app code via URL (see Shinylive)
Compact storage of large JSON blobs
Embedding compressed data in web apps
Automatic Shinylive links in documentation:
The roxy.shinylive package uses lzstring to provide a roxygen2 extension that automatically takes the code from the @examples tag and creates a URL to the shinylive.io service. During documentation build, a new section is added to the function manual containing the link and an iframe to the application itself.

lzstring