v11v9.1 - v10.1v8.2 - v9.0v6.0 - v8.1

JSON

Functions for interacting with JSON.

ignore

RESCRIPT
let ignore: t => unit

ignore(json) ignores the provided json and returns unit.

This helper is useful when you want to discard a value (for example, the result of an operation with side effects) without having to store or process it further.

parseExn

Deprecated

Use parseOrThrow instead

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 {
| JsExn(_) => 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 {
| JsExn(_) => Console.log("error")
}

Exceptions

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

parseExnWithReviver

Deprecated

Use parseOrThrow 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}`

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

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

Exceptions

  • Throws a SyntaxError if the string is not a valid JSON.

parseOrThrow

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

parseOrThrow(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.parseOrThrow(`{"foo":"bar","hello":"world"}`)
  // { foo: 'bar', hello: 'world' }

  let _ = JSON.parseOrThrow("")
  // error
} catch {
| JsExn(_) => 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.parseOrThrow(jsonString, ~reviver)->Console.log
  // { hello: 'WORLD', someNumber: 42 }

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

Exceptions

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

replacer

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

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}

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)),
])

dict
->JSON.stringifyAny
->Option.getUnsafe == `{"foo":"bar","hello":"world","someNumber":42}`

dict
->JSON.stringifyAny(~space=2)
->Option.getUnsafe == `{
  "foo": "bar",
  "hello": "world",
  "someNumber": 42
}`

dict
->JSON.stringifyAny(~replacer=Keys(["foo", "someNumber"]))
->Option.getUnsafe == `{"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
    }
  },
)

dict
->JSON.stringifyAny(~replacer)
->Option.getUnsafe == `{"foo":"BAR","hello":"WORLD","someNumber":42}`

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

// Throw a exception
switch BigInt.fromInt(0)->JSON.stringifyAny {
| exception _ => assert(true)
| _ => assert(false)
}

Exceptions

  • Throws a TypeError if the value contains circular references.

  • Throws 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)),
])

dict->JSON.stringifyAnyWithFilter(["foo", "someNumber"]) == `{"foo":"bar","someNumber":42}`

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

switch BigInt.fromInt(0)->JSON.stringifyAny {
| exception _ => assert(true)
| _ => assert(false)
}

Exceptions

  • Throws a TypeError if the value contains circular references.

  • Throws 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)),
])

dict
->JSON.stringifyAny
->Option.getUnsafe == `{"foo":"bar","hello":"world","someNumber":42}`

dict
->JSON.stringifyAny(~space=2)
->Option.getUnsafe == `{
  "foo": "bar",
  "hello": "world",
  "someNumber": 42
}`

dict
->JSON.stringifyAny(~replacer=Keys(["foo", "someNumber"]))
->Option.getUnsafe == `{"foo":"bar","someNumber":42}`

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

switch BigInt.fromInt(0)->JSON.stringifyAny {
| exception _ => assert(true)
| _ => assert(false)
}

Exceptions

  • Throws a TypeError if the value contains circular references.

  • Throws 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)),
])

dict
->JSON.stringifyAnyWithIndent(2)
->Option.getUnsafe == `{
  "foo": "bar",
  "hello": "world",
  "someNumber": 42
}`

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

switch BigInt.fromInt(0)->JSON.stringifyAny {
| exception _ => assert(true)
| _ => assert(false)
}

Exceptions

  • Throws a TypeError if the value contains circular references.

  • Throws 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
  }
}

dict
->JSON.stringifyAnyWithReplacer(replacer)
->Option.getUnsafe == `{"foo":"BAR","hello":"WORLD","someNumber":42}`

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

switch BigInt.fromInt(0)->JSON.stringifyAny {
| exception _ => assert(true)
| _ => assert(false)
}

Exceptions

  • Throws a TypeError if the value contains circular references.

  • Throws 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
  }
}

dict
->JSON.stringifyAnyWithReplacer(replacer)
->Option.getUnsafe == `{"foo":"BAR","hello":"WORLD","someNumber":42}`

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

switch BigInt.fromInt(0)->JSON.stringifyAny {
| exception _ => assert(true)
| _ => assert(false)
}

Exceptions

  • Throws a TypeError if the value contains circular references.

  • Throws a TypeError if the value contains BigInts.

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
// }

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
// }

t

RESCRIPT
@unboxed type t = | Boolean(bool) | @as(null) Null | String(string) | Number(float) | Object(dict<t>) | Array(array<t>)

A type representing a JSON object.