Classes and Methods

Polorizer

The Polorizer class is an encoding buffer that can sequentially polorize objects into it. It can be collapsed into its bytes with bytes() or packed().

// Creating a new Polorizer
const polorizer = new Polorizer()

parameters

none

methods

polorizeNull(): Encodes a WIRE_NULL into the head, consuming a position on the wire.

// Example
polorizer.polorizeNull()

polorizeBool(value)

Encodes the boolean as either WIRE_TRUE or WIRE_FALSE, depending on its value.

Arguments:

value (boolean) – The boolean value to encode.

// Example
polorizer.polorizeBool(true)

polorizeInteger(value)

Encodes the integer as the binary form of its absolute value with the wire type being WIRE_POSINT or WIRE_NEGINT based on polarity, with zero considered as positive.

Arguments:

value (number|BN) – The integer or BN value to encode.

// Example
polorizer.polorizeInteger(300)

polorizeFloat(value)

Encodes the float as its IEEE754 binary form (big-endian) with the wire type being WIRE_FLOAT.

Arguments:

value (number) – The float value to encode.

// Example
polorizer.polorizeFloat(123.456)

polorizeString(value)

Encodes the string as its UTF-8 encoded bytes with the wire type being WIRE_WORD.

Arguments:

value (string) – The string value to encode.

// Example
polorizer.polorizeString('foo')

polorizeRaw(value)

Encodes the Raw directly with the wire type being WIRE_RAW. A nil Raw is encoded as WIRE_NULL.

Arguments:

value (RAW) – The raw value to encode.

// Example
polorizer.polorizeRaw(new Raw([6, 98, 111, 111]))

polorizeBytes(value)

Encodes the bytes as is with the wire type being WireWord.

Arguments:

value (Uint8Array) – The bytes value to encode.

// Example
polorizer.polorizeBytes(new Uint8Array([1, 1, 1, 1]))

polorizePacked(pack)

The contents are packed into a WIRE_LOAD message and tagged with the WIRE_PACK wire type. If the given Polorizer is nil, a WIRE_NULL is encoded instead.

Arguments:

pack (Polorizer) – The Polorizer instance to encode.

// Example
const orange = {
    name: 'orange',
    cost: 300,
    alias: ['tangerine', 'mandarin']
}
// Encode the Name field as a string
polorizer.polorizeString(orange.name)
// Encode the Cost field as an integer
polorizer.polorizeInteger(orange.cost)
// Create a new Polorizer to serialize the Alias field (slice)
const aliases = new Polorizer()
// Encode each element in the Alias slice as a string
orange.alias.forEach((alias) => aliases.polorizeString(alias))
// Encode the Polorizer containing the alias field contents as packed data
polorizer.polorizePacked(aliases)

polorizeInner(inner)

Unlike PolorizePacked which will always write it as a packed wire while polorizeInner will write an atomic as is. If the given Polorizer is nil, a WireNull is encoded.

Arguments:

inner (Polorizer) – The Polorizer instance to encode.

// Example
const another = new Polorizer();
another.polorizeString('foo');

polorizer.polorizeInner(another);

polorize(value, schema)

Depending on the kind of the schema, the appropriate encoding method is called to encode the value. The supported kinds are null, bool, integer, float, string, raw, bytes, array, map, and struct.

Arguments:

value (null|boolean|number|BN|string|Uint8Array|Array.<unknown>|Map.<unknown, unknown>|object) –
- The value to be encoded into the Polorizer.
schema (Schema) – The schema that describes the value and its encoding.

Throws:

Error – If the kind of the schema is not one of the supported kinds.

polorize array

// Example
const arr = ["foo", "bar"]
const schema = {
    kind: 'array',
    fields: {
        values: {
            kind: 'string'
        }
    }
}

polorizer.polorize(arr, schema)

polorize map

// Example
const map = new Map()
map.set(0, "foo")
map.set(1, "bar")

const schema = {
    kind: 'map',
    fields: {
        keys: {
            kind: 'integer'
        },
        values: {
            kind: 'string'
        }
    }
}

polorizer.polorize(map, schema)

polorize struct

// Example
const struct = {
    name: 'orange',
    cost: 300,
}

const schema = {
    kind: 'struct',
    fields: {
        name: {
            kind: 'string'
        },
        cost: {
            kind: 'integer'
        }
    }
}

polorizer.polorize(struct, schema)

polorizeDocument(document)

Encodes the Document keys and raw values as POLO doc-encoded data with the wire type being WIRE_DOC. If the Document is nil, it is encoded as a WIRE_NULL.

Arguments:

document (object) – The document object to encode.

// Example
const doc = new Document()
doc.setInteger('far', 123)
doc.setString('foo', 'bar')

polorizer.polorizeDocument(doc.document)

Polorizer.bytes()

Returns the contents of the Polorizer as bytes.

If no objects were polarized, it returns a WIRE_NULL wire. If only one object was polarized, it returns the contents directly. If more than one object was polarized, it returns the contents in a packed wire.

Returns:: Uint8Array – The contents of the Polorizer as bytes.

// Example
const orange = {
    name: 'orange',
    cost: 300,
    alias: ['tangerine', 'mandarin']
}

// Create a new Polorizer
const polorizer = new Polorizer()

// Encode the Name field as a string
polorizer.polorizeString(orange.name)
// Encode the Cost field as an integer
polorizer.polorizeInteger(orange.cost)


// Create a new Polorizer to serialize the Alias field (slice)
const aliases = new Polorizer()
// Encode each element in the Alias slice as a string
orange.alias.forEach((alias) => aliases.polorizeString(alias))
// Encode the Polorizer containing the alias field contents as
// packed data
polorizer.polorizePacked(aliases)

// Print the serialized bytes in the Polorizer buffer
console.log(polorizer.bytes())

// Output:
// [14 79 6 99 142 1 111 114 97 110 103 101 1 44 63 6 150 1 116 97 110
// 103 101 114 105 110 101 109 97 110 100 97 114 105 110]

packed()

Returns the contents of the Polorizer as bytes after packing it and tagging with WIRE_PACK.

Returns:: Uint8Array – The packed contents of the Polorizer as bytes.

// Example
polorizer.polorizeString('foo')

console.log(polorizer.packed())

// Output:
// [14, 31, 6, 102, 111, 111]

Depolorizer

The Depolorizer class is a decoding buffer that can sequentially depolorize objects from it. It can check whether there are elements left in the buffer with isDone(), and peek the WireType of the next element with read().

// Creating a new Depolorizer
const depolorizer = new Depolorizer(new Uint8Array([ 14, ... ]));

parameters

data - Uint8Array: The polo encoded data.
load - LoadReader: The read-only buffer that is obtained from a compound wire (pack).

methods

depolorizeNull()

Decodes a null value from the Depolorizer, consuming one wire element. Returns null if a null value is successfully decoded.

Throws:: Error – If there are no elements left or if the element is not of type WireNull.
Returns:: null – The decoded null value.

// Example
depolorizer.depolorizeNull()
>> null

depolorizeBool()

Decodes a boolean value from the Depolorizer, consuming one wire element. Returns the decoded boolean value. Returns false if the element is of type WireNull.

Throws:: Error – If there are no elements left or if the element is not of type WireTrue or WireFalse.
Returns:: boolean – The decoded boolean value.

// Example
depolorizer.depolorizeBool()
>> true

depolorizeInteger()

Decodes an integer value from the Depolorizer, consuming one wire element. Returns the decoded integer value as either a number or a bigint, depending on the value’s size.

Throws:: Error – If there are no elements left or if the element is not of type WirePosInt or WireNegInt.
Returns:: number|bigint – The decoded integer value.

// Example
depolorizer.depolorizeInteger()
>> 300

depolorizeFloat()

Decodes a float value from the Depolorizer, consuming one wire element. Returns the decoded float value as a number. Returns 0 if the element is a WireNull.

Throws:: Error – If there are no elements left or if the element is not of type WireFloat.
Returns:: number – The decoded float value.

// Example
depolorizer.depolorizeFloat()
>> 123.456

depolorizeString()

Decodes a string value from the Depolorizer, consuming one wire element. Returns the decoded string value. Returns an empty string if the element is a WireNull.

Throws:: Error – If there are no elements left or if the element is not of type WireWord.
Returns:: string – The decoded string value.

// Example
depolorizer.depolorizeString()
>> foo

depolorizeRaw()

Decodes a Raw value from the Depolorizer, consuming one wire element. Returns the decoded Raw value.

Throws:: Error – If there are no elements left or if the element is not of type WireRaw.
Returns:: Raw – The decoded Raw value.

// Example
depolorizer.depolorizeRaw()
>> new Raw([6, 98, 111, 111])

depolorizeBytes()

Decodes a Uint8Array (bytes) value from the Depolorizer, consuming one wire element. Returns the decoded Uint8Array (bytes) value.

Throws:: Error – If there are no elements left or if the element is not of type WireWord.
Returns:: Uint8Array – The decoded Uint8Array (bytes) value.

// Example
depolorizer.depolorizeBytes()
>> new Uint8Array([1, 1, 1, 1])

depolorizePacked()

DepolorizePacked Decodes another Depolorizer from the Depolorizer, consuming one wire element.

Throws:: Error – If there are no elements left, if the element is not WirePack or WireDoc, or if it is a WireNull.
Returns:: Depolorizer – The depolorized packed Depolorizer.

// Example
depolorizer.depolorizePacked()
>> Depolorizer

depolorizeInner()

Decodes another Depolorizer from the Depolorizer, consuming one wire element.

Unlike DepolorizePacked, which expects a compound element and converts it into a packed Depolorizer. DepolorizeInner returns the atomic element as an atomic Depolorizer.

Throws:: Error – If there are no elements left or if the element is not a valid wire element.
Returns:: Depolorizer – The depolorized inner Depolorizer.

// Example
depolorizer.depolorizeInner()
>> new Uint8Array(6, ...)

depolorize(schema)

Decodes a value from the Depolorizer based on the provided schema.

Arguments:

schema (Schema) – The schema representing the type of the value to decode.

Throws:

Error – If the schema kind is unsupported or a decode error occurs.

Returns:

unknown – The decoded value.

depolorize array

// Example
const schema = {
    kind: 'array',
    fields: {
        values: {
            kind: 'string'
        }
    }
}

polorizer.depolorize(schema)
>> ["foo", "bar"]

depolorize map

// Example
const schema = {
    kind: 'map',
    fields: {
        keys: {
            kind: 'integer'
        },
        values: {
            kind: 'string'
        }
    }
}

const map = polorizer.depolorize(schema)
map.get(0)
>> foo
map.get(1)
>> bar

depolorize struct

// Example
const schema = {
    kind: 'struct',
    fields: {
        name: {
            kind: 'string'
        },
        cost: {
            kind: 'integer'
        }
    }
}

polorizer.depolorize(schema)
>> { name: 'orange', cost: 300 }

depolorizeDocument()

Depolorizes a Document from the Depolorizer.

Throws:: Error – If there are no elements left or if the element is not WireDoc.
Returns:: Document – The depolorized Document.

// Example
depolorizer.depolorize()
>> Document

isDone()

Checks if all elements in the Depolorizer have been read.

Returns:: boolean – True if all elements have been read, false otherwise.

// Example
depolorizer.isDone()
>> false

Depolorizer.read()

Reads the next element in the Depolorizer as a ReadBuffer. If the Depolorizer is in packed mode, it reads from the pack buffer. Otherwise, it returns the data from the read buffer and sets the done flag.

Throws:: Error – If there is insufficient data in the wire for decoding.
Returns:: ReadBuffer – The next element in the Depolorizer as a ReadBuffer.

// Example
depolorizer.read()
>> ReadBuffer

Document

The Document class is a representation for a string indexed collection of encoded object data. It represents an intermediary access format with objects settable/gettable with string keys.

// Creating a new Document
const doc = new Document()

parameters

data - Uint8Array (Optional): The polo encoded data.
schema - Schema (Optional): The polo schema that describes the data and its encoding.

methods

setNull(key)

Sets the encoded data associated with the specified key to represent a null value.

Arguments:

key – The key to set.

// Example
doc.setNull("foo")

setBool(key, data)

Sets the encoded data associated with the specified key to represent a boolean value.

Arguments:

key – The key to set.
data – The boolean value to set.

// Example
doc.setBool("foo", true)

setInteger(key, data)

Sets the encoded data associated with the specified key to represent an integer value.

Arguments:

key – The key to set.
data – The integer value to set.

// Example
doc.setInteger("foo", 300)

setFloat(key, data)

Sets the encoded data associated with the specified key to represent a float value.

Arguments:

key – The key to set.
data – The float value to set.

// Example
doc.setFloat("foo", 123.456)

setString(key, data)

Sets the encoded data associated with the specified key to represent a string value.

Arguments:

key – The key to set.
data – The string value to set.

// Example
doc.setString("foo", "bar")

setRaw(key, data)

Sets the encoded data associated with the specified key to represent a raw value.

Arguments:

key – The key to set.
data – The raw value to set.

// Example
doc.setRaw("foo", new Raw([6, 98, 111, 111]))

setBytes(key, data)

Sets the encoded data associated with the specified key to represent a byte array value.

Arguments:

key – The key to set.
data – The byte array value to set.

// Example
doc.setBytes("foo", new Uint8Array([1, 1, 1, 1]))

setArray(key, array, schema)

Sets the encoded data associated with the specified key to represent a array value.

Arguments:

key – The key to set.
array – The array value to set.
schema – The schema used to encode the array elements.

// Example
const arr = ["foo", "bar"]
const schema = {
    kind: 'array',
    fields: {
        values: {
            kind: 'string'
        }
    }
}

doc.setArray("foo", arr, schema)

setMap(key, map, schema)

Sets the encoded data associated with the specified key to represent a map value.

Arguments:

key – The key to set.
map – The map value to set.
schema – The schema used to encode the map keys and values.

// Example
const map = new Map()
map.set(0, "foo")
map.set(1, "bar")

const schema = {
    kind: 'map',
    fields: {
        keys: {
            kind: 'integer'
        },
        values: {
            kind: 'string'
        }
    }
}

doc.setMap("foo", map, schema)

setStruct(key, struct, schema)

Sets the encoded data associated with the specified key to represent a struct value.

Arguments:

key – The key to set.
struct – The struct value to set.
schema – The schema used to encode the struct fields.

// Example
const struct = {
    name: 'orange',
    cost: 300,
}

const schema = {
    kind: 'struct',
    fields: {
        name: {
            kind: 'string'
        },
        cost: {
            kind: 'integer'
        }
    }
}

doc.setStruct("foo", struct, schema)

getNull(key)

Retrieves a null value associated with the specified key from the Document.

Arguments:

key – The key of the null value to retrieve.

Returns:

null – The null value associated with the specified key, or null if the key does not exist.

// Example
doc.getNull("foo")
>> null

getBool(key)

Retrieves a boolean value associated with the specified key from the Document.

Arguments:

key – The key of the boolean value to retrieve.

Returns:

boolean – The boolean value associated with the specified key, or false if the key does not exist.

// Example
doc.getBool("foo")
>> true

getInteger(key)

Retrieves an integer value associated with the specified key from the Document.

Arguments:

key – The key of the integer value to retrieve.

Returns:

number|bigint – The integer value associated with the specified key, or 0 if the key does not exist.

// Example
doc.getInteger("foo")
>> 300

getFloat(key)

Retrieves a float value associated with the specified key from the Document.

Arguments:

key – The key of the float value to retrieve.

Returns:

number – The float value associated with the specified key, or 0 if the key does not exist.

// Example
doc.getFloat("foo")
>> 123.456

getString(key)

Retrieves a string value associated with the specified key from the Document.

Arguments:

key – The key of the string value to retrieve.

Returns:

string – The string value associated with the specified key, or an empty string if the key does not exist.

// Example
doc.getString("foo")
>> bar

getRaw(key)

Retrieves a raw value associated with the specified key from the Document.

Arguments:

key – The key of the raw value to retrieve.

Returns:

Raw – The raw value associated with the specified key, or null if the key does not exist.

// Example
doc.getRaw("foo")
>> new Raw([6, 98, 111, 111])

getBytes(key)

Retrieves a byte array value associated with the specified key from the Document.

Arguments:

key – The key of the byte array value to retrieve.

Returns:

Uint8Array – The byte array value associated with the specified key, or an empty Uint8Array if the key does not exist.

// Example
doc.getBytes("foo")
>> new Uint8Array([1, 1, 1, 1])

getArray(key, schema)

Retrieves an array value associated with the specified key from the Document.

Arguments:

key – The key of the array value to retrieve.
schema – The schema used to decode the array elements.

Returns:

Array – The array value associated with the specified key, or an empty array if the key does not exist.

// Example
const schema = {
    kind: 'array',
    fields: {
        values: {
            kind: 'string'
        }
    }
}

doc.getArray("foo", schema)
>> ["foo", "bar"]

getMap(key, schema)

Retrieves a map value associated with the specified key from the Document.

Arguments:

key – The key of the map value to retrieve.
schema – The schema used to decode the map keys and values.

Returns:

Map – The map value associated with the specified key, or an empty map if the key does not exist.

// Example
const schema = {
    kind: 'map',
    fields: {
        keys: {
            kind: 'integer'
        },
        values: {
            kind: 'string'
        }
    }
}

const map = doc.getMap("foo", schema)
map.get(0)
>> foo
map.get(1)
>> bar

getStruct(key, schema)

Retrieves a struct value associated with the specified key from the Document.

Arguments:

key – The key of the struct value to retrieve.
schema – The schema used to decode the struct fields.

Returns:

object – The struct value associated with the specified key, or an empty object if the key does not exist.

// Example
const schema = {
    kind: 'struct',
    fields: {
        name: {
            kind: 'string'
        },
        cost: {
            kind: 'integer'
        }
    }
}

doc.getStruct("foo", schema)
>> { name: 'orange', cost: 300 }

Document.is(key, kind)

Checks if the encoded data associated with the specified key in the Document has the specified WireType.

Arguments:

key – The key to check.
kind – The WireType to compare against.

Returns:

boolean – True if the encoded data has the specified WireType, false otherwise.

// Example
doc.is("foo", WIRE_STRING)
>> true

Document.size()

Returns the number of key-value pairs in the Document.

Returns:: number – The number of key-value pairs in the Document.

// Example
doc.size()
>> 5

Document.bytes()

Returns the encoded data of the Document as a Uint8Array.

Returns:: Uint8Array – The encoded data of the Document.

// Example
doc.bytes()
>> new Uint8Array([14 79 6 99 142 1 111 114 97 110 103 101 1 44 63 6 150 1
116 97 110 103 101 114 105 110 101 109 97 110 100 97 114 105 110])

functions

documentEncode(obj, schema)

Encodes an object or map into a Document using the provided schema.

Arguments:

obj – The object or map to encode.
schema – The schema used for encoding.

Throws:

Error – If the provided schema kind is unsupported.

Returns:

Document – The encoded Document.

// Example
const orange = {
    name: 'orange',
    cost: 300,
    alias: ['tangerine', 'mandarin']
}

const schema = {
    kind: 'struct',
    fields: {
        name: { kind: 'string' },
        cost: { kind: 'integer' },
        alias: {
            kind: 'array',
            fields: {
                values: { kind: 'string' }
            }
        }
    }
}

// Encode the object into a Document
const document = documentEncode(orange, schema)

console.log(document.data)
console.log(document.bytes())

// Output:
/*
    {
        name: Raw {
            bytes: Uint8Array(7) [
                6, 111, 114, 97,110, 103, 101
            ]
        },
        cost: Raw { bytes: Uint8Array(3) [ 3, 1, 44 ] },
        alias: Raw {
            bytes: Uint8Array(22) [
                14, 63, 6, 150, 1, 116,
                97, 110, 103, 101, 114, 105,
                110, 101, 109,  97, 110, 100,
                97, 114, 105, 110
            ]
        }
    }
*/

/*
    [
        13, 175, 1, 6, 85, 182, 3, 245, 3, 166, 4,
        229, 4, 97, 108, 105, 97, 115, 14, 63, 6, 150,
        1, 116, 97, 110, 103, 101, 114, 105, 110, 101, 109,
        97, 110, 100, 97, 114, 105, 110, 99, 111, 115, 116,
        3, 1, 44, 110, 97, 109, 101, 6, 111, 114,  97,
        110, 103, 101
    ]
*/

documentDecode(data)

Decodes a Document from the provided ReadBuffer.

Arguments:

data – The ReadBuffer containing the encoded Document data.

Throws:

Error – If the provided wire type is unsupported.

Returns:

Document – The decoded Document.

// Example
const wire = new Uint8Array([
    13, 175, 1, 6, 85, 182, 3, 245, 3, 166, 4, 229, 4, 97, 108, 105,
    97, 115, 14, 63, 6, 150, 1, 116, 97, 110, 103, 101, 114, 105, 110,
    101, 109, 97, 110, 100, 97, 114, 105, 110, 99, 111, 115, 116,
    3, 1, 44, 110, 97, 109, 101, 6, 111, 114,  97, 110, 103, 101
])

const schema = {
    kind: 'struct',
    fields: {
        name: { kind: 'string' },
        cost: { kind: 'integer' },
        alias: {
            kind: 'array',
            fields: {
                values: { kind: 'string' }
            }
        }
    }
}

const depolorizer = new Depolorizer(wire)
const readBuffer = depolorizer.read()
const doc = documentDecode(readBuffer)
console.log(doc.data)

// Output:
// {
//  name: Uint8Array(7) [
//          6, 111, 114, 97,
//    110, 103, 101
//  ],
//  cost: Uint8Array(3) [ 3, 1, 44 ],
//  alias: Uint8Array(22) [
//          14,  63,   6, 150,   1, 116,
//          97, 110, 103, 101, 114, 105,
//     110, 101, 109,  97, 110, 100,
//          97, 114, 105, 110
//   ],
// }