# Foreign

- Package
- purescript-foreign
- Repository
- purescript/purescript-foreign

This module defines types and functions for working with *foreign*
data.

`ExceptT (NonEmptyList ForeignError) m`

is used in this library
to encode possible failures when dealing with foreign data.

The `Alt`

instance for `ExceptT`

allows us to accumulate errors,
unlike `Either`

, which preserves only the last error.

### #Foreign Source

`data Foreign`

A type for *foreign data*.

Foreign data is data from any external *unknown* or *unreliable*
source, for which it cannot be guaranteed that the runtime representation
conforms to that of any particular type.

Suitable applications of `Foreign`

are

- To represent responses from web services
- To integrate with external JavaScript libraries.

### #ForeignError Source

`data ForeignError`

A type for foreign type errors

#### Constructors

`ForeignError String`

`TypeMismatch String String`

`ErrorAtIndex Int ForeignError`

`ErrorAtProperty String ForeignError`

#### Instances

### #MultipleErrors Source

`type MultipleErrors = NonEmptyList ForeignError`

A type for accumulating multiple `ForeignError`

s.

### #F Source

`type F = Except MultipleErrors`

While this alias is not deprecated, it is recommended
that one use `Except (NonEmptyList ForeignError)`

directly
for all future usages rather than this type alias.

An error monad, used in this library to encode possible failures when dealing with foreign data.

The `Alt`

instance for `Except`

allows us to accumulate errors,
unlike `Either`

, which preserves only the last error.

### #unsafeToForeign Source

`unsafeToForeign :: forall a. a -> Foreign`

Coerce any value to the a `Foreign`

value.

This is considered unsafe as it's only intended to be used on primitive JavaScript types, rather than PureScript types. Exporting PureScript values via the FFI can be dangerous as they can be mutated by code outside the PureScript program, resulting in difficult to diagnose problems elsewhere.

### #unsafeFromForeign Source

`unsafeFromForeign :: forall a. Foreign -> a`

Unsafely coerce a `Foreign`

value.

### #unsafeReadTagged Source

`unsafeReadTagged :: forall m a. Monad m => String -> Foreign -> ExceptT (NonEmptyList ForeignError) m a`

Unsafely coerce a `Foreign`

value when the value has a particular `tagOf`

value.

### #isUndefined Source

`isUndefined :: Foreign -> Boolean`

Test whether a foreign value is undefined

### #readString Source

`readString :: forall m. Monad m => Foreign -> ExceptT (NonEmptyList ForeignError) m String`

Attempt to coerce a foreign value to a `String`

.

### #readChar Source

`readChar :: forall m. Monad m => Foreign -> ExceptT (NonEmptyList ForeignError) m Char`

Attempt to coerce a foreign value to a `Char`

.

### #readBoolean Source

`readBoolean :: forall m. Monad m => Foreign -> ExceptT (NonEmptyList ForeignError) m Boolean`

Attempt to coerce a foreign value to a `Boolean`

.

### #readNumber Source

`readNumber :: forall m. Monad m => Foreign -> ExceptT (NonEmptyList ForeignError) m Number`

Attempt to coerce a foreign value to a `Number`

.

### #readInt Source

`readInt :: forall m. Monad m => Foreign -> ExceptT (NonEmptyList ForeignError) m Int`

Attempt to coerce a foreign value to an `Int`

.

### #readArray Source

`readArray :: forall m. Monad m => Foreign -> ExceptT (NonEmptyList ForeignError) m (Array Foreign)`

Attempt to coerce a foreign value to an array.

### #readNull Source

`readNull :: forall m. Monad m => Foreign -> ExceptT (NonEmptyList ForeignError) m (Maybe Foreign)`

### #readUndefined Source

`readUndefined :: forall m. Monad m => Foreign -> ExceptT (NonEmptyList ForeignError) m (Maybe Foreign)`

### #readNullOrUndefined Source

`readNullOrUndefined :: forall m. Monad m => Foreign -> ExceptT (NonEmptyList ForeignError) m (Maybe Foreign)`

### #fail Source

`fail :: forall m a. Monad m => ForeignError -> ExceptT (NonEmptyList ForeignError) m a`

Throws a failure error in `ExceptT (NonEmptyList ForeignError) m`

.

- Modules
- Foreign
- Foreign.
Index - Foreign.
Keys