lz4

Kind	ffi-c
Capabilities	ffi
Categories	compression ffi
Keywords	lz4 compression fast real-time

LZ4 fast compression library bindings for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`c/kit_lz4.c`	C FFI wrapper
`c/kit_lz4.h`	C header for FFI wrapper
`examples/basic.kit`	Basic usage example
`kit.toml`	Package manifest with metadata and dependencies
`src/lz4.kit`	Kit LZ4 - Fast compression library bindings
`tests/lz4.test.kit`	Tests for lz4

Dependencies

No Kit package dependencies.

Installation

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

System Requirements

Platform	Command
macOS	`brew install lz4`
Ubuntu	`sudo apt install liblz4-dev`
Fedora	`sudo dnf install lz4-devel`

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 ("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 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

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit

Compile examples to a native binary:

kit build examples/basic.kit && ./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:

Format and check source files in src/
Run tests in tests/ with coverage

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.

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, which prepend the original size as a 4-byte header.

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:

Int -> 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())}"