A lot of JS functions accept and return records where some fields may be missing. For missing fields in argument records you can use Data.Options module. For missing fields in return records you can either use Foreign and write parsers, or this module and trust the foreign code.

A simple example of usage:

// Test.js
exports.typicalApi = function() {
  if (Math.random() > 0.5) {
    return {"numberData": 9431, "stringData": "atad"};
  } else {
    return {"numberData": 8752}

-- Test.purs
type ApiRet = {numberData :: Boolean, stringData :: UndefinedOr String}

foreign import typicalApi :: Effect ApiRet


result <- typicalApi
case fromUndefined result.stringData of
    Just data -> Console.log $ "got a string: " <> data
    Nothing   -> Console.log "no string"

You should avoid using this library whenever possible, as it's a shortcut: it lifts the neccessity of data validation from you, the ffi-bindings writer, to the user of your api. Also 75% of the use cases can be covered by clever use of typeclasses.

You should especially Not use this over Maybe.

#UndefinedOr Source

newtype UndefinedOr a

Wrapper for foreign values which may be undefined.

Caution: it may misbehave if the wrapped value is null or undefined.

All instances are the same as Maybe's instances. The missing Bind, Monad and other advanced ones are omitted on purpose. If you want to use them, run fromUndefined and use Maybe's instances.


#isUndefined Source

isUndefined :: forall a. UndefinedOr a -> Boolean

Check if the value is present

#fromUndefined Source

fromUndefined :: forall a. UndefinedOr a -> Maybe a

Convert to Maybe, returning Nothing if the value is missing

#toUndefined Source

toUndefined :: forall a. a -> UndefinedOr a

Wrap a value. Useful for equality checks with a foreign value without having to unwrap it.

Is a synonym for pure. Use that or this function based on the style preference or if the name will disambiguate intent.

#runUndefined Source

runUndefined :: forall b a. b -> (a -> b) -> UndefinedOr a -> b

Like maybe but for undefined