fix(xdr): widen equals() param so union-typed values compile (#1637)

Author: Ryang-21

.github/workflows/tests.yml

@@ -56,6 +56,13 @@ jobs:
         if: matrix.node-version == 22
         run: pnpm run docs:snippets:check
 
+      # Compile-time regression tests (test/types/): code that must typecheck
+      # against src/, e.g. equals() on union-typed XDR values (issue #1630).
+      # tsc output does not vary by Node version, so run once.
+      - name: Type Tests
+        if: matrix.node-version == 22
+        run: pnpm run test:types
+
   # Browser tests get their own job per transport rather than two steps in
   # `build_and_test`. Each pass loads the SDK source graph — ~470 unbundled
   # `src/xdr` modules — once per test file, across 220 files and two browsers.

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 A breaking change will get clearly marked in this log.
 
+## Unreleased
+
+### Fixed
+* `equals()` on XDR values is now callable from TypeScript on union types like `xdr.ScVal`, `xdr.TransactionEnvelope`, and `xdr.Memo` — which is what the SDK's accessors return ([#1630](https://github.com/stellar/js-stellar-sdk/issues/1630)). The parameter was typed as polymorphic `this`, which reduces to `never` on a union, so every call failed with TS2345 even though the runtime worked. The parameter is now `XdrValue`, so comparing two different XDR types compiles and returns `false`.
+
 ## [v17.0.0-rc.1](https://github.com/stellar/js-stellar-sdk/compare/v16.2.0...v17.0.0-rc.1)
 
 ### Breaking Changes

package.json

@@ -112,10 +112,11 @@
     "docs:site": "astro build && tsx scripts/build-md-siblings.ts",
     "docs:dev": "astro dev",
     "docs:preview": "astro preview",
-    "test": "pnpm run docs:snippets:check && pnpm run test:node && pnpm run test:node:axios && pnpm run test:integration && pnpm run test:browser",
+    "test": "pnpm run docs:snippets:check && pnpm run test:types && pnpm run test:node && pnpm run test:node:axios && pnpm run test:integration && pnpm run test:browser",
     "test:all": "pnpm run test:node && pnpm run test:node:axios && pnpm run test:integration && pnpm run test:guides && pnpm run test:browser && pnpm run test:e2e",
     "test:e2e": "./test/e2e/initialize.sh && vitest run --config config/vitest.config.e2e.ts --coverage",
     "test:node": "vitest run test/unit --config config/vitest.config.ts --coverage",
+    "test:types": "tsc -p test/types/tsconfig.json",
     "test:node:axios": "cross-env TRANSPORT=axios vitest run test/unit --config config/vitest.config.ts",
     "test:e2e:noeval": "NODE_OPTIONS=--disallow-code-generation-from-strings pnpm run test:e2e",
     "test:integration": "vitest run test/integration --config config/vitest.config.ts --coverage",

src/xdr/values/xdr-value.ts

@@ -83,7 +83,10 @@ export abstract class XdrValue {
     return this.toJson();
   }
 
-  equals(other: this): boolean {
+  // Widened to `XdrValue` (not `this`): polymorphic `this` in parameter
+  // position intersects a union's arms to `never`, making equals uncallable
+  // on union-typed values (ScVal, Memo, ...). Cross-type calls return false.
+  equals(other: XdrValue): boolean {
     if (this === other) return true;
     if (other == null || !(other instanceof XdrValue)) return false;
     if (this.constructor !== other.constructor) return false;

test/types/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  // Typechecks the compile-time regression tests in this directory against
+  // the SDK source (`pnpm test:types`). These files contain code that must
+  // compile — e.g. `equals()` on union-typed XDR values (issue #1630), which
+  // the emitted declarations once rejected while runtime behavior was fine.
+  // Extends the root build config so src typechecks under the same
+  // strictness it builds with.
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "declaration": false,
+    "emitDeclarationOnly": false,
+    "declarationDir": null,
+    "outDir": null,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "rootDir": "../../",
+    // Mirrors the root config's `types`: the class-XDR layer resolves
+    // `@stellar/js-xdr` types from the package itself, so listing the local
+    // `stellar__js-xdr` stub here would shadow them.
+    "types": ["node", "js-xdr-v4"],
+    "typeRoots": [
+      "../../types",
+      "../../node_modules/@types",
+      "../../node_modules"
+    ]
+  },
+  "include": ["**/*.ts"]
+}

test/types/xdr-equals.ts

@@ -0,0 +1,60 @@
+// Compile-time regression test for issue #1630: `XdrValue.equals` must be
+// callable on union-typed values. The signature was once `equals(other: this)`,
+// and polymorphic `this` in parameter position intersects a union's arms —
+// discriminated arms with conflicting `type` properties reduce to `never`, so
+// no argument compiled (TS2345) on any of the SDK's union types even though
+// the runtime was correct. This file only has to typecheck; it never runs.
+
+import type {
+  ScVal,
+  ScValU32,
+  TransactionEnvelope,
+  LedgerEntry,
+  LedgerEntryData,
+  Memo,
+  HostFunction,
+  SorobanCredentials,
+  InvokeContractArgs,
+} from "../../src/xdr/index.js";
+
+declare const scValA: ScVal;
+declare const scValB: ScVal;
+declare const envelopeA: TransactionEnvelope;
+declare const envelopeB: TransactionEnvelope;
+declare const ledgerEntryDataA: LedgerEntryData;
+declare const ledgerEntryDataB: LedgerEntryData;
+declare const memoA: Memo;
+declare const memoB: Memo;
+declare const hostFunctionA: HostFunction;
+declare const hostFunctionB: HostFunction;
+declare const credentialsA: SorobanCredentials;
+declare const credentialsB: SorobanCredentials;
+declare const structA: InvokeContractArgs;
+declare const structB: InvokeContractArgs;
+declare const singleArm: ScValU32;
+declare const ledgerEntry: LedgerEntry;
+
+export const results: boolean[] = [
+  // Union receiver and union argument, for every union named in the issue.
+  scValA.equals(scValB),
+  envelopeA.equals(envelopeB),
+  ledgerEntryDataA.equals(ledgerEntryDataB),
+  memoA.equals(memoB),
+  hostFunctionA.equals(hostFunctionB),
+  credentialsA.equals(credentialsB),
+
+  // Structs and single union arms keep working.
+  structA.equals(structB),
+  singleArm.equals(singleArm),
+
+  // Single arm against the full union, both directions.
+  singleArm.equals(scValA),
+  scValA.equals(singleArm),
+
+  // Cross-type comparison compiles and returns false at runtime.
+  scValA.equals(memoA),
+
+  // Union-typed property read — the real-world shape that surfaced the bug
+  // (no `const` annotation to narrow the union back to one arm).
+  ledgerEntry.data.equals(ledgerEntryDataA),
+];

test/unit/xdr/equals.test.ts

@@ -0,0 +1,63 @@
+// Runtime behavior of `XdrValue.equals`. The signature takes `XdrValue`
+// (not `this`) so it stays callable on union-typed values — see issue #1630
+// and test/types/xdr-equals.ts for the compile-time side. These tests pin the
+// runtime contract: structural comparison by encoded bytes, `false` for
+// mismatched types, and `false` (never a throw) for junk arguments.
+
+import { describe, it, expect } from "vitest";
+
+import {
+  ScVal,
+  Memo,
+  InvokeContractArgs,
+  ScAddress,
+  ContractId,
+} from "../../../src/xdr/index.js";
+
+describe("XdrValue.equals", () => {
+  it("returns true for structurally equal values", () => {
+    expect(ScVal.scvU32(7).equals(ScVal.scvU32(7))).toBe(true);
+  });
+
+  it("returns true for self-comparison", () => {
+    const value = ScVal.scvU32(7);
+    expect(value.equals(value)).toBe(true);
+  });
+
+  it("returns false for unequal values of the same type", () => {
+    expect(ScVal.scvU32(7).equals(ScVal.scvU32(8))).toBe(false);
+  });
+
+  it("returns false across arms of the same union", () => {
+    expect(ScVal.scvU32(7).equals(ScVal.scvBool(true))).toBe(false);
+  });
+
+  it("returns false across different XDR types", () => {
+    expect(ScVal.scvVoid().equals(Memo.memoNone())).toBe(false);
+  });
+
+  it("compares union-typed values (the issue #1630 shape)", () => {
+    const a: ScVal = ScVal.scvU32(7);
+    const b: ScVal = ScVal.scvU32(7);
+    expect(a.equals(b)).toBe(true);
+  });
+
+  it("works on structs, not just unions", () => {
+    const make = () =>
+      new InvokeContractArgs({
+        contractAddress: ScAddress.scAddressTypeContract(
+          new ContractId(new Uint8Array(32)),
+        ),
+        functionName: "hello",
+        args: [ScVal.scvU32(1)],
+      });
+    expect(make().equals(make())).toBe(true);
+  });
+
+  it("returns false for null and non-XdrValue arguments", () => {
+    const value = ScVal.scvU32(7);
+    expect(value.equals(null as unknown as ScVal)).toBe(false);
+    expect(value.equals(undefined as unknown as ScVal)).toBe(false);
+    expect(value.equals({} as ScVal)).toBe(false);
+  });
+});