Codecs

Introduction

Kit includes a powerful serialisation system called Codecs. Whether you're working with account data, instruction arguments, or custom binary layouts, Codecs give you the tools to transform structured data into bytes — and back again.

Codecs are composable, type-safe, and environment-agnostic. They are designed to provide a flexible and consistent foundation for handling binary data across the Solana stack.

Installation

Codecs are included within the @solana/kit library but you may also install them using their standalone package.

npm install @solana/codecs

Note that the @solana/codecs package itself is composed of several smaller packages, each providing a different set of codec helpers. Here's the list of all packages containing codecs, should you need to install them individually:

What is a Codec?

A Codec is an object that knows how to encode a any type into a Uint8Array and how to decode a Uint8Array back into that value.

No matter which serialization strategy we use, Codecs abstract away its implementation and offer a simple encode and decode interface. They are also highly composable, allowing us to build complex data structures from simple building blocks.

Here's a quick example that encodes and decodes a simple Person type.

// Use composable codecs to build complex data structures.
type Person = { name: string; age: number };
const getPersonCodec = (): Codec<Person> =>
    getStructCodec([
        ['name', addCodecSizePrefix(getUtf8Codec(), getU32Codec())],
        ['age', getU32Codec()],
    ]);
 
// Use your own codecs to encode and decode data.
const personCodec = getPersonCodec();
const encodedPerson = personCodec.encode({ name: 'John', age: 42 });
const decodedPerson = personCodec.decode(encodedPerson);

Composing codecs

The easiest way to create your own codecs is to compose the various codecs at your disposal.

For instance, consider the following codecs available:

• getStructCodec: Creates a codec for objects with named fields.
• getU32Codec: Creates a codec for unsigned 32-bit integers.
• getUtf8Codec: Creates a codec for UTF-8 strings.
• addCodecSizePrefix: Creates a codec that prefixes the encoded data with its length.
• getBooleanCodec: Creates a codec for booleans using a single byte.

By combining them together we can create a custom codec for the following Person type.

type Person = {
    name: string;
    age: number;
    verified: boolean;
};
 
const getPersonCodec = (): Codec<Person> =>
    getStructCodec([
        ['name', addCodecSizePrefix(getUtf8Codec(), getU32Codec())],
        ['age', getU32Codec()],
        ['verified', getBooleanCodec()],
    ]);

This function returns a Codec object which contains both an encode and decode function that can be used to convert a Person type to and from a Uint8Array.

const personCodec = getPersonCodec();
const bytes = personCodec.encode({ name: 'John', age: 42, verified: true });
const person = personCodec.decode(bytes);

There is a significant library of composable codecs at your disposal, enabling you to compose complex types. Check out the available codecs section for more information. If you need a custom codec that cannot be composed from existing ones, you can always create your own as we will see in the "Creating custom codecs" section below.

Separate encoders and decoders

Whilst Codecs can both encode and decode, it is possible to only focus on encoding or decoding data, enabling the unused logic to be tree-shaken. For instance, here's our previous example using Encoders only to encode a Person type.

const getPersonEncoder = (): Encoder<Person> =>
    getStructEncoder([
        ['name', addEncoderSizePrefix(getUtf8Encoder(), getU32Encoder())],
        ['age', getU32Encoder()],
        ['verified', getBooleanEncoder()],
    ]);
 
const bytes = getPersonEncoder().encode({ name: 'John', age: 42, verified: true });

The same can be done for decoding the Person type by using Decoders like so.

const getPersonDecoder = (): Decoder<Person> =>
    getStructDecoder([
        ['name', addDecoderSizePrefix(getUtf8Decoder(), getU32Decoder())],
        ['age', getU32Decoder()],
        ['verified', getBooleanDecoder()],
    ]);
 
const person = getPersonDecoder().decode(bytes);

Combining encoders and decoders

Separating Codecs into Encoders and Decoders is particularly good practice for library maintainers as it allows their users to tree-shake any of the encoders and/or decoders they don't need. However, we may still want to offer a codec helper for users who need both for convenience.

That's why this library offers a combineCodec helper that creates a Codec instance from a matching Encoder and Decoder.

const getPersonCodec = (): Codec<Person> => combineCodec(getPersonEncoder(), getPersonDecoder());

This means library maintainers can offer Encoders, Decoders and Codecs for all their types whilst staying efficient and tree-shakeable. In summary, we recommend the following pattern when creating codecs for library types.

type MyType = /* ... */;
const getMyTypeEncoder = (): Encoder<MyType> => { /* ... */ };
const getMyTypeDecoder = (): Decoder<MyType> => { /* ... */ };
const getMyTypeCodec = (): Codec<MyType> => combineCodec(
    getMyTypeEncoder(),
    getMyTypeDecoder(),
);

Different From and To types

When creating codecs, the encoded type is allowed to be looser than the decoded type. A good example of that is the u64 number codec:

const u64Codec: Codec<number | bigint, bigint> = getU64Codec();

As you can see, the first type parameter is looser since it accepts numbers or big integers, whereas the second type parameter only accepts big integers. That's because when encoding a u64 number, you may provide either a bigint or a number for convenience. However, when you decode a u64 number, you will always get a bigint because not all u64 values can fit in a JavaScript number type.

const bytes = u64Codec.encode(42);
const value = u64Codec.decode(bytes); // BigInt(42)

This relationship between the type we encode “From” and decode “To” can be generalized in TypeScript as To extends From.

Here's another example using an object with default values. You can read more about the transformCodec helper below.

type Person = { name: string; age: number };
type PersonInput = { name: string; age?: number };
 
const getPersonEncoder = (): Encoder<PersonInput> =>
    transformEncoder(
        getStructEncoder([
            ['name', addEncoderSizePrefix(getUtf8Encoder(), getU32Encoder())],
            ['age', getU32Encoder()],
        ]),
        (input) => ({ ...input, age: input.age ?? 42 }),
    );
 
const getPersonDecoder = (): Decoder<Person> =>
    getStructDecoder([
        ['name', addDecoderSizePrefix(getUtf8Decoder(), getU32Decoder())],
        ['age', getU32Decoder()],
    ]);
 
const getPersonCodec = (): Codec<PersonInput, Person> =>
    combineCodec(getPersonEncoder(), getPersonDecoder());

Fixed-size and variable-size codecs

It is also worth noting that Codecs can either be of fixed size or variable size.

FixedSizeCodecs have a fixedSize number attribute that tells us exactly how big their encoded data is in bytes.

const myCodec = getU32Codec();
myCodec satisfies FixedSizeCodec<number>;
myCodec.fixedSize; // 4 bytes.

On the other hand, VariableSizeCodecs do not know the size of their encoded data in advance. Instead, they will grab that information either from the provided encoded data or from the value to encode. For the former, we can simply access the length of the Uint8Array. For the latter, it provides a getSizeFromValue that tells us the encoded byte size of the provided value.

const myCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
myCodec satisfies VariableSizeCodec<string>;
myCodec.getSizeFromValue('hello world'); // 4 + 11 bytes.

Also note that, if the VariableSizeCodec is bounded by a maximum size, it can be provided as a maxSize number attribute.

The following type guards are available to identify and/or assert the size of codecs: isFixedSize, isVariableSize, assertIsFixedSize and assertIsVariableSize.

Finally, note that the same is true for Encoders and Decoders.

• A FixedSizeEncoder has a fixedSize number attribute.
• A VariableSizeEncoder has a getSizeFromValue function and an optional maxSize number attribute.
• A FixedSizeDecoder has a fixedSize number attribute.
• A VariableSizeDecoder has an optional maxSize number attribute.

Creating custom codecs

If composing codecs isn't enough for you, you may implement your own codec logic by using the createCodec function. This function requires an object with a read and a write function telling us how to read from and write to an existing byte array.

The read function accepts the bytes to decode from and the offset at each we should start reading. It returns an array with two items:

• The first item should be the decoded value.
• The second item should be the next offset to read from.

createCodec({
    read(bytes, offset) {
        const value = bytes[offset];
        return [value, offset + 1];
    },
    write,
    fixedSize,
});

Reciprocally, the write function accepts the value to encode, the array of bytes to write the encoded value to and the offset at which it should be written. It should encode the given value, insert it in the byte array, and provide the next offset to write to as the return value.

createCodec({
    write(value: number, bytes, offset) {
        bytes.set([value], offset);
        return offset + 1;
    },
    read,
    fixedSize,
});

Additionally, we must specify the size of the codec. If we are defining a FixedSizeCodec, we must simply provide the fixedSize number attribute. For VariableSizeCodecs, we must provide the getSizeFromValue function as described in the previous section.

// FixedSizeCodec.
createCodec({
    fixedSize: 1,
    read,
    write,
});
 
// VariableSizeCodec.
createCodec({
    getSizeFromValue: (value: string) => value.length,
    read,
    write,
});

Here's a concrete example of a custom codec that encodes any unsigned integer in a single byte. Since a single byte can only store integers from 0 to 255, if any other integer is provided it will take its modulo 256 to ensure it fits in a single byte. Because it always requires a single byte, that codec is a FixedSizeCodec of size 1.

import { createCodec } from '@solana/kit';
 
const getModuloU8Codec = () =>
    createCodec<number>({
        fixedSize: 1,
        read(bytes, offset) {
            const value = bytes[offset];
            return [value, offset + 1];
        },
        write(value, bytes, offset) {
            bytes.set([value % 256], offset);
            return offset + 1;
        },
    });

Note that, it is also possible to create custom encoders and decoders separately by using the createEncoder and createDecoder functions respectively and then use the combineCodec function on them just like we were doing with composed codecs.

This approach is recommended to library maintainers as it allows their users to tree-shake any of the encoders and/or decoders they don't need.

Here's our previous modulo u8 example but split into separate Encoder, Decoder and Codec instances.

import { createEncoder, createDecoder, combineCodec } from '@solana/kit';
 
const getModuloU8Encoder = () =>
    createEncoder<number>({
        fixedSize: 1,
        write(value, bytes, offset) {
            bytes.set([value % 256], offset);
            return offset + 1;
        },
    });
 
const getModuloU8Decoder = () =>
    createDecoder<number>({
        fixedSize: 1,
        read(bytes, offset) {
            const value = bytes[offset];
            return [value, offset + 1];
        },
    });
 
const getModuloU8Codec = () => combineCodec(getModuloU8Encoder(), getModuloU8Decoder());

Here's another example returning a VariableSizeCodec. This one transforms a simple string composed of characters from a to z to a buffer of numbers from 1 to 26 where 0 bytes are spaces.

import { createEncoder, createDecoder, combineCodec } from '@solana/kit';
 
const alphabet = ' abcdefghijklmnopqrstuvwxyz';
 
const getCipherEncoder = () =>
    createEncoder<string>({
        getSizeFromValue: (value) => value.length,
        write(value, bytes, offset) {
            const bytesToAdd = [...value].map((char) => alphabet.indexOf(char));
            bytes.set(bytesToAdd, offset);
            return offset + bytesToAdd.length;
        },
    });
 
const getCipherDecoder = () =>
    createDecoder<string>({
        read(bytes, offset) {
            const value = [...bytes.slice(offset)].map((byte) => alphabet.charAt(byte)).join('');
            return [value, bytes.length];
        },
    });
 
const getCipherCodec = () => combineCodec(getCipherEncoder(), getCipherDecoder());

Available codecs

Core utilities

Numbers

Strings

Data structures

Core utilities listing

addCodecSentinel

One way of delimiting the size of a codec is to use sentinels. The addCodecSentinel function allows us to add a sentinel to the end of the encoded data and to read until that sentinel is found when decoding. It accepts any codec and a Uint8Array sentinel responsible for delimiting the encoded data.

const codec = addCodecSentinel(getUtf8Codec(), new Uint8Array([255, 255]));
codec.encode('hello');
// 0x68656c6c6fffff
//   |        └-- Our sentinel.
//   └-- Our encoded string.

Note that the sentinel must not be present in the encoded data and must be present in the decoded data for this to work. If this is not the case, dedicated errors will be thrown.

const sentinel = new Uint8Array([108, 108]); // 'll'
const codec = addCodecSentinel(getUtf8Codec(), sentinel);
 
codec.encode('hello'); // Throws: sentinel is in encoded data.
codec.decode(new Uint8Array([1, 2, 3])); // Throws: sentinel missing in decoded data.

Separate addEncoderSentinel and addDecoderSentinel functions are also available.

const bytes = addEncoderSentinel(getUtf8Encoder(), sentinel).encode('hello');
const value = addDecoderSentinel(getUtf8Decoder(), sentinel).decode(bytes);

addCodecSizePrefix

The addCodecSizePrefix function allows us to store the byte size of any codec as a number prefix, enabling us to contain variable-size codecs to their actual size.

When encoding, the size of the encoded data is stored before the encoded data itself. When decoding, the size is read first to know how many bytes to read next.

For example, say we want to represent a variable-size base-58 string using a u32 size prefix. Here's how we can use the addCodecSizePrefix function to achieve that.

const getU32Base58Codec = () => addCodecSizePrefix(getBase58Codec(), getU32Codec());
 
getU32Base58Codec().encode('hello world');
// 0x0b00000068656c6c6f20776f726c64
//   |       └-- Our encoded base-58 string.
//   └-- Our encoded u32 size prefix.

You may also use the addEncoderSizePrefix and addDecoderSizePrefix functions to separate your codec logic like so:

const getU32Base58Encoder = () => addEncoderSizePrefix(getBase58Encoder(), getU32Encoder());
const getU32Base58Decoder = () => addDecoderSizePrefix(getBase58Decoder(), getU32Decoder());
const getU32Base58Codec = () => combineCodec(getU32Base58Encoder(), getU32Base58Decoder());

containsBytes

Checks if a Uint8Array contains another Uint8Array at a given offset.

containsBytes(new Uint8Array([1, 2, 3, 4]), new Uint8Array([2, 3]), 1); // true
containsBytes(new Uint8Array([1, 2, 3, 4]), new Uint8Array([2, 3]), 2); // false

fixBytes

Pads or truncates a Uint8Array so it has the specified length.

fixBytes(new Uint8Array([1, 2]), 4); // Uint8Array([1, 2, 0, 0])
fixBytes(new Uint8Array([1, 2, 3, 4]), 2); // Uint8Array([1, 2])

fixCodecSize

The fixCodecSize function allows us to bind the size of a given codec to the given fixed size.

For instance, say we wanted to represent a base-58 string that uses exactly 32 bytes when decoded. Here's how we can use the fixCodecSize helper to achieve that.

const get32BytesBase58Codec = () => fixCodecSize(getBase58Codec(), 32);

You may also use the fixEncoderSize and fixDecoderSize functions to separate your codec logic like so:

const get32BytesBase58Encoder = () => fixEncoderSize(getBase58Encoder(), 32);
const get32BytesBase58Decoder = () => fixDecoderSize(getBase58Decoder(), 32);
const get32BytesBase58Codec = () =>
    combineCodec(get32BytesBase58Encoder(), get32BytesBase58Decoder());

mergeBytes

Concatenates an array of Uint8Arrays into a single Uint8Array.

const bytes1 = new Uint8Array([0x01, 0x02]);
const bytes2 = new Uint8Array([]);
const bytes3 = new Uint8Array([0x03, 0x04]);
const bytes = mergeBytes([bytes1, bytes2, bytes3]);
//    ^ [0x01, 0x02, 0x03, 0x04]

offsetCodec

The offsetCodec function is a powerful codec primitive that allows us to move the offset of a given codec forward or backwards. It accepts one or two functions that takes the current offset and returns a new offset.

To understand how this works, let's take the following biggerU32Codec example which encodes a u32 number inside an 8-byte buffer by using the resizeCodec helper.

const biggerU32Codec = resizeCodec(getU32Codec(), (size) => size + 4);
biggerU32Codec.encode(0xffffffff);
// 0xffffffff00000000
//   |       └-- Empty buffer space caused by the resizeCodec function.
//   └-- Our encoded u32 number.

Now, let's say we want to move the offset of that codec 2 bytes forward so that the encoded number sits in the middle of the buffer. To achieve, this we can use the offsetCodec helper and provide a preOffset function that moves the "pre-offset" of the codec 2 bytes forward.

const u32InTheMiddleCodec = offsetCodec(biggerU32Codec, {
    preOffset: ({ preOffset }) => preOffset + 2,
});
u32InTheMiddleCodec.encode(0xffffffff);
// 0x0000ffffffff0000
//       └-- Our encoded u32 number is now in the middle of the buffer.

We refer to this offset as the "pre-offset" because, once the inner codec is encoded or decoded, an additional offset will be returned which we refer to as the "post-offset". That "post-offset" is important as, unless we are reaching the end of our codec, it will be used by any further codecs to continue encoding or decoding data.

By default, that "post-offset" is simply the addition of the "pre-offset" and the size of the encoded or decoded inner data.

const u32InTheMiddleCodec = offsetCodec(biggerU32Codec, {
    preOffset: ({ preOffset }) => preOffset + 2,
});
u32InTheMiddleCodec.encode(0xffffffff);
// 0x0000ffffffff0000
//   |   |       └-- Post-offset.
//   |   └-- New pre-offset: The original pre-offset + 2.
//   └-- Pre-offset: The original pre-offset before we adjusted it.

However, you may also provide a postOffset function to adjust the "post-offset". For instance, let's push the "post-offset" 2 bytes forward as well such that any further codecs will start doing their job at the end of our 8-byte u32 number.

const u32InTheMiddleCodec = offsetCodec(biggerU32Codec, {
    preOffset: ({ preOffset }) => preOffset + 2,
    postOffset: ({ postOffset }) => postOffset + 2,
});
u32InTheMiddleCodec.encode(0xffffffff);
// 0x0000ffffffff0000
//   |   |       |   └-- New post-offset: The original post-offset + 2.
//   |   |       └-- Post-offset: The original post-offset before we adjusted it.
//   |   └-- New pre-offset: The original pre-offset + 2.
//   └-- Pre-offset: The original pre-offset before we adjusted it.

Both the preOffset and postOffset functions offer the following attributes:

• bytes: The entire byte array being encoded or decoded.
• preOffset: The original and unaltered pre-offset.
• wrapBytes: A helper function that wraps the given offset around the byte array length. E.g. wrapBytes(-1) will refer to the last byte of the byte array.

Additionally, the post-offset function also provides the following attributes:

• newPreOffset: The new pre-offset after the pre-offset function has been applied.
• postOffset: The original and unaltered post-offset.

Note that you may also decide to ignore these attributes to achieve absolute offsets. However, relative offsets are usually recommended as they won't break your codecs when composed with other codecs.

const u32InTheMiddleCodec = offsetCodec(biggerU32Codec, {
    preOffset: () => 2,
    postOffset: () => 8,
});
u32InTheMiddleCodec.encode(0xffffffff);
// 0x0000ffffffff0000

Also note that any negative offset or offset that exceeds the size of the byte array will throw a SolanaError of code SOLANA_ERROR__CODECS__OFFSET_OUT_OF_RANGE.

const u32InTheEndCodec = offsetCodec(biggerU32Codec, { preOffset: () => -4 });
u32InTheEndCodec.encode(0xffffffff);
// throws new SolanaError(SOLANA_ERROR__CODECS__OFFSET_OUT_OF_RANGE)

To avoid this, you may use the wrapBytes function to wrap the offset around the byte array length. For instance, here's how we can use the wrapBytes function to move the pre-offset 4 bytes from the end of the byte array.

const u32InTheEndCodec = offsetCodec(biggerU32Codec, {
    preOffset: ({ wrapBytes }) => wrapBytes(-4),
});
u32InTheEndCodec.encode(0xffffffff);
// 0x00000000ffffffff

As you can see, the offsetCodec helper allows you to jump all over the place with your codecs. This non-linear approach to encoding and decoding data allows you to achieve complex serialization strategies that would otherwise be impossible.

The offsetEncoder and offsetDecoder functions can also be used to split your codec logic into tree-shakeable functions.

const getU32InTheMiddleEncoder = () =>
    offsetEncoder(biggerU32Encoder, { preOffset: ({ preOffset }) => preOffset + 2 });
const getU32InTheMiddleDecoder = () =>
    offsetDecoder(biggerU32Decoder, { preOffset: ({ preOffset }) => preOffset + 2 });
const getU32InTheMiddleCodec = () =>
    combineCodec(getU32InTheMiddleEncoder(), getU32InTheMiddleDecoder());

padBytes

Pads a Uint8Array with zeroes (to the right) to the specified length.

padBytes(new Uint8Array([1, 2]), 4); // Uint8Array([1, 2, 0, 0])
padBytes(new Uint8Array([1, 2, 3, 4]), 2); // Uint8Array([1, 2, 3, 4])

padLeftCodec

The padLeftCodec helper can be used to add padding to the left of a given codec. It accepts an offset number that tells us how big the padding should be.

const leftPaddedCodec = padLeftCodec(getU16Codec(), 4);
leftPaddedCodec.encode(0xffff);
// 0x00000000ffff
//   |       └-- Our encoded u16 number.
//   └-- Our 4-byte padding.

Note that the padLeftCodec function is a simple wrapper around the offsetCodec and resizeCodec functions. For more complex padding strategies, you may want to use the offsetCodec and resizeCodec functions directly instead.

Encoder-only and decoder-only helpers are available for these padding functions.

const getMyPaddedEncoder = () => padLeftEncoder(getU16Encoder(), 6);
const getMyPaddedDecoder = () => padLeftDecoder(getU16Decoder(), 6);
const getMyPaddedCodec = () => combineCodec(getMyPaddedEncoder(), getMyPaddedDecoder());

padRightCodec

The padRightCodec helper can be used to add padding to the right of a given codec. It accepts an offset number that tells us how big the padding should be.

const rightPaddedCodec = padRightCodec(getU16Codec(), 4);
rightPaddedCodec.encode(0xffff);
// 0xffff00000000
//   |   └-- Our 4-byte padding.
//   └-- Our encoded u16 number.

Note that the padRightCodec function is a simple wrapper around the offsetCodec and resizeCodec functions. For more complex padding strategies, you may want to use the offsetCodec and resizeCodec functions directly instead.

Encoder-only and decoder-only helpers are available for these padding functions.

const getMyPaddedEncoder = () => padRightEncoder(getU16Encoder(), 6);
const getMyPaddedDecoder = () => padRightDecoder(getU16Decoder(), 6);
const getMyPaddedCodec = () => combineCodec(getMyPaddedEncoder(), getMyPaddedDecoder());

resizeCodec

The resizeCodec helper re-defines the size of a given codec by accepting a function that takes the current size of the codec and returns a new size. This works for both fixed-size and variable-size codecs.

// Fixed-size codec.
const getBiggerU32Codec = () => resizeCodec(getU32Codec(), (size) => size + 4);
getBiggerU32Codec().encode(42);
// 0x2a00000000000000
//   |       └-- Empty buffer space caused by the resizeCodec function.
//   └-- Our encoded u32 number.
 
// Variable-size codec.
const getBiggerUtf8Codec = () => resizeCodec(getUtf8Codec(), (size) => size + 4);
getBiggerUtf8Codec().encode('ABC');
// 0x41424300000000
//   |     └-- Empty buffer space caused by the resizeCodec function.
//   └-- Our encoded string.

Note that the resizeCodec function doesn't change any encoded or decoded bytes, it merely tells the encode and decode functions how big the Uint8Array should be before delegating to their respective write and read functions. In fact, this is completely bypassed when using the write and read functions directly. For instance:

const getBiggerU32Codec = () => resizeCodec(getU32Codec(), (size) => size + 4);
 
// Using the encode function.
getBiggerU32Codec().encode(42);
// 0x2a00000000000000
 
// Using the lower-level write function.
const myCustomBytes = new Uint8Array(4);
getBiggerU32Codec().write(42, myCustomBytes, 0);
// 0x2a000000

So when would it make sense to use the resizeCodec function? This function is particularly useful when combined with the offsetCodec function. Whilst offsetCodec may help us push the offset forward — e.g. to skip some padding — it won't change the size of the encoded data which means the last bytes will be truncated by how much we pushed the offset forward. The resizeCodec function can be used to fix that. For instance, here's how we can use the resizeCodec and the offsetCodec functions together to create a struct codec that includes some padding.

const personCodec = getStructCodec([
    ['name', fixCodecSize(getUtf8Codec(), 8)],
    // There is a 4-byte padding between name and age.
    [
        'age',
        offsetCodec(
            resizeCodec(getU32Codec(), (size) => size + 4),
            { preOffset: ({ preOffset }) => preOffset + 4 },
        ),
    ],
]);
 
personCodec.encode({ name: 'Alice', age: 42 });
// 0x416c696365000000000000002a000000
//   |               |       └-- Our encoded u32 (42).
//   |               └-- The 4-bytes of padding we are skipping.
//   └-- Our 8-byte encoded string ("Alice").

Note that this can be achieved using the padLeftCodec helper which is implemented that way.

The resizeEncoder and resizeDecoder functions can also be used to split your codec logic into tree-shakeable functions.

const getBiggerU32Encoder = () => resizeEncoder(getU32Encoder(), (size) => size + 4);
const getBiggerU32Decoder = () => resizeDecoder(getU32Decoder(), (size) => size + 4);
const getBiggerU32Codec = () => combineCodec(getBiggerU32Encoder(), getBiggerU32Decoder());

reverseCodec

The reverseCodec helper reverses the bytes of the provided FixedSizeCodec.

const getBigEndianU64Codec = () => reverseCodec(getU64Codec());

Note that number codecs can already do that for you via their endian option.

const getBigEndianU64Codec = () => getU64Codec({ endian: Endian.Big });

The reverseEncoder and reverseDecoder functions can also be used to achieve that.

const getBigEndianU64Encoder = () => reverseEncoder(getU64Encoder());
const getBigEndianU64Decoder = () => reverseDecoder(getU64Decoder());
const getBigEndianU64Codec = () => combineCodec(getBigEndianU64Encoder(), getBigEndianU64Decoder());

transformCodec

It is possible to transform a Codec<T> to a Codec<U> by providing two mapping functions: one that goes from T to U and one that does the opposite.

For instance, here's how you would map a u32 integer into a string representation of that number.

const getStringU32Codec = () =>
    transformCodec(
        getU32Codec(),
        (integerAsString: string): number => parseInt(integerAsString),
        (integer: number): string => integer.toString(),
    );
 
getStringU32Codec().encode('42'); // new Uint8Array([42])
getStringU32Codec().decode(new Uint8Array([42])); // "42"

If a Codec has different From and To types, say Codec<OldFrom, OldTo>, and we want to map it to Codec<NewFrom, NewTo>, we must provide functions that map from NewFrom to OldFrom and from OldTo to NewTo.

To illustrate that, let's take our previous getStringU32Codec example but make it use a getU64Codec codec instead as it returns a Codec<number | bigint, bigint>. Additionally, let's make it so our getStringU64Codec function returns a Codec<number | string, string> so that it also accepts numbers when encoding values. Here's what our mapping functions look like:

const getStringU64Codec = () =>
    transformCodec(
        getU64Codec(),
        (integerInput: number | string): number | bigint =>
            typeof integerInput === 'string' ? BigInt(integerInput) : integerInput,
        (integer: bigint): string => integer.toString(),
    );

Note that the second function that maps the decoded type is optional. That means, you can omit it to simply update or loosen the type to encode whilst keeping the decoded type the same.

This is particularly useful to provide default values to object structures. For instance, here's how we can map a Person codec to give a default value to its age attribute.

type Person = { name: string; age: number };
type PersonInput = { name: string; age?: number };
const getPersonWithDefaultValueCodec = (): Codec<PersonInput, Person> =>
    transformCodec(
        getPersonCodec(),
        (person: PersonInput): Person => ({ ...person, age: person.age ?? 42 }),
    );

Similar helpers exist to map Encoder and Decoder instances allowing you to separate your codec logic into tree-shakeable functions. Here's our getStringU32Codec written that way.

const getStringU32Encoder = () =>
    transformEncoder(getU32Encoder(), (integerAsString: string): number =>
        parseInt(integerAsString),
    );
const getStringU32Decoder = () =>
    transformDecoder(getU32Decoder(), (integer: number): string => integer.toString());
const getStringU32Codec = () => combineCodec(getStringU32Encoder(), getStringU32Decoder());

Numbers listing

getI8Codec

Encodes and decodes signed 8-bit integers. It supports values from -127 (-2^7) to 128 (2^7 - 1).

Values can be provided as either number or bigint, but the decoded value is always a number.

const codec = getI8Codec();
const bytes = codec.encode(-42); // 0xd6
const value = codec.decode(bytes); // -42

getI8Encoder and getI8Decoder functions are also available.

getI16Codec

Encodes and decodes signed 16-bit integers. It supports values from -32,768 (-2^15) to 32,767 (2^15 - 1).

Values can be provided as either number or bigint, but the decoded value is always a number. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getI16Codec();
const bytes = codec.encode(-42); // 0xd6ff
const value = codec.decode(bytes); // -42
 
// Big-endian.
const beCodec = getI16Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(-42); // 0xffd6
const beValue = beCodec.decode(bytes); // -42

getI16Encoder and getI16Decoder functions are also available.

getI32Codec

Encodes and decodes signed 32-bit integers. It supports values from -2,147,483,648 (-2^31) to 2,147,483,647 (2^31 - 1).

Values can be provided as either number or bigint, but the decoded value is always a number. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getI32Codec();
const bytes = codec.encode(-42); // 0xd6ffffff
const value = codec.decode(bytes); // -42
 
// Big-endian.
const beCodec = getI32Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(-42); // 0xffffffd6
const beValue = beCodec.decode(bytes); // -42

getI32Encoder and getI32Decoder functions are also available.

getI64Codec

Encodes and decodes signed 64-bit integers. It supports values from -2^63 to 2^63 - 1.

Values can be provided as either number or bigint, but the decoded value is always a bigint. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getI64Codec();
const bytes = codec.encode(-42); // 0xd6ffffffffffffff
const value = codec.decode(bytes); // BigInt(-42)
 
// Big-endian.
const beCodec = getI64Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(-42); // 0xffffffffffffffd6
const beValue = beCodec.decode(bytes); // BigInt(-42)

getI64Encoder and getI64Decoder functions are also available.

getI128Codec

Encodes and decodes signed 128-bit integers. It supports values from -2^127 to 2^127 - 1.

Values can be provided as either number or bigint, but the decoded value is always a bigint. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getI128Codec();
const bytes = codec.encode(-42); // 0xd6ffffffffffffffffffffffffffffff
const value = codec.decode(bytes); // BigInt(-42)
 
// Big-endian.
const beCodec = getI128Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(-42); // 0xffffffffffffffffffffffffffffffd6
const beValue = beCodec.decode(bytes); // BigInt(-42)

getI128Encoder and getI128Decoder functions are also available.

getF32Codec

Encodes and decodes 32-bit floating-point numbers. Due to the IEEE 754 floating-point representation, some precision loss may occur.

Values can be provided as either number or bigint, but the decoded value is always a number. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getF32Codec();
const bytes = codec.encode(-1.5); // 0x0000c0bf
const value = codec.decode(bytes); // -1.5
 
// Big-endian.
const beCodec = getF32Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(-1.5); // 0xbfc00000
const beValue = beCodec.decode(bytes); // -1.5

getF32Encoder and getF32Decoder functions are also available.

getF64Codec

Encodes and decodes 64-bit floating-point numbers. Due to the IEEE 754 floating-point representation, some precision loss may occur.

Values can be provided as either number or bigint, but the decoded value is always a number. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getF64Codec();
const bytes = codec.encode(-1.5); // 0x000000000000f8bf
const value = codec.decode(bytes); // -1.5
 
// Big-endian.
const beCodec = getF64Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(-1.5); // 0xbff8000000000000
const beValue = beCodec.decode(bytes); // -1.5

getF64Encoder and getF64Decoder functions are also available.

getShortU16Codec

Encodes and decodes unsigned integer using 1 to 3 bytes based on the encoded value. It supports values from 0 to 4,194,303 (2^22 - 1).

The larger the value, the more bytes it uses.

• If the value is <= 0x7f (127), it is stored in a single byte and the first bit is set to 0 to indicate the end of the value.
• Otherwise, the first bit is set to 1 to indicate that the value continues in the next byte, which follows the same pattern.
• This process repeats until the value is fully encoded in up to 3 bytes. The third and last byte, if needed, uses all 8 bits to store the remaining value.

In other words, the encoding scheme follows this structure:

0XXXXXXX                   <- Values 0 to 127 (1 byte)
1XXXXXXX 0XXXXXXX          <- Values 128 to 16,383 (2 bytes)
1XXXXXXX 1XXXXXXX XXXXXXXX <- Values 16,384 to 4,194,303 (3 bytes)

Values can be provided as either number or bigint, but the decoded value is always a number.

const codec = getShortU16Codec();
const bytes1 = codec.encode(42); // 0x2a
const bytes2 = codec.encode(128); // 0x8001
const bytes3 = codec.encode(16384); // 0x808001
 
codec.decode(bytes1); // 42
codec.decode(bytes2); // 128
codec.decode(bytes3); // 16384

getShortU16Encoder and getShortU16Decoder functions are also available.

getU8Codec

Encodes and decodes unsigned 8-bit integers. It supports values from 0 to 255 (2^8 - 1).

Values can be provided as either number or bigint, but the decoded value is always a number.

const codec = getU8Codec();
const bytes = codec.encode(42); // 0x2a
const value = codec.decode(bytes); // 42

getU8Encoder and getU8Decoder functions are also available.

getU16Codec

Encodes and decodes unsigned 16-bit integers. It supports values from 0 to 65,535 (2^16 - 1).

Values can be provided as either number or bigint, but the decoded value is always a number. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getU16Codec();
const bytes = codec.encode(42); // 0x2a00
const value = codec.decode(bytes); // 42
 
// Big-endian.
const beCodec = getU16Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(42); // 0x002a
const beValue = beCodec.decode(bytes); // 42

getU16Encoder and getU16Decoder functions are also available.

getU32Codec

Encodes and decodes unsigned 32-bit integers. It supports values from 0 to 4,294,967,295 (2^32 - 1).

Values can be provided as either number or bigint, but the decoded value is always a number. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getU32Codec();
const bytes = codec.encode(42); // 0x2a000000
const value = codec.decode(bytes); // 42
 
// Big-endian.
const beCodec = getU32Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(42); // 0x0000002a
const beValue = beCodec.decode(bytes); // 42

getU32Encoder and getU32Decoder functions are also available.

getU64Codec

Encodes and decodes unsigned 64-bit integers. It supports values from 0 to 2^64 - 1.

Values can be provided as either number or bigint, but the decoded value is always a bigint. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getU64Codec();
const bytes = codec.encode(42); // 0x2a00000000000000
const value = codec.decode(bytes); // 42
 
// Big-endian.
const beCodec = getU64Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(42); // 0x000000000000002a
const beValue = beCodec.decode(bytes); // 42

getU64Encoder and getU64Decoder functions are also available.

getU128Codec

Encodes and decodes unsigned 128-bit integers. It supports values from 0 to 2^128 - 1.

Values can be provided as either number or bigint, but the decoded value is always a bigint. Endianness can be specified using the endian option. The default is Endian.Little.

// Little-endian.
const codec = getU128Codec();
const bytes = codec.encode(42); // 0x2a000000000000000000000000000000
const value = codec.decode(bytes); // 42
 
// Big-endian.
const beCodec = getU128Codec({ endian: Endian.Big });
const beBytes = beCodec.encode(42); // 0x0000000000000000000000000000002a
const beValue = beCodec.decode(bytes); // 42

getU128Encoder and getU128Decoder functions are also available.

Strings listing

getBase10Codec

Encodes and decodes Base 10 strings.

const codec = getBase10Codec();
const bytes = codec.encode('1024'); // 0x0400
const value = codec.decode(bytes); // "1024"

This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string. To add size constraints to your codec, you may use utility functions such as fixCodecSize, addCodecSizePrefix or addCodecSentinel.

fixCodecSize(getBase10Codec(), 4).encode('1024');
// 0x04000000 (padded to 4 bytes)
 
addCodecSizePrefix(getBase10Codec(), getU32Codec()).encode('1024');
// 0x020000000400
//   |       └-- The 2 bytes of content.
//   └-- 4-byte prefix telling us to read 2 bytes.
 
addCodecSentinel(getBase10Codec(), new Uint8Array([0xff, 0xff])).encode('1024');
// 0x0400ffff
//   |   └-- The sentinel signaling the end of the content.
//   └-- The 2 bytes of content.

getBase10Encoder and getBase10Decoder functions are also available.

getBase16Codec

Encodes and decodes Base 16 strings.

const codec = getBase16Codec();
const bytes = codec.encode('deadface'); // 0xdeadface
const value = codec.decode(bytes); // "deadface"

This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string. To add size constraints to your codec, you may use utility functions such as fixCodecSize, addCodecSizePrefix or addCodecSentinel.

fixCodecSize(getBase16Codec(), 2).encode('deadface');
// 0xdead (truncated to 2 bytes)
 
addCodecSizePrefix(getBase16Codec(), getU32Codec()).encode('deadface');
// 0x04000000deadface
//   |       └-- The 4 bytes of content.
//   └-- 4-byte prefix telling us to read 4 bytes.
 
addCodecSentinel(getBase16Codec(), new Uint8Array([0xff, 0xff])).encode('deadface');
// 0xdeadfaceffff
//   |       └-- The sentinel signaling the end of the content.
//   └-- The 4 bytes of content.

getBase16Encoder and getBase16Decoder functions are also available.

getBase58Codec

Encodes and decodes Base 58 strings.

const codec = getBase58Codec();
const bytes = codec.encode('heLLo'); // 0x1b6a3070
const value = codec.decode(bytes); // "heLLo"

This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string. To add size constraints to your codec, you may use utility functions such as fixCodecSize, addCodecSizePrefix or addCodecSentinel.

fixCodecSize(getBase58Codec(), 2).encode('heLLo');
// 0x1b6a (truncated to 2 bytes)
 
addCodecSizePrefix(getBase58Codec(), getU32Codec()).encode('heLLo');
// 0x040000001b6a3070
//   |       └-- The 4 bytes of content.
//   └-- 4-byte prefix telling us to read 4 bytes.
 
addCodecSentinel(getBase58Codec(), new Uint8Array([0xff, 0xff])).encode('heLLo');
// 0x1b6a3070ffff
//   |       └-- The sentinel signaling the end of the content.
//   └-- The 4 bytes of content.

getBase58Encoder and getBase58Decoder functions are also available.

getBase64Codec

Encodes and decodes Base 64 strings.

const codec = getBase64Codec();
const bytes = codec.encode('hello+world'); // 0x85e965a3ec28ae57
const value = codec.decode(bytes); // "hello+world"

This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string. To add size constraints to your codec, you may use utility functions such as fixCodecSize, addCodecSizePrefix or addCodecSentinel.

fixCodecSize(getBase64Codec(), 4).encode('hello+world');
// 0x85e965a3 (truncated to 4 bytes)
 
addCodecSizePrefix(getBase64Codec(), getU32Codec()).encode('hello+world');
// 0x0400000085e965a3ec28ae57
//   |       └-- The 8 bytes of content.
//   └-- 4-byte prefix telling us to read 8 bytes.
 
addCodecSentinel(getBase64Codec(), new Uint8Array([0xff, 0xff])).encode('hello+world');
// 0x85e965a3ec28ae57ffff
//   |               └-- The sentinel signaling the end of the content.
//   └-- The 8 bytes of content.

getBase64Encoder and getBase64Decoder functions are also available.

getBaseXCodec

The getBaseXCodec accepts a custom alphabet of X characters and creates a base-X codec using that alphabet. It does so by iteratively dividing by X and handling leading zeros.

const codec = getBaseXCodec('0ehlo');
const bytes = codec.encode('hello'); // 0x05bd
const value = codec.decode(bytes); // "hello"

This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string. To add size constraints to your codec, you may use utility functions such as fixCodecSize, addCodecSizePrefix or addCodecSentinel.

const codec = getBaseXCodec('0ehlo');
 
fixCodecSize(codec, 4).encode('hello');
// 0x05bd0000 (padded to 4 bytes)
 
addCodecSizePrefix(codec, getU32Codec()).encode('hello');
// 0x0200000005bd
//   |       └-- The 2 bytes of content.
//   └-- 4-byte prefix telling us to read 2 bytes.
 
addCodecSentinel(codec, new Uint8Array([0xff, 0xff])).encode('hello');
// 0x05bdffff
//   |   └-- The sentinel signaling the end of the content.
//   └-- The 2 bytes of content.

getBaseXEncoder and getBaseXDecoder functions are also available.

getBaseXResliceCodec

The getBaseXResliceCodec accepts a custom alphabet of X characters and creates a base-X codec using that alphabet.

It does so by re-slicing bytes into custom chunks of bits that are then mapped to the provided alphabet. The number of bits per chunk is also provided as the second argument and should typically be set to log2(alphabet.length).

This is typically used to create codecs whose alphabet's length is a power of 2 such as base-16 or base-64.

const codec = getBaseXResliceCodec('elho', 2);
const bytes = codec.encode('hellolol'); // 0x4aee
const value = codec.decode(bytes); // "hellolol"

This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string. To add size constraints to your codec, you may use utility functions such as fixCodecSize, addCodecSizePrefix or addCodecSentinel.

const codec = getBaseXResliceCodec('elho', 2);
 
fixCodecSize(codec, 4).encode('hellolol');
// 0x4aee0000 (padded to 4 bytes)
 
addCodecSizePrefix(codec, getU32Codec()).encode('hellolol');
// 0x020000004aee
//   |       └-- The 2 bytes of content.
//   └-- 4-byte prefix telling us to read 2 bytes.
 
addCodecSentinel(codec, new Uint8Array([0xff, 0xff])).encode('hellolol');
// 0x4aeeffff
//   |   └-- The sentinel signaling the end of the content.
//   └-- The 2 bytes of content.

getBaseXResliceEncoder and getBaseXResliceDecoder functions are also available.

getUtf8Codec

Encodes and decodes UTF-8 strings.

const codec = getUtf8Codec();
const bytes = codec.encode('hello'); // 0x68656c6c6f
const value = codec.decode(bytes); // "hello"

This codec does not enforce a size boundary. It will encode and decode all bytes necessary to represent the string. To add size constraints to your codec, you may use utility functions such as fixCodecSize, addCodecSizePrefix or addCodecSentinel.

fixCodecSize(getUtf8Codec(), 4).encode('hello');
// 0x68656c6c (truncated to 4 bytes)
 
addCodecSizePrefix(getUtf8Codec(), getU32Codec()).encode('hello');
// 0x0500000068656c6c6f
//   |       └-- The 5 bytes of content.
//   └-- 4-byte prefix telling us to read 5 bytes.
 
addCodecSentinel(getUtf8Codec(), new Uint8Array([0xff, 0xff])).encode('hello');
// 0x68656c6c6fffff
//   |         └-- The sentinel signaling the end of the content.
//   └-- The 5 bytes of content.

getUtf8Encoder and getUtf8Decoder functions are also available.

Data structures listing

getArrayCodec

The getArrayCodec function accepts any codec of type T and returns a codec of type Array<T>.

const codec = getArrayCodec(getU8Codec());
const bytes = codec.encode([1, 2, 3]); // 0x03000000010203
const array = codec.decode(bytes); // [1, 2, 3]

By default, the size of the array is stored as a u32 prefix before encoding the items.

getArrayCodec(getU8Codec()).encode([1, 2, 3]);
// 0x03000000010203
//   |       └-- 3 items of 1 byte each.
//   └-- 4-byte prefix telling us to read 3 items.

However, you may use the size option to configure this behaviour. It can be one of the following three strategies:

• Codec<number>: When a number codec is provided, that codec will be used to encode and decode the size prefix.
• number: When a number is provided, the codec will expect a fixed number of items in the array. An error will be thrown when trying to encode an array of a different length.
• "remainder": When the string "remainder" is passed as a size, the codec will use the remainder of the bytes to encode/decode its items. This means the size is not stored or known in advance but simply inferred from the rest of the buffer. For instance, if we have an array of u16 numbers and 10 bytes remaining, we know there are 5 items in this array.

getArrayCodec(getU8Codec(), { size: getU16Codec() }).encode([1, 2, 3]);
// 0x0300010203
//   |   └-- 3 items of 1 byte each.
//   └-- 2-byte prefix telling us to read 3 items.
 
getArrayCodec(getU8Codec(), { size: 3 }).encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. There must always be 3 items in the array.
 
getArrayCodec(getU8Codec(), { size: 'remainder' }).encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. The size is inferred from the remainder of the bytes.

getArrayEncoder and getArrayDecoder functions are also available.

getBitArrayCodec

The getBitArrayCodec function returns a codec that encodes and decodes an array of booleans such that each boolean is represented by a single bit. It requires the size of the codec in bytes and an optional backward flag that can be used to reverse the order of the bits.

const booleans = [true, false, true, false, true, false, true, false];
 
getBitArrayCodec(1).encode(booleans);
// 0xaa or 0b10101010
 
getBitArrayCodec(1, { backward: true }).encode(booleans);
// 0x55 or 0b01010101

getBitArrayEncoder and getBitArrayDecoder functions are also available.

getBooleanCodec

The getBooleanCodec function returns a Codec<boolean> that stores the boolean as 0 or 1 using a u8 number by default.

const codec = getBooleanCodec();
const bytes = codec.encode(true); // 0x01
const value = codec.decode(bytes); // true

You may configure that behaviour by providing an explicit number codec as the size option of the getBooleanCodec function. That number codec will then be used to encode and decode the values 0 and 1 accordingly.

getBooleanCodec({ size: getU16Codec() }).encode(false); // 0x0000
getBooleanCodec({ size: getU16Codec() }).encode(true); // 0x0100
 
getBooleanCodec({ size: getU32Codec() }).encode(false); // 0x00000000
getBooleanCodec({ size: getU32Codec() }).encode(true); // 0x01000000

getBooleanEncoder and getBooleanDecoder functions are also available.

getBytesCodec

The getBytesCodec function returns a Codec<Uint8Array> meaning it converts Uint8Arrays to and from… Uint8Arrays! Whilst this might seem a bit useless, it can be useful when composed into other codecs. For example, you could use it in a struct codec to say that a particular field should be left unserialised.

const codec = getBytesCodec();
const bytes = codec.encode(new Uint8Array([42])); // 0x2a
const value = codec.decode(bytes); // 0x2a

The getBytesCodec function will encode and decode Uint8Arrays using as many bytes as necessary. If you'd like to restrict the number of bytes used by this codec, you may combine it with utilities such as fixCodecSize, addCodecSizePrefix or addCodecSentinel.

const value = new Uint8Array([42, 43]); // 0x2a2b
 
fixCodecSize(getBytesCodec(), 4).encode(value);
// 0x2a2b0000 (padded to 4 bytes)
 
addCodecSizePrefix(getBytesCodec(), getU32Codec()).encode(value);
// 0x020000002a2b
//   |       └-- The 2 bytes of content.
//   └-- 4-byte prefix telling us to read 2 bytes.
 
addCodecSentinel(getBytesCodec(), new Uint8Array([0xff, 0xff])).encode(value);
// 0x2a2bffff
//   |   └-- The sentinel signaling the end of the content.
//   └-- The 2 bytes of content.

getBytesEncoder and getBytesDecoder functions are also available.

getConstantCodec

The getConstantCodec function accepts any Uint8Array and returns a Codec<void>. When encoding, it will set the provided Uint8Array as-is. When decoding, it will assert that the next bytes contain the provided Uint8Array and move the offset forward.

const codec = getConstantCodec(new Uint8Array([1, 2, 3]));
 
codec.encode(undefined); // 0x010203
codec.decode(new Uint8Array([1, 2, 3])); // undefined
codec.decode(new Uint8Array([1, 2, 4])); // Throws an error.

getConstantEncoder and getConstantDecoder functions are also available.

getDiscriminatedUnionCodec

In Rust, enums are powerful data types whose variants can be one of the following:

• An empty variant — e.g. enum Message { Quit }.
• A tuple variant — e.g. enum Message { Write(String) }.
• A struct variant — e.g. enum Message { Move { x: i32, y: i32 } }.

Whilst we do not have such powerful enums in JavaScript, we can emulate them in TypeScript using a union of objects such that each object is differentiated by a specific field. We call this a discriminated union.

We use a special field named __kind to distinguish between the different variants of a discriminated union. Additionally, since all variants are objects, we can use a fields property to wrap the array of tuple variants. Here is an example.

type Message =
    | { __kind: 'quit' } // Empty variant.
    | { __kind: 'write'; fields: [string] } // Tuple variant.
    | { __kind: 'move'; x: number; y: number }; // Struct variant.