triepack v1.1.0

A compressed trie-based dictionary format for fast, compact key-value storage.

TriePack encodes dictionaries into a compact binary format (.trp) optimized for fast lookups, prefix search, and ROM-safe deployment. It uses prefix sharing and bit-level packing with configurable symbol encoding and full value type support.

Features

• Compact binary format — compressed tries with prefix sharing and bit-level packing
• Fast lookups — O(key-length) point queries via skip pointers
• Prefix search — iterate all keys matching a prefix
• Fuzzy search — find keys within edit distance d<=2
• ROM-safe — readers work directly on const buffers with zero allocation
• Typed values — null, bool, int, uint, float, double, string, blob, array, nested dict
• JSON support — encode/decode JSON documents to/from .trp format
• 10 languages — C core with native implementations across 9 additional languages
• Small footprint — C static library under 235 KB; bindings are 874-1,672 source lines each

Supported Languages

All bindings are native implementations that read/write the .trp binary format directly (no FFI).

Language	Type	Source Lines	Binary/Library Size	Notes
C	Core library	4,169	~235 KB (static, 64-bit)	C99, 32-bit and 64-bit, ROM-safe
C++	Wrapper	369	~51 KB (static)	C++11 RAII wrappers over C core
Python	Binding	874	pure source	No dependencies
JavaScript	Binding	1,052	pure source	Node.js and browser
TypeScript	Binding	49	pure source	Type-safe wrapper over JS
Go	Binding	1,239	pure source	No dependencies
Rust	Binding	1,672	pure source	No dependencies, no unsafe
Swift	Binding	1,092	pure source	SPM package
Kotlin	Binding	1,079	pure source	Kotlin/JVM, Gradle
Java	Binding	1,485	pure source	Java 11+, Gradle

Quick Start

C / C++

# Install
git clone https://github.com/deftio/triepack.git
cd triepack
cmake -B build -DBUILD_TESTS=ON -DBUILD_JSON=ON
cmake --build build
ctest --test-dir build --output-on-failure

#include "triepack/triepack.h"

tp_encoder *enc = NULL;
tp_encoder_create(&enc);
tp_value v = tp_value_int(42);
tp_encoder_add(enc, "hello", &v);
uint8_t *buf = NULL;  size_t len = 0;
tp_encoder_build(enc, &buf, &len);

tp_dict *dict = NULL;
tp_dict_open(&dict, buf, len);
tp_value val;
if (tp_dict_lookup(dict, "hello", &val) == TP_OK)
    printf("hello -> %lld\n", (long long)val.data.int_val);
tp_dict_close(&dict);
tp_encoder_destroy(&enc);
free(buf);

Python

# Install (from source, PyPI package coming soon)
cd bindings/python
pip install -e .

from triepack import encode, decode

buf = encode({"hello": 42, "world": "foo"})
result = decode(buf)
print(result)  # {'hello': 42, 'world': 'foo'}

JavaScript

# Install (from source, npm package coming soon)
cd bindings/javascript
npm install

const { encode, decode } = require('./src/index');

const buf = encode({ hello: 42, world: 'foo' });
const result = decode(buf);
console.log(result);  // { hello: 42, world: 'foo' }

TypeScript

cd bindings/typescript
npm install

import { encode, decode } from './src/index';

const buf = encode({ hello: 42, world: 'foo' });
const result = decode(buf);

Go

# Copy bindings/go/ into your project
cp -r bindings/go/triepack your_project/

data := map[string]interface{}{"hello": 42, "world": "foo"}
buf, _ := triepack.Encode(data)
result, _ := triepack.Decode(buf)

Rust

# Add to Cargo.toml (from source, crates.io coming soon)
# [dependencies]
# triepack = { path = "bindings/rust" }

use triepack::{encode, decode, Value};
use std::collections::HashMap;

let mut data = HashMap::new();
data.insert("hello".into(), Value::UInt(42));
let buf = encode(&data).unwrap();
let result = decode(&buf).unwrap();

Swift

# Add to Package.swift dependencies
# .package(path: "bindings/swift")

import Triepack

let data: [String: TriepackValue] = ["hello": .uint(42)]
let buf = try Triepack.encode(data)
let result = try Triepack.decode(buf)

Kotlin

# Add bindings/kotlin/ to your Gradle project
cd bindings/kotlin
./gradlew test

import com.deftio.triepack.*

val data = mapOf("hello" to TpValue.UInt(42))
val buf = encode(data)
val result = decode(buf)

Java

# Add bindings/java/ to your Gradle project
cd bindings/java
./gradlew test

import com.deftio.triepack.*;

Map<String, TpValue> data = new LinkedHashMap<>();
data.put("hello", TpValue.ofUInt(42));
byte[] buf = TriePack.encode(data);
Map<String, TpValue> result = TriePack.decode(buf);

See Examples for more detailed usage including JSON round-trips, file I/O, and cross-language interop.

Library Stack

triepack_json          (JSON encode/decode)
    |
triepack_core          (trie codec: encoder, dictionary, iterator)
    |
triepack_bitstream     (bit-level I/O, VarInt, UTF-8)

Each layer can be used independently. triepack_wrapper provides C++11 RAII wrappers over all three.

Build Options

Option	Default	Description
BUILD_TESTS	ON	Build test suite
BUILD_EXAMPLES	ON	Build example programs
BUILD_JSON	ON	Build JSON library
BUILD_DOCS	OFF	Build Doxygen documentation
ENABLE_COVERAGE	OFF	Enable code coverage instrumentation

File Format

• Magic bytes: TRP\0 (0x54 0x52 0x50 0x00)
• File extension: .trp
• 32-byte fixed header
• Two-trie architecture with configurable addressing modes
• CRC32/SHA256/xxHash64 integrity checking

See docs/internals/ for format details.

Documentation

• Getting Started
• Building
• API Reference
• Examples
• Testing
• Release Process

Project Status

v1.1.0 released. Core C library (bitstream, trie codec, JSON), C++ wrappers, and 8 language bindings (Python, JavaScript, TypeScript, Go, Rust, Swift, Kotlin, Java) are implemented. C/C++, Python, and JavaScript maintain 100% line coverage. 27 C/C++ test programs, 97 Python tests, 99 JavaScript tests, 75 Rust tests, 27 Swift tests, plus Go, Kotlin, and Java test suites.

Roadmap

v1.1 — Client Libraries

• TypeScript binding (wraps JS implementation)
• Go binding
• Swift binding (with SPM package)
• Rust binding (with crate on crates.io)
• Kotlin binding
• Java binding
• npm package for JavaScript/TypeScript
• PyPI package for Python

v1.2 — Format Enhancements

• Suffix table (shared ending compression)
• Huffman symbol encoding (for large dictionaries)
• Nested dict values (embed sub-dictionaries inline)

v1.3 — Tooling & Ecosystem

• trp CLI: encode/decode/validate/inspect
• Fuzzy search (edit distance d<=2)
• Performance benchmarks across languages
• Language binding conformance test suite

License

BSD-2-Clause. See LICENSE.txt.

Copyright (c) 2026 M. A. Chatterjee