@grain/stdlib 0.5.13 → 0.6.0

package/json.gr

@@ -0,0 +1,2084 @@
+/**
+ * JSON (JavaScript Object Notation) parsing, printing, and access utilities.
+ *
+ * @example from "json" include Json
+ * @example Json.parse("{\"currency\":\"€\",\"price\":99.99}")
+ * @example
+ * print(
+ *   toString(
+ *     format=Pretty,
+ *     JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))])
+ *   )
+ * )
+ */
+module Json
+
+from "runtime/bigint" include Bigint as BI
+from "runtime/dataStructures" include DataStructures
+from "runtime/numbers" include Numbers
+from "runtime/numberUtils" include NumberUtils
+from "runtime/string" include String as RuntimeString
+from "runtime/unsafe/tags" include Tags
+from "runtime/unsafe/wasmi32" include WasmI32
+from "runtime/unsafe/wasmi64" include WasmI64
+from "runtime/unsafe/wasmf64" include WasmF64
+from "runtime/atof/parse" include Parse as Atof
+from "buffer" include Buffer
+from "char" include Char
+from "string" include String
+from "list" include List
+from "uint8" include Uint8
+use RuntimeString.{ toString as runtimeToString, getCodePoint }
+use Numbers.{ coerceNumberToWasmI32 }
+use DataStructures.{ tagSimpleNumber, untagSimpleNumber }
+
+// Primitive offsets
+// TODO(#703): Get these offsets from the runtime
+@unsafe
+let _INT64_BOXED_VALUE_OFFSET = 8n
+@unsafe
+let _Float64_BOXED_VALUE_OFFSET = 8n
+
+/**
+ * Data structure representing JSON in Grain.
+ *
+ * @example
+ * assert Json.parse("{\"currency\":\"€\",\"price\":99.99}") == JsonObject([
+ *   ("currency", JsonString("€")),
+ *   ("price", JsonNumber(99.99)),
+ * ])
+ *
+ * @example
+ * assert Json.parse("{\n\"currency\":\"€\",\n\"price\":99.99\n}") == JsonObject([
+ *   ("currency", JsonString("€")),
+ *   ("price", JsonNumber(99.99)),
+ * ])
+ */
+provide enum rec Json {
+  JsonNull,
+  JsonBoolean(Bool),
+  JsonNumber(Number),
+  JsonString(String),
+  JsonArray(List<Json>),
+  // Note that JsonObject here is deliberately defined as a simple list of key value pair tuples as opposed
+  // to for example a Map in order to accommodate the fact that the ECMA-404 standard doesn't prohibit
+  // duplicate names in Objects. Such JSON should be representable by the JSON data structure for lossless
+  // processing. This also simplifies implementation by not requiring a purpose built data structure and
+  // has the benefit of List's immutability. It's a conscious decision that sacrifices ease of use of the
+  // API for lossless handing of these edge cases with intention of later building more ergonomic APIs on a
+  // higher level of abstraction.
+  JsonObject(List<(String, Json)>),
+}
+
+/**
+ * Represents errors for cases where a `Json` data structure cannot be represented as a
+ * JSON string.
+ */
+provide enum JsonToStringError {
+  /**
+   * The `Json` data structure contains a number value of `NaN`, `Infinity`, or `-Infinity`.
+   */
+  InvalidNumber(String),
+}
+
+/**
+ * Controls how indentation is output in custom formatting.
+ */
+provide enum IndentationFormat {
+  /**
+   * No indentation is emitted.
+   *
+   * ```json
+   * {
+   * "currency": "€",
+   * "price": 99.9
+   * }
+   * ```
+   */
+  NoIndentation,
+  /**
+   * Tabs are emitted.
+   *
+   * ```json
+   * {
+   * 	"currency": "€",
+   * 	"price": 99.9
+   * }
+   * ```
+   */
+  IndentWithTab,
+  /**
+   * The desired number of spaces are emitted.
+   *
+   * `IndentWithSpaces(2)`
+   * ```json
+   * {
+   *   "currency": "€",
+   *   "price": 99.9
+   * }
+   * ```
+   *
+   * `IndentWithSpaces(4)`
+   * ```json
+   * {
+   *     "currency": "€",
+   *     "price": 99.9
+   * }
+   * ```
+   */
+  IndentWithSpaces(Number),
+}
+
+/**
+ * Controls how arrays are output in custom formatting.
+ */
+provide enum ArrayFormat {
+  /**
+   * Arrays are emitted in a compact manner.
+   *
+   * ```json
+   * []
+   * ```
+   *
+   * ```json
+   * [1]
+   * ```
+   *
+   * ```json
+   * [1,2,3]
+   * ```
+   */
+  CompactArrayEntries,
+  /**
+   * Arrays are emitted with spaces between elements.
+   *
+   * ```json
+   * [ ]
+   * ```
+   *
+   * ```json
+   * [1]
+   * ```
+   *
+   * ```json
+   * [1, 2, 3]
+   * ```
+   */
+  SpacedArrayEntries,
+  /**
+   * Arrays are emitted with newlines and indentation between each element.
+   *
+   * ```json
+   * []
+   * ```
+   *
+   * ```json
+   * [
+   *   1
+   * ]
+   * ```
+   *
+   * ```json
+   * [
+   *   1,
+   *   2,
+   *   3
+   * ]
+   * ```
+   */
+  OneArrayEntryPerLine,
+}
+
+/**
+ * Controls how objects are output in custom formatting.
+ */
+provide enum ObjectFormat {
+  /**
+   * Objects are emitted in a compact manner.
+   *
+   * ```json
+   * {}
+   * ```
+   *
+   * ```json
+   * {"a":1}
+   * ```
+   *
+   * ```json
+   * {"a":1,"b":2,"c":3}
+   * ```
+   */
+  CompactObjectEntries,
+  /**
+   * Objects are emitted with spaces between entries.
+   *
+   * ```json
+   * { }
+   * ```
+   *
+   * ```json
+   * {"a": 1}
+   * ```
+   *
+   * ```json
+   * {"a": 1, "b": 2, "c": 3}
+   * ```
+   */
+  SpacedObjectEntries,
+  /**
+   * Objects are emitted with each entry on a new line.
+   *
+   * ```
+   * {}
+   * ```
+   *
+   * ```
+   * {
+   *   "a": 1
+   * }
+   * ```
+   *
+   * ```
+   * {
+   *   "a": 1,
+   *   "b": 2,
+   *   "c": 3
+   * }
+   * ```
+   */
+  OneObjectEntryPerLine,
+}
+
+/**
+ * Controls how line endings are output in custom formatting.
+ */
+provide enum LineEnding {
+  /**
+   * No line endings will be emitted.
+   */
+  NoLineEnding,
+  /**
+   * A `\n` will be emitted at the end of each line.
+   */
+  LineFeed,
+  /**
+   * A `\r\n` will be emitted at the end of each line.
+   */
+  CarriageReturnLineFeed,
+  /**
+   * A `\r` will be emitted at the end of each line.
+   */
+  CarriageReturn,
+}
+
+/*
+ * Allows fine-grained control of formatting in JSON output.
+ */
+record FormattingSettings {
+  indentation: IndentationFormat,
+  arrayFormat: ArrayFormat,
+  objectFormat: ObjectFormat,
+  lineEnding: LineEnding,
+  finishWithNewLine: Bool,
+  escapeAllControlPoints: Bool,
+  escapeHTMLUnsafeSequences: Bool,
+  escapeNonASCII: Bool,
+}
+
+/**
+ * Allows control of formatting in JSON output.
+ */
+provide enum FormattingChoices {
+  /**
+   * Recommended human readable formatting.
+   *
+   * Escapes all control points for the sake of clarity, but outputs unicode
+   * codepoints directly so the result needs to be treated as proper unicode and
+   * is not safe to be transported in ASCII encoding.
+   *
+   * Roughly Equivalent to:
+   * ```grain
+   * Custom{
+   *  indentation: IndentWithSpaces(2),
+   *  arrayFormat: OneArrayEntryPerLine,
+   *  objectFormat: OneObjectEntryPerLine,
+   *  lineEnding: LineFeed,
+   *  finishWithNewLine: true,
+   *  escapeAllControlPoints: true,
+   *  escapeHTMLUnsafeSequences: false,
+   *  escapeNonASCII: false,
+   * }
+   * ```
+   *
+   * ```json
+   * {
+   *   "currency": "€",
+   *   "price": 99.9,
+   *   "currencyDescription": "EURO\u007f",
+   * }
+   * ```
+   */
+  Pretty,
+  /**
+   * Compact formatting that minimizes the size of resulting JSON at cost of not
+   * being easily human readable.
+   *
+   * Only performs minimal string escaping as required by the ECMA-404 standard,
+   * so the result needs to be treated as proper unicode and is not safe to be
+   * transported in ASCII encoding.
+   *
+   * Roughly Equivalent to:
+   * ```grain
+   * Custom{
+   *  indentation: NoIndentation,
+   *  arrayFormat: CompactArrayEntries,
+   *  objectFormat: CompactObjectEntries,
+   *  lineEnding: NoLineEnding,
+   *  finishWithNewLine: false,
+   *  escapeAllControlPoints: false,
+   *  escapeHTMLUnsafeSequences: false,
+   *  escapeNonASCII: false,
+   * }
+   * ```
+   *
+   * ```json
+   * {"currency":"€","price":99.9,"currencyDescription":"EURO␡"}
+   * ```
+   */
+  Compact,
+  /**
+   * Pretty and conservative formatting to maximize compatibility and
+   * embeddability of the resulting JSON.
+   *
+   * Should be safe to copy and paste directly into HTML and to be transported in
+   * plain ASCII.
+   *
+   * Roughly Equivalent to:
+   * ```grain
+   * Custom{
+   *  indentation: IndentWithSpaces(2),
+   *  arrayFormat: OneArrayEntryPerLine,
+   *  objectFormat: OneObjectEntryPerLine,
+   *  lineEnding: LineFeed,
+   *  finishWithNewLine: true,
+   *  escapeAllControlPoints: true,
+   *  escapeHTMLUnsafeSequences: true,
+   *  escapeNonASCII: true,
+   * }
+   * ```
+   *
+   * ```json
+   * {
+   *   "currency": "\u20ac",
+   *   "price": 99.9,
+   *   "currencyDescription": "EURO\u007f",
+   * }
+   * ```
+   */
+  PrettyAndSafe,
+  /**
+   * Compact and conservative formatting to maximize compatibility and
+   * embeddability of the resulting JSON.
+   *
+   * Should be safe to copy and paste directly into HTML and to transported in
+   * plain ASCII.
+   *
+   * Roughly Equivalent to:
+   * ```grain
+   * Custom{
+   *  indentation: NoIndentation,
+   *  arrayFormat: CompactArrayEntries,
+   *  objectFormat: CompactObjectEntries,
+   *  lineEnding: NoLineEnding,
+   *  finishWithNewLine: false,
+   *  escapeAllControlPoints: true,
+   *  escapeHTMLUnsafeSequences: true,
+   *  escapeNonASCII: true,
+   * }
+   * ```
+   *
+   * ```json
+   * {"currency":"\u20ac","price":99.9,"currencyDescription":"EURO\u007f"}
+   * ```
+   */
+  CompactAndSafe,
+  /**
+   * Allows for fined grained control of the formatting output.
+   */
+  Custom{
+    indentation: IndentationFormat,
+    arrayFormat: ArrayFormat,
+    objectFormat: ObjectFormat,
+    lineEnding: LineEnding,
+    finishWithNewLine: Bool,
+    escapeAllControlPoints: Bool,
+    escapeHTMLUnsafeSequences: Bool,
+    escapeNonASCII: Bool,
+  },
+}
+
+record JsonWriterConfig {
+  format: FormattingSettings,
+  buffer: Buffer.Buffer,
+  emitEscapedQuotedString: String => Void,
+  printNewLine: Option<() => Void>,
+  printIndentation: Option<Number => Void>,
+}
+
+// The idea for this type is to allow reusing a bit of work done in preparing for printing JSON.
+// For now this is not exposed and remains an internal implementation detail.
+// It may make sense in the future to expose it and let the user reuse a writer for multiple
+// JSON emit operations without reallocating new closures and buffers each time.
+record JsonWriter {
+  emit: Json => Option<JsonToStringError>,
+}
+
+let emitUTF16EscapeSequence = (codePoint: Number, buffer: Buffer.Buffer) => {
+  // Emit the "\u" followed by hexadecimal representation of the codepoint
+  // with fixed length of 4 hexadecimal digits corresponding to the two byte
+  // codepoint. No checks are performed here if the codepoint is in the
+  // "Basic Multilingual Plane" (0000-FFFF) as this function is only called
+  // internally.
+  // An alternative was to this implementation was to use NumberUtils.itoa32,
+  // but this avoids unnecessary heap allocations. As a possible future
+  // optimization this loop could be unrolled possibly even converted to be
+  // branchless and SIMD optimized, but it could be a bit of an overkill as
+  // this codepath is only for escape sequences, which probably aren't all
+  // that common occurrence.
+
+  Buffer.addChar('\\', buffer)
+  Buffer.addChar('u', buffer)
+  // Loop over the four digit from most to least significant.
+  for (let mut digitIndex = 3; digitIndex >= 0; digitIndex -= 1) {
+    // Use bit masking and shifting to extract from the codepoint a number
+    // with just the bits corresponding to this hexadecimal digit.
+    let shift = digitIndex * 4
+    let mask = 0b1111 << shift
+    let digit = (codePoint & mask) >>> shift
+
+    // Digit now is a number in the range 0..15 and we need to translate it
+    // into a unicode codepoint representing the hexadecimal digit
+    // (0..9/a..f). We can use the fact that digits and latin letters in
+    // ASCII and by extension in Unicode are adjacent and ordered.
+    let hexDigitCodePoint = if (digit <= 9) {
+      // 48 is codepoint for char '0'
+      digit + 48
+    } else {
+      // 97 is codepoint for char 'a'
+      // But we also need to subtract 10 from it because we need
+      // the 10..15 number range translated to 0..5 in order to
+      // serve as an index in the ASCI range 'a'..'f'.
+      digit + 87
+    }
+
+    Buffer.addCharFromCodePoint(hexDigitCodePoint, buffer)
+  }
+}
+
+let emitEscapedUnicodeSequence = (codePoint: Number, buffer: Buffer.Buffer) => {
+  // See the String section in the ECMA-404 doc.
+  // If the code point is "in the Basic Multilingual Plane", that is in range
+  // 0..65535. Greater values need to be split into two UTF-16 chunks.
+  if (codePoint <= 0xFFFF) {
+    emitUTF16EscapeSequence(codePoint, buffer)
+  } else {
+    // The following three lines are copied from String module of Grain's
+    // stdlib. It would be nice to share more code. On the other hand it
+    // may make sense to just have these few instructions directly here
+    // from the performance standpoint so we can print millions of emojis
+    // per second 😄.
+
+    // https://en.wikipedia.org/wiki/UTF-16#Code_points_from_U+010000_to_U+10FFFF
+    let uPrime = codePoint - 0x10000
+    let highSurrogate = ((uPrime & 0b11111111110000000000) >>> 10) + 0xD800
+    // High surrogate
+    let lowSurrogate = (uPrime & 0b00000000001111111111) + 0xDC00
+    // Low surrogate
+
+    emitUTF16EscapeSequence(highSurrogate, buffer)
+    emitUTF16EscapeSequence(lowSurrogate, buffer)
+  }
+}
+
+let emitEscapedCodePoint = (codePoint: Number, buffer: Buffer.Buffer) => {
+  match (codePoint) {
+    0x0008 => { // backspace
+      Buffer.addChar('\\', buffer)
+      Buffer.addChar('b', buffer)
+    },
+    0x0009 => { // tab
+      Buffer.addChar('\\', buffer)
+      Buffer.addChar('t', buffer)
+    },
+    0x000A => { // line feed
+      Buffer.addChar('\\', buffer)
+      Buffer.addChar('n', buffer)
+    },
+    0x000C => { // form feed
+      Buffer.addChar('\\', buffer)
+      Buffer.addChar('f', buffer)
+    },
+    0x000D => { // carriage return
+      Buffer.addChar('\\', buffer)
+      Buffer.addChar('r', buffer)
+    },
+    0x0022 => { // quotation mark
+      Buffer.addChar('\\', buffer)
+      Buffer.addChar('"', buffer)
+    },
+    0x005C => { // backslash or "Reverse Solidus"
+      Buffer.addChar('\\', buffer)
+      Buffer.addChar('\\', buffer)
+    },
+    _ => {
+      emitEscapedUnicodeSequence(codePoint, buffer)
+    },
+  }
+}
+
+let printNull = (buffer: Buffer.Buffer) => Buffer.addString("null", buffer)
+
+let printBool = (b: Bool, buffer: Buffer.Buffer) => {
+  if (b) {
+    Buffer.addString("true", buffer)
+  } else {
+    Buffer.addString("false", buffer)
+  }
+}
+
+@unsafe
+let printNumberWasmI32 = (value: WasmI32, buffer: Buffer.Buffer) => {
+  let s = NumberUtils.itoa32(value, 10n)
+  Buffer.addString(s, buffer)
+}
+
+@unsafe
+let printNumberWasmI64 = (value: WasmI64, buffer: Buffer.Buffer) => {
+  let s = NumberUtils.itoa64(value, 10n)
+  Buffer.addString(s, buffer)
+}
+
+@unsafe
+let isFinite = (value: WasmF64) => {
+  use WasmF64.{ (==), (-) }
+  value - value == 0.0W
+}
+
+@unsafe
+let isNaN = (value: WasmF64) => {
+  use WasmF64.{ (!=) }
+  value != value
+}
+
+@unsafe
+let printNumberWasmF64 = (value: WasmF64, buffer: Buffer.Buffer) => {
+  if (isFinite(value)) {
+    let s = NumberUtils.dtoa(value)
+    Buffer.addString(s, buffer)
+    None
+  } else {
+    use WasmF64.{ (<) }
+    // JSON standard doesn't allow NaN or infinite values in numbers,
+    // but WASM f64 (IEEE 754-2008), as well as Grain's number types do
+    // (Float64 as well as Number). This is the only reason that the
+    // formatting needs to return a Result and not just a String
+    // directly. Other possible choices were to throw exceptions or to
+    // continue formatting without representing these values correctly
+    // (like JavaScript's JSON.stringify).
+    if (isNaN(value)) {
+      Some(InvalidNumber("NaN is not allowed in JsonNumber"))
+    } else if (value < 0.0W) {
+      Some(InvalidNumber("-Infinity is not allowed in JsonNumber"))
+    } else {
+      Some(InvalidNumber("Infinity is not allowed in JsonNumber"))
+    }
+  }
+}
+
+@unsafe
+let printNumber = (value: Number, buffer: Buffer.Buffer) => {
+  use WasmI32.{ (&), (==), (!=), (<<), (>>) }
+
+  let ptr = WasmI32.fromGrain(value)
+  let ret = if ((ptr & 1n) != 0n) {
+    printNumberWasmI32(untagSimpleNumber(value), buffer)
+    None
+  } else if ((ptr & 7n) == Tags._GRAIN_GENERIC_HEAP_TAG_TYPE) {
+    let tag = WasmI32.load(ptr, 0n)
+    match (tag) {
+      t when t == Tags._GRAIN_BOXED_NUM_HEAP_TAG => {
+        let numberTag = WasmI32.load(ptr, 4n)
+        match (numberTag) {
+          t when t == Tags._GRAIN_INT64_BOXED_NUM_TAG => {
+            let asWasmI64 = WasmI64.load(ptr, _INT64_BOXED_VALUE_OFFSET)
+            printNumberWasmI64(asWasmI64, buffer)
+            None
+          },
+          t when t == Tags._GRAIN_BIGINT_BOXED_NUM_TAG => {
+            Buffer.addString(BI.bigIntToString10(ptr), buffer)
+            None
+          },
+          t when t == Tags._GRAIN_RATIONAL_BOXED_NUM_TAG => {
+            // JSON does not support rationals as a compromise
+            // we coerce them to an f64 and print that
+            // this means there is a slight loss in precision
+            let asFloat64 = Numbers.coerceNumberToFloat64(value)
+            let ptr = WasmI32.fromGrain(asFloat64)
+            let asWasmF64 = WasmF64.load(ptr, _Float64_BOXED_VALUE_OFFSET)
+            printNumberWasmF64(asWasmF64, buffer)
+          },
+          t when t == Tags._GRAIN_FLOAT64_BOXED_NUM_TAG => {
+            let asWasmF64 = WasmF64.load(ptr, _Float64_BOXED_VALUE_OFFSET)
+            printNumberWasmF64(asWasmF64, buffer)
+          },
+          _ => {
+            fail "Impossible: Json.toString encountered an unknown number tag"
+          },
+        }
+      },
+      _ => {
+        fail "Impossible: Json.toString encountered an unknown number tag"
+      },
+    }
+  } else {
+    fail "Impossible: Json.toString encountered an unknown number tag"
+  }
+  // This keeps the gc from prematurely freeing the value
+  ignore(value)
+  ret
+}
+
+// Note that this compromises on peak performance by also handling
+// the compact printing case, merging these two together greatly simplifies the amount
+// of code we need to maintain so it seems worth it.
+let rec printElement = (
+  json: Json,
+  implHelper: JsonWriterConfig,
+  indentationLevel: Number,
+) => {
+  let buffer = implHelper.buffer
+  match (json) {
+    JsonNull => {
+      printNull(buffer)
+      return None
+    },
+    JsonBoolean(b) => {
+      printBool(b, buffer)
+      return None
+    },
+    JsonNumber(n) => return printNumber(n, buffer),
+    JsonString(s) => {
+      implHelper.emitEscapedQuotedString(s)
+      return None
+    },
+    JsonArray(elems) => {
+      match (elems) {
+        [] => {
+          Buffer.addChar('[', buffer)
+          if (implHelper.format.arrayFormat == SpacedArrayEntries) {
+            Buffer.addChar(' ', buffer)
+          }
+          Buffer.addChar(']', buffer)
+          return None
+        },
+        [e] => {
+          let format = implHelper.format
+
+          Buffer.addChar('[', buffer)
+
+          if (format.arrayFormat == OneArrayEntryPerLine) {
+            match (implHelper.printNewLine) {
+              Some(printNewLine) => printNewLine(),
+              None => void,
+            }
+          }
+
+          let elemLevel = indentationLevel + 1
+
+          if (format.arrayFormat == OneArrayEntryPerLine) {
+            match (implHelper.printIndentation) {
+              Some(printIndentation) => printIndentation(elemLevel),
+              None => void,
+            }
+          }
+
+          match (printElement(e, implHelper, elemLevel)) {
+            None => void,
+            err => return err,
+          }
+
+          if (format.arrayFormat == OneArrayEntryPerLine) {
+            match (implHelper.printNewLine) {
+              Some(printNewLine) => printNewLine(),
+              None => void,
+            }
+            match (implHelper.printIndentation) {
+              Some(printIndentation) => printIndentation(indentationLevel),
+              None => void,
+            }
+          }
+
+          Buffer.addChar(']', buffer)
+
+          return None
+        },
+        [initialHead, ...initialRest] => {
+          let format = implHelper.format
+
+          Buffer.addChar('[', buffer)
+
+          if (format.arrayFormat == OneArrayEntryPerLine) {
+            match (implHelper.printNewLine) {
+              Some(printNewLine) => printNewLine(),
+              None => void,
+            }
+          }
+
+          let mut currentHead = initialHead
+          let mut currentRest = initialRest
+
+          let elemLevel = indentationLevel + 1
+
+          for (let mut index = 0;; index += 1) {
+            if (index > 0) {
+              Buffer.addChar(',', buffer)
+              if (format.arrayFormat == SpacedArrayEntries) {
+                Buffer.addChar(' ', buffer)
+              }
+
+              if (format.arrayFormat == OneArrayEntryPerLine) {
+                match (implHelper.printNewLine) {
+                  Some(printNewLine) => printNewLine(),
+                  None => void,
+                }
+              }
+            }
+
+            if (format.arrayFormat == OneArrayEntryPerLine) {
+              match (implHelper.printIndentation) {
+                Some(printIndentation) => printIndentation(elemLevel),
+                None => void,
+              }
+            }
+
+            match (printElement(currentHead, implHelper, elemLevel)) {
+              None => void,
+              err => return err,
+            }
+
+            match (currentRest) {
+              [] => break,
+              [newHead, ...newRest] => {
+                currentHead = newHead
+                currentRest = newRest
+              },
+            }
+          }
+
+          if (format.arrayFormat == OneArrayEntryPerLine) {
+            match (implHelper.printNewLine) {
+              Some(printNewLine) => printNewLine(),
+              None => void,
+            }
+            match (implHelper.printIndentation) {
+              Some(printIndentation) => printIndentation(indentationLevel),
+              None => void,
+            }
+          }
+
+          Buffer.addChar(']', buffer)
+
+          return None
+        },
+      }
+    },
+    JsonObject(entries) => {
+      match (entries) {
+        [] => {
+          Buffer.addChar('{', buffer)
+          if (implHelper.format.objectFormat == SpacedObjectEntries) {
+            Buffer.addChar(' ', buffer)
+          }
+          Buffer.addChar('}', buffer)
+          return None
+        },
+        [(key, value)] => {
+          let format = implHelper.format
+
+          Buffer.addChar('{', buffer)
+
+          let elemLevel = indentationLevel + 1
+
+          if (format.objectFormat == OneObjectEntryPerLine) {
+            match (implHelper.printNewLine) {
+              Some(printNewLine) => printNewLine(),
+              None => void,
+            }
+            match (implHelper.printIndentation) {
+              Some(printIndentation) => printIndentation(elemLevel),
+              None => void,
+            }
+          }
+
+          implHelper.emitEscapedQuotedString(key)
+
+          Buffer.addChar(':', buffer)
+          match (format.objectFormat) {
+            CompactObjectEntries => void,
+            SpacedObjectEntries | OneObjectEntryPerLine => {
+              Buffer.addChar(' ', buffer)
+            },
+          }
+
+          match (printElement(value, implHelper, elemLevel)) {
+            None => void,
+            err => return err,
+          }
+
+          if (format.objectFormat == OneObjectEntryPerLine) {
+            match (implHelper.printNewLine) {
+              Some(printNewLine) => printNewLine(),
+              None => void,
+            }
+            match (implHelper.printIndentation) {
+              Some(printIndentation) => printIndentation(indentationLevel),
+              None => void,
+            }
+          }
+
+          Buffer.addChar('}', buffer)
+
+          return None
+        },
+        [initialHead, ...initialRest] => {
+          let format = implHelper.format
+
+          Buffer.addChar('{', buffer)
+
+          if (format.objectFormat == OneObjectEntryPerLine) {
+            match (implHelper.printNewLine) {
+              Some(printNewLine) => printNewLine(),
+              None => void,
+            }
+          }
+
+          let mut currentHead = initialHead
+          let mut currentRest = initialRest
+
+          let elemLevel = indentationLevel + 1
+
+          for (let mut index = 0;; index += 1) {
+            if (index > 0) {
+              Buffer.addChar(',', buffer)
+              if (format.objectFormat == SpacedObjectEntries) {
+                Buffer.addChar(' ', buffer)
+              }
+
+              if (format.objectFormat == OneObjectEntryPerLine) {
+                match (implHelper.printNewLine) {
+                  Some(printNewLine) => printNewLine(),
+                  None => void,
+                }
+              }
+            }
+
+            if (format.objectFormat == OneObjectEntryPerLine) {
+              match (implHelper.printIndentation) {
+                Some(printIndentation) => printIndentation(elemLevel),
+                None => void,
+              }
+            }
+
+            let (key, value) = currentHead
+
+            implHelper.emitEscapedQuotedString(key)
+
+            Buffer.addChar(':', buffer)
+            match (format.objectFormat) {
+              CompactObjectEntries => void,
+              SpacedObjectEntries | OneObjectEntryPerLine => {
+                Buffer.addChar(' ', buffer)
+              },
+            }
+
+            match (printElement(value, implHelper, elemLevel)) {
+              None => void,
+              err => return err,
+            }
+
+            match (currentRest) {
+              [] => break,
+              [newHead, ...newRest] => {
+                currentHead = newHead
+                currentRest = newRest
+              },
+            }
+          }
+
+          if (format.objectFormat == OneObjectEntryPerLine) {
+            match (implHelper.printNewLine) {
+              Some(printNewLine) => printNewLine(),
+              None => void,
+            }
+            match (implHelper.printIndentation) {
+              Some(printIndentation) => printIndentation(indentationLevel),
+              None => void,
+            }
+          }
+
+          Buffer.addChar('}', buffer)
+
+          return None
+        },
+      }
+    },
+  }
+}
+
+let isCodePointInBasicMultilingualPlane = (code: Number) =>
+  code >= 0x0000 && code <= 0xFFFF
+
+let isHighSurrogate = (code: Number) => code >= 0xD800 && code <= 0xDBFF
+
+let isLowSurrogate = (code: Number) => code >= 0xDC00 && code <= 0xDFFF
+
+let combineSurrogatePairToCodePoint = (
+  highSurrogate: Number,
+  lowSurrogate: Number,
+) => {
+  // If this was a method exposed by itself in a library then it should check the
+  // ranges of the input surrogates, but here it's necessary because checks are made
+  // as part of the parsing logic.
+  ((highSurrogate - 0xD800) << 10) + (lowSurrogate - 0xDC00) + 0x10000
+}
+
+let makeJsonWriter = (format: FormattingSettings, buffer: Buffer.Buffer) => {
+  let printNewLine = match (format.lineEnding) {
+    NoLineEnding => None,
+    LineFeed => Some(() => {
+      Buffer.addChar('\n', buffer)
+    }),
+    CarriageReturnLineFeed => Some(() => {
+      Buffer.addChar('\r', buffer)
+      Buffer.addChar('\n', buffer)
+    }),
+    CarriageReturn => Some(() => {
+      Buffer.addChar('\r', buffer)
+    }),
+  }
+
+  let printIndentation = match (format.indentation) {
+    IndentWithTab => Some(indentationLevel => {
+      for (let mut count = 0; count < indentationLevel; count += 1) {
+        Buffer.addChar('\t', buffer)
+      }
+    }),
+    // Implement fast path, for common indentation level to avoid closure
+    IndentWithSpaces(spacesPerIndentation) when spacesPerIndentation == 2 =>
+      Some(indentationLevel => {
+        let spaceCount = indentationLevel * 2
+        for (let mut count = 0; count < spaceCount; count += 1) {
+          Buffer.addChar(' ', buffer)
+        }
+      }),
+    // Implement fast path, for common indentation level to avoid closure
+    IndentWithSpaces(spacesPerIndentation) when spacesPerIndentation == 4 =>
+      Some(indentationLevel => {
+        let spaceCount = indentationLevel * 4
+        for (let mut count = 0; count < spaceCount; count += 1) {
+          Buffer.addChar(' ', buffer)
+        }
+      }),
+    IndentWithSpaces(spacesPerIndentation) => Some(indentationLevel => {
+      let spaceCount = indentationLevel * spacesPerIndentation
+      for (let mut count = 0; count < spaceCount; count += 1) {
+        Buffer.addChar(' ', buffer)
+      }
+    }),
+    NoIndentation => None,
+  }
+
+  // A possible optimization to make this faster would be to
+  // prepare a different closure for each combination of escaping options.
+  // This way unnecessary branching is avoided.
+  // The most important thing is that the non pretty printed format is optimized for
+  // as this is where the performance is most likely to matter.
+
+  // In every case code points 0..31 must be escaped as
+  // required by ECMA-404 (the so called "C0" control point group).
+
+  // For the non pretty printed case it is fastest to escape only what is
+  // strictly required to avoid increasing output size
+  // But for pretty printing or compatibility it may be desirable to escape other control points
+  // or even everything other than printable ASCII characters.
+  // for this reason options for this control has been exposed otherwise
+  // just a sane default would suffice.
+  // Additionally many JSON libraries escape additional two character
+  // sequences for direct embedding into html for example. This is
+  // specifically to avoid emitting the sequence "</" like in "</script>".
+  // The lazy approach would be to just escape the slash (which can become
+  // "\\/", not necessarily "\u002F"). This more conservative approach only
+  // escapes it when needed, but requires to keep track of the previous code
+  // point in the iteration so it's more complicated and handled separately.
+  let emitCodePoint = if (
+    !format.escapeAllControlPoints &&
+    !format.escapeNonASCII
+  ) {
+    (codePoint: Number) => {
+      if (codePoint > 31 && codePoint != 0x0022 && codePoint != 0x005C) {
+        Buffer.addCharFromCodePoint(codePoint, buffer)
+      } else {
+        emitEscapedCodePoint(codePoint, buffer)
+      }
+    }
+  } else if (!format.escapeAllControlPoints && format.escapeNonASCII) {
+    // If desired, escape all non ASCII code points. So the only non
+    // escaped code points are those in the range of ASCII characters
+    // from 31 to 127.
+    (codePoint: Number) => {
+      if (
+        codePoint > 31 &&
+        codePoint != 0x0022 &&
+        codePoint != 0x005C &&
+        codePoint < 128
+      ) {
+        Buffer.addCharFromCodePoint(codePoint, buffer)
+      } else {
+        emitEscapedCodePoint(codePoint, buffer)
+      }
+    }
+  } else if (format.escapeAllControlPoints && !format.escapeNonASCII) {
+    // If desired, in addition to the required 0..31 control points,
+    // also escape unicode control point group C1 (128-159).
+    // There could be more control points or otherwise escape worthy
+    // codepoints, but covering that would be overkill.
+    (codePoint: Number) => {
+      if (
+        codePoint > 31 &&
+          codePoint != 0x0022 &&
+          codePoint != 0x005C &&
+          codePoint < 127 ||
+        codePoint > 159
+      ) {
+        Buffer.addCharFromCodePoint(codePoint, buffer)
+      } else {
+        emitEscapedCodePoint(codePoint, buffer)
+      }
+    }
+  } else {
+    // And this is just the combination of both flags, which means
+    // doing almost the same as for the case above for
+    // escapeNonASCII=true, but also escape the ASCII control codepoint
+    // 127 (Delete).
+    (codePoint: Number) => {
+      if (
+        codePoint > 31 &&
+        codePoint != 0x0022 &&
+        codePoint != 0x005C &&
+        codePoint < 127
+      ) {
+        // fast path for chars that never need any escaping
+        Buffer.addCharFromCodePoint(codePoint, buffer)
+      } else {
+        emitEscapedCodePoint(codePoint, buffer)
+      }
+    }
+  }
+
+  let emitEscapedQuotedString = if (!format.escapeHTMLUnsafeSequences) {
+    (s: String) => {
+      Buffer.addChar('"', buffer)
+
+      // Note that it's important for performance that the closure passed to forEachCodePoint
+      // is not allocated inline here, but just once when creating the writer.
+
+      String.forEachCodePoint(emitCodePoint, s)
+
+      Buffer.addChar('"', buffer)
+    }
+  } else {
+    // Special handling for the escapeHTMLUnsafeSequences flag.
+    // Escaping a sequence requires keeping track of previous characters,
+    // which is difficult and suboptimal when using a function to iterate
+    // the input string. So we don't want to pay the price in other cases.
+    // This cannot be done just in the emitCodePoint function.
+    // It could be possible to implement more optimally, but would
+    // complicate things even more than this.
+    (s: String) => {
+      Buffer.addChar('"', buffer)
+
+      let mut prevCodePoint = 0
+
+      String.forEachCodePoint(codePoint => {
+        if (codePoint == 47) {
+          if (prevCodePoint == 60) {
+            Buffer.addChar('\\', buffer)
+            Buffer.addChar('/', buffer)
+          } else {
+            // otherwise just emit the slash as-is
+            Buffer.addChar('/', buffer)
+          }
+        } else {
+          emitCodePoint(codePoint)
+        }
+
+        prevCodePoint = codePoint
+      }, s)
+
+      Buffer.addChar('"', buffer)
+    }
+  }
+
+  let implHelper = {
+    format,
+    buffer,
+    emitEscapedQuotedString,
+    printNewLine,
+    printIndentation,
+  }: JsonWriterConfig
+
+  { emit: json => {
+    match (printElement(json, implHelper, 0)) {
+      None => void,
+      err => return err,
+    }
+    if (format.finishWithNewLine) {
+      match (printNewLine) {
+        Some(printNewLine) => printNewLine(),
+        None => void,
+      }
+    }
+    return None
+  }, }: JsonWriter
+}
+
+/**
+ * Converts the `Json` data structure into a JSON string with specific formatting settings.
+ *
+ * @param format: Formatting options
+ * @param json: The `Json` data structure to convert
+ * @returns `Ok(str)` containing the JSON string or `Err(err)` if the provided `Json` data structure cannot be converted to a string
+ *
+ * @example
+ * assert toString(
+ *   JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))]
+ * ) == Ok("{\"currency\":\"€\",\"price\":99.9}")
+ * @example
+ * assert toString(
+ *   format=Compact
+ *   JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))])
+ * ) == Ok("{\"currency\":\"€\",\"price\":99.9}")
+ * @example
+ * assert toString(
+ *   format=Pretty,
+ *   JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))])
+ * ) == Ok("{
+ *   \"currency\": \"€\",
+ *   \"price\": 99.9
+ * }")
+ * @example
+ * assert toString(
+ *   format=Custom{
+ *     indentation: NoIndentation,
+ *     arrayFormat: CompactArrayEntries,
+ *     objectFormat: CompactObjectEntries,
+ *     lineEnding: NoLineEnding,
+ *     finishWithNewLine: false,
+ *     escapeAllControlPoints: true,
+ *     escapeHTMLUnsafeSequences: true,
+ *     escapeNonASCII: true,
+ *   },
+ *   JsonObject([("currency", JsonString("€")), ("price", JsonNumber(99.9))])
+ * ) == Ok("{\"currency\":\"\\u20ac\",\"price\":99.9}")
+ *
+ * @since v0.6.0
+ */
+provide let toString = (format=Compact, json: Json) => {
+  let buf = Buffer.make(16)
+  let format = match (format) {
+    Pretty =>
+      {
+        indentation: IndentWithSpaces(2),
+        arrayFormat: OneArrayEntryPerLine,
+        objectFormat: OneObjectEntryPerLine,
+        lineEnding: LineFeed,
+        finishWithNewLine: true,
+        escapeAllControlPoints: true,
+        escapeHTMLUnsafeSequences: false,
+        escapeNonASCII: false,
+      },
+    Compact =>
+      {
+        indentation: NoIndentation,
+        arrayFormat: CompactArrayEntries,
+        objectFormat: CompactObjectEntries,
+        lineEnding: NoLineEnding,
+        finishWithNewLine: false,
+        escapeAllControlPoints: false,
+        escapeHTMLUnsafeSequences: false,
+        escapeNonASCII: false,
+      },
+    PrettyAndSafe =>
+      {
+        indentation: IndentWithSpaces(2),
+        arrayFormat: OneArrayEntryPerLine,
+        objectFormat: OneObjectEntryPerLine,
+        lineEnding: LineFeed,
+        finishWithNewLine: true,
+        escapeAllControlPoints: true,
+        escapeHTMLUnsafeSequences: true,
+        escapeNonASCII: true,
+      },
+    CompactAndSafe =>
+      {
+        indentation: NoIndentation,
+        arrayFormat: CompactArrayEntries,
+        objectFormat: CompactObjectEntries,
+        lineEnding: NoLineEnding,
+        finishWithNewLine: false,
+        escapeAllControlPoints: true,
+        escapeHTMLUnsafeSequences: true,
+        escapeNonASCII: true,
+      },
+    Custom{
+      indentation,
+      arrayFormat,
+      objectFormat,
+      lineEnding,
+      finishWithNewLine,
+      escapeAllControlPoints,
+      escapeHTMLUnsafeSequences,
+      escapeNonASCII,
+    } =>
+      {
+        indentation,
+        arrayFormat,
+        objectFormat,
+        lineEnding,
+        finishWithNewLine,
+        escapeAllControlPoints,
+        escapeHTMLUnsafeSequences,
+        escapeNonASCII,
+      },
+  }
+  let writer = makeJsonWriter(format, buf)
+  let error = writer.emit(json)
+
+  match (error) {
+    None => Ok(Buffer.toString(buf)),
+    Some(e) => Err(e),
+  }
+}
+
+/**
+ * Represents errors for JSON parsing along with a human readable message.
+ */
+provide enum JsonParseError {
+  UnexpectedEndOfInput(String),
+  UnexpectedToken(String),
+  InvalidUTF16SurrogatePair(String),
+}
+
+/*
+ * Internal data structure used during parsing.
+ */
+record JsonParserState {
+  string: String,
+  bufferParse: Buffer.Buffer,
+  mut currentCodePoint: Number,
+  mut pos: Number,
+  mut bytePos: Number,
+}
+
+let isInterTokenWhiteSpace = (codePoint: Number) => {
+  match (codePoint) {
+    0x0009 => true, // tab
+    0x000A => true, // line feed
+    0x000D => true, // carriage return
+    0x0020 => true, // space
+    _ => false,
+  }
+}
+
+let _END_OF_INPUT = -1
+
+@unsafe
+let rec readCodePoint = (bytePosition: Number, string: String) => {
+  use WasmI32.{ (+), (<) }
+
+  let strPtr = WasmI32.fromGrain(string)
+
+  let byteSize = WasmI32.load(strPtr, 4n)
+
+  let bytePositionW32 = coerceNumberToWasmI32(bytePosition)
+
+  let ptr = strPtr + 8n + bytePositionW32
+
+  if (bytePositionW32 < byteSize) {
+    let codePoint = getCodePoint(ptr)
+    tagSimpleNumber(codePoint)
+  } else {
+    _END_OF_INPUT
+  }
+}
+
+let codePointUTF8ByteCount = (usv: Number) => {
+  if (!Char.isValid(usv)) {
+    fail "Impossible: JSON parser encountered an invalid unicode scalar value in codePointUTF8ByteCount"
+  }
+
+  if (usv <= 0x7f) {
+    1
+  } else if (usv <= 0x7ff) {
+    2
+  } else if (usv <= 0xffff) {
+    3
+  } else {
+    4
+  }
+}
+
+let isAtEndOfInput = (parserState: JsonParserState) => {
+  parserState.currentCodePoint == _END_OF_INPUT
+}
+
+let next = (parserState: JsonParserState) => {
+  let mut c = parserState.currentCodePoint
+  if (c != _END_OF_INPUT) {
+    parserState.bytePos += codePointUTF8ByteCount(c)
+
+    c = readCodePoint(parserState.bytePos, parserState.string)
+
+    parserState.currentCodePoint = c
+    parserState.pos += 1
+  }
+  c
+}
+
+let skipWhiteSpace = (parserState: JsonParserState) => {
+  // isAtEndOfInput is not strictly necessary here
+  // could remove as an optimization
+  while (
+    isInterTokenWhiteSpace(parserState.currentCodePoint) &&
+    !isAtEndOfInput(parserState)
+  ) {
+    next(parserState)
+    void
+  }
+}
+
+let buildUnexpectedTokenError = (parserState: JsonParserState, detail: String) => {
+  let codePoint = parserState.currentCodePoint
+  let pos = parserState.pos
+  if (codePoint == _END_OF_INPUT) {
+    UnexpectedEndOfInput(
+      "Unexpected token at position " ++ runtimeToString(pos) ++ ": " ++ detail,
+    )
+  } else {
+    UnexpectedToken(
+      "Unexpected token at position " ++ runtimeToString(pos) ++ ": " ++ detail,
+    )
+  }
+}
+
+@unsafe
+let toHex = (n: Number) => {
+  let x = coerceNumberToWasmI32(n)
+  NumberUtils.itoa32(x, 16n)
+}
+
+let toHexWithZeroPadding = (n: Number, padTo: Number) => {
+  // Note that this function is only called in exceptional cases so no effort
+  // was made to optimize it.
+  let mut result = toHex(n)
+  for (let mut i = String.length(result); i < padTo; i += 1) {
+    result = "0" ++ result
+  }
+  result
+}
+
+let formatCodePointOrEOF = (codePoint: Number) => {
+  if (codePoint >= 32 && codePoint <= 126) {
+    // If the codepoint is in the range of printable ASCII characters, then
+    // display the character itself . Whether it's a good idea to display
+    // all of them, especially space is up for debate.
+    "'" ++ Char.toString(Char.fromCode(codePoint)) ++ "'"
+  } else if (codePoint == -1) {
+    // Special case for value used by the parsing code to avoid heap allocations.
+    "end of input"
+  } else {
+    // Format any other code point as hexadecimal value.
+    "U+" ++ toHexWithZeroPadding(codePoint, 4)
+  }
+}
+
+let expectCodePointAndAdvance = (
+  expectedCodePoint: Number,
+  parserState: JsonParserState,
+) => {
+  let c = parserState.currentCodePoint
+  if (c == expectedCodePoint) {
+    next(parserState)
+    None
+  } else {
+    let detail = "expected " ++
+      formatCodePointOrEOF(expectedCodePoint) ++
+      ", found " ++
+      formatCodePointOrEOF(c)
+    Some(buildUnexpectedTokenError(parserState, detail))
+  }
+}
+let atoiFast = buffer => {
+  let bufLen = Buffer.length(buffer)
+  let mut result = 0
+  for (let mut i = 0; i < bufLen; i += 1) {
+    use Uint8.{ (-) }
+    result = (result << 1) +
+      (result << 3) +
+      Uint8.toNumber(Buffer.getUint8(i, buffer) - 48us)
+  }
+  result
+}
+let rec parseValue = (parserState: JsonParserState) => {
+  skipWhiteSpace(parserState)
+
+  let result = match (parserState.currentCodePoint) {
+    0x7B => parseObject(parserState), // '{'
+    0x5B => parseArray(parserState), // '['
+    0x22 => parseStringValue(parserState), // '"'
+    0x74 => parseTrueValue(parserState), // 't'
+    0x66 => parseFalseValue(parserState), // 'f'
+    0x6E => parseNullValue(parserState), // 'n'
+    // Numbers
+    0x30 => parseNumberValue(parserState), // '0'
+    0x31 => parseNumberValue(parserState), // '1'
+    0x32 => parseNumberValue(parserState), // '2'
+    0x33 => parseNumberValue(parserState), // '3'
+    0x34 => parseNumberValue(parserState), // '4'
+    0x35 => parseNumberValue(parserState), // '5'
+    0x36 => parseNumberValue(parserState), // '6'
+    0x37 => parseNumberValue(parserState), // '7'
+    0x38 => parseNumberValue(parserState), // '8'
+    0x39 => parseNumberValue(parserState), // '9'
+    0x2D => parseNumberValue(parserState), // '-'
+    c => {
+      let detail = "expected start of a JSON value, found " ++
+        formatCodePointOrEOF(c)
+      Err(buildUnexpectedTokenError(parserState, detail))
+    },
+  }
+
+  skipWhiteSpace(parserState)
+
+  result
+}
+and parseNullValue = (parserState: JsonParserState) => {
+  match (expectCodePointAndAdvance(0x6E, parserState)) {
+    // 'n'
+    Some(e) => Err(e),
+    None => {
+      match (expectCodePointAndAdvance(0x75, parserState)) {
+        // 'u'
+        Some(e) => Err(e),
+        None => {
+          match (expectCodePointAndAdvance(0x6C, parserState)) {
+            // 'l'
+            Some(e) => Err(e),
+            None => {
+              match (expectCodePointAndAdvance(0x6C, parserState)) {
+                // 'l'
+                Some(e) => Err(e),
+                None => Ok(JsonNull),
+              }
+            },
+          }
+        },
+      }
+    },
+  }
+}
+and parseTrueValue = (parserState: JsonParserState) => {
+  match (expectCodePointAndAdvance(0x74, parserState)) {
+    // 't'
+    Some(e) => Err(e),
+    None => {
+      match (expectCodePointAndAdvance(0x72, parserState)) {
+        // 'r'
+        Some(e) => Err(e),
+        None => {
+          match (expectCodePointAndAdvance(0x75, parserState)) {
+            // 'u'
+            Some(e) => Err(e),
+            None => {
+              match (expectCodePointAndAdvance(0x65, parserState)) {
+                // 'e'
+                Some(e) => Err(e),
+                None => Ok(JsonBoolean(true)),
+              }
+            },
+          }
+        },
+      }
+    },
+  }
+}
+and parseFalseValue = (parserState: JsonParserState) => {
+  match (expectCodePointAndAdvance(0x66, parserState)) {
+    // 'f'
+    Some(e) => Err(e),
+    None => {
+      match (expectCodePointAndAdvance(0x61, parserState)) {
+        // 'a'
+        Some(e) => Err(e),
+        None => {
+          match (expectCodePointAndAdvance(0x6C, parserState)) {
+            // 'l'
+            Some(e) => Err(e),
+            None => {
+              match (expectCodePointAndAdvance(0x73, parserState)) {
+                // 's'
+                Some(e) => Err(e),
+                None => {
+                  match (expectCodePointAndAdvance(0x65, parserState)) {
+                    // 'e'
+                    Some(e) => Err(e),
+                    None => Ok(JsonBoolean(false)),
+                  }
+                },
+              }
+            },
+          }
+        },
+      }
+    },
+  }
+}
+and parseString = (parserState: JsonParserState) => {
+  match (expectCodePointAndAdvance(0x22, parserState)) {
+    // '"'
+    Some(e) => return Err(e),
+    None => {
+      let mut done = false
+      let buffer = parserState.bufferParse
+      Buffer.clear(buffer)
+
+      while (!done) {
+        match (parserState.currentCodePoint) {
+          0x22 => { // '"'
+            next(parserState)
+            done = true
+            break
+          },
+          -1 => {
+            // just end the loop without setting done to true
+            break
+          },
+          0x5C => { // '\'
+            // Keep the starting position for better error reporting.
+            let escapeStartPos = parserState.pos
+
+            next(parserState)
+
+            match (parserState.currentCodePoint) {
+              0x22 => { // '"'
+                Buffer.addChar('"', buffer)
+                ignore(next(parserState))
+              },
+              0x5C => { // '\'
+                Buffer.addChar('\\', buffer)
+                ignore(next(parserState))
+              },
+              0x2F => { // '/'
+                Buffer.addChar('/', buffer)
+                ignore(next(parserState))
+              },
+              0x62 => { // letter 'b' as in Backspace
+                // emit backspace control code
+                Buffer.addChar('\u{08}', buffer)
+                ignore(next(parserState))
+              },
+              0x66 => { // letter 'f' as in Form Feed
+                // emit Form Feed control code
+                Buffer.addChar('\u{0C}', buffer)
+                ignore(next(parserState))
+              },
+              0x6E => { // letter 'n' as in New line
+                // emit Line Feed control code
+                Buffer.addChar('\u{0A}', buffer)
+                ignore(next(parserState))
+              },
+              0x72 => { // letter 'r' as in carriage Return
+                // emit Carriage Return control code
+                Buffer.addChar('\u{0D}', buffer)
+                ignore(next(parserState))
+              },
+              0x74 => { // letter 't' as in Tab
+                // emit Tab control code
+                Buffer.addChar('\u{09}', buffer)
+                ignore(next(parserState))
+              },
+              0x75 => { // 'u' (start of hexadecimal UTF-16 escape sequence)
+                next(parserState)
+
+                // The escape sequence can either be a standalone code point or
+                // a UTF-16 surrogate pair made of two code units that have to
+                // be combined to form a code point. This is legacy of
+                // JavaScript's UTF-16 string representation, despite JSON
+                // mandating UTF-8 (kind of, as stated in rfc8259: "JSON text
+                // exchanged between systems that are not part of a closed
+                // ecosystem MUST be encoded using UTF-8").
+                // This would be easy to do using a function for shared logic,
+                // but in order to avoid heap allocation I've chosen to instead
+                // use a loop and local state.
+
+                let mut highSurrogate = -1
+
+                while (true) {
+                  let mut codeUnit = 0
+
+                  for (
+                    let mut digitIndex = 3;
+                    digitIndex >= 0;
+                    digitIndex -= 1
+                  ) {
+                    let hexDigitCodePoint = parserState.currentCodePoint
+
+                    let mut digit = hexDigitCodePoint
+
+                    if (hexDigitCodePoint >= 48 && hexDigitCodePoint <= 57) { // 0..9
+                      digit -= 48
+                    } else if (
+                      hexDigitCodePoint >= 65 &&
+                      hexDigitCodePoint <= 70
+                    ) { // A..F
+                      digit -= 55 // (65 - 10)
+                    } else if (
+                      hexDigitCodePoint >= 97 &&
+                      hexDigitCodePoint <= 102
+                    ) { // a..f
+                      digit -= 87 // (97 - 10)
+                    } else {
+                      let digitsSoFar = 3 - digitIndex
+                      let detail =
+                        "expected exactly 4 hexadecimal digits in the UTF-16 escape sequence, found only " ++
+                          runtimeToString(digitsSoFar)
+                      return Err(buildUnexpectedTokenError(parserState, detail))
+                    }
+
+                    let shift = digitIndex * 4
+                    codeUnit = codeUnit | digit << shift
+
+                    ignore(next(parserState))
+                  }
+
+                  if (highSurrogate == -1) {
+                    // This is the first iteration of the loop.
+                    // The code unit should either be the high surrogate of the
+                    // pair or a full code point in the Basic Multilingual
+                    // Plane (U+0000..U+FFFF).
+                    if (isHighSurrogate(codeUnit)) {
+                      // Next characters should be "\u"
+                      // '\'
+                      match (expectCodePointAndAdvance(0x5C, parserState)) {
+                        Some(e) => return Err(e),
+                        None => void,
+                      }
+                      // 'u'
+                      match (expectCodePointAndAdvance(0x75, parserState)) {
+                        Some(e) => return Err(e),
+                        None => void,
+                      }
+
+                      // Keep the high surrogate and proceed to the second
+                      // iteration of the loop.
+                      highSurrogate = codeUnit
+                    } else if (
+                      isCodePointInBasicMultilingualPlane(codeUnit) &&
+                      !isLowSurrogate(codeUnit)
+                    ) {
+                      let codePoint = codeUnit
+                      Buffer.addCharFromCodePoint(codePoint, buffer)
+                      break
+                    } else {
+                      let message =
+                        "Invalid character escape sequence at position " ++
+                          runtimeToString(escapeStartPos) ++
+                          ": expected a Unicode code point in Basic Multilingual Plane (U+0000..U+FFFF) or a high surrogate (0xD800..0xDBFF) of a UTF-16 surrogate pair, found " ++
+                          "0x" ++
+                          toHexWithZeroPadding(codeUnit, 4)
+                      return Err(InvalidUTF16SurrogatePair(message))
+                    }
+                  } else {
+                    // This is the second iteration of the loop.
+                    // The code unit should be the low surrogate of the pair.
+                    if (isLowSurrogate(codeUnit)) {
+                      let lowSurrogate = codeUnit
+                      let combinedCodePoint = combineSurrogatePairToCodePoint(
+                        highSurrogate,
+                        lowSurrogate
+                      )
+                      Buffer.addCharFromCodePoint(combinedCodePoint, buffer)
+                      break
+                    } else {
+                      let message =
+                        "Invalid character escape sequence at position " ++
+                          runtimeToString(escapeStartPos) ++
+                          ": expected a low surrogate (0xDC00..0xDFFF) in the second code unit of the UTF-16 sequence, found " ++
+                          "0x" ++
+                          toHexWithZeroPadding(codeUnit, 4)
+                      return Err(InvalidUTF16SurrogatePair(message))
+                    }
+                  }
+                }
+              },
+              unexpectedCodePoint => {
+                // JSON doesn't allow arbitrary characters to be preceded by backslash escape.
+                // Only the ones above.
+                let detail =
+                  "expected a valid escape sequence or the end of string, found " ++
+                    formatCodePointOrEOF(unexpectedCodePoint)
+                return Err(buildUnexpectedTokenError(parserState, detail))
+              },
+            }
+          },
+          c => {
+            if (c >= 0x00 && c <= 0x1F) {
+              return Err(
+                buildUnexpectedTokenError(
+                  parserState,
+                  "Bad control character in string literal"
+                ),
+              )
+            }
+            // Finally the happy case of a simple unescaped code point.
+            next(parserState)
+            Buffer.addCharFromCodePoint(c, buffer)
+          },
+        }
+      }
+
+      if (done) {
+        let s = Buffer.toString(buffer)
+        return Ok(s)
+      } else {
+        return Err(
+          buildUnexpectedTokenError(
+            parserState,
+            "unexpected end of string value"
+          ),
+        )
+      }
+    },
+  }
+}
+and parseStringValue = (parserState: JsonParserState) => {
+  match (parseString(parserState)) {
+    Ok(s) => Ok(JsonString(s)),
+    Err(e) => Err(e),
+  }
+}
+and parseNumberValue = (parserState: JsonParserState) => {
+  // TODO(#1878): Use a streaming-optimized way to parse numbers
+  let buffer = parserState.bufferParse
+  Buffer.clear(buffer)
+  // First char can optionally be a minus sign.
+  let mut c = parserState.currentCodePoint
+  let mut isFloat = false
+  let isNegative = c == 0x2D
+  // '-'
+  if (isNegative) {
+    c = next(parserState)
+  }
+
+  // After that, the first/second char can only be a decimal digit ('0'..'9').
+  match (c) {
+    0x30 => { // '0'
+      // JSON doesn't allow numbers with additional leading zeros like
+      // "01". Which means that if a number starts with zero then the
+      // integer part is just zero and the next one can only be one of
+      // '.', 'e' or 'E'. In any case all that needs to be done here is
+      // to advance over the zero character and proceed to the optional
+      // fractional and exponential parts. If another digit follows then
+      // a parsing error will occur as expected, but implicitly because
+      // this function finishes with the parser positioned on a digit
+      // and not on a token expected after a number like ',', ']', '}' or
+      // EOF.
+      Buffer.addCharFromCodePoint(c, buffer)
+      c = next(parserState)
+    },
+    x when x >= 0x31 && x <= 0x39 => { // '1'..'9'
+      while (true) {
+        Buffer.addCharFromCodePoint(c, buffer)
+        c = next(parserState)
+        if (c < 0x30 || c > 0x39) {
+          break
+        }
+      }
+    },
+    unexpectedCodePoint => {
+      // The integer part of the number has to have at least one digit.
+      // JSON doesn't allow numbers starting with decimal separator like ".1".
+      let detail = "expected a decimal digit, found " ++
+        formatCodePointOrEOF(unexpectedCodePoint)
+      return Err(buildUnexpectedTokenError(parserState, detail))
+    },
+  }
+  // Optional fractional part of the number.
+  if (c == 0x2E) { // '.'
+    isFloat = true
+    Buffer.addChar('.', buffer)
+    c = next(parserState)
+    let mut hasHitDigit = false
+    for (; c >= 0x30 && c <= 0x39;) {
+      hasHitDigit = true
+      Buffer.addCharFromCodePoint(c, buffer)
+      c = next(parserState)
+    }
+    if (!hasHitDigit)
+      return Err(
+        buildUnexpectedTokenError(
+          parserState,
+          "exponent part is missing in number"
+        ),
+      )
+  }
+  // Optional exponential part of the number.
+  if (c == 0x65 || c == 0x45) { // 'e' or 'E'
+    isFloat = true
+    Buffer.addChar('e', buffer)
+    c = next(parserState)
+    // can start with optional plus or minus sign
+    match (c) {
+      0x2D => { // '-'
+        c = next(parserState)
+        Buffer.addChar('-', buffer)
+      },
+      0x2B => { // '+'
+        c = next(parserState)
+      },
+      _ => void,
+    }
+    // followed by one or more digits (0-9)
+    let mut hasHitDigit = false
+    for (; c >= 0x30 && c <= 0x39;) {
+      hasHitDigit = true
+      Buffer.addCharFromCodePoint(c, buffer)
+      c = next(parserState)
+    }
+    if (!hasHitDigit)
+      return Err(
+        buildUnexpectedTokenError(
+          parserState,
+          "exponent part is missing in number"
+        ),
+      )
+  }
+  // Note that unlike all other JSON value types there's no explicit ending
+  // character like ('"' for strings, ']' for arrays,'}' for objects etc). We
+  // just leave the parser state at current position and the reading of next
+  // token will succeed or fail, but number parsing just ends here.
+  let result = match (isFloat) {
+    false => atoiFast(buffer),
+    true => {
+      let str = Buffer.toString(buffer)
+      match (Atof.parseFloat(str)) {
+        Err(err) => fail "Impossible: Json parse float on invalid float",
+        Ok(n) => n,
+      }
+    },
+  }
+  if (result == 0 && isNegative)
+    return Ok(JsonNumber(-0.0))
+  else
+    return Ok(JsonNumber(if (isNegative) result * -1 else result))
+}
+and parseArray = (parserState: JsonParserState) => {
+  match (expectCodePointAndAdvance(0x5B, parserState)) {
+    // '['
+    Some(e) => return Err(e),
+    None => {
+      skipWhiteSpace(parserState)
+
+      let mut elems = []: List<Json>
+
+      let mut done = false
+      let mut first = true
+      let mut trailingComma = false
+      while (!done) {
+        let c = parserState.currentCodePoint
+        match (c) {
+          0x2C => { // ','
+            if (first) {
+              return Err(
+                buildUnexpectedTokenError(
+                  parserState,
+                  "unexpected comma at beginning of array"
+                ),
+              )
+            }
+            trailingComma = true
+            next(parserState)
+            skipWhiteSpace(parserState)
+          },
+          0x5D => { // ']'
+            next(parserState)
+            done = true
+            break
+          },
+          -1 => {
+            // just end the loop without setting done to true
+            break
+          },
+          _ => {
+            // note that parseValue skips initial and final whitespace
+            match (parseValue(parserState)) {
+              Ok(elem) => {
+                first = false
+                trailingComma = false
+                elems = [elem, ...elems]
+              },
+              Err(e) => return Err(e),
+            }
+          },
+        }
+      }
+
+      if (trailingComma) {
+        return Err(
+          buildUnexpectedTokenError(parserState, "unexpected end of array"),
+        )
+      } else if (done) {
+        return Ok(JsonArray(List.reverse(elems)))
+      } else {
+        return Err(
+          buildUnexpectedTokenError(parserState, "unexpected end of array"),
+        )
+      }
+    },
+  }
+}
+and parseObject = (parserState: JsonParserState) => {
+  match (expectCodePointAndAdvance(0x7B, parserState)) {
+    // '{'
+    Some(e) => return Err(e),
+    None => {
+      let mut entries = []: List<(String, Json)>
+
+      let mut done = false
+      let mut first = true
+
+      // one iteration of this loop should correspond to a key-value pair
+      let mut trailingComma = false
+      while (!done) {
+        skipWhiteSpace(parserState)
+
+        let c = parserState.currentCodePoint
+        match (c) {
+          -1 => {
+            let detail = "expected a key-value pair or the end of the object"
+            return Err(buildUnexpectedTokenError(parserState, detail))
+          },
+          0x2C => { // ','
+            trailingComma = true
+            if (first) {
+              let detail =
+                "expected a key-value pair or the end of the object, found ','"
+              return Err(buildUnexpectedTokenError(parserState, detail))
+            } else {
+              ignore(next(parserState))
+            }
+          },
+          0x7D => { // '}'
+            if (trailingComma) {
+              let detail = "unexpected trailing comma in object"
+              return Err(buildUnexpectedTokenError(parserState, detail))
+            }
+            next(parserState)
+            done = true
+            break
+          },
+          _ => {
+            trailingComma = false
+            // A new entry in current object.
+            // Just call parseString directly. In case the current character id not '"', it will return an error we can pass along.
+            match (parseString(parserState)) {
+              Ok(key) => {
+                skipWhiteSpace(parserState)
+
+                match (expectCodePointAndAdvance(0x3A, parserState)) {
+                  // ':'
+                  None => {
+                    // note that parseValue skips initial and final whitespace
+                    match (parseValue(parserState)) {
+                      Ok(value) => {
+                        entries = [(key, value), ...entries]
+                        first = false
+                      },
+                      Err(e) => return Err(e),
+                    }
+                  },
+                  Some(e) => return Err(e),
+                }
+              },
+              Err(e) => return Err(e),
+            }
+          },
+        }
+      }
+      // end of entry loop
+
+      if (done) {
+        return Ok(JsonObject(List.reverse(entries)))
+      } else {
+        // This branch is not expected to actually execute,
+        // but in case it does, may just as well do the right thing.
+        return Err(
+          buildUnexpectedTokenError(parserState, "unexpected end of object"),
+        )
+      }
+    },
+  }
+}
+
+/**
+ * Parses JSON string into a `Json` data structure.
+ *
+ * @param str: The JSON string to parse
+ * @returns `Ok(json)` containing the parsed data structure on a successful parse or `Err(err)` containing a parse error otherwise
+ *
+ * @example
+ * assert parse("{\"currency\":\"$\",\"price\":119}") == Ok(
+ *  JsonObject([
+ *    ("currency", JsonString("$")),
+ *    ("price", JsonNumber(119))
+ *  ])
+ * )
+ *
+ * @since v0.6.0
+ */
+provide let parse: (str: String) => Result<Json, JsonParseError> = (str: String) => {
+  let parserState = {
+    string: str,
+    bufferParse: Buffer.make(16),
+    currentCodePoint: readCodePoint(0, str),
+    pos: 0,
+    bytePos: 0,
+  }: JsonParserState
+
+  let root = parseValue(parserState)
+
+  skipWhiteSpace(parserState)
+
+  if (isAtEndOfInput(parserState)) {
+    root
+  } else {
+    match (root) {
+      Ok(_) => {
+        let detail = "expected end of input, found " ++
+          formatCodePointOrEOF(parserState.currentCodePoint)
+        Err(buildUnexpectedTokenError(parserState, detail))
+      },
+      e => e,
+    }
+  }
+}