getNullableCodec

Call Signature

getNullableCodec<TFrom, TTo, TSize>(item, config): FixedSizeCodec<null | TFrom, null | TTo, TSize>

Returns a codec for encoding and decoding optional values, allowing null values to be handled.

This codec serializes and deserializes optional values using a configurable approach:

By default, a u8 prefix is used (0 = null, 1 = present). This can be customized using a custom number codec or even disabled by setting the prefix to null.
If noneValue: 'zeroes' is set, null values are encoded/decoded as zeroes.
If noneValue is a byte array, null values are represented by the provided constant.

For more details on the configuration options, see NullableCodecConfig.

Type Parameters

Type Parameter	Description
`TFrom`	The type of the main value being encoded.
`TTo`	The type of the main value being decoded.
`TSize` extends `number`	-

Parameters

Parameter	Type	Description
`item`	`FixedSizeCodec`<`TFrom`, `TTo`, `TSize`>	The codec for the value that may be present.
`config`	`NullableCodecConfig`<`NumberCodec`> & `object`	Configuration options for encoding and decoding optional values.

Returns

FixedSizeCodec<null | TFrom, null | TTo, TSize>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding nullable values.

Examples

Encoding and decoding an optional number using a u8 prefix (default).

const codec = getNullableCodec(getU32Codec());
 
codec.encode(null); // 0x00
codec.encode(42);   // 0x012a000000
 
codec.decode(new Uint8Array([0x00])); // null
codec.decode(new Uint8Array([0x01, 0x2a, 0x00, 0x00, 0x00])); // 42

Encoding and decoding an optional number using a fixed-size codec, by filling null values with zeroes.

const codec = getNullableCodec(getU32Codec(), { noneValue: 'zeroes' });
 
codec.encode(null); // 0x0000000000
codec.encode(42);   // 0x012a000000
 
codec.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00, 0x00])); // null
codec.decode(new Uint8Array([0x01, 0x2a, 0x00, 0x00, 0x00])); // 42

Encoding and decoding null values with zeroes and no prefix.

const codec = getNullableCodec(getU32Codec(), {
  noneValue: 'zeroes',
  prefix: null,
});
 
codec.encode(null); // 0x00000000
codec.encode(42);   // 0x2a000000
 
codec.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00])); // null
codec.decode(new Uint8Array([0x2a, 0x00, 0x00, 0x00])); // 42

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

const codec = getNullableCodec(getU16Codec(), {
  noneValue: new Uint8Array([0xff, 0xff]),
  prefix: null,
});
 
codec.encode(null); // 0xffff
codec.encode(42); // 0x2a00
 
codec.decode(new Uint8Array([0xff, 0xff])); // null
codec.decode(new Uint8Array([0x2a, 0x00])); // 42

Identifying null values by the absence of bytes.

const codec = getNullableCodec(getU16Codec(), { prefix: null });
 
codec.encode(null); // Empty bytes
codec.encode(42); // 0x2a00
 
codec.decode(new Uint8Array([])); // null
codec.decode(new Uint8Array([0x2a, 0x00])); // 42

Remarks

Separate getNullableEncoder and getNullableDecoder functions are available.

const bytes = getNullableEncoder(getU32Encoder()).encode(42);
const value = getNullableDecoder(getU32Decoder()).decode(bytes);

See

Call Signature

getNullableCodec<TFrom, TTo>(item, config): FixedSizeCodec<null | TFrom, null | TTo>

Returns a codec for encoding and decoding optional values, allowing null values to be handled.

This codec serializes and deserializes optional values using a configurable approach:

By default, a u8 prefix is used (0 = null, 1 = present). This can be customized using a custom number codec or even disabled by setting the prefix to null.
If noneValue: 'zeroes' is set, null values are encoded/decoded as zeroes.
If noneValue is a byte array, null values are represented by the provided constant.

For more details on the configuration options, see NullableCodecConfig.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the main value being encoded.
`TTo`	`TFrom`	The type of the main value being decoded.

Parameters

Parameter	Type	Description
`item`	`FixedSizeCodec`<`TFrom`, `TTo`>	The codec for the value that may be present.
`config`	`NullableCodecConfig`<`FixedSizeNumberCodec`> & `object`	Configuration options for encoding and decoding optional values.

Returns

FixedSizeCodec<null | TFrom, null | TTo>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding nullable values.

Examples

Encoding and decoding an optional number using a u8 prefix (default).

const codec = getNullableCodec(getU32Codec());
 
codec.encode(null); // 0x00
codec.encode(42);   // 0x012a000000
 
codec.decode(new Uint8Array([0x00])); // null
codec.decode(new Uint8Array([0x01, 0x2a, 0x00, 0x00, 0x00])); // 42

Encoding and decoding an optional number using a fixed-size codec, by filling null values with zeroes.

const codec = getNullableCodec(getU32Codec(), { noneValue: 'zeroes' });
 
codec.encode(null); // 0x0000000000
codec.encode(42);   // 0x012a000000
 
codec.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00, 0x00])); // null
codec.decode(new Uint8Array([0x01, 0x2a, 0x00, 0x00, 0x00])); // 42

Encoding and decoding null values with zeroes and no prefix.

const codec = getNullableCodec(getU32Codec(), {
  noneValue: 'zeroes',
  prefix: null,
});
 
codec.encode(null); // 0x00000000
codec.encode(42);   // 0x2a000000
 
codec.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00])); // null
codec.decode(new Uint8Array([0x2a, 0x00, 0x00, 0x00])); // 42

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

const codec = getNullableCodec(getU16Codec(), {
  noneValue: new Uint8Array([0xff, 0xff]),
  prefix: null,
});
 
codec.encode(null); // 0xffff
codec.encode(42); // 0x2a00
 
codec.decode(new Uint8Array([0xff, 0xff])); // null
codec.decode(new Uint8Array([0x2a, 0x00])); // 42

Identifying null values by the absence of bytes.

const codec = getNullableCodec(getU16Codec(), { prefix: null });
 
codec.encode(null); // Empty bytes
codec.encode(42); // 0x2a00
 
codec.decode(new Uint8Array([])); // null
codec.decode(new Uint8Array([0x2a, 0x00])); // 42

Remarks

Separate getNullableEncoder and getNullableDecoder functions are available.

const bytes = getNullableEncoder(getU32Encoder()).encode(42);
const value = getNullableDecoder(getU32Decoder()).decode(bytes);

See

Call Signature

getNullableCodec<TFrom, TTo>(item, config): VariableSizeCodec<null | TFrom, null | TTo>

Returns a codec for encoding and decoding optional values, allowing null values to be handled.

This codec serializes and deserializes optional values using a configurable approach:

By default, a u8 prefix is used (0 = null, 1 = present). This can be customized using a custom number codec or even disabled by setting the prefix to null.
If noneValue: 'zeroes' is set, null values are encoded/decoded as zeroes.
If noneValue is a byte array, null values are represented by the provided constant.

For more details on the configuration options, see NullableCodecConfig.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the main value being encoded.
`TTo`	`TFrom`	The type of the main value being decoded.

Parameters

Parameter	Type	Description
`item`	`FixedSizeCodec`<`TFrom`, `TTo`>	The codec for the value that may be present.
`config`	`NullableCodecConfig`<`NumberCodec`> & `object`	Configuration options for encoding and decoding optional values.

Returns

VariableSizeCodec<null | TFrom, null | TTo>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding nullable values.

Examples

Encoding and decoding an optional number using a u8 prefix (default).

const codec = getNullableCodec(getU32Codec());
 
codec.encode(null); // 0x00
codec.encode(42);   // 0x012a000000
 
codec.decode(new Uint8Array([0x00])); // null
codec.decode(new Uint8Array([0x01, 0x2a, 0x00, 0x00, 0x00])); // 42

Encoding and decoding an optional number using a fixed-size codec, by filling null values with zeroes.

const codec = getNullableCodec(getU32Codec(), { noneValue: 'zeroes' });
 
codec.encode(null); // 0x0000000000
codec.encode(42);   // 0x012a000000
 
codec.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00, 0x00])); // null
codec.decode(new Uint8Array([0x01, 0x2a, 0x00, 0x00, 0x00])); // 42

Encoding and decoding null values with zeroes and no prefix.

const codec = getNullableCodec(getU32Codec(), {
  noneValue: 'zeroes',
  prefix: null,
});
 
codec.encode(null); // 0x00000000
codec.encode(42);   // 0x2a000000
 
codec.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00])); // null
codec.decode(new Uint8Array([0x2a, 0x00, 0x00, 0x00])); // 42

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

const codec = getNullableCodec(getU16Codec(), {
  noneValue: new Uint8Array([0xff, 0xff]),
  prefix: null,
});
 
codec.encode(null); // 0xffff
codec.encode(42); // 0x2a00
 
codec.decode(new Uint8Array([0xff, 0xff])); // null
codec.decode(new Uint8Array([0x2a, 0x00])); // 42

Identifying null values by the absence of bytes.

const codec = getNullableCodec(getU16Codec(), { prefix: null });
 
codec.encode(null); // Empty bytes
codec.encode(42); // 0x2a00
 
codec.decode(new Uint8Array([])); // null
codec.decode(new Uint8Array([0x2a, 0x00])); // 42

Remarks

Separate getNullableEncoder and getNullableDecoder functions are available.

const bytes = getNullableEncoder(getU32Encoder()).encode(42);
const value = getNullableDecoder(getU32Decoder()).decode(bytes);

See

Call Signature

getNullableCodec<TFrom, TTo>(item, config?): VariableSizeCodec<null | TFrom, null | TTo>

Returns a codec for encoding and decoding optional values, allowing null values to be handled.

This codec serializes and deserializes optional values using a configurable approach:

By default, a u8 prefix is used (0 = null, 1 = present). This can be customized using a custom number codec or even disabled by setting the prefix to null.
If noneValue: 'zeroes' is set, null values are encoded/decoded as zeroes.
If noneValue is a byte array, null values are represented by the provided constant.

For more details on the configuration options, see NullableCodecConfig.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the main value being encoded.
`TTo`	`TFrom`	The type of the main value being decoded.

Parameters

Parameter	Type	Description
`item`	`Codec`<`TFrom`, `TTo`>	The codec for the value that may be present.
`config?`	`NullableCodecConfig`<`NumberCodec`> & `object`	Configuration options for encoding and decoding optional values.

Returns

VariableSizeCodec<null | TFrom, null | TTo>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding nullable values.

Examples

Encoding and decoding an optional number using a u8 prefix (default).

const codec = getNullableCodec(getU32Codec());
 
codec.encode(null); // 0x00
codec.encode(42);   // 0x012a000000
 
codec.decode(new Uint8Array([0x00])); // null
codec.decode(new Uint8Array([0x01, 0x2a, 0x00, 0x00, 0x00])); // 42

Encoding and decoding an optional number using a fixed-size codec, by filling null values with zeroes.

const codec = getNullableCodec(getU32Codec(), { noneValue: 'zeroes' });
 
codec.encode(null); // 0x0000000000
codec.encode(42);   // 0x012a000000
 
codec.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00, 0x00])); // null
codec.decode(new Uint8Array([0x01, 0x2a, 0x00, 0x00, 0x00])); // 42

Encoding and decoding null values with zeroes and no prefix.

const codec = getNullableCodec(getU32Codec(), {
  noneValue: 'zeroes',
  prefix: null,
});
 
codec.encode(null); // 0x00000000
codec.encode(42);   // 0x2a000000
 
codec.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00])); // null
codec.decode(new Uint8Array([0x2a, 0x00, 0x00, 0x00])); // 42

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

const codec = getNullableCodec(getU16Codec(), {
  noneValue: new Uint8Array([0xff, 0xff]),
  prefix: null,
});
 
codec.encode(null); // 0xffff
codec.encode(42); // 0x2a00
 
codec.decode(new Uint8Array([0xff, 0xff])); // null
codec.decode(new Uint8Array([0x2a, 0x00])); // 42

Identifying null values by the absence of bytes.

const codec = getNullableCodec(getU16Codec(), { prefix: null });
 
codec.encode(null); // Empty bytes
codec.encode(42); // 0x2a00
 
codec.decode(new Uint8Array([])); // null
codec.decode(new Uint8Array([0x2a, 0x00])); // 42

Remarks

Separate getNullableEncoder and getNullableDecoder functions are available.

const bytes = getNullableEncoder(getU32Encoder()).encode(42);
const value = getNullableDecoder(getU32Decoder()).decode(bytes);

getNullableCodec

On this page