https://github.com/rescript-labs/decco

Bucklescript PPX which generates JSON (de)serializers for user-defined types
https://github.com/rescript-labs/decco

Last synced: about 2 months ago
JSON representation

Bucklescript PPX which generates JSON (de)serializers for user-defined types

• Host: GitHub
• URL: https://github.com/rescript-labs/decco
• Owner: rescript-labs
• License: mit
• Created: 2018-06-24T23:54:05.000Z (about 6 years ago)
• Default Branch: main
• Last Pushed: 2024-05-03T19:38:05.000Z (about 2 months ago)
• Last Synced: 2024-05-04T02:49:21.506Z (about 2 months ago)
• Language: OCaml
• Size: 1.06 MB
• Stars: 227
• Watchers: 4
• Forks: 28
• Open Issues: 23
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Lists

• awesome-list - decco - defined types | reasonml-labs | 219 | (Reason)
• awesome-reasonml - decco - Bucklescript PPX which generates JSON (de)serializers for user-defined types (Reason / Libraries and Bindings)
• awesome-reasonml - decco - Bucklescript PPX which generates JSON (de)serializers for user-defined types (Reason / Libraries and Bindings)

README

        
# Decco

## Project Status

Decco is lazily maintained by it users, but it's not being actively developed, since its feature set is complete enough for general production use. If you find a major bug that you need fixed, it'll probably be your job to fix it. 💪

## How do I install it?

1. Install package

```

npm i @rescript-labs/decco

```

2. Update your `rescript.json` (or bsconfig.json if you haven't changed its name)

```json

{

  ...,

  "bs-dependencies": [ "@rescript-labs/decco" ],

  "ppx-flags": [ "@rescript-labs/decco/ppx" ],

  ...

}

```

Adding `decco/ppx` to `ppx-flags` will enable the PPX. Adding decco to `bs-dependencies` is required because the code generated by the PPX references the `Decco` module.

## Compatibility

Decco 2.0.0 and above work with ReScript 11 in uncurried mode. If you need to use Decco with an older version of ReScript, install decco version `1.6.0`

If you need to use decco with BuckleScript 5, install `@ryb73/decco` version ^0.1.0 by [following the old ReadMe here](https://github.com/reasonml-labs/decco/blob/0452fc42fa4cd4230d394c718e7f62a0384ce045/README.md).

## What is it?

A Rescript PPX which generates JSON serializers and deserializers for user-defined types.

Example:

```rescript

/* Define types */

@decco type variant<'a> = A | B(int) | C(int, 'a);

type dict = Js.Dict.t;

@decco

type mytype = {

    s: string,

    i: int,

    o: option,

    complex: array>>>,

    @decco.default(1.0) f: float,

    @decco.key("other_key") otherKey: string,

    magic: @decco.codec(Decco.Codecs.magic) dict,

};

/* Use _encode to encode */

let encoded = mytype_encode({

    s: "hello",

    i: 12,

    o: None,

    complex: [Some(list{ C(25, "bullseye") })],

    f: 13.,

    otherKey: "other",

    magic: Js.Dict.fromArray([("key","value")]),

});

Js.log(Js.Json.stringifyWithSpace(encoded, 2));

/* {

     "s": "hello",

     "i": 12,

     "o": null,

     "complex": [ [ ["C", 25, "bullseye"] ] ],

     "f": 13,

     "other_key": "other",

     "magic": { "key": "value" }

  } */

/* Use _decode to decode */

let { s, i, o, complex, f, otherKey, magic } =

    mytype_decode(encoded)->Belt.Result.getExn;

```

## How do I use it?

See the test folder in this repo for some examples.

## Reference

### Attributes

#### @decco

Applies to: type declarations, type signatures

Indicates that an encoder and decoder should be generated for the given type.

#### @decco.encode

Applies to: type declarations, type signatures

Indicates than an encoder (but no decoder) should be generated for the given type.

#### @decco.decode

Applies to: type declarations, type signatures

Indicates than an decoder (but no encoder) should be generated for the given type.

#### @decco.codec

Applies to: type expressions

Specifies custom encoders and decoders for the type. Note that both an encoder and decoder must be specified, even if the type expression is within a type for which @decco.encode or @decco.decode was specified.

```rescript

@decco type t = @decco.codec((fancyEncoder, fancyDecoder)) fancyType;

```

#### @decco.key

Applies to: record fields

By default, ReScript record fields map to JS object fields of the same name. Use @decco.key to specify a custom JS field name. Useful if the JS field name is invalid as a ReScript record field name.

```rescript

@decco

type record = {

    @decco.key("other_key") otherKey: string,

};

```

#### @decco.default

Applies to: record fields

Default: `Js.Json.null`

When decoding a record, the default value will be used for keys that are missing from the JSON object being decoded.

```rescript

@decco type record = {

    @decco.default("def") s: string,

};

let {s} = Js.Json.parseExn("{}")->record_decode->Belt.Result.getExn;

Js.log(s); /* def */

```

# Contributing

Please read the [CONTRIBUTING.md](./CONTRIBUTING.md)