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