json.gr

/**
 * @module Json: JSON (JavaScript Object Notation) parsing and printing.
 */

import String from "string"
import Char from "char"
import List from "list"
import Option from "option"
import Number from "number"
import WasmI32 from "runtime/unsafe/wasmi32"
import WasmI64 from "runtime/unsafe/wasmi64"
import WasmF32 from "runtime/unsafe/wasmf32"
import WasmF64 from "runtime/unsafe/wasmf64"
import NumberUtils from "runtime/numberUtils"
import Tags from "runtime/unsafe/tags"
import Numbers from "runtime/numbers"
import Memory from "runtime/unsafe/memory"
import StringReader from "./stringreader"
import Buffer from "buffer"
import { toString as runtimeToString } from "runtime/string"
import { coerceNumberToWasmI32 } from "runtime/numbers"

/**
 * Data structure representing the result of parsing and the input of printing
 * JSON.
 * 
 * For example this object
 * ```grain
 * JSONObject([
 *   ("currency", JSONString("€")),
 *   ("price", JSONNumber(99.99)),
 * ])
 * ```
 * is equivalent to the following JSON:
 * ```json
 * {"currency":"€","price":99.99}
 * ```
 * 
 * This data structure is semantically equivalent to the JSON format allowing
 * mostly lossless round trips of printing and parsing. Exceptions to this are
 * white spaces, multiple ways JSON allows escaping characters in strings and
 * some edge-cases related to Grain's `Number` type.
 * 
 * For example parsing the following JSON text will also result in the same
 * `JSON` object as above.
 * ```json
 * {
 *   "currency": "\u20ac",
 *   "price": 99.99
 * }
 * ```
 */
export enum JSON {
  JSONNull,
  JSONBoolean(Bool),
  JSONNumber(Number),
  JSONString(String),
  // Here I've chosen to use a List and not an array as a conscious trade of performance for immutability.
  // I'd love to use a more advanced persistent collection instead, but there currently aren't any in Grain.
  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 accomodate 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 vastly simplifies implementation and has the benefit of List's immutability.
  JSONObject(List<(String, JSON)>),
}

/**
 * Represents errors for cases when a `JSON` object cannot be represente in the
 * JSON format along with a human readable text message. This can happen when
 * it contains number values `NaN`, `Infinity` or `-Infinity`.
 */
export enum JSONToStringError {
  InvalidNumber(String),
}

/**
 * Controls how indentation is performed in custom formatting.
 * 
 * Following examples have whitespaces and line breaks replaced with visible
 * charactes for illustrative purposes.
 * 
 * `NoIndentation`
 * ```
 * {↵
 * "currency":·"€",↵
 * "price":·99.9↵
 * }
 * ```
 * 
 * `IndentWithTab`
 * ```
 * {↵
 * →"currency":·"€",↵
 * →"price":·99.9↵
 * }
 * ```
 * 
 * `IndentWithSpaces(2)`
 * ```
 * {↵
 * ··"currency":·"€",↵
 * ··"price":·99.9↵
 * }
 * ```
 * 
 * `IndentWithSpaces(4)`
 * ```
 * {↵
 * ····"currency":·"€",↵
 * ····"price":·99.9↵
 * }
 * ```
 */
export enum IndentationFormat {
  NoIndentation,
  IndentWithTab,
  IndentWithSpaces(Number),
}

/**
 * Controls how arrays are printed in custom formatting.
 * 
 * Following examples have whitespaces and line breaks replaced with visible
 * charactes for illustrative purposes.
 * 
 * `CompactArrayEntries`
 * ```
 * []
 * ```
 * 
 * ```
 * [1]
 * ```
 * 
 * ```
 * [1,2,3]
 * ```
 * 
 * `OneArrayEntryPerLine`
 * ```
 * []
 * ```
 * 
 * ```
 * [↵
 * ··1↵
 * ]
 * ```
 * 
 * ```
 * [↵
 * ··1,↵
 * ··2,↵
 * ··3↵
 * ]
 * ```
 */
export enum ArrayFormat {
  CompactArrayEntries,
  OneArrayEntryPerLine,
}

/**
 * Controls how objects are printed in custom formatting.
 * 
 * Following examples have whitespaces and line breaks replaced with visible
 * charactes for illustrative purposes.
 * 
 * `CompactObjectEntries`
 * ```
 * {}
 * ```
 * 
 * ```
 * {"a":1}
 * ```
 * 
 * ```
 * {"a":1,"b":2,"c":3}
 * ```
 * 
 * `OneObjectEntryPerLine`
 * ```
 * {}
 * ```
 * 
 * ```
 * {↵
 * ··"a":·1↵
 * }
 * ```
 * 
 * ```
 * {↵
 * ··"a":·1,↵
 * ··"b":·2,↵
 * ··"c":·3↵
 * }
 * ```
 */
export enum ObjectFormat {
  CompactObjectEntries,
  OneObjectEntryPerLine,
}

/**
 * Controls line ending type in custom formatting.
 */
export enum LineEnding {
  NoLineEnding,
  LineFeed,
  CarriageReturnLineFeed,
  CarriageReturn,
}

/**
 * Allows fine grained control of formatting in JSON printing.
 */
export record FormattingSettings {
  indentation: IndentationFormat,
  arrayFormat: ArrayFormat,
  objectFormat: ObjectFormat,
  lineEnding: LineEnding,
  finishWithNewLine: Bool,
  escapeAllControlPoints: Bool,
  escapeHTMLUnsafeSequences: Bool,
  escapeNonASCII: Bool,
}

/**
 * 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.
 * 
 * The following example have whitespaces, line breaks and control points
 * replaced with visible characters.
 * ```
 * {"currency":"€","price":99.9,"currencyDescription":"EURO␡","script·unembeddable":"You·cannot·pase·a·JSON·object·directly·into·a·<script>·tag·in·HTML·if·it·contains·</·with·unescaped·forward·slash"}
 * ```
 */
export let defaultCompactFormat = () =>
  {
    indentation: NoIndentation,
    arrayFormat: CompactArrayEntries,
    objectFormat: CompactObjectEntries,
    lineEnding: NoLineEnding,
    finishWithNewLine: false,
    escapeAllControlPoints: false,
    escapeHTMLUnsafeSequences: false,
    escapeNonASCII: false,
  }: FormattingSettings

/**
 * Recommended human readable formatting.
 * 
 * Escapes all control points for the sake of clarity, but prints unicode
 * codepoints directly so the result needs to be treated as proper unicode and
 * is not safe to be transported in ASCII encoding.
 * 
 * The following example have whitespaces, line breaks and control points
 * replaced with visible characters.
 * ```
 * {↵
 * ··"currency":·"€",↵
 * ··"price":·99.9,↵
 * ··"currencyDescription":·"EURO\u007f",↵
 * ··"script·unembeddable":·"You·cannot·pase·a·JSON·object·directly·into·a·<script>·tag·in·HTML·if·it·contains·</·with·unescaped·forward·slash"↵
 * }
 * ```
 */
export let defaultPrettyFormat = () =>
  {
    indentation: IndentWithSpaces(2),
    arrayFormat: OneArrayEntryPerLine,
    objectFormat: OneObjectEntryPerLine,
    lineEnding: LineFeed,
    finishWithNewLine: true,
    escapeAllControlPoints: true,
    escapeHTMLUnsafeSequences: false,
    escapeNonASCII: false,
  }: FormattingSettings

/**
 * 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.
 * 
 * The following example have whitespaces, line breaks and control points
 * replaced with visible characters.
 * ```
 * {"currency":"\u20ac","price":99.9,"currencyDescription":"EURO\u007f","script·unembeddable":"You·cannot·pase·a·JSON·object·directly·into·a·<script>·tag·in·HTML·if·it·contains·<\/·with·unescaped·forward·slash"}
 * ```
 */
export let defaultCompactAndSafeFormat = () =>
  {
    indentation: NoIndentation,
    arrayFormat: CompactArrayEntries,
    objectFormat: CompactObjectEntries,
    lineEnding: NoLineEnding,
    finishWithNewLine: false,
    escapeAllControlPoints: true,
    escapeHTMLUnsafeSequences: true,
    escapeNonASCII: true,
  }: FormattingSettings

/**
 * 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 transported in
 * plain ASCII.
 * 
 * The following example have whitespaces, line breaks and control points
 * replaced with visible characters.
 * ```
 * {↵
 * ··"currency":·"\u20ac",↵
 * ··"price":·99.9,↵
 * ··"currencyDescription":·"EURO\u007f",↵
 * ··"script·unembeddable":·"You·cannot·pase·a·JSON·object·directly·into·a·<script>·tag·in·HTML·if·it·contains·<\/·with·unescaped·forward·slash"↵
 * }
 * ```
 */
export let defaultPrettyAndSafeFormat = () =>
  {
    indentation: IndentWithSpaces(2),
    arrayFormat: OneArrayEntryPerLine,
    objectFormat: OneObjectEntryPerLine,
    lineEnding: LineFeed,
    finishWithNewLine: true,
    escapeAllControlPoints: true,
    escapeHTMLUnsafeSequences: true,
    escapeNonASCII: true,
  }: FormattingSettings

record JSONWriterCompactImplHelper {
  buffer: Buffer.Buffer,
  emitEscapedQuotedString: String -> Void,
}

record JSONWriterPrettyImplHelper {
  format: FormattingSettings,
  // Note that the "Pretty" suffix here is a workaround for a Grain compiler bug.
  // It generates warnings just because two record types have some field names in common.
  // Unless there's something I don't understand about its type system.
  bufferPretty: Buffer.Buffer,
  emitEscapedQuotedStringPretty: String -> Void,
  printNewLine: () -> Void,
  printIndentation: 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 addCharFromCodePoint = (codePoint: Number, buffer: Buffer.Buffer) => {
  Buffer.addChar(Char.fromCode(codePoint), buffer)
}

let emitUTF16EscapeSequence = (codePoint: Number, buffer: Buffer.Buffer) => {
  // Emit the "\u" followed by hexadecimal representation of the codepoint
  // with fixed length of 4 hexadecimal digits correspondeing to the two byte
  // codepoint. No checks are performed here if the codepoint is in the
  // "Basic Multilingual Plane" (0000-FFFF) as this funcion is only called
  // internally.
  // An alternative was to this implementation was to use NumberUtils.itoa32,
  // but I wanted to avoid 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 occurence.

  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 hexadecinak 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 hexacedimal 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 codeppoint for char '0'
      digit + 48
    } else {
      // 97 is codeppoint 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
    }

    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, writer)
    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)
  }
}

exception UnknownNumberTag

// The following few functions are only meant to be called from a @disableGC
// context of the printNumber function so there's no need to do all the
// reference adjustment for the parameters and the functions themselves.

@disableGC
let printNumberWasmI32 = (value: WasmI32, buffer: Buffer.Buffer) => {
  let s = NumberUtils.itoa32(value, 10n)

  Memory.incRef(WasmI32.fromGrain(Buffer.addString))
  Memory.incRef(WasmI32.fromGrain(s))
  Memory.incRef(WasmI32.fromGrain(buffer))
  Buffer.addString(s, buffer)

  Memory.decRef(WasmI32.fromGrain(s))

  let none = None
  Memory.incRef(WasmI32.fromGrain(none))
  none
}

@disableGC
let printNumberWasmI64 = (value: WasmI64, buffer: Buffer.Buffer) => {
  let s = NumberUtils.itoa64(value, 10n)

  Memory.incRef(WasmI32.fromGrain(Buffer.addString))
  Memory.incRef(WasmI32.fromGrain(s))
  Memory.incRef(WasmI32.fromGrain(buffer))
  Buffer.addString(s, buffer)

  Memory.decRef(WasmI32.fromGrain(s))

  let none = None
  Memory.incRef(WasmI32.fromGrain(none))
  none
}

@disableGC
let isFinite = (value: WasmF64) => {
  WasmF64.eq(WasmF64.sub(value, value), 0.W)
}

@disableGC
let isNaN = (value: WasmF64) => {
  WasmF64.ne(value, value)
}

let makeNaNError = () => Some(InvalidNumber("NaN is not allowed in JSONNumber"))

let makeInfError = () =>
  Some(InvalidNumber("Infinity is not allowed in JSONNumber"))

let makeNegInfError = () =>
  Some(InvalidNumber("-Infinity is not allowed in JSONNumber"))

@disableGC
let printNumberWasmF64 = (value: WasmF64, buffer: Buffer.Buffer) => {
  let result = if (isFinite(value)) {
    let s = NumberUtils.dtoa(value)

    Memory.incRef(WasmI32.fromGrain(Buffer.addString))
    Memory.incRef(WasmI32.fromGrain(s))
    Memory.incRef(WasmI32.fromGrain(buffer))
    Buffer.addString(s, buffer)

    Memory.decRef(WasmI32.fromGrain(s))

    let none = None
    Memory.incRef(WasmI32.fromGrain(none))
    none
  } else {
    // 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
    // coninue formatting without representing these values correctly
    // (like JavaScript's JSON.stringify).
    if (isNaN(value)) {
      // Allocating the exception in a function without @disableGC makes
      // it easier to avoid problems with reference counting.
      Memory.incRef(WasmI32.fromGrain(makeNaNError))
      makeNaNError()
    } else if (WasmF64.lt(value, 0.0W)) {
      Memory.incRef(WasmI32.fromGrain(makeNegInfError))
      makeNegInfError()
    } else {
      Memory.incRef(WasmI32.fromGrain(makeInfError))
      makeInfError()
    }
  }

  result
}

@disableGC
let rec printNumber = (value: Number, buffer: Buffer.Buffer) => {
  let (&) = WasmI32.and
  let (==) = WasmI32.eq
  let (!=) = WasmI32.ne
  let (<<) = WasmI32.shl
  let (>>) = WasmI32.shrS

  let ptr = WasmI32.fromGrain(value)
  let result = if ((ptr & 1n) != 0n) {
    // FIXME expose runtime/numbers.untagSimple?
    let asWasmI32 = ptr >> 1n
    printNumberWasmI32(asWasmI32, buffer)
  } 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_INT32_BOXED_NUM_TAG => {
            let asWasmI32 = WasmI32.load(ptr, 8n)
            // FIXME magic numbers
            printNumberWasmI32(asWasmI32, buffer)
          },
          t when t == Tags._GRAIN_INT64_BOXED_NUM_TAG => {
            let asWasmI64 = WasmI64.load(ptr, 8n)
            // FIXME magic numbers
            printNumberWasmI64(asWasmI64, buffer)
          },
          t when t == Tags._GRAIN_RATIONAL_BOXED_NUM_TAG => {
            // As a compromnise, convert the rational into a float
            // and then print that. This means there can be
            // precision loss even for values that could be printed
            // exactly in decimal notation, but doing otherwise
            // could both compromise perfomance and confuse
            // developers as most JSON libraries in other languages
            // likely only deal with integers and floats.
            // Note that the ECMA-404 standard only specifies how
            // numbers should be formatted as text (in decimal
            // notation), so we could go the extra mile and at
            // least for some numbers try printing the exact
            // number. For example those that have a power of 10
            // in the denominator.
            let asWasmF64 = WasmF64.div(
              WasmF64.convertI32S(Numbers.boxedRationalNumerator(ptr)),
              WasmF64.convertI32S(Numbers.boxedRationalDenominator(ptr))
            )

            printNumberWasmF64(asWasmF64, buffer)
          },
          t when t == Tags._GRAIN_FLOAT32_BOXED_NUM_TAG => {
            let asWasmF32 = WasmF32.load(ptr, 8n)
            // FIXME magic numbers
            let asWasmF64 = WasmF64.promoteF32(asWasmF32)
            printNumberWasmF64(asWasmF64, buffer)
          },
          t when t == Tags._GRAIN_FLOAT64_BOXED_NUM_TAG => {
            let asWasmF64 = WasmF64.load(ptr, 8n)
            // FIXME magic numbers
            printNumberWasmF64(asWasmF64, buffer)
          },
          _ => {
            throw UnknownNumberTag
          },
        }
      },
      _ => {
        throw UnknownNumberTag
      },
    }
  } else {
    throw UnknownNumberTag
  }

  Memory.decRef(WasmI32.fromGrain(value))
  Memory.decRef(WasmI32.fromGrain(buffer))
  Memory.decRef(WasmI32.fromGrain(printNumber))

  result
}

// Note that this function is not allocated with the JSONWriter because currently
// Grain leaks memory each time a recursive closure is allocated. Not reallocating
// it may also be a better thing to do.
let rec printElementCompact =
  (
    json: JSON,
    implHelper: JSONWriterCompactImplHelper,
  ) => {
  let buffer = implHelper.buffer
  match (json) {
    JSONNull => {
      printNull(buffer)
      None
    },
    JSONBoolean(b) => {
      printBool(b, buffer)
      None
    },
    JSONNumber(n) => printNumber(n, buffer),
    JSONString(s) => {
      implHelper.emitEscapedQuotedString(s)
      None
    },
    JSONArray(elems) => {
      // Here I'm not using List.forEachi or similar in order to avoid
      // allocations of closures. The code is verbose and a bit ugly as a
      // consequence, but I think it's an OK price for performance gain.
      // Another approach would be to allocate a function for the
      // formattng arrays just once at the start of formatting and pass
      // it in emitJSONElement.
      match (elems) {
        [] => {
          Buffer.addChar('[', buffer)
          Buffer.addChar(']', buffer)
          None
        },
        [e] => {
          Buffer.addChar('[', buffer)

          let err = printElementCompact(e, implHelper)

          if (Option.isNone(err)) {
            Buffer.addChar(']', buffer)
          }

          err
        },
        [initialHead, ...initialRest] => {
          Buffer.addChar('[', buffer)

          let mut currentHead = initialHead
          let mut currentRest = initialRest

          let mut err = None

          for (let mut index = 0; ; index += 1) {
            if (index > 0) {
              Buffer.addChar(',', buffer)
            }

            err = printElementCompact(currentHead, implHelper)
            if (Option.isSome(err)) break

            match (currentRest) {
              [] => break,
              [newHead, ...newRest] => {
                currentHead = newHead
                currentRest = newRest
              },
            }
          }

          if (Option.isNone(err)) {
            Buffer.addChar(']', buffer)
          }

          err
        },
      }
    },
    JSONObject(entries) => {
      match (entries) {
        [] => {
          Buffer.addChar('{', buffer)
          Buffer.addChar('}', buffer)
          None
        },
        [(key, value)] => {
          Buffer.addChar('{', buffer)

          implHelper.emitEscapedQuotedString(key)

          Buffer.addChar(':', buffer)

          let err = printElementCompact(value, implHelper)

          if (Option.isNone(err)) {
            Buffer.addChar('}', buffer)
          }

          err
        },
        [initialHead, ...initialRest] => {
          Buffer.addChar('{', buffer)

          let mut currentHead = initialHead
          let mut currentRest = initialRest

          let mut err = None

          for (let mut index = 0; ; index += 1) {
            if (index > 0) {
              Buffer.addChar(',', buffer)
            }

            let (key, value) = currentHead

            implHelper.emitEscapedQuotedString(key)

            Buffer.addChar(':', buffer)

            err = printElementCompact(value, implHelper)

            if (Option.isSome(err)) {
              break
            }

            match (currentRest) {
              [] => break,
              [newHead, ...newRest] => {
                currentHead = newHead
                currentRest = newRest
              },
            }
          }

          if (Option.isNone(err)) {
            Buffer.addChar('}', buffer)
          }

          err
        },
      }
    },
  }
}

let makeCompactJSONWriter = (buffer: Buffer.Buffer) => {
  // As an optimization prepare a closure function to execute for each code
  // point of the input. It's important that this is not inlide in the
  // emitEscapedQuotedString function directly to avoid allocating the closue
  // for each input string.
  let emitCodePoint = (codePoint: Number) => {
    // For the compact formatting only escape backslash, double quotes and
    // code points 0..31 (the so called "C0" control point group) as
    // required by ECMA-404. For the non pretty printed case we don't want
    // to escape more than what is stricty required to avoid increasing the
    // output size.
    if (codePoint > 31 && codePoint != 0x0022 && codePoint != 0x005C) {
      addCharFromCodePoint(codePoint, buffer)
    } else {
      emitEscapedCodePoint(codePoint, buffer)
    }
  }

  let emitEscapedQuotedString = (s: String) => {
    Buffer.addChar('"', buffer)

    String.forEachCodePoint(emitCodePoint, s)

    Buffer.addChar('"', buffer)
  }

  let implHelper = {
    buffer,
    emitEscapedQuotedString: s => {
      emitEscapedQuotedString(s)
    },
  }: JSONWriterCompactImplHelper

  {
    emit: json => {
      let error = printElementCompact(json, implHelper)

      error
    },
  }: JSONWriter
}

// Note that this could relatively easily be integrated with
// printElementCompact to avoid code duplication, but it would mean
// compromising peak performance and also increasing complexity in other ways.
let rec printElementPretty =
  (
    json: JSON,
    implHelper: JSONWriterPrettyImplHelper,
    indentationLevel: Number,
  ) => {
  let buffer = implHelper.bufferPretty
  match (json) {
    JSONNull => {
      printNull(buffer)
      None
    },
    JSONBoolean(b) => {
      printBool(b, buffer)
      None
    },
    JSONNumber(n) => printNumber(n, buffer),
    JSONString(s) => {
      implHelper.emitEscapedQuotedStringPretty(s)
      None
    },
    JSONArray(elems) => {
      match (elems) {
        [] => {
          Buffer.addChar('[', buffer)
          Buffer.addChar(']', buffer)
          None
        },
        [e] => {
          let format = implHelper.format

          Buffer.addChar('[', buffer)

          if (format.arrayFormat == OneArrayEntryPerLine) {
            implHelper.printNewLine()
          }

          let elemLevel = indentationLevel + 1

          if (format.arrayFormat == OneArrayEntryPerLine) {
            implHelper.printIndentation(elemLevel)
          }

          let err = printElementPretty(e, implHelper, elemLevel)

          if (Option.isNone(err)) {
            if (format.arrayFormat == OneArrayEntryPerLine) {
              implHelper.printNewLine()
              implHelper.printIndentation(indentationLevel)
            }

            Buffer.addChar(']', buffer)
          }

          err
        },
        [initialHead, ...initialRest] => {
          let format = implHelper.format

          Buffer.addChar('[', buffer)

          if (format.arrayFormat == OneArrayEntryPerLine) {
            implHelper.printNewLine()
          }

          let mut currentHead = initialHead
          let mut currentRest = initialRest

          let mut err = None

          let elemLevel = indentationLevel + 1

          for (let mut index = 0; ; index += 1) {
            if (index > 0) {
              Buffer.addChar(',', buffer)

              if (format.arrayFormat == OneArrayEntryPerLine) {
                implHelper.printNewLine()
              }
            }

            if (format.arrayFormat == OneArrayEntryPerLine) {
              implHelper.printIndentation(elemLevel)
            }

            err = printElementPretty(currentHead, implHelper, elemLevel)
            if (Option.isSome(err)) {
              break
            }

            match (currentRest) {
              [] => break,
              [newHead, ...newRest] => {
                currentHead = newHead
                currentRest = newRest
              },
            }
          }

          if (Option.isNone(err)) {
            if (format.arrayFormat == OneArrayEntryPerLine) {
              implHelper.printNewLine()
              implHelper.printIndentation(indentationLevel)
            }

            Buffer.addChar(']', buffer)
          }

          err
        },
      }
    },
    JSONObject(entries) => {
      match (entries) {
        [] => {
          Buffer.addChar('{', buffer)
          Buffer.addChar('}', buffer)
          None
        },
        [(key, value)] => {
          let format = implHelper.format

          Buffer.addChar('{', buffer)

          let elemLevel = indentationLevel + 1

          if (format.objectFormat == OneObjectEntryPerLine) {
            implHelper.printNewLine()
            implHelper.printIndentation(elemLevel)
          }

          implHelper.emitEscapedQuotedStringPretty(key)

          match (format.objectFormat) {
            CompactObjectEntries => {
              Buffer.addChar(':', buffer)
            },
            OneObjectEntryPerLine => {
              Buffer.addChar(':', buffer)
              Buffer.addChar(' ', buffer)
            },
          }

          let err = printElementPretty(value, implHelper, elemLevel)

          if (Option.isNone(err)) {
            if (format.objectFormat == OneObjectEntryPerLine) {
              implHelper.printNewLine()
              implHelper.printIndentation(indentationLevel)
            }

            Buffer.addChar('}', buffer)
          }

          err
        },
        [initialHead, ...initialRest] => {
          let format = implHelper.format

          Buffer.addChar('{', buffer)

          if (format.objectFormat == OneObjectEntryPerLine) {
            implHelper.printNewLine()
          }

          let mut currentHead = initialHead
          let mut currentRest = initialRest

          let mut err = None

          let elemLevel = indentationLevel + 1

          for (let mut index = 0; ; index += 1) {
            if (index > 0) {
              Buffer.addChar(',', buffer)

              if (format.objectFormat == OneObjectEntryPerLine) {
                implHelper.printNewLine()
              }
            }

            if (format.objectFormat == OneObjectEntryPerLine) {
              implHelper.printIndentation(elemLevel)
            }

            let (key, value) = currentHead

            implHelper.emitEscapedQuotedStringPretty(key)

            match (format.objectFormat) {
              CompactObjectEntries => {
                Buffer.addChar(':', buffer)
              },
              OneObjectEntryPerLine => {
                Buffer.addChar(':', buffer)
                Buffer.addChar(' ', buffer)
              },
            }

            err = printElementPretty(value, implHelper, elemLevel)

            if (Option.isSome(err)) {
              break
            }

            match (currentRest) {
              [] => break,
              [newHead, ...newRest] => {
                currentHead = newHead
                currentRest = newRest
              },
            }
          }

          if (Option.isNone(err)) {
            if (format.objectFormat == OneObjectEntryPerLine) {
              implHelper.printNewLine()
              implHelper.printIndentation(indentationLevel)
            }

            Buffer.addChar('}', buffer)
          }

          err
        },
      }
    },
  }
}

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 makePrettyPrintJSONWriter =
  (
    format: FormattingSettings,
    buffer: Buffer.Buffer,
  ) => {
  let printNewLine = match (format.lineEnding) {
    NoLineEnding => () => void,
    LineFeed =>
      () => {
        Buffer.addChar('\n', buffer)
      },
    CarriageReturnLineFeed =>
      () => {
        Buffer.addChar('\r', buffer)
        Buffer.addChar('\n', buffer)
      },
    CarriageReturn =>
      () => {
        Buffer.addChar('\r', buffer)
      },
  }

  let printIndentation = match (format.indentation) {
    IndentWithTab =>
      indentationLevel => {
        let mut count = 0
        while (count < indentationLevel) {
          Buffer.addChar('\t', buffer)
          count += 1
        }
      },
    IndentWithSpaces(spacesPerIndentation) =>
      indentationLevel => {
        let mut count = 0
        let spaceCount = indentationLevel * spacesPerIndentation
        while (count < spaceCount) {
          Buffer.addChar(' ', buffer)
          count += 1
        }
      },
    NoIndentation => indentationLevel => void,
  }

  // As an optimization prepare a different closure function for each
  // combination of escaping options. This ways we can avoid unnecessary
  // branching in the code executed for each character. What is most
  // important here is to optimize for the non pretty printed format as this
  // is where the performance is most likely to matter. In every case escape
  // code points 0..31 as required by ECMA-404 (the so called "C0" control
  // point group). For the non pretty printed case we don't want to escape
  // more than what is stricty required to avoid increasing the output size.
  // But for pretty printing or compatiblity it may be desirable to escape
  // other control points or even everything other than printable ASCII
  // characters. Thus I've decided to expose options for this, but 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) {
        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 chacarcters
    // from 31 to 127.
    (codePoint: Number) => {
      if (
        codePoint > 31 &&
        codePoint != 0x0022 &&
        codePoint != 0x005C &&
        codePoint < 128
      ) {
        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
      ) {
        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
        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 (format.escapeHTMLUnsafeSequences && prevCodePoint == 60) {
            Buffer.addChar('\\', buffer)
            Buffer.addChar('/', buffer)
          } else {
            // otherwise just emit the slash as-is
            addCharFromCodePoint(codePoint, buffer)
          }
        } else {
          emitCodePoint(codePoint)
        }

        prevCodePoint = codePoint
      }, s)

      Buffer.addChar('"', buffer)
    }
  }

  let implHelper = {
    format,
    bufferPretty: buffer,
    emitEscapedQuotedStringPretty: s => {
      emitEscapedQuotedString(s)
    },
    printNewLine,
    printIndentation,
  }: JSONWriterPrettyImplHelper

  {
    emit: json => {
      let error = printElementPretty(json, implHelper, 0)

      if (format.finishWithNewLine && Option.isNone(error)) {
        printNewLine()
      }

      error
    },
  }: JSONWriter
}

/**
 * Prints the JSON object into a string with specific formatting settings.
 * 
 * @param json: The JSON object to print
 * @param format: Custom formatting setttings
 * @returns A `Result` object with either the string containing the printed JSON or an error if the input object cannot be represented in the JSON format.
 *
 * @example print(Result.unwrap(toString(JSONObject([("currency", JSONString("€")), ("price", JSONNumber(99.9))]), defaultCompactAndSafeFormat())))
 * 
 * Example output:
 * ```json
 * {"currency":"\u20ac","price":99.9}
 * ```
 */
export let toString = (json: JSON, format: FormattingSettings) => {
  let buf = Buffer.make(16)

  let writer = makePrettyPrintJSONWriter(format, buf)

  let error = writer.emit(json)

  match (error) {
    None => Ok(Buffer.toString(buf)),
    Some(e) => Err(e),
  }
}

/**
 * Prints the JSON object into a string with compact formatting optimized for
 * small size. Recommended for all uses where the intended consumer is a
 * machine program. For example in REST APIs.
 * 
 * Using this function can be preferred over `toString` with compact formatting
 * settings since it can be slightly faster.
 * 
 * @param json: The JSON object to print
 * @returns A `Result` object with either the string containing the printed JSON or an error if the input object cannot be represented in the JSON format.
 *
 * @example print(Result.unwrap(toStringCompact(JSONObject([("currency", JSONString("€")), ("price", JSONNumber(99.9))]))))
 * 
 * Example output:
 * ```json
 * {"currency":"€","price":99.9}
 * ```
 */
export let toStringCompact = (json: JSON) => {
  let buf = Buffer.make(16)

  let writer = makeCompactJSONWriter(buf)

  let error = writer.emit(json)

  match (error) {
    None => Ok(Buffer.toString(buf)),
    Some(e) => Err(e),
  }
}

/**
 * Prints the JSON object into a string with default pretty formatting
 * settings. Recommended for uses where the intended consumer is a person or
 * the text should be easily inspectable. For example configuration files or
 * document file formats.
 * 
 * @param json: The JSON object to print
 * @returns A `Result` object with either the string containing the printed JSON or an error if the input object cannot be represented in the JSON format.
 * 
 * Example output:
 * ```json
 * {
 *   "currency": "€",
 *   "price": 99.9
 * }
 * ```
 *
 * @example print(Result.unwrap(toStringPretty(JSONObject([("currency", JSONString("€")), ("price", JSONNumber(99.9))]))))
 */
export let toStringPretty = (json: JSON) =>
  toString(json, defaultPrettyFormat())

/**
 * Represents errors for JSON parsing along with a human readable text message.
 */
export enum JSONParseError {
  UnexpectedEndOfInput(String),
  UnexpectedToken(String),
  InvalidUTF16SurrogatePair(String),
}

/**
 * Internal data structure used during parsing.
 */
record JSONParserImplHelper {
  reader: StringReader.StringReader,
  bufferParse: Buffer.Buffer,
  mut currentCodePoint: Number,
  mut pos: 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

let isAtEndOfInput = (parserImplHelper: JSONParserImplHelper) => {
  parserImplHelper.currentCodePoint == _END_OF_INPUT
}

let next = (parserImplHelper: JSONParserImplHelper) => {
  let c = StringReader.readCodePointFast(parserImplHelper.reader)
  parserImplHelper.currentCodePoint = c
  parserImplHelper.pos = parserImplHelper.pos + 1
  c
}

let skipWhiteSpace = (parserImplHelper: JSONParserImplHelper) => {
  // isAtEndOfInput is not strictly necessary here
  // could remove as an optimization
  while (
    isInterTokenWhiteSpace(parserImplHelper.currentCodePoint) &&
    !isAtEndOfInput(parserImplHelper)
  ) {
    next(parserImplHelper)
    void
  }
}

let buildUnexpectedTokenError =
  (
    parserImplHelper: JSONParserImplHelper,
    detail: String,
  ) => {
  let codePoint = parserImplHelper.currentCodePoint
  let pos = parserImplHelper.pos
  if (codePoint == _END_OF_INPUT) {
    UnexpectedEndOfInput(
      "Unexpected token at position " ++ runtimeToString(pos) ++ ": " ++ detail
    )
  } else {
    UnexpectedToken(
      "Unexpected token at position " ++ runtimeToString(pos) ++ ": " ++ detail
    )
  }
}

@disableGC
let rec toHex = (n: Number) => {
  let x = coerceNumberToWasmI32(n)
  let result = NumberUtils.itoa32(x, 16n)

  Memory.decRef(WasmI32.fromGrain(n))
  Memory.decRef(WasmI32.fromGrain(toHex))

  result
}

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)
  while (String.length(result) < padTo) {
    result = "0" ++ result
  }
  result
}

let formatCodePointOrEOF = (codePoint: Number) => {
  if (codePoint >= 32 && codePoint <= 126) {
    // If the codepoint is in the range of printable ASCII charactes, then
    // display the character itself . Whether it's a good idea to display
    // all of them, especially space is up for debate.
    "'" ++ runtimeToString(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,
    parserImplHelper: JSONParserImplHelper,
  ) => {
  let c = parserImplHelper.currentCodePoint
  if (c == expectedCodePoint) {
    next(parserImplHelper)
    None
  } else {
    let detail = "expected " ++
      formatCodePointOrEOF(expectedCodePoint) ++
      ", found " ++
      formatCodePointOrEOF(c)
    Some(buildUnexpectedTokenError(parserImplHelper, detail))
  }
}

let rec parseValue = (parserImplHelper: JSONParserImplHelper) => {
  skipWhiteSpace(parserImplHelper)

  let result = match (parserImplHelper.currentCodePoint) {
    0x7B => parseObject(parserImplHelper), // '{'
    0x5B => parseArray(parserImplHelper), // '['
    0x22 => parseStringValue(parserImplHelper), // '"'
    0x74 => parseTrueValue(parserImplHelper), // 't'
    0x66 => parseFalseValue(parserImplHelper), // 'f'
    0x6E => parseNullValue(parserImplHelper), // 'n'
    // TODO Check if having a match case for each digit would be faster or not.
    c when c >= 0x30 && c <= 0x39 || c == 0x2D =>
      parseNumberValue(parserImplHelper), // '0'..'9' or '-'
    c => {
      let detail = "expected start of a JSON value, found " ++
        formatCodePointOrEOF(c)
      Err(buildUnexpectedTokenError(parserImplHelper, detail))
    },
  }

  skipWhiteSpace(parserImplHelper)

  result
}, parseNullValue = (parserImplHelper: JSONParserImplHelper) => {
  match (expectCodePointAndAdvance(0x6E, parserImplHelper)) {
    // 'n'
    Some(e) => Err(e),
    None => {
      match (expectCodePointAndAdvance(0x75, parserImplHelper)) {
        // 'u'
        Some(e) => Err(e),
        None => {
          match (expectCodePointAndAdvance(0x6C, parserImplHelper)) {
            // 'l'
            Some(e) => Err(e),
            None => {
              match (expectCodePointAndAdvance(0x6C, parserImplHelper)) {
                // 'l'
                Some(e) => Err(e),
                None => Ok(JSONNull),
              }
            },
          }
        },
      }
    },
  }
}, parseTrueValue = (parserImplHelper: JSONParserImplHelper) => {
  match (expectCodePointAndAdvance(0x74, parserImplHelper)) {
    // 't'
    Some(e) => Err(e),
    None => {
      match (expectCodePointAndAdvance(0x72, parserImplHelper)) {
        // 'r'
        Some(e) => Err(e),
        None => {
          match (expectCodePointAndAdvance(0x75, parserImplHelper)) {
            // 'u'
            Some(e) => Err(e),
            None => {
              match (expectCodePointAndAdvance(0x65, parserImplHelper)) {
                // 'e'
                Some(e) => Err(e),
                None => Ok(JSONBoolean(true)),
              }
            },
          }
        },
      }
    },
  }
}, parseFalseValue = (parserImplHelper: JSONParserImplHelper) => {
  match (expectCodePointAndAdvance(0x66, parserImplHelper)) {
    // 'f'
    Some(e) => Err(e),
    None => {
      match (expectCodePointAndAdvance(0x61, parserImplHelper)) {
        // 'a'
        Some(e) => Err(e),
        None => {
          match (expectCodePointAndAdvance(0x6C, parserImplHelper)) {
            // 'l'
            Some(e) => Err(e),
            None => {
              match (expectCodePointAndAdvance(0x73, parserImplHelper)) {
                // 's'
                Some(e) => Err(e),
                None => {
                  match (expectCodePointAndAdvance(0x65, parserImplHelper)) {
                    // 'e'
                    Some(e) => Err(e),
                    None => Ok(JSONBoolean(false)),
                  }
                },
              }
            },
          }
        },
      }
    },
  }
}, parseString = (parserImplHelper: JSONParserImplHelper) => {
  match (expectCodePointAndAdvance(0x22, parserImplHelper)) {
    // '"'
    Some(e) => Err(e),
    None => {
      let mut err = None
      let mut done = false
      let buffer = parserImplHelper.bufferParse
      Buffer.clear(buffer)

      while (!done) {
        match (parserImplHelper.currentCodePoint) {
          0x22 => { // '"'
            next(parserImplHelper)
            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 = parserImplHelper.pos

            next(parserImplHelper)

            match (parserImplHelper.currentCodePoint) {
              0x22 => { // '"'
                Buffer.addChar('"', buffer)
                next(parserImplHelper)
                void
              },
              0x5C => { // '\'
                Buffer.addChar('\\', buffer)
                next(parserImplHelper)
                void
              },
              0x2F => { // '/'
                Buffer.addChar('/', buffer)
                next(parserImplHelper)
                void
              },
              0x62 => { // letter 'b' as in Backspace
                // emit backspace control code
                Buffer.addChar('\u{08}', buffer)
                next(parserImplHelper)
                void
              },
              0x66 => { // letter 'f' as in Form Feed
                // emit Form Feed control code
                Buffer.addChar('\u{0C}', buffer)
                next(parserImplHelper)
                void
              },
              0x6E => { // letter 'n' as in New line
                // emit Line Feed control code
                Buffer.addChar('\u{0A}', buffer)
                next(parserImplHelper)
                void
              },
              0x72 => { // letter 'r' as in carriage Return
                // emit Carriage Return control code
                Buffer.addChar('\u{0D}', buffer)
                next(parserImplHelper)
                void
              },
              0x74 => { // letter 't' as in Tab
                // emit Tab control code
                Buffer.addChar('\u{09}', buffer)
                next(parserImplHelper)
                void
              },
              0x75 => { // 'u' (start of hexadecimal UTF-16 escape sequence)
                next(parserImplHelper)

                // 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 = parserImplHelper.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)
                      err = Some(
                        buildUnexpectedTokenError(parserImplHelper, detail)
                      )
                      break
                    }

                    let shift = digitIndex * 4
                    codeUnit = codeUnit | digit << shift

                    next(parserImplHelper)
                    void
                  }

                  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"
                      err = expectCodePointAndAdvance(0x5C, parserImplHelper)
                      // '\'
                      if (Option.isSome(err)) break
                      err = expectCodePointAndAdvance(0x75, parserImplHelper)
                      // 'u'
                      if (Option.isSome(err)) break

                      // Keep the high surrogate and proceed to the second
                      // iteration of the loop.
                      highSurrogate = codeUnit
                    } else if (
                      isCodePointInBasicMultilingualPlane(codeUnit) &&
                      !isLowSurrogate(codeUnit)
                    ) {
                      let codePoint = codeUnit
                      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)
                      err = Some(InvalidUTF16SurrogatePair(message))
                      break
                    }
                  } 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
                      )
                      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)
                      err = Some(InvalidUTF16SurrogatePair(message))
                      break
                    }
                  }
                }

                if (Option.isSome(err)) break
              },
              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)
                err = Some(buildUnexpectedTokenError(parserImplHelper, detail))
                break
              },
            }
          },
          c => {
            // Finally the happy case of a simple unescaped code point.
            next(parserImplHelper)
            addCharFromCodePoint(c, buffer)
          },
        }
      }

      match (err) {
        None => {
          if (done) {
            let s = Buffer.toString(buffer)
            Ok(s)
          } else {
            Err(
              buildUnexpectedTokenError(
                parserImplHelper,
                "unexpected end of string value"
              )
            )
          }
        },
        Some(e) => Err(e),
      }
    },
  }
}, parseStringValue = (parserImplHelper: JSONParserImplHelper) => {
  match (parseString(parserImplHelper)) {
    Ok(s) => Ok(JSONString(s)),
    Err(e) => Err(e),
  }
}, parseNumberValue = (parserImplHelper: JSONParserImplHelper) => {
  // First char can optionally be a minus sign.
  let mut c = parserImplHelper.currentCodePoint
  let isNegative = c == 0x2D
  // '-'
  if (isNegative) {
    c = next(parserImplHelper)
  }

  let mut err = None

  let mut significand = 0
  let mut exponent = 0
  let mut isExponentNegative = false

  // Note on performance: the hope here is to keep calculations in a way to
  // do at least the intermediate operations with Simple Numbers (non heap
  // allocated). If there's no fractional part then the resulting number
  // itself is packed into the "pointer" / value and only an instance of
  // JSONNumber is allocated on the heap. If the number has a fractional part
  // or a negative exponent then the final number will be heap allocated.
  // If the number doesn't fit 31 bits then intermetdiate calculations will
  // allocate numbers on the heap. This could be alleviated by doing
  // intermediate calculations with raw wasm numbers, but it would add some
  // complexity.

  // 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.
      c = next(parserImplHelper)
    },
    x when x >= 0x31 && x <= 0x39 => { // '1'..'9'
      for (;;) {
        let digit = c - 0x30

        significand = significand * 10 + digit

        c = next(parserImplHelper)

        if (c < 0x30 || c > 0x39) {
          break
        }
      }

      void
    },
    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)
      err = Some(buildUnexpectedTokenError(parserImplHelper, detail))
    },
  }

  // Optional fractional part of the number.
  if (Option.isNone(err) && c == 0x2E) { // '.'
    c = next(parserImplHelper)

    // let mut decimalPos = 10
    // let mut denominator = 1
    for (; c >= 0x30 && c <= 0x39;) {
      let digit = c - 0x30

      significand = significand * 10 + digit

      // denominator = denominator * 10

      c = next(parserImplHelper)

      exponent -= 1
    }
    // result /= denominator
  }

  // Optional exponential part of the number.
  if (Option.isNone(err) && (c == 0x65 || c == 0x45)) { // 'e' or 'E'
    c = next(parserImplHelper)

    // can start with optional plus or minus sign
    isExponentNegative = match (c) {
      0x2D => { // '-'
        c = next(parserImplHelper)
        true
      },
      0x2B => { // '+'
        c = next(parserImplHelper)
        false
      },
      _ => {
        false
      },
    }

    // followed by one or more digits (0-9)

    let mut explicitExponent = 0
    for (; c >= 0x30 && c <= 0x39;) {
      let digit = c - 0x30

      explicitExponent = explicitExponent * 10 + digit

      c = next(parserImplHelper)
    }

    if (isExponentNegative) {
      exponent -= explicitExponent
    } else {
      exponent += explicitExponent
    }

    void
  }

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

  match (err) {
    Some(e) => Err(e),
    None => {
      let mut result = significand

      if (exponent != 0) {
        // This is just a temporary naive implementation.

        if (exponent > 0) {
          let mut factor = 1
          for (let mut i = 0; i < exponent; i += 1) {
            factor *= 10
          }
          result *= factor
        } else {
          let mut factor = 1
          for (let mut i = 0; i < 0 - exponent; i += 1) {
            factor *= 10
          }
          result /= factor
        }
      }

      if (isNegative) {
        result = 0 - result
      }
      Ok(JSONNumber(result))
    },
  }
}, parseArray = (parserImplHelper: JSONParserImplHelper) => {
  match (expectCodePointAndAdvance(0x5B, parserImplHelper)) {
    // '['
    Some(e) => Err(e),
    None => {
      let mut err = None

      let mut elems = []: (List<JSON>)

      let mut done = false

      while (!done) {
        let c = parserImplHelper.currentCodePoint
        match (c) {
          0x2C => { // ','
            next(parserImplHelper)
            skipWhiteSpace(parserImplHelper)
          },
          0x5D => { // ']'
            next(parserImplHelper)
            done = true
            break
          },
          -1 => {
            // just end the loop without setting done to true
            break
          },
          _ => {
            // note that parseValue skips initial and final whitespace
            match (parseValue(parserImplHelper)) {
              Ok(elem) => {
                elems = [elem, ...elems]
                void
              },
              Err(e) => {
                err = Some(e)
                break
              },
            }
          },
        }
      }

      match (err) {
        Some(e) => Err(e),
        None => {
          if (done) {
            Ok(JSONArray(List.reverse(elems)))
          } else {
            Err(
              buildUnexpectedTokenError(
                parserImplHelper,
                "unexpected end of array"
              )
            )
          }
        },
      }
    },
  }
}, parseObject = (parserImplHelper: JSONParserImplHelper) => {
  match (expectCodePointAndAdvance(0x7B, parserImplHelper)) {
    // '{'
    Some(e) => Err(e),
    None => {
      let mut err = 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
      while (!done) {
        skipWhiteSpace(parserImplHelper)

        let c = parserImplHelper.currentCodePoint
        match (c) {
          -1 => {
            let detail = "expected a key-value pair or the end of the object"
            err = Some(buildUnexpectedTokenError(parserImplHelper, detail))
            break
          },
          0x2C => { // ','
            if (first) {
              let detail = "expected a key-value pair or the end of the object, found ','"
              err = Some(buildUnexpectedTokenError(parserImplHelper, detail))
              break
            } else {
              next(parserImplHelper)
              void
            }
          },
          0x7D => { // '}'
            next(parserImplHelper)
            done = true
            break
          },
          _ => {
            // 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(parserImplHelper)) {
              Ok(key) => {
                skipWhiteSpace(parserImplHelper)

                match (expectCodePointAndAdvance(0x3A, parserImplHelper)) {
                  // ':'
                  None => {
                    // note that parseValue skips initial and final whitespace
                    match (parseValue(parserImplHelper)) {
                      Ok(value) => {
                        entries = [(key, value), ...entries]
                        first = false
                        void
                      },
                      Err(e) => {
                        err = Some(e)
                        break
                      },
                    }
                  },
                  Some(e) => {
                    err = Some(e)
                    break
                  },
                }
              },
              Err(e) => {
                err = Some(e)
                break
              },
            }
          },
        }
      }
      // end of entry loop

      match (err) {
        Some(e) => Err(e),
        None => {
          if (done) {
            Ok(JSONObject(List.reverse(entries)))
          } else {
            // This brand is not expected to actually execute,
            // but in case it does, may just as well do the right thing.
            Err(
              buildUnexpectedTokenError(
                parserImplHelper,
                "unexpected end of object"
              )
            )
          }
        },
      }
    },
  }
}

/**
 * Parses JSON input from a string into a `JSON` object.
 * 
 * @param str: The JSON text string
 * @returns A `Result` object with either the parsed `JSON` object or an error.
 *
 * Example output:
 * ```
 * Ok(JSONObject([("currency", JSONString("$")), ("price", JSONNumber(119))]))
 * ```
 * 
 * @example print(parse("{\"currency\":\"$\",\"price\":119}"))
 */
export let parse: String -> Result<JSON, JSONParseError> = (str: String) => {
  let reader = StringReader.make(str)

  let parserImplHelper = {
    reader,
    bufferParse: Buffer.make(16),
    currentCodePoint: StringReader.readCodePointFast(reader),
    pos: 0,
  }: JSONParserImplHelper

  let root = parseValue(parserImplHelper)

  skipWhiteSpace(parserImplHelper)

  if (isAtEndOfInput(parserImplHelper)) {
    root
  } else {
    match (root) {
      Ok(_) => {
        let detail = "expected end of input, found " ++
          formatCodePointOrEOF(parserImplHelper.currentCodePoint)
        Err(buildUnexpectedTokenError(parserImplHelper, detail))
      },
      e => e,
    }
  }
}