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

package/src/predicate.ts

@@ -0,0 +1,214 @@
+import {
+    Codec,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    ReadonlyUint8Array,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+
+import { getUnionCodec, getUnionDecoder, getUnionEncoder } from './union';
+
+/**
+ * Returns an encoder that selects between two encoders based on a predicate.
+ *
+ * This encoder uses a boolean predicate function to determine which of two
+ * encoders to use for a given value. If the predicate returns `true`, the
+ * `ifTrue` encoder is used; otherwise, the `ifFalse` encoder is used.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ *
+ * @param predicate - A function that returns `true` or `false` for a given value.
+ * @param ifTrue - The encoder to use when the predicate returns `true`.
+ * @param ifFalse - The encoder to use when the predicate returns `false`.
+ * @returns An `Encoder` based on the provided encoders.
+ *
+ * @example
+ * Encoding small and large numbers differently.
+ * ```ts
+ * const encoder = getPredicateEncoder(
+ *   (n: number) => n < 256,
+ *   getU8Encoder(),
+ *   getU32Encoder()
+ * );
+ *
+ * encoder.encode(42);
+ * // 0x2a
+ * //   └── Small number encoded as u8
+ *
+ * encoder.encode(1000);
+ * // 0xe8030000
+ * //   └── Large number encoded as u32
+ * ```
+ *
+ * @see {@link getPredicateCodec}
+ */
+export function getPredicateEncoder<TFrom, TSize extends number>(
+    predicate: (value: TFrom) => boolean,
+    ifTrue: FixedSizeEncoder<TFrom, TSize>,
+    ifFalse: FixedSizeEncoder<TFrom, TSize>,
+): FixedSizeEncoder<TFrom, TSize>;
+export function getPredicateEncoder<TFrom>(
+    predicate: (value: TFrom) => boolean,
+    ifTrue: FixedSizeEncoder<TFrom>,
+    ifFalse: FixedSizeEncoder<TFrom>,
+): FixedSizeEncoder<TFrom>;
+export function getPredicateEncoder<TFrom>(
+    predicate: (value: TFrom) => boolean,
+    ifTrue: VariableSizeEncoder<TFrom>,
+    ifFalse: VariableSizeEncoder<TFrom>,
+): VariableSizeEncoder<TFrom>;
+export function getPredicateEncoder<TFrom>(
+    predicate: (value: TFrom) => boolean,
+    ifTrue: Encoder<TFrom>,
+    ifFalse: Encoder<TFrom>,
+): Encoder<TFrom>;
+export function getPredicateEncoder<TFrom>(
+    predicate: (value: TFrom) => boolean,
+    ifTrue: Encoder<TFrom>,
+    ifFalse: Encoder<TFrom>,
+): Encoder<TFrom> {
+    return getUnionEncoder([ifTrue, ifFalse], (value: TFrom) => (predicate(value) ? 0 : 1));
+}
+
+/**
+ * Returns a decoder that selects between two decoders based on a predicate.
+ *
+ * This decoder uses a boolean predicate function on the raw bytes to determine
+ * which of two decoders to use. If the predicate returns `true`, the `ifTrue`
+ * decoder is used; otherwise, the `ifFalse` decoder is used.
+ *
+ * @typeParam TTo - The type of the value to decode.
+ *
+ * @param predicate - A function that returns `true` or `false` for a given byte array.
+ * @param ifTrue - The decoder to use when the predicate returns `true`.
+ * @param ifFalse - The decoder to use when the predicate returns `false`.
+ * @returns A `Decoder` based on the provided decoders.
+ *
+ * @example
+ * Decoding small and large numbers based on byte length.
+ * ```ts
+ * const decoder = getPredicateDecoder(
+ *   bytes => bytes.length === 1,
+ *   getU8Decoder(),
+ *   getU32Decoder()
+ * );
+ *
+ * decoder.decode(new Uint8Array([0x2a]));
+ * // 42 (decoded as u8)
+ *
+ * decoder.decode(new Uint8Array([0xe8, 0x03, 0x00, 0x00]));
+ * // 1000 (decoded as u32)
+ * ```
+ *
+ * @see {@link getPredicateCodec}
+ */
+export function getPredicateDecoder<TTo, TSize extends number>(
+    predicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: FixedSizeDecoder<TTo, TSize>,
+    ifFalse: FixedSizeDecoder<TTo, TSize>,
+): FixedSizeDecoder<TTo, TSize>;
+export function getPredicateDecoder<TTo>(
+    predicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: FixedSizeDecoder<TTo>,
+    ifFalse: FixedSizeDecoder<TTo>,
+): FixedSizeDecoder<TTo>;
+export function getPredicateDecoder<TTo>(
+    predicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: VariableSizeDecoder<TTo>,
+    ifFalse: VariableSizeDecoder<TTo>,
+): VariableSizeDecoder<TTo>;
+export function getPredicateDecoder<TTo>(
+    predicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: Decoder<TTo>,
+    ifFalse: Decoder<TTo>,
+): Decoder<TTo>;
+export function getPredicateDecoder<TTo>(
+    predicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: Decoder<TTo>,
+    ifFalse: Decoder<TTo>,
+): Decoder<TTo> {
+    return getUnionDecoder([ifTrue, ifFalse], (value: ReadonlyUint8Array) => (predicate(value) ? 0 : 1));
+}
+
+/**
+ * Returns a codec that selects between two codecs based on predicates.
+ *
+ * This codec uses boolean predicate functions to determine which of two codecs
+ * to use for encoding and decoding. If the encoding predicate returns `true`
+ * for a value, the `ifTrue` codec is used to encode it; otherwise `ifFalse`.
+ * Similarly, if the decoding predicate returns `true` for the bytes, the
+ * `ifTrue` codec is used to decode them.
+ *
+ * @typeParam TFrom - The type of the value to encode.
+ * @typeParam TTo - The type of the value to decode.
+ *
+ * @param encodePredicate - A function that returns `true` or `false` for a given value.
+ * @param decodePredicate - A function that returns `true` or `false` for a given byte array.
+ * @param ifTrue - The codec to use when the respective predicate returns `true`.
+ * @param ifFalse - The codec to use when the respective predicate returns `false`.
+ * @returns A `Codec` based on the provided codecs.
+ *
+ * @example
+ * Encoding and decoding small and large numbers differently.
+ * ```ts
+ * const codec = getPredicateCodec(
+ *   (n: number) => n < 256,
+ *   bytes => bytes.length === 1,
+ *   getU8Codec(),
+ *   getU32Codec()
+ * );
+ *
+ * const smallBytes = codec.encode(42);
+ * // 0x2a (encoded as u8)
+ *
+ * const largeBytes = codec.encode(1000);
+ * // 0xe8030000 (encoded as u32)
+ *
+ * codec.decode(smallBytes); // 42
+ * codec.decode(largeBytes); // 1000
+ * ```
+ *
+ * @see {@link getPredicateEncoder}
+ * @see {@link getPredicateDecoder}
+ */
+export function getPredicateCodec<TFrom, TTo extends TFrom, TSize extends number>(
+    encodePredicate: (value: TFrom) => boolean,
+    decodePredicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: FixedSizeCodec<TFrom, TTo, TSize>,
+    ifFalse: FixedSizeCodec<TFrom, TTo, TSize>,
+): FixedSizeCodec<TFrom, TTo, TSize>;
+export function getPredicateCodec<TFrom, TTo extends TFrom>(
+    encodePredicate: (value: TFrom) => boolean,
+    decodePredicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: FixedSizeCodec<TFrom, TTo>,
+    ifFalse: FixedSizeCodec<TFrom, TTo>,
+): FixedSizeCodec<TFrom, TTo>;
+export function getPredicateCodec<TFrom, TTo extends TFrom>(
+    encodePredicate: (value: TFrom) => boolean,
+    decodePredicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: VariableSizeCodec<TFrom, TTo>,
+    ifFalse: VariableSizeCodec<TFrom, TTo>,
+): VariableSizeCodec<TFrom, TTo>;
+export function getPredicateCodec<TFrom, TTo extends TFrom>(
+    encodePredicate: (value: TFrom) => boolean,
+    decodePredicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: Codec<TFrom, TTo>,
+    ifFalse: Codec<TFrom, TTo>,
+): Codec<TFrom, TTo>;
+export function getPredicateCodec<TFrom, TTo extends TFrom>(
+    encodePredicate: (value: TFrom) => boolean,
+    decodePredicate: (value: ReadonlyUint8Array) => boolean,
+    ifTrue: Codec<TFrom, TTo>,
+    ifFalse: Codec<TFrom, TTo>,
+): Codec<TFrom, TTo> {
+    return getUnionCodec(
+        [ifTrue, ifFalse],
+        (value: TFrom) => (encodePredicate(value) ? 0 : 1),
+        (value: ReadonlyUint8Array) => (decodePredicate(value) ? 0 : 1),
+    );
+}

package/src/set.ts

@@ -0,0 +1,206 @@
+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';
+
+/**
+ * Defines the configuration options for set codecs.
+ *
+ * This configuration allows specifying how the size of the set is encoded.
+ * The `size` option can be:
+ *
+ * - A {@link NumberCodec}, {@link NumberEncoder}, or {@link NumberDecoder} to store the size as a prefix.
+ * - A fixed number of items, enforcing a strict length.
+ * - The string `'remainder'` to infer the set size from the remaining bytes (only for fixed-size items).
+ *
+ * @typeParam TPrefix - The type used for encoding the size of the set.
+ */
+export type SetCodecConfig<TPrefix extends NumberCodec | NumberDecoder | NumberEncoder> = {
+    /**
+     * The size encoding strategy for the set.
+     * @defaultValue Uses a `u32` prefix.
+     */
+    size?: ArrayLikeCodecSize<TPrefix>;
+};
+
+/**
+ * Returns an encoder for sets of items.
+ *
+ * This encoder serializes `Set<T>` values by encoding each item using the provided item encoder.
+ * The number of items is stored as a prefix using a `u32` codec by default.
+ *
+ * For more details, see {@link getSetCodec}.
+ *
+ * @typeParam TFrom - The type of the items in the set before encoding.
+ *
+ * @param item - The encoder to use for each set item.
+ * @param config - Optional configuration specifying the size strategy.
+ * @returns An `Encoder<Set<TFrom>>` for encoding sets of items.
+ *
+ * @example
+ * Encoding a set of `u8` numbers.
+ * ```ts
+ * const encoder = getSetEncoder(getU8Encoder());
+ * const bytes = encoder.encode(new Set([1, 2, 3]));
+ * // 0x03000000010203
+ * //   |       └-- 3 items of 1 byte each.
+ * //   └-- 4-byte prefix indicating 3 items.
+ * ```
+ *
+ * @see {@link getSetCodec}
+ */
+export function getSetEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config: SetCodecConfig<NumberEncoder> & { size: 0 },
+): FixedSizeEncoder<Set<TFrom>, 0>;
+export function getSetEncoder<TFrom>(
+    item: FixedSizeEncoder<TFrom>,
+    config: SetCodecConfig<NumberEncoder> & { size: number },
+): FixedSizeEncoder<Set<TFrom>>;
+export function getSetEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config?: SetCodecConfig<NumberEncoder>,
+): VariableSizeEncoder<Set<TFrom>>;
+export function getSetEncoder<TFrom>(
+    item: Encoder<TFrom>,
+    config: SetCodecConfig<NumberEncoder> = {},
+): Encoder<Set<TFrom>> {
+    return transformEncoder(getArrayEncoder(item, config as object), (set: Set<TFrom>): TFrom[] => [...set]);
+}
+
+/**
+ * Returns a decoder for sets of items.
+ *
+ * This decoder deserializes a `Set<T>` from a byte array by decoding each item using the provided item decoder.
+ * The number of items is determined by a `u32` size prefix by default.
+ *
+ * For more details, see {@link getSetCodec}.
+ *
+ * @typeParam TTo - The type of the items in the set after decoding.
+ *
+ * @param item - The decoder to use for each set item.
+ * @param config - Optional configuration specifying the size strategy.
+ * @returns A `Decoder<Set<TTo>>` for decoding sets of items.
+ *
+ * @example
+ * Decoding a set of `u8` numbers.
+ * ```ts
+ * const decoder = getSetDecoder(getU8Decoder());
+ * const value = decoder.decode(new Uint8Array([0x03, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03]));
+ * // new Set([1, 2, 3])
+ * ```
+ *
+ * @see {@link getSetCodec}
+ */
+export function getSetDecoder<TTo>(
+    item: Decoder<TTo>,
+    config: SetCodecConfig<NumberDecoder> & { size: 0 },
+): FixedSizeDecoder<Set<TTo>, 0>;
+export function getSetDecoder<TTo>(
+    item: FixedSizeDecoder<TTo>,
+    config: SetCodecConfig<NumberDecoder> & { size: number },
+): FixedSizeDecoder<Set<TTo>>;
+export function getSetDecoder<TTo>(
+    item: Decoder<TTo>,
+    config?: SetCodecConfig<NumberDecoder>,
+): VariableSizeDecoder<Set<TTo>>;
+export function getSetDecoder<TTo>(item: Decoder<TTo>, config: SetCodecConfig<NumberDecoder> = {}): Decoder<Set<TTo>> {
+    return transformDecoder(getArrayDecoder(item, config as object), (entries: TTo[]): Set<TTo> => new Set(entries));
+}
+
+/**
+ * Returns a codec for encoding and decoding sets of items.
+ *
+ * This codec serializes `Set<T>` values by encoding each item using the provided item codec.
+ * The number of items is stored as a prefix using a `u32` codec by default.
+ *
+ * @typeParam TFrom - The type of the items in the set before encoding.
+ * @typeParam TTo - The type of the items in the set after decoding.
+ *
+ * @param item - The codec to use for each set item.
+ * @param config - Optional configuration specifying the size strategy.
+ * @returns A `Codec<Set<TFrom>, Set<TTo>>` for encoding and decoding sets.
+ *
+ * @example
+ * Encoding and decoding a set of `u8` numbers.
+ * ```ts
+ * const codec = getSetCodec(getU8Codec());
+ * const bytes = codec.encode(new Set([1, 2, 3]));
+ * // 0x03000000010203
+ * //   |       └-- 3 items of 1 byte each.
+ * //   └-- 4-byte prefix indicating 3 items.
+ *
+ * const value = codec.decode(bytes);
+ * // new Set([1, 2, 3])
+ * ```
+ *
+ * @example
+ * Using a `u16` prefix for size.
+ * ```ts
+ * const codec = getSetCodec(getU8Codec(), { size: getU16Codec() });
+ * const bytes = codec.encode(new Set([1, 2, 3]));
+ * // 0x0300010203
+ * //   |   └-- 3 items of 1 byte each.
+ * //   └-- 2-byte prefix indicating 3 items.
+ * ```
+ *
+ * @example
+ * Using a fixed-size set.
+ * ```ts
+ * const codec = getSetCodec(getU8Codec(), { size: 3 });
+ * const bytes = codec.encode(new Set([1, 2, 3]));
+ * // 0x010203
+ * //   └-- Exactly 3 items of 1 byte each.
+ * ```
+ *
+ * @example
+ * Using remainder to infer set size.
+ * ```ts
+ * const codec = getSetCodec(getU8Codec(), { size: 'remainder' });
+ * const bytes = codec.encode(new Set([1, 2, 3]));
+ * // 0x010203
+ * //   └-- 3 items of 1 byte each. The size is inferred from the remaining bytes.
+ * ```
+ *
+ * @remarks
+ * Separate {@link getSetEncoder} and {@link getSetDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getSetEncoder(getU8Encoder()).encode(new Set([1, 2, 3]));
+ * const value = getSetDecoder(getU8Decoder()).decode(bytes);
+ * ```
+ *
+ * @see {@link getSetEncoder}
+ * @see {@link getSetDecoder}
+ */
+export function getSetCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config: SetCodecConfig<NumberCodec> & { size: 0 },
+): FixedSizeCodec<Set<TFrom>, Set<TTo>, 0>;
+export function getSetCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: FixedSizeCodec<TFrom, TTo>,
+    config: SetCodecConfig<NumberCodec> & { size: number },
+): FixedSizeCodec<Set<TFrom>, Set<TTo>>;
+export function getSetCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config?: SetCodecConfig<NumberCodec>,
+): VariableSizeCodec<Set<TFrom>, Set<TTo>>;
+export function getSetCodec<TFrom, TTo extends TFrom = TFrom>(
+    item: Codec<TFrom, TTo>,
+    config: SetCodecConfig<NumberCodec> = {},
+): Codec<Set<TFrom>, Set<TTo>> {
+    return combineCodec(getSetEncoder(item, config as object), getSetDecoder(item, config as object));
+}

package/src/struct.ts

@@ -0,0 +1,239 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import {
+    Codec,
+    combineCodec,
+    createDecoder,
+    createEncoder,
+    Decoder,
+    Encoder,
+    FixedSizeCodec,
+    FixedSizeDecoder,
+    FixedSizeEncoder,
+    getEncodedSize,
+    ReadonlyUint8Array,
+    VariableSizeCodec,
+    VariableSizeDecoder,
+    VariableSizeEncoder,
+} from '@solana/codecs-core';
+
+import { DrainOuterGeneric, getFixedSize, getMaxSize, sumCodecSizes } from './utils';
+
+/**
+ * Represents a collection of named fields used in struct codecs.
+ *
+ * Each field is defined as a tuple containing:
+ * - A string key representing the field name.
+ * - A codec used to encode and decode the field's value.
+ *
+ * @typeParam T - The codec type used for each field.
+ */
+type Fields<T> = readonly (readonly [string, T])[];
+
+type ArrayIndices<T extends readonly unknown[]> = Exclude<Partial<T>['length'], T['length']> & number;
+
+/**
+ * Infers the TypeScript type for an object that can be encoded using a struct codec.
+ *
+ * This type maps the provided field encoders to their corresponding values.
+ *
+ * @typeParam TFields - The fields of the struct, each paired with an encoder.
+ */
+type GetEncoderTypeFromFields<TFields extends Fields<Encoder<any>>> = DrainOuterGeneric<{
+    [I in ArrayIndices<TFields> as TFields[I][0]]: TFields[I][1] extends Encoder<infer TFrom> ? TFrom : never;
+}>;
+
+/**
+ * Infers the TypeScript type for an object that can be decoded using a struct codec.
+ *
+ * This type maps the provided field decoders to their corresponding values.
+ *
+ * @typeParam TFields - The fields of the struct, each paired with a decoder.
+ */
+type GetDecoderTypeFromFields<TFields extends Fields<Decoder<any>>> = DrainOuterGeneric<{
+    [I in ArrayIndices<TFields> as TFields[I][0]]: TFields[I][1] extends Decoder<infer TTo> ? TTo : never;
+}>;
+
+/**
+ * Returns an encoder for custom objects.
+ *
+ * This encoder serializes an object by encoding its fields sequentially,
+ * using the provided field encoders.
+ *
+ * For more details, see {@link getStructCodec}.
+ *
+ * @typeParam TFields - The fields of the struct, each paired with an encoder.
+ *
+ * @param fields - The name and encoder of each field.
+ * @returns A `FixedSizeEncoder` or `VariableSizeEncoder` for encoding custom objects.
+ *
+ * @example
+ * Encoding a custom struct.
+ * ```ts
+ * const encoder = getStructEncoder([
+ *   ['name', fixCodecSize(getUtf8Encoder(), 5)],
+ *   ['age', getU8Encoder()]
+ * ]);
+ *
+ * const bytes = encoder.encode({ name: 'Alice', age: 42 });
+ * // 0x416c6963652a
+ * //   |         └── Age (42)
+ * //   └── Name ("Alice")
+ * ```
+ *
+ * @see {@link getStructCodec}
+ */
+export function getStructEncoder<const TFields extends Fields<FixedSizeEncoder<any>>>(
+    fields: TFields,
+): FixedSizeEncoder<GetEncoderTypeFromFields<TFields>>;
+export function getStructEncoder<const TFields extends Fields<Encoder<any>>>(
+    fields: TFields,
+): VariableSizeEncoder<GetEncoderTypeFromFields<TFields>>;
+export function getStructEncoder<const TFields extends Fields<Encoder<any>>>(
+    fields: TFields,
+): Encoder<GetEncoderTypeFromFields<TFields>> {
+    type TFrom = GetEncoderTypeFromFields<TFields>;
+    const fieldCodecs = fields.map(([, codec]) => codec);
+    const fixedSize = sumCodecSizes(fieldCodecs.map(getFixedSize));
+    const maxSize = sumCodecSizes(fieldCodecs.map(getMaxSize)) ?? undefined;
+
+    return createEncoder({
+        ...(fixedSize === null
+            ? {
+                  getSizeFromValue: (value: TFrom) =>
+                      fields
+                          .map(([key, codec]) => getEncodedSize(value[key as keyof TFrom], codec))
+                          .reduce((all, one) => all + one, 0),
+                  maxSize,
+              }
+            : { fixedSize }),
+        write: (struct: TFrom, bytes, offset) => {
+            fields.forEach(([key, codec]) => {
+                offset = codec.write(struct[key as keyof TFrom], bytes, offset);
+            });
+            return offset;
+        },
+    });
+}
+
+/**
+ * Returns a decoder for custom objects.
+ *
+ * This decoder deserializes an object by decoding its fields sequentially,
+ * using the provided field decoders.
+ *
+ * For more details, see {@link getStructCodec}.
+ *
+ * @typeParam TFields - The fields of the struct, each paired with a decoder.
+ *
+ * @param fields - The name and decoder of each field.
+ * @returns A `FixedSizeDecoder` or `VariableSizeDecoder` for decoding custom objects.
+ *
+ * @example
+ * Decoding a custom struct.
+ * ```ts
+ * const decoder = getStructDecoder([
+ *   ['name', fixCodecSize(getUtf8Decoder(), 5)],
+ *   ['age', getU8Decoder()]
+ * ]);
+ *
+ * const struct = decoder.decode(new Uint8Array([
+ *   0x41,0x6c,0x69,0x63,0x65,0x2a
+ * ]));
+ * // { name: 'Alice', age: 42 }
+ * ```
+ *
+ * @see {@link getStructCodec}
+ */
+export function getStructDecoder<const TFields extends Fields<FixedSizeDecoder<any>>>(
+    fields: TFields,
+): FixedSizeDecoder<GetDecoderTypeFromFields<TFields>>;
+export function getStructDecoder<const TFields extends Fields<Decoder<any>>>(
+    fields: TFields,
+): VariableSizeDecoder<GetDecoderTypeFromFields<TFields>>;
+export function getStructDecoder<const TFields extends Fields<Decoder<any>>>(
+    fields: TFields,
+): Decoder<GetDecoderTypeFromFields<TFields>> {
+    type TTo = GetDecoderTypeFromFields<TFields>;
+    const fieldCodecs = fields.map(([, codec]) => codec);
+    const fixedSize = sumCodecSizes(fieldCodecs.map(getFixedSize));
+    const maxSize = sumCodecSizes(fieldCodecs.map(getMaxSize)) ?? undefined;
+
+    return createDecoder({
+        ...(fixedSize === null ? { maxSize } : { fixedSize }),
+        read: (bytes: ReadonlyUint8Array | Uint8Array, offset) => {
+            const struct = {} as TTo;
+            fields.forEach(([key, codec]) => {
+                const [value, newOffset] = codec.read(bytes, offset);
+                offset = newOffset;
+                struct[key as keyof TTo] = value;
+            });
+            return [struct, offset];
+        },
+    });
+}
+
+/**
+ * Returns a codec for encoding and decoding custom objects.
+ *
+ * This codec serializes objects by encoding and decoding each field sequentially.
+ *
+ * @typeParam TFields - The fields of the struct, each paired with a codec.
+ *
+ * @param fields - The name and codec of each field.
+ * @returns A `FixedSizeCodec` or `VariableSizeCodec` for encoding and decoding custom objects.
+ *
+ * @example
+ * Encoding and decoding a custom struct.
+ * ```ts
+ * const codec = getStructCodec([
+ *   ['name', fixCodecSize(getUtf8Codec(), 5)],
+ *   ['age', getU8Codec()]
+ * ]);
+ *
+ * const bytes = codec.encode({ name: 'Alice', age: 42 });
+ * // 0x416c6963652a
+ * //   |         └── Age (42)
+ * //   └── Name ("Alice")
+ *
+ * const struct = codec.decode(bytes);
+ * // { name: 'Alice', age: 42 }
+ * ```
+ *
+ * @remarks
+ * Separate {@link getStructEncoder} and {@link getStructDecoder} functions are available.
+ *
+ * ```ts
+ * const bytes = getStructEncoder([
+ *   ['name', fixCodecSize(getUtf8Encoder(), 5)],
+ *   ['age', getU8Encoder()]
+ * ]).encode({ name: 'Alice', age: 42 });
+ *
+ * const struct = getStructDecoder([
+ *   ['name', fixCodecSize(getUtf8Decoder(), 5)],
+ *   ['age', getU8Decoder()]
+ * ]).decode(bytes);
+ * ```
+ *
+ * @see {@link getStructEncoder}
+ * @see {@link getStructDecoder}
+ */
+export function getStructCodec<const TFields extends Fields<FixedSizeCodec<any>>>(
+    fields: TFields,
+): FixedSizeCodec<
+    GetEncoderTypeFromFields<TFields>,
+    GetDecoderTypeFromFields<TFields> & GetEncoderTypeFromFields<TFields>
+>;
+export function getStructCodec<const TFields extends Fields<Codec<any>>>(
+    fields: TFields,
+): VariableSizeCodec<
+    GetEncoderTypeFromFields<TFields>,
+    GetDecoderTypeFromFields<TFields> & GetEncoderTypeFromFields<TFields>
+>;
+export function getStructCodec<const TFields extends Fields<Codec<any>>>(
+    fields: TFields,
+): Codec<GetEncoderTypeFromFields<TFields>, GetDecoderTypeFromFields<TFields> & GetEncoderTypeFromFields<TFields>> {
+    return combineCodec(
+        getStructEncoder(fields),
+        getStructDecoder(fields) as Decoder<GetDecoderTypeFromFields<TFields> & GetEncoderTypeFromFields<TFields>>,
+    );
+}