English | 中文

API Document
JBOD encoding format
Benchmark

JavaScript Binary Object Data

JavaScript Binary Serialization and deserialization lib. Support for more JS data types。Can be used for transmission, and storage.
JavaScript 二进制序列化与反序列库。支持更多的 JS 数据类型，序列化后大小占用很小。可用于传输、和存储。

Inspired by ProtoBuf, JBOD is more flexible than ProtoBuf. More applicable to dynamically typed languages like JavaScript.

Features

More JavaScript data types

type	Notes
boolean
null
undefined
number	Support NaN、-Infinity、+Infinity
bigint
Uint8Array
string
RegExp
Array
Object
Symbol	The significance is not significant, only the description attribute will be retained after conversion
Error	Keep only the cause, code, message, and name attributes
Map
Set

Smaller binary data size

Data type	Byte size (JSON)	Byte size (JBOD)
int(0~2147483647)	1~ 10	1~5
int (-1~-2147483648)	2~ 11	1~5
double	1~22	8
boolean	4(true)、5(false)	1
null	4	1
string (Set n as the UTF-8 encoding length of the string)	n+2	n+(1~5)

The data encoded by JBOD.encode() is about 70% the size of JSON The data size of structured encoding is 20% ~ 40% of JSON View Structured Encoding

View simple code size comparison example

Usage

Node

npm install jbod

1import JBOD from "jbod";
2const u8Arr = JBOD.encode(data);
3const decodedData = JBOD.decode(u8Arr).data;

Deno

1import JBOD from "jsr:@asn/jbod";
2const u8Arr = JBOD.encode(data);
3const decodedData = JBOD.decode(u8Arr).data;

Browser

1import JBOD from "https://esm.sh/jbod";
2const u8Arr = JBOD.encode(data);
3const decodedData = JBOD.decode(u8Arr).data;

Structured encoding

There are some scenarios where the data structure is fairly fixed, in which case transmitting type information can be quite redundant. For example, the object type has very space-consuming key names, and it also has a significant impact on performance in the JavaScript environment. In some scenarios, the keys are fixed, in which case ideally, the encoding should not retain the key information, only encode the values, and the decoder should decode the values based on the predefined structure, then restore the object data. This feature is inspired by ProtoBuf.

Struct data types

Type symbol	description	js type
dyI32	32-bit Integer （Dynamic length encode by zigzag + varints ）	number
dyI64	64-bit Integer （Dynamic length, encode by zigzag + varints ）	bigint
i32	32-bit Integer	number
i64	64-bit Integer	bigint
f64	64-bit Float	number
bool	Boolean	boolean
string		string
binary		Uint8Array
any	Any type
anyArray	Array elements can be of any type
anyRecord	Object pieces and values can be of any type
regExp		RegExp
error		Error
map		Map
set		Set
symbol		symbol

Any type: The any type has an extra byte to hold type information than the fixed type

Example Struct definition

Suppose you need to define the following data structure:

1interface Data {
2  name: string;
3  count?: number;
4  custom: any;
5  list: number[];
6  items: { key1: any; key2: any }[];
7}

Defining structure：

1const struct = StructCodec.define({
2  name: { id: 1, type: "string" },
3  count: { id: 2, type: "dyI32", optional: true }, // Optional field
4  custom: { id: 111, type: "any" }, // Any type, or you can omit type
5  list: { id: 3, repeat: true, type: "dyI32" },
6
7  // Array of objects
8  items: {
9    id: 4,
10    repeat: true,
11    type: {
12      key1: { id: 1, type: "any" },
13      key2: { id: 2, type: "any" },
14    },
15  },
16});
17const rawObject = { name: "test", count: 9, custom: [1] };
18const u8Arr = struct.encode(rawObject);
19
20const decodedData = struct.decode(u8Arr).data;
21console.log(decodedData);

Note that the id is used to map with the key name, it must be a positive integer, and it cannot be repeated。
For the any type, you don't have to write the type. In this case, you could have also defined it like this:

1const struct = StructCodec.define({
2  name: { id: 1, type: "string" },
3  count: { id: 2, type: "dyI32", optional: true },
4  custom: 111,
5  list: { id: 3, repeat: true, type: "dyI32" },
6  items: {
7    id: 4,
8    repeat: true,
9    type: { key1: 1, key2: 2 },
10  },
11});

The any type contains an extra byte to hold the type information, depending on your use case

Examples

Simple code size comparison example

1import JBOD, { StructCodec } from "jbod";
2import { Buffer } from "node:buffer";
3function encodeJSON(data: any) {
4  return Buffer.from(JSON.stringify(data));
5}
6export const objData = {
7  disabled: false,
8  count: 100837,
9  name: "Documentation",
10  dataStamp: 4 / 7,
11  id: 876,
12};
13
14const anyStruct = StructCodec.define({ disabled: 1, count: 2, name: 3, dataStamp: 4, id: 5 });
15const fixedStruct = StructCodec.define({
16  disabled: { id: 1, type: "bool" },
17  count: { id: 2, type: "dyI32" },
18  name: { id: 3, type: "string" },
19  dataStamp: { id: 4, type: "f64" },
20  id: { id: 5, type: "dyI32" },
21});
22
23console.log(encodeJSON(objData).byteLength); // 96
24console.log(JBOD.encode(objData).byteLength); // 67   (70% of JSON)
25console.log(anyStruct.encode(objData).byteLength); // 38 (55% of JSON)
26console.log(fixedStruct.encode(objData).byteLength); // 34 (35% of JSON)