PureScript FFI ↔ JavaScript Promises: Automatic Conversion?

No automatic conversion exists

PureScript's foreign import does not automatically convert JavaScript Promises to Effect or an async monad. The compiler binds the JavaScript value directly and does not inspect runtime shapes. A Promise returned from an imported function remains a raw JavaScript object in your PureScript type system.

Why Effect cannot represent a Promise

Effect is synchronous. It models computations that complete before returning control to PureScript. A JavaScript Promise settles asynchronously, so mapping it to Effect a would require either blocking the JavaScript event loop (which PureScript cannot do) or returning before settlement. Neither is possible. The correct target is an asynchronous effect type, not Effect.

Confirmed facts vs. likely explanation

Confirmed: foreign import only binds a JavaScript value. The compiler does not inspect runtime shapes. A Promise is just a JS object, so the boundary must be typed explicitly, for example as returning Effect (Promise a).

Likely explanation: The absence of automatic conversion is deliberate. Automatic conversion would impose one global policy for rejection, cancellation, and laziness. JS rejection is not a PureScript exception; converting it to an async effect usually yields a generic error unless you wrap failures in Either or a custom error type.

Recommended approach

1. Import the JS function as returning Effect (Promise a) or Effect (Promise Foreign).
2. Convert explicitly with your async-effect library's Promise interop.
3. For typed failures, use the async effect's callback constructor to settle into Either e a.

Backward compatibility and future changes

If FFI later auto-converted, existing imports typed Effect (Promise a) and manual wrappers would change meaning or break. A typeclass or annotation could be added as a library convention, but it cannot be inferred safely without runtime tags and still needs explicit instances and an error policy.

One missing detail

Which async-effect library and helper names does your codebase use? The recommendation to keep the boundary raw and convert explicitly does not change, but the exact conversion code depends on which async monad you target.