search

ahrefs / atd

Static types for JSON APIs
Other
315 stars 52 forks source link

Way to support adapter.ocaml="Type_field" for the TypeScript backend #376

Closed Stepland closed 11 months ago

Stepland commented 11 months ago

I'm using ATD to type JSON data exchanged between an OCaml program and a TypeScript program.

The ATD file makes use of <json adapter.ocaml="Atdgen_runtime.Json_adapter.Type_field">, unfortunately this annotation doesn't seem to have any effect on the generated parsing code in TypeScript. As a result, parsing fails because the generated TypeScript code expects the usual "tuple" representation.

I would really like to keep the type field reprensentation in the output JSON, but also be able to parse that JSON using code generated by atdts.

Is there a way to do that ?

mjambon commented 11 months ago

The adapter feature is intended for reading from external APIs that use different conventions than ATD for representing data in JSON. It's most often used for sum types. I strongly advise against its use if you can change the API to conform to ATD conventions.

Right now, adapter is only supported for OCaml via atdgen. It could be added to atdts, atdpy, etc. but this work hasn't been done.

You could try using abstract to keep the node as a raw JSON tree (Yojson.Safe.t in OCaml, a map in TypeScript) and use abstract wrap to convert it to something better in OCaml but there's still no equivalent feature for TypeScript. The whole thing would be confusing to most developers having to deal with this code.

So, I recommend one of these solutions:

Stepland commented 11 months ago

In my case I'm lucky enough to be able change the API. So I'll just do that, thanks !

I'll close this issue, but I still think having a backend-agnostic annotation to specify sum type representation could be a big plus.

mjambon commented 11 months ago

having a backend-agnostic annotation to specify sum type representation could be a big plus

I haven't found a solution that is both fully customizable (arbitrary JSON to JSON conversion) and very easy to implement for all the programming languages targeted by ATD. Implementing support for adapter.typescript, adapter.python, etc. still seems like the best compromise to me.