Upgrading from v0.29 to v0.30.0

This page lists every change in v0.30.0 that can affect code or a deploy that worked on v0.29.13. Each entry says what changed, the old code, and the new code.

v0.30.0 has no change that is loud only at run time. The full story of each change is in CHANGELOG.md under v0.30.0.

Loud (fails to compile, the error shows the fix)

New stdlib names

A bare name that two exposing (..) imports now both export is [E1012] ambiguous, and the error names both modules. The fix is the qualified name, or a narrower exposing list.

Task.timeout meets Error.timeout

Sky.Core.Task gains timeout (and remaining). Sky.Core.Error already exports the value timeout : Error. A program that imports both modules with exposing (..) and writes a bare timeout gets [E1012], and the error names both modules. Qualify the name: Error.timeout for the error value, Task.timeout ms task for the deadline.

Live.routeParam and Spa.routeParam meet App.routeParam

Std.Live and Std.Spa gain routeParam for a :param route, the name Std.App already uses. A program that imports two of these modules with exposing (..) and writes a bare routeParam gets [E1012], and the error names the modules. Qualify the name: App.routeParam, Live.routeParam or Spa.routeParam.

More new names meet your own names

v0.30.0 adds these exports, which can clash with a name that a project module exports:

A program that imports one of these modules and a project module that exports the same name, both with exposing (..), and writes the bare name gets [E1012] AMBIGUOUS NAME. v0.29.13 accepted it:

import Std.Sub exposing (..)
import Screen exposing (..)   -- Screen exports viewport : Int -> String

main =
    Log.info (viewport 3)

Qualify the name (Screen.viewport 3, or Sub.viewport for the subscription), or give one of the two imports an explicit exposing list (import Std.Sub exposing (Sub)).

An undefined type name is [E1001]

A type name that no module declares (a typo, or a type you removed) was accepted as an opaque type. An alias that held it compiled, and a use of it failed with a type mismatch far from the cause. The build now stops with [E1001] Undefined name: CardView at the name. Fix the name, or declare or import the type.

Program is one such name. A test file that wrote main : Program above main = Test.runMain tests now gets [E1001] Undefined name: Program. Write main : Task Error () instead.

A routed page has the model's page type

An app with App.withRoutes writes the routed page (and the App.withNotFound page) into its model's page field on every request. The checker did not compare the two types, so a program like this built and then answered 500 on every request (or, with two custom types of the same shape, crashed in the view):

type alias Model = { page : Route, title : String }

app =
    App.app { init = init, update = update, view = view, subscriptions = subs }
        |> App.withRoutes [ App.route "/" "home", App.routeParam "/item/:id" (\s -> "item:" ++ s) ]
        |> App.withNotFound "missing"

Such a program is now refused at App.withRoutes with [E2001] The app's pages have type String(from its routes, its NotFound page or itswithOnNavigatefunction), but the model'spagefield has typeRoute``. Make every route page and the NotFound page a value of the field's type (App.route "/" Dashboard, App.routeParam "/item/:id" Detail, App.withNotFound Missing), or give the field another name if it is not the app's page. A model with no page field is unchanged.

The check follows a helper that is generic in the model (withPages routes missing a = a |> App.withRoutes routes |> App.withNotFound missing): each caller is checked with its own model. This is true for a top-level helper and for a helper bound in a let (a function, a lambda, an alias of another helper, or a record field), at any depth.

The check also runs on the served app, and this is what makes it complete. At each use of App.run, App.serve and the target runners (runLive, runLiveWindow, runSpa, runTui, runCli, runWebview), the checker ties the served app's page type to its model's page field. The type of the served app carries the routes' page type through every helper, so any helper shape is covered: a helper hidden in a user custom type (type Router … = Router (App … -> App …)), in a record field of one, or in another module. A project module is app code whatever its name, so a helper in module Sky.Pages or module Std.Pages is checked the same way. Then the error points at App.run and says that the app is served there.

The check at the served app is decided for each top-level function that serves an app, not for each app and not for the whole program. A use of a runner is checked when the top-level function it is in reaches App.withRoutes or App.withOnNavigate (directly or through helpers it uses), or when such a function uses it (the app may be passed to it). Another entry of the project, another module or a helper that no such function uses does not change the verdict.

Where the served app can have routes or a navigation hook, the model type must be known where the app is served. A function that builds and serves an app with a model type it does not know is refused with [E2001] The routed page type of the app that is served here cannot be checked:

serve parts =
    App.app parts |> App.withRoutes routes |> App.withNotFound Missing |> App.run

Give it a type annotation with the model type, or serve the app where its model type is known (main = App.run app).

The navigation function gets the same rule. After each navigation the runtime gives the model's page field to the App.withOnNavigate function, with or without routes. So its argument must have the type of that field:

type alias Model = { page : Route, title : String }

app =
    App.app { init = init, update = update, view = view, subscriptions = subs }
        |> App.withNotFound { count = 1 }
        |> App.withOnNavigate (\r -> Go r.count)

Such a program built and then answered 500 on every request (rt.Coerce: expected struct { Count int }, got main.Main_Route_Detail_V). With an Int or a String argument it used a wrong value. It is now [E2001] at App.withOnNavigate. Make the argument a Route (App.withOnNavigate Navigated), or ignore it (App.withOnNavigate (\_ -> Cleared)). In such an app the App.withNotFound page must also have the field's type, with or without routes, and the model type must be known where the app is served.

A served app with no App.withRoutes and no App.withOnNavigate is unchanged when the function that serves it does not reach those builders and no function that reaches them uses it. Then the runtime does not read or write its model's page field, so that field and the App.withNotFound page may have any type. This is true also when another entry of the project (for example src/Admin.sky beside a routed src/Main.sky), another module or an unused helper sets routes or a navigation hook.

Because the check is decided for each function, a route-less app served in the same function as a routed app is checked as a routed one is. Its model's page field must have the type of its App.withNotFound page. v0.29.13 accepted this program, and it is now [E2001] at App.serve admin:

type alias AdminModel = { page : String, count : Int }

main =
    let
        site =
            App.app { init = init, update = update, view = view, subscriptions = \_ -> Sub.none }
                |> App.withRoutes [ App.route "/" Dashboard ]
                |> App.withNotFound Missing

        admin =
            App.app { init = adminInit, update = adminUpdate, view = adminView, subscriptions = \_ -> Sub.none }
                |> App.withNotFound 404
    in
    App.serve admin
        |> Task.andThen (\_ -> App.run site)

Moving admin into its own function (serveAdmin) does not change this while main uses that function, because main reaches App.withRoutes. Give the page field the NotFound page's type (page : Int), or give the field another name (screen : String) if it is not the app's page.

The raw APIs get the same rule. Std.Live.Route and Std.Spa.Route now take the page type (Route page):

The runtime also checks each page before it writes it into the model. This check is defence in depth only. A program that the checker accepts cannot give a page of the wrong type (to the model or to the navigation function), so such a page gets to the runtime only through a defect: a checker defect (before this release, a helper path that the checker did not follow, such as a let-bound helper or a helper in a custom type), or a Go binding whose Go value does not agree with its declared Sky type. Then the app stops at the first such request with the same [E2001] text, instead of a panic on every request. A program that passes sky check and then stops with this error shows a checker defect: report it.

A project module named Shared in a Sky.Spa app

The Sky.Spa split generates a module named Shared (Shared.sky) for the types and codecs that the client and the server both use. A project module with the same name would compete with it for one file. A Sky.Spa build that splits the app (for example --target web:app) with a module named Shared now stops with "cannot auto-split: the project module Shared has the name of a module the Sky.Spa split generates". Rename the module (for example to Contract), and change its module line and every import of it. An app that is not a Sky.Spa app is unchanged.

HttpRequest has a minRemaining field

Sky.Core.Http.HttpRequest gained minRemaining : Int, read by the new Http.withMinRemaining (a request refused before it is sent when too little time is left before a Task.timeout deadline). A request built with Http.defaultRequest and the with… builders compiles as it did. A request written as a full record literal is [E2001], naming the missing field.

Before:

{ method = "GET", url = u, body = "", headers = [], timeout = 30000, followRedirects = True, maxRedirects = 10 }

After:

{ method = "GET", url = u, body = "", headers = [], timeout = 30000, followRedirects = True, maxRedirects = 10, minRemaining = 0 }

0 keeps the old behaviour. Better still, start from Http.defaultRequest u.

Silent (compiles, behaves differently)

Added in v0.30.0

These are new features. Code that does not use them works as before, except where a bullet says otherwise.

Fixes in v0.30.0