lz4

LZ4 fast compression library bindings for Kit

Files

Dependencies

No Kit package dependencies.

This package links against the system liblz4 library through Kit's C FFI.

System Requirements

Installation

Install the native system dependency first, then add the Kit package:

kit add gitlab.com/kit-lang/packages/kit-lz4.git

Usage

import Kit.LZ4 as Lz4

main = fn =>
  data = "Hello, World! Hello, World! Hello, World! Hello, World!"
  println ("Original size: " ++ (show (String.length data)))

  # Compress with default settings
  compressed = Lz4.compress data
  println ("Encoded compressed size: " ++ (show (String.length compressed)))

  # Decompress
  match Lz4.decompress compressed
    | Ok decompressed -> println ("Decompressed: " ++ decompressed)
    | Err e -> println ("Error: " ++ e)

  # High-compression mode (smaller output, slower)
  compressed-hc = Lz4.compress-hc data
  println ("HC encoded compressed size: " ++ (show (String.length compressed-hc)))

  # Estimate maximum compressed size
  max-size = Lz4.max-compressed-size 1024
  println ("Max compressed size for 1KB: " ++ (show max-size))

  # Library version
  println ("LZ4 version: " ++ (show Lz4.version))

main

Payload Format

compress and compress-hc return hex-encoded strings. The decoded payload starts with a 4-byte little-endian original-size header followed by the LZ4-compressed bytes. This keeps compressed data safe across Kit's string-based FFI boundary, where raw NUL bytes would otherwise truncate data.

String.length on a compressed value reports the encoded string length, not the raw compressed byte count.

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit --allow=ffi

Compile examples to a native binary:

kit build examples/basic.kit --allow=ffi && ./basic

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Rebuild libkit_lz4.dylib if native sources changed
2. Format and check Kit source files
3. Run tests in tests/ with coverage

Running Parity

Compare interpreter and compiled example output:

kit parity --no-spinner --failures-only

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/lz4/, making it available for import as Kit.LZ4 in other projects. It also rebuilds the installed native library, which matters for compiled examples because they link against the installed package dylib.

License

This package is released under the MIT License - see LICENSE for details.

LZ4 is released under the BSD 2-Clause License.

Exported Functions & Types

compress

Compress a string using LZ4 default (fastest) compression.

Parameters:

Returns:

String -> String

compressed = compress "Hello, World!"

decompress

Decompress an LZ4-compressed string.

The input must have been compressed with compress or compress-hc. Compressed payloads are hex-encoded so they can safely travel through Kit strings.

Parameters:

Returns:

String -> Result String String

match decompress compressed-data
  | Ok original -> println original
  | Err e -> println "Decompression failed: ${e}"

compress-hc

Compress a string using LZ4 high-compression mode.

Produces better compression ratios than compress but is slower. The output is compatible with decompress.

Parameters:

Returns:

String -> String

compressed = compress-hc "Hello, World!"

max-compressed-size

Calculate the maximum compressed size for a given input size.

This is useful for pre-allocating buffers. The actual compressed size will typically be smaller.

Parameters:

Returns:

NonNegativeInt -> Int

max-size = max-compressed-size 1024
println "Max compressed size for 1KB: ${max-size}"

version

Get the LZ4 library version number.

Returns:

Int

println "LZ4 version: ${show version}"