@solana/codecs

@solana/codecs

This package contains all types and helpers for encoding and decoding anything to and from a Uint8Array. It can be used standalone, but it is also exported as part of the Solana JavaScript SDK @solana/web3.js@rc.

No matter which serialization strategy we use, Codecs abstract away its implementation and offers a simple encode and decode interface. Codecs 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 object.

// 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 person = { name: 'John', age: 42 };
const personCodec = getPersonCodec();
const encodedPerson: Uint8Array = personCodec.encode(person);
const decodedPerson: Person = personCodec.decode(encodedPerson);

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 Decoders only to decode a Person type.

const getPersonDecoder = (): Decoder<Person> =>
    getStructDecoder([
        ['name', addDecoderSizePrefix(getUtf8Decoder(), getU32Decoder())],
        ['age', getU32Decoder()],
    ]);

The @solana/codecs package is composed of several smaller packages, each with its own set of responsibilities. You can learn more about codecs and how to create your own by reading their respective documentation.

• @solana/codecs-core This package lays the foundation of codecs by providing core type and helper functions to create and compose them.
  • Composing codecs.
  • Composing encoders and decoders.
  • Combining encoders and decoders.
  • Different From and To types.
  • Fixed-size and variable-size codecs.
  • Creating custom codecs.
  • Transforming codecs.
  • Fixing the size of codecs.
  • Prefixing codecs with their size.
  • Adding sentinels to codecs.
  • Adjusting the size of codecs.
  • Offsetting codecs.
  • Padding codecs.
  • Reversing codecs.
  • Byte helpers.
• @solana/codecs-numbers This package offers codecs for numbers of various sizes and characteristics.
  • Integer codecs.
  • Decimal number codecs.
  • Short u16 codec.
• @solana/codecs-strings This package provides codecs for strings of various encodings and size strategies.
  • Sizing string codecs.
  • Utf8 codec.
  • Base 64 codec.
  • Base 58 codec.
  • Base 16 codec.
  • Base 10 codec.
  • Base X codec.
  • Re-slicing base X codec.
• @solana/codecs-data-structures This package offers a set of helpers for a variety of data structures such as objects, enums, arrays, maps, etc.
  • Array codec.
  • Set codec.
  • Map codec.
  • Tuple codec.
  • Struct codec.
  • Enum codec.
  • Literal union codec.
  • Discriminated union codec.
  • Union codec.
  • Boolean codec.
  • Nullable codec.
  • Bytes codec.
  • Bit array codec.
  • Constant codec.
  • Unit codec.
  • Hidden prefix and suffix codec.
• @solana/options This package adds Rust-like Options to JavaScript and offers codecs and helpers to manage them.
  • Creating options.
  • Option helpers.
  • Unwrapping options.
  • Option codec.