getOptionCodec

Call Signature

function getOptionCodec<TFrom, TTo, TSize>(
    item,
    config,
): FixedSizeCodec<OptionOrNullable<TFrom>, Option<TTo>, TSize>;

Returns a codec for encoding and decoding optional values using the Option type.

This codec serializes and deserializes Option<T> values using a configurable approach:

  • By default, a u8 prefix is used (0 = None, 1 = Some).
  • If noneValue: 'zeroes' is set, None values are encoded/decoded as zeroes.
  • If noneValue is a byte array, None values are represented by the provided constant.
  • If prefix: null is set, the codec determines None values solely from noneValue or the presence of bytes.

For more details on the configuration options, see OptionCodecConfig.

Note that this behaves similarly to getNullableCodec, except it encodes OptionOrNullable values and decodes Option values.

Type Parameters

Type ParameterDescription
TFromThe type of the main value being encoded.
TToThe type of the main value being decoded.
TSize extends number-

Parameters

ParameterTypeDescription
itemFixedSizeCodec<TFrom, TTo, TSize>The codec for the value that may be present.
configOptionCodecConfig<NumberCodec> & objectConfiguration options for encoding and decoding option values.

Returns

FixedSizeCodec<OptionOrNullable<TFrom>, Option<TTo>, TSize>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding option values.

Examples

Encoding and decoding an optional string with a size prefix.

const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const codec = getOptionCodec(stringCodec);
 
const someBytes = codec.encode(some('Hi'));
// 0x01020000004869
//   | |       └-- utf8 string content ("Hi").
//   | └-- u32 string prefix (2 characters).
//   └-- 1-byte prefix (Some).
 
const noneBytes = codec.encode(none());
// 0x00
//   └-- 1-byte prefix (None).
 
codec.decode(someBytes); // some('Hi')
codec.decode(noneBytes); // none()

Encoding nullable values.

const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const codec = getOptionCodec(stringCodec);
 
const someBytes = codec.encode('Hi'); // 0x01020000004869
const noneBytes = codec.encode(null); // 0x00
 
codec.decode(someBytes); // some('Hi')
codec.decode(noneBytes); // none()

Encoding and decoding an optional number with a fixed size.

const codec = getOptionCodec(getU16Codec(), { noneValue: 'zeroes' });
 
const someBytes = codec.encode(some(42)); // 0x012a00
const noneBytes = codec.encode(none());   // 0x000000
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Encoding and decoding None values with a custom byte sequence and no prefix.

const codec = getOptionCodec(getU16Codec(), {
  noneValue: new Uint8Array([0xff, 0xff]),
  prefix: null,
});
 
const someBytes = codec.encode(some(42)); // 0x2a00
const noneBytes = codec.encode(none());   // 0xffff
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Identifying None values by the absence of bytes.

const codec = getOptionCodec(getU16Codec(), { prefix: null });
 
const someBytes = codec.encode(some(42)); // 0x2a00
const noneBytes = codec.encode(none());   // new Uint8Array(0)
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Remarks

Separate getOptionEncoder and getOptionDecoder functions are available.

const bytes = getOptionEncoder(getU32Encoder()).encode(some(42));
const value = getOptionDecoder(getU32Decoder()).decode(bytes);

See

Call Signature

function getOptionCodec<TFrom, TTo>(
    item,
    config,
): FixedSizeCodec<OptionOrNullable<TFrom>, Option<TTo>>;

Returns a codec for encoding and decoding optional values using the Option type.

This codec serializes and deserializes Option<T> values using a configurable approach:

  • By default, a u8 prefix is used (0 = None, 1 = Some).
  • If noneValue: 'zeroes' is set, None values are encoded/decoded as zeroes.
  • If noneValue is a byte array, None values are represented by the provided constant.
  • If prefix: null is set, the codec determines None values solely from noneValue or the presence of bytes.

For more details on the configuration options, see OptionCodecConfig.

Note that this behaves similarly to getNullableCodec, except it encodes OptionOrNullable values and decodes Option values.

Type Parameters

Type ParameterDefault typeDescription
TFrom-The type of the main value being encoded.
TToTFromThe type of the main value being decoded.

Parameters

ParameterTypeDescription
itemFixedSizeCodec<TFrom, TTo>The codec for the value that may be present.
configOptionCodecConfig<FixedSizeNumberCodec> & objectConfiguration options for encoding and decoding option values.

Returns

FixedSizeCodec<OptionOrNullable<TFrom>, Option<TTo>>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding option values.

Examples

Encoding and decoding an optional string with a size prefix.

const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const codec = getOptionCodec(stringCodec);
 
const someBytes = codec.encode(some('Hi'));
// 0x01020000004869
//   | |       └-- utf8 string content ("Hi").
//   | └-- u32 string prefix (2 characters).
//   └-- 1-byte prefix (Some).
 
const noneBytes = codec.encode(none());
// 0x00
//   └-- 1-byte prefix (None).
 
codec.decode(someBytes); // some('Hi')
codec.decode(noneBytes); // none()

Encoding nullable values.

const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const codec = getOptionCodec(stringCodec);
 
const someBytes = codec.encode('Hi'); // 0x01020000004869
const noneBytes = codec.encode(null); // 0x00
 
codec.decode(someBytes); // some('Hi')
codec.decode(noneBytes); // none()

Encoding and decoding an optional number with a fixed size.

const codec = getOptionCodec(getU16Codec(), { noneValue: 'zeroes' });
 
const someBytes = codec.encode(some(42)); // 0x012a00
const noneBytes = codec.encode(none());   // 0x000000
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Encoding and decoding None values with a custom byte sequence and no prefix.

const codec = getOptionCodec(getU16Codec(), {
  noneValue: new Uint8Array([0xff, 0xff]),
  prefix: null,
});
 
const someBytes = codec.encode(some(42)); // 0x2a00
const noneBytes = codec.encode(none());   // 0xffff
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Identifying None values by the absence of bytes.

const codec = getOptionCodec(getU16Codec(), { prefix: null });
 
const someBytes = codec.encode(some(42)); // 0x2a00
const noneBytes = codec.encode(none());   // new Uint8Array(0)
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Remarks

Separate getOptionEncoder and getOptionDecoder functions are available.

const bytes = getOptionEncoder(getU32Encoder()).encode(some(42));
const value = getOptionDecoder(getU32Decoder()).decode(bytes);

See

Call Signature

function getOptionCodec<TFrom, TTo>(
    item,
    config,
): VariableSizeCodec<OptionOrNullable<TFrom>, Option<TTo>>;

Returns a codec for encoding and decoding optional values using the Option type.

This codec serializes and deserializes Option<T> values using a configurable approach:

  • By default, a u8 prefix is used (0 = None, 1 = Some).
  • If noneValue: 'zeroes' is set, None values are encoded/decoded as zeroes.
  • If noneValue is a byte array, None values are represented by the provided constant.
  • If prefix: null is set, the codec determines None values solely from noneValue or the presence of bytes.

For more details on the configuration options, see OptionCodecConfig.

Note that this behaves similarly to getNullableCodec, except it encodes OptionOrNullable values and decodes Option values.

Type Parameters

Type ParameterDefault typeDescription
TFrom-The type of the main value being encoded.
TToTFromThe type of the main value being decoded.

Parameters

ParameterTypeDescription
itemFixedSizeCodec<TFrom, TTo>The codec for the value that may be present.
configOptionCodecConfig<NumberCodec> & objectConfiguration options for encoding and decoding option values.

Returns

VariableSizeCodec<OptionOrNullable<TFrom>, Option<TTo>>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding option values.

Examples

Encoding and decoding an optional string with a size prefix.

const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const codec = getOptionCodec(stringCodec);
 
const someBytes = codec.encode(some('Hi'));
// 0x01020000004869
//   | |       └-- utf8 string content ("Hi").
//   | └-- u32 string prefix (2 characters).
//   └-- 1-byte prefix (Some).
 
const noneBytes = codec.encode(none());
// 0x00
//   └-- 1-byte prefix (None).
 
codec.decode(someBytes); // some('Hi')
codec.decode(noneBytes); // none()

Encoding nullable values.

const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const codec = getOptionCodec(stringCodec);
 
const someBytes = codec.encode('Hi'); // 0x01020000004869
const noneBytes = codec.encode(null); // 0x00
 
codec.decode(someBytes); // some('Hi')
codec.decode(noneBytes); // none()

Encoding and decoding an optional number with a fixed size.

const codec = getOptionCodec(getU16Codec(), { noneValue: 'zeroes' });
 
const someBytes = codec.encode(some(42)); // 0x012a00
const noneBytes = codec.encode(none());   // 0x000000
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Encoding and decoding None values with a custom byte sequence and no prefix.

const codec = getOptionCodec(getU16Codec(), {
  noneValue: new Uint8Array([0xff, 0xff]),
  prefix: null,
});
 
const someBytes = codec.encode(some(42)); // 0x2a00
const noneBytes = codec.encode(none());   // 0xffff
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Identifying None values by the absence of bytes.

const codec = getOptionCodec(getU16Codec(), { prefix: null });
 
const someBytes = codec.encode(some(42)); // 0x2a00
const noneBytes = codec.encode(none());   // new Uint8Array(0)
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Remarks

Separate getOptionEncoder and getOptionDecoder functions are available.

const bytes = getOptionEncoder(getU32Encoder()).encode(some(42));
const value = getOptionDecoder(getU32Decoder()).decode(bytes);

See

Call Signature

function getOptionCodec<TFrom, TTo>(
    item,
    config?,
): VariableSizeCodec<OptionOrNullable<TFrom>, Option<TTo>>;

Returns a codec for encoding and decoding optional values using the Option type.

This codec serializes and deserializes Option<T> values using a configurable approach:

  • By default, a u8 prefix is used (0 = None, 1 = Some).
  • If noneValue: 'zeroes' is set, None values are encoded/decoded as zeroes.
  • If noneValue is a byte array, None values are represented by the provided constant.
  • If prefix: null is set, the codec determines None values solely from noneValue or the presence of bytes.

For more details on the configuration options, see OptionCodecConfig.

Note that this behaves similarly to getNullableCodec, except it encodes OptionOrNullable values and decodes Option values.

Type Parameters

Type ParameterDefault typeDescription
TFrom-The type of the main value being encoded.
TToTFromThe type of the main value being decoded.

Parameters

ParameterTypeDescription
itemCodec<TFrom, TTo>The codec for the value that may be present.
config?OptionCodecConfig<NumberCodec> & objectConfiguration options for encoding and decoding option values.

Returns

VariableSizeCodec<OptionOrNullable<TFrom>, Option<TTo>>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding option values.

Examples

Encoding and decoding an optional string with a size prefix.

const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const codec = getOptionCodec(stringCodec);
 
const someBytes = codec.encode(some('Hi'));
// 0x01020000004869
//   | |       └-- utf8 string content ("Hi").
//   | └-- u32 string prefix (2 characters).
//   └-- 1-byte prefix (Some).
 
const noneBytes = codec.encode(none());
// 0x00
//   └-- 1-byte prefix (None).
 
codec.decode(someBytes); // some('Hi')
codec.decode(noneBytes); // none()

Encoding nullable values.

const stringCodec = addCodecSizePrefix(getUtf8Codec(), getU32Codec());
const codec = getOptionCodec(stringCodec);
 
const someBytes = codec.encode('Hi'); // 0x01020000004869
const noneBytes = codec.encode(null); // 0x00
 
codec.decode(someBytes); // some('Hi')
codec.decode(noneBytes); // none()

Encoding and decoding an optional number with a fixed size.

const codec = getOptionCodec(getU16Codec(), { noneValue: 'zeroes' });
 
const someBytes = codec.encode(some(42)); // 0x012a00
const noneBytes = codec.encode(none());   // 0x000000
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Encoding and decoding None values with a custom byte sequence and no prefix.

const codec = getOptionCodec(getU16Codec(), {
  noneValue: new Uint8Array([0xff, 0xff]),
  prefix: null,
});
 
const someBytes = codec.encode(some(42)); // 0x2a00
const noneBytes = codec.encode(none());   // 0xffff
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Identifying None values by the absence of bytes.

const codec = getOptionCodec(getU16Codec(), { prefix: null });
 
const someBytes = codec.encode(some(42)); // 0x2a00
const noneBytes = codec.encode(none());   // new Uint8Array(0)
 
codec.decode(someBytes); // some(42)
codec.decode(noneBytes); // none()

Remarks

Separate getOptionEncoder and getOptionDecoder functions are available.

const bytes = getOptionEncoder(getU32Encoder()).encode(some(42));
const value = getOptionDecoder(getU32Decoder()).decode(bytes);

See

On this page