Tree Shaking
The @timeleap/sia library exports every serialization operation as a standalone function alongside the Sia class. If you import the Sia class, the entire library is included in your bundle. If you import standalone functions instead, your bundler can drop everything you don't use.
Class vs. Functional Imports
With the Sia class, every method is available and the full library is bundled:
import { Sia } from "@timeleap/sia";
const sia = new Sia();
sia.addString8("Alice").addUInt8(30).addBool(true);
sia.seek(0);
const name = sia.readString8();
const age = sia.readUInt8();
const active = sia.readBool();
With standalone functions, only the imported functions and their dependencies are bundled:
import {
Buffer,
addString8,
readString8,
addUInt8,
readUInt8,
addBool,
readBool,
} from "@timeleap/sia";
const buf = Buffer.alloc(256);
addString8(buf, "Alice");
addUInt8(buf, 30);
addBool(buf, true);
buf.seek(0);
const name = readString8(buf);
const age = readUInt8(buf);
const active = readBool(buf);
In this example, the integer, string, and boolean modules are included, but arrays, byte arrays, bigint, embed, and ASCII code is excluded from the bundle.
Standalone Functions
Every standalone function takes a Buffer (or any subclass) as its first argument and returns it, so you can chain calls if needed:
import { Buffer, addUInt8, addBool } from "@timeleap/sia";
const buf = Buffer.alloc(256);
addBool(addUInt8(buf, 42), true);
Though in practice, sequential calls are more readable.
Full Example
Serializing and deserializing a user object with only the functions you need:
import {
Buffer,
addString8,
readString8,
addUInt8,
readUInt8,
addBool,
readBool,
addArray8,
readArray8,
} from "@timeleap/sia";
interface User {
name: string;
age: number;
active: boolean;
tags: string[];
}
function encodeUser(buf: Buffer, user: User): Buffer {
addString8(buf, user.name);
addUInt8(buf, user.age);
addBool(buf, user.active);
addArray8(buf, user.tags, (b, tag) => addString8(b, tag));
return buf;
}
function decodeUser(buf: Buffer): User {
return {
name: readString8(buf),
age: readUInt8(buf),
active: readBool(buf),
tags: readArray8(buf, (b) => readString8(b)),
};
}
// Usage
const buf = Buffer.alloc(1024);
encodeUser(buf, {
name: "Alice",
age: 30,
active: true,
tags: ["admin", "verified"],
});
buf.seek(0);
const user = decodeUser(buf);
Available Functions
Integers
| Write | Read |
|---|---|
addUInt8(buf, n) | readUInt8(buf) |
addInt8(buf, n) | readInt8(buf) |
addUInt16(buf, n) | readUInt16(buf) |
addInt16(buf, n) | readInt16(buf) |
addUInt32(buf, n) | readUInt32(buf) |
addInt32(buf, n) | readInt32(buf) |
addUInt64(buf, n) | readUInt64(buf) |
addInt64(buf, n) | readInt64(buf) |
Strings
| Write | Read |
|---|---|
addString8(buf, s) | readString8(buf) |
addString16(buf, s) | readString16(buf) |
addString32(buf, s) | readString32(buf) |
addString64(buf, s) | readString64(buf) |
addAsciiN(buf, s) | readAsciiN(buf, len) |
addAscii8(buf, s) | readAscii8(buf) |
addAscii16(buf, s) | readAscii16(buf) |
addAscii32(buf, s) | readAscii32(buf) |
addAscii64(buf, s) | readAscii64(buf) |
addUtfz(buf, s) | readUtfz(buf) |
Byte Arrays
| Write | Read |
|---|---|
addByteArrayN(buf, bytes) | readByteArrayN(buf, len) |
addByteArray8(buf, bytes) | readByteArray8(buf) |
addByteArray16(buf, bytes) | readByteArray16(buf) |
addByteArray32(buf, bytes) | readByteArray32(buf) |
addByteArray64(buf, bytes) | readByteArray64(buf) |
Arrays
| Write | Read |
|---|---|
addArray8(buf, arr, fn) | readArray8(buf, fn) |
addArray16(buf, arr, fn) | readArray16(buf, fn) |
addArray32(buf, arr, fn) | readArray32(buf, fn) |
addArray64(buf, arr, fn) | readArray64(buf, fn) |
Boolean
| Write | Read |
|---|---|
addBool(buf, val) | readBool(buf) |
BigInt
| Write | Read |
|---|---|
addBigInt(buf, val) | readBigInt(buf) |
Embed
| Function | Description |
|---|---|
embedSia(buf, sia) | Embed another Sia/Buffer's content |
embedBytes(buf, bytes) | Embed raw bytes |