Skip to content

rikimasan/bs-decode

 
 

Repository files navigation

bs-decode

build status test coverage npm version license

Note

bs-decode has been stable and used in production for several years, so a v1 release makes sense. This is the final release that will be compatible with BuckleScript as we turn our attention to the newer OCaml features available in Melange.

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:

yarn add bs-decode relude bs-bastet

Add the library stanzas in your dune file

If you're using dune to build your project, add a library stanza to tell dune about bs-decode. You'll need to add similar library stanzas for bsBastet and relude if you haven't already.

(subdir
 node_modules/bs-decode/src
 (library
  (name bsDecode)
  (modes melange)
  (libraries bsBastet relude)))

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": "Alice", "age": 44, "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", list(string) |> map(List.contains("admin")))
    |> optionalField("lastLogin", date)
    |> run(json)
  );

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

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.

About

Type-safe JSON decoding for ReasonML and OCaml

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Reason 91.4%
  • JavaScript 4.5%
  • Makefile 3.5%
  • CSS 0.6%