data-struct

Schema-driven binary serialization between JavaScript values and Node Buffers.

• Tiny. No runtime dependencies.
• Typed. A schema infers the exact TypeScript shape of the decoded value via Infer<S>.
• Fast. Two-pass encoder allocates the output buffer exactly once.
• Dual-format. Ships ESM + CommonJS + .d.ts for both.
• Wire-stable. Big-endian by default, byte-identical with prior 0.0.x releases.

Install

npm install data-struct

Requires Node >=20.9.

Usage

import { struct, t, type Infer } from 'data-struct';

const Hero = struct({
  id: t.u32,
  name: t.string,
  hp: t.i16,
  skills: [{ id: t.u16, description: t.string }],
  playable: t.bool,
  experience: t.u32,
  position: { x: t.u16, y: t.u16 },
});

type Hero = Infer<typeof Hero.schema>;

const buf = Hero.encode({
  id: 9,
  name: 'CirnoBaka',
  hp: 146,
  skills: [
    { id: 34, description: 'freezing frogs' },
    { id: 16, description: 'perfect math' },
  ],
  playable: false,
  experience: 99_999_999,
  position: { x: 2, y: 3 },
});

const hero = Hero.decode(buf); // typed as Hero

Functional form, when you don't want to keep a compiled struct around:

import { encode, decode, t } from 'data-struct';

const Map2D = [[t.u8]];
const buf = encode([[0, 1, 0], [1, 0, 1]], Map2D);
const map = decode(buf, Map2D); // number[][]

API

Codec tokens — t

Token	Bytes	TS type	Notes
t.bool	1	boolean
t.i8 / t.u8	1	number
t.i16 / t.u16	2	number	big-endian
t.i32 / t.u32	4	number	big-endian
t.f32 / t.f64	4 / 8	number	big-endian
t.i64 / t.u64	8	bigint	big-endian
t.string	2 + utf-8	string	uint16 length prefix, max 65535 utf-8 bytes
t.shortBytes	2 + n	Uint8Array	uint16 length prefix, max 65535 bytes
t.bytes	4 + n	Uint8Array	uint32 length prefix, max 4294967295 bytes

Little-endian variants live under t.le.* (e.g. t.le.u32, t.le.f64, t.le.string).

Schema shape

A schema is one of:

• A codec token (t.u32).
• A single-element array [Schema] — encodes as a uint16 length prefix followed by N child encodings.
• A plain object — fields encoded in declared key order.

type Schema = Codec<unknown> | Schema[] | { [k: string]: Schema };
type Infer<S> = /* recursively maps each leaf to its TS type */;

Functions

struct<S extends Schema>(schema: S): {
  schema: S;
  encode(value: Infer<S>): Buffer;
  decode(input: Uint8Array): Infer<S>;
  sizeOf(value: Infer<S>): number;
};

encode<S extends Schema>(value: Infer<S>, schema: S): Buffer;
decode<S extends Schema>(input: Uint8Array, schema: S): Infer<S>;

struct(schema) compiles the schema tree once and reuses the compiled codec across calls — prefer it in hot paths.

Errors

Validation throws DataStructError with a code:

Code	When
VALUE_OUT_OF_RANGE	Numeric value outside the leaf's range or non-int
STRING_TOO_LONG	UTF-8 byte length exceeds 65535
BYTES_TOO_LONG	Bytes value exceeds the leaf's length cap
ARRAY_TOO_LONG	Array length exceeds 65535
BUFFER_UNDERFLOW	Decode would read past the end of the input
SCHEMA_MISMATCH	Value shape does not match the schema
INVALID_SCHEMA	Schema itself is malformed

Every error carries path (e.g. $.skills[1].description) and, for decode errors, offset.

Wire format

bool          : 1 byte               0x00 = false, anything else = true
i8/u8         : 1 byte
i16/u16       : 2 bytes BE
i32/u32       : 4 bytes BE
f32/f64       : 4 / 8 bytes BE
i64/u64       : 8 bytes BE
string        : uint16 BE length || utf-8 bytes
shortBytes    : uint16 BE length || raw bytes
bytes         : uint32 BE length || raw bytes
array [E]     : uint16 BE length || N encoded elements
object {…}    : fields encoded in declared key order, no header

LE variants (t.le.*) swap the byte order of length prefixes and the numeric payload.

Migration from 0.0.x

The 0.1.0 release is a full rewrite with a new API surface. The wire format is preserved, so buffers produced by older versions decode correctly under the new codecs.

Old	New
DataTypes.boolean	t.bool
DataTypes.int8 / uint8	t.i8 / t.u8
DataTypes.int16/uint16	t.i16 / t.u16
DataTypes.int32/uint32	t.i32 / t.u32
DataTypes.float	t.f32
DataTypes.double	t.f64
DataTypes.string	t.string
DataTypes.shortBuffer	t.shortBytes
DataTypes.buffer	t.bytes
DataWriter(obj, scheme)	encode(obj, schema)
DataReader(buf, scheme)	decode(buf, schema)

The legacy DataTypes / DataReader / DataWriter exports are removed.

Development

npm install
npm run typecheck
npm run lint
npm test
npm run bench
npm run build

License

MIT