getArrayCodec

Call Signature

function getArrayCodec<TFrom, TTo>(
    item,
    config,
): FixedSizeCodec<TFrom[], TTo[], 0>;

Returns a codec for encoding and decoding arrays of values.

This codec serializes arrays by encoding each element using the provided item codec. By default, a u32 size prefix is included to indicate the number of items in the array. The size option can be used to modify this behaviour.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the elements to encode.
`TTo`	`TFrom`	The type of the decoded elements.

Parameters

Parameter	Type	Description
`item`	`Codec`<`TFrom`, `TTo`>	The codec for each item in the array.
`config`	`ArrayCodecConfig`<`NumberCodec`> & `object`	Optional configuration for the size encoding/decoding strategy.

Returns

FixedSizeCodec<TFrom[], TTo[], 0>

A VariableSizeCodec<TFrom[], TTo[]> for encoding and decoding arrays.

Examples

Encoding and decoding an array of u8 numbers.

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

Using a u16 size prefix instead of u32.

const codec = getArrayCodec(getU8Codec(), { size: getU16Codec() });
const bytes = codec.encode([1, 2, 3]);
// 0x0300010203
//   |   └-- 3 items of 1 byte each.
//   └-- 2-byte prefix telling us to read 3 items.

Using a fixed-size array of 3 items.

const codec = getArrayCodec(getU8Codec(), { size: 3 });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. There must always be 3 items in the array.

Using the "remainder" size strategy.

const codec = getArrayCodec(getU8Codec(), { size: 'remainder' });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. The size is inferred from the remainder of the bytes.

Using a sentinel to mark the end of the array. Note that no valid item may begin with the sentinel's bytes, or decoding would stop early — see ArrayLikeCodecSentinelSize for the full constraints.

const codec = getArrayCodec(getU8Codec(), { size: { __kind: 'sentinel', sentinel: new Uint8Array([0]) } });
codec.encode([1, 2, 3]);
// 0x01020300
//   |      └-- The sentinel that marks the end of the array.
//   └-- 3 items of 1 byte each.

Requiring the size prefix to be present when decoding.

getArrayCodec(getU8Codec()).decode(new Uint8Array([]));
// [] (an exhausted byte array decodes as an empty array by default).
 
getArrayCodec(getU8Codec(), { requireSizePrefix: true }).decode(new Uint8Array([]));
// Throws: the size prefix is missing.

Remarks

The size of the array can be controlled using the size option:

A Codec<number> (e.g. getU16Codec()) stores a size prefix before the array.
A number enforces a fixed number of elements.
"remainder" uses all remaining bytes to infer the array length.
A sentinel object (see ArrayLikeCodecSentinelSize) ends the array when the bytes at the next item position match a constant sentinel.

When the size is stored as a prefix, decoding an exhausted byte array yields an empty array, which allows arrays to be appended to existing data layouts without breaking older data. Use the requireSizePrefix option to throw instead.

Separate getArrayEncoder and getArrayDecoder functions are available.

const bytes = getArrayEncoder(getU8Encoder()).encode([1, 2, 3]);
const array = getArrayDecoder(getU8Decoder()).decode(bytes);

See

Call Signature

function getArrayCodec<TFrom, TTo>(
    item,
    config,
): FixedSizeCodec<TFrom[], TTo[]>;

Returns a codec for encoding and decoding arrays of values.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the elements to encode.
`TTo`	`TFrom`	The type of the decoded elements.

Parameters

Parameter	Type	Description
`item`	`FixedSizeCodec`<`TFrom`, `TTo`>	The codec for each item in the array.
`config`	`ArrayCodecConfig`<`NumberCodec`> & `object`	Optional configuration for the size encoding/decoding strategy.

Returns

FixedSizeCodec<TFrom[], TTo[]>

A VariableSizeCodec<TFrom[], TTo[]> for encoding and decoding arrays.

Examples

Encoding and decoding an array of u8 numbers.

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

Using a u16 size prefix instead of u32.

const codec = getArrayCodec(getU8Codec(), { size: getU16Codec() });
const bytes = codec.encode([1, 2, 3]);
// 0x0300010203
//   |   └-- 3 items of 1 byte each.
//   └-- 2-byte prefix telling us to read 3 items.

Using a fixed-size array of 3 items.

const codec = getArrayCodec(getU8Codec(), { size: 3 });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. There must always be 3 items in the array.

Using the "remainder" size strategy.

const codec = getArrayCodec(getU8Codec(), { size: 'remainder' });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. The size is inferred from the remainder of the bytes.

Using a sentinel to mark the end of the array. Note that no valid item may begin with the sentinel's bytes, or decoding would stop early — see ArrayLikeCodecSentinelSize for the full constraints.

const codec = getArrayCodec(getU8Codec(), { size: { __kind: 'sentinel', sentinel: new Uint8Array([0]) } });
codec.encode([1, 2, 3]);
// 0x01020300
//   |      └-- The sentinel that marks the end of the array.
//   └-- 3 items of 1 byte each.

Requiring the size prefix to be present when decoding.

getArrayCodec(getU8Codec()).decode(new Uint8Array([]));
// [] (an exhausted byte array decodes as an empty array by default).
 
getArrayCodec(getU8Codec(), { requireSizePrefix: true }).decode(new Uint8Array([]));
// Throws: the size prefix is missing.

Remarks

The size of the array can be controlled using the size option:

A Codec<number> (e.g. getU16Codec()) stores a size prefix before the array.
A number enforces a fixed number of elements.
"remainder" uses all remaining bytes to infer the array length.
A sentinel object (see ArrayLikeCodecSentinelSize) ends the array when the bytes at the next item position match a constant sentinel.

Separate getArrayEncoder and getArrayDecoder functions are available.

const bytes = getArrayEncoder(getU8Encoder()).encode([1, 2, 3]);
const array = getArrayDecoder(getU8Decoder()).decode(bytes);

See

Call Signature

function getArrayCodec<TFrom, TTo>(
    item,
    config?,
): VariableSizeCodec<TFrom[], TTo[]>;

Returns a codec for encoding and decoding arrays of values.

Type Parameters

Type Parameter	Default type	Description
`TFrom`	-	The type of the elements to encode.
`TTo`	`TFrom`	The type of the decoded elements.

Parameters

Parameter	Type	Description
`item`	`Codec`<`TFrom`, `TTo`>	The codec for each item in the array.
`config?`	`ArrayCodecConfig`<`NumberCodec`>	Optional configuration for the size encoding/decoding strategy.

Returns

VariableSizeCodec<TFrom[], TTo[]>

A VariableSizeCodec<TFrom[], TTo[]> for encoding and decoding arrays.

Examples

Encoding and decoding an array of u8 numbers.

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

Using a u16 size prefix instead of u32.

const codec = getArrayCodec(getU8Codec(), { size: getU16Codec() });
const bytes = codec.encode([1, 2, 3]);
// 0x0300010203
//   |   └-- 3 items of 1 byte each.
//   └-- 2-byte prefix telling us to read 3 items.

Using a fixed-size array of 3 items.

const codec = getArrayCodec(getU8Codec(), { size: 3 });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. There must always be 3 items in the array.

Using the "remainder" size strategy.

const codec = getArrayCodec(getU8Codec(), { size: 'remainder' });
codec.encode([1, 2, 3]);
// 0x010203
//   └-- 3 items of 1 byte each. The size is inferred from the remainder of the bytes.

Using a sentinel to mark the end of the array. Note that no valid item may begin with the sentinel's bytes, or decoding would stop early — see ArrayLikeCodecSentinelSize for the full constraints.

const codec = getArrayCodec(getU8Codec(), { size: { __kind: 'sentinel', sentinel: new Uint8Array([0]) } });
codec.encode([1, 2, 3]);
// 0x01020300
//   |      └-- The sentinel that marks the end of the array.
//   └-- 3 items of 1 byte each.

Requiring the size prefix to be present when decoding.

getArrayCodec(getU8Codec()).decode(new Uint8Array([]));
// [] (an exhausted byte array decodes as an empty array by default).
 
getArrayCodec(getU8Codec(), { requireSizePrefix: true }).decode(new Uint8Array([]));
// Throws: the size prefix is missing.

Remarks

The size of the array can be controlled using the size option:

A Codec<number> (e.g. getU16Codec()) stores a size prefix before the array.
A number enforces a fixed number of elements.
"remainder" uses all remaining bytes to infer the array length.
A sentinel object (see ArrayLikeCodecSentinelSize) ends the array when the bytes at the next item position match a constant sentinel.

Separate getArrayEncoder and getArrayDecoder functions are available.

const bytes = getArrayEncoder(getU8Encoder()).encode([1, 2, 3]);
const array = getArrayDecoder(getU8Decoder()).decode(bytes);

getArrayCodec

On this page