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

package/src/literal-union.ts

@@ -0,0 +1,249 @@
+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__INVALID_LITERAL_UNION_VARIANT,
+    SOLANA_ERROR__CODECS__LITERAL_UNION_DISCRIMINATOR_OUT_OF_RANGE,
+    SolanaError,
+} from '@solana/errors';
+
+/**
+ * Defines the configuration options for literal union codecs.
+ *
+ * A literal union codec encodes values from a predefined set of literals.
+ * The `size` option determines the numerical encoding used for the discriminant.
+ * By default, literals are stored as a `u8` (1 byte).
+ *
+ * @typeParam TDiscriminator - A number codec, encoder, or decoder used for the discriminant.
+ */
+export type LiteralUnionCodecConfig<TDiscriminator = NumberCodec | NumberDecoder | NumberEncoder> = {
+    /**
+     * The codec used to encode/decode the discriminator.
+     * @defaultValue `u8` discriminator.
+     */
+    size?: TDiscriminator;
+};
+
+type Variant = bigint | boolean | number | string | null | undefined;
+type GetTypeFromVariants<TVariants extends readonly Variant[]> = TVariants[number];
+
+/**
+ * Returns an encoder for literal unions.
+ *
+ * This encoder serializes a value from a predefined set of literals
+ * as a numerical index representing its position in the `variants` array.
+ *
+ * For more details, see {@link getLiteralUnionCodec}.
+ *
+ * @typeParam TVariants - A tuple of allowed literal values.
+ *
+ * @param variants - The possible literal values for the union.
+ * @param config - Configuration options for encoding the literal union.
+ * @returns A `FixedSizeEncoder` or `VariableSizeEncoder` for encoding literal unions.
+ *
+ * @example
+ * Encoding a union of string literals.
+ * ```ts
+ * type Size = 'small' | 'medium' | 'large';
+ * const sizeEncoder = getLiteralUnionEncoder(['small', 'medium', 'large']);
+ *
+ * sizeEncoder.encode('small');  // 0x00
+ * sizeEncoder.encode('medium'); // 0x01
+ * sizeEncoder.encode('large');  // 0x02
+ * ```
+ *
+ * @see {@link getLiteralUnionCodec}
+ */
+export function getLiteralUnionEncoder<const TVariants extends readonly Variant[]>(
+    variants: TVariants,
+): FixedSizeEncoder<GetTypeFromVariants<TVariants>, 1>;
+export function getLiteralUnionEncoder<const TVariants extends readonly Variant[], TSize extends number>(
+    variants: TVariants,
+    config: LiteralUnionCodecConfig<NumberEncoder> & { size: FixedSizeNumberEncoder<TSize> },
+): FixedSizeEncoder<GetTypeFromVariants<TVariants>, TSize>;
+export function getLiteralUnionEncoder<const TVariants extends readonly Variant[]>(
+    variants: TVariants,
+    config?: LiteralUnionCodecConfig<NumberEncoder>,
+): VariableSizeEncoder<GetTypeFromVariants<TVariants>>;
+export function getLiteralUnionEncoder<const TVariants extends readonly Variant[]>(
+    variants: TVariants,
+    config: LiteralUnionCodecConfig<NumberEncoder> = {},
+): Encoder<GetTypeFromVariants<TVariants>> {
+    const discriminator = config.size ?? getU8Encoder();
+    return transformEncoder(discriminator, variant => {
+        const index = variants.indexOf(variant);
+        if (index < 0) {
+            throw new SolanaError(SOLANA_ERROR__CODECS__INVALID_LITERAL_UNION_VARIANT, {
+                value: variant,
+                variants,
+            });
+        }
+        return index;
+    });
+}
+
+/**
+ * Returns a decoder for literal unions.
+ *
+ * This decoder deserializes a numerical index into a corresponding
+ * value from a predefined set of literals.
+ *
+ * For more details, see {@link getLiteralUnionCodec}.
+ *
+ * @typeParam TVariants - A tuple of allowed literal values.
+ *
+ * @param variants - The possible literal values for the union.
+ * @param config - Configuration options for decoding the literal union.
+ * @returns A `FixedSizeDecoder` or `VariableSizeDecoder` for decoding literal unions.
+ *
+ * @example
+ * Decoding a union of string literals.
+ * ```ts
+ * type Size = 'small' | 'medium' | 'large';
+ * const sizeDecoder = getLiteralUnionDecoder(['small', 'medium', 'large']);
+ *
+ * sizeDecoder.decode(new Uint8Array([0x00])); // 'small'
+ * sizeDecoder.decode(new Uint8Array([0x01])); // 'medium'
+ * sizeDecoder.decode(new Uint8Array([0x02])); // 'large'
+ * ```
+ *
+ * @see {@link getLiteralUnionCodec}
+ */
+export function getLiteralUnionDecoder<const TVariants extends readonly Variant[]>(
+    variants: TVariants,
+): FixedSizeDecoder<GetTypeFromVariants<TVariants>, 1>;
+export function getLiteralUnionDecoder<const TVariants extends readonly Variant[], TSize extends number>(
+    variants: TVariants,
+    config: LiteralUnionCodecConfig<NumberDecoder> & { size: FixedSizeNumberDecoder<TSize> },
+): FixedSizeDecoder<GetTypeFromVariants<TVariants>, TSize>;
+export function getLiteralUnionDecoder<const TVariants extends readonly Variant[]>(
+    variants: TVariants,
+    config?: LiteralUnionCodecConfig<NumberDecoder>,
+): VariableSizeDecoder<GetTypeFromVariants<TVariants>>;
+export function getLiteralUnionDecoder<const TVariants extends readonly Variant[]>(
+    variants: TVariants,
+    config: LiteralUnionCodecConfig<NumberDecoder> = {},
+): Decoder<GetTypeFromVariants<TVariants>> {
+    const discriminator = config.size ?? getU8Decoder();
+    return transformDecoder(discriminator, (index: bigint | number) => {
+        if (index < 0 || index >= variants.length) {
+            throw new SolanaError(SOLANA_ERROR__CODECS__LITERAL_UNION_DISCRIMINATOR_OUT_OF_RANGE, {
+                discriminator: index,
+                maxRange: variants.length - 1,
+                minRange: 0,
+            });
+        }
+        return variants[Number(index)];
+    });
+}
+
+/**
+ * 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.
+ *
+ * @typeParam TVariants - A tuple of allowed literal values.
+ *
+ * @param variants - The possible literal values for the union.
+ * @param config - Configuration options for encoding and decoding the literal union.
+ * @returns A `FixedSizeCodec` or `VariableSizeCodec` for encoding and decoding literal unions.
+ *
+ * @example
+ * Encoding and decoding a union of string literals.
+ * ```ts
+ * 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'
+ * ```
+ *
+ * @example
+ * Encoding and decoding a union of number literals.
+ * ```ts
+ * 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
+ * ```
+ *
+ * @example
+ * Using a custom discriminator size with different variant types.
+ * ```ts
+ * 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 {@link getLiteralUnionEncoder} and {@link getLiteralUnionDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getLiteralUnionEncoder(['red', 'green', 'blue']).encode('green');
+ * const value = getLiteralUnionDecoder(['red', 'green', 'blue']).decode(bytes);
+ * ```
+ *
+ * @see {@link getLiteralUnionEncoder}
+ * @see {@link getLiteralUnionDecoder}
+ */
+export function getLiteralUnionCodec<const TVariants extends readonly Variant[]>(
+    variants: TVariants,
+): FixedSizeCodec<GetTypeFromVariants<TVariants>, GetTypeFromVariants<TVariants>, 1>;
+export function getLiteralUnionCodec<const TVariants extends readonly Variant[], TSize extends number>(
+    variants: TVariants,
+    config: LiteralUnionCodecConfig<NumberCodec> & { size: FixedSizeNumberCodec<TSize> },
+): FixedSizeCodec<GetTypeFromVariants<TVariants>, GetTypeFromVariants<TVariants>, TSize>;
+export function getLiteralUnionCodec<const TVariants extends readonly Variant[]>(
+    variants: TVariants,
+    config?: LiteralUnionCodecConfig<NumberCodec>,
+): VariableSizeCodec<GetTypeFromVariants<TVariants>>;
+export function getLiteralUnionCodec<const TVariants extends readonly Variant[]>(
+    variants: TVariants,
+    config: LiteralUnionCodecConfig<NumberCodec> = {},
+): Codec<GetTypeFromVariants<TVariants>> {
+    return combineCodec(getLiteralUnionEncoder(variants, config), getLiteralUnionDecoder(variants, config));
+}

package/src/map.ts

@@ -0,0 +1,285 @@
+import {
+    Codec,
+    combineCodec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    transformDecoder,
+    transformEncoder,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+import { NumberCodec, NumberDecoder, NumberEncoder } from '@solana/codecs-numbers';
+
+import { ArrayLikeCodecSize, getArrayDecoder, getArrayEncoder } from './array';
+import { getTupleDecoder, getTupleEncoder } from './tuple';
+
+/**
+ * Defines the configuration options for map codecs.
+ *
+ * The `size` option determines how the number of entries in the map is stored.
+ * It can be:
+ * - A {@link NumberCodec} to prefix the map with its size.
+ * - A fixed number of entries.
+ * - `'remainder'`, which infers the number of entries based on the remaining bytes.
+ *   This option is only available for fixed-size keys and values.
+ *
+ * @typeParam TPrefix - A number codec, encoder, or decoder used for the size prefix.
+ */
+export type MapCodecConfig<TPrefix extends NumberCodec | NumberDecoder | NumberEncoder> = {
+    /**
+     * The size of the map.
+     * @defaultValue u32 prefix.
+     */
+    size?: ArrayLikeCodecSize<TPrefix>;
+};
+
+/**
+ * Returns an encoder for maps.
+ *
+ * This encoder serializes maps where the keys and values are encoded
+ * using the provided key and value encoders. The number of entries
+ * is determined by the `size` configuration.
+ *
+ * For more details, see {@link getMapCodec}.
+ *
+ * @typeParam TFromKey - The type of the keys before encoding.
+ * @typeParam TFromValue - The type of the values before encoding.
+ *
+ * @param key - The encoder for the map's keys.
+ * @param value - The encoder for the map's values.
+ * @param config - Configuration options for encoding the map.
+ * @returns A `FixedSizeEncoder` or `VariableSizeEncoder` for encoding maps.
+ *
+ * @example
+ * Encoding a map with a `u32` size prefix.
+ * ```ts
+ * const encoder = getMapEncoder(fixCodecSize(getUtf8Encoder(), 5), getU8Encoder());
+ * const bytes = encoder.encode(new Map([['alice', 42], ['bob', 5]]));
+ * // 0x02000000616c6963652a626f62000005
+ * //   |       |         | |         └── Value (5)
+ * //   |       |         | └── Key ("bob", 5 bytes fixed, null-padded)
+ * //   |       |         └── Value (42)
+ * //   |       └── Key ("alice", 5 bytes fixed)
+ * //   └── 4-byte prefix (2 entries)
+ * ```
+ *
+ * @see {@link getMapCodec}
+ */
+export function getMapEncoder<TFromKey, TFromValue>(
+    key: Encoder<TFromKey>,
+    value: Encoder<TFromValue>,
+    config: MapCodecConfig<NumberEncoder> & { size: 0 },
+): FixedSizeEncoder<Map<TFromKey, TFromValue>, 0>;
+export function getMapEncoder<TFromKey, TFromValue>(
+    key: FixedSizeEncoder<TFromKey>,
+    value: FixedSizeEncoder<TFromValue>,
+    config: MapCodecConfig<NumberEncoder> & { size: number },
+): FixedSizeEncoder<Map<TFromKey, TFromValue>>;
+export function getMapEncoder<TFromKey, TFromValue>(
+    key: Encoder<TFromKey>,
+    value: Encoder<TFromValue>,
+    config?: MapCodecConfig<NumberEncoder>,
+): VariableSizeEncoder<Map<TFromKey, TFromValue>>;
+export function getMapEncoder<TFromKey, TFromValue>(
+    key: Encoder<TFromKey>,
+    value: Encoder<TFromValue>,
+    config: MapCodecConfig<NumberEncoder> = {},
+): Encoder<Map<TFromKey, TFromValue>> {
+    return transformEncoder(
+        getArrayEncoder(getTupleEncoder([key, value]), config as object),
+        (map: Map<TFromKey, TFromValue>): [TFromKey, TFromValue][] => [...map.entries()],
+    );
+}
+
+/**
+ * Returns a decoder for maps.
+ *
+ * This decoder deserializes maps where the keys and values are decoded
+ * using the provided key and value decoders. The number of entries
+ * is determined by the `size` configuration.
+ *
+ * For more details, see {@link getMapCodec}.
+ *
+ * @typeParam TToKey - The type of the keys after decoding.
+ * @typeParam TToValue - The type of the values after decoding.
+ *
+ * @param key - The decoder for the map's keys.
+ * @param value - The decoder for the map's values.
+ * @param config - Configuration options for decoding the map.
+ * @returns A `FixedSizeDecoder` or `VariableSizeDecoder` for decoding maps.
+ *
+ * @example
+ * Decoding a map with a `u32` size prefix.
+ * ```ts
+ * const decoder = getMapDecoder(fixCodecSize(getUtf8Decoder(), 5), getU8Decoder());
+ * const map = decoder.decode(new Uint8Array([
+ *   0x02,0x00,0x00,0x00,0x61,0x6c,0x69,0x63,0x65,0x2a,0x62,0x6f,0x62,0x00,0x00,0x05
+ * ]));
+ * // new Map([['alice', 42], ['bob', 5]])
+ * ```
+ *
+ * @see {@link getMapCodec}
+ */
+export function getMapDecoder<TToKey, TToValue>(
+    key: Decoder<TToKey>,
+    value: Decoder<TToValue>,
+    config: MapCodecConfig<NumberDecoder> & { size: 0 },
+): FixedSizeDecoder<Map<TToKey, TToValue>, 0>;
+export function getMapDecoder<TToKey, TToValue>(
+    key: FixedSizeDecoder<TToKey>,
+    value: FixedSizeDecoder<TToValue>,
+    config: MapCodecConfig<NumberDecoder> & { size: number },
+): FixedSizeDecoder<Map<TToKey, TToValue>>;
+export function getMapDecoder<TToKey, TToValue>(
+    key: Decoder<TToKey>,
+    value: Decoder<TToValue>,
+    config?: MapCodecConfig<NumberDecoder>,
+): VariableSizeDecoder<Map<TToKey, TToValue>>;
+export function getMapDecoder<TToKey, TToValue>(
+    key: Decoder<TToKey>,
+    value: Decoder<TToValue>,
+    config: MapCodecConfig<NumberDecoder> = {},
+): Decoder<Map<TToKey, TToValue>> {
+    return transformDecoder(
+        getArrayDecoder(getTupleDecoder([key, value]), config as object) as Decoder<[TToKey, TToValue][]>,
+        (entries: [TToKey, TToValue][]): Map<TToKey, TToValue> => new Map(entries),
+    );
+}
+
+/**
+ * Returns a codec for encoding and decoding maps.
+ *
+ * This codec serializes maps where the key/value pairs are encoded
+ * and decoded one after another using the provided key and value codecs.
+ * The number of entries is determined by the `size` configuration and
+ * defaults to a `u32` size prefix.
+ *
+ * @typeParam TFromKey - The type of the keys before encoding.
+ * @typeParam TFromValue - The type of the values before encoding.
+ * @typeParam TToKey - The type of the keys after decoding.
+ * @typeParam TToValue - The type of the values after decoding.
+ *
+ * @param key - The codec for the map's keys.
+ * @param value - The codec for the map's values.
+ * @param config - Configuration options for encoding and decoding the map.
+ * @returns A `FixedSizeCodec` or `VariableSizeCodec` for encoding and decoding maps.
+ *
+ * @example
+ * Encoding and decoding a map with a `u32` size prefix (default).
+ * ```ts
+ * const codec = getMapCodec(fixCodecSize(getUtf8Codec(), 5), getU8Codec());
+ * const bytes = codec.encode(new Map([['alice', 42], ['bob', 5]]));
+ * // 0x02000000616c6963652a626f62000005
+ * //   |       |         | |         └── Value (5)
+ * //   |       |         | └── Key ("bob", 5 bytes fixed, null-padded)
+ * //   |       |         └── Value (42)
+ * //   |       └── Key ("alice", 5 bytes fixed)
+ * //   └── 4-byte prefix (2 entries)
+ *
+ * const map = codec.decode(bytes);
+ * // new Map([['alice', 42], ['bob', 5]])
+ * ```
+ *
+ * @example
+ * Encoding and decoding a map with a `u16` size prefix.
+ * ```ts
+ * const codec = getMapCodec(fixCodecSize(getUtf8Codec(), 5), getU8Codec(), { size: getU16Codec() });
+ * const bytes = codec.encode(new Map([['alice', 42], ['bob', 5]]));
+ * // 0x0200616c6963652a626f62000005
+ * //   |   |         | |         └── Value (5)
+ * //   |   |         | └── Key ("bob", 5 bytes fixed, null-padded)
+ * //   |   |         └── Value (42)
+ * //   |   └── Key ("alice", 5 bytes fixed)
+ * //   └── 2-byte prefix (2 entries)
+ *
+ * const map = codec.decode(bytes);
+ * // new Map([['alice', 42], ['bob', 5]])
+ * ```
+ *
+ * @example
+ * Encoding and decoding a fixed-size map.
+ * ```ts
+ * const codec = getMapCodec(fixCodecSize(getUtf8Codec(), 5), getU8Codec(), { size: 2 });
+ * const bytes = codec.encode(new Map([['alice', 42], ['bob', 5]]));
+ * // 0x616c6963652a626f62000005
+ * //   |         | |         └── Value (5)
+ * //   |         | └── Key ("bob", 5 bytes fixed, null-padded)
+ * //   |         └── Value (42)
+ * //   └── Key ("alice", 5 bytes fixed)
+ *
+ * const map = codec.decode(bytes);
+ * // new Map([['alice', 42], ['bob', 5]])
+ * ```
+ *
+ * @example
+ * Encoding and decoding a map with remainder size.
+ * ```ts
+ * const codec = getMapCodec(fixCodecSize(getUtf8Codec(), 5), getU8Codec(), { size: 'remainder' });
+ * const bytes = codec.encode(new Map([['alice', 42], ['bob', 5]]));
+ * // 0x616c6963652a626f62000005
+ * //   |         | |         └── Value (5)
+ * //   |         | └── Key ("bob", 5 bytes fixed, null-padded)
+ * //   |         └── Value (42)
+ * //   └── Key ("alice", 5 bytes fixed)
+ * // No size prefix, the size is inferred from the remaining bytes.
+ *
+ * const map = codec.decode(bytes);
+ * // new Map([['alice', 42], ['bob', 5]])
+ * ```
+ *
+ * @remarks
+ * Separate {@link getMapEncoder} and {@link getMapDecoder} functions are available.
+ * ```ts
+ * const bytes = getMapEncoder(fixCodecSize(getUtf8Encoder(), 5), getU8Encoder()).encode(new Map([['alice', 42]]));
+ * const map = getMapDecoder(fixCodecSize(getUtf8Decoder(), 5), getU8Decoder()).decode(bytes);
+ * ```
+ *
+ * @see {@link getMapEncoder}
+ * @see {@link getMapDecoder}
+ */
+export function getMapCodec<
+    TFromKey,
+    TFromValue,
+    TToKey extends TFromKey = TFromKey,
+    TToValue extends TFromValue = TFromValue,
+>(
+    key: Codec<TFromKey, TToKey>,
+    value: Codec<TFromValue, TToValue>,
+    config: MapCodecConfig<NumberCodec> & { size: 0 },
+): FixedSizeCodec<Map<TFromKey, TFromValue>, Map<TToKey, TToValue>, 0>;
+export function getMapCodec<
+    TFromKey,
+    TFromValue,
+    TToKey extends TFromKey = TFromKey,
+    TToValue extends TFromValue = TFromValue,
+>(
+    key: FixedSizeCodec<TFromKey, TToKey>,
+    value: FixedSizeCodec<TFromValue, TToValue>,
+    config: MapCodecConfig<NumberCodec> & { size: number },
+): FixedSizeCodec<Map<TFromKey, TFromValue>, Map<TToKey, TToValue>>;
+export function getMapCodec<
+    TFromKey,
+    TFromValue,
+    TToKey extends TFromKey = TFromKey,
+    TToValue extends TFromValue = TFromValue,
+>(
+    key: Codec<TFromKey, TToKey>,
+    value: Codec<TFromValue, TToValue>,
+    config?: MapCodecConfig<NumberCodec>,
+): VariableSizeCodec<Map<TFromKey, TFromValue>, Map<TToKey, TToValue>>;
+export function getMapCodec<
+    TFromKey,
+    TFromValue,
+    TToKey extends TFromKey = TFromKey,
+    TToValue extends TFromValue = TFromValue,
+>(
+    key: Codec<TFromKey, TToKey>,
+    value: Codec<TFromValue, TToValue>,
+    config: MapCodecConfig<NumberCodec> = {},
+): Codec<Map<TFromKey, TFromValue>, Map<TToKey, TToValue>> {
+    return combineCodec(getMapEncoder(key, value, config as object), getMapDecoder(key, value, config as object));
+}