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

package/src/boolean.ts

@@ -0,0 +1,163 @@
+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';
+
+/**
+ * Defines the configuration options for boolean codecs.
+ *
+ * A boolean codec encodes `true` as `1` and `false` as `0`.
+ * The `size` option allows customizing the number codec used for storage.
+ *
+ * @typeParam TSize - A number codec, encoder, or decoder used for boolean representation.
+ *
+ * @see {@link getBooleanEncoder}
+ * @see {@link getBooleanDecoder}
+ * @see {@link getBooleanCodec}
+ */
+export type BooleanCodecConfig<TSize extends NumberCodec | NumberDecoder | NumberEncoder> = {
+    /**
+     * The number codec used to store boolean values.
+     *
+     * - By default, booleans are stored as a `u8` (`1` for `true`, `0` for `false`).
+     * - A custom number codec can be provided to change the storage size.
+     *
+     * @defaultValue `u8`
+     */
+    size?: TSize;
+};
+
+/**
+ * Returns an encoder for boolean values.
+ *
+ * This encoder converts `true` into `1` and `false` into `0`.
+ * The `size` option allows customizing the number codec used for storage.
+ *
+ * For more details, see {@link getBooleanCodec}.
+ *
+ * @param config - Configuration options for encoding booleans.
+ * @returns A `FixedSizeEncoder<boolean, N>` where `N` is the size of the number codec.
+ *
+ * @example
+ * Encoding booleans.
+ * ```ts
+ * const encoder = getBooleanEncoder();
+ *
+ * encoder.encode(false); // 0x00
+ * encoder.encode(true);  // 0x01
+ * ```
+ *
+ * @see {@link getBooleanCodec}
+ */
+export function getBooleanEncoder(): FixedSizeEncoder<boolean, 1>;
+export function getBooleanEncoder<TSize extends number>(
+    config: BooleanCodecConfig<NumberEncoder> & { size: FixedSizeNumberEncoder<TSize> },
+): FixedSizeEncoder<boolean, TSize>;
+export function getBooleanEncoder(config: BooleanCodecConfig<NumberEncoder>): VariableSizeEncoder<boolean>;
+export function getBooleanEncoder(config: BooleanCodecConfig<NumberEncoder> = {}): Encoder<boolean> {
+    return transformEncoder(config.size ?? getU8Encoder(), (value: boolean) => (value ? 1 : 0));
+}
+
+/**
+ * Returns a decoder for boolean values.
+ *
+ * This decoder reads a number and interprets `1` as `true` and `0` as `false`.
+ * The `size` option allows customizing the number codec used for storage.
+ *
+ * For more details, see {@link getBooleanCodec}.
+ *
+ * @param config - Configuration options for decoding booleans.
+ * @returns A `FixedSizeDecoder<boolean, N>` where `N` is the size of the number codec.
+ *
+ * @example
+ * Decoding booleans.
+ * ```ts
+ * const decoder = getBooleanDecoder();
+ *
+ * decoder.decode(new Uint8Array([0x00])); // false
+ * decoder.decode(new Uint8Array([0x01])); // true
+ * ```
+ *
+ * @see {@link getBooleanCodec}
+ */
+export function getBooleanDecoder(): FixedSizeDecoder<boolean, 1>;
+export function getBooleanDecoder<TSize extends number>(
+    config: BooleanCodecConfig<NumberDecoder> & { size: FixedSizeNumberDecoder<TSize> },
+): FixedSizeDecoder<boolean, TSize>;
+export function getBooleanDecoder(config: BooleanCodecConfig<NumberDecoder>): VariableSizeDecoder<boolean>;
+export function getBooleanDecoder(config: BooleanCodecConfig<NumberDecoder> = {}): Decoder<boolean> {
+    return transformDecoder(config.size ?? getU8Decoder(), (value: bigint | number): boolean => Number(value) === 1);
+}
+
+/**
+ * Returns a codec for encoding and decoding boolean values.
+ *
+ * By default, booleans are stored as a `u8` (`1` for `true`, `0` for `false`).
+ * The `size` option allows customizing the number codec used for storage.
+ *
+ * @param config - Configuration options for encoding and decoding booleans.
+ * @returns A `FixedSizeCodec<boolean, boolean, N>` where `N` is the size of the number codec.
+ *
+ * @example
+ * Encoding and decoding booleans using a `u8` (default).
+ * ```ts
+ * const codec = getBooleanCodec();
+ *
+ * codec.encode(false); // 0x00
+ * codec.encode(true);  // 0x01
+ *
+ * codec.decode(new Uint8Array([0x00])); // false
+ * codec.decode(new Uint8Array([0x01])); // true
+ * ```
+ *
+ * @example
+ * Encoding and decoding booleans using a custom number codec.
+ * ```ts
+ * const codec = getBooleanCodec({ size: getU16Codec() });
+ *
+ * codec.encode(false); // 0x0000
+ * codec.encode(true);  // 0x0100
+ *
+ * codec.decode(new Uint8Array([0x00, 0x00])); // false
+ * codec.decode(new Uint8Array([0x01, 0x00])); // true
+ * ```
+ *
+ * @remarks
+ * Separate {@link getBooleanEncoder} and {@link getBooleanDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getBooleanEncoder().encode(true);
+ * const value = getBooleanDecoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getBooleanEncoder}
+ * @see {@link getBooleanDecoder}
+ */
+export function getBooleanCodec(): FixedSizeCodec<boolean, boolean, 1>;
+export function getBooleanCodec<TSize extends number>(
+    config: BooleanCodecConfig<NumberCodec> & { size: FixedSizeNumberCodec<TSize> },
+): FixedSizeCodec<boolean, boolean, TSize>;
+export function getBooleanCodec(config: BooleanCodecConfig<NumberCodec>): VariableSizeCodec<boolean>;
+export function getBooleanCodec(config: BooleanCodecConfig<NumberCodec> = {}): Codec<boolean> {
+    return combineCodec(getBooleanEncoder(config), getBooleanDecoder(config));
+}

package/src/bytes.ts

@@ -0,0 +1,115 @@
+import {
+    combineCodec,
+    createDecoder,
+    createEncoder,
+    ReadonlyUint8Array,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+
+/**
+ * Returns an encoder for raw byte arrays.
+ *
+ * This encoder writes byte arrays exactly as provided without modification.
+ *
+ * The size of the encoded byte array is determined by the length of the input.
+ * - To enforce a fixed size, consider using {@link fixEncoderSize}.
+ * - To add a size prefix, use {@link addEncoderSizePrefix}.
+ * - To add a sentinel value, use {@link addEncoderSentinel}.
+ *
+ * For more details, see {@link getBytesCodec}.
+ *
+ * @returns A `VariableSizeEncoder<ReadonlyUint8Array | Uint8Array>`.
+ *
+ * @example
+ * Encoding a byte array as-is.
+ * ```ts
+ * const encoder = getBytesEncoder();
+ *
+ * encoder.encode(new Uint8Array([1, 2, 3])); // 0x010203
+ * encoder.encode(new Uint8Array([255, 0, 127])); // 0xff007f
+ * ```
+ *
+ * @see {@link getBytesCodec}
+ */
+export function getBytesEncoder(): VariableSizeEncoder<ReadonlyUint8Array | Uint8Array> {
+    return createEncoder({
+        getSizeFromValue: value => value.length,
+        write: (value, bytes, offset) => {
+            bytes.set(value, offset);
+            return offset + value.length;
+        },
+    });
+}
+
+/**
+ * Returns a decoder for raw byte arrays.
+ *
+ * This decoder reads byte arrays exactly as provided without modification.
+ *
+ * The decoded byte array extends from the provided offset to the end of the input.
+ * - To enforce a fixed size, consider using {@link fixDecoderSize}.
+ * - To add a size prefix, use {@link addDecoderSizePrefix}.
+ * - To add a sentinel value, use {@link addDecoderSentinel}.
+ *
+ * For more details, see {@link getBytesCodec}.
+ *
+ * @returns A `VariableSizeDecoder<ReadonlyUint8Array>`.
+ *
+ * @example
+ * Decoding a byte array as-is.
+ * ```ts
+ * const decoder = getBytesDecoder();
+ *
+ * decoder.decode(new Uint8Array([1, 2, 3])); // Uint8Array([1, 2, 3])
+ * decoder.decode(new Uint8Array([255, 0, 127])); // Uint8Array([255, 0, 127])
+ * ```
+ *
+ * @see {@link getBytesCodec}
+ */
+export function getBytesDecoder(): VariableSizeDecoder<ReadonlyUint8Array> {
+    return createDecoder({
+        read: (bytes, offset) => {
+            const slice = bytes.slice(offset);
+            return [slice, offset + slice.length];
+        },
+    });
+}
+
+/**
+ * Returns a codec for encoding and decoding raw byte arrays.
+ *
+ * This codec serializes and deserializes byte arrays without modification.
+ *
+ * The size of the encoded and decoded byte array is determined dynamically.
+ * This means, when reading, the codec will consume all remaining bytes in the input.
+ * - To enforce a fixed size, consider using {@link fixCodecSize}.
+ * - To add a size prefix, use {@link addCodecSizePrefix}.
+ * - To add a sentinel value, use {@link addCodecSentinel}.
+ *
+ * @returns A `VariableSizeCodec<ReadonlyUint8Array | Uint8Array, ReadonlyUint8Array>`.
+ *
+ * @example
+ * Encoding and decoding a byte array.
+ * ```ts
+ * const codec = getBytesCodec();
+ *
+ * codec.encode(new Uint8Array([1, 2, 3])); // 0x010203
+ * codec.decode(new Uint8Array([255, 0, 127])); // Uint8Array([255, 0, 127])
+ * ```
+ *
+ * @remarks
+ * Separate {@link getBytesEncoder} and {@link getBytesDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getBytesEncoder().encode(new Uint8Array([1, 2, 3]));
+ * const value = getBytesDecoder().decode(bytes);
+ * ```
+ *
+ * @see {@link getBytesEncoder}
+ * @see {@link getBytesDecoder}
+ */
+export function getBytesCodec(): VariableSizeCodec<ReadonlyUint8Array | Uint8Array, ReadonlyUint8Array> {
+    return combineCodec(getBytesEncoder(), getBytesDecoder());
+}

package/src/constant.ts

@@ -0,0 +1,135 @@
+import {
+    combineCodec,
+    containsBytes,
+    createDecoder,
+    createEncoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    ReadonlyUint8Array,
+} from '@solana/codecs-core';
+import { getBase16Decoder } from '@solana/codecs-strings';
+import { SOLANA_ERROR__CODECS__INVALID_CONSTANT, SolanaError } from '@solana/errors';
+
+/**
+ * Returns an encoder that always writes a predefined constant byte sequence.
+ *
+ * This encoder ensures that encoding always produces the specified byte array,
+ * ignoring any input values.
+ *
+ * For more details, see {@link getConstantCodec}.
+ *
+ * @typeParam TConstant - The fixed byte sequence that will be written during encoding.
+ *
+ * @param constant - The predefined byte array to encode.
+ * @returns A `FixedSizeEncoder<void, N>` where `N` is the length of the constant.
+ *
+ * @example
+ * Encoding a constant magic number.
+ * ```ts
+ * const encoder = getConstantEncoder(new Uint8Array([1, 2, 3, 4]));
+ *
+ * const bytes = encoder.encode();
+ * // 0x01020304
+ * //   └──────┘ The predefined 4-byte constant.
+ * ```
+ *
+ * @see {@link getConstantCodec}
+ */
+export function getConstantEncoder<TConstant extends ReadonlyUint8Array>(
+    constant: TConstant,
+): FixedSizeEncoder<void, TConstant['length']> {
+    return createEncoder({
+        fixedSize: constant.length,
+        write: (_, bytes, offset) => {
+            bytes.set(constant, offset);
+            return offset + constant.length;
+        },
+    });
+}
+
+/**
+ * Returns a decoder that verifies a predefined constant byte sequence.
+ *
+ * This decoder reads the next bytes and checks that they match the provided constant.
+ * If the bytes differ, it throws an error.
+ *
+ * For more details, see {@link getConstantCodec}.
+ *
+ * @typeParam TConstant - The fixed byte sequence expected during decoding.
+ *
+ * @param constant - The predefined byte array to verify.
+ * @returns A `FixedSizeDecoder<void, N>` where `N` is the length of the constant.
+ *
+ * @example
+ * Decoding a constant magic number.
+ * ```ts
+ * const decoder = getConstantDecoder(new Uint8Array([1, 2, 3]));
+ *
+ * decoder.decode(new Uint8Array([1, 2, 3])); // Passes
+ * decoder.decode(new Uint8Array([1, 2, 4])); // Throws an error
+ * ```
+ *
+ * @see {@link getConstantCodec}
+ */
+export function getConstantDecoder<TConstant extends ReadonlyUint8Array>(
+    constant: TConstant,
+): FixedSizeDecoder<void, TConstant['length']> {
+    return createDecoder({
+        fixedSize: constant.length,
+        read: (bytes, offset) => {
+            const base16 = getBase16Decoder();
+            if (!containsBytes(bytes, constant, offset)) {
+                throw new SolanaError(SOLANA_ERROR__CODECS__INVALID_CONSTANT, {
+                    constant,
+                    data: bytes,
+                    hexConstant: base16.decode(constant),
+                    hexData: base16.decode(bytes),
+                    offset,
+                });
+            }
+            return [undefined, offset + constant.length];
+        },
+    });
+}
+
+/**
+ * Returns a codec that encodes and decodes a predefined constant byte sequence.
+ *
+ * - **Encoding:** Always writes the specified byte array.
+ * - **Decoding:** Asserts that the next bytes match the constant, throwing an error if they do not.
+ *
+ * This is useful for encoding fixed byte patterns required in a binary format or to use in
+ * conjunction with other codecs such as {@link getHiddenPrefixCodec} or {@link getHiddenSuffixCodec}.
+ *
+ * @typeParam TConstant - The fixed byte sequence to encode and verify during decoding.
+ *
+ * @param constant - The predefined byte array to encode and assert during decoding.
+ * @returns A `FixedSizeCodec<void, void, N>` where `N` is the length of the constant.
+ *
+ * @example
+ * Encoding and decoding a constant magic number.
+ * ```ts
+ * const codec = getConstantCodec(new Uint8Array([1, 2, 3]));
+ *
+ * codec.encode(); // 0x010203
+ * codec.decode(new Uint8Array([1, 2, 3])); // Passes
+ * codec.decode(new Uint8Array([1, 2, 4])); // Throws an error
+ * ```
+ *
+ * @remarks
+ * Separate {@link getConstantEncoder} and {@link getConstantDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getConstantEncoder(new Uint8Array([1, 2, 3])).encode();
+ * getConstantDecoder(new Uint8Array([1, 2, 3])).decode(bytes);
+ * ```
+ *
+ * @see {@link getConstantEncoder}
+ * @see {@link getConstantDecoder}
+ */
+export function getConstantCodec<TConstant extends ReadonlyUint8Array>(
+    constant: TConstant,
+): FixedSizeCodec<void, void, TConstant['length']> {
+    return combineCodec(getConstantEncoder(constant), getConstantDecoder(constant));
+}