ahrefs/melange-atdgen-codec-runtime

melange-atdgen-codec-runtime

melange-atdgen-codec-runtime is a Melange runtime for atdgen. It is based on the Js.Json.t provided by Melange and combinators of melange-json.

Installation

Install opam package manager.

Then:

opam install melange-atdgen-codec-runtime

Usage

To generate ml files from atd ones, add a couple of rules to your dune file:

(rule
 (targets test_bs.ml test_bs.mli)
 (deps test.atd)
 (action
  (run atdgen -bs %{deps})))

(rule
 (targets test_t.ml test_t.mli)
 (deps test.atd)
 (action
  (run atdgen -t %{deps})))

You can see examples in the tests or the example.

To use the generated modules, you will need to include the runtime library in your project. To do so, add melange-atdgen-codec-runtime to the libraries field in your dune file:

; ...
  (libraries melange-atdgen-codec-runtime)
; ...

To write atd type definitions, please have a look at the great atd documentation.

Simple example

Reason code to query and deserialize the response of a REST API. It requires melange-fetch.

let get = (url, decode) =>
  Js.Promise.(
    Fetch.fetchWithInit(
      url,
      Fetch.RequestInit.make(~method_=Get, ()),
    )
    |> then_(Fetch.Response.json)
    |> then_(json => json |> decode |> resolve)
  );

let v: Meetup_t.events =
  get(
    "http://localhost:8000/events",
    Atdgen_codec_runtime.Decode.decode(Meetup_bs.read_events),
  );

Full example

The example directory contains a full example of a simple cli to read and write data in a JSON file.

For a complete introduction from atdgen installation to json manipulation, please refer to Getting started with ATD and Melange.

melange-atdgen-codec-runtime's Issues

Update blog post and links to it

There was a blog post that goes through the example of the repo. We could update it to reflect the changes after melange migration in #41.

using the `-bs` flag doesnt work.

If you install and run the example yarn adtgen script, you get this error in the terminal, suggesting the adtgen -bs flag is not recognized though its listed as an option.

➜  example yarn atdgen
yarn run v1.15.2
warning package.json: No license field
warning ../../../package.json: No license field
$ atdgen -t src/meetup.atd && atdgen -bs src/meetup.atd
atdgen: unknown option '-bs'.
Generate OCaml code offering:
  * OCaml type definitions translated from ATD file (-t)
  * serializers and deserializers for Biniou (-b)
  * serializers and deserializers for JSON (-j)
  * record-creating functions supporting default fields (-v)
  * user-specified data validators (-v)

Recommended usage: atdgen (-t|-b|-j|-v|-dep|-list|-bs) example.atd
  -type-conv 
    GEN1,GEN2,...
         Insert 'with GEN1, GEN2, ...' after OCaml type definitions for the
         type-conv preprocessor
    
  -deriving-conv 
    GEN1,GEN2,...
         Insert 'with GEN1, GEN2, ...' after OCaml type definitions for the
         ppx_deriving preprocessor
    
  -t 
          Produce files example_t.mli and example_t.ml
          containing OCaml type definitions derived from example.atd.
  -b 
          Produce files example_b.mli and example_b.ml
          containing OCaml serializers and deserializers for the Biniou
          data format from the specifications in example.atd.
  -j 
          Produce files example_j.mli and example_j.ml
          containing OCaml serializers and deserializers for the JSON
          data format from the specifications in example.atd.
  -v 
          Produce files example_v.mli and example_v.ml
          containing OCaml functions for creating records and
          validators from the specifications in example.atd.
  -dep 
          Output Make-compatible dependencies for all possible
          products of atdgen -t, -b, -j and -v, and exit.
  -list 
          Output a space-separated list of all possible products of
          atdgen -t, -b, -j and -v, and exit.
  -o [ PREFIX | - ]
          Use this prefix for the generated files, e.g. 'foo/bar' for
          foo/bar.ml and foo/bar.mli.
          `-' designates stdout and produces code of the form
            struct ... end : sig ... end
  -biniou 
          [deprecated in favor of -t and -b]
          Produce serializers and deserializers for Biniou
          including OCaml type definitions (default).
  -json 
          [deprecated in favor of -t and -j]
          Produce serializers and deserializers for JSON
          including OCaml type definitions.
  -j-std 
          Convert tuples and variants into standard JSON and
          refuse to print NaN and infinities (implying -json mode
          unless another mode is specified).
  -std-json 
          [deprecated in favor of -j-std]
          Same as -j-std.
  -j-pp <func>
          OCaml function of type (string -> string) applied on the input
          of each *_of_string function generated by atdgen (JSON mode).
          This is originally intended for UTF-8 validation of the input
          which is not performed by atdgen.
  -j-defaults 
          Output JSON record fields even if their value is known
          to be the default.
  -j-strict-fields 
          Call !Atdgen_runtime.Util.Json.unknown_field_handler for every unknown JSON field
          found in the input instead of simply skipping them.
          The initial behavior is to raise an exception.
  -j-custom-fields FUNCTION
          Call the given function of type (string -> unit)
          for every unknown JSON field found in the input
          instead of simply skipping them.
          See also -j-strict-fields.
  -validate 
          [deprecated in favor of -t and -v]
          Produce data validators from <ocaml validator="x"> annotations
          where x is a user-written validator to be applied on a specific
          node.
          This is typically used in conjunction with -extend because
          user-written validators depend on the type definitions.
  -extend MODULE
          Assume that all type definitions are provided by the specified
          module unless otherwise annotated. Type aliases are created
          for each type, e.g.
            type t = Module.t
  -open MODULE1,MODULE2,...
          List of modules to open (comma-separated or space-separated)
  -nfd 
          Do not dump OCaml function definitions
  -ntd 
          Do not dump OCaml type definitions
  -pos-fname FILENAME
          Source file name to use for error messages
          (default: input file name)
  -pos-lnum LINENUM
          Source line number of the first line of the input (default: 1)
  -rec 
          Keep OCaml type definitions mutually recursive
  -version 
          Print the version identifier of atdgen and exit.
  -help  Display this list of options
  --help  Display this list of options
error Command failed with exit code 2.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
➜  example 

Alternatively are there docs on generating the atdgen bucklescript code as seen in https://github.com/ahrefs/atdgen-workshop-starter?

Thank you

Fix ci

Broke after #41.

include Atdgen_codec_runtime in Atdgen_runtime

This would be consistent with Atdgen_runtime on native. I stumbled upon this inconsistency when I wanted to use Type_Field adapter in bucklescript. I had to workaround the difference between native and bs by creating a Atdgen_universal_runtime and using it from .atd.

Please document the exact SHA of `atd` in use

I've recently upgraded bs-atdgen-codec-runtime & atd and the code generated from master atd doesn't work anymore.

  We've found a bug for you!
  /home/tim/src/pt/all/swage/web/src/Types_bs.ml 121:39-84
  
  119 │ )
  120 │ let write_zt_network = (
  121 │   Atdgen_codec_runtime.Encode.adapter Atdgen_runtime.Json_adapter.Typ
        e_field.restore (
  122 │     Atdgen_codec_runtime.Encode.make (fun (t : zt_network) ->
  123 │       (
  
  The module or file Atdgen_runtime can't be found.
  - If it's a third-party dependency:
    - Did you list it in bsconfig.json?
    - Did you run `bsb` instead of `bsb -make-world`
      (latter builds third-parties)?
  - Did you include the file's directory in bsconfig.json?

get rid of `optional` from bs-json

It swallows exceptions breaking serialization contract

output to different directory

How do you output the generated atdgen files to a different directory?

Update:

  "gen_atd": "atdgen -t ./shared/example.atd -o frontend/atd/Example && atdgen -bs ./shared/example.atd -o frontend/atd/Example",

this will take ./shared/example.atd and generate frontend/atd/Example_t.ml etc.

int64 serialization doesn't match the one in ocaml atdgen-runtime

When we have a type with an ocaml representation of int64, it doesn't get serialized in the same way as it would in ocaml atdgen-runtime.
ex:

type int64 = int <ocaml repr="int64">

In this example, the value would be returned from the ocaml side as an int in the json response, and the atdgen-codec-runtime would complain that it can't parse that value as it's expecting a string.

Int64 serialization functions:

ocaml atdgen-runtime:

let write_int64 ob x =
  Bi_outbuf.add_string ob (Int64.to_string x)

bs-atdgen-codec-runtime:

let int64 s = string (Int64.to_string s)

Missing encode/decode functions

Compared to https://github.com/mjambon/atd/blob/master/atdgen-codec-runtime/src/decode.mli, the following decode functions are missing:

• obj_list
• obj_array

obj_list is needed for https://atd.readthedocs.io/en/latest/atdgen.html#association-lists.

Also tuple1 is missing for both encode and decode (it was added very recently).

Default values treated differently than native runtime

Given some atd file in a module Answer:

type value = [
  | True
  | False
] <ocaml repr="classic">

type t = {
  ~mode <ocaml default="False"> : value;
}

when calling from native:

utop # Answer_j.string_of_t {mode = False};;
- : string = "{}"

but from JavaScript:

$ Answer_bs.write_t({mode: False})->Js.Json.stringify
{"mode":"False"}

The expected result should be same as native:

$ Answer_bs.write_t({mode: False})->Js.Json.stringify
{}