From 859733eb47230cb8cbc32d2b9d50ddbf52c8d106 Mon Sep 17 00:00:00 2001 From: Shin <128954611+shin4141@users.noreply.github.com> Date: Sun, 23 Aug 2026 22:13:19 +0900 Subject: [PATCH 1/2] Preserve fixedSize for single-field struct codecs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Forward the only field’s literal fixedSize through struct encoder, decoder, and codec overloads while keeping multi-field structs on the existing number fallback. Add focused typetests and a patch changeset. --- .changeset/sunny-melons-do.md | 5 ++ .../src/__typetests__/struct-typetest.ts | 70 +++++++++++++++++++ packages/codecs-data-structures/src/struct.ts | 13 ++++ 3 files changed, 88 insertions(+) create mode 100644 .changeset/sunny-melons-do.md diff --git a/.changeset/sunny-melons-do.md b/.changeset/sunny-melons-do.md new file mode 100644 index 000000000..baa853d98 --- /dev/null +++ b/.changeset/sunny-melons-do.md @@ -0,0 +1,5 @@ +--- +"@solana/codecs-data-structures": patch +--- + +Preserve the literal `fixedSize` type for single-field fixed-size struct codecs. diff --git a/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts b/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts index e00d794c3..710570fb7 100644 --- a/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts +++ b/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts @@ -11,6 +11,8 @@ import { getUtf8Codec, getUtf8Decoder, getUtf8Encoder } from '@solana/codecs-str import { getStructCodec, getStructDecoder, getStructEncoder } from '../struct'; +type IsWidenedNumber = number extends T ? true : false; + { // [getStructEncoder]: It knows if the encoder is fixed size or variable size. getStructEncoder([ @@ -22,6 +24,7 @@ import { getStructCodec, getStructDecoder, getStructEncoder } from '../struct'; ['age', {} as FixedSizeEncoder], ]) satisfies VariableSizeEncoder<{ age: number; name: string }>; getStructEncoder([['age', getU32Encoder()]]) satisfies FixedSizeEncoder<{ age: number }>; + getStructEncoder([['age', getU32Encoder()]]) satisfies FixedSizeEncoder<{ age: bigint | number }, 4>; getStructEncoder([['name', getUtf8Encoder()]]) satisfies VariableSizeEncoder<{ name: string }>; } @@ -36,6 +39,7 @@ import { getStructCodec, getStructDecoder, getStructEncoder } from '../struct'; ['age', {} as FixedSizeDecoder], ]) satisfies VariableSizeDecoder<{ age: number; name: string }>; getStructDecoder([['age', getU32Decoder()]]) satisfies FixedSizeDecoder<{ age: number }>; + getStructDecoder([['age', getU32Decoder()]]) satisfies FixedSizeDecoder<{ age: number }, 4>; getStructDecoder([['name', getUtf8Decoder()]]) satisfies VariableSizeDecoder<{ name: string }>; } @@ -50,9 +54,75 @@ import { getStructCodec, getStructDecoder, getStructEncoder } from '../struct'; ['age', {} as FixedSizeCodec], ]) satisfies VariableSizeCodec<{ age: number; name: string }>; getStructCodec([['age', getU32Codec()]]) satisfies FixedSizeCodec<{ age: number }>; + getStructCodec([['age', getU32Codec()]]) satisfies FixedSizeCodec<{ age: bigint | number }, { age: number }, 4>; getStructCodec([['name', getUtf8Codec()]]) satisfies VariableSizeCodec<{ name: string }>; } +{ + // [getStructEncoder/Decoder/Codec]: It only preserves literal sizes for exactly one fixed-size field. + { + // It forwards a second literal size without hard-coding the U32 size. + getStructEncoder([['value', {} as FixedSizeEncoder]]) satisfies FixedSizeEncoder< + { value: number }, + 8 + >; + getStructDecoder([['value', {} as FixedSizeDecoder]]) satisfies FixedSizeDecoder< + { value: number }, + 8 + >; + getStructCodec([['value', {} as FixedSizeCodec]]) satisfies FixedSizeCodec< + { value: number }, + { value: number }, + 8 + >; + } + + { + // Two fixed-size fields stay widened; their sizes are not added by the type system. + const encoder = getStructEncoder([ + ['a', {} as FixedSizeEncoder], + ['b', {} as FixedSizeEncoder], + ]); + const decoder = getStructDecoder([ + ['a', {} as FixedSizeDecoder], + ['b', {} as FixedSizeDecoder], + ]); + const codec = getStructCodec([ + ['a', {} as FixedSizeCodec], + ['b', {} as FixedSizeCodec], + ]); + [encoder.fixedSize, decoder.fixedSize, codec.fixedSize] satisfies number[]; + true satisfies IsWidenedNumber; + true satisfies IsWidenedNumber; + true satisfies IsWidenedNumber; + } + + { + // Non-tuple field arrays stay widened even when their items have a literal size. + const encoderFields: readonly (readonly [string, FixedSizeEncoder])[] = []; + const decoderFields: readonly (readonly [string, FixedSizeDecoder])[] = []; + const codecFields: readonly (readonly [string, FixedSizeCodec])[] = []; + const encoder = getStructEncoder(encoderFields); + const decoder = getStructDecoder(decoderFields); + const codec = getStructCodec(codecFields); + [encoder.fixedSize, decoder.fixedSize, codec.fixedSize] satisfies number[]; + true satisfies IsWidenedNumber; + true satisfies IsWidenedNumber; + true satisfies IsWidenedNumber; + } + + { + // Empty structs preserve their existing widened fixed-size classification. + const encoder = getStructEncoder([]); + const decoder = getStructDecoder([]); + const codec = getStructCodec([]); + [encoder.fixedSize, decoder.fixedSize, codec.fixedSize] satisfies number[]; + true satisfies IsWidenedNumber; + true satisfies IsWidenedNumber; + true satisfies IsWidenedNumber; + } +} + { // [getStructEncoder]: It can infer complex struct types from fields. getStructEncoder([ diff --git a/packages/codecs-data-structures/src/struct.ts b/packages/codecs-data-structures/src/struct.ts index ad520bc88..15812a269 100644 --- a/packages/codecs-data-structures/src/struct.ts +++ b/packages/codecs-data-structures/src/struct.ts @@ -82,6 +82,9 @@ type GetDecoderTypeFromFields>> = DrainOuter * * @see {@link getStructCodec} */ +export function getStructEncoder]]>( + fields: TFields, +): FixedSizeEncoder, TFields[0][1]['fixedSize']>; export function getStructEncoder>>( fields: TFields, ): FixedSizeEncoder>; @@ -144,6 +147,9 @@ export function getStructEncoder>>( * * @see {@link getStructCodec} */ +export function getStructDecoder]]>( + fields: TFields, +): FixedSizeDecoder, TFields[0][1]['fixedSize']>; export function getStructDecoder>>( fields: TFields, ): FixedSizeDecoder>; @@ -217,6 +223,13 @@ export function getStructDecoder>>( * @see {@link getStructEncoder} * @see {@link getStructDecoder} */ +export function getStructCodec]]>( + fields: TFields, +): FixedSizeCodec< + GetEncoderTypeFromFields, + GetDecoderTypeFromFields & GetEncoderTypeFromFields, + TFields[0][1]['fixedSize'] +>; export function getStructCodec>>( fields: TFields, ): FixedSizeCodec< From 18d0aebe920c1df1c3f58c01a69bf91490e2402d Mon Sep 17 00:00:00 2001 From: Shin <128954611+shin4141@users.noreply.github.com> Date: Thu, 27 Aug 2026 22:58:14 +0900 Subject: [PATCH 2/2] Tighten struct fixedSize typetests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use the repository’s strict Equal helper and separate encoder, decoder, and codec assertions so widened fixed sizes are checked exactly as number. --- .../src/__typetests__/struct-typetest.ts | 177 +++++++++++------- 1 file changed, 114 insertions(+), 63 deletions(-) diff --git a/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts b/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts index 710570fb7..0493bb1c9 100644 --- a/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts +++ b/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts @@ -11,7 +11,29 @@ import { getUtf8Codec, getUtf8Decoder, getUtf8Encoder } from '@solana/codecs-str import { getStructCodec, getStructDecoder, getStructEncoder } from '../struct'; -type IsWidenedNumber = number extends T ? true : false; +/** + * Strict type-equality helper used by typetests below. Resolves to `true` only + * if `A` and `B` are mutually assignable AND share the same modifier set (`?`, + * `readonly`); otherwise resolves to `false`. + * + * This is stricter than `satisfies` for two reasons: + * + * 1. **Bidirectionality.** `A satisfies B` only checks that `A` is assignable + * to `B`. A test using `satisfies` passes if the actual type has extra + * members beyond what we asserted — which would silently mask a regression + * that re-introduced a nested `Omit<...>` wrapper, since `Omit & A` + * is still structurally assignable to a flat literal. + * 2. **Modifier strictness.** `A satisfies B` tolerates losing `?` (required + * is assignable to optional) and losing `readonly` (readonly is assignable + * to mutable). `Equal` distinguishes `{ x: T }` from `{ x?: T }` and from + * `{ readonly x: T }` because the inferred-position generic comparison + * uses identity rather than assignability for the type parameters. + * + * Use `Equal` when the exact shape (including modifiers) matters. Use + * `satisfies` when one-way assignability is the actual requirement (e.g. + * "this value is usable where `Disposable & X` is expected"). + */ +type Equal = (() => T extends A ? 1 : 2) extends () => T extends B ? 1 : 2 ? true : false; { // [getStructEncoder]: It knows if the encoder is fixed size or variable size. @@ -59,68 +81,97 @@ type IsWidenedNumber = number extends T ? true : false; } { - // [getStructEncoder/Decoder/Codec]: It only preserves literal sizes for exactly one fixed-size field. - { - // It forwards a second literal size without hard-coding the U32 size. - getStructEncoder([['value', {} as FixedSizeEncoder]]) satisfies FixedSizeEncoder< - { value: number }, - 8 - >; - getStructDecoder([['value', {} as FixedSizeDecoder]]) satisfies FixedSizeDecoder< - { value: number }, - 8 - >; - getStructCodec([['value', {} as FixedSizeCodec]]) satisfies FixedSizeCodec< - { value: number }, - { value: number }, - 8 - >; - } - - { - // Two fixed-size fields stay widened; their sizes are not added by the type system. - const encoder = getStructEncoder([ - ['a', {} as FixedSizeEncoder], - ['b', {} as FixedSizeEncoder], - ]); - const decoder = getStructDecoder([ - ['a', {} as FixedSizeDecoder], - ['b', {} as FixedSizeDecoder], - ]); - const codec = getStructCodec([ - ['a', {} as FixedSizeCodec], - ['b', {} as FixedSizeCodec], - ]); - [encoder.fixedSize, decoder.fixedSize, codec.fixedSize] satisfies number[]; - true satisfies IsWidenedNumber; - true satisfies IsWidenedNumber; - true satisfies IsWidenedNumber; - } - - { - // Non-tuple field arrays stay widened even when their items have a literal size. - const encoderFields: readonly (readonly [string, FixedSizeEncoder])[] = []; - const decoderFields: readonly (readonly [string, FixedSizeDecoder])[] = []; - const codecFields: readonly (readonly [string, FixedSizeCodec])[] = []; - const encoder = getStructEncoder(encoderFields); - const decoder = getStructDecoder(decoderFields); - const codec = getStructCodec(codecFields); - [encoder.fixedSize, decoder.fixedSize, codec.fixedSize] satisfies number[]; - true satisfies IsWidenedNumber; - true satisfies IsWidenedNumber; - true satisfies IsWidenedNumber; - } - - { - // Empty structs preserve their existing widened fixed-size classification. - const encoder = getStructEncoder([]); - const decoder = getStructDecoder([]); - const codec = getStructCodec([]); - [encoder.fixedSize, decoder.fixedSize, codec.fixedSize] satisfies number[]; - true satisfies IsWidenedNumber; - true satisfies IsWidenedNumber; - true satisfies IsWidenedNumber; - } + // [getStructEncoder]: It forwards a second literal size without hard-coding the U32 size. + getStructEncoder([['value', {} as FixedSizeEncoder]]) satisfies FixedSizeEncoder<{ value: number }, 8>; +} + +{ + // [getStructDecoder]: It forwards a second literal size without hard-coding the U32 size. + getStructDecoder([['value', {} as FixedSizeDecoder]]) satisfies FixedSizeDecoder<{ value: number }, 8>; +} + +{ + // [getStructCodec]: It forwards a second literal size without hard-coding the U32 size. + getStructCodec([['value', {} as FixedSizeCodec]]) satisfies FixedSizeCodec< + { value: number }, + { value: number }, + 8 + >; +} + +{ + // [getStructEncoder]: Two fixed-size fields keep a widened size; it is not narrowed to a literal. + const encoder = getStructEncoder([ + ['a', {} as FixedSizeEncoder], + ['b', {} as FixedSizeEncoder], + ]); + encoder satisfies FixedSizeEncoder<{ a: number; b: number }>; + true satisfies Equal; +} + +{ + // [getStructDecoder]: Two fixed-size fields keep a widened size; it is not narrowed to a literal. + const decoder = getStructDecoder([ + ['a', {} as FixedSizeDecoder], + ['b', {} as FixedSizeDecoder], + ]); + decoder satisfies FixedSizeDecoder<{ a: number; b: number }>; + true satisfies Equal; +} + +{ + // [getStructCodec]: Two fixed-size fields keep a widened size; it is not narrowed to a literal. + const codec = getStructCodec([ + ['a', {} as FixedSizeCodec], + ['b', {} as FixedSizeCodec], + ]); + codec satisfies FixedSizeCodec<{ a: number; b: number }>; + true satisfies Equal; +} + +{ + // [getStructEncoder]: A non-tuple field array keeps a widened size even when its items have a literal size. + const fields: readonly (readonly [string, FixedSizeEncoder])[] = []; + const encoder = getStructEncoder(fields); + encoder.fixedSize satisfies number; + true satisfies Equal; +} + +{ + // [getStructDecoder]: A non-tuple field array keeps a widened size even when its items have a literal size. + const fields: readonly (readonly [string, FixedSizeDecoder])[] = []; + const decoder = getStructDecoder(fields); + decoder.fixedSize satisfies number; + true satisfies Equal; +} + +{ + // [getStructCodec]: A non-tuple field array keeps a widened size even when its items have a literal size. + const fields: readonly (readonly [string, FixedSizeCodec])[] = []; + const codec = getStructCodec(fields); + codec.fixedSize satisfies number; + true satisfies Equal; +} + +{ + // [getStructEncoder]: An empty struct preserves its existing widened fixed-size classification. + const encoder = getStructEncoder([]); + encoder.fixedSize satisfies number; + true satisfies Equal; +} + +{ + // [getStructDecoder]: An empty struct preserves its existing widened fixed-size classification. + const decoder = getStructDecoder([]); + decoder.fixedSize satisfies number; + true satisfies Equal; +} + +{ + // [getStructCodec]: An empty struct preserves its existing widened fixed-size classification. + const codec = getStructCodec([]); + codec.fixedSize satisfies number; + true satisfies Equal; } {