PureScript FFI and JavaScript module formats: verifying runtime representations across compiler versions

Direct answer

Validate at both boundaries, but for different reasons. Use Foreign readers inside PureScript wrappers to coerce values coming from JavaScript. Assert the shape of generated exports at the JavaScript import site because the compiler can change how records, constructors, and newtypes are emitted. Module format (CommonJS versus ES modules) is a separate resolution concern; pin it explicitly instead of relying on compiler defaults.

Confirmed facts versus likely explanation

Confirmed: foreign import erases PureScript types, so records, ADT constructors, and newtypes appear at runtime as plain objects, arrays, or functions. The Foreign library provides readers such as readNumber, readString, and readObject. Module format determines whether Node.js and bundlers resolve output with require or import, and defaults have shifted across PureScript releases.

Likely explanation: Surprising FFI layouts usually come from newtype erasure and recursive-type code generation, not from the module format itself. A module-format mismatch typically surfaces as a resolution or interop error—for example, require is not defined or an unexpected default export—rather than as a type error.

Steps for this case

1. Pin the PureScript compiler version and explicitly configure the module format for both Node.js and the browser bundler build. Do not mix compiler versions in the same build without testing each one.
2. Compile the same fixture with each target compiler version using identical module settings, then diff exported names and top-level structure.
3. In PureScript FFI wrappers, apply Foreign readers to every host value and turn read failures into explicit errors rather than letting invalid values propagate.
4. At the JavaScript import site, assert expected keys, function types, and constructor tags before calling exports, especially when the generated module may have been rebuilt with a different compiler version.
5. Run smoke tests under Node.js and the bundler configuration for each compiler version to confirm the emitted module format resolves without interop errors.

How module format affects the choice

It does not change whether to validate values; it changes which failure appears first. If the build switches from CommonJS to ES modules, an old JavaScript import site may break on resolution before any FFI value is inspected. Fix the module format and import interop first, then apply Foreign validation and JavaScript shape assertions.

Missing diagnostic

Are you seeing module-resolution errors such as require is not defined or unexpected default exports, or are values arriving with an unexpected runtime shape? That detail determines whether to fix module configuration or add Foreign validation first.

Assumptions: standard PureScript JavaScript code generation and the Foreign FFI library. Alternative codegen backends or FFI conventions may behave differently. Exact compiler flags and default module formats vary by release; verify against the installed version.