API / Core / Json

JSON

Functions for interacting with JSON.

t

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

A type representing a JSON object.

replacer

RESCRIPT
type replacer = | Keys(array<string>) | Replacer((string, t) => t)

parseExn

RESCRIPT
let parseExn: (string, ~reviver: (string, t) => t=?) => t

parseExn(string, ~reviver=?)

Parses a JSON string or throws a JavaScript exception (SyntaxError), if the string isn't valid. The reviver describes how the value should be transformed. It is a function which receives a key and a value. It returns a JSON type.

Examples

RESCRIPT
try {
  let _ = JSON.parseExn(`{"foo":"bar","hello":"world"}`)
  // { foo: 'bar', hello: 'world' }

  let _ = JSON.parseExn("")
  // error
} catch {
| Exn.Error(_) => Console.log("error")
}

let reviver = (_, value: JSON.t) =>
  switch value {
  | String(string) => string->String.toUpperCase->JSON.Encode.string
  | Number(number) => (number *. 2.0)->JSON.Encode.float
  | _ => value
  }

let jsonString = `{"hello":"world","someNumber":21}`

try {
  JSON.parseExn(jsonString, ~reviver)->Console.log
  // { hello: 'WORLD', someNumber: 42 }

  JSON.parseExn("", ~reviver)->Console.log
  // error
} catch {
| Exn.Error(_) => Console.log("error")
}

Exceptions

  • Raises a SyntaxError (Exn.t) if the string isn't valid JSON.

parseExnWithReviver

Deprecated

Use parseExn with optional parameter instead

RESCRIPT
let parseExnWithReviver: (string, (string, t) => t) => t

parseExnWithReviver(string, reviver)

Parses a JSON string or throws a JavaScript exception (SyntaxError), if the string isn't valid. The reviver describes how the value should be transformed. It is a function which receives a key and a value. It returns a JSON type.

Examples

RESCRIPT
let reviver = (_, value: JSON.t) =>
  switch value {
  | String(string) => string->String.toUpperCase->JSON.Encode.string
  | Number(number) => (number *. 2.0)->JSON.Encode.float
  | _ => value
  }

let jsonString = `{"hello":"world","someNumber":21}`

try {
  JSON.parseExnWithReviver(jsonString, reviver)->Console.log
  // { hello: 'WORLD', someNumber: 42 }

  JSON.parseExnWithReviver("", reviver)->Console.log
  // error
} catch {
| Exn.Error(_) => Console.log("error")
}

Exceptions

  • Raises a SyntaxError if the string isn't valid JSON.

stringify

RESCRIPT
let stringify: (t, ~replacer: replacer=?, ~space: int=?) => string

stringify(json, ~replacer=?, ~space=?)

Converts a JSON object to a JSON string. The replacer describes how the value should be transformed. It is a function which receives a key and a value, or an array of keys which should be included in the output. If you want to stringify any type, use JSON.stringifyAny instead.

Examples

RESCRIPT
let json =
  Dict.fromArray([
    ("foo", JSON.Encode.string("bar")),
    ("hello", JSON.Encode.string("world")),
    ("someNumber", JSON.Encode.int(42)),
  ])->JSON.Encode.object

JSON.stringify(json)
// {"foo":"bar","hello":"world","someNumber":42}

JSON.stringify(json, ~space=2)
// {
//   "foo": "bar",
//   "hello": "world",
//   "someNumber": 42
// }

JSON.stringify(json, ~replacer=Keys(["foo", "someNumber"]))
// {"foo":"bar","someNumber":42}

let replacer = JSON.Replacer((_, value) => {
  let decodedValue = value->JSON.Decode.string

  switch decodedValue {
  | Some(string) => string->String.toUpperCase->JSON.Encode.string
  | None => value
  }
})

JSON.stringify(json, ~replacer)
// {"foo":"BAR","hello":"WORLD","someNumber":42}

stringifyWithIndent

Deprecated

Use stringify with optional parameter instead

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

stringifyWithIndent(json, indentation)

Converts a JSON object to a JSON string. The output will be indented. If you want to stringify any type, use JSON.stringifyAnyWithIndent instead.

Examples

RESCRIPT
let json =
  Dict.fromArray([
    ("foo", JSON.Encode.string("bar")),
    ("hello", JSON.Encode.string("world")),
    ("someNumber", JSON.Encode.int(42)),
  ])->JSON.Encode.object

JSON.stringifyWithIndent(json, 2)
// {
//   "foo": "bar",
//   "hello": "world",
//   "someNumber": 42
// }

stringifyWithReplacer

Deprecated

Use stringify with optional parameter instead

RESCRIPT
let stringifyWithReplacer: (t, (string, t) => t) => string

stringifyWithReplacer(json, replacer)

Converts a JSON object to a JSON string. The replacer describes how the value should be transformed. It is a function which receives a key and a value. If you want to stringify any type, use JSON.stringifyAnyWithReplacer instead.

Examples

RESCRIPT
let json =
  Dict.fromArray([
    ("foo", JSON.Encode.string("bar")),
    ("hello", JSON.Encode.string("world")),
    ("someNumber", JSON.Encode.int(42)),
  ])->JSON.Encode.object

let replacer = (_, value) => {
  let decodedValue = value->JSON.Decode.string

  switch decodedValue {
  | Some(string) => string->String.toUpperCase->JSON.Encode.string
  | None => value
  }
}

JSON.stringifyWithReplacer(json, replacer)
// {"foo":"BAR","hello":"WORLD","someNumber":42}

stringifyWithReplacerAndIndent

Deprecated

Use stringify with optional parameters instead

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

stringifyWithReplacerAndIndent(json, replacer, indentation)

Converts a JSON object to a JSON string. The output will be indented. The replacer describes how the value should be transformed. It is a function which receives a key and a value. If you want to stringify any type, use JSON.stringifyAnyWithReplacerAndIndent instead.

Examples

RESCRIPT
let json =
  Dict.fromArray([
    ("foo", JSON.Encode.string("bar")),
    ("hello", JSON.Encode.string("world")),
    ("someNumber", JSON.Encode.int(42)),
  ])->JSON.Encode.object

let replacer = (_, value) => {
  let decodedValue = value->JSON.Decode.string

  switch decodedValue {
  | Some(string) => string->String.toUpperCase->JSON.Encode.string
  | None => value
  }
}

JSON.stringifyWithReplacerAndIndent(json, replacer, 2)
// {
//   "foo": "BAR",
//   "hello": "WORLD",
//   "someNumber": 42
// }

stringifyWithFilter

Deprecated

Use stringify with optional parameter instead

RESCRIPT
let stringifyWithFilter: (t, array<string>) => string

stringifyWithFilter(json, filter)

Converts a JSON object to a JSON string. The filter is an array of keys, which should be included in the output. If you want to stringify any type, use JSON.stringifyAnyWithFilter instead.

Examples

RESCRIPT
let json =
  Dict.fromArray([
    ("foo", JSON.Encode.string("bar")),
    ("hello", JSON.Encode.string("world")),
    ("someNumber", JSON.Encode.int(42)),
  ])->JSON.Encode.object

JSON.stringifyWithFilter(json, ["foo", "someNumber"])
// {"foo":"bar","someNumber":42}

stringifyWithFilterAndIndent

Deprecated

Use stringify with optional parameters instead

RESCRIPT
let stringifyWithFilterAndIndent: (t, array<string>, int) => string

stringifyWithFilterAndIndent(json, filter, indentation)

Converts a JSON object to a JSON string. The output will be indented. The filter is an array of keys, which should be included in the output. If you want to stringify any type, use JSON.stringifyAnyWithFilterAndIndent instead.

Examples

RESCRIPT
let json =
  Dict.fromArray([
    ("foo", JSON.Encode.string("bar")),
    ("hello", JSON.Encode.string("world")),
    ("someNumber", JSON.Encode.int(42)),
  ])->JSON.Encode.object

JSON.stringifyWithFilterAndIndent(json, ["foo", "someNumber"], 2)
// {
//   "foo": "bar",
//   "someNumber": 42
// }

stringifyAny

RESCRIPT
let stringifyAny: ('a, ~replacer: replacer=?, ~space: int=?) => option<string>

stringifyAny(any, ~replacer=?, ~space=?)

Converts any type to a JSON string. The replacer describes how the value should be transformed. It is a function which receives a key and a value. Stringifying a function or undefined will return None. If the value contains circular references or BigInts, the function will throw a JavaScript exception (TypeError). If you want to stringify a JSON object, use JSON.stringify instead.

Examples

RESCRIPT
let dict = Dict.fromArray([
  ("foo", JSON.Encode.string("bar")),
  ("hello", JSON.Encode.string("world")),
  ("someNumber", JSON.Encode.int(42)),
])

JSON.stringifyAny(dict)
// {"foo":"bar","hello":"world","someNumber":42}

JSON.stringifyAny(dict, ~space=2)
// {
//   "foo": "bar",
//   "hello": "world",
//   "someNumber": 42
// }

JSON.stringifyAny(dict, ~replacer=Keys(["foo", "someNumber"]))
// {"foo":"bar","someNumber":42}

let replacer = JSON.Replacer((_, value) => {
  let decodedValue = value->JSON.Decode.string

  switch decodedValue {
  | Some(string) => string->String.toUpperCase->JSON.Encode.string
  | None => value
  }
})

JSON.stringifyAny(dict, ~replacer)
// {"foo":"BAR","hello":"WORLD","someNumber":42}

JSON.stringifyAny(() => "hello world")
// None

BigInt.fromInt(0)->JSON.stringifyAny
// exception

Exceptions

  • Raises a TypeError if the value contains circular references.

  • Raises a TypeError if the value contains BigInts.

stringifyAnyWithIndent

Deprecated

Use stringifyAny with optional parameter instead

RESCRIPT
let stringifyAnyWithIndent: ('a, int) => option<string>

stringifyAnyWithIndent(any, indentation)

Converts any type to a JSON string. The output will be indented. Stringifying a function or undefined will return None. If the value contains circular references or BigInts, the function will throw a JavaScript exception (TypeError). If you want to stringify a JSON object, use JSON.stringifyWithIndent instead.

Examples

RESCRIPT
let dict = Dict.fromArray([
  ("foo", JSON.Encode.string("bar")),
  ("hello", JSON.Encode.string("world")),
  ("someNumber", JSON.Encode.int(42)),
])

JSON.stringifyAnyWithIndent(dict, 2)
// {
//   "foo": "bar",
//   "hello": "world",
//   "someNumber": 42
// }

JSON.stringifyAny(() => "hello world")
// None

BigInt.fromInt(0)->JSON.stringifyAny
// exception

Exceptions

  • Raises a TypeError if the value contains circular references.

  • Raises a TypeError if the value contains BigInts.

stringifyAnyWithReplacer

Deprecated

Use stringifyAny with optional parameter instead

RESCRIPT
let stringifyAnyWithReplacer: ('a, (string, t) => t) => option<string>

stringifyAnyWithReplacer(json, replacer)

Converts any type to a JSON string. The replacer describes how the value should be transformed. It is a function which receives a key and a value. Stringifying a function or undefined will return None. If the value contains circular references or BigInts, the function will throw a JavaScript exception (TypeError). If you want to stringify a JSON object, use JSON.stringifyWithReplacer instead.

Examples

RESCRIPT
let dict = Dict.fromArray([
  ("foo", JSON.Encode.string("bar")),
  ("hello", JSON.Encode.string("world")),
  ("someNumber", JSON.Encode.int(42)),
])

let replacer = (_, value) => {
  let decodedValue = value->JSON.Decode.string

  switch decodedValue {
  | Some(string) => string->String.toUpperCase->JSON.Encode.string
  | None => value
  }
}

JSON.stringifyAnyWithReplacer(dict, replacer)
// {"foo":"BAR","hello":"WORLD","someNumber":42}

JSON.stringifyAny(() => "hello world")
// None

BigInt.fromInt(0)->JSON.stringifyAny
// exception

Exceptions

  • Raises a TypeError if the value contains circular references.

  • Raises a TypeError if the value contains BigInts.

stringifyAnyWithReplacerAndIndent

Deprecated

Use stringifyAny with optional parameters instead

RESCRIPT
let stringifyAnyWithReplacerAndIndent: ('a, (string, t) => t, int) => option<string>

stringifyAnyWithReplacerAndIndent(json, replacer, indentation)

Converts any type to a JSON string. The output will be indented. The replacer describes how the value should be transformed. It is a function which receives a key and a value. Stringifying a function or undefined will return None. If the value contains circular references or BigInts, the function will throw a JavaScript exception (TypeError). If you want to stringify a JSON object, use JSON.stringifyWithReplacerAndIndent instead.

Examples

RESCRIPT
let dict = Dict.fromArray([
  ("foo", JSON.Encode.string("bar")),
  ("hello", JSON.Encode.string("world")),
  ("someNumber", JSON.Encode.int(42)),
])

let replacer = (_, value) => {
  let decodedValue = value->JSON.Decode.string

  switch decodedValue {
  | Some(string) => string->String.toUpperCase->JSON.Encode.string
  | None => value
  }
}

JSON.stringifyAnyWithReplacerAndIndent(dict, replacer, 2)
// {
//   "foo": "BAR",
//   "hello": "WORLD",
//   "someNumber": 42
// }

JSON.stringifyAny(() => "hello world")
// None

BigInt.fromInt(0)->JSON.stringifyAny
// exception

Exceptions

  • Raises a TypeError if the value contains circular references.

  • Raises a TypeError if the value contains BigInts.

stringifyAnyWithFilter

Deprecated

Use stringifyAny with optional parameter instead

RESCRIPT
let stringifyAnyWithFilter: ('a, array<string>) => string

stringifyAnyWithFilter(json, filter)

Converts any type to a JSON string. The filter is an array of keys, which should be included in the output. Stringifying a function or undefined will return None. If the value contains circular references or BigInts, the function will throw a JavaScript exception (TypeError). If you want to stringify a JSON object, use JSON.stringifyWithFilter instead.

Examples

RESCRIPT
let dict = Dict.fromArray([
  ("foo", JSON.Encode.string("bar")),
  ("hello", JSON.Encode.string("world")),
  ("someNumber", JSON.Encode.int(42)),
])

JSON.stringifyAnyWithFilter(dict, ["foo", "someNumber"])
// {"foo": "bar","someNumber": 42}

JSON.stringifyAny(() => "hello world")
// None

BigInt.fromInt(0)->JSON.stringifyAny
// exception

Exceptions

  • Raises a TypeError if the value contains circular references.

  • Raises a TypeError if the value contains BigInts.

stringifyAnyWithFilterAndIndent

Deprecated

Use stringifyAny with optional parameters instead

RESCRIPT
let stringifyAnyWithFilterAndIndent: ('a, array<string>, int) => string

stringifyAnyWithFilterAndIndent(json, filter, indentation)

Converts any type to a JSON string. The output will be indented. The filter is an array of keys, which should be included in the output. Stringifying a function or undefined will return None. If the value contains circular references or BigInts, the function will throw a JavaScript exception (TypeError). If you want to stringify a JSON object, use JSON.stringifyWithFilterAndIndent instead.

Examples

RESCRIPT
let dict = Dict.fromArray([
  ("foo", JSON.Encode.string("bar")),
  ("hello", JSON.Encode.string("world")),
  ("someNumber", JSON.Encode.int(42)),
])

JSON.stringifyAnyWithFilterAndIndent(dict, ["foo", "someNumber"], 2)
// {
//   "foo": "bar",
//   "someNumber": 42
// }

JSON.stringifyAny(() => "hello world")
// None

BigInt.fromInt(0)->JSON.stringifyAny
// exception

Exceptions

  • Raises a TypeError if the value contains circular references.

  • Raises a TypeError if the value contains BigInts.