A BackendTask represents data that will be gathered at build time. Multiple BackendTasks can be combined together using the mapN functions, very similar to how you can manipulate values with Json Decoders in Elm.

Transform a request into an arbitrary value. The same underlying task will be performed, but mapping allows you to change the resulting values by applying functions to the results.

import BackendTask exposing (BackendTask)
import BackendTask.Http
import FatalError exposing (FatalError)
import Json.Decode as Decode


starsMessage : BackendTask FatalError String
starsMessage =
    BackendTask.Http.getJson
        "https://api.github.com/repos/dillonkearns/elm-pages"
        (Decode.field "stargazers_count" Decode.int)
        |> BackendTask.map
            (\stars -> "⭐️ " ++ String.fromInt stars)
        |> BackendTask.allowFatal

This is useful for prototyping with some hardcoded data, or for having a view that doesn't have any BackendTask data.

import BackendTask exposing (BackendTask)


type alias RouteParams =
    { name : String }


pages : BackendTask error (List RouteParams)
pages =
    BackendTask.succeed [ { name = "elm-pages" } ]

Turn Ok into BackendTask.succeed and Err into BackendTask.fail.

Build off of the response from a previous BackendTask request to build a follow-up request. You can use the data from the previous response to build up the URL, headers, etc. that you send to the subsequent request.

import BackendTask exposing (BackendTask)
import BackendTask.Http
import FatalError exposing (FatalError)
import Json.Decode as Decode


licenseData : BackendTask FatalError String
licenseData =
    BackendTask.Http.getJson
        "https://api.github.com/repos/dillonkearns/elm-pages"
        (Decode.at [ "license", "url" ] Decode.string)
        |> BackendTask.andThen
            (\licenseUrl ->
                BackendTask.Http.getJson licenseUrl (Decode.field "description" Decode.string)
            )
        |> BackendTask.allowFatal

Helper to remove an inner layer of Request wrapping.

Turn a list of BackendTasks into a single one.

import BackendTask exposing (BackendTask)
import BackendTask.Http
import FatalError exposing (FatalError)
import Json.Decode as Decode


type alias Pokemon =
    { name : String
    , sprite : String
    }


pokemonDetailRequest : BackendTask FatalError (List Pokemon)
pokemonDetailRequest =
    BackendTask.Http.getJson
        "https://pokeapi.co/api/v2/pokemon/?limit=3"
        (Decode.field "results"
            (Decode.list
                (Decode.map2 Tuple.pair
                    (Decode.field "name" Decode.string)
                    (Decode.field "url" Decode.string)
                    |> Decode.map
                        (\( name, url ) ->
                            BackendTask.Http.getJson url
                                (Decode.at
                                    [ "sprites", "front_default" ]
                                    Decode.string
                                    |> Decode.map (Pokemon name)
                                )
                        )
                )
            )
        )
        |> BackendTask.andThen BackendTask.combine
        |> BackendTask.allowFatal

A helper for combining BackendTasks in pipelines.

Like map, but it takes in two BackendTasks.

import BackendTask exposing (BackendTask)
import BackendTask.Env as Env
import BackendTask.Http
import FatalError exposing (FatalError)
import Json.Decode as Decode


type alias Data =
    { pokemon : List String, envValue : Maybe String }


data : BackendTask FatalError Data
data =
    BackendTask.map2 Data
        (BackendTask.Http.getJson
            "https://pokeapi.co/api/v2/pokemon/?limit=100&offset=0"
            (Decode.field "results"
                (Decode.list (Decode.field "name" Decode.string))
            )
            |> BackendTask.allowFatal
        )
        (Env.get "HELLO")

Ignore any recoverable error data and propagate the FatalError. Similar to a Cmd in The Elm Architecture, a FatalError will not do anything except if it is returned at the top-level of your application. Read more in the FatalError docs.

Ignore the resulting value of the BackendTask.

Perform a List of BackendTasks with no output, one-by-one sequentially.

Same as sequence, except it ignores the resulting value of each BackendTask.

Perform a List of BackendTasks one-by-one sequentially. combine will perform them all in parallel, which is typically a better default when you aren't sure which you want.

Same as doEach, except it ignores the resulting value of each BackendTask.

If the condition is true, fail with the given FatalError. Otherwise, succeed with ().

inDir sets the working directory for a BackendTask. The working directory of a BackendTask will be used to resolve relative paths and is relevant for the following types of BackendTasks:

• Reading files (BackendTask.File)
• Running glob patterns (BackendTask.Glob)
• Executing shell commands (BackendTask.Stream.command) and Pages.Script.sh

See the BackendTask Context section for more about how setting context works.

For example, these two values will produce the same result:

import BackendTask.Glob as Glob


example1 : BackendTask error (List String)
example1 =
    Glob.fromString "src/**/*.elm"


example2 : BackendTask error (List String)
example2 =
    BackendTask.inDir "src" (Glob.fromString "**/*.elm")

You can also nest the working directory by using inDir multiple times:

import BackendTask.Glob as Glob


example3 : BackendTask error (List String)
example3 =
    BackendTask.map2
        (\routeModules specialModules ->
            { routeModules = routeModules
            , specialModules = specialModules
            }
        )
        (BackendTask.inDir "Route" (Glob.fromString "**/*.elm"))
        (Glob.fromString "*.elm")
        |> BackendTask.inDir "app"

The above example will list out files from app/Route/**/*.elm and app/*.elm because inDir "app" is applied to the BackendTask.map2 which combines together both of the Glob tasks.

inDir supports absolute paths. In this example, we apply a relative path on top of an absolute path, so the relative path will be resolved relative to the absolute path.

import BackendTask.Glob as Glob


example3 : BackendTask error (List String)
example3 =
    BackendTask.map2
        (\routeModules specialModules ->
            { routeModules = routeModules
            , specialModules = specialModules
            }
        )
        -- same as `Glob.fromString "/projects/my-elm-pages-blog/app/Route/**/*.elm"`
        (BackendTask.inDir "Route" (Glob.fromString "**/*.elm"))
        (Glob.fromString "*.elm")
        |> BackendTask.inDir "/projects/my-elm-pages-blog/app"

You can also use BackendTask.inDir ".." to go up a directory, or `BackendTask.inDir "../.." to go up two directories, etc.

Use of trailing slashes is optional and does not change the behavior of inDir. Leading slashes distinguish between absolute and relative paths, so BackendTask.inDir "./src" is exactly the same as BackendTask.inDir "src", etc.

Each level of nesting with inDir will resolve using NodeJS's path.resolve.

Sets the verbosity level to quiet in the context of the given BackendTask (including all nested BackendTasks and continuations within it).

This will turn off performance timing logs. It will also prevent shell commands from printing their output to the console when they are run (see BackendTask.Stream.command).