Sia for TypeScript

TypeScript/JavaScript implementation of the Sia binary serialization library. Fast, compact, zero dependencies.

Documentation

Installation

npm install @timeleap/sia
# or
yarn add @timeleap/sia
# or
pnpm add @timeleap/sia

Quick Example

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

const sia = new Sia();
sia.addString8("Alice").addUInt8(30).addBool(true);

sia.seek(0);
console.log(sia.readString8()); // "Alice"
console.log(sia.readUInt8()); // 30
console.log(sia.readBool()); // true

All add* methods return this, so calls can be chained. After writing, seek(0) resets the offset for reading.

Functional API

Every operation is also exported as a standalone function for tree-shaking. If you import functions directly instead of the Sia class, your bundler can drop everything you don't use:

import {
  Buffer,
  addString8,
  readString8,
  addUInt8,
  readUInt8,
} from "@timeleap/sia";

const buf = Buffer.alloc(256);
addString8(buf, "Alice");
addUInt8(buf, 30);

buf.seek(0);
console.log(readString8(buf)); // "Alice"
console.log(readUInt8(buf)); // 30

See the tree-shaking guide for the full list of available functions.

Supported Types

| Type | Write | Read | | -------------------------- | ------------------------------------- | --------------------------------------- | | Integers (8/16/32/64) | addUInt8, addInt32, ... | readUInt8, readInt32, ... | | Strings (8/16/32/64) | addString8, addString32, ... | readString8, readString32, ... | | Byte arrays (N/8/16/32/64) | addByteArrayN, addByteArray8, ... | readByteArrayN, readByteArray8, ... | | Typed arrays (8/16/32/64) | addArray8, addArray32, ... | readArray8, readArray32, ... | | Boolean | addBool | readBool | | BigInt | addBigInt | readBigInt | | ASCII (N/8/16/32/64) | addAscii8, addAsciiN, ... | readAscii8, readAsciiN, ... | | UTFZ | addUtfz | readUtfz | | Embed | embedSia, embedBytes | - |

The number suffix indicates the byte width of the length prefix. N variants take an explicit length with no prefix.

Schema Compiler

Instead of writing serialization code by hand, you can define types in .sia files and generate TypeScript code:

schema User {
  name    string8
  age     uint8
  active  bool
}

npx @timeleap/sia-schema compile user.sia -o user.ts

See sia-schema for details.

Other Languages

Sia has native implementations with the same wire format:

| Language | Repo | Package | | -------- | -------------------------------------------------- | ----------------------------------- | | Go | go-sia | github.com/TimeleapLabs/go-sia/v2 | | Python | py-sia | timeleap-sia | | C++ | cpp-sia | CMake |

Serialize in TypeScript, deserialize in Go (or any other combination). The wire format is identical across all implementations.

License

ISC