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

package/src/Exception.elm

@@ -0,0 +1,95 @@
+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.
+
+`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 =
+    Exception ()
+
+
+{-| -}
+type Exception error
+    = Exception error { title : String, body : String }
+
+
+{-| -}
+fromString : String -> Exception ()
+fromString string =
+    fromStringWithValue string ()
+
+
+{-| -}
+fromStringWithValue : String -> value -> Exception value
+fromStringWithValue string value =
+    Exception value { title = "Custom Error", body = string }
+
+
+{-| -}
+throw : Exception error -> Exception ()
+throw exception =
+    case exception of
+        Exception _ string ->
+            Exception () string
+
+
+{-| -}
+unwrap : Exception error -> error
+unwrap (Exception error _) =
+    error

package/src/Form.elm

@@ -23,7 +23,7 @@ module Form exposing
   - Showing validation errors on the client-side
   - Receiving a form submission on the server-side
   - Using the exact same client-side validations on the server-side
-  - Letting you run server-only Validations with DataSource's (things like checking for a unique username)
+  - Letting you run server-only Validations with BackendTask's (things like checking for a unique username)
 
 Because elm-pages is a framework, it has its own internal Model and Msg's. That means you, the user,
 can offload some of the responsibility to elm-pages and build an interactive form with real-time
@@ -64,7 +64,7 @@ them into a type and/or errors.
 
 Totally customizable. Uses [`Form.FieldView`](Form-FieldView) to render all of the fields declared.
 
-    import DataSource exposing (DataSource)
+    import BackendTask exposing (BackendTask)
     import ErrorPage exposing (ErrorPage)
     import Form
     import Form.Field as Field
@@ -184,7 +184,7 @@ Totally customizable. Uses [`Form.FieldView`](Form-FieldView) to render all of t
 
 ### Step 3 - Handle Server-Side Form Submissions
 
-    action : RouteParams -> Request.Parser (DataSource (Response ActionData ErrorPage))
+    action : RouteParams -> Request.Parser (BackendTask (Response ActionData ErrorPage))
     action routeParams =
         Request.formData [ signupForm ]
             |> Request.map
@@ -192,8 +192,8 @@ Totally customizable. Uses [`Form.FieldView`](Form-FieldView) to render all of t
                     case signupResult of
                         Ok newUser ->
                             newUser
-                                |> myCreateUserDataSource
-                                |> DataSource.map
+                                |> myCreateUserBackendTask
+                                |> BackendTask.map
                                     (\() ->
                                         -- redirect to the home page
                                         -- after successful sign-up
@@ -202,12 +202,12 @@ Totally customizable. Uses [`Form.FieldView`](Form-FieldView) to render all of t
 
                         Err _ ->
                             Route.redirectTo Route.Login
-                                |> DataSource.succeed
+                                |> BackendTask.succeed
                 )
 
-    myCreateUserDataSource : DataSource ()
-    myCreateUserDataSource =
-        DataSource.fail
+    myCreateUserBackendTask : BackendTask ()
+    myCreateUserBackendTask =
+        BackendTask.fail
             "TODO - make a database call to create a new user"
 
 
@@ -267,8 +267,9 @@ Totally customizable. Uses [`Form.FieldView`](Form-FieldView) to render all of t
 
 -}
 
-import DataSource exposing (DataSource)
+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 (DataSource (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 (DataSource (Validation.Validation error combined kind constraints)) kind constraints
+                    { combine : Validation.Validation error (BackendTask Throwable (Validation.Validation error combined kind constraints)) kind constraints
                     , view : viewFn
                     }
                 }
@@ -705,7 +706,7 @@ toServerForm (Form a b c) =
                         , combineAndView =
                             { combine =
                                 thing.combineAndView.combine
-                                    |> DataSource.succeed
+                                    |> BackendTask.succeed
                                     |> Validation.succeed2
                             , view = thing.combineAndView.view
                             }
@@ -1568,12 +1569,12 @@ initCombinedServer :
         Form
             error
             { combineAndView
-                | combine : Combined error (DataSource (Validation.Validation error parsed kind constraints))
+                | combine : Combined error (BackendTask backendTaskError (Validation.Validation error parsed kind constraints))
             }
             input
-    -> ServerForms error (DataSource (Validation.Validation error combined kind constraints))
+    -> ServerForms error (BackendTask backendTaskError (Validation.Validation error combined kind constraints))
 initCombinedServer mapFn serverForms =
-    initCombined (DataSource.map (Validation.map mapFn)) serverForms
+    initCombined (BackendTask.map (Validation.map mapFn)) serverForms
 
 
 {-| -}
@@ -1584,13 +1585,13 @@ combineServer :
             error
             { combineAndView
                 | combine :
-                    Combined error (DataSource (Validation.Validation error parsed kind constraints))
+                    Combined error (BackendTask backendTaskError (Validation.Validation error parsed kind constraints))
             }
             input
-    -> ServerForms error (DataSource (Validation.Validation error combined kind constraints))
-    -> ServerForms error (DataSource (Validation.Validation error combined kind constraints))
+    -> ServerForms error (BackendTask backendTaskError (Validation.Validation error combined kind constraints))
+    -> ServerForms error (BackendTask backendTaskError (Validation.Validation error combined kind constraints))
 combineServer mapFn a b =
-    combine (DataSource.map (Validation.map mapFn)) a b
+    combine (BackendTask.map (Validation.map mapFn)) a b
 
 
 {-| -}

package/src/Head.elm

@@ -15,18 +15,18 @@ when your page is pre-rendered (or server-rendered, in the case of your server-r
 which has some helper functions for defining OpenGraph and Twitter tags.
 
 One of the unique benefits of using `elm-pages` is that all of your routes (both pre-rendered and server-rendered) fully
-render the HTML of your page. That includes the full initial `view` (with the DataSource resolved, and the `Model` from `init`).
+render the HTML of your page. That includes the full initial `view` (with the BackendTask resolved, and the `Model` from `init`).
 The HTML response also includes all of the `Head` tags, which are defined in two places:
 
 1.  `app/Site.elm` - there is a `head` definition in `Site.elm` where you define global head tags that will be included on every rendered page.
 
-2.  In each Route Module - there is a `head` function where you have access to both the resolved `DataSource` and the `RouteParams` for the page and can return head tags based on that.
+2.  In each Route Module - there is a `head` function where you have access to both the resolved `BackendTask` and the `RouteParams` for the page and can return head tags based on that.
 
 Here is a common set of global head tags that we can define in `Site.elm`:
 
     module Site exposing (canonicalUrl, config)
 
-    import DataSource exposing (DataSource)
+    import BackendTask exposing (BackendTask)
     import Head
     import MimeType
     import SiteConfig exposing (SiteConfig)
@@ -37,7 +37,7 @@ Here is a common set of global head tags that we can define in `Site.elm`:
     , head = head
     }
 
-    head : DataSource (List Head.Tag)
+    head : BackendTask (List Head.Tag)
     head =
     [ Head.metaName "viewport" (Head.raw "width=device-width,initial-scale=1")
     , Head.metaName "mobile-web-app-capable" (Head.raw "yes")
@@ -49,13 +49,13 @@ Here is a common set of global head tags that we can define in `Site.elm`:
     , Head.appleTouchIcon (Just 180) (cloudinaryIcon MimeType.Png 180)
     , Head.appleTouchIcon (Just 192) (cloudinaryIcon MimeType.Png 192)
     ]
-    |> DataSource.succeed
+    |> BackendTask.succeed
 
-And here is a `head` function for a Route Module for a blog post. Note that we have access to our `DataSource` Data and
+And here is a `head` function for a Route Module for a blog post. Note that we have access to our `BackendTask` Data and
 are using it to populate article metadata like the article's image, publish date, etc.
 
     import Article
-    import DataSource
+    import BackendTask
     import Date
     import Head
     import Head.Seo

package/src/Internal/ApiRoute.elm

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

package/src/PageServerResponse.elm

@@ -15,7 +15,12 @@ type PageServerResponse data error
     | ErrorPage error { headers : List ( String, String ) }
 
 
-toRedirect : Response -> Maybe { statusCode : Int, location : String }
+toRedirect :
+    { response
+        | statusCode : Int
+        , headers : List ( String, String )
+    }
+    -> Maybe { statusCode : Int, location : String }
 toRedirect response =
     response.headers
         |> Dict.fromList