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