@solana/codecs-core 6.3.1 → 6.3.2-canary-20260313112147

package/src/combine-codec.ts

@@ -0,0 +1,133 @@
+import {
+    SOLANA_ERROR__CODECS__ENCODER_DECODER_FIXED_SIZE_MISMATCH,
+    SOLANA_ERROR__CODECS__ENCODER_DECODER_MAX_SIZE_MISMATCH,
+    SOLANA_ERROR__CODECS__ENCODER_DECODER_SIZE_COMPATIBILITY_MISMATCH,
+    SolanaError,
+} from '@solana/errors';
+
+import {
+    Codec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    isFixedSize,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from './codec';
+
+/**
+ * Combines an `Encoder` and a `Decoder` into a `Codec`.
+ *
+ * That is, given a `Encoder<TFrom>` and a `Decoder<TTo>`, this function returns a `Codec<TFrom, TTo>`.
+ *
+ * This allows for modular composition by keeping encoding and decoding logic separate
+ * while still offering a convenient way to bundle them into a single `Codec`.
+ * This is particularly useful for library maintainers who want to expose `Encoders`,
+ * `Decoders`, and `Codecs` separately, enabling tree-shaking of unused logic.
+ *
+ * The provided `Encoder` and `Decoder` must be compatible in terms of:
+ * - **Fixed Size:** If both are fixed-size, they must have the same `fixedSize` value.
+ * - **Variable Size:** If either has a `maxSize` attribute, it must match the other.
+ *
+ * If these conditions are not met, a {@link SolanaError} will be thrown.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ * @typeParam TTo - The type of the decoded value.
+ * @typeParam TSize - The fixed size of the encoded value in bytes (for fixed-size codecs).
+ *
+ * @param encoder - The `Encoder` to combine.
+ * @param decoder - The `Decoder` to combine.
+ * @returns A `Codec` that provides both `encode` and `decode` methods.
+ *
+ * @throws {SolanaError}
+ * - `SOLANA_ERROR__CODECS__ENCODER_DECODER_SIZE_COMPATIBILITY_MISMATCH`
+ *   Thrown if the encoder and decoder have mismatched size types (fixed vs. variable).
+ * - `SOLANA_ERROR__CODECS__ENCODER_DECODER_FIXED_SIZE_MISMATCH`
+ *   Thrown if both are fixed-size but have different `fixedSize` values.
+ * - `SOLANA_ERROR__CODECS__ENCODER_DECODER_MAX_SIZE_MISMATCH`
+ *   Thrown if the `maxSize` attributes do not match.
+ *
+ * @example
+ * Creating a fixed-size `Codec` from an encoder and a decoder.
+ * ```ts
+ * const encoder = getU32Encoder();
+ * const decoder = getU32Decoder();
+ * const codec = combineCodec(encoder, decoder);
+ *
+ * const bytes = codec.encode(42); // 0x2a000000
+ * const value = codec.decode(bytes); // 42
+ * ```
+ *
+ * @example
+ * Creating a variable-size `Codec` from an encoder and a decoder.
+ * ```ts
+ * const encoder = addEncoderSizePrefix(getUtf8Encoder(), getU32Encoder());
+ * const decoder = addDecoderSizePrefix(getUtf8Decoder(), getU32Decoder());
+ * const codec = combineCodec(encoder, decoder);
+ *
+ * const bytes = codec.encode("hello"); // 0x0500000068656c6c6f
+ * const value = codec.decode(bytes); // "hello"
+ * ```
+ *
+ * @remarks
+ * The recommended pattern for defining codecs in libraries is to expose separate functions for the encoder, decoder, and codec.
+ * This allows users to import only what they need, improving tree-shaking efficiency.
+ *
+ * ```ts
+ * type MyType = \/* ... *\/;
+ * const getMyTypeEncoder = (): Encoder<MyType> => { \/* ... *\/ };
+ * const getMyTypeDecoder = (): Decoder<MyType> => { \/* ... *\/ };
+ * const getMyTypeCodec = (): Codec<MyType> =>
+ *     combineCodec(getMyTypeEncoder(), getMyTypeDecoder());
+ * ```
+ *
+ * @see {@link Codec}
+ * @see {@link Encoder}
+ * @see {@link Decoder}
+ */
+export function combineCodec<TFrom, TTo extends TFrom, TSize extends number>(
+    encoder: FixedSizeEncoder<TFrom, TSize>,
+    decoder: FixedSizeDecoder<TTo, TSize>,
+): FixedSizeCodec<TFrom, TTo, TSize>;
+export function combineCodec<TFrom, TTo extends TFrom>(
+    encoder: VariableSizeEncoder<TFrom>,
+    decoder: VariableSizeDecoder<TTo>,
+): VariableSizeCodec<TFrom, TTo>;
+export function combineCodec<TFrom, TTo extends TFrom>(
+    encoder: Encoder<TFrom>,
+    decoder: Decoder<TTo>,
+): Codec<TFrom, TTo>;
+export function combineCodec<TFrom, TTo extends TFrom>(
+    encoder: Encoder<TFrom>,
+    decoder: Decoder<TTo>,
+): Codec<TFrom, TTo> {
+    if (isFixedSize(encoder) !== isFixedSize(decoder)) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__ENCODER_DECODER_SIZE_COMPATIBILITY_MISMATCH);
+    }
+
+    if (isFixedSize(encoder) && isFixedSize(decoder) && encoder.fixedSize !== decoder.fixedSize) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__ENCODER_DECODER_FIXED_SIZE_MISMATCH, {
+            decoderFixedSize: decoder.fixedSize,
+            encoderFixedSize: encoder.fixedSize,
+        });
+    }
+
+    if (!isFixedSize(encoder) && !isFixedSize(decoder) && encoder.maxSize !== decoder.maxSize) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__ENCODER_DECODER_MAX_SIZE_MISMATCH, {
+            decoderMaxSize: decoder.maxSize,
+            encoderMaxSize: encoder.maxSize,
+        });
+    }
+
+    return {
+        ...decoder,
+        ...encoder,
+        decode: decoder.decode,
+        encode: encoder.encode,
+        read: decoder.read,
+        write: encoder.write,
+    };
+}

package/src/decoder-entire-byte-array.ts

@@ -0,0 +1,45 @@
+import { SOLANA_ERROR__CODECS__EXPECTED_DECODER_TO_CONSUME_ENTIRE_BYTE_ARRAY, SolanaError } from '@solana/errors';
+
+import { createDecoder, Decoder } from './codec';
+
+/**
+ * Create a {@link Decoder} that asserts that the bytes provided to `decode` or `read` are fully consumed by the inner decoder
+ * @param decoder A decoder to wrap
+ * @returns A new decoder that will throw if provided with a byte array that it does not fully consume
+ *
+ * @typeParam T - The type of the decoder
+ *
+ * @remarks
+ * Note that this compares the offset after encoding to the length of the input byte array
+ *
+ * The `offset` parameter to `decode` and `read` is still considered, and will affect the new offset that is compared to the byte array length
+ *
+ * The error that is thrown by the returned decoder is a {@link SolanaError} with the code `SOLANA_ERROR__CODECS__EXPECTED_DECODER_TO_CONSUME_ENTIRE_BYTE_ARRAY`
+ *
+ * @example
+ * Create a decoder that decodes a `u32` (4 bytes) and ensures the entire byte array is consumed
+ * ```ts
+ * const decoder = createDecoderThatUsesExactByteArray(getU32Decoder());
+ * decoder.decode(new Uint8Array([0, 0, 0, 0])); // 0
+ * decoder.decode(new Uint8Array([0, 0, 0, 0, 0])); // throws
+ *
+ * // with an offset
+ * decoder.decode(new Uint8Array([0, 0, 0, 0, 0]), 1); // 0
+ * decoder.decode(new Uint8Array([0, 0, 0, 0, 0, 0]), 1); // throws
+ * ```
+ */
+export function createDecoderThatConsumesEntireByteArray<T>(decoder: Decoder<T>): Decoder<T> {
+    return createDecoder({
+        ...decoder,
+        read(bytes, offset) {
+            const [value, newOffset] = decoder.read(bytes, offset);
+            if (bytes.length > newOffset) {
+                throw new SolanaError(SOLANA_ERROR__CODECS__EXPECTED_DECODER_TO_CONSUME_ENTIRE_BYTE_ARRAY, {
+                    expectedLength: newOffset,
+                    numExcessBytes: bytes.length - newOffset,
+                });
+            }
+            return [value, newOffset];
+        },
+    });
+}

package/src/fix-codec-size.ts

@@ -0,0 +1,170 @@
+import { assertByteArrayHasEnoughBytesForCodec } from './assertions';
+import { fixBytes } from './bytes';
+import {
+    Codec,
+    createDecoder,
+    createEncoder,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    isFixedSize,
+    Offset,
+} from './codec';
+import { combineCodec } from './combine-codec';
+
+/**
+ * Creates a fixed-size encoder from a given encoder.
+ *
+ * The resulting encoder ensures that encoded values always have the specified number of bytes.
+ * If the original encoded value is larger than `fixedBytes`, it is truncated.
+ * If it is smaller, it is padded with trailing zeroes.
+ *
+ * For more details, see {@link fixCodecSize}.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ * @typeParam TSize - The fixed size of the encoded value in bytes.
+ *
+ * @param encoder - The encoder to wrap into a fixed-size encoder.
+ * @param fixedBytes - The fixed number of bytes to write.
+ * @returns A `FixedSizeEncoder` that ensures a consistent output size.
+ *
+ * @example
+ * ```ts
+ * const encoder = fixEncoderSize(getUtf8Encoder(), 4);
+ * encoder.encode("Hello"); // 0x48656c6c (truncated)
+ * encoder.encode("Hi");    // 0x48690000 (padded)
+ * encoder.encode("Hiya");  // 0x48697961 (same length)
+ * ```
+ *
+ * @remarks
+ * If you need a full codec with both encoding and decoding, use {@link fixCodecSize}.
+ *
+ * @see {@link fixCodecSize}
+ * @see {@link fixDecoderSize}
+ */
+export function fixEncoderSize<TFrom, TSize extends number>(
+    encoder: Encoder<TFrom>,
+    fixedBytes: TSize,
+): FixedSizeEncoder<TFrom, TSize> {
+    return createEncoder({
+        fixedSize: fixedBytes,
+        write: (value: TFrom, bytes: Uint8Array, offset: Offset) => {
+            // Here we exceptionally use the `encode` function instead of the `write`
+            // function as using the nested `write` function on a fixed-sized byte
+            // array may result in a out-of-bounds error on the nested encoder.
+            const variableByteArray = encoder.encode(value);
+            const fixedByteArray =
+                variableByteArray.length > fixedBytes ? variableByteArray.slice(0, fixedBytes) : variableByteArray;
+            bytes.set(fixedByteArray, offset);
+            return offset + fixedBytes;
+        },
+    });
+}
+
+/**
+ * Creates a fixed-size decoder from a given decoder.
+ *
+ * The resulting decoder always reads exactly `fixedBytes` bytes from the input.
+ * If the nested decoder is also fixed-size, the bytes are truncated or padded as needed.
+ *
+ * For more details, see {@link fixCodecSize}.
+ *
+ * @typeParam TTo - The type of the decoded value.
+ * @typeParam TSize - The fixed size of the encoded value in bytes.
+ *
+ * @param decoder - The decoder to wrap into a fixed-size decoder.
+ * @param fixedBytes - The fixed number of bytes to read.
+ * @returns A `FixedSizeDecoder` that ensures a consistent input size.
+ *
+ * @example
+ * ```ts
+ * const decoder = fixDecoderSize(getUtf8Decoder(), 4);
+ * decoder.decode(new Uint8Array([72, 101, 108, 108, 111])); // "Hell" (truncated)
+ * decoder.decode(new Uint8Array([72, 105, 0, 0]));          // "Hi" (zeroes ignored)
+ * decoder.decode(new Uint8Array([72, 105, 121, 97]));       // "Hiya" (same length)
+ * ```
+ *
+ * @remarks
+ * If you need a full codec with both encoding and decoding, use {@link fixCodecSize}.
+ *
+ * @see {@link fixCodecSize}
+ * @see {@link fixEncoderSize}
+ */
+export function fixDecoderSize<TTo, TSize extends number>(
+    decoder: Decoder<TTo>,
+    fixedBytes: TSize,
+): FixedSizeDecoder<TTo, TSize> {
+    return createDecoder({
+        fixedSize: fixedBytes,
+        read: (bytes, offset) => {
+            assertByteArrayHasEnoughBytesForCodec('fixCodecSize', fixedBytes, bytes, offset);
+            // Slice the byte array to the fixed size if necessary.
+            if (offset > 0 || bytes.length > fixedBytes) {
+                bytes = bytes.slice(offset, offset + fixedBytes);
+            }
+            // If the nested decoder is fixed-size, pad and truncate the byte array accordingly.
+            if (isFixedSize(decoder)) {
+                bytes = fixBytes(bytes, decoder.fixedSize);
+            }
+            // Decode the value using the nested decoder.
+            const [value] = decoder.read(bytes, 0);
+            return [value, offset + fixedBytes];
+        },
+    });
+}
+
+/**
+ * Creates a fixed-size codec from a given codec.
+ *
+ * The resulting codec ensures that both encoding and decoding operate on a fixed number of bytes.
+ * When encoding:
+ * - If the encoded value is larger than `fixedBytes`, it is truncated.
+ * - If it is smaller, it is padded with trailing zeroes.
+ * - If it is exactly `fixedBytes`, it remains unchanged.
+ *
+ * When decoding:
+ * - Exactly `fixedBytes` bytes are read from the input.
+ * - If the nested decoder has a smaller fixed size, bytes are truncated or padded as necessary.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ * @typeParam TTo - The type of the decoded value.
+ * @typeParam TSize - The fixed size of the encoded value in bytes.
+ *
+ * @param codec - The codec to wrap into a fixed-size codec.
+ * @param fixedBytes - The fixed number of bytes to read/write.
+ * @returns A `FixedSizeCodec` that ensures both encoding and decoding conform to a fixed size.
+ *
+ * @example
+ * ```ts
+ * const codec = fixCodecSize(getUtf8Codec(), 4);
+ *
+ * const bytes1 = codec.encode("Hello"); // 0x48656c6c (truncated)
+ * const value1 = codec.decode(bytes1);  // "Hell"
+ *
+ * const bytes2 = codec.encode("Hi");    // 0x48690000 (padded)
+ * const value2 = codec.decode(bytes2);  // "Hi"
+ *
+ * const bytes3 = codec.encode("Hiya");  // 0x48697961 (same length)
+ * const value3 = codec.decode(bytes3);  // "Hiya"
+ * ```
+ *
+ * @remarks
+ * If you only need to enforce a fixed size for encoding, use {@link fixEncoderSize}.
+ * If you only need to enforce a fixed size for decoding, use {@link fixDecoderSize}.
+ *
+ * ```ts
+ * const bytes = fixEncoderSize(getUtf8Encoder(), 4).encode("Hiya");
+ * const value = fixDecoderSize(getUtf8Decoder(), 4).decode(bytes);
+ * ```
+ *
+ * @see {@link fixEncoderSize}
+ * @see {@link fixDecoderSize}
+ */
+export function fixCodecSize<TFrom, TTo extends TFrom, TSize extends number>(
+    codec: Codec<TFrom, TTo>,
+    fixedBytes: TSize,
+): FixedSizeCodec<TFrom, TTo, TSize> {
+    return combineCodec(fixEncoderSize(codec, fixedBytes), fixDecoderSize(codec, fixedBytes));
+}