small-frame

Zero-dependency structured message frame for small binary messages using the Really Compact Structured Binary (RCSB) encoding format.

Warning

This project is still in development and the API is not stable.

Usage

import { createFrameFromFields, FieldType, SerializerDataType } from "small-frame";

const UserFrame = createFrameFromFields({
  name: FieldType.String,
  age: FieldType.Number,
  isAdmin: FieldType.Boolean,
});

export type User = typeof UserFrame.$type;

const user = { 
  name: "Kane", 
  age: 20, 
  isAdmin: false 
};

// Serialize to RCSB format
const buffer = UserFrame.serialize(user);

// Deserialize from RCSB format
const user2 = UserFrame.deserialize(buffer);

console.log(user2);

The value will be serialized as:

04 4b 61 6e 65 00 00 00 14 00
└─ "Kane" (5)  └─ 20 (4)   └─ false (1)

Total size: 10 bytes

Really Compact Structured Binary (RCSB) Specification

RCSB is a compact, type-safe binary serialization format designed for really small structured messages. It provides predictable encoding with minimal overhead and strong type safety.

Data Types

Type	Size	Description
Boolean	1 byte	0x00 for false, 0x01 for true
Number	4 bytes	32-bit unsigned integer (uint32)
BigInt	8 bytes	64-bit unsigned integer (uint64)
String	1 + N bytes	Length prefix (uint8) + UTF-8 encoded bytes

String Encoding

Strings are encoded as:

[length: uint8][utf8_bytes...]

• Maximum string length: 255 bytes (uint8 max)
• UTF-8 encoding is used for text

Structure Encoding

Message structures are encoded by concatenating fields in definition order:

field1_bytes + field2_bytes + field3_bytes + ...

No delimiters or padding between fields. The total size is the sum of all field sizes.

Size Calculation

The serialized size can be calculated as:

• Boolean: 1 byte
• Number: 4 bytes
• BigInt: 8 bytes
• String: 1 + UTF-8 byte length