Creates a Task encapsulating an invocation of a particular asyncronous JavaScript function. This function will usually be wrapped into a more specific one, which will partially apply it providing the encoder and the decoders but curry the last parameter, so that it could invoked where necessary as a args -> Task function.

Because interop calls can fail, produced task would likely need to be piped into a Task.attempt or handled further using Task.onError.

Here is a simple example that creates a Cmd invoking a registered JavaScript function called ping and produces a message GotPong with a Result, containing either an Ok variant with a string (determined by the first decoder argument), or an Err, containing a TaskPort.Error describing what went wrong.

type Msg = GotWidgetName (Result String String)


TaskPort.call "getWidgetNameByIndex" Json.Decode.string Json.Decode.string Json.Encode.int 0
    |> Task.attempt GotWidgetName

The Task abstraction allows to effectively compose chains of tasks without creating many intermediate variants in the Msg type, and designing the model to deal with partially completed call chain. The following example shows how this might be used when working with a hypothetical 'chatty' JavaScript API, requiring to call getWidgetsCount function to obtain a number of widgets, and then call getWidgetName with each widget's index to obtain its name.

type Msg = GotWidgets (Result String (List String))


TaskPort.callNoArgs "getWidgetsCount" Json.Decode.int Json.Decode.string
    |> Task.andThen
        (\count ->
            List.range 0 (count - 1)
                |> List.map Json.Encode.int
                |> List.map (TaskPort.call "getWidgetNameByIndex" Json.Decode.string Json.Decode.string)
                |> Task.sequence
        )
    |> Task.attempt GotWidgets

The resulting task has type Task (TaskPort.Error String) (List String), which could be attempted as a single command, which, if successful, provides a handy List String with all widget names.

Special version of the call that reduces amount of boilerplate code required when calling JavaScript functions that don't take any parameters. It is eqivalent of passing Json.Encoder.null into the call.

type Msg = GotWidgetsCount (Result String Int)


TaskPort.callNoArgs "getWidgetsCount" Json.Decode.int Json.Decode.string
    |> Task.attempt GotWidgetsCount

A structured error describing exactly how the interop call failed. You can use this to determine the best way to react to and recover from the problem.

CallError prefix is for errors explicitly sent from the JavaScript side. The error information will be specific to the interop use case, and it should be reconsituted from a JSON payload.

InteropError prefix is for the failures of the interop mechanism itself.

Subcategory of errors indicating a failure of the interop mechanism itself. These errors are generally not receoverable, but you can use them to allow the application to fail gracefully, or at least provide useful context for debugging.

This is an embedded tests suite allowing to test module-internal logic. No need to use this.