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.

Module-level encode and decode helpers

const buffer = cenc.encode(enc, value)

Encodes a single value using enc into a freshly allocated Buffer and returns it. Equivalent to manually creating a state, calling enc.preencode and enc.encode, and slicing the buffer — useful when you just want bytes back in one step.

• Returns: Buffer

const buf = cenc.encode(cenc.uint, 42)
// <Buffer 2a>

const value = cenc.decode(enc, buffer)

Decodes a single value from buffer using enc. Equivalent to constructing a state from the buffer and calling enc.decode.

• Returns: The decoded value.

const val = cenc.decode(cenc.uint, buf) // 42

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, val)

Does a fast preencode dry-run that only sets state.end. Use this to figure out how big of a buffer you need.

enc.encode(state, val)

src

Writes the encoded form of the value into state.buffer at state.start (the buffer must have been preallocated via preencode), advancing state.start past the written bytes.

• Returns: Buffer — A newly allocated buffer containing the encoded value.

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.uint, 42)
// buf is a 1-byte Buffer containing the encoded uint

val = enc.decode(state)

src

Reads and returns a value from state.buffer at state.start, advancing state.start past the decoded value.

• Returns: * — The decoded value.

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.bool, true)
const val = cenc.decode(cenc.bool, buf) // true

State and convenience helpers

cenc.state(start = 0, end = 0, buffer = null)

src

A mutable state object { start, end, buffer } used by all encoders.

• Returns: State — A new state object { start, end, buffer }.

const cenc = require('compact-encoding')
const state = cenc.state()
cenc.uint.preencode(state, 42)
cenc.string.preencode(state, 'hi')
state.buffer = Buffer.allocUnsafe(state.end)
cenc.uint.encode(state, 42)
cenc.string.encode(state, 'hi')

cenc.from(enc)

src

Coerces encLike — 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 — into a compact-encoding-compatible encoder object.

• Returns: object — A compact-encoding encoder with preencode, encode, and decode.

const cenc = require('compact-encoding')
const enc = cenc.from('utf-8')
const buf = cenc.encode(enc, 'hello')
const val = cenc.decode(enc, buf) // 'hello'

Encoder factories

cenc.fixed(n)

src

An encoder for fixed-size buffers, where length is the exact byte length every encoded value must have.

• Returns: object — An encoder that reads and writes exactly n bytes.

const cenc = require('compact-encoding')
const enc = cenc.fixed(4)
const buf = cenc.encode(enc, Buffer.alloc(4, 0xff))
const val = cenc.decode(enc, buf) // <Buffer ff ff ff ff>

cenc.array(enc)

src

An encoder that prefixes arrays with their length and encodes each item in order using itemEncoding.

• Returns: object — An encoder for arrays of values handled by enc.

const cenc = require('compact-encoding')
const enc = cenc.array(cenc.uint)
const buf = cenc.encode(enc, [1, 2, 3])
const val = cenc.decode(enc, buf) // [1, 2, 3]

cenc.frame(enc)

src

An encoder that prefixes one encoded payload with its byte length.

• Returns: object — An encoder that wraps each value in a byte-length frame.

const cenc = require('compact-encoding')
const enc = cenc.frame(cenc.string)
const buf = cenc.encode(enc, 'hello')
const val = cenc.decode(enc, buf) // 'hello'

cenc.record(keyEncoding, valueEncoding)

src

An encoder for plain object records, with keyEncoding for object keys and valueEncoding for object values.

• Returns: object — An encoder that reads/writes plain objects as key-value pairs.

const cenc = require('compact-encoding')
const enc = cenc.record(cenc.string, cenc.uint)
const buf = cenc.encode(enc, { a: 1, b: 2 })
const val = cenc.decode(enc, buf) // { a: 1, b: 2 }

cenc.stringRecord

src

A prebuilt record(cenc.string, cenc.string) encoder for simple string maps.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.stringRecord, { name: 'alice', role: 'admin' })
const val = cenc.decode(cenc.stringRecord, buf) // { name: 'alice', role: 'admin' }

Numeric encodings

cenc.uint64

src

Unsigned integer encoders (cenc.uint, cenc.uint8, cenc.uint16, cenc.uint24, cenc.uint32, cenc.uint40, cenc.uint48, cenc.uint56, cenc.uint64). cenc.uint chooses a compact size automatically; the fixed-width variants always use the named byte width.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.uint64, 2 ** 32)
const val = cenc.decode(cenc.uint64, buf) // 4294967296

cenc.int64

src

Signed integer encoders (cenc.int, cenc.int8 … cenc.int64) built on top of the unsigned variants with ZigZag encoding.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.int64, -4294967296)
const val = cenc.decode(cenc.int64, buf) // -4294967296

cenc.bigint

src

BigInt-aware integer encoders (cenc.biguint64, cenc.bigint64, cenc.biguint, cenc.bigint) for fixed-width or variable-width large integer values.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.bigint, -(2n ** 128n))
const val = cenc.decode(cenc.bigint, buf) // -340282366920938463463374607431768211456n

cenc.float64

src

Floating-point encoders (cenc.float32, cenc.float64) using IEEE-754 little-endian layouts.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.float64, Math.PI)
const val = cenc.decode(cenc.float64, buf) // 3.141592653589793

cenc.lexint

src

The exported lexicographic integer encoder family from the ./lexint module.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.lexint, 1000)
const val = cenc.decode(cenc.lexint, buf) // 1000

Binary, buffer, and typed-array encodings

cenc.binary

src

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.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.binary, 'hello')
const val = cenc.decode(cenc.binary, buf) // <Buffer 68 65 6c 6c 6f>

cenc.arraybuffer

src

An encoder for ArrayBuffer instances.

• Returns: object

const cenc = require('compact-encoding')
const ab = new ArrayBuffer(4)
const buf = cenc.encode(cenc.arraybuffer, ab)
const val = cenc.decode(cenc.arraybuffer, buf) // ArrayBuffer { byteLength: 4 }

cenc.float64array

src

Length-prefixed typed-array encoders (cenc.uint8array, cenc.uint16array, cenc.uint32array, cenc.int8array, cenc.int16array, cenc.int32array, cenc.biguint64array, cenc.bigint64array, cenc.float32array, cenc.float64array) that preserve the underlying element type.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.float64array, new Float64Array([Math.PI]))
const val = cenc.decode(cenc.float64array, buf) // Float64Array [3.141592653589793]

cenc.fixed64

src

Prebuilt fixed-size buffer encoders (cenc.fixed32, cenc.fixed64) for 32-byte and 64-byte values.

• Returns: object

const cenc = require('compact-encoding')
const sig = Buffer.alloc(64)
const buf = cenc.encode(cenc.fixed64, sig)
const val = cenc.decode(cenc.fixed64, buf) // <Buffer 00 00 ... (64 bytes)>

Text encodings

cenc.ucs2

src

String encoders for the named text encoding (cenc.string, cenc.utf8, cenc.ascii, cenc.hex, cenc.base64, cenc.utf16le, cenc.ucs2). Each one also exposes .fixed(length) for fixed-size strings.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.ucs2, 'hi')
const val = cenc.decode(cenc.ucs2, buf) // 'hi'

Boolean, date, and structured-value encodings

cenc.bool

src

A one-byte boolean encoder.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.bool, true)
const val = cenc.decode(cenc.bool, buf) // true

cenc.date

src

A Date encoder backed by the signed integer timestamp value from date.getTime().

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.date, new Date('2024-01-01'))
const val = cenc.decode(cenc.date, buf) // Date object for 2024-01-01

cenc.ndjson

src

UTF-8 JSON encoders (cenc.json, cenc.ndjson). ndjson appends a trailing newline before encoding.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.ndjson, { a: 1 })
const val = cenc.decode(cenc.ndjson, buf) // { a: 1 }

cenc.none

src

A sentinel encoder that always decodes to null and writes no payload bytes.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.none, null)
const val = cenc.decode(cenc.none, buf) // null

cenc.any

src

A schemaless tagged-value encoder for JSON-like values, arrays, objects, dates, strings, buffers, booleans, integers, and floats.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.any, { n: 42, flag: true })
const val = cenc.decode(cenc.any, buf) // { n: 42, flag: true }

Network encodings

cenc.port

src

The same encoder as cenc.uint16, provided for protocol readability when encoding network ports.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.port, 8080)
const val = cenc.decode(cenc.port, buf) // 8080

cenc.ip

src

Encoders for IPv4 addresses, IPv6 addresses, or either family with an embedded family tag (cenc.ipv4, cenc.ipv6, cenc.ip).

• Returns: object

const cenc = require('compact-encoding')
const buf4 = cenc.encode(cenc.ip, '1.2.3.4')
cenc.decode(cenc.ip, buf4) // '1.2.3.4'
const buf6 = cenc.encode(cenc.ip, '::1')
cenc.decode(cenc.ip, buf6) // '0:0:0:0:0:0:0:1'

cenc.ipAddress

src

Address-object encoders (cenc.ipv4Address, cenc.ipv6Address, cenc.ipAddress) for { host, family?, port } shapes.

• Returns: object

const cenc = require('compact-encoding')
const buf = cenc.encode(cenc.ipAddress, { host: '1.2.3.4', port: 8080 })
const val = cenc.decode(cenc.ipAddress, buf) // { host: '1.2.3.4', family: 4, port: 8080 }

Raw variants

cenc.raw

src

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.

• Returns: object

const cenc = require('compact-encoding')
// copy raw bytes into state
const buf = Buffer.from([1, 2, 3])
const state = cenc.state()
cenc.raw.preencode(state, buf)
state.buffer = Buffer.allocUnsafe(state.end)
cenc.raw.encode(state, buf)

Types

State

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.