Task

newtype Task x a

A Task x a represents an asynchronous computation that can either succeed with a value of type a, or fail with a value of type x.

If you're coming from Elm and it seems like a lot of the functions are missing, that's because their equivalents are hiding in the type class instances. They have been annotated below.

Instances

• Functor (Task x)

  Task.map -> map

• Apply (Task x)

  Task.mapN -> liftN

• Applicative (Task x)

  Task.succeed -> pure

  Task.sequence -> For this, we use the sequence function that is a member of the Traversable type class. Note: we are not using a Traversable instance of Task, we're using the Traversable instance of whatever we want to sequence over. So while Elm's Task.sequence only works over Lists, we can sequence over anything that has a Traversable instance.

• Bind (Task x)

  Task.andThen -> bind (the only difference is the order of the arguments)

• Monad (Task x)
• Alt (Task x)
• (Semigroup a) => Semigroup (Task x a)
• (Monoid a) => Monoid (Task x a)
• Bifunctor Task

  Task.mapError: lmap, which isn't a member of Bifunctor directly, but uses the Bifunctor instance.

• MonadEffect (Task x)
• MonadThrow x (Task x)

  Task.fail -> throwError

• MonadError x (Task x)
• Parallel (ParTask x) (Task x)

run :: forall a x. Task x a -> Effect Unit

Execute a task, disregarding its result.

type Callback a = a -> Effect Unit

capture :: forall a x. Callback (x \/ a) -> Task x a -> Effect Unit

Execute a task, capturing the result with an effectual function.

type Canceler = Effect Unit

This type alias is used to show the Effect Unit should be used to cancel a task. See makeTask for an example.

makeTask :: forall a x. (Callback a -> Callback x -> Effect Canceler) -> Task x a

To use makeTask, you need to create a function that takes a callback for both success and failure, and returns an effect that will cancel a task in the event of an error during parallel execution. If you do not need or do not care about cancelling a task, you can use pure $ pure unit.

Here is how you would make a simple waiting task using js-timers:

wait :: ∀ x. Int -> Task x Unit
wait ms =
  makeTask \aC _ -> do
    id <- setTimeout ms $ aC unit
    pure $ clearTimeout id

bindError :: forall a x y. Task x a -> (x -> Task y a) -> Task y a

Operator alias for Task.bindError (left-associative / precedence 1)

liftEither :: forall a x. Either x a -> Task x a

type ForeignCallback a = EffectFn1 a Unit

fromForeign :: forall x a. (ForeignCallback a -> ForeignCallback x -> Effect Canceler) -> Task x a

A convenience function for creating tasks from JavaScript functions that take callbacks.

// JavaScript
exports.waitImpl = ms => cb => () => {
    const id = setTimeout(cb, ms);
    return () => clearTimeout(id);
};

-- PureScript
foreign import waitImpl :: Int -> ForeignCallback Unit -> Effect Canceler

wait :: ∀ x. Int -> Task x Unit
wait ms = fromForeign \cb _ -> waitImpl ms cb

data Promise t0 t1

A type that represents JavaScript promises. Use this with the FFI and fromPromise to turn promises into tasks.

foreign import fetchImpl :: String -> Effect (Promise Error Json)

fromPromise :: forall x a. Effect (Promise x a) -> Task x a

A convenience function for creating tasks from JavaScript promises.

fetch :: String -> Task Error Json
fetch = fromPromise <<< fetchImpl

toPromise :: forall x a. Task x a -> Effect (Promise x a)

Turn Tasks into Promises so they can be used in normal JS code.

newtype ParTask x a

ParTask is the applicative that lets you run tasks in parallel via the parallel library.

You may not need to work with any ParTask values directly. One of the most useful functions parSequence, which can take an array of Task x a and executes them all in parallel, returning a Task x (Array a).

If tasks are executing in parallel via ParTask's Apply instance (as is the case with parSequence), when one of them fails, the cancelers are called for all the task that are currently running.

Instances

• Functor (ParTask x)
• Apply (ParTask x)
• Applicative (ParTask x)
• Alt (ParTask x)
• Parallel (ParTask x) (Task x)

throwError :: forall e m a. MonadThrow e m => e -> m a

lmap :: forall f a b c. Bifunctor f => (a -> b) -> f a c -> f b c

Map a function over the first type argument of a Bifunctor.