getLiteralUnionCodec

Call Signature

function getLiteralUnionCodec<TVariants>(
    variants,
): FixedSizeCodec<
    GetTypeFromVariants<TVariants>,
    GetTypeFromVariants<TVariants>,
    1
>;

Returns a codec for encoding and decoding literal unions.

A literal union codec serializes and deserializes values from a predefined set of literals, using a numerical index to represent each value in the variants array.

This allows efficient storage and retrieval of common predefined values such as enum-like structures in TypeScript.

Type Parameters

Type Parameter	Description
`TVariants` extends readonly `Variant`[]	A tuple of allowed literal values.

Parameters

Parameter	Type	Description
`variants`	`TVariants`	The possible literal values for the union.

Returns

FixedSizeCodec<GetTypeFromVariants<TVariants>, GetTypeFromVariants<TVariants>, 1>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding literal unions.

Examples

Encoding and decoding a union of string literals.

type Size = 'small' | 'medium' | 'large';
const sizeCodec = getLiteralUnionCodec(['small', 'medium', 'large']);
 
sizeCodec.encode('small');  // 0x00
sizeCodec.encode('medium'); // 0x01
sizeCodec.encode('large');  // 0x02
 
sizeCodec.decode(new Uint8Array([0x00])); // 'small'
sizeCodec.decode(new Uint8Array([0x01])); // 'medium'
sizeCodec.decode(new Uint8Array([0x02])); // 'large'

Encoding and decoding a union of number literals.

type Level = 10 | 20 | 30;
const levelCodec = getLiteralUnionCodec([10, 20, 30]);
 
levelCodec.encode(10);  // 0x00
levelCodec.encode(20);  // 0x01
levelCodec.encode(30);  // 0x02
 
levelCodec.decode(new Uint8Array([0x00])); // 10
levelCodec.decode(new Uint8Array([0x01])); // 20
levelCodec.decode(new Uint8Array([0x02])); // 30

Using a custom discriminator size with different variant types.

type MaybeBoolean = false | true | "either";
const codec = getLiteralUnionCodec([false, true, 'either'], { size: getU16Codec() });
 
codec.encode(false);    // 0x0000
codec.encode(true);     // 0x0100
codec.encode('either'); // 0x0200
 
codec.decode(new Uint8Array([0x00, 0x00])); // false
codec.decode(new Uint8Array([0x01, 0x00])); // true
codec.decode(new Uint8Array([0x02, 0x00])); // 'either'

Remarks

Separate getLiteralUnionEncoder and getLiteralUnionDecoder functions are available.

const bytes = getLiteralUnionEncoder(['red', 'green', 'blue']).encode('green');
const value = getLiteralUnionDecoder(['red', 'green', 'blue']).decode(bytes);

See

Call Signature

function getLiteralUnionCodec<TVariants, TSize>(
    variants,
    config,
): FixedSizeCodec<
    GetTypeFromVariants<TVariants>,
    GetTypeFromVariants<TVariants>,
    TSize
>;

Returns a codec for encoding and decoding literal unions.

A literal union codec serializes and deserializes values from a predefined set of literals, using a numerical index to represent each value in the variants array.

This allows efficient storage and retrieval of common predefined values such as enum-like structures in TypeScript.

Type Parameters

Type Parameter	Description
`TVariants` extends readonly `Variant`[]	A tuple of allowed literal values.
`TSize` extends `number`	-

Parameters

Parameter	Type	Description
`variants`	`TVariants`	The possible literal values for the union.
`config`	`LiteralUnionCodecConfig`<`NumberCodec`> & `object`	Configuration options for encoding and decoding the literal union.

Returns

FixedSizeCodec<GetTypeFromVariants<TVariants>, GetTypeFromVariants<TVariants>, TSize>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding literal unions.

Examples

Encoding and decoding a union of string literals.

type Size = 'small' | 'medium' | 'large';
const sizeCodec = getLiteralUnionCodec(['small', 'medium', 'large']);
 
sizeCodec.encode('small');  // 0x00
sizeCodec.encode('medium'); // 0x01
sizeCodec.encode('large');  // 0x02
 
sizeCodec.decode(new Uint8Array([0x00])); // 'small'
sizeCodec.decode(new Uint8Array([0x01])); // 'medium'
sizeCodec.decode(new Uint8Array([0x02])); // 'large'

Encoding and decoding a union of number literals.

type Level = 10 | 20 | 30;
const levelCodec = getLiteralUnionCodec([10, 20, 30]);
 
levelCodec.encode(10);  // 0x00
levelCodec.encode(20);  // 0x01
levelCodec.encode(30);  // 0x02
 
levelCodec.decode(new Uint8Array([0x00])); // 10
levelCodec.decode(new Uint8Array([0x01])); // 20
levelCodec.decode(new Uint8Array([0x02])); // 30

Using a custom discriminator size with different variant types.

type MaybeBoolean = false | true | "either";
const codec = getLiteralUnionCodec([false, true, 'either'], { size: getU16Codec() });
 
codec.encode(false);    // 0x0000
codec.encode(true);     // 0x0100
codec.encode('either'); // 0x0200
 
codec.decode(new Uint8Array([0x00, 0x00])); // false
codec.decode(new Uint8Array([0x01, 0x00])); // true
codec.decode(new Uint8Array([0x02, 0x00])); // 'either'

Remarks

Separate getLiteralUnionEncoder and getLiteralUnionDecoder functions are available.

const bytes = getLiteralUnionEncoder(['red', 'green', 'blue']).encode('green');
const value = getLiteralUnionDecoder(['red', 'green', 'blue']).decode(bytes);

See

Call Signature

function getLiteralUnionCodec<TVariants>(
    variants,
    config?,
): VariableSizeCodec<GetTypeFromVariants<TVariants>>;

Returns a codec for encoding and decoding literal unions.

A literal union codec serializes and deserializes values from a predefined set of literals, using a numerical index to represent each value in the variants array.

This allows efficient storage and retrieval of common predefined values such as enum-like structures in TypeScript.

Type Parameters

Type Parameter	Description
`TVariants` extends readonly `Variant`[]	A tuple of allowed literal values.

Parameters

Parameter	Type	Description
`variants`	`TVariants`	The possible literal values for the union.
`config?`	`LiteralUnionCodecConfig`<`NumberCodec`>	Configuration options for encoding and decoding the literal union.

Returns

VariableSizeCodec<GetTypeFromVariants<TVariants>>

A FixedSizeCodec or VariableSizeCodec for encoding and decoding literal unions.

Examples

Encoding and decoding a union of string literals.

type Size = 'small' | 'medium' | 'large';
const sizeCodec = getLiteralUnionCodec(['small', 'medium', 'large']);
 
sizeCodec.encode('small');  // 0x00
sizeCodec.encode('medium'); // 0x01
sizeCodec.encode('large');  // 0x02
 
sizeCodec.decode(new Uint8Array([0x00])); // 'small'
sizeCodec.decode(new Uint8Array([0x01])); // 'medium'
sizeCodec.decode(new Uint8Array([0x02])); // 'large'

Encoding and decoding a union of number literals.

type Level = 10 | 20 | 30;
const levelCodec = getLiteralUnionCodec([10, 20, 30]);
 
levelCodec.encode(10);  // 0x00
levelCodec.encode(20);  // 0x01
levelCodec.encode(30);  // 0x02
 
levelCodec.decode(new Uint8Array([0x00])); // 10
levelCodec.decode(new Uint8Array([0x01])); // 20
levelCodec.decode(new Uint8Array([0x02])); // 30

Using a custom discriminator size with different variant types.

type MaybeBoolean = false | true | "either";
const codec = getLiteralUnionCodec([false, true, 'either'], { size: getU16Codec() });
 
codec.encode(false);    // 0x0000
codec.encode(true);     // 0x0100
codec.encode('either'); // 0x0200
 
codec.decode(new Uint8Array([0x00, 0x00])); // false
codec.decode(new Uint8Array([0x01, 0x00])); // true
codec.decode(new Uint8Array([0x02, 0x00])); // 'either'

Remarks

Separate getLiteralUnionEncoder and getLiteralUnionDecoder functions are available.

const bytes = getLiteralUnionEncoder(['red', 'green', 'blue']).encode('green');
const value = getLiteralUnionDecoder(['red', 'green', 'blue']).decode(bytes);

getLiteralUnionCodec

On this page