package
Random-access struct encoding/decoding as an extensible class for msgpackr, cbor-x, and compatible encoders
npm install structonGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Estimated unpacked size across 1 packages.
259.2 kB
Includes dependencies.
Random-access struct encoding/decoding as an extensible class for msgpackr, cbor-x, and compatible binary encoders.
structon extracts the random-access struct functionality from msgpackr's struct.js into a standalone, class-based package. It exposes a createStructon(BaseClass) factory that returns a class extending any compatible encoder. The resulting class encodes top-level plain objects as compact fixed-width structs with lazy-access property getters, while delegating inner nested-object encoding to the underlying base encoder (msgpackr or cbor-x).
Binary format compatibility: the byte layout produced by structon is identical to msgpackr's struct.js format. Data written by either implementation can be read by the other.
Packr/Encoder or cbor-x's Encoder (or any compatible encoder).saveStructures/getStructures callbacks.struct.js random-access format.npm install structon
# peer dependency for msgpackr usage:
npm install msgpackr
# or for cbor-x:
npm install cbor-ximport { Packr } from 'msgpackr';
import { createStructon } from 'structon';
const Structon = createStructon(Packr);
// Persist structures so they survive process restarts
let savedStructures = null;
const enc = new Structon({
structures: [],
saveStructures(s) { savedStructures = s; },
getStructures() { return savedStructures; },
});
const buf = enc.encode({ name: 'Alice', age: 30, score: 99.5 });
const obj = enc.decode(buf);
import { Encoder } from 'cbor-x';
import { createStructon } from 'structon';
const Structon = createStructon(Encoder);
const enc = new Structon({ structures: [] });
const buf = enc.encode({ id: 1, label: 'widget' });
const obj = enc.decode(buf);
console.log(obj.id); // 1
console.log(obj.label); // 'widget'Values that are not plain objects (arrays, strings, numbers, Maps, etc.) are encoded and decoded by the base class transparently.
enc.encode([1, 2, 3]); // regular msgpack/cbor array
enc.encode('hello'); // regular msgpack/cbor string
enc.encode(new Map([['a', 1]])); // regular msgpack/cbor mapcreateStructon(BaseClass)Returns a Structon class that extends BaseClass.
Parameters
BaseClass — Packr from msgpackr, Encoder from cbor-x, or any compatible encoder class.Returns a class with the following additions over BaseClass:
| Member | Description |
|---|---|
encode(value) | Encodes plain objects as structs; other values via base class. |
decode(buffer) | Decodes struct buffers into lazy objects; other buffers via base class. |
typedStructs | Array of learned structure definitions (auto-populated). |
_decodeSliceDirect(src, start, end) | Low-level slice decoder used by struct getters. |
All options from the base class are forwarded. Additional behaviour:
| Option | Description |
|---|---|
structures | Shared structure definitions array (passed to base class). |
saveStructures(s) | Called when new struct definitions are learned (msgpackr API). |
getStructures() | Called to load previously saved structures (msgpackr API). |
saveShared(s) | cbor-x equivalent of saveStructures. |
getShared() | cbor-x equivalent of getStructures. |
The format is identical to msgpackr's struct.js:
[header (1-4 bytes)][fixed-width field section][variable ref section]0x20 + id (single byte for ids 0-15), or 0x38/0x39/0x3a with 1/2/3 extra bytes for larger IDs.uint8/uint32/float64, strings as 0/1/2-byte ref offsets, objects as 2/4-byte ref offsets, dates as float64.Field access resolves directly from the buffer — only the bytes for the accessed field are read.
structon is bidirectionally byte-compatible with msgpackr's randomAccessStructure: true mode (msgpackr ≤ 1.11.10, before its struct.js was removed). The test suite verifies all four directions:
Packr readsPackr writes → Structon readsstructures and typedStructs are sharedThese compatibility tests pin msgpackr 1.11.10 as a dev dependency.
Apache 2.0 — see LICENSE.