# bs-decode

> Type-safe JSON decoding for ReasonML and OCaml

Latest version **1.2.0** (published 2023-10-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install bs-decode
pnpm add bs-decode
yarn add bs-decode
bun add bs-decode
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2023-10-15 |
| First published | 2018-09-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 65.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 103 |
| Author | Michael Martin |
| Maintainers | mlms13 |
| Keywords | reasonml, bucklescript, json, decode, validation, result, applicative |

## Links

- npm: https://www.npmjs.com/package/bs-decode
- Repository: https://github.com/mlms13/bs-decode
- Homepage: https://mlms13.github.io/bs-decode/docs
- Issues: https://github.com/mlms13/bs-decode/issues
- npm.io page: https://npm.io/package/bs-decode

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 1.2.0 (latest) — 2023-10-15
- 1.1.0 — 2023-04-08
- 1.0.0 — 2023-03-09
- 0.11.2 — 2020-06-28
- 0.11.1 — 2020-04-01
- 0.11.0 — 2020-03-31
- 0.10.0 — 2020-03-03
- 0.9.0 — 2019-10-07
- 0.8.1 — 2019-07-12
- 0.8.0 — 2019-07-03
- 0.7.0 — 2019-06-25
- 0.6.2 — 2019-06-07
- 0.6.1 — 2019-05-28
- 0.6.0 — 2019-05-28
- 0.5.1 — 2019-05-23
- … 8 more at https://npm.io/package/bs-decode/versions

## README

# bs-decode

[![build status](https://img.shields.io/circleci/build/github/mlms13/bs-decode.svg?style=flat-square)](https://circleci.com/gh/mlms13/bs-decode)
[![test coverage](https://img.shields.io/coveralls/github/mlms13/bs-decode.svg?style=flat-square)](https://coveralls.io/github/mlms13/bs-decode)
[![npm version](https://img.shields.io/npm/v/bs-decode.svg?style=flat-square)](https://www.npmjs.com/package/bs-decode)
[![license](https://img.shields.io/github/license/mlms13/bs-decode.svg?style=flat-square)](https://github.com/mlms13/bs-decode/blob/master/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](https://mlms13.github.io/bs-decode/docs/)

Decode JSON values into structured ReasonML and OCaml types. Inspired by Elm's [Json.Decode](https://package.elm-lang.org/packages/elm-lang/core/5.1.1/Json-Decode) and the [Decode Pipeline](https://package.elm-lang.org/packages/NoRedInk/elm-decode-pipeline/3.0.1/Json-Decode-Pipeline), `bs-decode` is an alternative to [bs-json](https://github.com/glennsl/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 relude bs-bastet`

**Update your bsconfig.json**

```
"bs-dependencies": [
  "bs-bastet",
  "bs-decode",
  "relude"
],
```


## Usage

The following is available to give you an idea of how the library works, but [the complete documentation](https://mlms13.github.io/bs-decode/docs/simple-example) will probably be more useful if you want to write your own decoders.

```reason
// 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](https://github.com/mlms13/bs-decode/blob/master/CONTRIBUTING.md)), but we also appreciate any feedback you want to provide (in the form of [Github issues](https://github.com/mlms13/bs-decode/issues)) about concepts that are confusing or poorly explained in [the docs](https://mlms13.github.io/bs-decode/docs/what-and-why).

## License

Released under the [MIT license](https://github.com/mlms13/bs-decode/blob/master/LICENSE).

---
_Source: https://npm.io/package/bs-decode · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._