-- | This module defines an effect, actions and handlers for working

-- | with JavaScript exceptions.

module Effect.Exception

( Error

, error

, message

, name

, stack

, throwException

, catchException

, throw

, try

) where

import Prelude

import Effect (Effect)

import Data.Either (Either(..))

import Data.Maybe (Maybe(..))

-- | The type of JavaScript errors

foreign import data Error :: Type

instance showError :: Show Error where

show = showErrorImpl

foreign import showErrorImpl :: Error -> String

-- | Create a JavaScript error, specifying a message

foreign import error :: String -> Error

-- | Get the error message from a JavaScript error

foreign import message :: Error -> String

-- | Get the error name when defined, or fallback to 'Error'

foreign import name :: Error -> String

-- | Get the stack trace from a JavaScript error

stack :: Error -> Maybe String

stack = stackImpl Just Nothing

foreign import stackImpl

:: (forall a. a -> Maybe a)

-> (forall a. Maybe a)

-> Error

-> Maybe String

-- | Throw an exception

-- |

-- | For example:

-- |

-- | ```purescript

-- | main = do

-- | x <- readNumber

-- | when (x < 0) $ throwException $

-- | error "Expected a non-negative number"

-- | ```

foreign import throwException

:: forall a

. Error

-> Effect a

-- | Catch an exception by providing an exception handler.

-- |

-- | For example:

-- |

-- | ```purescript

-- | main = catchException Console.logShow do

-- | Console.log "Exceptions thrown in this block will be logged to the console"

-- | ```

foreign import catchException

:: forall a

. (Error -> Effect a)

-> Effect a

-> Effect a

-- | A shortcut allowing you to throw an error in one step. Defined as

-- | `throwException <<< error`.

throw :: forall a. String -> Effect a

throw = throwException <<< error

-- | Runs an Eff and returns eventual Exceptions as a `Left` value. If the

-- | computation succeeds the result gets wrapped in a `Right`.

-- |

-- | For example:

-- |

-- | ```purescript

-- | main :: Effect Unit

-- | main = do

-- | result <- try (readTextFile UTF8 "README.md")

-- | case result of

-- | Right lines ->

-- | Console.log ("README: \n" <> lines )

-- | Left error ->

-- | Console.error ("Couldn't open README.md. Error was: " <> show error)

-- | ```

try :: forall a. Effect a -> Effect (Either Error a)

try action = catchException (pure <<< Left) (Right <$> action)