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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solana/codecs-data-structures",
-  "version": "6.3.1",
+  "version": "6.3.2-canary-20260313112147",
   "description": "Codecs for various data structures",
   "homepage": "https://www.solanakit.com/api#solanacodecs-data-structures",
   "exports": {
@@ -33,7 +33,8 @@
   "types": "./dist/types/index.d.ts",
   "type": "commonjs",
   "files": [
-    "./dist/"
+    "./dist/",
+    "./src/"
   ],
   "sideEffects": false,
   "keywords": [
@@ -55,9 +56,9 @@
     "maintained node versions"
   ],
   "dependencies": {
-    "@solana/errors": "6.3.1",
-    "@solana/codecs-core": "6.3.1",
-    "@solana/codecs-numbers": "6.3.1"
+    "@solana/codecs-core": "6.3.2-canary-20260313112147",
+    "@solana/codecs-numbers": "6.3.2-canary-20260313112147",
+    "@solana/errors": "6.3.2-canary-20260313112147"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"

package/src/array.ts

@@ -0,0 +1,300 @@
+import {
+    Codec,
+    combineCodec,
+    createDecoder,
+    createEncoder,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    getEncodedSize,
+    ReadonlyUint8Array,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+import { getU32Decoder, getU32Encoder, NumberCodec, NumberDecoder, NumberEncoder } from '@solana/codecs-numbers';
+
+import { assertValidNumberOfItemsForCodec } from './assertions';
+import { getFixedSize, getMaxSize } from './utils';
+
+/**
+ * Defines the possible size strategies for array-like codecs (`array`, `map`, and `set`).
+ *
+ * The size of the collection can be determined using one of the following approaches:
+ * - A {@link NumberCodec}, {@link NumberDecoder}, or {@link NumberEncoder} to store a size prefix.
+ * - A fixed `number` of items, enforcing an exact length.
+ * - The string `"remainder"`, which infers the number of items by consuming the rest of the available bytes.
+ *
+ * @typeParam TPrefix - A number codec, decoder, or encoder used for size prefixing.
+ */
+export type ArrayLikeCodecSize<TPrefix extends NumberCodec | NumberDecoder | NumberEncoder> =
+    | TPrefix
+    | number
+    | 'remainder';
+
+/**
+ * Defines the configuration options for array codecs.
+ *
+ * @typeParam TPrefix - A number codec, decoder, or encoder used for size prefixing.
+ */
+export type ArrayCodecConfig<TPrefix extends NumberCodec | NumberDecoder | NumberEncoder> = {
+    /**
+     * An optional description for the codec, that will be used in error messages.
+     */
+    description?: string;
+    /**
+     * Specifies how the size of the array is determined.
+     *
+     * - A {@link NumberCodec}, {@link NumberDecoder}, or {@link NumberEncoder} stores a size prefix before encoding the array.
+     * - A `number` enforces a fixed number of elements.
+     * - `"remainder"` uses all remaining bytes to infer the array length (only for fixed-size items).
+     *
+     * @defaultValue A `u32` size prefix.
+     */
+    size?: ArrayLikeCodecSize<TPrefix>;
+};
+
+/**
+ * Returns an encoder for arrays of values.
+ *
+ * This encoder serializes arrays by encoding each element using the provided item encoder.
+ * By default, a `u32` size prefix is included to indicate the number of items in the array.
+ * The `size` option can be used to modify this behaviour.
+ *
+ * For more details, see {@link getArrayCodec}.
+ *
+ * @typeParam TFrom - The type of the elements in the array.
+ *
+ * @param item - The encoder for each item in the array.
+ * @param config - Optional configuration for the size encoding strategy and description.
+ * @returns A `VariableSizeEncoder<TFrom[]>` for encoding arrays.
+ *
+ * @example
+ * Encoding an array of `u8` numbers.
+ * ```ts
+ * const encoder = getArrayEncoder(getU8Encoder());
+ * const bytes = encoder.encode([1, 2, 3]);
+ * // 0x03000000010203
+ * //   |       └-- 3 items of 1 byte each.
+ * //   └-- 4-byte prefix telling us to read 3 items.
+ * ```
+ *
+ * @see {@link getArrayCodec}
+ */
+export function getArrayEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config: ArrayCodecConfig<NumberEncoder> & { size: 0 },
+): FixedSizeEncoder<TFrom[], 0>;
+export function getArrayEncoder<TFrom>(
+    item: FixedSizeEncoder<TFrom>,
+    config: ArrayCodecConfig<NumberEncoder> & { size: number },
+): FixedSizeEncoder<TFrom[]>;
+export function getArrayEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config?: ArrayCodecConfig<NumberEncoder>,
+): VariableSizeEncoder<TFrom[]>;
+export function getArrayEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config: ArrayCodecConfig<NumberEncoder> = {},
+): Encoder<TFrom[]> {
+    const size = config.size ?? getU32Encoder();
+    const fixedSize = computeArrayLikeCodecSize(size, getFixedSize(item));
+    const maxSize = computeArrayLikeCodecSize(size, getMaxSize(item)) ?? undefined;
+
+    return createEncoder({
+        ...(fixedSize !== null
+            ? { fixedSize }
+            : {
+                  getSizeFromValue: (array: TFrom[]) => {
+                      const prefixSize = typeof size === 'object' ? getEncodedSize(array.length, size) : 0;
+                      return prefixSize + [...array].reduce((all, value) => all + getEncodedSize(value, item), 0);
+                  },
+                  maxSize,
+              }),
+        write: (array: TFrom[], bytes, offset) => {
+            if (typeof size === 'number') {
+                assertValidNumberOfItemsForCodec(config.description ?? 'array', size, array.length);
+            }
+            if (typeof size === 'object') {
+                offset = size.write(array.length, bytes, offset);
+            }
+            array.forEach(value => {
+                offset = item.write(value, bytes, offset);
+            });
+            return offset;
+        },
+    });
+}
+
+/**
+ * Returns a decoder for arrays of values.
+ *
+ * This decoder deserializes arrays by decoding each element using the provided item decoder.
+ * By default, a `u32` size prefix is expected to indicate the number of items in the array.
+ * The `size` option can be used to modify this behaviour.
+ *
+ * For more details, see {@link getArrayCodec}.
+ *
+ * @typeParam TTo - The type of the decoded elements in the array.
+ *
+ * @param item - The decoder for each item in the array.
+ * @param config - Optional configuration for the size decoding strategy.
+ * @returns A `VariableSizeDecoder<TTo[]>` for decoding arrays.
+ *
+ * @example
+ * Decoding an array of `u8` numbers.
+ * ```ts
+ * const decoder = getArrayDecoder(getU8Decoder());
+ * const array = decoder.decode(new Uint8Array([0x03, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03]));
+ * // [1, 2, 3]
+ * // 0x03000000010203
+ * //   |       └-- 3 items of 1 byte each.
+ * //   └-- 4-byte prefix telling us to read 3 items.
+ * ```
+ *
+ * @see {@link getArrayCodec}
+ */
+export function getArrayDecoder<TTo>(
+    item: Decoder<TTo>,
+    config: ArrayCodecConfig<NumberDecoder> & { size: 0 },
+): FixedSizeDecoder<TTo[], 0>;
+export function getArrayDecoder<TTo>(
+    item: FixedSizeDecoder<TTo>,
+    config: ArrayCodecConfig<NumberDecoder> & { size: number },
+): FixedSizeDecoder<TTo[]>;
+export function getArrayDecoder<TTo>(
+    item: Decoder<TTo>,
+    config?: ArrayCodecConfig<NumberDecoder>,
+): VariableSizeDecoder<TTo[]>;
+export function getArrayDecoder<TTo>(item: Decoder<TTo>, config: ArrayCodecConfig<NumberDecoder> = {}): Decoder<TTo[]> {
+    const size = config.size ?? getU32Decoder();
+    const itemSize = getFixedSize(item);
+    const fixedSize = computeArrayLikeCodecSize(size, itemSize);
+    const maxSize = computeArrayLikeCodecSize(size, getMaxSize(item)) ?? undefined;
+
+    return createDecoder({
+        ...(fixedSize !== null ? { fixedSize } : { maxSize }),
+        read: (bytes: ReadonlyUint8Array | Uint8Array, offset) => {
+            const array: TTo[] = [];
+            if (typeof size === 'object' && bytes.slice(offset).length === 0) {
+                return [array, offset];
+            }
+
+            if (size === 'remainder') {
+                while (offset < bytes.length) {
+                    const [value, newOffset] = item.read(bytes, offset);
+                    offset = newOffset;
+                    array.push(value);
+                }
+                return [array, offset];
+            }
+
+            const [resolvedSize, newOffset] = typeof size === 'number' ? [size, offset] : size.read(bytes, offset);
+            offset = newOffset;
+            for (let i = 0; i < resolvedSize; i += 1) {
+                const [value, newOffset] = item.read(bytes, offset);
+                offset = newOffset;
+                array.push(value);
+            }
+            return [array, offset];
+        },
+    });
+}
+
+/**
+ * Returns a codec for encoding and decoding arrays of values.
+ *
+ * This codec serializes arrays by encoding each element using the provided item codec.
+ * By default, a `u32` size prefix is included to indicate the number of items in the array.
+ * The `size` option can be used to modify this behaviour.
+ *
+ * @typeParam TFrom - The type of the elements to encode.
+ * @typeParam TTo - The type of the decoded elements.
+ *
+ * @param item - The codec for each item in the array.
+ * @param config - Optional configuration for the size encoding/decoding strategy.
+ * @returns A `VariableSizeCodec<TFrom[], TTo[]>` for encoding and decoding arrays.
+ *
+ * @example
+ * Encoding and decoding an array of `u8` numbers.
+ * ```ts
+ * const codec = getArrayCodec(getU8Codec());
+ * const bytes = codec.encode([1, 2, 3]);
+ * // 0x03000000010203
+ * //   |       └-- 3 items of 1 byte each.
+ * //   └-- 4-byte prefix telling us to read 3 items.
+ *
+ * const array = codec.decode(bytes);
+ * // [1, 2, 3]
+ * ```
+ *
+ * @example
+ * Using a `u16` size prefix instead of `u32`.
+ * ```ts
+ * const codec = getArrayCodec(getU8Codec(), { size: getU16Codec() });
+ * const bytes = codec.encode([1, 2, 3]);
+ * // 0x0300010203
+ * //   |   └-- 3 items of 1 byte each.
+ * //   └-- 2-byte prefix telling us to read 3 items.
+ * ```
+ *
+ * @example
+ * Using a fixed-size array of 3 items.
+ * ```ts
+ * const codec = getArrayCodec(getU8Codec(), { size: 3 });
+ * codec.encode([1, 2, 3]);
+ * // 0x010203
+ * //   └-- 3 items of 1 byte each. There must always be 3 items in the array.
+ * ```
+ *
+ * @example
+ * Using the `"remainder"` size strategy.
+ * ```ts
+ * const codec = getArrayCodec(getU8Codec(), { size: 'remainder' });
+ * codec.encode([1, 2, 3]);
+ * // 0x010203
+ * //   └-- 3 items of 1 byte each. The size is inferred from the remainder of the bytes.
+ * ```
+ *
+ * @remarks
+ * The size of the array can be controlled using the `size` option:
+ * - A `Codec<number>` (e.g. `getU16Codec()`) stores a size prefix before the array.
+ * - A `number` enforces a fixed number of elements.
+ * - `"remainder"` uses all remaining bytes to infer the array length.
+ *
+ * Separate {@link getArrayEncoder} and {@link getArrayDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getArrayEncoder(getU8Encoder()).encode([1, 2, 3]);
+ * const array = getArrayDecoder(getU8Decoder()).decode(bytes);
+ * ```
+ *
+ * @see {@link getArrayEncoder}
+ * @see {@link getArrayDecoder}
+ */
+export function getArrayCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config: ArrayCodecConfig<NumberCodec> & { size: 0 },
+): FixedSizeCodec<TFrom[], TTo[], 0>;
+export function getArrayCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: FixedSizeCodec<TFrom, TTo>,
+    config: ArrayCodecConfig<NumberCodec> & { size: number },
+): FixedSizeCodec<TFrom[], TTo[]>;
+export function getArrayCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config?: ArrayCodecConfig<NumberCodec>,
+): VariableSizeCodec<TFrom[], TTo[]>;
+export function getArrayCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config: ArrayCodecConfig<NumberCodec> = {},
+): Codec<TFrom[], TTo[]> {
+    return combineCodec(getArrayEncoder(item, config as object), getArrayDecoder(item, config as object));
+}
+
+function computeArrayLikeCodecSize(size: number | object | 'remainder', itemSize: number | null): number | null {
+    if (typeof size !== 'number') return null;
+    if (size === 0) return 0;
+    return itemSize === null ? null : itemSize * size;
+}

package/src/assertions.ts

@@ -0,0 +1,16 @@
+import { SOLANA_ERROR__CODECS__INVALID_NUMBER_OF_ITEMS, SolanaError } from '@solana/errors';
+
+/** Checks the number of items in an array-like structure is expected. */
+export function assertValidNumberOfItemsForCodec(
+    codecDescription: string,
+    expected: bigint | number,
+    actual: bigint | number,
+) {
+    if (expected !== actual) {
+        throw new SolanaError(SOLANA_ERROR__CODECS__INVALID_NUMBER_OF_ITEMS, {
+            actual,
+            codecDescription,
+            expected,
+        });
+    }
+}

package/src/bit-array.ts

@@ -0,0 +1,203 @@
+import {
+    assertByteArrayHasEnoughBytesForCodec,
+    combineCodec,
+    createDecoder,
+    createEncoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+} from '@solana/codecs-core';
+
+/**
+ * Defines the configuration options for bit array codecs.
+ *
+ * A bit array codec encodes an array of booleans into bits, packing them into bytes.
+ * This configuration allows adjusting the bit ordering.
+ *
+ * @see {@link getBitArrayEncoder}
+ * @see {@link getBitArrayDecoder}
+ * @see {@link getBitArrayCodec}
+ */
+export type BitArrayCodecConfig = {
+    /**
+     * Determines whether the bits should be read in reverse order.
+     *
+     * - `false` (default): The first boolean is stored in the most significant bit (MSB-first).
+     * - `true`: The first boolean is stored in the least significant bit (LSB-first).
+     *
+     * @defaultValue `false`
+     */
+    backward?: boolean;
+};
+
+/**
+ * Returns an encoder that packs an array of booleans into bits.
+ *
+ * This encoder converts a list of `boolean` values into a compact bit representation,
+ * storing 8 booleans per byte.
+ *
+ * The `backward` config option determines whether the bits are stored in MSB-first (`false`)
+ * or LSB-first (`true`).
+ *
+ * For more details, see {@link getBitArrayCodec}.
+ *
+ * @typeParam TSize - The number of bytes used to store the bit array.
+ *
+ * @param size - The number of bytes allocated for the bit array (must be sufficient for the expected boolean count).
+ * @param config - Configuration options for encoding the bit array.
+ * @returns A `FixedSizeEncoder<boolean[], TSize>` for encoding bit arrays.
+ *
+ * @example
+ * Encoding a bit array.
+ * ```ts
+ * const encoder = getBitArrayEncoder(1);
+ *
+ * encoder.encode([true, false, true, false, false, false, false, false]);
+ * // 0xa0 (0b10100000)
+ * ```
+ *
+ * @see {@link getBitArrayCodec}
+ */
+export function getBitArrayEncoder<TSize extends number>(
+    size: TSize,
+    config: BitArrayCodecConfig | boolean = {},
+): FixedSizeEncoder<boolean[], TSize> {
+    const parsedConfig: BitArrayCodecConfig = typeof config === 'boolean' ? { backward: config } : config;
+    const backward = parsedConfig.backward ?? false;
+    return createEncoder({
+        fixedSize: size,
+        write(value: boolean[], bytes, offset) {
+            const bytesToAdd: number[] = [];
+
+            for (let i = 0; i < size; i += 1) {
+                let byte = 0;
+                for (let j = 0; j < 8; j += 1) {
+                    const feature = Number(value[i * 8 + j] ?? 0);
+                    byte |= feature << (backward ? j : 7 - j);
+                }
+                if (backward) {
+                    bytesToAdd.unshift(byte);
+                } else {
+                    bytesToAdd.push(byte);
+                }
+            }
+
+            bytes.set(bytesToAdd, offset);
+            return size;
+        },
+    });
+}
+
+/**
+ * Returns a decoder that unpacks bits into an array of booleans.
+ *
+ * This decoder converts a compact bit representation back into a list of `boolean` values.
+ * Each byte is expanded into 8 booleans.
+ *
+ * The `backward` config option determines whether the bits are read in MSB-first (`false`)
+ * or LSB-first (`true`).
+ *
+ * For more details, see {@link getBitArrayCodec}.
+ *
+ * @typeParam TSize - The number of bytes used to store the bit array.
+ *
+ * @param size - The number of bytes allocated for the bit array (must be sufficient for the expected boolean count).
+ * @param config - Configuration options for decoding the bit array.
+ * @returns A `FixedSizeDecoder<boolean[], TSize>` for decoding bit arrays.
+ *
+ * @example
+ * Decoding a bit array.
+ * ```ts
+ * const decoder = getBitArrayDecoder(1);
+ *
+ * decoder.decode(new Uint8Array([0xa0]));
+ * // [true, false, true, false, false, false, false, false]
+ * ```
+ *
+ * @see {@link getBitArrayCodec}
+ */
+export function getBitArrayDecoder<TSize extends number>(
+    size: TSize,
+    config: BitArrayCodecConfig | boolean = {},
+): FixedSizeDecoder<boolean[], TSize> {
+    const parsedConfig: BitArrayCodecConfig = typeof config === 'boolean' ? { backward: config } : config;
+    const backward = parsedConfig.backward ?? false;
+    return createDecoder({
+        fixedSize: size,
+        read(bytes, offset) {
+            assertByteArrayHasEnoughBytesForCodec('bitArray', size, bytes, offset);
+            const booleans: boolean[] = [];
+            let slice = bytes.slice(offset, offset + size);
+            slice = backward ? slice.reverse() : slice;
+
+            slice.forEach(byte => {
+                for (let i = 0; i < 8; i += 1) {
+                    if (backward) {
+                        booleans.push(Boolean(byte & 1));
+                        byte >>= 1;
+                    } else {
+                        booleans.push(Boolean(byte & 0b1000_0000));
+                        byte <<= 1;
+                    }
+                }
+            });
+
+            return [booleans, offset + size];
+        },
+    });
+}
+
+/**
+ * Returns a codec that encodes and decodes boolean arrays as compact bit representations.
+ *
+ * This codec efficiently stores boolean arrays as bits, packing 8 values per byte.
+ * The `backward` config option determines whether bits are stored in MSB-first (`false`)
+ * or LSB-first (`true`).
+ *
+ * @typeParam TSize - The number of bytes used to store the bit array.
+ *
+ * @param size - The number of bytes allocated for the bit array (must be sufficient for the expected boolean count).
+ * @param config - Configuration options for encoding and decoding the bit array.
+ * @returns A `FixedSizeCodec<boolean[], boolean[], TSize>` for encoding and decoding bit arrays.
+ *
+ * @example
+ * Encoding and decoding a bit array.
+ * ```ts
+ * const codec = getBitArrayCodec(1);
+ *
+ * codec.encode([true, false, true, false, false, false, false, false]);
+ * // 0xa0 (0b10100000)
+ *
+ * codec.decode(new Uint8Array([0xa0]));
+ * // [true, false, true, false, false, false, false, false]
+ * ```
+ *
+ * @example
+ * Encoding and decoding a bit array backwards.
+ * ```ts
+ * const codec = getBitArrayCodec(1, { backward: true });
+ *
+ * codec.encode([true, false, true, false, false, false, false, false]);
+ * // 0x05 (0b00000101)
+ *
+ * codec.decode(new Uint8Array([0x05]));
+ * // [true, false, true, false, false, false, false, false]
+ * ```
+ *
+ * @remarks
+ * Separate {@link getBitArrayEncoder} and {@link getBitArrayDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getBitArrayEncoder(1).encode([true, false, true, false]);
+ * const value = getBitArrayDecoder(1).decode(bytes);
+ * ```
+ *
+ * @see {@link getBitArrayEncoder}
+ * @see {@link getBitArrayDecoder}
+ */
+export function getBitArrayCodec<TSize extends number>(
+    size: TSize,
+    config: BitArrayCodecConfig | boolean = {},
+): FixedSizeCodec<boolean[], boolean[], TSize> {
+    return combineCodec(getBitArrayEncoder(size, config), getBitArrayDecoder(size, config));
+}