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

package/src/enum.ts

@@ -0,0 +1,309 @@
+import {
+    Codec,
+    combineCodec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    transformDecoder,
+    transformEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+import {
+    FixedSizeNumberCodec,
+    FixedSizeNumberDecoder,
+    FixedSizeNumberEncoder,
+    getU8Decoder,
+    getU8Encoder,
+    NumberCodec,
+    NumberDecoder,
+    NumberEncoder,
+} from '@solana/codecs-numbers';
+import {
+    SOLANA_ERROR__CODECS__CANNOT_USE_LEXICAL_VALUES_AS_ENUM_DISCRIMINATORS,
+    SOLANA_ERROR__CODECS__ENUM_DISCRIMINATOR_OUT_OF_RANGE,
+    SOLANA_ERROR__CODECS__INVALID_ENUM_VARIANT,
+    SolanaError,
+} from '@solana/errors';
+
+import {
+    EnumLookupObject,
+    formatNumericalValues,
+    GetEnumFrom,
+    getEnumIndexFromDiscriminator,
+    getEnumIndexFromVariant,
+    getEnumStats,
+    GetEnumTo,
+} from './enum-helpers';
+
+/**
+ * Defines the configuration options for enum codecs.
+ *
+ * The `size` option determines the numerical encoding used for the enum's discriminant.
+ * By default, enums are stored as a `u8` (1 byte).
+ *
+ * The `useValuesAsDiscriminators` option allows mapping the actual enum values
+ * as discriminators instead of using their positional index.
+ *
+ * @typeParam TDiscriminator - A number codec, encoder, or decoder used for the discriminant.
+ */
+export type EnumCodecConfig<TDiscriminator extends NumberCodec | NumberDecoder | NumberEncoder> = {
+    /**
+     * The codec used to encode/decode the enum discriminator.
+     * @defaultValue `u8` discriminator.
+     */
+    size?: TDiscriminator;
+
+    /**
+     * If set to `true`, the enum values themselves will be used as discriminators.
+     * This is only valid for numerical enum values.
+     *
+     * @defaultValue `false`
+     */
+    useValuesAsDiscriminators?: boolean;
+};
+
+/**
+ * Returns an encoder for enums.
+ *
+ * This encoder serializes enums as a numerical discriminator.
+ * By default, the discriminator is based on the positional index of the enum variants.
+ *
+ * For more details, see {@link getEnumCodec}.
+ *
+ * @typeParam TEnum - The TypeScript enum or object mapping enum keys to values.
+ *
+ * @param constructor - The constructor of the enum.
+ * @param config - Configuration options for encoding the enum.
+ * @returns A `FixedSizeEncoder` or `VariableSizeEncoder` for encoding enums.
+ *
+ * @example
+ * Encoding enum values.
+ * ```ts
+ * enum Direction { Up,  Down, Left, Right }
+ * const encoder = getEnumEncoder(Direction);
+ *
+ * encoder.encode(Direction.Up);    // 0x00
+ * encoder.encode(Direction.Down);  // 0x01
+ * encoder.encode(Direction.Left);  // 0x02
+ * encoder.encode(Direction.Right); // 0x03
+ * ```
+ *
+ * @see {@link getEnumCodec}
+ */
+export function getEnumEncoder<TEnum extends EnumLookupObject>(
+    constructor: TEnum,
+    config?: Omit<EnumCodecConfig<NumberEncoder>, 'size'>,
+): FixedSizeEncoder<GetEnumFrom<TEnum>, 1>;
+export function getEnumEncoder<TEnum extends EnumLookupObject, TSize extends number>(
+    constructor: TEnum,
+    config: EnumCodecConfig<NumberEncoder> & { size: FixedSizeNumberEncoder<TSize> },
+): FixedSizeEncoder<GetEnumFrom<TEnum>, TSize>;
+export function getEnumEncoder<TEnum extends EnumLookupObject>(
+    constructor: TEnum,
+    config?: EnumCodecConfig<NumberEncoder>,
+): VariableSizeEncoder<GetEnumFrom<TEnum>>;
+export function getEnumEncoder<TEnum extends EnumLookupObject>(
+    constructor: TEnum,
+    config: EnumCodecConfig<NumberEncoder> = {},
+): Encoder<GetEnumFrom<TEnum>> {
+    const prefix = config.size ?? getU8Encoder();
+    const useValuesAsDiscriminators = config.useValuesAsDiscriminators ?? false;
+    const { enumKeys, enumValues, numericalValues, stringValues } = getEnumStats(constructor);
+    if (useValuesAsDiscriminators && enumValues.some(value => typeof value === 'string')) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__CANNOT_USE_LEXICAL_VALUES_AS_ENUM_DISCRIMINATORS, {
+            stringValues: enumValues.filter((v): v is string => typeof v === 'string'),
+        });
+    }
+    return transformEncoder(prefix, (variant: GetEnumFrom<TEnum>): number => {
+        const index = getEnumIndexFromVariant({ enumKeys, enumValues, variant });
+        if (index < 0) {
+            throw new SolanaError(SOLANA_ERROR__CODECS__INVALID_ENUM_VARIANT, {
+                formattedNumericalValues: formatNumericalValues(numericalValues),
+                numericalValues,
+                stringValues,
+                variant,
+            });
+        }
+        return useValuesAsDiscriminators ? (enumValues[index] as number) : index;
+    });
+}
+
+/**
+ * Returns a decoder for enums.
+ *
+ * This decoder deserializes enums from a numerical discriminator.
+ * By default, the discriminator is based on the positional index of the enum variants.
+ *
+ * For more details, see {@link getEnumCodec}.
+ *
+ * @typeParam TEnum - The TypeScript enum or object mapping enum keys to values.
+ *
+ * @param constructor - The constructor of the enum.
+ * @param config - Configuration options for decoding the enum.
+ * @returns A `FixedSizeDecoder` or `VariableSizeDecoder` for decoding enums.
+ *
+ * @example
+ * Decoding enum values.
+ * ```ts
+ * enum Direction { Up,  Down, Left, Right }
+ * const decoder = getEnumDecoder(Direction);
+ *
+ * decoder.decode(new Uint8Array([0x00])); // Direction.Up
+ * decoder.decode(new Uint8Array([0x01])); // Direction.Down
+ * decoder.decode(new Uint8Array([0x02])); // Direction.Left
+ * decoder.decode(new Uint8Array([0x03])); // Direction.Right
+ * ```
+ *
+ * @see {@link getEnumCodec}
+ */
+export function getEnumDecoder<TEnum extends EnumLookupObject>(
+    constructor: TEnum,
+    config?: Omit<EnumCodecConfig<NumberDecoder>, 'size'>,
+): FixedSizeDecoder<GetEnumTo<TEnum>, 1>;
+export function getEnumDecoder<TEnum extends EnumLookupObject, TSize extends number>(
+    constructor: TEnum,
+    config: EnumCodecConfig<NumberDecoder> & { size: FixedSizeNumberDecoder<TSize> },
+): FixedSizeDecoder<GetEnumTo<TEnum>, TSize>;
+export function getEnumDecoder<TEnum extends EnumLookupObject>(
+    constructor: TEnum,
+    config?: EnumCodecConfig<NumberDecoder>,
+): VariableSizeDecoder<GetEnumTo<TEnum>>;
+export function getEnumDecoder<TEnum extends EnumLookupObject>(
+    constructor: TEnum,
+    config: EnumCodecConfig<NumberDecoder> = {},
+): Decoder<GetEnumTo<TEnum>> {
+    const prefix = config.size ?? getU8Decoder();
+    const useValuesAsDiscriminators = config.useValuesAsDiscriminators ?? false;
+    const { enumKeys, enumValues, numericalValues } = getEnumStats(constructor);
+    if (useValuesAsDiscriminators && enumValues.some(value => typeof value === 'string')) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__CANNOT_USE_LEXICAL_VALUES_AS_ENUM_DISCRIMINATORS, {
+            stringValues: enumValues.filter((v): v is string => typeof v === 'string'),
+        });
+    }
+    return transformDecoder(prefix, (value: bigint | number): GetEnumTo<TEnum> => {
+        const discriminator = Number(value);
+        const index = getEnumIndexFromDiscriminator({
+            discriminator,
+            enumKeys,
+            enumValues,
+            useValuesAsDiscriminators,
+        });
+        if (index < 0) {
+            const validDiscriminators = useValuesAsDiscriminators
+                ? numericalValues
+                : [...Array(enumKeys.length).keys()];
+            throw new SolanaError(SOLANA_ERROR__CODECS__ENUM_DISCRIMINATOR_OUT_OF_RANGE, {
+                discriminator,
+                formattedValidDiscriminators: formatNumericalValues(validDiscriminators),
+                validDiscriminators,
+            });
+        }
+        return enumValues[index] as GetEnumTo<TEnum>;
+    });
+}
+
+/**
+ * Returns a codec for encoding and decoding enums.
+ *
+ * This codec serializes enums as a numerical discriminator, allowing them
+ * to be efficiently stored and reconstructed from binary data.
+ *
+ * By default, the discriminator is derived from the positional index
+ * of the enum variant, but it can be configured to use the enum's numeric values instead.
+ *
+ * @typeParam TEnum - The TypeScript enum or object mapping enum keys to values.
+ *
+ * @param constructor - The constructor of the enum.
+ * @param config - Configuration options for encoding and decoding the enum.
+ * @returns A `FixedSizeCodec` or `VariableSizeCodec` for encoding and decoding enums.
+ *
+ * @example
+ * Encoding and decoding enums using positional indexes.
+ * ```ts
+ * enum Direction { Up, Down, Left, Right }
+ * const codec = getEnumCodec(Direction);
+ *
+ * codec.encode(Direction.Up);    // 0x00
+ * codec.encode(Direction.Down);  // 0x01
+ * codec.encode(Direction.Left);  // 0x02
+ * codec.encode(Direction.Right); // 0x03
+ *
+ * codec.decode(new Uint8Array([0x00])); // Direction.Up
+ * codec.decode(new Uint8Array([0x01])); // Direction.Down
+ * codec.decode(new Uint8Array([0x02])); // Direction.Left
+ * codec.decode(new Uint8Array([0x03])); // Direction.Right
+ * ```
+ *
+ * @example
+ * Encoding and decoding enums using their numeric values.
+ * ```ts
+ * enum GameDifficulty { Easy = 1, Normal = 4, Hard = 7, Expert = 9 }
+ * const codec = getEnumCodec(GameDifficulty, { useValuesAsDiscriminators: true });
+ *
+ * codec.encode(GameDifficulty.Easy);   // 0x01
+ * codec.encode(GameDifficulty.Normal); // 0x04
+ * codec.encode(GameDifficulty.Hard);   // 0x07
+ * codec.encode(GameDifficulty.Expert); // 0x09
+ *
+ * codec.decode(new Uint8Array([0x01])); // GameDifficulty.Easy
+ * codec.decode(new Uint8Array([0x04])); // GameDifficulty.Normal
+ * codec.decode(new Uint8Array([0x07])); // GameDifficulty.Hard
+ * codec.decode(new Uint8Array([0x09])); // GameDifficulty.Expert
+ * ```
+ *
+ * Note that, when using values as discriminators, the enum values must be numerical.
+ * Otherwise, an error will be thrown.
+ *
+ * ```ts
+ * enum GameDifficulty { Easy = 'EASY', Normal = 'NORMAL', Hard = 'HARD' }
+ * getEnumCodec(GameDifficulty, { useValuesAsDiscriminators: true }); // Throws an error.
+ * ```
+ *
+ * @example
+ * Using a custom discriminator size.
+ * ```ts
+ * enum Status { Pending, Approved, Rejected }
+ * const codec = getEnumCodec(Status, { size: getU16Codec() });
+ *
+ * codec.encode(Status.Pending);  // 0x0000
+ * codec.encode(Status.Approved); // 0x0100
+ * codec.encode(Status.Rejected); // 0x0200
+ *
+ * codec.decode(new Uint8Array([0x00, 0x00])); // Status.Pending
+ * codec.decode(new Uint8Array([0x01, 0x00])); // Status.Approved
+ * codec.decode(new Uint8Array([0x02, 0x00])); // Status.Rejected
+ * ```
+ *
+ * @remarks
+ * Separate {@link getEnumEncoder} and {@link getEnumDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getEnumEncoder(Direction).encode(Direction.Up);
+ * const value = getEnumDecoder(Direction).decode(bytes);
+ * ```
+ *
+ * @see {@link getEnumEncoder}
+ * @see {@link getEnumDecoder}
+ */
+export function getEnumCodec<TEnum extends EnumLookupObject>(
+    constructor: TEnum,
+    config?: Omit<EnumCodecConfig<NumberCodec>, 'size'>,
+): FixedSizeCodec<GetEnumFrom<TEnum>, GetEnumTo<TEnum>, 1>;
+export function getEnumCodec<TEnum extends EnumLookupObject, TSize extends number>(
+    constructor: TEnum,
+    config: EnumCodecConfig<NumberCodec> & { size: FixedSizeNumberCodec<TSize> },
+): FixedSizeCodec<GetEnumFrom<TEnum>, GetEnumTo<TEnum>, TSize>;
+export function getEnumCodec<TEnum extends EnumLookupObject>(
+    constructor: TEnum,
+    config?: EnumCodecConfig<NumberCodec>,
+): VariableSizeCodec<GetEnumFrom<TEnum>, GetEnumTo<TEnum>>;
+export function getEnumCodec<TEnum extends EnumLookupObject>(
+    constructor: TEnum,
+    config: EnumCodecConfig<NumberCodec> = {},
+): Codec<GetEnumFrom<TEnum>, GetEnumTo<TEnum>> {
+    return combineCodec(getEnumEncoder(constructor, config), getEnumDecoder(constructor, config));
+}

package/src/hidden-prefix.ts

@@ -0,0 +1,180 @@
+import {
+    Codec,
+    combineCodec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    transformDecoder,
+    transformEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+
+import { getTupleDecoder, getTupleEncoder } from './tuple';
+
+/**
+ * Returns an encoder that prefixes encoded values with hidden data.
+ *
+ * This encoder applies a list of void encoders before encoding the main value.
+ * The prefixed data is encoded before the main value without being exposed to the user.
+ *
+ * For more details, see {@link getHiddenPrefixCodec}.
+ *
+ * @typeParam TFrom - The type of the main value being encoded.
+ *
+ * @param encoder - The encoder for the main value.
+ * @param prefixedEncoders - A list of void encoders that produce the hidden prefix.
+ * @returns A `FixedSizeEncoder` or `VariableSizeEncoder` that encodes the value with a hidden prefix.
+ *
+ * @example
+ * Prefixing a value with constants.
+ * ```ts
+ * const encoder = getHiddenPrefixEncoder(getUtf8Encoder(), [
+ *   getConstantCodec(new Uint8Array([1, 2, 3])),
+ *   getConstantCodec(new Uint8Array([4, 5, 6])),
+ * ]);
+ *
+ * encoder.encode('Hello');
+ * // 0x01020304050648656c6c6f
+ * //   |     |     └-- Our encoded value ("Hello").
+ * //   |     └-- Our second hidden prefix.
+ * //   └-- Our first hidden prefix.
+ * ```
+ *
+ * @see {@link getHiddenPrefixCodec}
+ */
+export function getHiddenPrefixEncoder<TFrom>(
+    encoder: FixedSizeEncoder<TFrom>,
+    prefixedEncoders: readonly FixedSizeEncoder<void>[],
+): FixedSizeEncoder<TFrom>;
+export function getHiddenPrefixEncoder<TFrom>(
+    encoder: Encoder<TFrom>,
+    prefixedEncoders: readonly Encoder<void>[],
+): VariableSizeEncoder<TFrom>;
+export function getHiddenPrefixEncoder<TFrom>(
+    encoder: Encoder<TFrom>,
+    prefixedEncoders: readonly Encoder<void>[],
+): Encoder<TFrom> {
+    return transformEncoder(
+        getTupleEncoder([...prefixedEncoders, encoder]) as Encoder<readonly [...void[], TFrom]>,
+        (value: TFrom) => [...prefixedEncoders.map(() => undefined), value] as const,
+    );
+}
+
+/**
+ * Returns a decoder that skips hidden prefixed data before decoding the main value.
+ *
+ * This decoder applies a list of void decoders before decoding the main value.
+ * The prefixed data is skipped during decoding without being exposed to the user.
+ *
+ * For more details, see {@link getHiddenPrefixCodec}.
+ *
+ * @typeParam TTo - The type of the main value being decoded.
+ *
+ * @param decoder - The decoder for the main value.
+ * @param prefixedDecoders - A list of void decoders that produce the hidden prefix.
+ * @returns A `FixedSizeDecoder` or `VariableSizeDecoder` that decodes values while ignoring the hidden prefix.
+ *
+ * @example
+ * Decoding a value with prefixed constants.
+ * ```ts
+ * const decoder = getHiddenPrefixDecoder(getUtf8Decoder(), [
+ *   getConstantCodec(new Uint8Array([1, 2, 3])),
+ *   getConstantCodec(new Uint8Array([4, 5, 6])),
+ * ]);
+ *
+ * decoder.decode(new Uint8Array([1, 2, 3, 4, 5, 6, 0x48, 0x65, 0x6C, 0x6C, 0x6F]));
+ * // 'Hello'
+ * ```
+ *
+ * @see {@link getHiddenPrefixCodec}
+ */
+export function getHiddenPrefixDecoder<TTo>(
+    decoder: FixedSizeDecoder<TTo>,
+    prefixedDecoders: readonly FixedSizeDecoder<void>[],
+): FixedSizeDecoder<TTo>;
+export function getHiddenPrefixDecoder<TTo>(
+    decoder: Decoder<TTo>,
+    prefixedDecoders: readonly Decoder<void>[],
+): VariableSizeDecoder<TTo>;
+export function getHiddenPrefixDecoder<TTo>(
+    decoder: Decoder<TTo>,
+    prefixedDecoders: readonly Decoder<void>[],
+): Decoder<TTo> {
+    return transformDecoder(
+        getTupleDecoder([...prefixedDecoders, decoder]) as Decoder<readonly [...void[], TTo]>,
+        tuple => tuple[tuple.length - 1] as TTo,
+    );
+}
+
+/**
+ * Returns a codec that encodes and decodes values with a hidden prefix.
+ *
+ * - **Encoding:** Prefixes the value with hidden data before encoding.
+ * - **Decoding:** Skips the hidden prefix before decoding the main value.
+ *
+ * This is useful for any implicit metadata that should be present in
+ * binary formats but omitted from the API.
+ *
+ * @typeParam TFrom - The type of the main value being encoded.
+ * @typeParam TTo - The type of the main value being decoded.
+ *
+ * @param codec - The codec for the main value.
+ * @param prefixedCodecs - A list of void codecs that produce the hidden prefix.
+ * @returns A `FixedSizeCodec` or `VariableSizeCodec` for encoding and decoding values with a hidden prefix.
+ *
+ * @example
+ * Encoding and decoding a value with prefixed constants.
+ * ```ts
+ * const codec = getHiddenPrefixCodec(getUtf8Codec(), [
+ *   getConstantCodec(new Uint8Array([1, 2, 3])),
+ *   getConstantCodec(new Uint8Array([4, 5, 6])),
+ * ]);
+ *
+ * const bytes = codec.encode('Hello');
+ * // 0x01020304050648656c6c6f
+ * //   |     |     └-- Our encoded value ("Hello").
+ * //   |     └-- Our second hidden prefix.
+ * //   └-- Our first hidden prefix.
+ *
+ * codec.decode(bytes);
+ * // 'Hello'
+ * ```
+ *
+ * @remarks
+ * If all you need is padding zeroes before a value, consider using {@link padLeftCodec} instead.
+ *
+ * Separate {@link getHiddenPrefixEncoder} and {@link getHiddenPrefixDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getHiddenPrefixEncoder(getUtf8Encoder(), [
+ *   getConstantEncoder(new Uint8Array([1, 2, 3])),
+ *   getConstantEncoder(new Uint8Array([4, 5, 6])),
+ * ]).encode('Hello');
+ *
+ * const value = getHiddenPrefixDecoder(getUtf8Decoder(), [
+ *   getConstantDecoder(new Uint8Array([1, 2, 3])),
+ *   getConstantDecoder(new Uint8Array([4, 5, 6])),
+ * ]).decode(bytes);
+ * ```
+ *
+ * @see {@link getHiddenPrefixEncoder}
+ * @see {@link getHiddenPrefixDecoder}
+ */
+export function getHiddenPrefixCodec<TFrom, TTo extends TFrom>(
+    codec: FixedSizeCodec<TFrom, TTo>,
+    prefixedCodecs: readonly FixedSizeCodec<void>[],
+): FixedSizeCodec<TFrom, TTo>;
+export function getHiddenPrefixCodec<TFrom, TTo extends TFrom>(
+    codec: Codec<TFrom, TTo>,
+    prefixedCodecs: readonly Codec<void>[],
+): VariableSizeCodec<TFrom, TTo>;
+export function getHiddenPrefixCodec<TFrom, TTo extends TFrom>(
+    codec: Codec<TFrom, TTo>,
+    prefixedCodecs: readonly Codec<void>[],
+): Codec<TFrom, TTo> {
+    return combineCodec(getHiddenPrefixEncoder(codec, prefixedCodecs), getHiddenPrefixDecoder(codec, prefixedCodecs));
+}

package/src/hidden-suffix.ts

@@ -0,0 +1,180 @@
+import {
+    Codec,
+    combineCodec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    transformDecoder,
+    transformEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+
+import { getTupleDecoder, getTupleEncoder } from './tuple';
+
+/**
+ * Returns an encoder that appends hidden data after the encoded value.
+ *
+ * This encoder applies a list of void encoders after encoding the main value.
+ * The suffixed data is encoded after the main value without being exposed to the user.
+ *
+ * For more details, see {@link getHiddenSuffixCodec}.
+ *
+ * @typeParam TFrom - The type of the main value being encoded.
+ *
+ * @param encoder - The encoder for the main value.
+ * @param suffixedEncoders - A list of void encoders that produce the hidden suffix.
+ * @returns A `FixedSizeEncoder` or `VariableSizeEncoder` that encodes the value with a hidden suffix.
+ *
+ * @example
+ * Suffixing a value with constants.
+ * ```ts
+ * const encoder = getHiddenSuffixEncoder(getUtf8Encoder(), [
+ *   getConstantCodec(new Uint8Array([1, 2, 3])),
+ *   getConstantCodec(new Uint8Array([4, 5, 6])),
+ * ]);
+ *
+ * encoder.encode('Hello');
+ * // 0x48656c6c6f010203040506
+ * //   |         |     └-- Our second hidden suffix.
+ * //   |         └-- Our first hidden suffix.
+ * //   └-- Our encoded value ("Hello").
+ * ```
+ *
+ * @see {@link getHiddenSuffixCodec}
+ */
+export function getHiddenSuffixEncoder<TFrom>(
+    encoder: FixedSizeEncoder<TFrom>,
+    suffixedEncoders: readonly FixedSizeEncoder<void>[],
+): FixedSizeEncoder<TFrom>;
+export function getHiddenSuffixEncoder<TFrom>(
+    encoder: Encoder<TFrom>,
+    suffixedEncoders: readonly Encoder<void>[],
+): VariableSizeEncoder<TFrom>;
+export function getHiddenSuffixEncoder<TFrom>(
+    encoder: Encoder<TFrom>,
+    suffixedEncoders: readonly Encoder<void>[],
+): Encoder<TFrom> {
+    return transformEncoder(
+        getTupleEncoder([encoder, ...suffixedEncoders]) as Encoder<readonly [TFrom, ...void[]]>,
+        (value: TFrom) => [value, ...suffixedEncoders.map(() => undefined)] as const,
+    );
+}
+
+/**
+ * Returns a decoder that skips hidden suffixed data after decoding the main value.
+ *
+ * This decoder applies a list of void decoders after decoding the main value.
+ * The suffixed data is skipped during decoding without being exposed to the user.
+ *
+ * For more details, see {@link getHiddenSuffixCodec}.
+ *
+ * @typeParam TTo - The type of the main value being decoded.
+ *
+ * @param decoder - The decoder for the main value.
+ * @param suffixedDecoders - A list of void decoders that produce the hidden suffix.
+ * @returns A `FixedSizeDecoder` or `VariableSizeDecoder` that decodes values while ignoring the hidden suffix.
+ *
+ * @example
+ * Decoding a value with suffixed constants.
+ * ```ts
+ * const decoder = getHiddenSuffixDecoder(getUtf8Decoder(), [
+ *   getConstantCodec(new Uint8Array([1, 2, 3])),
+ *   getConstantCodec(new Uint8Array([4, 5, 6])),
+ * ]);
+ *
+ * decoder.decode(new Uint8Array([0x48, 0x65, 0x6C, 0x6C, 0x6F, 1, 2, 3, 4, 5, 6]));
+ * // 'Hello'
+ * ```
+ *
+ * @see {@link getHiddenSuffixCodec}
+ */
+export function getHiddenSuffixDecoder<TTo>(
+    decoder: FixedSizeDecoder<TTo>,
+    suffixedDecoders: readonly FixedSizeDecoder<void>[],
+): FixedSizeDecoder<TTo>;
+export function getHiddenSuffixDecoder<TTo>(
+    decoder: Decoder<TTo>,
+    suffixedDecoders: readonly Decoder<void>[],
+): VariableSizeDecoder<TTo>;
+export function getHiddenSuffixDecoder<TTo>(
+    decoder: Decoder<TTo>,
+    suffixedDecoders: readonly Decoder<void>[],
+): Decoder<TTo> {
+    return transformDecoder(
+        getTupleDecoder([decoder, ...suffixedDecoders]) as Decoder<readonly [TTo, ...void[]]>,
+        tuple => tuple[0],
+    );
+}
+
+/**
+ * Returns a codec that encodes and decodes values with a hidden suffix.
+ *
+ * - **Encoding:** Appends hidden data after encoding the main value.
+ * - **Decoding:** Skips the hidden suffix after decoding the main value.
+ *
+ * This is useful for any implicit metadata that should be present in
+ * binary formats but omitted from the API.
+ *
+ * @typeParam TFrom - The type of the main value being encoded.
+ * @typeParam TTo - The type of the main value being decoded.
+ *
+ * @param codec - The codec for the main value.
+ * @param suffixedCodecs - A list of void codecs that produce the hidden suffix.
+ * @returns A `FixedSizeCodec` or `VariableSizeCodec` for encoding and decoding values with a hidden suffix.
+ *
+ * @example
+ * Encoding and decoding a value with suffixed constants.
+ * ```ts
+ * const codec = getHiddenSuffixCodec(getUtf8Codec(), [
+ *   getConstantCodec(new Uint8Array([1, 2, 3])),
+ *   getConstantCodec(new Uint8Array([4, 5, 6])),
+ * ]);
+ *
+ * const bytes = codec.encode('Hello');
+ * // 0x48656c6c6f010203040506
+ * //   |         |     └-- Our second hidden suffix.
+ * //   |         └-- Our first hidden suffix.
+ * //   └-- Our encoded value ("Hello").
+ *
+ * codec.decode(bytes);
+ * // 'Hello'
+ * ```
+ *
+ * @remarks
+ * If all you need is padding zeroes after a value, consider using {@link padRightCodec} instead.
+ *
+ * Separate {@link getHiddenSuffixEncoder} and {@link getHiddenSuffixDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getHiddenSuffixEncoder(getUtf8Encoder(), [
+ *   getConstantEncoder(new Uint8Array([1, 2, 3])),
+ *   getConstantEncoder(new Uint8Array([4, 5, 6])),
+ * ]).encode('Hello');
+ *
+ * const value = getHiddenSuffixDecoder(getUtf8Decoder(), [
+ *   getConstantDecoder(new Uint8Array([1, 2, 3])),
+ *   getConstantDecoder(new Uint8Array([4, 5, 6])),
+ * ]).decode(bytes);
+ * ```
+ *
+ * @see {@link getHiddenSuffixEncoder}
+ * @see {@link getHiddenSuffixDecoder}
+ */
+export function getHiddenSuffixCodec<TFrom, TTo extends TFrom>(
+    codec: FixedSizeCodec<TFrom, TTo>,
+    suffixedCodecs: readonly FixedSizeCodec<void>[],
+): FixedSizeCodec<TFrom, TTo>;
+export function getHiddenSuffixCodec<TFrom, TTo extends TFrom>(
+    codec: Codec<TFrom, TTo>,
+    suffixedCodecs: readonly Codec<void>[],
+): VariableSizeCodec<TFrom, TTo>;
+export function getHiddenSuffixCodec<TFrom, TTo extends TFrom>(
+    codec: Codec<TFrom, TTo>,
+    suffixedCodecs: readonly Codec<void>[],
+): Codec<TFrom, TTo> {
+    return combineCodec(getHiddenSuffixEncoder(codec, suffixedCodecs), getHiddenSuffixDecoder(codec, suffixedCodecs));
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * This package contains codecs for various data structures such as arrays, maps, structs, tuples, enums, etc.
+ * It can be used standalone, but it is also exported as part of Kit
+ * [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ *
+ * This package is also part of the [`@solana/codecs` package](https://github.com/anza-xyz/kit/tree/main/packages/codecs)
+ * which acts as an entry point for all codec packages as well as for their documentation.
+ *
+ * @packageDocumentation
+ */
+export * from './array';
+export * from './assertions';
+export * from './bit-array';
+export * from './boolean';
+export * from './bytes';
+export * from './constant';
+export * from './discriminated-union';
+export * from './enum';
+export * from './hidden-prefix';
+export * from './hidden-suffix';
+export * from './literal-union';
+export * from './map';
+export * from './nullable';
+export * from './pattern-match';
+export * from './predicate';
+export * from './set';
+export * from './struct';
+export * from './tuple';
+export * from './union';
+export * from './unit';