API / Js / Json

Json

Efficient JSON encoding using JavaScript API

see MDN

t

RESCRIPT
type t = | Boolean(bool) | Null | String(string) | Number(float) | Object(Js.Dict.t<t>) | Array(array<t>)

The JSON data structure

tagged_t

RESCRIPT
type tagged_t = | JSONFalse | JSONTrue | JSONNull | JSONString(string) | JSONNumber(float) | JSONObject(Js_dict.t<t>) | JSONArray(array<t>)

classify

RESCRIPT
let classify: t => tagged_t

test

RESCRIPT
let test: ('a, Kind.t<'b>) => bool

test(v, kind) returns true if v is of kind.

decodeString

RESCRIPT
let decodeString: t => option<Js_string.t>

decodeString(json) returns Some(s) if json is a string, None otherwise.

decodeNumber

RESCRIPT
let decodeNumber: t => option<float>

decodeNumber(json) returns Some(n) if json is a number, None otherwise.

decodeObject

RESCRIPT
let decodeObject: t => option<Js_dict.t<t>>

decodeObject(json) returns Some(o) if json is an object, None otherwise.

decodeArray

RESCRIPT
let decodeArray: t => option<array<t>>

decodeArray(json) returns Some(a) if json is an array, None otherwise.

decodeBoolean

RESCRIPT
let decodeBoolean: t => option<bool>

decodeBoolean(json) returns Some(b) if json is a boolean, None otherwise.

decodeNull

RESCRIPT
let decodeNull: t => option<Js_null.t<'a>>

decodeNull(json) returns Some(null) if json is a null, None otherwise.

null

RESCRIPT
let null: t

null is the singleton null JSON value.

string

RESCRIPT
let string: string => t

string(s) makes a JSON string of the string s.

number

RESCRIPT
let number: float => t

number(n) makes a JSON number of the float n.

boolean

RESCRIPT
let boolean: bool => t

boolean(b) makes a JSON boolean of the bool b.

object_

RESCRIPT
let object_: Js_dict.t<t> => t

object_(dict) makes a JSON object of the Js.Dict.t dict.

array

RESCRIPT
let array: array<t> => t

array_(a) makes a JSON array of the Js.Json.t array a.

stringArray

RESCRIPT
let stringArray: array<string> => t

stringArray(a) makes a JSON array of the string array a.

numberArray

RESCRIPT
let numberArray: array<float> => t

numberArray(a) makes a JSON array of the float array a.

booleanArray

RESCRIPT
let booleanArray: array<bool> => t

booleanArray(a) makes a JSON array of the bool array a.

objectArray

RESCRIPT
let objectArray: array<Js_dict.t<t>> => t

objectArray(a) makes a JSON array of the JsDict.tarraya`.

parseExn

RESCRIPT
let parseExn: string => t

parseExn(s) parses the string s into a JSON data structure. Returns a JSON data structure. Raises SyntaxError if the given string is not a valid JSON. Note: SyntaxError is a JavaScript exception.

See parse on MDN.

Examples

RESCRIPT
/* parse a simple JSON string */

let json = try Js.Json.parseExn(` "hello" `) catch {
| _ => failwith("Error parsing JSON string")
}

switch Js.Json.classify(json) {
| Js.Json.JSONString(value) => Js.log(value)
| _ => failwith("Expected a string")
}

RESCRIPT
/* parse a complex JSON string */

let getIds = s => {
  let json = try Js.Json.parseExn(s) catch {
  | _ => failwith("Error parsing JSON string")
  }

  switch Js.Json.classify(json) {
  | Js.Json.JSONObject(value) =>
    /* In this branch, compiler infer value : Js.Json.t Js.Dict.t */
    switch Js.Dict.get(value, "ids") {
    | Some(ids) =>
      switch Js.Json.classify(ids) {
      | Js.Json.JSONArray(ids) => /* In this branch compiler infer ids : Js.Json.t array */
        ids
      | _ => failwith("Expected an array")
      }
    | None => failwith("Expected an `ids` property")
    }
  | _ => failwith("Expected an object")
  }
}

/* prints `1, 2, 3` */
Js.log(getIds(` { "ids" : [1, 2, 3 ] } `))

stringify

RESCRIPT
let stringify: t => string

stringify(json) formats the JSON data structure as a string. Returns the string representation of a given JSON data structure.

See stringify on MDN.

Examples

RESCRIPT
/* Creates and stringifies a simple JS object */

let dict = Js.Dict.empty()
Js.Dict.set(dict, "name", Js.Json.string("John Doe"))
Js.Dict.set(dict, "age", Js.Json.number(30.0))
Js.Dict.set(dict, "likes", Js.Json.stringArray(["ReScript", "ocaml", "js"]))

Js.log(Js.Json.stringify(Js.Json.object_(dict)))

stringifyWithSpace

RESCRIPT
let stringifyWithSpace: (t, int) => string

stringifyWithSpace(json) formats the JSON data structure as a string. Returns the string representation of a given JSON data structure with spacing.

See stringify on MDN.

Examples

RESCRIPT
/* Creates and stringifies a simple JS object with spacing */

let dict = Js.Dict.empty()
Js.Dict.set(dict, "name", Js.Json.string("John Doe"))
Js.Dict.set(dict, "age", Js.Json.number(30.0))
Js.Dict.set(dict, "likes", Js.Json.stringArray(["ReScript", "ocaml", "js"]))

Js.log(Js.Json.stringifyWithSpace(Js.Json.object_(dict), 2))

stringifyAny

RESCRIPT
let stringifyAny: 'a => option<string>

stringifyAny(value) formats any value into a JSON string.

Examples

RESCRIPT
/* prints `["hello", "world"]` */
Js.log(Js.Json.stringifyAny(["hello", "world"]))

deserializeUnsafe

RESCRIPT
let deserializeUnsafe: string => 'a

Best-effort serialization, it tries to seralize as many objects as possible and deserialize it back

It is unsafe in two aspects

  • It may throw during parsing

  • when you cast it to a specific type, it may have a type mismatch

serializeExn

RESCRIPT
let serializeExn: 'a => string

It will raise in such situations:

  • The object can not be serlialized to a JSON

  • There are cycles

  • Some JS engines can not stringify deeply nested json objects