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

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 `Exception BackendTask.Port.Error` if it isn't found). In this example,
+we're using `BackendTask.throw` to let the framework treat that as an unexpected exception, but we could also handle the possible failures of the `Exception` (see [`Exception`](Exception)).
 
     import BackendTask exposing (BackendTask)
     import BackendTask.Port
     import Json.Encode
     import OptimizedDecoder as Decode
 
-    data : BackendTask String
+    data : BackendTask Throwable String
     data =
         BackendTask.Port.get "environmentVariable"
             (Json.Encode.string "EDITOR")
             Decode.string
+            |> BackendTask.throw
 
     -- 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,47 @@ 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.
 
-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.
+@docs Error
+
+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 Exception exposing (Exception)
+import Json.Decode as Decode exposing (Decoder)
+import Json.Encode as Encode
+import TerminalText
+
+
+{-| -}
+get : String -> Encode.Value -> Decoder b -> BackendTask.BackendTask (Exception Error) b
 get portName input decoder =
     BackendTask.Internal.Request.request
         { name = "port"
@@ -97,7 +101,7 @@ get portName input decoder =
                     |> Decode.andThen
                         (\errorKind ->
                             if errorKind == "PortNotDefined" then
-                                Exception.Catchable (PortNotDefined { name = portName })
+                                Exception.Exception (PortNotDefined { name = portName })
                                     { title = "Port Error"
                                     , body =
                                         [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I expected to find a port named `"
@@ -114,7 +118,7 @@ get portName input decoder =
                                     |> Decode.map (Maybe.withDefault "")
                                     |> Decode.map
                                         (\incorrectPortType ->
-                                            Exception.Catchable ExportIsNotFunction
+                                            Exception.Exception ExportIsNotFunction
                                                 { title = "Port Error"
                                                 , body =
                                                     [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I found an export called `"
@@ -127,7 +131,7 @@ get portName input decoder =
                                         )
 
                             else if errorKind == "MissingPortsFile" then
-                                Exception.Catchable MissingPortsFile
+                                Exception.Exception MissingPortsFile
                                     { 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."
@@ -142,7 +146,7 @@ get portName input decoder =
                                     |> Decode.map (Maybe.withDefault "")
                                     |> Decode.map
                                         (\errorMessage ->
-                                            Exception.Catchable
+                                            Exception.Exception
                                                 ErrorInPortsFile
                                                 { title = "Port Error"
                                                 , body =
@@ -154,26 +158,26 @@ get portName input decoder =
                                                 }
                                         )
 
-                            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)
+                                            Exception.Exception
+                                                (PortCallException portCallError)
                                                 { 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
                                                 }
                                         )
 
                             else
-                                Exception.Catchable ErrorInPortsFile
+                                Exception.Exception ErrorInPortsFile
                                     { title = "Port Error"
                                     , body =
                                         [ TerminalText.text "Something went wrong in a call to BackendTask.Port.get. I expected to find a port named `"
@@ -198,5 +202,5 @@ type Error
     | ErrorInPortsFile
     | MissingPortsFile
     | PortNotDefined { name : String }
-    | PortCallError Decode.Value
+    | PortCallException Decode.Value
     | ExportIsNotFunction

package/src/BackendTask.elm

@@ -86,7 +86,7 @@ Any place in your `elm-pages` app where the framework lets you pass in a value o
 
 -}
 
-import Exception exposing (Catchable(..), Throwable)
+import Exception exposing (Exception(..), Throwable)
 import Json.Encode
 import Pages.StaticHttpRequest exposing (RawRequest(..))
 
@@ -524,26 +524,26 @@ map9 combineFn request1 request2 request3 request4 request5 request6 request7 re
 
 
 {-| -}
-catch : BackendTask (Catchable error) value -> BackendTask error value
+catch : BackendTask (Exception error) value -> BackendTask error value
 catch ds =
     ds
         |> onError
             (\exception ->
                 case exception of
-                    Catchable error _ ->
+                    Exception error _ ->
                         fail error
             )
 
 
 {-| -}
-throw : BackendTask (Catchable error) data -> BackendTask Throwable data
+throw : BackendTask (Exception error) data -> BackendTask Throwable data
 throw backendTask =
     backendTask
         |> onError (Exception.throw >> fail)
 
 
 {-| -}
-toResult : BackendTask (Catchable error) data -> BackendTask noError (Result error data)
+toResult : BackendTask (Exception error) data -> BackendTask noError (Result error data)
 toResult backendTask =
     backendTask
         |> catch

package/src/Exception.elm

@@ -1,37 +1,95 @@
-module Exception exposing (Throwable, Catchable(..), fromString, fromStringWithValue, throw)
+module Exception exposing (Throwable, Exception(..), fromString, fromStringWithValue, throw, unwrap)
 
-{-|
+{-| 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.
 
-@docs Throwable, Catchable, fromString, fromStringWithValue, throw
+`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 `Exception`. 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 Exception.Throwable 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 Throwable Data
+    data routeParams =
+        BackendTask.Http.getJson "https://api.github.com/repos/dillonkearns/elm-pages"
+            (Decode.field "description" Decode.string)
+            |> BackendTask.onError
+                (\error ->
+                    case Exception.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 Throwable
+                                BackendTask.fail error |> BackendTask.throw
+
+                        _ ->
+                            BackendTask.fail error |> BackendTask.throw
+                )
+
+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 Throwable Data
+    data routeParams =
+        BackendTask.Http.getJson "https://api.github.com/repos/dillonkearns/elm-pages"
+            (Decode.field "description" Decode.string)
+            |> BackendTask.throw
+
+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 Throwable, Exception, fromString, fromStringWithValue, throw, unwrap
 
 -}
 
 
 {-| -}
 type alias Throwable =
-    Catchable ()
+    Exception ()
 
 
 {-| -}
-type Catchable error
-    = Catchable error { title : String, body : String }
+type Exception error
+    = Exception error { title : String, body : String }
 
 
 {-| -}
-fromString : String -> Catchable ()
+fromString : String -> Exception ()
 fromString string =
     fromStringWithValue string ()
 
 
 {-| -}
-fromStringWithValue : String -> value -> Catchable value
+fromStringWithValue : String -> value -> Exception value
 fromStringWithValue string value =
-    Catchable value { title = "Custom Error", body = string }
+    Exception value { title = "Custom Error", body = string }
 
 
 {-| -}
-throw : Catchable error -> Catchable ()
+throw : Exception error -> Exception ()
 throw exception =
     case exception of
-        Catchable _ string ->
-            Catchable () string
+        Exception _ string ->
+            Exception () string
+
+
+{-| -}
+unwrap : Exception error -> error
+unwrap (Exception error _) =
+    error

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 Exception exposing (Throwable)
 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 Throwable (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 Throwable (Validation.Validation error combined kind constraints)) kind constraints
                     , view : viewFn
                     }
                 }