elm-typed-value

better 1-constructor types

Fundamental concepts are similar to Prior art:

A value is wrapped in the type Typed with a phantom tag.

A Typed ... Meters ... Float can't be called a Typed ... Kilos ... Float anymore!

For types with just 1 constructor with a value a Typed can be a good replacement.

type Special
    = Special Value

extract (Special value) =
    value

map alter (Special value) =
    Special (alter value)

--...

You get rid of writing and calling different mehods for those types:

naturalNumber |> NaturalNumber.toInt
height |> Meters.toFloat
oneWeight |> Kilos.map ((+) (Kilos.toFloat otherWeight))
if
    (oneHeight |> Meters.toFloat)
        > (otherHeight |> Meters.toFloat)
then

Do you really have to remind yourself every step that you're still operating on Meters or Kilos? With Typed:

val naturalNumber
val height
Typed.map2 (+) oneWeight otherWeight
if val2 (>) oneHeight otherHeight then

There are 2 kinds of Typed:

• Checked, if the type should only contain "validated" values

  module NaturalNumber exposing (NaturalNumber)
  
  type NaturalNumber =
      -- nobody outside this module can call this constructor
      NaturalNumber Int

  Creating & updating NaturalNumbers will only be possible inside that module.

• Tagged, if you want to write

  -- constructor can be used anywhere
  type Meters =
      Meters Float

  Users can update & create a new Meters everywhere

If you want users to access the value with val, use Public; use Internal to hide it from users.

examples

import val
    exposing
        ( Typed, Tagged, Public, Checked, Internal
        , tag, val, val2, isChecked
        )

Tagged + Public

type alias Pixels =
    Typed Tagged PixelsTag Public Int

type PixelsTag
    = Pixels Never

-- use a type annotation to say what the result is
ratio : Int -> Int -> ( Pixels, Pixels )
ratio w h =
    ( tag w, tag h )

-- annotate to say it's in Pixels
defaultWindowWidth : Pixels
defaultWindowWidth =
    Typed.map2 (+)
        (tag 700)
        (borderWidth |> Typed.map ((*) 2))

borderWidth : Pixels
borderWidth =
    tag 5

val defaultWindowWidth
--> 710

Checked + Public

module Even exposing
    ( Even, zero, two
    , multiply, add
    )

type alias Even =
    Typed Checked EvenTag Public Int

-- don't expose this
type EvenTag = Even

multiply : Int -> Even -> Even
multiply int =
    Typed.map ((*) int) >> isChecked Even

add : Even -> Even -> Even
add toAdd =
    Typed.map2 (+) toAdd >> isChecked Even

zero : Even
zero =
    tag 0 |> isChecked Even

two : Even
two =
    tag 2 |> isChecked Even

Then outside this module

cakeForEvenNumbers : Even -> Cake

cakeForEvenNumbers (tag 3)
--> compile-time error: isn't of type Typed ... Public ...

cakeForEvenNumbers
    (Even.two |> Even.multiply -5)
--> Cake

Checked + Internal

A validated value that can't be directly accessed by a user.

A module that only exposes randomly generated unique Ids:

module Id exposing (Id, random, toBytes, toString)

import Random

type alias Id =
    Typed Checked IdTag Internal String

type IdTag = Id

random : Random.Generator Id
random =
    Random.list 16 ({-...-})
        |> Random.map String.fromList
        |> Random.map (isChecked Id)

-- the API stays the same even if the implementation changes
toBytes --...
toString --...

No Id can be created outside this package!

Combined with Tagged + Internal

module Password exposing (UncheckedPassword, GoodPassword, isGood, toOnlyDots)

type alias Password goodOrUnchecked =
    Typed goodOrUnchecked PasswordTag Internal String

-- don't expose the tag
type PasswordTag
    = Password

type alias GoodPassword =
    Password Checked

type alias UncheckedPassword =
    Password Tagged


isGood :
    UncheckedPassword -> Result String GoodPassword
isGood passwordToTest =
    let
        passwordString =
            Typed.internal Password passwordToTest
    in
    if (passwordString |> String.length) < 10 then
        Err "Use at lest 10 letters & symbols."
    else if Set.member passwordString commonPasswords then
        Err "Choose a less common password."
    else
        Ok (passwordToTest |> isChecked Password)

commonPasswords =
    Set.fromList
        [ "password1234", "secret1234"
        , "c001_p4ssw0rd", "1234567890"
        --...
        ]

You can then decide that only a part of the information should be accessible.

-- doesn't expose too much information.
toOnlyDots : Password goodOrUnchecked -> String
toOnlyDots =
    Typed.internal Password
        >> String.length
        >> (\length ->
                List.repeat length '·'
                    |> String.fromList
           )

In another module

type alias Model =
    { passwordTypedIntoRegister : UncheckedPassword
        --cannot access the password the user typed
    , loggedIn : LoggedIn
    }

type LoggedIn
    = LoggedIn { userPassword : GoodPassword }
        --there can't be a user with an insecure password
    | NotLoggedIn


type Msg
    = PasswordTypedIntoRegisterChanged UncheckedPassword
    | Register GoodPassword

update msg model =
    case msg of
        PasswordTypedIntoRegisterChanged uncheckedPassword ->
            { model
              | passwordTypedIntoRegister = uncheckedPassword
            }
        
        Register goodPassword ->
            { model
                | passwordTypedIntoRegister = tag ""
                , loggedIn =
                    LoggedIn { userPassword = goodPassword }
            }

view { passwordTypedIntoRegister } =
    Html.div []
        [ Html.div [] [ Html.text "register" ]
        , Html.input
            [ onInput
                --not accessible from now on
                (tag >> PasswordTypedIntoRegisterChanged)
            , Html.value (Password.toOnlyDots passwordTypedIntoRegister)
            ]
            []
        , case Password.isGood passwordTypedIntoRegister of
            Ok goodPassword ->
                Html.button
                    [ onClick (Register goodPassword) ]
                    [ Html.text "Create account" ]
                
            Err message ->
                text message
        ]

leak (val passwordTypedIntoRegister)
-- or
leak (val userPassword)

→ compile-time error: Can't access the value inside a Internal.

When not to use Checked

There might be a type that can guarantee these promises even if created by users.

Example GoodPassword:

type alias GoodPassword howMuchLongerThan10 maxLength lengthMaybeN =
    Arr
        (In (Nat10Plus howMuchLongerThan10)
            maxLength
            lengthMaybeN
        )
        Char

Used: elm-bounded-array.

Prior art

This package wouldn't exist without a lot of inspiration from those packages.

• Punie/elm-id

especially

• joneshf/elm-tagged
• IzumiSy/elm-typed