Compact encoding

compact-encoding packages small binary codecs behind a shared encoder interface. It is commonly paired with Protomux message schemas and shows up in Hypercore and other Holepunch protocol surfaces whenever structured binary payloads matter. For the upstream package and implementation details, see the compact-encoding repository.

Install

npm i compact-encoding

Quickstart

import cenc from 'compact-encoding'

const state = cenc.state()

cenc.uint.preencode(state, 42)
cenc.string.preencode(state, 'hello')

state.buffer = Buffer.allocUnsafe(state.end)
state.start = 0

cenc.uint.encode(state, 42)
cenc.string.encode(state, 'hello')

state.start = 0

console.log(cenc.uint.decode(state))
console.log(cenc.string.decode(state))

API Reference

Encoder contract

Every bundled encoder follows the same three-method contract. The top-level helpers and exported factories below all return or consume objects with this shape.

enc.preencode(state, value)

API definition on GitHub

• Signature: enc.preencode(state, value) (GitHub)
• Parameters: state is the mutable encoding state object. value is the value that will later be encoded. (GitHub)
• Returns: Nothing. It updates state.end so you know how large the output buffer must be. (GitHub)
• Example:

const state = cenc.state()
cenc.uint.preencode(state, 42)
console.log(state.end)

enc.encode(state, value)

API definition on GitHub

• Signature: enc.encode(state, value) (GitHub)
• Parameters: state is a state object with buffer set. value is the value to encode. (GitHub)
• Returns: Nothing. It writes into state.buffer at state.start and advances state.start. (GitHub)
• Example:

const state = cenc.state()
cenc.uint.preencode(state, 42)
state.buffer = Buffer.allocUnsafe(state.end)
cenc.uint.encode(state, 42)

const value = enc.decode(state)

API definition on GitHub

• Signature: const value = enc.decode(state) (GitHub)
• Parameters: state is a state object whose buffer contains encoded bytes. (GitHub)
• Returns: The decoded value. state.start advances past the consumed bytes. (GitHub)
• Example:

const state = cenc.state(0, buffer.byteLength, buffer)
const value = cenc.uint.decode(state)

State and convenience helpers

const state = cenc.state([start], [end], [buffer])

API definition on GitHub

• Signature: const state = cenc.state([start], [end], [buffer]) (GitHub)
• Parameters: start defaults to 0, end defaults to 0, and buffer defaults to null. (GitHub)
• Returns: A mutable state object { start, end, buffer } used by all encoders. (GitHub)
• Example:

const state = cenc.state()

const buffer = cenc.encode(enc, value)

API definition on GitHub

• Signature: const buffer = cenc.encode(enc, value) (GitHub)
• Parameters: enc is any compact encoder. value is the value to serialize. (GitHub)
• Returns: A freshly allocated buffer containing the encoded value. (GitHub)
• Example:

const buffer = cenc.encode(cenc.bool, true)

const value = cenc.decode(enc, buffer)

API definition on GitHub

• Signature: const value = cenc.decode(enc, buffer) (GitHub)
• Parameters: enc is any compact encoder. buffer is the encoded byte sequence. (GitHub)
• Returns: The decoded value. (GitHub)
• Example:

const value = cenc.decode(cenc.bool, buffer)

const enc = cenc.from(encLike)

API definition on GitHub

• Signature: const enc = cenc.from(encLike) (GitHub)
• Parameters: encLike can be an existing compact encoder, a named raw string encoding such as 'utf8' or 'json', a codec with encode/decode, or an abstract encoding with encodingLength. (GitHub)
• Returns: A compact-encoding-compatible encoder object. (GitHub)
• Example:

const enc = cenc.from('utf8')
const buffer = cenc.encode(enc, 'hello')

Encoder factories

const enc = cenc.fixed(length)

API definition on GitHub

• Signature: const enc = cenc.fixed(length) (GitHub)
• Parameters: length is the exact byte length that every encoded value must have. (GitHub)
• Returns: An encoder for fixed-size buffers. (GitHub)
• Example:

const keyEncoding = cenc.fixed(32)

const enc = cenc.array(itemEncoding)

API definition on GitHub

• Signature: const enc = cenc.array(itemEncoding) (GitHub)
• Parameters: itemEncoding is the encoder used for each array element. (GitHub)
• Returns: An encoder that prefixes arrays with their length and encodes each item in order. (GitHub)
• Example:

const listEncoding = cenc.array(cenc.string)
const buffer = cenc.encode(listEncoding, ['a', 'b'])

const enc = cenc.frame(innerEncoding)

API definition on GitHub

• Signature: const enc = cenc.frame(innerEncoding) (GitHub)
• Parameters: innerEncoding is the payload encoding to wrap. (GitHub)
• Returns: An encoder that prefixes one encoded payload with its byte length. (GitHub)
• Example:

const framed = cenc.frame(cenc.string)

const enc = cenc.record(keyEncoding, valueEncoding)

API definition on GitHub

• Signature: const enc = cenc.record(keyEncoding, valueEncoding) (GitHub)
• Parameters: keyEncoding encodes object keys and valueEncoding encodes object values. (GitHub)
• Returns: An encoder for plain object records. (GitHub)
• Example:

const headerEncoding = cenc.record(cenc.string, cenc.string)

cenc.stringRecord

API definition on GitHub

• Returns: A prebuilt record(cenc.string, cenc.string) encoder for simple string maps. (GitHub)

Numeric encodings

cenc.uint, cenc.uint8, cenc.uint16, cenc.uint24, cenc.uint32, cenc.uint40, cenc.uint48, cenc.uint56, cenc.uint64

API definition on GitHub

• Returns: Unsigned integer encoders. cenc.uint chooses a compact size automatically; the fixed-width variants always use the named byte width. (GitHub)
• Example:

const port = cenc.encode(cenc.uint16, 8080)

cenc.int, cenc.int8, cenc.int16, cenc.int24, cenc.int32, cenc.int40, cenc.int48, cenc.int56, cenc.int64

API definition on GitHub

• Returns: Signed integer encoders built on top of the unsigned variants with ZigZag encoding. (GitHub)
• Example:

const delta = cenc.encode(cenc.int, -12)

cenc.biguint64, cenc.bigint64, cenc.biguint, cenc.bigint

API definition on GitHub

• Returns: BigInt-aware integer encoders for fixed-width or variable-width large integer values. (GitHub)
• Example:

const buffer = cenc.encode(cenc.biguint64, 42n)

cenc.float32, cenc.float64

API definition on GitHub

• Returns: Floating-point encoders using IEEE-754 little-endian layouts. (GitHub)
• Example:

const sample = cenc.encode(cenc.float32, 3.14)

cenc.lexint

API definition on GitHub

• Returns: The exported lexicographic integer encoder family from the ./lexint module. (GitHub)

Binary, buffer, and typed-array encodings

cenc.buffer, cenc.optionalBuffer, cenc.binary

API definition on GitHub

• Returns: Buffer-oriented encoders. buffer length-prefixes a byte sequence, optionalBuffer maps zero length to null, and binary accepts either a string or buffer-like input. (GitHub)
• Example:

const payload = cenc.encode(cenc.buffer, Buffer.from('hello'))

cenc.arraybuffer

API definition on GitHub

• Returns: An encoder for ArrayBuffer instances. (GitHub)
• Example:

const encoded = cenc.encode(cenc.arraybuffer, new Uint8Array([1, 2, 3]).buffer)

cenc.uint8array, cenc.uint16array, cenc.uint32array, cenc.int8array, cenc.int16array, cenc.int32array, cenc.biguint64array, cenc.bigint64array, cenc.float32array, cenc.float64array

API definition on GitHub

• Returns: Length-prefixed typed-array encoders that preserve the underlying element type. (GitHub)
• Example:

const encoded = cenc.encode(cenc.uint32array, new Uint32Array([1, 2, 3]))

cenc.fixed32, cenc.fixed64

API definition on GitHub

• Returns: Prebuilt fixed-size buffer encoders for 32-byte and 64-byte values. (GitHub)
• Example:

const key = cenc.encode(cenc.fixed32, Buffer.alloc(32))

Text encodings

cenc.string, cenc.utf8, cenc.ascii, cenc.hex, cenc.base64, cenc.utf16le, cenc.ucs2

API definition on GitHub

• Returns: String encoders for the named text encoding. Each one also exposes .fixed(length) for fixed-size strings. (GitHub)
• Example:

const topic = cenc.encode(cenc.hex.fixed(64), '0123abcd'.repeat(8))

Boolean, date, and structured-value encodings

cenc.bool

API definition on GitHub

• Returns: A one-byte boolean encoder. (GitHub)
• Example:

const encoded = cenc.encode(cenc.bool, true)

cenc.date

API definition on GitHub

• Returns: A Date encoder backed by the signed integer timestamp value from date.getTime(). (GitHub)
• Example:

const encoded = cenc.encode(cenc.date, new Date())

cenc.json, cenc.ndjson

API definition on GitHub

• Returns: UTF-8 JSON encoders. ndjson appends a trailing newline before encoding. (GitHub)
• Example:

const encoded = cenc.encode(cenc.json, { type: 'ping' })

cenc.none

API definition on GitHub

• Returns: A sentinel encoder that always decodes to null and writes no payload bytes. (GitHub)
• Example:

const encoded = cenc.encode(cenc.none, null)

cenc.any

API definition on GitHub

• Returns: A schemaless tagged-value encoder for JSON-like values, arrays, objects, dates, strings, buffers, booleans, integers, and floats. (GitHub)
• Example:

const encoded = cenc.encode(cenc.any, {
  type: 'hello',
  count: 3,
  ok: true
})

Network encodings

cenc.port

API definition on GitHub

• Returns: The same encoder as cenc.uint16, provided for protocol readability when encoding network ports. (GitHub)
• Example:

const encoded = cenc.encode(cenc.port, 49737)

cenc.ipv4, cenc.ipv6, cenc.ip

API definition on GitHub

• Returns: Encoders for IPv4 addresses, IPv6 addresses, or either family with an embedded family tag. (GitHub)
• Example:

const encoded = cenc.encode(cenc.ip, '127.0.0.1')

cenc.ipv4Address, cenc.ipv6Address, cenc.ipAddress

API definition on GitHub

• Returns: Address-object encoders for { host, family?, port } shapes. (GitHub)
• Example:

const encoded = cenc.encode(cenc.ipAddress, {
  host: '127.0.0.1',
  port: 49737
})

Raw variants

cenc.raw

API definition on GitHub

• Returns: A namespace of non-length-prefixed variants for many buffer, string, array, JSON, and typed-array encodings such as cenc.raw.buffer, cenc.raw.utf8, cenc.raw.array(enc), and cenc.raw.json. (GitHub)
• Example:

const encoded = cenc.encode(cenc.raw.utf8, 'hello')

See also

• Protomux — the most common higher-level protocol surface built directly on compact-encoding schemas.
• Hypercore — accepts compact encodings for structured values and message payloads.
• Upstream compact-encoding repository — source, releases, and implementation details.