Api

String Methods

Methods for serializing and deserializing UTF-8, ASCII, and UTFZ-compressed strings with various length-prefix sizes.

Sia supports three string encodings, each with different trade-offs between compatibility, size, and speed. All string methods follow the symmetric add/read pattern and are available as both class methods and standalone functions:

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

// Functional API (tree-shakeable)
import {
  Buffer,
  addString8,
  readString8,
  addAscii8,
  readAscii8,
} from "@timeleap/sia";

UTF-8 Strings

UTF-8 string methods encode text using the standard TextEncoder/TextDecoder APIs. The number suffix indicates the bit width of the length prefix, which determines the maximum string byte length.

`addString8(str)` / `readString8()`

Writes or reads a UTF-8 string with an 8-bit (1 byte) length prefix. Maximum encoded length: 255 bytes.

addString8(str: string): Sia
readString8(): string

Parameter	Type	Description
`str`	`string`	The string to serialize

const sia = new Sia();
sia.addString8("Hello!");
sia.seek(0);
console.log(sia.readString8()); // "Hello!"

`addString16(str)` / `readString16()`

Writes or reads a UTF-8 string with a 16-bit (2 byte) length prefix. Maximum encoded length: 65,535 bytes.

addString16(str: string): Sia
readString16(): string

Parameter	Type	Description
`str`	`string`	The string to serialize

const sia = new Sia();
sia.addString16("A longer string that might exceed 255 bytes when encoded");
sia.seek(0);
console.log(sia.readString16());

`addString32(str)` / `readString32()`

Writes or reads a UTF-8 string with a 32-bit (4 byte) length prefix. Maximum encoded length: ~4 GB.

addString32(str: string): Sia
readString32(): string

Parameter	Type	Description
`str`	`string`	The string to serialize

const sia = new Sia();
sia.addString32("Works for very large strings");
sia.seek(0);
console.log(sia.readString32());

`addString64(str)` / `readString64()`

Writes or reads a UTF-8 string with a 64-bit (8 byte) length prefix.

addString64(str: string): Sia
readString64(): string

Parameter	Type	Description
`str`	`string`	The string to serialize

In practice, addString64 is rarely needed. The 64-bit length prefix itself uses 8 bytes, and JavaScript strings are limited by available memory. Prefer addString8 or addString16 for typical use cases.

const sia = new Sia();
sia.addString64("Hello, String64!");
sia.seek(0);
console.log(sia.readString64()); // "Hello, String64!"

ASCII Strings

ASCII string methods use a direct byte-per-character copy instead of TextEncoder, which is faster for ASCII-only content. Like UTF-8 strings, variants differ by length-prefix size. There is also a no-prefix variant (addAsciiN) for fixed-length fields.

All ASCII methods only support characters in the range 0–127. Non-ASCII characters (accented letters, emoji, CJK, etc.) will produce incorrect output. Use the UTF-8 addString* methods for Unicode content.

`addAsciiN(str)` / `readAsciiN(length)`

Writes or reads a fixed-length ASCII string with no length prefix. The caller must know the length at read time.

addAsciiN(str: string): Sia
readAsciiN(length: number): string

Parameter	Type	Description
`str`	`string`	ASCII-only string to serialize
`length`	`number`	Number of characters to read

const sia = new Sia();
sia.addAsciiN("USD"); // no length prefix, 3 bytes total
sia.seek(0);
console.log(sia.readAsciiN(3)); // "USD"

Use addAsciiN for fixed-length fields like currency codes, country codes, or protocol magic bytes where the length is known at compile time.

`addAscii8(str)` / `readAscii8()`

Writes or reads an ASCII string with an 8-bit (1 byte) length prefix. Maximum length: 255 characters.

addAscii8(str: string): Sia
readAscii8(): string

Parameter	Type	Description
`str`	`string`	ASCII-only string to serialize (max 255 chars)

const sia = new Sia();
sia.addAscii8("Hello, ASCII!");
sia.seek(0);
console.log(sia.readAscii8()); // "Hello, ASCII!"

`addAscii16(str)` / `readAscii16()`

Writes or reads an ASCII string with a 16-bit (2 byte) length prefix. Maximum length: 65,535 characters.

addAscii16(str: string): Sia
readAscii16(): string

Parameter	Type	Description
`str`	`string`	ASCII-only string to serialize (max 65,535 chars)

`addAscii32(str)` / `readAscii32()`

Writes or reads an ASCII string with a 32-bit (4 byte) length prefix.

addAscii32(str: string): Sia
readAscii32(): string

`addAscii64(str)` / `readAscii64()`

Writes or reads an ASCII string with a 64-bit (8 byte) length prefix.

addAscii64(str: string): Sia
readAscii64(): string

The ASCII methods use a pre-compiled lookup table of String.fromCharCode functions, making decoding extremely fast for short strings (up to 65 characters).

UTFZ Strings

`addUtfz(str)` / `readUtfz()`

Writes or reads a string using the UTFZ compressed encoding. UTFZ is a compact encoding that can be more space-efficient than UTF-8 for certain string patterns.

addUtfz(str: string): Sia
readUtfz(): string

Parameter	Type	Description
`str`	`string`	The string to serialize

UTFZ stores a 1-byte length prefix representing the encoded byte count (not the string length). This means UTFZ strings are limited to 255 encoded bytes. For longer strings, use the UTF-8 methods.

const sia = new Sia();
sia.addUtfz("Hello, UTFZ!");
sia.seek(0);
console.log(sia.readUtfz()); // "Hello, UTFZ!"

Choosing the Right Method

Method	Encoding	Max Size	Length Prefix	Best For
`addAsciiN`	ASCII	Fixed	None	Currency codes, fixed-width fields
`addAscii8`	ASCII	255 chars	1 byte	Short identifiers, keys, codes
`addAscii16`	ASCII	65,535 chars	2 bytes	Longer ASCII text
`addAscii32`	ASCII	~4 billion chars	4 bytes	Large ASCII payloads
`addAscii64`	ASCII	Huge	8 bytes	Theoretical ASCII payloads
`addUtfz`	UTFZ	255 encoded bytes	1 byte	Short Unicode strings, compression
`addString8`	UTF-8	255 bytes	1 byte	Short Unicode strings
`addString16`	UTF-8	64 KB	2 bytes	Medium text fields
`addString32`	UTF-8	~4 GB	4 bytes	Large text content
`addString64`	UTF-8	Huge	8 bytes	Theoretical large payloads

Rules of thumb:

Use addAscii8 for protocol identifiers, enum-like strings, and keys where you know the content is ASCII.
Use addString8 for short user-facing text (names, labels, short messages).
Use addString16 for medium-length text (descriptions, comments).
Use addString32 for large text (articles, documents).
Use addUtfz when you need compact encoding for short strings with Unicode characters.

Complete Example

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

interface UserProfile {
  username: string; // ASCII only, short
  displayName: string; // Unicode, short
  bio: string; // Unicode, medium length
}

// Serialize
const sia = new Sia();
sia
  .addAscii8("alice_42") // username: fast ASCII
  .addString8("Alice") // displayName: short UTF-8
  .addString16(
    "Software engineer from Zurich. I love TypeScript and binary protocols!",
  );

const bytes = sia.toUint8Array();

// Deserialize
const reader = new Sia(bytes);
const profile: UserProfile = {
  username: reader.readAscii8(),
  displayName: reader.readString8(),
  bio: reader.readString16(),
};

console.log(profile);
// {
//   username: "alice_42",
//   displayName: "Alice",
//   bio: "Software engineer from Zurich. I love TypeScript and binary protocols!"
// }

Edit this pageorReport an issue

Integer Methods

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

Byte Array Methods

Methods for serializing and deserializing raw byte arrays with or without length prefixes, and controlling memory allocation behavior.