Many changes improving interoperability and completeness

Author: garyb

bower.json

@@ -24,10 +24,13 @@
     "purescript-functions": "^6.0.0",
     "purescript-maybe": "^6.0.0",
     "purescript-either": "^6.1.0",
-    "purescript-st": "^6.2.0",
     "purescript-tuples": "^7.0.0",
     "purescript-foldable-traversable": "^6.0.0",
     "purescript-gen": "^4.0.0",
-    "purescript-strings": "^6.0.1"
+    "purescript-strings": "^6.0.1",
+    "purescript-unfoldable": "^6.0.0"
+  },
+  "devDependencies": {
+    "purescript-assert": "^6.0.0"
   }
 }

src/JSON.js

@@ -0,0 +1,17 @@
+const coerce = (x) => x;
+
+export const _null = null;
+
+export const fromBoolean = coerce;
+
+export const fromInt = coerce;
+
+export const fromString = coerce;
+
+export const fromArray = coerce;
+
+export const fromObject = coerce;
+
+export const print = (j) => JSON.stringify(j);
+
+export const printIndented = (j) => JSON.stringify(j, null, 2);

src/Json.purs

@@ -1,26 +1,128 @@
-module Json (module Json.Internal) where
-
-import Json.Internal
-  ( Json
-
-  , parse
-  , print
-  , printIndented
-
+module JSON
+  ( parse
+  , null
+  , fromBoolean
+  , fromNumberWithDefault
+  , fromNumber
+  , fromInt
+  , fromString
+  , fromArray
+  , fromObject
   , case_
   , toNull
   , toBoolean
   , toNumber
   , toString
   , toArray
   , toObject
+  , print
+  , printIndented
+  , module Internal
+  ) where
 
-  , null
-  , fromNumber
-  , fromNumberWithDefault
-  , fromInt
-  , fromBoolean
-  , fromString
-  , fromArray
-  , fromObject
-  )
+import Prelude
+
+import Data.Either (Either(..))
+import Data.Function.Uncurried (runFn2, runFn3, runFn7)
+import Data.Maybe (Maybe(..))
+import JSON.Internal (JSON) as Internal
+import JSON.Internal (JSON, Object, _case, _fromNumberWithDefault, _parse)
+
+-- | Attempts to parse a string as a JSON value. If parsing fails, an error message detailing the
+-- | cause may be returned in the `Left` of the result.
+parse :: String -> Either String JSON
+parse j = runFn3 _parse Left Right j
+
+-- | The JSON `null` value.
+null :: JSON
+null = _null
+
+foreign import _null :: JSON
+
+-- | Creates a `JSON` value from a `Boolean`.
+foreign import fromBoolean :: Boolean -> JSON
+
+-- | Creates a `JSON` value from a `Number`, using a fallback `Int` value for cases where the
+-- | PureScript number value is not valid for JSON.
+fromNumberWithDefault :: Int -> Number -> JSON
+fromNumberWithDefault fallback n = runFn2 _fromNumberWithDefault fallback n
+
+-- | Creates a `JSON` value from a `Number`.
+-- |
+-- | The PureScript `Number` type admits infinities and a `NaN` value which are not allowed in JSON,
+-- | so when encountered, this function will treat those values as 0.
+fromNumber :: Number -> JSON
+fromNumber n = runFn2 _fromNumberWithDefault 0 n
+
+-- | Creates a `JSON` value from an `Int`.
+-- |
+-- | There is no corresponding `toInt` as JSON doesn't have a concept of integers - this is provided
+-- | as a convenience to avoid having to convert `Int` to `Number` before creating a `JSON` value.
+foreign import fromInt :: Int -> JSON
+
+-- | Creates a `JSON` value from a `String`.
+-- |
+-- | **Note**: this does not parse a string as a JSON value, it takes a PureScript string and
+-- | produces the corresponding `JSON` value for that string, similar to the other functions like
+-- | `fromBoolean` and `fromNumber`.
+-- |
+-- | To take a string that contains printed JSON and turn it into a `JSON` value, see
+-- | [`parse`](#v:parse).
+foreign import fromString :: String -> JSON
+
+-- | Creates a `JSON` value from an array of `JSON` values.
+foreign import fromArray :: Array JSON -> JSON
+
+-- | Creates a `JSON` value from an `Object`.
+foreign import fromObject :: Object -> JSON
+
+-- | Performs case analysis on a JSON value.
+-- |
+-- | As the `JSON` type is not a PureScript sum type, pattern matching cannot be used to
+-- | discriminate between the potential varieties of value. This function provides an equivalent
+-- | mechanism by accepting functions that deal with each variety, similar to an exaustive `case`
+-- | statement.
+case_
+  :: forall a
+   . (Unit -> a)
+  -> (Boolean -> a)
+  -> (Number -> a)
+  -> (String -> a)
+  -> (Array JSON -> a)
+  -> (Object -> a)
+  -> JSON
+  -> a
+case_ a b c d e f json = runFn7 _case a b c d e f json
+
+fail :: forall a b. a -> Maybe b
+fail _ = Nothing
+
+-- | Converts a `JSON` value to `Null` if the `JSON` is `null`.
+toNull :: JSON -> Maybe Unit
+toNull json = runFn7 _case Just fail fail fail fail fail json
+
+-- | Converts a `JSON` value to `Boolean` if the `JSON` is a boolean.
+toBoolean :: JSON -> Maybe Boolean
+toBoolean json = runFn7 _case fail Just fail fail fail fail json
+
+-- | Converts a `JSON` value to `Number` if the `JSON` is a number.
+toNumber :: JSON -> Maybe Number
+toNumber json = runFn7 _case fail fail Just fail fail fail json
+
+-- | Converts a `JSON` value to `String` if the `JSON` is a string.
+toString :: JSON -> Maybe String
+toString json = runFn7 _case fail fail fail Just fail fail json
+
+-- | Converts a `JSON` value to `Array JSON` if the `JSON` is an array.
+toArray :: JSON -> Maybe (Array JSON)
+toArray json = runFn7 _case fail fail fail fail Just fail json
+
+-- | Converts a `JSON` value to `Object` if the `JSON` is an object.
+toObject :: JSON -> Maybe Object
+toObject json = runFn7 _case fail fail fail fail fail Just json
+
+-- | Prints a JSON value as a compact (single line) string.
+foreign import print :: JSON -> String
+
+-- | Prints a JSON value as a "pretty" string,
+foreign import printIndented :: JSON -> String

src/Json/Gen.purs

@@ -1,4 +1,4 @@
-module Json.Gen where
+module JSON.Gen where
 
 import Prelude
 
@@ -9,35 +9,50 @@ import Control.Monad.Rec.Class (class MonadRec)
 import Data.NonEmpty ((:|))
 import Data.String.Gen (genUnicodeString)
 import Data.Tuple (Tuple(..))
-import Json as J
-import Json.Object as Object
+import JSON as J
+import JSON.Object as Object
 
--- | A generator for `Json` values. Especially useful for writing property-based tests.
-genJson :: forall m. MonadGen m => MonadRec m => Lazy (m J.Json) => m J.Json
-genJson = Gen.resize (min 5) $ Gen.sized genJson'
+-- | A generator for random `JSON` values of any variety.
+genJSON :: forall m. MonadGen m => MonadRec m => Lazy (m J.JSON) => m J.JSON
+genJSON = Gen.resize (min 5) $ Gen.sized genJSON'
   where
-  genJson' :: Int -> m J.Json
-  genJson' size
+  genJSON' :: Int -> m J.JSON
+  genJSON' size
     | size > 1 = Gen.resize (_ - 1) (Gen.choose genArray genObject)
     | otherwise = genLeaf
 
-  genArray :: m J.Json
-  genArray = J.fromArray <$> Gen.unfoldable (defer \_ -> genJson)
+-- | A generator for JSON arrays containing items based on the passed generator.
+genArrayOf :: forall m. MonadGen m => MonadRec m => m J.JSON -> m J.JSON
+genArrayOf inner = J.fromArray <$> Gen.unfoldable inner
 
-  genObject :: m J.Json
-  genObject = J.fromObject <<< Object.fromFoldable <$> genObjectEntries
+-- | A generator for JSON arrays containing random items.
+genArray :: forall m. MonadGen m => MonadRec m => Lazy (m J.JSON) => m J.JSON
+genArray = genArrayOf (defer \_ -> genJSON)
 
-  genObjectEntries :: m (Array (Tuple String J.Json))
-  genObjectEntries = Gen.unfoldable (Tuple <$> genUnicodeString <*> (defer \_ -> genJson))
+-- | A generator for JSON objects containing entries based on the passed generator.
+genObjectOf :: forall m. MonadGen m => MonadRec m => m (Tuple String J.JSON) -> m J.JSON
+genObjectOf inner = J.fromObject <<< Object.fromEntries <$> (Gen.unfoldable inner)
 
-  genLeaf :: m J.Json
-  genLeaf = Gen.oneOf $ pure J.null :| [ genBoolean, genNumber, genString ]
+-- | A generator for JSON objects containing random entries.
+genObject :: forall m. MonadGen m => MonadRec m => Lazy (m J.JSON) => m J.JSON
+genObject = genObjectOf (Tuple <$> genUnicodeString <*> defer \_ -> genJSON)
 
-  genBoolean :: m J.Json
-  genBoolean = J.fromBoolean <$> Gen.chooseBool
+-- | A generator for JSON leaf (null, boolean, number, string) values.
+genLeaf :: forall m. MonadGen m => MonadRec m => m J.JSON
+genLeaf = Gen.oneOf $ pure J.null :| [ genBoolean, genNumber, genString ]
 
-  genNumber :: m J.Json
-  genNumber = J.fromNumber <$> Gen.chooseFloat (-1000000.0) 1000000.0
+-- | A generator for JSON booleans.
+genBoolean :: forall m. MonadGen m => m J.JSON
+genBoolean = J.fromBoolean <$> Gen.chooseBool
 
-  genString :: m J.Json
-  genString = J.fromString <$> genUnicodeString
+-- | A generator for JSON numbers.
+genNumber :: forall m. MonadGen m => m J.JSON
+genNumber = J.fromNumber <$> Gen.chooseFloat (-1000000.0) 1000000.0
+
+-- | A generator for JSON integers.
+genInt :: forall m. MonadGen m => m J.JSON
+genInt = J.fromInt <$> Gen.chooseInt (-1000000) 1000000
+
+-- | A generator for JSON strings.
+genString :: forall m. MonadGen m => MonadRec m => m J.JSON
+genString = J.fromString <$> genUnicodeString

src/Json/Internal.js

@@ -1,6 +1,5 @@
 const toString = Object.prototype.toString;
 const hasOwnProperty = Object.prototype.hasOwnProperty;
-const coerce = (x) => x;
 
 export const _parse = (left, right, s) => {
   try {
@@ -11,9 +10,7 @@ export const _parse = (left, right, s) => {
   }
 };
 
-export const print = (j) => JSON.stringify(j);
-
-export const printIndented = (j) => JSON.stringify(j, null, 2);
+export const _fromNumberWithDefault = (fallback, n) => isNaN(n) || !isFinite(n) ? fallback : n;
 
 export const _case = (isNull, isBool, isNum, isStr, isArr, isObj, j) => {
   if (j == null) return isNull(null);
@@ -25,19 +22,23 @@ export const _case = (isNull, isBool, isNum, isStr, isArr, isObj, j) => {
   return isObj(j);
 };
 
-export const _null = null;
-
-export const fromBoolean = coerce;
-
-export const fromNumberWithDefault = (fallback) => (n) => isNaN(n) || !isFinite(n) ? fallback : n;
-
-export const fromInt = coerce;
-
-export const fromString = coerce;
+export const _fromEntries = (fst, snd, entries) => {
+  const result = {};
+  for (var i = 0; i < entries.length; i++) {
+    result[fst(entries[i])] = snd(entries[i]);
+  }
+  return result;
+};
 
-export const fromArray = coerce;
+export const _insert = (k, v, obj) =>
+  Object.assign({ [k]: v }, obj);
 
-export const fromObject = coerce;
+export const _delete = (k, obj) => {
+  if (!Object.hasOwn(obj, k)) return obj;
+  const result = Object.assign({}, obj);
+  delete result[k];
+  return result;
+};
 
 export const _entries = (tuple, obj) =>
   Object.entries(obj).map(([k, v]) => tuple(k)(v));