fix(TSchema): preserve field order during Struct encoding

Author: solidsnakedev

packages/evolution/src/core/TSchema.ts

@@ -280,10 +280,10 @@ export interface StructOptions {
  *
  * @since 2.0.0
  */
-export function Struct<Fields extends Schema.Struct.Fields>(
+export const Struct = <Fields extends Schema.Struct.Fields>(
   fields: Fields,
   options: StructOptions = {}
-): Struct<Fields> {
+): Struct<Fields> => {
   const { flatFields, flatInUnion, index = 0, tagField } = options
 
   // flatInUnion defaults to true when index is specified
@@ -325,9 +325,10 @@ export function Struct<Fields extends Schema.Struct.Fields>(
     encode: (encodedStruct) => {
       // encodedStruct is the result of Schema.Struct(fields), which has already transformed all fields
 
-      // Filter out the tag field if detected (it's metadata, not data)
-      const fieldEntries = Object.entries(encodedStruct).filter(([key]) => key !== detectedTagField)
-      const fieldValues = fieldEntries.map(([_, value]) => value) as ReadonlyArray<Data.Data>
+      // Use Object.keys(fields) to preserve schema definition order
+      // (Object.entries doesn't guarantee property order)
+      const orderedKeys = Object.keys(fields).filter((key) => key !== detectedTagField)
+      const fieldValues = orderedKeys.map((key) => encodedStruct[key as keyof typeof encodedStruct]) as ReadonlyArray<Data.Data>
 
       // Check if any field values are Constrs with flatFields:true
       // If so, spread their fields into this Struct's field array
@@ -793,24 +794,24 @@ export const Tuple = <Elements extends Schema.TupleType.Elements>(element: [...E
  * @since 2.0.0
  * @category constructors
  */
-export function Variant<const Variants extends Record<PropertyKey, Schema.Struct.Fields>>(
+export const Variant = <const Variants extends Record<PropertyKey, Schema.Struct.Fields>>(
   variants: Variants
 ): Union<
   ReadonlyArray<
     {
       [K in keyof Variants]: Struct<{ readonly [P in K]: Struct<Variants[K]> }>
     }[keyof Variants]
   >
-> {
+> => {
   return Union(
-    ...Object.entries(variants).map(([name, fields], index) =>
+    ...(Object.entries(variants).map(([name, fields], index) =>
       Struct(
         {
           [name]: Struct(fields, { flatFields: true })
         } as any,
         { flatInUnion: true, index }
       )
-    ) as any
+    ) as any)
   )
 }
 

packages/evolution/test/TSchema.test.ts

@@ -291,6 +291,135 @@ describe("TypeTaggedSchema Tests", () => {
         expect(encoded).toEqual("d87a80")
         expect(decoded).toBeNull()
       })
+
+      it("should preserve field order in structs with NullOr fields (regression test)", () => {
+        // Regression test for field ordering bug with NullOr/UndefinedOr
+        const CredentialSchema = TSchema.Union(
+          TSchema.Struct({ pubKeyHash: TSchema.ByteArray }, { flatFields: true }),
+          TSchema.Struct({ scriptHash: TSchema.ByteArray }, { flatFields: true })
+        )
+
+        const AddressSchema = TSchema.Struct({
+          paymentCredential: CredentialSchema,
+          stakeCredential: TSchema.NullOr(TSchema.Integer)
+        })
+
+        const input = {
+          paymentCredential: { pubKeyHash: fromHex("deadbeef") },
+          stakeCredential: null
+        }
+
+        const encoded = Data.withSchema(AddressSchema).toData(input)
+        const decoded = Data.withSchema(AddressSchema).fromData(encoded)
+
+        // Verify roundtrip
+        expect(decoded).toEqual(input)
+
+        // Verify field order in CBOR: paymentCredential should be field 0, stakeCredential field 1
+        expect(encoded.fields.length).toBe(2)
+        expect(encoded.fields[0]).toBeInstanceOf(Data.Constr) // paymentCredential
+        expect(encoded.fields[1]).toBeInstanceOf(Data.Constr) // stakeCredential (null)
+        expect((encoded.fields[1] as Data.Constr).index).toBe(1n) // null is Constr(1, [])
+      })
+
+      it("should preserve field order with multiple NullOr fields", () => {
+        const TestSchema = TSchema.Struct({
+          first: TSchema.Integer,
+          second: TSchema.NullOr(TSchema.ByteArray),
+          third: TSchema.Boolean,
+          fourth: TSchema.NullOr(TSchema.Integer)
+        })
+
+        const input = {
+          first: 100n,
+          second: fromHex("cafe"),
+          third: true,
+          fourth: null
+        }
+
+        const encoded = Data.withSchema(TestSchema).toData(input)
+        const decoded = Data.withSchema(TestSchema).fromData(encoded)
+
+        expect(decoded).toEqual(input)
+
+        // Verify field order
+        expect(encoded.fields[0]).toBe(100n) // first
+        expect(encoded.fields[1]).toBeInstanceOf(Data.Constr) // second (NullOr with value)
+        expect(encoded.fields[2]).toBeInstanceOf(Data.Constr) // third (Boolean)
+        expect(encoded.fields[3]).toBeInstanceOf(Data.Constr) // fourth (null)
+        expect((encoded.fields[3] as Data.Constr).index).toBe(1n) // null
+      })
+
+      it("should preserve field order with UndefinedOr fields", () => {
+        const TestSchema = TSchema.Struct({
+          first: TSchema.ByteArray,
+          second: TSchema.UndefinedOr(TSchema.Integer),
+          third: TSchema.Boolean
+        })
+
+        const inputWithValue = {
+          first: fromHex("deadbeef"),
+          second: 42n,
+          third: false
+        }
+
+        const encodedWithValue = Data.withSchema(TestSchema).toData(inputWithValue)
+        const decodedWithValue = Data.withSchema(TestSchema).fromData(encodedWithValue)
+
+        expect(decodedWithValue).toEqual(inputWithValue)
+
+        // Verify field order when value is present
+        expect(encodedWithValue.fields[0]).toBeInstanceOf(Uint8Array) // first
+        expect(encodedWithValue.fields[1]).toBeInstanceOf(Data.Constr) // second (UndefinedOr with value)
+        expect(encodedWithValue.fields[2]).toBeInstanceOf(Data.Constr) // third (Boolean)
+
+        const inputUndefined = {
+          first: fromHex("cafebabe"),
+          second: undefined,
+          third: true
+        }
+
+        const encodedUndefined = Data.withSchema(TestSchema).toData(inputUndefined)
+        const decodedUndefined = Data.withSchema(TestSchema).fromData(encodedUndefined)
+
+        expect(decodedUndefined).toEqual(inputUndefined)
+
+        // Verify field order when value is undefined
+        expect(encodedUndefined.fields[0]).toBeInstanceOf(Uint8Array) // first
+        expect(encodedUndefined.fields[1]).toBeInstanceOf(Data.Constr) // second (undefined)
+        expect((encodedUndefined.fields[1] as Data.Constr).index).toBe(1n) // undefined is Constr(1, [])
+        expect(encodedUndefined.fields[2]).toBeInstanceOf(Data.Constr) // third (Boolean)
+      })
+
+      it("should preserve field order with mixed NullOr and UndefinedOr fields", () => {
+        const TestSchema = TSchema.Struct({
+          a: TSchema.Integer,
+          b: TSchema.NullOr(TSchema.ByteArray),
+          c: TSchema.UndefinedOr(TSchema.Integer),
+          d: TSchema.Boolean
+        })
+
+        const input = {
+          a: 999n,
+          b: null,
+          c: undefined,
+          d: true
+        }
+
+        const encoded = Data.withSchema(TestSchema).toData(input)
+        const decoded = Data.withSchema(TestSchema).fromData(encoded)
+
+        expect(decoded).toEqual(input)
+
+        // Verify all fields are in correct order
+        expect(encoded.fields[0]).toBe(999n) // a
+        expect(encoded.fields[1]).toBeInstanceOf(Data.Constr) // b (null)
+        expect((encoded.fields[1] as Data.Constr).index).toBe(1n) // null
+        expect(encoded.fields[2]).toBeInstanceOf(Data.Constr) // c (undefined)
+        expect((encoded.fields[2] as Data.Constr).index).toBe(1n) // undefined
+        expect(encoded.fields[3]).toBeInstanceOf(Data.Constr) // d (Boolean)
+        expect((encoded.fields[3] as Data.Constr).index).toBe(1n) // true
+      })
     })
 
     describe("Literal Schema", () => {