Fable.SimpleJson

A simple library for easily parsing, transforming and converting JSON in Fable projects. It is written using parser combinators from Fable.Parsimmon

Installation

Install from nuget using paket

paket add nuget Fable.SimpleJson --project path/to/YourProject.fsproj

Make sure the references are added to your paket files

# paket.dependencies (solution-wide dependencies)
nuget Fable.SimpleJson

# paket.refernces (project-specific dependencies)
Fable.SimpleJson

Using the library

JSON Parsing and Transformation API

open Fable.SimpleJson 

// ... 

SimpleJson.tryParse : string -> Option<Json>
SimpleJson.parse : string -> Json
SimpleJson.toString : Json -> string
SimpleJson.fromObjectLiteral : 'a -> Option<Json>
SimpleJson.mapKeys : (f: string -> string) -> Json -> Json
SimpleJson.mapKeysByPath : (f: string list -> string option) -> Json -> Json

JSON Convertion API

open Fable.SimpleJson 

// ...

Json.parseAs<'t> (inputJson: string) : 't 
Json.tryParseAs<'t> (inputJson: string) : Result<'t, string> 
Json.parseFromJsonAs<'t> (parsedJson: Json) : 't 
Json.tryParseFromJsonAs<'t> (parsedJson: Json) : Result<'t, string>

The AST looks like this:

type Json = 
    | JNumber of float
    | JString of string
    | JBool of bool
    | JNull
    | JArray of Json list
    | JObject of Map<string, Json>

Auto Deserialization

Suppose you have the record of Person, you can then use Json.parseAs<'t> for automatic deserialization:

type Person = { Name: string; Age: int }

"{ \"Name\": \"John\", \"Age\": 42  }"
|> Json.parseAs<Person> 
// result => { Name = "John"; Age = 42 }

Manual Deserialization

Suppose you have the record of Person:

type Person = { Name: string; Age: int }

And you want to deserialize this string:

"{ \"name\":\"john\", \"age\":20 }"

Then you can would use the safe SimpleJson.tryParse to pattern-match and extract the values from the parsed JSON:

open Fable.SimpleJson

"{ \"name\":\"john\", \"age\":20 }"
|> SimpleJson.tryParse
|> function
    | Some (JObject dict) ->
        let value key = Map.tryFind key dict
        [value "name"; value "age"]
        |> List.choose id
        |> function
            | [JString name; JNumber age]  -> 
                Some { Name = name; Age = int age }
            | _ -> None
    | _ -> None

You could also use the non-safe version SimpleJson.parse if you know for sure that the JSON input string is parsable. SimpleJson.parse will throw an exception if it can't deserialize the JSON string.

Auto Serialization

let person = { Name = "John"; Age = 34 } 
Json.stringify person

Manual Serialization

Now, to serialize a typed entity into a JSON string, you build the JSON structure by hand and call SimpleJson.toString like the following:

let person = { Name = "John"; Age = 34 }

let serialized = 
    [ "name", JString person.Name
      "age", JNumber (float person.Age) ]
    |> Map.ofList
    |> JObject
    |> SimpleJson.toString

Pre-processing JSON values

Suppose you want to deserialize the string:

{  "first_name": "John", 
   "last_name": "Doe"    }

And you have the type

type Person = { FirstName: string; LastName: string }

Then obviously it wouldn't "just work" because the keys of the object don't match. SimpleJson can help with this by first rewriting the keys to match with the field names of the record before converting:

"{\"first_name\":\"John\",\"last_name\":\"Doe\"}"
|> SimpleJson.parse
|> SimpleJson.mapKeys (function
    | "first_name" -> "FirstName"
    | "last_name" -> "LastName"
    | key -> key)
|> Json.convertFromJsonAs<Person>
 // { FirstName = "John"; LastName = "Doe" }

Selective re-writing of JSON keys based on key path:

The function SimpleJson.mapKeys will convert every possible key in every object within the JSON structure. Sometimes you want to select exactly which keys to convert based on their path in the JSON using SimpleJson.mapKeysByPath:

testCase "mapKeysByPath works" <| fun test ->
    "[{\"person\":{\"first\":\"john\", \"last\":\"doe\"}}, {\"first\":\"not-mapped\"}]"
    |> SimpleJson.parse
    |> SimpleJson.mapKeysByPath (function
        | ["person"] -> Some "Person"
        | ["person";"first"] -> Some "first_name"
        | ["person";"last"] -> Some "last_name"
        | other -> None)
    |> SimpleJson.toString
    |> test.areEqual "[{\"Person\":{\"first_name\":\"john\",\"last_name\":\"doe\"}},{\"first\":\"not-mapped\"}]"

Building and running tests

Requirements

Dotnet 2.0
Mono
Node

Running the watching the tests live

bash build.sh RunLiveTests

Building the tests and running them using QUnut cli runner

bash build.sh RunTests

or just Ctrl + Shift + B to run the cli tests as a VS Code task

Elonon/Fable.SimpleJson