Api

Sia Class

Core class for binary serialization and deserialization. Extends Buffer with a fluent, chainable API for reading and writing typed data.

The Sia class is the main entry point for the @timeleap/sia library. It extends Buffer and provides a fluent, chainable API for serializing and deserializing typed binary data.

Every method on the Sia class is a thin wrapper around a standalone function. You can use the class for ergonomic chaining, or import individual functions for tree-shakeable builds. See the API pages for each data type for functional equivalents.

import { Sia } from "@timeleap/sia";

Constructor

new Sia(content?: Uint8Array)

Creates a new Sia instance. If no buffer is provided, a shared 32 MB buffer (lazy-allocated on first use) is used internally for maximum performance.

Parameter	Type	Default	Description
`content`	`Uint8Array`	Global shared buffer (32 MB)	Optional backing buffer

Basic Usage

// Uses the global shared buffer (fast, but not safe to hold references)
const sia = new Sia();
sia.addUInt8(42);

Custom Buffer

// Uses a dedicated buffer (safe to hold references)
const buffer = new Uint8Array(1024);
const sia = new Sia(buffer);
sia.addUInt8(42);

When using the default constructor without arguments, Sia uses a global shared buffer. This is extremely fast but means you must extract your data (via toUint8Array()) before creating another Sia instance, or the buffer will be overwritten.

Static Methods

`Sia.alloc(size)`

Allocates a new Sia instance backed by a zero-filled Uint8Array of the given size.

static alloc(size: number): Sia

Parameter	Type	Description
`size`	`number`	Number of bytes to allocate

Returns: A new Sia instance with a dedicated, zero-filled buffer.

const sia = Sia.alloc(256);
sia.addString8("Hello");
const bytes = sia.toUint8Array();

`Sia.allocUnsafe(size)`

Allocates a Sia instance from a region of the global shared buffer. The memory is not zero-filled.

static allocUnsafe(size: number): Sia

Parameter	Type	Description
`size`	`number`	Number of bytes to allocate

Returns: A new Sia instance backed by a subarray of the global shared buffer.

The returned buffer may contain stale data from previous operations. Only use allocUnsafe when you will write to every byte before reading. If the requested size exceeds the remaining space in the shared buffer, allocation wraps around to the beginning.

// Fast allocation for a message you'll fully populate
const sia = Sia.allocUnsafe(128);
sia.addUInt32(1).addString8("event").addBool(true);
const bytes = sia.toUint8Array();

Utility Methods

`seek(index)`

Sets the internal read/write offset to an absolute position.

seek(index: number): Sia

Parameter	Type	Description
`index`	`number`	Byte offset to seek to

Returns: this (for chaining)

const sia = new Sia();
sia.addUInt8(10).addUInt8(20);

// Seek back to the start to read
sia.seek(0);
console.log(sia.readUInt8()); // 10
console.log(sia.readUInt8()); // 20

`skip(bytes)`

Advances the internal offset by the given number of bytes.

skip(bytes: number): Sia

Parameter	Type	Description
`bytes`	`number`	Number of bytes to skip forward

Returns: this (for chaining)

const sia = new Sia();
sia.addUInt8(1).addUInt8(2).addUInt8(3);
sia.seek(0);

sia.skip(1); // Skip the first byte
console.log(sia.readUInt8()); // 2

`setContent(uint8Array)`

Replaces the internal buffer with a new Uint8Array and resets the offset to 0.

setContent(uint8Array: Uint8Array): Sia

Parameter	Type	Description
`uint8Array`	`Uint8Array`	New backing buffer

Returns: this (for chaining)

const sia = new Sia();

// Load received data for deserialization
const received = new Uint8Array([42, 0, 5, 72, 101, 108, 108, 111]);
sia.setContent(received);

const id = sia.readUInt8(); // 42
const name = sia.readString8(); // "Hello"

`embedSia(sia)`

Copies the serialized content of another Sia instance into this one at the current offset.

embedSia(sia: Sia): Sia

Parameter	Type	Description
`sia`	`Sia`	Another Sia instance whose content will be embedded

Returns: this (for chaining)

// Serialize a header separately
const header = new Sia();
header.addUInt8(1).addUInt32(Date.now());

// Embed the header into the main message
const message = new Sia();
message.embedSia(header);
message.addString8("payload data");

`embedBytes(bytes)`

Copies raw bytes into the buffer at the current offset. Unlike addByteArrayN, this does not write a length prefix.

embedBytes(bytes: Uint8Array): Sia

Parameter	Type	Description
`bytes`	`Uint8Array`	Raw bytes to embed

Returns: this (for chaining)

const sia = new Sia();
const magic = new Uint8Array([0x53, 0x49, 0x41]); // "SIA" magic bytes
sia.embedBytes(magic);
sia.addUInt8(1); // version

Data Extraction Methods

`toUint8Array()`

Returns a copy of the buffer contents from byte 0 to the current offset.

toUint8Array(): Uint8Array

Returns: A new Uint8Array containing the serialized data.

const sia = new Sia();
sia.addUInt8(1).addString8("hello");
const bytes = sia.toUint8Array(); // Safe to store, send, etc.

`toUint8ArrayReference()`

Returns a reference (subarray) into the underlying buffer from byte 0 to the current offset.

toUint8ArrayReference(): Uint8Array

Returns: A Uint8Array subarray referencing the internal buffer.

The returned array shares memory with the Sia buffer. If you use the default shared buffer, this reference will become invalid as soon as the buffer is reused. Only use this when you need zero-copy performance and will consume the data immediately.

Safe: Copy

const sia = new Sia();
sia.addUInt8(42);
const copy = sia.toUint8Array(); // Independent copy

Fast: Reference

const sia = new Sia();
sia.addUInt8(42);
const ref = sia.toUint8ArrayReference(); // Shares memory
// Use ref immediately — do not store for later

`slice(start, end)`

Returns a copy of a range of bytes from the internal buffer.

slice(start: number, end: number): Uint8Array

Parameter	Type	Description
`start`	`number`	Start byte index (inclusive)
`end`	`number`	End byte index (exclusive)

Returns: A new Uint8Array with the sliced bytes.

const sia = new Sia();
sia.addUInt32(100).addUInt32(200);
const firstInt = sia.slice(0, 4); // Bytes for the first uint32

`get(offset)`

Returns a single byte at the given offset.

get(offset: number): number

Parameter	Type	Description
`offset`	`number`	Byte index to read

Returns: The byte value at that offset.

const sia = new Sia();
sia.addUInt8(0xff);
console.log(sia.get(0)); // 255

Properties

`length`

A getter that returns the total size of the backing buffer (not the amount of data written).

get length(): number

const sia = Sia.alloc(512);
console.log(sia.length); // 512
sia.addUInt8(1);
console.log(sia.length); // Still 512 (buffer size, not data size)

Properties Table

Property	Type	Description
`offset`	`number`	Current read/write position in the buffer
`size`	`number`	Total size of the backing buffer
`content`	`Uint8Array`	The raw backing buffer
`dataView`	`DataView`	DataView over the backing buffer for typed access

Complete Example

import { Sia } from "@timeleap/sia";

interface Sensor {
  id: number;
  name: string;
  value: number;
  active: boolean;
}

// Serialize
const sia = new Sia();
sia
  .addUInt32(1001) // id
  .addString8("temperature") // name
  .addUInt16(2350) // value (23.50 * 100)
  .addBool(true); // active

const bytes = sia.toUint8Array();
console.log(bytes.length); // Compact binary representation

// Deserialize
const reader = new Sia(bytes);
const sensor: Sensor = {
  id: reader.readUInt32(),
  name: reader.readString8(),
  value: reader.readUInt16(),
  active: reader.readBool(),
};

console.log(sensor);
// { id: 1001, name: "temperature", value: 2350, active: true }

Edit this pageorReport an issue

Deserialization

Read binary data back into typed values using Sia's read methods, with error handling and zero-copy options.

Integer Methods

Methods for serializing and deserializing unsigned and signed integers of 8, 16, 32, and 64-bit widths using little-endian byte order.