PureScript FFI and JavaScript Modules: Enforcing Type Contracts Across an Untyped Boundary

PureScript’s type checker validates PureScript modules, but the Foreign Function Interface treats imported JavaScript as opaque. A foreign import can declare a precise PureScript type while the underlying JavaScript returns null, undefined, or an unexpected object shape, and the compiler accepts the mismatch without complaint. The resulting failure appears only at runtime, making it difficult to trace deployment errors back to the boundary. Escape hatches such as unsafeCoerce and raw foreign imports deliberately permit this unchecked passage, reflecting a tension between ecosystem access and compile-time safety.

Compiler upgrades introduce additional uncertainty: generated JavaScript module formats and FFI file resolution rules have shifted across releases, so a project that builds correctly on one version may break after an upgrade. Because these behaviors are version-sensitive, verifying FFI modules across compiler releases is a practical concern. The unresolved question is where responsibility for correctness should reside when the compiler cannot inspect the JavaScript side.

What strategies exist for narrowing the gap between declared PureScript types and runtime JavaScript values at the FFI boundary? Are there compiler flags or library patterns that surface boundary violations earlier without abandoning the FFI entirely? How should teams design FFI modules to remain robust against version-sensitive changes in generated module formats?