Should we explain why `new` is effectful in the docs?

[BebeSparkelSparkel]

Quick question on the type of new. Why does it have the type new :: forall s. s -> Effect (Ref s) instead of new :: forall s. s -> Ref s? I see no effects happening in the code.

[hdgarrood]

Creating a Ref is effectful, because if new didn’t have that type it could be used to violate referential transparency. Consider:

let
  x = Ref.new “hi”
in
  Tuple x x

which in this hypothetical scenario would have the type Tuple (Ref String) (Ref String).

Comparing to the following:

Tuple (Ref.new “hi”) (Ref.new “hi”)

According to referential transparency these should be the same. They are not, however, because writing to one of the refs in the first tuple will also write to the other, whereas in the second case you have two distinct refs which can be updated independently of each other.

[hdgarrood]

Thoughts on mentioning this in the API docs?

[natefaubion]

Also note that without it, one can violate the type system by giving a ref a polymorphic type and specializing it after the fact.

example =
  let
    ref :: forall a. Ref (Maybe a)
    ref = Ref.new Nothing
  in
    Type (ref :: Ref (Maybe Int)) (ref :: Ref (Maybe String))

These refs now share the same reference, but I've ascribed them different types. See http://mlton.org/ValueRestriction. This happens frequently with the combination of referential values that have polymorphic entities. For example, when Elm supported referential Channels (pre 0.18), you could violate the type system in the same way. Monadic plumbing prevents this from happening. The best you could try to create is Ref (forall a. Maybe a) which you can't do anything with.