getDiscriminatedUnionCodec

function getDiscriminatedUnionCodec<TVariants, TDiscriminatorProperty>(
    variants,
    config?,
): UnionCodec<TVariants, TDiscriminatorProperty>;

Returns a codec for encoding and decoding DiscriminatedUnion.

A DiscriminatedUnion is a TypeScript representation of Rust-like enums, where each variant is distinguished by a discriminator field (default: __kind).

This codec inserts a numerical prefix to represent the variant index.

Type Parameters

Type Parameter	Default type	Description
`TVariants` extends `Variants`<`Codec`<`any`, `any`>>	-	The variants of the discriminated union.
`TDiscriminatorProperty` extends `string`	`"__kind"`	The property used as the discriminator.

Parameters

Parameter	Type	Description
`variants`	`TVariants`	The variant codecs as `[discriminator, codec]` pairs.
`config?`	`DiscriminatedUnionCodecConfig`<`TDiscriminatorProperty`, `NumberCodec`>	Configuration options for encoding/decoding.

Returns

UnionCodec<TVariants, TDiscriminatorProperty>

A Codec for encoding and decoding discriminated union objects.

Examples

Encoding and decoding a discriminated union.

type Message =
  | { __kind: 'Quit' } // Empty variant.
  | { __kind: 'Write'; fields: [string] } // Tuple variant.
  | { __kind: 'Move'; x: number; y: number }; // Struct variant.
 
const messageCodec = getDiscriminatedUnionCodec([
  ['Quit', getUnitCodec()],
  ['Write', getStructCodec([['fields', getTupleCodec([addCodecSizePrefix(getUtf8Codec(), getU32Codec())])]])],
  ['Move', getStructCodec([['x', getI32Codec()], ['y', getI32Codec()]])]
]);
 
messageCodec.encode({ __kind: 'Move', x: 5, y: 6 });
// 0x020500000006000000
//   | |       └── Field y (6)
//   | └── Field x (5)
//   └── 1-byte discriminator (Index 2 — the "Move" variant)
 
const value = messageCodec.decode(bytes);
// { __kind: 'Move', x: 5, y: 6 }

Using a u32 discriminator instead of u8.

const codec = getDiscriminatedUnionCodec([...], { size: getU32Codec() });
 
codec.encode({ __kind: 'Quit' });
// 0x00000000
//   └------┘ 4-byte discriminator (Index 0)
 
codec.decode(new Uint8Array([0x00, 0x00, 0x00, 0x00]));
// { __kind: 'Quit' }

Customizing the discriminator property.

const codec = getDiscriminatedUnionCodec([...], { discriminator: 'message' });
 
codec.encode({ message: 'Quit' }); // 0x00
codec.decode(new Uint8Array([0x00])); // { message: 'Quit' }

Remarks

Separate getDiscriminatedUnionEncoder and getDiscriminatedUnionDecoder functions are available.

const bytes = getDiscriminatedUnionEncoder(variantEncoders).encode({ __kind: 'Quit' });
const message = getDiscriminatedUnionDecoder(variantDecoders).decode(bytes);