json

Author: chenglou

docs/json.md

@@ -0,0 +1,52 @@
+---
+id: json
+title: JSON
+---
+
+There are several ways to work with JSON right now, that we'll unify and polish very soon.
+
+## Unsafe Conversion
+
+This emulates JavaScript's JSON conversion.
+
+### Parse
+
+Simply use the (last resort) special [identity external](intro-to-external.md#special-identity-external):
+
+```ocaml
+type data = < name :string  > Js.t
+external parseIntoMyData : string -> data = "parse" [@@bs.scope "JSON"][@@bs.val]
+
+let result = parseIntoMyData "{\"name\": \"Luke\"}"
+```
+
+Reason syntax:
+
+```reason
+type data = {. "name": string};
+[@bs.scope "JSON"][@bs.val] external parseIntoMyData: string => data = "parse";
+
+let result = parseIntoMyData("{\"name\": \"Luke\"}");
+```
+
+Output:
+
+```js
+var result = JSON.parse("{\"name\": \"Luke\"}");
+```
+
+Where `data` can be any type you assume the JSON is. As you can see, this compiles to a straightforward `JSON.parse` call. As with regular JS, this is convenient, but has no guarantee that e.g. the data is correctly shaped, or even syntactically valid.
+
+### Stringify
+
+Since JSON.stringify is _slightly_ safer than `JSON.parse`, we've provided it out of the box in [Js.Json](https://bucklescript.github.io/bucklescript/api/Js.Json.html#VALstringifyAny). It compiles to `JSON.stringify`.
+
+## Properly Use `Js.Json`
+
+Technically, the correct way to handle JSON is to recursively parse each field, and handle invalid data accordingly. [Js.Json](https://bucklescript.github.io/bucklescript/api/Js.Json.html) provides such low-level building blocks. See the examples in the API docs.
+
+## Higher-level Helpers
+
+We have a community-maintaned, pseudo-official JSON helper library called [bs-json](https://github.com/reasonml-community/bs-json). Those interested in combinators can also check out [JsonCodec](https://github.com/state-machine-systems/JsonCodec). Both provide more convenient JSON parsing/printing helpers that leverage the previous section's low-level API.
+
+We'll provide a better, first-party solution to JSON too in the future. Stay tuned!

website/i18n/en.json

@@ -33,6 +33,7 @@
     "interop-overview": "Overview",
     "interop-with-js-build-systems": "Interop with JS Build System",
     "intro-to-external": "Intro to External",
+    "json": "JSON",
     "load-third-party-libraries": "Load Third-party Libraries",
     "new-project": "New Project",
     "nodejs-special-variables": "NodeJS Special Variables",
@@ -66,4 +67,4 @@
     "Edit this Doc|recruitment message asking to edit the doc source": "Edit",
     "Translate this Doc|recruitment message asking to translate the docs": "Translate"
   }
-}
+}

website/sidebars.json

@@ -21,6 +21,7 @@
       "import-export",
       "regular-expression",
       "exceptions",
+      "json",
       "generate-converters-accessors",
       "nodejs-special-variables",
       "interop-misc",