@rescript-labs/decco

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)

{
  ...,
  "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.

What is it?

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

Example:

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

type dict = Js.Dict.t<string>;
@decco
type mytype = {
    s: string,
    i: int,
    o: option<int>,
    complex: array<option<list<variant<string>>>>,
    @decco.default(1.0) f: float,
    @decco.key("other_key") otherKey: string,
    magic: @decco.codec(Decco.Codecs.magic) dict,
};

/* Use <typename>_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 <typename>_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.

@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.

@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.

@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