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..0493bb1c9 100644 --- a/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts +++ b/packages/codecs-data-structures/src/__typetests__/struct-typetest.ts @@ -11,6 +11,30 @@ import { getUtf8Codec, getUtf8Decoder, getUtf8Encoder } from '@solana/codecs-str import { getStructCodec, getStructDecoder, getStructEncoder } from '../struct'; +/** + * 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. getStructEncoder([ @@ -22,6 +46,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 +61,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 +76,104 @@ 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]: 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; +} + { // [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<