Add coerced (#140)

Author: ozkutuk

CHANGELOG.md

@@ -7,6 +7,7 @@ Notable changes to this project are documented in this file. The format is based
 Breaking changes:
 
 New features:
+- Add `coerced` (#140 by @ozkutuk)
 - Add `sans` and `both` (#97 by @xgrommx)
 
 Bugfixes:

spago.dhall

@@ -22,6 +22,7 @@
   , "profunctor"
   , "psci-support"
   , "record"
+  , "safe-coerce"
   , "transformers"
   , "tuples"
   ]

src/Data/Lens/Iso.purs

@@ -13,6 +13,7 @@ module Data.Lens.Iso
   , flipped
   , mapping
   , dimapping
+  , coerced
   , module Data.Lens.Types
   ) where
 
@@ -23,6 +24,7 @@ import Data.Maybe (Maybe(..), fromMaybe)
 import Data.Newtype (unwrap)
 import Data.Profunctor (class Profunctor, dimap, rmap)
 import Data.Tuple (Tuple, curry, uncurry)
+import Safe.Coerce (class Coercible, coerce)
 
 -- | Create an `Iso` from a pair of morphisms.
 iso :: forall s t a b. (s -> a) -> (b -> t) -> Iso s t a b
@@ -84,3 +86,18 @@ dimapping
   -> AnIso ss tt aa bb
   -> Iso (p a ss) (q b tt) (p s aa) (q t bb)
 dimapping f g = withIso f \sa bt -> withIso g \ssaa bbtt -> iso (dimap sa ssaa) (dimap bt bbtt)
+
+-- | An `Iso` between two types that are inferred to have the
+-- | same representation by the compiler. One scenario that this is
+-- | particularly useful is the case of nested newtypes:
+-- |
+-- |```purescript
+-- |  newtype UserId = UserId Int
+-- |  newtype DeletedUserId = DeletedUserId UserId
+-- |
+-- |  -- `simple` is used to aid the type inference
+-- |  deletedUser :: DeletedUserId
+-- |  deletedUser = review (simple coerced) 42
+-- |```
+coerced :: forall s t a b. Coercible s a => Coercible t b => Iso s t a b
+coerced = iso coerce coerce

src/Data/Lens/Iso/Newtype.purs

@@ -1,15 +1,15 @@
 module Data.Lens.Iso.Newtype where
 
-import Data.Lens.Iso (Iso, Iso', iso)
-import Data.Newtype (class Newtype, unwrap, wrap)
+import Data.Lens.Iso (Iso, Iso', coerced)
+import Data.Newtype (class Newtype)
 
--- | An Iso between a newtype and its inner type.
--- | Supports switching between different types that have instances of the
--- | Newtype type class.
+-- | An Iso between a newtype and its inner type. This is a specialization of
+-- | `coerced` restricted to newtypes. Supports switching between different
+-- | types that have instances of the Newtype type class.
 -- | If you don't need to change types, you may have a better experience with
 -- | type inference if you use `simple _Newtype`.
 _Newtype :: forall t a s b. Newtype t a => Newtype s b => Iso t s a b
-_Newtype = iso unwrap wrap
+_Newtype = coerced
 
 -- | A variant of `_Newtype` which takes the constructor as an argument
 -- | and infers its inverse.