bs-decode

bs-decode

Read the Documentation

Decode JSON values into structured ReasonML and OCaml types. Inspired by Elm's Json.Decode and the Decode Pipeline, bs-decode is an alternative to bs-json that focuses on structured, type-safe error handling, rather than exceptions. Additionally, bs-decode collects up everything that went wrong while parsing the JSON, rather than failing on the first error.

Installation

Install via npm:

npm install --save bs-decode

Update your bsconfig.json

"bs-dependencies": [
  "bs-decode"
],

Usage

The following is available to give you an idea of how the library works, but the complete documentation will probably be more useful if you want to write your own decoders.

// imagine you have a `user` type and `make` function to construct one
type user = {
  name: string,
  age: int,
  isAdmin: bool,
  lastLogin: option(Js.Date.t)
};

let make = (name, age, isAdmin, lastLogin) =>
  { name, age, isAdmin, lastLogin };

/**
 * Given a JSON value that looks like:
 * { "name": "Michael", "age": 32, "roles": ["admin"] }
 *
 * you can write a function to convert this JSON into a value of type `user`
 */
module Decode = Decode.AsResult.OfParseError; // module alias for brevity

let decode = json =>
  Decode.Pipeline.(
    succeed(make)
    |> field("name", string)
    |> field("age", intFromNumber)
    |> field("roles", map(List.contains("admin"), list(string)))
    |> optionalField("lastLogin", date)
    |> run(json)
  );

let myUser = decode(json); /* Ok({ name: "Michael", ...}) */

Contributing

All contributions are welcome! This obviously includes code changes and documentation improvements (see CONTRIBUTING), but we also appreciate any feedback you want to provide (in the form of Github issues) about concepts that are confusing or poorly explained in the docs.

License

Released under the MIT license.

Changelog

0.8.0 (Jul 3, 2019)

:rotating_light: Breaking

• Long-deprecated int and float functions have been removed. You should be using intFromNumber and floatFromNumber instead to avoid shadowing issues
• tuple (which previously contructed a tuple from a JSON object) is now tupleFromFields
• Base failure type now includes an ExpectedTuple(int) constructor, where int is the expected size. This is only a breaking change if you're manually matching on values of the base failure type.

:sparkles: New features

• JSON arrays can now be decoded directly into tuples using tuple2...tuple5 (which will fail if the JSON array is larger than expected) or tupleAtLeast2...tupleAtLeast5 (which will tolerate longer arrays)