Compact

Small, shared-schema state encoded as a URL-safe string.

Compact packs structured values into a length-prefixed bitstream. Both endpoints keep the application schema in code: what each section means, which values it contains, and how to interpret them. The token carries the values and the structural information needed to separate them, rather than repeating field names or an application-level type description.

The repository contains implementations in Python, JavaScript, C99, and Fortran 2008, a wire specification, tests, and executable examples. Python and JavaScript encode and decode sections. C and Fortran provide encoders and bitstream/text conversion.

Why I built it

I needed to move structured state through a short, text-only channel. Both ends already knew what the values meant, but sending a verbose representation spent space describing information they already shared. The problem was to preserve the state in a string small enough to carry, and recover it without losing the boundaries between values.

I developed the original format and initial implementation from scratch, without AI assistance or a textbook walkthrough. I had no prior experience designing a serialization format. I started with the problem, worked out how to represent the values, and built the encoding and decoding rules around the constraints.

The central decision was to separate meaning from representation. A flag needs one bit; a small set of choices needs only enough bits to identify a choice. Field names and domain types stay in the application. Lengths and section modes stay in the token so the decoder can recover its structure.

That work is the reason I include Compact in my portfolio: taking an unfamiliar problem, reducing it to concrete rules, and implementing a solution rather than starting from an existing serializer.

The design notes explain those rules and their trade-offs.

A working example

from compact import (
    decode_stream,
    encode_bitfield,
    encode_small_ints,
    encode_text,
    stream,
    to_base64url,
)

code = to_base64url(stream([
    encode_text("NODE-A7F3"),
    encode_small_ints([5, 2, 1], width=3),
    encode_bitfield([True, False, True, True]),
]))

assert code == "A_oE8QnJ6IilqCboxmjHUUuw"

name, choices, flags = decode_stream(code)
assert name.as_text() == "NODE-A7F3"
assert choices.as_ints() == (5, 2, 1)
assert flags.as_bitfield() == (True, False, True, True)

The result is 24 printable characters: 140 stream bits and four right-padding bits. Those numbers include the section and length headers.

Format

Mode	Representation	Typical values
01 FIXED	Equal-width binary chunks, with their width stored once	Text bytes, flags, bounded integers
10 DYNAMIC	Individually length-prefixed binary chunks	Values with different bit widths
11 INTEGER	A sequence of positive-integer prefix codes	Counts and positive integers

Each section contains a mode tag and a length-prefixed body. The sections are concatenated, wrapped with a total bit length, and mapped six bits at a time to the URL-safe alphabet A-Z a-z 0-9 - _.

This is bit packing and omission of application metadata, not a statistical compressor. Smaller output depends on the data and its schema. The size comparison includes named JSON and values-only JSON baselines, with a script to reproduce every number.

See SPEC.md for the bit-level rules and reference vectors.

Implementations

Language	Included functionality	Instructions
Python 3.10+	Encoding, section decoding, schema helpers, CLI	Python
JavaScript	Encoding, section decoding, schema helpers; dependency-free ES module	JavaScript
C99	Encoding and bitstream/text conversion; caller-owned strings	C
Fortran 2008	Encoding and bitstream/text conversion	Fortran

Install and use the implementations from this checkout. The examples do not require a package-registry release.

Python

From the repository root:

python -m pip install -e "./implementations/python[dev]"
python -m pytest implementations/python/tests
python -m compact encode --text "hi"
python -m compact decode BEhcQ0NI

The CLI's encode command prints BEhcQ0NI.

JavaScript

cd implementations/javascript
npm test

import { encodeText, stream, toBase64Url } from "./src/compact.mjs";

const code = toBase64Url(stream([encodeText("hi")]));
console.log(code); // BEhcQ0NI

The module has no runtime dependencies; its tests use Node's built-in test runner. No dependency installation or application build is needed.

C and Fortran

From the repository root, with Make and the corresponding compiler:

make -C implementations/c run
make -C implementations/fortran FC=gfortran run

Each demo prints the six reference tokens. These are encoder examples, not complete decoder test suites.

Verification

Run the shared-vector checker from the repository root:

python tools/check_vectors.py          # Python encoding and semantic decoding
python tools/check_vectors.py --all    # Also JavaScript, C, and Fortran
python tools/size_comparison.py --check

The --all command requires Node, Make, a C99 compiler, and gfortran. It compares native-demo output against the shared vectors instead of relying on a successful build alone. Python and JavaScript also verify the decoded values, not just the number of sections.

The existing language-specific tests remain in their implementation directories. The input contract describes the supported input profile, empty-section behavior, numeric ranges, and validation boundaries.

Repository layout

implementations/
  python/       Codec, CLI, tests, and command-line examples
  javascript/   ES module and tests
  c/            C99 encoder and demo
  fortran/      Fortran 2008 encoder and demo
docs/           Design, input contract, and measured size examples
tests/          Shared reference vectors
tools/          Vector verification and size-comparison scripts
SPEC.md         Wire format

License

The implementations are MIT-licensed. See LICENSE. The specification retains its CC0 notice.