Serializer

new Serializer

new Serializer() is the main class used for working with encodexx. It is responsible for encoding and decoding schemas.

new Serializer(schema, options?)

Parameters

• schema – the schema that describes the serializable object
• options? – optional settings that add extra schema checks for the object being serialized:
  • strict?: boolean – enables type checks and throws an error if the types do not match. Defaults to false
  • version?: string – adds a version tag to the final buffer. If the version tag does not match during deserialization, an error is thrown.
  • resetCursor?: boolean – automatically resets the cursor during encoding and decoding. This option is necessary for implementing advanced custom types, but is not required for typical use. Defaults to true

Usage

Creation

Create a Serializer instance and pass in the required types.

import { Serializer, t } from "encodexx";

const serializer = new Serializer([t.int8], {
  strict: true,
  version: "2.32.1"
})

As you can see, you can serialize not only objects but also arrays and even individual types. Since we enabled the strict setting, trying to encode anything other than an array of int8 will result in an error.

serializer.encode([100_000]) // TypeMatchError [TypeError]
serializer.encode(["Some string"]) // TypeMatchError [TypeError]

Serialization

The .encode() method is used to serialize objects.

.encode(obj: TConvertValueToType<T>, buff?: DataBuffer): DataBuffer;

• obj – the object to serialize
• buff? – the buffer that will hold the result. If not provided, a new buffer is created.

const obj = Array.from({length: 100}, () => Math.floor((Math.random() * 8)))

const encoded = serializer.encode(obj);
console.log(encoded.buffer)

Deserialization

The .decode() method is used for deserialization.

decode(buff: DataBuffer | ArrayBuffer | Uint8Array): TConvertValueToType<T>;

• buff – the buffer to decode

console.log(serializer.decode(encoded))

Validating an Object Against a Schema

To check if an object conforms to the schema, use the .guard(obj) method:

const obj = [1, 2, 3, 4, 5];

serializer.guard(obj) // true
serializer.guard("Some string") // false

Typing

Encodexx provides a schema type that you can leverage in your projects. To extract the type, use the helper type ExtractObj:

import { Serializer, t, ExtractObj } from "encodexx"

const serializer = new Serializer({
  name: t.or(t.int8, t.string, t.date),
  age: t.optional(t.uint8)
})

type TSchemaType = ExtractObj<typeof serializer>

// TSchemaType is: { name: number | string | Date, age?: number }

import { ArraySingle, t, Serializer } from "encodexx"
const schema = { arr: [t.int8] }

new Serializer(schema as ArraySingle<typeof schema>)

Learn more about Typing

Serializer.equal(schema1, schema2)

The static method Serializer.equal(schema1, schema2): boolean allows you to compare two schemas.

const schema1 = {
  name: t.str,
  age: t.uint8,
}

const schema2 = {
  age: t.uint8,
  name: t.str,
}

Serializer.equal(schema1, schema2) // true

const schema1 = {
  age: t.or(t.str, t.int8, t.float64),
}

const schema2 = {
  age: t.or(t.float64, t.str, t.int8),
}

Serializer.equal(schema1, schema2) // false