@scintilla-network/serialize

A library for serializing and deserializing data according to the Scintilla Network protocol. Provides efficient binary serialization for JavaScript objects, arrays, strings, numbers, and booleans with support for nested structures and variable-length encoding.

Features

• Universal Serialization: Convert JavaScript objects, arrays, and primitives to binary format
• Type-Safe Deserialization: Convert binary data back to JavaScript structures
• Variable-Length Encoding: Efficient encoding for integers and big integers
• Nested Structure Support: Handle complex nested objects and arrays recursively

Installation

npm install @scintilla-network/serialize

Quick Start

import{serialize,deserialize}from'@scintilla-network/serialize';// Serialize JavaScript object to binaryconstdata={name: 'Alice',age: 30,active: true,scores: [95,87,92],metadata: {version: 1,tags: ['user','premium']}};constserialized=serialize.fromObject(data);console.log(serialized.value);// Uint8Array with binary dataconsole.log(serialized.length);// Total bytes used// Deserialize binary back to JavaScript objectconstdeserialized=deserialize.toObject(serialized.value);console.log(deserialized.value);// Original object restoredconsole.log(deserialized.length);// Bytes consumed

API Reference

Serialization Functions

The serialize namespace provides functions to convert JavaScript values into binary format:

Function	Description	Input	Output
fromObject()	Serialize objects and arrays	Object/Array	{value: Uint8Array, length: number}
fromString()	Serialize strings	String	{value: Uint8Array, length: number}
fromVarInt()	Serialize variable-length integers	Number	{value: Uint8Array, length: number}
fromVarBigInt()	Serialize variable-length big integers	BigInt	{value: Uint8Array, length: number}
fromBoolean()	Serialize booleans	Boolean	{value: Uint8Array, length: number}

Deserialization Functions

The deserialize namespace provides functions to convert binary data back to JavaScript values:

Function	Description	Input	Output
toObject()	Deserialize objects and arrays	Uint8Array	{value: Object/Array, length: number}
toString()	Deserialize strings	Uint8Array	{value: String, length: number}
toVarInt()	Deserialize variable-length integers	Uint8Array	{value: Number, length: number}
toVarBigInt()	Deserialize variable-length big integers	Uint8Array	{value: BigInt, length: number}
toBoolean()	Deserialize booleans	Uint8Array	{value: Boolean, length: number}

Detailed Documentation

For comprehensive protocol specifications, implementation details, examples, and advanced usage patterns, see the detailed documentation:

Serialization Details

• fromObject - Complete object and array serialization
• fromString - String encoding and UTF-8 handling
• fromVarInt - Variable-length integer encoding
• fromVarBigInt - Big integer encoding
• fromBoolean - Boolean serialization

Deserialization Details

• toObject - Complete object and array deserialization
• toString - String decoding and validation
• toVarInt - Variable-length integer decoding
• toVarBigInt - Big integer decoding
• toBoolean - Boolean deserialization

Protocol Specification

The library implements the Scintilla Network binary protocol with these key characteristics:

• Type System: 6 core types (String, Variable Integer, Variable Big Integer, Array, Object, Boolean)
• Variable-Length Encoding: Efficient encoding using Protocol Buffers varint format
• Deterministic Serialization: Field names are alphabetically sorted for consistency
• Nested Structure Support: Recursive encoding/decoding of complex data structures
• Length Prefixing: All sections include length prefixes for safe parsing

Advanced Usage

The toObject function provides a way to deserialize to specific constructor, for such, provide a kindToConstructor function to the toObject function.

classTransaction{constructor(data){this.kind='TRANSACTION';this.amount=data.amount;}toUint8Array(){returnnewUint8Array([NET_KINDS.TRANSACTION, ...serialize.fromVarInt(this.amount).value]);}staticfromUint8Array(bytes){returnnewTransaction({amount: deserialize.toVarInt(bytes.subarray(1)).value,});}}constkindToConstructor=(kind)=>{switch(kind){case'TRANSACTION':
returnTransaction;}};consttx=newTransaction({amount: 100});constserializedTx=serialize.fromObject(tx);// [8, 100]constdeserializedTx=deserialize.toObject(serializedTx.value,kindToConstructor);// Transaction { amount: 100 }

Supporting Utilities

Type Detection

• getFieldTypeFromBytes() - Helper function to identify field types from binary data

Constants

• NET_KINDS - Protocol type constants and mappings

 UNKNOWN = 0,
PEER_INFO = 1,
REQUEST = 2,
RESPONSE = 3,
ACKHANDSHAKE = 4,
EPOCHBLOCK = 5,
CLUSTERBLOCK = 6,
HASHPROOF = 7,
TRANSACTION = 8,
TRANSITION = 9,
TRANSFER = 10,
STATEMENT = 11,
HANDSHAKE = 12,
QUORUMDECISION = 13,
QUORUMDECISIONVOTE = 14,
RELAYBLOCK = 15,
VOUCHER = 16,
ASSET = 17,
IDENTITY = 18,
GOVERNANCEPROPOSAL = 19,
GOVERNANCEVOTE = 20,
INSTRUCTION = 21,
RAW = 22,
PACKEDOBJECT = 23,
PACKEDARRAY = 24,

Logging

• llog - Conditional logging utility (enabled with VERBOSE_SERIALIZATION=true)

License

MIT License - see the LICENSE file for details

Contributing

Contributions are welcome!
For issues, feature requests, or contributions, please visit the GitHub repository.