elm-pages 3.0.0-beta.14 → 3.0.0-beta.16

package/src/BackendTask/Port.elm

@@ -3,47 +3,36 @@ module BackendTask.Port exposing
     , Error(..)
     )
 
-{-|
-
-@docs get
-
-@docs Error
-
--}
-
-import BackendTask
-import BackendTask.Http
-import BackendTask.Internal.Request
-import Exception exposing (Catchable)
-import Json.Decode as Decode exposing (Decoder)
-import Json.Encode as Encode
-import TerminalText
+{-| In a vanilla Elm application, ports let you either send or receive JSON data between your Elm application and the JavaScript context in the user's browser at runtime.
 
+With `BackendTask.Port`, you send and receive JSON to JavaScript running in NodeJS. As with any `BackendTask`, Port BackendTask's are either run at build-time (for pre-rendered routes) or at request-time (for server-rendered routes). See [`BackendTask`](BackendTask) for more about the
+lifecycle of `BackendTask`'s.
 
-{-| In a vanilla Elm application, ports let you either send or receive JSON data between your Elm application and the JavaScript context in the user's browser at runtime.
+This means that you can call shell scripts, run NPM packages that are installed, or anything else you could do with NodeJS to perform custom side-effects, get some data, or both.
 
-With `BackendTask.Port`, you send and receive JSON to JavaScript running in NodeJS during build-time. This means that you can call shell scripts, or run NPM packages that are installed, or anything else you could do with NodeJS.
+A `BackendTask.Port` will call an async JavaScript function with the given name from the definition in a file called `port-data-source.js` in your project's root directory. The function receives the input JSON value, and the Decoder is used to decode the return value of the async function.
 
-A `BackendTask.Port` will call an async JavaScript function with the given name. The function receives the input JSON value, and the Decoder is used to decode the return value of the async function.
+@docs get
 
-Here is the Elm code and corresponding JavaScript definition for getting an environment variable (or a build error if it isn't found).
+Here is the Elm code and corresponding JavaScript definition for getting an environment variable (or an `FatalError BackendTask.Port.Error` if it isn't found). In this example,
+we're using `BackendTask.allowFatal` to let the framework treat that as an unexpected exception, but we could also handle the possible failures of the `FatalError` (see [`FatalError`](FatalError)).
 
     import BackendTask exposing (BackendTask)
     import BackendTask.Port
     import Json.Encode
     import OptimizedDecoder as Decode
 
-    data : BackendTask String
+    data : BackendTask FatalError String
     data =
         BackendTask.Port.get "environmentVariable"
             (Json.Encode.string "EDITOR")
             Decode.string
+            |> BackendTask.allowFatal
 
     -- will resolve to "VIM" if you run `EDITOR=vim elm-pages dev`
 
 ```javascript
-const kleur = require("kleur");
-
+// port-data-source.js
 
 module.exports =
   /**
@@ -56,32 +45,51 @@ module.exports =
       if (result) {
         return result;
       } else {
-        throw `No environment variable called ${kleur
-          .yellow()
-          .underline(name)}\n\nAvailable:\n\n${Object.keys(process.env).join(
-          "\n"
-        )}`;
+        throw `No environment variable called ${name}
+
+Available:
+
+${Object.keys(process.env).join("\n")}
+`;
       }
     },
   }
 ```
 
 
-## Error Handling
+## Performance
 
-`port-data-source.js`
+As with any JavaScript or NodeJS code, avoid doing blocking IO operations. For example, avoid using `fs.readFileSync`, because blocking IO can slow down your elm-pages builds and dev server. `elm-pages` performances all `BackendTask`'s in parallel whenever possible.
+So if you do `BackendTask.map2 Tuple.pair myHttpBackendTask myPortBackendTask`, it will resolve those two in parallel. NodeJS performs best when you take advantage of its ability to do non-blocking I/O (file reads, HTTP requests, etc.). If you use `BackendTask.andThen`,
+it will need to resolve them in sequence rather than in parallel, but it's still best to avoid blocking IO operations in your BackendTask Port definitions.
 
-Any time you throw an exception from a BackendTask.Port definition, it will result in a build error in your `elm-pages build` or dev server. In the example above, if the environment variable
-is not found it will result in a build failure. Notice that the NPM package `kleur` is being used in this example to add color to the output for that build error. You can use any tool you
-prefer to add ANSI color codes within the error string in an exception and it will show up with color output in the build output and dev server.
 
+## Error Handling
 
-## Performance
+There are a few different things that can go wrong when running a port-data-source. These possible errors are captured in the `BackendTask.Port.Error` type.
+
+@docs Error
 
-As with any JavaScript or NodeJS code, avoid doing blocking IO operations. For example, avoid using `fs.readFileSync`, because blocking IO can slow down your elm-pages builds and dev server.
+Any time you throw a JavaScript exception from a BackendTask.Port definition, it will give you a `PortCallException`. It's usually easier to add a `try`/`catch` in your JavaScript code in `port-data-source.js`
+to handle possible errors, but you can throw a JSON value and handle it in Elm in the `PortCallException` call error.
 
 -}
-get : String -> Encode.Value -> Decoder b -> BackendTask.BackendTask (Catchable Error) b
+
+import BackendTask
+import BackendTask.Http
+import BackendTask.Internal.Request
+import FatalError exposing (FatalError, Recoverable)
+import Json.Decode as Decode exposing (Decoder)
+import Json.Encode as Encode
+import TerminalText
+
+
+{-| -}
+get :
+    String
+    -> Encode.Value
+    -> Decoder b
+    -> BackendTask.BackendTask { fatal : FatalError, recoverable : Error } b
 get portName input decoder =
     BackendTask.Internal.Request.request
         { name = "port"
@@ -97,7 +105,7 @@ get portName input decoder =
                     |> Decode.andThen
                         (\errorKind ->
                             if errorKind == "PortNotDefined" then
-                                Exception.Catchable (PortNotDefined { name = portName })
+                                FatalError.recoverable
                                     { title = "Port Error"
                                     , body =
                                         [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I expected to find a port named `"
@@ -106,6 +114,7 @@ get portName input decoder =
                                         ]
                                             |> TerminalText.toString
                                     }
+                                    (PortNotDefined { name = portName })
                                     |> Decode.succeed
 
                             else if errorKind == "ExportIsNotFunction" then
@@ -114,7 +123,7 @@ get portName input decoder =
                                     |> Decode.map (Maybe.withDefault "")
                                     |> Decode.map
                                         (\incorrectPortType ->
-                                            Exception.Catchable ExportIsNotFunction
+                                            FatalError.recoverable
                                                 { title = "Port Error"
                                                 , body =
                                                     [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I found an export called `"
@@ -124,16 +133,18 @@ get portName input decoder =
                                                     ]
                                                         |> TerminalText.toString
                                                 }
+                                                ExportIsNotFunction
                                         )
 
                             else if errorKind == "MissingPortsFile" then
-                                Exception.Catchable MissingPortsFile
+                                FatalError.recoverable
                                     { title = "Port Error"
                                     , body =
                                         [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I couldn't find your port-data-source file. Be sure to create a 'port-data-source.ts' or 'port-data-source.js' file."
                                         ]
                                             |> TerminalText.toString
                                     }
+                                    MissingPortsFile
                                     |> Decode.succeed
 
                             else if errorKind == "ErrorInPortsFile" then
@@ -142,8 +153,7 @@ get portName input decoder =
                                     |> Decode.map (Maybe.withDefault "")
                                     |> Decode.map
                                         (\errorMessage ->
-                                            Exception.Catchable
-                                                ErrorInPortsFile
+                                            FatalError.recoverable
                                                 { title = "Port Error"
                                                 , body =
                                                     [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I couldn't import the port definitions file, because of this exception:\n\n"
@@ -152,28 +162,29 @@ get portName input decoder =
                                                     ]
                                                         |> TerminalText.toString
                                                 }
+                                                ErrorInPortsFile
                                         )
 
-                            else if errorKind == "PortCallError" then
+                            else if errorKind == "PortCallException" then
                                 Decode.field "error" Decode.value
                                     |> Decode.maybe
                                     |> Decode.map (Maybe.withDefault Encode.null)
                                     |> Decode.map
                                         (\portCallError ->
-                                            Exception.Catchable
-                                                (PortCallError portCallError)
+                                            FatalError.recoverable
                                                 { title = "Port Error"
                                                 , body =
-                                                    [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I couldn't import the port definitions file, because of this exception:\n\n"
+                                                    [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I was able to import the port definitions file, but when running it I encountered this exception:\n\n"
                                                     , TerminalText.red (Encode.encode 2 portCallError)
-                                                    , TerminalText.text "\n\nAre there syntax errors or exceptions thrown during import?"
+                                                    , TerminalText.text "\n\nYou could add a `try`/`catch` in your `port-data-source` JavaScript code to handle that error."
                                                     ]
                                                         |> TerminalText.toString
                                                 }
+                                                (PortCallException portCallError)
                                         )
 
                             else
-                                Exception.Catchable ErrorInPortsFile
+                                FatalError.recoverable
                                     { title = "Port Error"
                                     , body =
                                         [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I expected to find a port named `"
@@ -182,6 +193,7 @@ get portName input decoder =
                                         ]
                                             |> TerminalText.toString
                                     }
+                                    ErrorInPortsFile
                                     |> Decode.succeed
                         )
                     |> Decode.map Err
@@ -198,5 +210,5 @@ type Error
     | ErrorInPortsFile
     | MissingPortsFile
     | PortNotDefined { name : String }
-    | PortCallError Decode.Value
+    | PortCallException Decode.Value
     | ExportIsNotFunction

package/src/BackendTask.elm

@@ -5,7 +5,7 @@ module BackendTask exposing
     , andThen, resolve, combine
     , andMap
     , map2, map3, map4, map5, map6, map7, map8, map9
-    , catch, throw, mapError, onError, toResult
+    , allowFatal, mapError, onError, toResult
     )
 
 {-| In an `elm-pages` app, each Route Module can define a value `data` which is a `BackendTask` that will be resolved **before** `init` is called. That means it is also available
@@ -80,13 +80,13 @@ 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
+## FatalError Handling
 
-@docs catch, throw, mapError, onError, toResult
+@docs allowFatal, mapError, onError, toResult
 
 -}
 
-import Exception exposing (Catchable(..), Throwable)
+import FatalError exposing (FatalError)
 import Json.Encode
 import Pages.StaticHttpRequest exposing (RawRequest(..))
 
@@ -524,28 +524,14 @@ map9 combineFn request1 request2 request3 request4 request5 request6 request7 re
 
 
 {-| -}
-catch : BackendTask (Catchable error) value -> BackendTask error value
-catch ds =
-    ds
-        |> onError
-            (\exception ->
-                case exception of
-                    Catchable error _ ->
-                        fail error
-            )
-
-
-{-| -}
-throw : BackendTask (Catchable error) data -> BackendTask Throwable data
-throw backendTask =
-    backendTask
-        |> onError (Exception.throw >> fail)
+allowFatal : BackendTask { error | fatal : FatalError } data -> BackendTask FatalError data
+allowFatal backendTask =
+    mapError .fatal backendTask
 
 
 {-| -}
-toResult : BackendTask (Catchable error) data -> BackendTask noError (Result error data)
+toResult : BackendTask error data -> BackendTask noError (Result error data)
 toResult backendTask =
     backendTask
-        |> catch
         |> andThen (Ok >> succeed)
         |> onError (Err >> succeed)

package/src/FatalError.elm

@@ -0,0 +1,101 @@
+module FatalError exposing
+    ( FatalError, fromString, recoverable
+    , Recoverable
+    )
+
+{-| The Elm language doesn't have the concept of exceptions or special control flow for errors. It just has
+Custom Types, and by convention types like `Result` and the `Err` variant are used to represent possible failure states
+and combine together different error states.
+
+`elm-pages` doesn't change that, Elm still doesn't have special exception control flow at the language level. It does have
+a type, which is just a regular old Elm type, called `FatalError`. Why? Because this plain old Elm type does have one
+special characteristic - the `elm-pages` framework knows how to turn it into an error message. This becomes interesting
+because an `elm-pages` app has several places that accept a value of type `BackendTask FatalError.FatalError value`.
+This design lets the `elm-pages` framework do some of the work for you.
+
+For example, if you wanted to handle possible errors to present them to the user
+
+    type alias Data =
+        String
+
+    data : RouteParams -> BackendTask FatalError Data
+    data routeParams =
+        BackendTask.Http.getJson "https://api.github.com/repos/dillonkearns/elm-pages"
+            (Decode.field "description" Decode.string)
+            |> BackendTask.onError
+                (\error ->
+                    case FatalError.unwrap error of
+                        BackendTask.Http.BadStatus metadata string ->
+                            if metadata.statusCode == 401 || metadata.statusCode == 403 || metadata.statusCode == 404 then
+                                BackendTask.succeed "Either this repo doesn't exist or you don't have access to it."
+
+                            else
+                                -- we're only handling these expected error cases. In the case of an HTTP timeout,
+                                -- we'll let the error propagate as a FatalError
+                                BackendTask.fail error |> BackendTask.allowFatal
+
+                        _ ->
+                            BackendTask.fail error |> BackendTask.allowFatal
+                )
+
+This can be a lot of work for all possible errors, though. If you don't expect this kind of error (it's an _exceptional_ case),
+you can let the framework handle it if the error ever does unexpectedly occur.
+
+    data : RouteParams -> BackendTask FatalError Data
+    data routeParams =
+        BackendTask.Http.getJson "https://api.github.com/repos/dillonkearns/elm-pages"
+            (Decode.field "description" Decode.string)
+            |> BackendTask.allowFatal
+
+This is especially useful for pages generated at build-time (`RouteBuilder.preRender`) where you want the build
+to fail if anything unexpected happens. With pre-rendered routes, you know that these error cases won't
+be seen by users, so it's often a great idea to just let the framework handle these unexpected errors so a developer can
+debug them and see what went wrong. In the example above, maybe we are only pre-rendering pages for a set of known
+GitHub Repositories, so a Not Found or Unauthorized HTTP error would be unexpected and should stop the build so we can fix the
+issue.
+
+In the case of server-rendered Routes (`RouteBuilder.serverRender`), `elm-pages` will show your 500 error page
+when these errors occur.
+
+@docs FatalError, fromString, recoverable
+
+@docs Recoverable
+
+-}
+
+import Pages.Internal.FatalError
+
+
+{-| -}
+type alias Recoverable error =
+    { fatal : FatalError
+    , recoverable : error
+    }
+
+
+{-| -}
+type alias FatalError =
+    Pages.Internal.FatalError.FatalError
+
+
+{-| -}
+build : { title : String, body : String } -> FatalError
+build info =
+    Pages.Internal.FatalError.FatalError info
+
+
+{-| -}
+fromString : String -> FatalError
+fromString string =
+    build
+        { title = "Custom Error"
+        , body = string
+        }
+
+
+{-| -}
+recoverable : { title : String, body : String } -> value -> Recoverable value
+recoverable info value =
+    { fatal = build info
+    , recoverable = value
+    }

package/src/Form.elm

@@ -269,6 +269,7 @@ Totally customizable. Uses [`Form.FieldView`](Form-FieldView) to render all of t
 
 import BackendTask exposing (BackendTask)
 import Dict exposing (Dict)
+import FatalError exposing (FatalError)
 import Form.Field as Field exposing (Field(..))
 import Form.FieldStatus as FieldStatus exposing (FieldStatus)
 import Form.FieldView
@@ -681,7 +682,7 @@ toServerForm :
     ->
         Form
             error
-            { combine : Validation.Validation error (BackendTask backendTaskError (Validation.Validation error combined kind constraints)) kind constraints
+            { combine : Validation.Validation error (BackendTask FatalError (Validation.Validation error combined kind constraints)) kind constraints
             , view : viewFn
             }
             data
@@ -694,7 +695,7 @@ toServerForm (Form a b c) =
                 { result : Dict String (List error)
                 , isMatchCandidate : Bool
                 , combineAndView :
-                    { combine : Validation.Validation error (BackendTask backendTaskError (Validation.Validation error combined kind constraints)) kind constraints
+                    { combine : Validation.Validation error (BackendTask FatalError (Validation.Validation error combined kind constraints)) kind constraints
                     , view : viewFn
                     }
                 }

package/src/Internal/ApiRoute.elm

@@ -9,7 +9,7 @@ module Internal.ApiRoute exposing
     )
 
 import BackendTask exposing (BackendTask)
-import Exception exposing (Throwable)
+import FatalError exposing (FatalError)
 import Head
 import Json.Decode
 import Pattern exposing (Pattern)
@@ -46,12 +46,12 @@ tryMatchDone path (ApiRoute handler) =
 type ApiRoute response
     = ApiRoute
         { regex : Regex
-        , matchesToResponse : Json.Decode.Value -> String -> BackendTask Throwable (Maybe response)
-        , buildTimeRoutes : BackendTask Throwable (List String)
-        , handleRoute : String -> BackendTask Throwable Bool
+        , matchesToResponse : Json.Decode.Value -> String -> BackendTask FatalError (Maybe response)
+        , buildTimeRoutes : BackendTask FatalError (List String)
+        , handleRoute : String -> BackendTask FatalError Bool
         , pattern : Pattern
         , kind : String
-        , globalHeadTags : Maybe (BackendTask Throwable (List Head.Tag))
+        , globalHeadTags : Maybe (BackendTask FatalError (List Head.Tag))
         }