@solana/codecs-data-structures 6.3.1 → 6.3.2-canary-20260313112147

package/src/nullable.ts

@@ -0,0 +1,356 @@
+import {
+    assertIsFixedSize,
+    Codec,
+    combineCodec,
+    containsBytes,
+    Decoder,
+    Encoder,
+    fixDecoderSize,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    fixEncoderSize,
+    ReadonlyUint8Array,
+    transformDecoder,
+    transformEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+import {
+    FixedSizeNumberCodec,
+    FixedSizeNumberDecoder,
+    FixedSizeNumberEncoder,
+    getU8Decoder,
+    getU8Encoder,
+    NumberCodec,
+    NumberDecoder,
+    NumberEncoder,
+} from '@solana/codecs-numbers';
+
+import { getBooleanDecoder, getBooleanEncoder } from './boolean';
+import { getConstantDecoder, getConstantEncoder } from './constant';
+import { getTupleDecoder, getTupleEncoder } from './tuple';
+import { getUnionDecoder, getUnionEncoder } from './union';
+import { getUnitDecoder, getUnitEncoder } from './unit';
+
+/**
+ * Defines the configuration options for nullable codecs.
+ *
+ * This configuration controls how nullable values are encoded and decoded.
+ *
+ * By default, nullable values are prefixed with a `u8` (0 = `null`, 1 = present).
+ * The `noneValue` and `prefix` options allow customizing this behavior.
+ *
+ * @typeParam TPrefix - A number codec, encoder, or decoder used as the presence prefix.
+ *
+ * @see {@link getNullableEncoder}
+ * @see {@link getNullableDecoder}
+ * @see {@link getNullableCodec}
+ */
+export type NullableCodecConfig<TPrefix extends NumberCodec | NumberDecoder | NumberEncoder> = {
+    /**
+     * Specifies how `null` values are represented in the encoded data.
+     *
+     * - By default, `null` values are omitted from encoding.
+     * - `'zeroes'`: The bytes allocated for the value are filled with zeroes. This requires a fixed-size codec.
+     * - Custom byte array: `null` values are replaced with a predefined byte sequence. This results in a variable-size codec.
+     *
+     * @defaultValue No explicit `noneValue` is used; `null` values are omitted.
+     */
+    noneValue?: ReadonlyUint8Array | 'zeroes';
+
+    /**
+     * The presence prefix used to distinguish between `null` and present values.
+     *
+     * - By default, a `u8` prefix is used (`0 = null`, `1 = present`).
+     * - Custom number codec: Allows defining a different number size for the prefix.
+     * - `null`: No prefix is used; `noneValue` (if provided) determines `null`.
+     *   If no `noneValue` is set, `null` is identified by the absence of bytes.
+     *
+     * @defaultValue `u8` prefix.
+     */
+    prefix?: TPrefix | null;
+};
+
+/**
+ * Returns an encoder for optional values, allowing `null` values to be encoded.
+ *
+ * This encoder serializes an optional value using a configurable approach:
+ * - By default, a `u8` prefix is used (0 = `null`, 1 = present). This can be customized or disabled.
+ * - If `noneValue: 'zeroes'` is set, `null` values are encoded as zeroes.
+ * - If `noneValue` is a byte array, `null` values are replaced with the provided constant.
+ *
+ * For more details, see {@link getNullableCodec}.
+ *
+ * @typeParam TFrom - The type of the main value being encoded.
+ *
+ * @param item - The encoder for the value that may be present.
+ * @param config - Configuration options for encoding optional values.
+ * @returns A `FixedSizeEncoder` or `VariableSizeEncoder` for encoding nullable values.
+ *
+ * @example
+ * Encoding an optional number.
+ * ```ts
+ * const encoder = getNullableEncoder(getU32Encoder());
+ *
+ * encoder.encode(null); // 0x00
+ * encoder.encode(42);   // 0x012a000000
+ * ```
+ *
+ * @see {@link getNullableCodec}
+ */
+export function getNullableEncoder<TFrom, TSize extends number>(
+    item: FixedSizeEncoder<TFrom, TSize>,
+    config: NullableCodecConfig<NumberEncoder> & { noneValue: 'zeroes'; prefix: null },
+): FixedSizeEncoder<TFrom | null, TSize>;
+export function getNullableEncoder<TFrom>(
+    item: FixedSizeEncoder<TFrom>,
+    config: NullableCodecConfig<FixedSizeNumberEncoder> & { noneValue: 'zeroes' },
+): FixedSizeEncoder<TFrom | null>;
+export function getNullableEncoder<TFrom>(
+    item: FixedSizeEncoder<TFrom>,
+    config: NullableCodecConfig<NumberEncoder> & { noneValue: 'zeroes' },
+): VariableSizeEncoder<TFrom | null>;
+export function getNullableEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config?: NullableCodecConfig<NumberEncoder> & { noneValue?: ReadonlyUint8Array },
+): VariableSizeEncoder<TFrom | null>;
+export function getNullableEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config: NullableCodecConfig<NumberEncoder> = {},
+): Encoder<TFrom | null> {
+    const prefix = (() => {
+        if (config.prefix === null) {
+            return transformEncoder(getUnitEncoder(), (_boolean: boolean) => undefined);
+        }
+        return getBooleanEncoder({ size: config.prefix ?? getU8Encoder() });
+    })();
+    const noneValue = (() => {
+        if (config.noneValue === 'zeroes') {
+            assertIsFixedSize(item);
+            return fixEncoderSize(getUnitEncoder(), item.fixedSize);
+        }
+        if (!config.noneValue) {
+            return getUnitEncoder();
+        }
+        return getConstantEncoder(config.noneValue);
+    })();
+
+    return getUnionEncoder(
+        [
+            transformEncoder(getTupleEncoder([prefix, noneValue]), (_value: null): [boolean, void] => [
+                false,
+                undefined,
+            ]),
+            transformEncoder(getTupleEncoder([prefix, item]), (value: TFrom): [boolean, TFrom] => [true, value]),
+        ],
+        variant => Number(variant !== null),
+    );
+}
+
+/**
+ * Returns a decoder for optional values, allowing `null` values to be recognized.
+ *
+ * This decoder deserializes an optional value using a configurable approach:
+ * - By default, a `u8` prefix is used (0 = `null`, 1 = present). This can be customized or disabled.
+ * - If `noneValue: 'zeroes'` is set, `null` values are identified by zeroes.
+ * - If `noneValue` is a byte array, `null` values match the provided constant.
+ *
+ * For more details, see {@link getNullableCodec}.
+ *
+ * @typeParam TTo - The type of the main value being decoded.
+ *
+ * @param item - The decoder for the value that may be present.
+ * @param config - Configuration options for decoding optional values.
+ * @returns A `FixedSizeDecoder` or `VariableSizeDecoder` for decoding nullable values.
+ *
+ * @example
+ * Decoding an optional number.
+ * ```ts
+ * const decoder = getNullableDecoder(getU32Decoder());
+ *
+ * decoder.decode(new Uint8Array([0x00])); // null
+ * decoder.decode(new Uint8Array([0x01, 0x2a, 0x00, 0x00, 0x00])); // 42
+ * ```
+ *
+ * @see {@link getNullableCodec}
+ */
+export function getNullableDecoder<TTo, TSize extends number>(
+    item: FixedSizeDecoder<TTo, TSize>,
+    config: NullableCodecConfig<NumberDecoder> & { noneValue: 'zeroes'; prefix: null },
+): FixedSizeDecoder<TTo | null, TSize>;
+export function getNullableDecoder<TTo>(
+    item: FixedSizeDecoder<TTo>,
+    config: NullableCodecConfig<FixedSizeNumberDecoder> & { noneValue: 'zeroes' },
+): FixedSizeDecoder<TTo | null>;
+export function getNullableDecoder<TTo>(
+    item: FixedSizeDecoder<TTo>,
+    config: NullableCodecConfig<NumberDecoder> & { noneValue: 'zeroes' },
+): VariableSizeDecoder<TTo | null>;
+export function getNullableDecoder<TTo>(
+    item: Decoder<TTo>,
+    config?: NullableCodecConfig<NumberDecoder> & { noneValue?: ReadonlyUint8Array },
+): VariableSizeDecoder<TTo | null>;
+export function getNullableDecoder<TTo>(
+    item: Decoder<TTo>,
+    config: NullableCodecConfig<NumberDecoder> = {},
+): Decoder<TTo | null> {
+    const prefix = (() => {
+        if (config.prefix === null) {
+            return transformDecoder(getUnitDecoder(), () => false);
+        }
+        return getBooleanDecoder({ size: config.prefix ?? getU8Decoder() });
+    })();
+    const noneValue = (() => {
+        if (config.noneValue === 'zeroes') {
+            assertIsFixedSize(item);
+            return fixDecoderSize(getUnitDecoder(), item.fixedSize);
+        }
+        if (!config.noneValue) {
+            return getUnitDecoder();
+        }
+        return getConstantDecoder(config.noneValue);
+    })();
+
+    return getUnionDecoder(
+        [
+            transformDecoder(getTupleDecoder([prefix, noneValue]), () => null),
+            transformDecoder(getTupleDecoder([prefix, item]), ([, value]): TTo => value),
+        ],
+        (bytes, offset) => {
+            if (config.prefix === null && !config.noneValue) {
+                return Number(offset < bytes.length);
+            }
+            if (config.prefix === null && config.noneValue != null) {
+                const zeroValue =
+                    config.noneValue === 'zeroes' ? new Uint8Array(noneValue.fixedSize).fill(0) : config.noneValue;
+                return containsBytes(bytes, zeroValue, offset) ? 0 : 1;
+            }
+            return Number(prefix.read(bytes, offset)[0]);
+        },
+    );
+}
+
+/**
+ * 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 {@link NullableCodecConfig}.
+ *
+ * @typeParam TFrom - The type of the main value being encoded.
+ * @typeParam TTo - The type of the main value being decoded.
+ *
+ * @param item - The codec for the value that may be present.
+ * @param config - Configuration options for encoding and decoding optional values.
+ * @returns A `FixedSizeCodec` or `VariableSizeCodec` for encoding and decoding nullable values.
+ *
+ * @example
+ * Encoding and decoding an optional number using a `u8` prefix (default).
+ * ```ts
+ * 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
+ * ```
+ *
+ * @example
+ * Encoding and decoding an optional number using a fixed-size codec, by filling `null` values with zeroes.
+ * ```ts
+ * 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
+ * ```
+ *
+ * @example
+ * Encoding and decoding `null` values with zeroes and no prefix.
+ * ```ts
+ * 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
+ * ```
+ *
+ * @example
+ * Encoding and decoding `null` values with a custom byte sequence and no prefix.
+ * ```ts
+ * 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
+ * ```
+ *
+ * @example
+ * Identifying `null` values by the absence of bytes.
+ * ```ts
+ * 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 {@link getNullableEncoder} and {@link getNullableDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getNullableEncoder(getU32Encoder()).encode(42);
+ * const value = getNullableDecoder(getU32Decoder()).decode(bytes);
+ * ```
+ *
+ * @see {@link getNullableEncoder}
+ * @see {@link getNullableDecoder}
+ */
+export function getNullableCodec<TFrom, TTo extends TFrom, TSize extends number>(
+    item: FixedSizeCodec<TFrom, TTo, TSize>,
+    config: NullableCodecConfig<NumberCodec> & { noneValue: 'zeroes'; prefix: null },
+): FixedSizeCodec<TFrom | null, TTo | null, TSize>;
+export function getNullableCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: FixedSizeCodec<TFrom, TTo>,
+    config: NullableCodecConfig<FixedSizeNumberCodec> & { noneValue: 'zeroes' },
+): FixedSizeCodec<TFrom | null, TTo | null>;
+export function getNullableCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: FixedSizeCodec<TFrom, TTo>,
+    config: NullableCodecConfig<NumberCodec> & { noneValue: 'zeroes' },
+): VariableSizeCodec<TFrom | null, TTo | null>;
+export function getNullableCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config?: NullableCodecConfig<NumberCodec> & { noneValue?: ReadonlyUint8Array },
+): VariableSizeCodec<TFrom | null, TTo | null>;
+export function getNullableCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config: NullableCodecConfig<NumberCodec> = {},
+): Codec<TFrom | null, TTo | null> {
+    type ConfigCast = NullableCodecConfig<NumberCodec> & { noneValue?: ReadonlyUint8Array };
+    return combineCodec(
+        getNullableEncoder<TFrom>(item, config as ConfigCast),
+        getNullableDecoder<TTo>(item, config as ConfigCast),
+    );
+}

package/src/pattern-match.ts

@@ -0,0 +1,312 @@
+import {
+    Codec,
+    combineCodec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    ReadonlyUint8Array,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+import {
+    SOLANA_ERROR__CODECS__INVALID_PATTERN_MATCH_BYTES,
+    SOLANA_ERROR__CODECS__INVALID_PATTERN_MATCH_VALUE,
+    SolanaError,
+} from '@solana/errors';
+
+import { getUnionDecoder, getUnionEncoder } from './union';
+
+type PatternMatchEncoderEntry<TNarrowed, TFrom = TNarrowed> = TNarrowed extends TFrom
+    ? // Boolean predicate with original encoder
+          | readonly [(value: TFrom) => boolean, Encoder<TFrom>]
+          // Type predicate with narrowed encoder
+          | readonly [(value: TFrom) => value is TNarrowed, Encoder<TNarrowed>]
+    : never;
+
+type FixedSizePatternMatchEncoderEntry<
+    TNarrowed,
+    TFrom = TNarrowed,
+    TSize extends number = number,
+> = TNarrowed extends TFrom
+    ? // Boolean predicate with original encoder
+          | readonly [(value: TFrom) => boolean, FixedSizeEncoder<TFrom, TSize>]
+          // Type predicate with narrowed encoder
+          | readonly [(value: TFrom) => value is TNarrowed, FixedSizeEncoder<TNarrowed, TSize>]
+    : never;
+
+type VariableSizePatternMatchEncoderEntry<TNarrowed, TFrom = TNarrowed> = TNarrowed extends TFrom
+    ? // Boolean predicate with original encoder
+          | readonly [(value: TFrom) => boolean, VariableSizeEncoder<TFrom>]
+          // Type predicate with narrowed encoder
+          | readonly [(value: TFrom) => value is TNarrowed, VariableSizeEncoder<TNarrowed>]
+    : never;
+
+/**
+ * Returns an encoder that selects which variant encoder to use based on pattern matching.
+ *
+ * This encoder evaluates the value against a series of predicate functions in order,
+ * and uses the first matching encoder to encode the value.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ *
+ * @param patterns - An array of `[predicate, encoder]` pairs. Predicates are tested in order
+ * and the first matching encoder is used to encode the value. Note that predicates can be either
+ * type predicates that narrow the type of the value, or boolean predicates. If using type predicates,
+ * the encoder can be for the narrowed type.
+ * @returns An encoder that selects the appropriate variant based on the matched pattern.
+ *
+ * @throws Throws a {@link SOLANA_ERROR__CODECS__INVALID_PATTERN_MATCH_VALUE} error
+ * if the value does not match any of the specified patterns.
+ *
+ * @example
+ * Encoding values using pattern matching.
+ * ```ts
+ * const encoder = getPatternMatchEncoder([
+ *   [(n: number) => n < 256, getU8Encoder()],
+ *   [(n: number) => n < 2 ** 16, getU16Encoder()],
+ *   [(n: number) => n < 2 ** 32, getU32Encoder()]
+ * ]);
+ *
+ * encoder.encode(42);
+ * // 0x2a
+ * //  └── Small number encoded as u8
+ *
+ * encoder.encode(1000);
+ * // 0xe803
+ * //   └── Medium number encoded as u16
+ *
+ *
+ * encoder.encode(100_000);
+ * // 0xa0860100
+ * //   └── Large number encoded as u32
+ *
+ * ender.encode(2 ** 32 + 1);
+ * // Throws an error because the value does not match any pattern
+ * ```
+ *
+ * @see {@link getPatternMatchCodec}
+ */
+export function getPatternMatchEncoder<TFrom, TSize extends number>(
+    patterns: FixedSizePatternMatchEncoderEntry<TFrom, TFrom, TSize>[],
+): FixedSizeEncoder<TFrom, TSize>;
+export function getPatternMatchEncoder<TFrom>(
+    patterns: FixedSizePatternMatchEncoderEntry<TFrom>[],
+): FixedSizeEncoder<TFrom>;
+export function getPatternMatchEncoder<TFrom>(
+    patterns: VariableSizePatternMatchEncoderEntry<TFrom>[],
+): VariableSizeEncoder<TFrom>;
+export function getPatternMatchEncoder<TFrom>(patterns: PatternMatchEncoderEntry<TFrom>[]): Encoder<TFrom>;
+export function getPatternMatchEncoder<TFrom>(patterns: PatternMatchEncoderEntry<TFrom>[]): Encoder<TFrom> {
+    return getUnionEncoder(
+        patterns.map(([, encoder]) => encoder),
+        (value: TFrom) => {
+            const index = patterns.findIndex(([predicate]) => predicate(value));
+            if (index === -1) {
+                throw new SolanaError(SOLANA_ERROR__CODECS__INVALID_PATTERN_MATCH_VALUE);
+            }
+            return index;
+        },
+    );
+}
+
+/**
+ * Returns a decoder that selects which variant decoder to use based on pattern matching.
+ *
+ * This decoder evaluates the byte array against a series of predicate functions in order,
+ * and uses the first matching decoder to decode the value.
+ *
+ * @typeParam TTo - The type of the value to decode.
+ *
+ * @param patterns - An array of `[predicate, decoder]` pairs. Predicates are tested in order
+ * and the first matching decoder is used to decode the byte array.
+ * @returns A decoder that selects the appropriate variant based on the matched byte pattern.
+ *
+ * @throws Throws a {@link SOLANA_ERROR__CODECS__INVALID_PATTERN_MATCH_BYTES} error
+ * if the byte array does not match any of the specified patterns.
+ *
+ * @example
+ * Decoding values using pattern matching on bytes.
+ * ```ts
+ * const decoder = getPatternMatchDecoder([
+ *   [(bytes) => bytes.length === 1, getU8Decoder()],
+ *   [(bytes) => bytes.length === 2, getU16Decoder()],
+ *   [(bytes) => bytes.length <= 4, getU32Decoder()]
+ * ]);
+ *
+ * decoder.decode(new Uint8Array([0x2a])); // 42 (decoded as u8)
+ * decoder.decode(new Uint8Array([0xe8, 0x03])) // 1000 (decoded as u16)
+ * decoder.decode(new Uint8Array([0xa0, 0x86, 0x01, 0x00])) // 100_000 (decoded as u32)
+ * decoder.decode(new Uint8Array([0xa0, 0x86, 0x01, 0x00, 0x00]))
+ * // Throws an error because the bytes do not match any pattern
+ * ```
+ *
+ * @see {@link getPatternMatchCodec}
+ * @see {@link getPatternMatchEncoder}
+ */
+export function getPatternMatchDecoder<TTo, TSize extends number>(
+    patterns: [(value: ReadonlyUint8Array) => boolean, FixedSizeDecoder<TTo, TSize>][],
+): FixedSizeDecoder<TTo, TSize>;
+export function getPatternMatchDecoder<TTo>(
+    patterns: [(value: ReadonlyUint8Array) => boolean, FixedSizeDecoder<TTo>][],
+): FixedSizeDecoder<TTo>;
+export function getPatternMatchDecoder<TTo>(
+    patterns: [(value: ReadonlyUint8Array) => boolean, VariableSizeDecoder<TTo>][],
+): VariableSizeDecoder<TTo>;
+export function getPatternMatchDecoder<TTo>(
+    patterns: [(value: ReadonlyUint8Array) => boolean, Decoder<TTo>][],
+): Decoder<TTo>;
+export function getPatternMatchDecoder<TTo>(
+    patterns: [(value: ReadonlyUint8Array) => boolean, Decoder<TTo>][],
+): Decoder<TTo> {
+    return getUnionDecoder(
+        patterns.map(([, decoder]) => decoder),
+        (value: ReadonlyUint8Array) => {
+            const index = patterns.findIndex(([predicate]) => predicate(value));
+            if (index === -1) {
+                throw new SolanaError(SOLANA_ERROR__CODECS__INVALID_PATTERN_MATCH_BYTES, {
+                    bytes: value,
+                });
+            }
+            return index;
+        },
+    );
+}
+
+type PatternMatchCodecEntry<TNarrowedFrom, TFrom = TNarrowedFrom, TTo = TNarrowedFrom> = TNarrowedFrom extends TFrom
+    ? TTo extends TNarrowedFrom
+        ?
+              | readonly [
+                    (value: TFrom) => value is TNarrowedFrom,
+                    (bytes: ReadonlyUint8Array) => boolean,
+                    Codec<TNarrowedFrom, TTo>,
+                ]
+              | readonly [(value: TFrom) => boolean, (bytes: ReadonlyUint8Array) => boolean, Codec<TFrom, TTo>]
+        : never
+    : never;
+
+type FixedSizePatternMatchCodecEntry<
+    TNarrowedFrom,
+    TFrom = TNarrowedFrom,
+    TTo = TNarrowedFrom,
+    TSize extends number = number,
+> = TNarrowedFrom extends TFrom
+    ? TTo extends TNarrowedFrom
+        ?
+              | readonly [
+                    (value: TFrom) => boolean,
+                    (bytes: ReadonlyUint8Array) => boolean,
+                    FixedSizeCodec<TFrom, TTo, TSize>,
+                ]
+              | readonly [
+                    (value: TFrom) => value is TNarrowedFrom,
+                    (bytes: ReadonlyUint8Array) => boolean,
+                    FixedSizeCodec<TNarrowedFrom, TTo, TSize>,
+                ]
+        : never
+    : never;
+
+type VariableSizePatternMatchCodecEntry<
+    TNarrowedFrom,
+    TFrom = TNarrowedFrom,
+    TTo = TNarrowedFrom,
+> = TNarrowedFrom extends TFrom
+    ? TTo extends TNarrowedFrom
+        ?
+              | readonly [
+                    (value: TFrom) => boolean,
+                    (bytes: ReadonlyUint8Array) => boolean,
+                    VariableSizeCodec<TFrom, TTo>,
+                ]
+              | readonly [
+                    (value: TFrom) => value is TNarrowedFrom,
+                    (bytes: ReadonlyUint8Array) => boolean,
+                    VariableSizeCodec<TNarrowedFrom, TTo>,
+                ]
+        : never
+    : never;
+
+/**
+ * Returns a codec that selects which variant codec to use based on pattern matching.
+ *
+ * This codec evaluates values and byte arrays against a series of predicate functions in order,
+ * using the first matching codec for encoding or decoding.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ * @typeParam TTo - The type of the value to decode.
+ *
+ * @param patterns - An array of `[valuePredicate, bytesPredicate, codec]` triples. Predicates
+ * are tested in order and the first match determines the codec used. During encoding,
+ * `valuePredicate` receives the value to encode. During decoding, `bytesPredicate` receives
+ * the byte array.
+ * @returns A codec that selects the appropriate variant based on the matched pattern.
+ *
+ * @throws Throws a {@link SOLANA_ERROR__CODECS__INVALID_PATTERN_MATCH_VALUE} error
+ * if a value being encoded does not match any of the specified patterns.
+ * @throws Throws a {@link SOLANA_ERROR__CODECS__INVALID_PATTERN_MATCH_BYTES} error
+ * if a byte array being decoded does not match any of the specified patterns.
+ *
+ * @example
+ * Encoding and decoding using pattern matching.
+ * ```ts
+ * const codec = getPatternMatchCodec([
+ *  [
+ *    (n: number) => n < 256,
+ *    (bytes) => bytes.length === 1,
+ *    getU8Codec(),
+ *  ],
+ *  [
+ *    (n: number) => n < 2 ** 16,
+ *    (bytes) => bytes.length === 2,
+ *    getU16Codec(),
+ *  ],
+ *  [
+ *    (n: number) => n < 2 ** 32,
+ *    (bytes) => bytes.length <= 4,
+ *    getU32Codec(),
+ *  ]
+ * ]);
+ *
+ * const bytes1 = codec.encode(42);     // 0x2a, encoded as u8
+ * const value1 = codec.decode(bytes1); // 42, decoded as u8
+ *
+ * const bytes2 = codec.encode(1000);   // 0xe803, encoded as u16
+ * const value2 = codec.decode(bytes2); // 1000, decoded as u16
+ *
+ * const bytes3 = codec.encode(100_000); //0xa0860100, encoded as u32
+ * const value3 = codec.decode(bytes3); // 100_000, decoded as u32
+ *
+ * codec.encode(2 ** 32 + 1);
+ * // throws, no encode pattern matches
+ * codec.decode(new Uint8Array([0xa0, 0x86, 0x01, 0x00, 0x00]))
+ * // throws, no decode pattern matches
+ * ```
+ *
+ * @see {@link getPatternMatchEncoder}
+ * @see {@link getPatternMatchDecoder}
+ * @see {@link getUnionCodec}
+ */
+export function getPatternMatchCodec<TFrom, TTo extends TFrom = TFrom, TSize extends number = number>(
+    patterns: FixedSizePatternMatchCodecEntry<TFrom, TFrom, TTo, TSize>[],
+): FixedSizeCodec<TFrom, TTo, TSize>;
+export function getPatternMatchCodec<TFrom, TTo extends TFrom = TFrom>(
+    patterns: FixedSizePatternMatchCodecEntry<TFrom, TFrom, TTo>[],
+): FixedSizeCodec<TFrom, TTo>;
+export function getPatternMatchCodec<TFrom, TTo extends TFrom = TFrom>(
+    patterns: VariableSizePatternMatchCodecEntry<TFrom, TFrom, TTo>[],
+): VariableSizeCodec<TFrom, TTo>;
+export function getPatternMatchCodec<TFrom, TTo extends TFrom = TFrom>(
+    patterns: PatternMatchCodecEntry<TFrom, TFrom, TTo>[],
+): Codec<TFrom, TTo>;
+export function getPatternMatchCodec<TFrom, TTo extends TFrom = TFrom>(
+    patterns: PatternMatchCodecEntry<TFrom, TFrom, TTo>[],
+): Codec<TFrom, TTo> {
+    return combineCodec(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        getPatternMatchEncoder(patterns.map(([valuePredicate, , codec]) => [valuePredicate, codec]) as any),
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        getPatternMatchDecoder(patterns.map(([, bytesPredicate, codec]) => [bytesPredicate, codec]) as any),
+    );
+}