API / Js / Js_json

Js_json

Efficient JSON encoding using JavaScript API

see MDN

t

The JSON data structure

type t =
  | False
  | True
  | Null
  | String(string)
  | Number(float)
  | Object(Js.Dict.t<t>)
  | Array(array<t>)

Kind

json

type json = t

t

Underlying type of a JSON value

type t<_> =
  | String: t<Js_string.t>
  | Number: t<float>
  | Object: t<Js_dict.t<json>>
  | Array: t<array<json>>
  | Boolean: t<bool>
  | Null: t<Js_types.null_val>

tagged_t

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

classify

let classify: t => tagged_t

test

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

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

decodeString

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

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

decodeNumber

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

let decodeNumber: t => option<float>

decodeObject

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

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

decodeArray

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

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

decodeBoolean

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

let decodeBoolean: t => option<bool>

decodeNull

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

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

null

null is the singleton null JSON value.

let null: t

string

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

let string: string => t

number

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

let number: float => t

boolean

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

let boolean: bool => t

object_

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

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

array

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

let array: array<t> => t

stringArray

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

let stringArray: array<string> => t

numberArray

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

let numberArray: array<float> => t

booleanArray

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

let booleanArray: array<bool> => t

objectArray

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

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

parseExn

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 MDN

RES
/* 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")
}

RES
/* 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 ] } `))

let parseExn: string => t

stringify

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

See MDN

RES
/* 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)))

let stringify: t => string

stringifyWithSpace

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

See MDN

RES
/* 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))

let stringifyWithSpace: (t, int) => string

stringifyAny

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

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

let stringifyAny: 'a => option<string>

deserializeUnsafe

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

let deserializeUnsafe: string => 'a

serializeExn

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

let serializeExn: 'a => string