Update docs and fix some errors in elm-pages run.

generator/src/cli.js

@@ -270,6 +270,7 @@ function generatorWrapperFile(moduleName) {
 
 import Bytes
 import DataSource exposing (DataSource)
+import Exception
 import Cli.Program as Program
 import Json.Decode as Decode
 import Json.Encode as Encode
@@ -277,7 +278,7 @@ import Pages.Internal.Platform.GeneratorApplication
 import ${moduleName}
 
 
-main : Program.StatefulProgram Pages.Internal.Platform.GeneratorApplication.Model Pages.Internal.Platform.GeneratorApplication.Msg (DataSource ()) Pages.Internal.Platform.GeneratorApplication.Flags
+main : Program.StatefulProgram Pages.Internal.Platform.GeneratorApplication.Model Pages.Internal.Platform.GeneratorApplication.Msg (DataSource Exception.Throwable ()) Pages.Internal.Platform.GeneratorApplication.Flags
 main =
     Pages.Internal.Platform.GeneratorApplication.app
         { data = ${moduleName}.run

src/DataSource.elm

@@ -5,7 +5,7 @@ module DataSource exposing
     , andThen, resolve, combine
     , andMap
     , map2, map3, map4, map5, map6, map7, map8, map9
-    , catch, mapError, onError, throw
+    , catch, throw, mapError, onError
     )
 
 {-| In an `elm-pages` app, each Route Module can define a value `data` which is a `DataSource` that will be resolved **before** `init` is called. That means it is also available
@@ -79,6 +79,11 @@ Any place in your `elm-pages` app where the framework lets you pass in a value o
 
 @docs map2, map3, map4, map5, map6, map7, map8, map9
 
+
+## Exception Handling
+
+@docs catch, throw, mapError, onError
+
 -}
 
 import Dict
@@ -281,6 +286,7 @@ andThen fn requestInfo =
                     )
 
 
+{-| -}
 onError : (error -> DataSource mappedError value) -> DataSource error value -> DataSource mappedError value
 onError fromError dataSource =
     case dataSource of
@@ -527,6 +533,7 @@ map9 combineFn request1 request2 request3 request4 request5 request6 request7 re
         |> map2 (|>) request9
 
 
+{-| -}
 catch : DataSource (Catchable error) value -> DataSource error value
 catch ds =
     ds
@@ -538,6 +545,7 @@ catch ds =
             )
 
 
+{-| -}
 throw : DataSource (Catchable error) data -> DataSource Throwable data
 throw dataSource =
     dataSource

src/DataSource/Env.elm

@@ -1,6 +1,6 @@
 module DataSource.Env exposing
     ( get, expect
-    , Error(..), toBuildError
+    , Error(..)
     )
 
 {-| Because DataSource's in `elm-pages` never run in the browser (see [the DataSource docs](DataSource)), you can access environment variables securely. As long as the environment variable isn't sent
@@ -29,9 +29,13 @@ down into the final `Data` value, it won't end up in the client!
 
 @docs get, expect
 
+
+## Errors
+
+@docs Error
+
 -}
 
-import BuildError exposing (BuildError)
 import DataSource exposing (DataSource)
 import DataSource.Http
 import DataSource.Internal.Request
@@ -40,6 +44,7 @@ import Json.Decode as Decode
 import Json.Encode as Encode
 
 
+{-| -}
 type Error
     = MissingEnvVariable String
 
@@ -58,11 +63,6 @@ get envVariableName =
         |> DataSource.onError (\_ -> DataSource.succeed Nothing)
 
 
-toBuildError : Error -> BuildError
-toBuildError (MissingEnvVariable errorName) =
-    BuildError.internal ("Missing environment variable from DataSource.Env.expect: `" ++ errorName ++ "`")
-
-
 {-| Get an environment variable, or a DataSource failure if there is no environment variable matching that name.
 -}
 expect : String -> DataSource (Catchable Error) String

src/DataSource/File.elm

@@ -1,7 +1,7 @@
 module DataSource.File exposing
     ( bodyWithFrontmatter, bodyWithoutFrontmatter, onlyFrontmatter
     , jsonFile, rawFile
-    , FileReadError(..), toBuildError
+    , FileReadError(..)
     )
 
 {-| This module lets you read files from the local filesystem as a [`DataSource`](DataSource#DataSource).
@@ -41,9 +41,13 @@ plain old JSON in Elm.
 
 @docs jsonFile, rawFile
 
+
+## Exceptions
+
+@docs FileReadError
+
 -}
 
-import BuildError exposing (BuildError)
 import DataSource exposing (DataSource)
 import DataSource.Http
 import DataSource.Internal.Request
@@ -147,6 +151,7 @@ bodyWithFrontmatter frontmatterDecoder filePath =
         )
 
 
+{-| -}
 type FileReadError decoding
     = FileDoesntExist
     | FileReadError String
@@ -263,12 +268,6 @@ rawFile filePath =
     read filePath (Decode.field "rawFile" Decode.string)
 
 
-toBuildError : FileReadError decodingError -> BuildError
-toBuildError error =
-    BuildError.internal
-        ("TODO - turn into a custom type variant of BuildError" ++ Debug.toString error)
-
-
 {-| Read a file as JSON.
 
 The Decode will strip off any unused JSON data.

src/Pages/Internal/Platform/GeneratorApplication.elm

@@ -11,6 +11,7 @@ import Cli.Program as Program exposing (FlagsIncludingArgv)
 import Codec
 import DataSource exposing (DataSource)
 import Dict
+import Exception exposing (Throwable)
 import HtmlPrinter
 import Json.Decode as Decode
 import Json.Encode
@@ -33,7 +34,7 @@ type alias Flags =
 
 {-| -}
 type alias Model =
-    { staticResponses : DataSource ()
+    { staticResponses : DataSource Throwable ()
     , errors : List BuildError
     , allRawResponses : RequestsAndPending
     , done : Bool
@@ -54,10 +55,10 @@ type Msg
 {-| -}
 app :
     GeneratorProgramConfig
-    -> Program.StatefulProgram Model Msg (DataSource ()) Flags
+    -> Program.StatefulProgram Model Msg (DataSource Throwable ()) Flags
 app config =
     let
-        cliConfig : Program.Config (DataSource ())
+        cliConfig : Program.Config (DataSource Throwable ())
         cliConfig =
             case config.data of
                 Pages.Internal.Script.Script theCliConfig ->
@@ -277,7 +278,7 @@ perform config effect =
 
 {-| -}
 init :
-    DataSource ()
+    DataSource Throwable ()
     -> FlagsIncludingArgv Flags
     -> ( Model, Effect )
 init execute flags =
@@ -315,12 +316,12 @@ init execute flags =
 
 
 initLegacy :
-    DataSource ()
+    DataSource Throwable ()
     -> { staticHttpCache : RequestsAndPending }
     -> ( Model, Effect )
 initLegacy execute { staticHttpCache } =
     let
-        staticResponses : DataSource ()
+        staticResponses : DataSource Throwable ()
         staticResponses =
             StaticResponses.renderApiRequest execute
 

src/Pages/Internal/Script.elm

@@ -2,6 +2,7 @@ module Pages.Internal.Script exposing (Script(..))
 
 import Cli.Program as Program
 import DataSource exposing (DataSource)
+import Exception exposing (Throwable)
 import Html exposing (Html)
 
 
@@ -12,5 +13,5 @@ type Script
           -> Html Never
           -> String
          )
-         -> Program.Config (DataSource ())
+         -> Program.Config (DataSource Throwable ())
         )

src/Pages/Script.elm

@@ -28,6 +28,7 @@ import Cli.Program as Program
 import DataSource exposing (DataSource)
 import DataSource.Http
 import DataSource.Internal.Request
+import Exception exposing (Catchable, Throwable)
 import Json.Decode as Decode
 import Json.Encode as Encode
 import Pages.Internal.Script
@@ -38,8 +39,13 @@ type alias Script =
     Pages.Internal.Script.Script
 
 
+type Error
+    = --TODO make more descriptive
+      FileWriteError
+
+
 {-| -}
-writeFile : { path : String, body : String } -> DataSource ()
+writeFile : { path : String, body : String } -> DataSource (Catchable Error) ()
 writeFile { path, body } =
     DataSource.Internal.Request.request
         { name = "write-file"
@@ -50,12 +56,14 @@ writeFile { path, body } =
                     , ( "body", Encode.string body )
                     ]
                 )
-        , expect = DataSource.Http.expectJson (Decode.succeed ())
+        , expect =
+            -- TODO decode possible error details here
+            DataSource.Http.expectJson (Decode.succeed ())
         }
 
 
 {-| -}
-log : String -> DataSource ()
+log : String -> DataSource error ()
 log message =
     DataSource.Internal.Request.request
         { name = "log"
@@ -70,7 +78,7 @@ log message =
 
 
 {-| -}
-withoutCliOptions : DataSource () -> Script
+withoutCliOptions : DataSource Throwable () -> Script
 withoutCliOptions execute =
     Pages.Internal.Script.Script
         (\_ ->
@@ -85,7 +93,7 @@ withoutCliOptions execute =
 
 
 {-| -}
-withCliOptions : Program.Config cliOptions -> (cliOptions -> DataSource ()) -> Script
+withCliOptions : Program.Config cliOptions -> (cliOptions -> DataSource Throwable ()) -> Script
 withCliOptions config execute =
     Pages.Internal.Script.Script
         (\_ ->