bserial

A high-performance binary serializer framework. Supports both ESM and CJS modules.

Installation

npm i bserial

Features

Supported Data Types

Type	Alias / Notes
uint8	byte
int8
uint16	ushort
int16	short
uint32	uint
int32	int
uint64	ulong
int64	long
float	float32
double	float64
bool	boolean
string	str
date	date_ms, date_time_ms, int64_date_time_ms
date_s	date_time_s, int64_date_time_s

Supported Data Annotations

Annotation	Description
@if(expr:string)	Generates an optional node, present only when expr is true.
@len(fixedLength:number)	Sets string to use a fixed byte length.
@encoding(encoding:string)	Sets the string encoding (e.g., 'utf-8').

Usages

Basic Usage

import { compile, codec } from "bserial";
// const { compile, codec } = require("bserial"); // or commonjs module

const scheme = {
    isOk: 'byte',
    info: {
        id: 'int',
        name: 'string',
        isVIP: 'boolean',
        scope: 'float',
        createdAt: 'date',
    },
    behaviors: ['short', {
        name: 'string',
    }], // [length type, element scheme]
};

const srcObj = {
    isOk: 1,
    info: {
        id: 100,
        name: 'alien',
        isVIP: true,
        scope: 98.5,
        createdAt: new Date(),
    },
    behaviors: [{name: 'coding'}, {name: 'writing'}],
};

// compile
const ast = compile(scheme);

// encode
const buf = codec.encode(ast, srcObj);
// console.log(buf);
/*
log:
<Buffer 01 00 00 00 64 00 05 61 6c 69 65 6e 01 42 c5 00 00 00 00 01 9c b3 fd de 51 00 02 00 06 63 6f 64 69 6e 67 00 07 77 72 69 74 69 6e 67>
*/

// decode
const obj = codec.decode(ast, buf);
console.log(obj);
/*
log:
{
  isOk: 1,
  info: {
    id: 100,
    name: 'alien',
    isVIP: true,
    scope: 98.5,
    createdAt: 2026-03-03T14:01:48.621Z
  },
  behaviors: [ { name: 'coding' }, { name: 'writing' } ]
}
*/

Usage Via Annotation

annotation place	usage
filed	fieldName: dataType[@annotation...]
object	__annotations__: [@annotation...]
list	fieldName: [lengthDataType[@annotation...], elementType]

import { compile, codec } from "bserial";
// const { compile, codec } = require("bserial"); // or commonjs module

const scheme = {
    isOk: 'byte',
    info: {
        __annotations__: '@if(isOk == 1 || isOk > 3)',
        isVIP: 'boolean',
        name: 'string@len(16)@encoding("utf-8")',
    },
    deadline: 'date@if(info.isVIP)', // or @if(this.info.isVIP)
    data: ['int@if(isOk != 1 )', 'int']
};

const srcObj = {
    isOk: 4,
    info: {
        isVIP: false,
        name: 'fixed string buffer size'
    },
    deadline: new Date(),
    data: [1, 2, 3, 4],
};

// compile
const ast = compile(scheme);

// set endian "BE" or "LE"
codec.setEndian('BE'); // defautl BE if not set.

// encode
const buf = codec.encode(ast, srcObj);
console.log(buf);
/*
log:
<Buffer 04 00 66 69 78 65 64 20 73 74 72 69 6e 67 20 62 75 66 00 00 00 04 00 00 00 01 00 00 00 02 00 00 00 03 00 00 00 04>
*/

// decode
const obj = codec.decode(ast, buf);
console.log(obj);
/*
log:
{
  isOk: 4,
  info: { isVIP: false, name: 'fixed string buf' },
  data: [ 1, 2, 3, 4 ]
}
*/

License

MIT