Possible API Changes

[paf31]

I've wondered for a while whether it would be a good idea to rethink the API for this module. Given that I'm about to write about it for the book, it's probably a good time to raise my concern.

What if we changed the API as follows:

data ForeignError = 
  = TypeMismatch String
  | NoSuchProperty String
  | ...

type F = V [ForeignError]

class ReadForeign a where
  read :: Foreign -> F a

• Use V instead of Either.
• Encourage function composition and applicative validation instead of do notation
• Provide combinators for things like property access:

(.:) :: Foreign -> String -> F Foreign

[natefaubion]

Additionally, things like property/index testing and default values would be nice.

[natefaubion]

With the signature (.:) :: Foreign -> String -> F Foreign you have to introduce something like:

parse :: forall a. (ReadForeign a) => F Foreign -> F a
parse = runV invalid read

data TestData = TestData Number Number Number

instance readTestData :: ReadForeign TestData where
  read o = TestData <$> parse (o .: "foo")
                    <*> parse (o .: "bar")
                    <*> parse (o .: "baz")

If you make it (.:) :: forall a. (ReadForeign a) => Foreign -> String -> F a, you can do this:

(.:?) :: forall a. (ReadForeign a) => F Foreign -> String -> F a
(.:?) obj k = runV invalid (\x -> x .: k) obj

instance readForeign :: ReadForeign Foreign where
  read = pure

data TestData = TestData Number Number Number

instance readTestData :: ReadForeign TestData where
  read o = TestData <$> (o .: "foo" .:? "nested")
                    <*> (o .: "bar")
                    <*> (o .: "baz")

Which relates back to #8

[natefaubion]

(I have implemented this library using Data.Validation if you are interested)

[paf31]

I've mocked up another version here: https://github.com/paf31/purescript-foreign-experimental

Having tried pretty hard to get the applicative validation to work with a decent API, and without resorting to invalid Monad instances, I've decided it's not worth the hassle. At this point, I'd just like to tidy things up a little bit.