Overview

gen_js_api aims at simplifying the creation of OCaml bindings for
JavaScript libraries. It must currently be used with the js_of_ocaml
compiler, although other ways
to run OCaml code "against" JavaScript might be supported later with
the same binding definitions (for instance,
Bucklescript,
or direct embedding of a JS engine in a native OCaml application).

gen_js_api is based on the following ideas:

• Authors of bindings write OCaml signatures for JavaScript libraries
  and the tool generates the actual binding code with a combination
  of implicit conventions and explicit annotations.

• The generated binding code takes care of translating values between
  OCaml and JavaScript and of dealing with JavaScript calling
  conventions.

• All syntactic processing is done by authors of bindings: the client
  code is normal OCaml code and does not depend on custom syntax nor
  on JS-specific types.

gen_js_api can be used in two complementary ways:

• Generating .ml implementations from annotated .mli interfaces,
  in order to create the code for stub libraries.

• As a ppx preprocessor on implementations to define local
  bindings.

Examples

The repository contains some examples of OCaml bindings to JavaScript
libraries created with gen_js_api:

• Very partial bindings to jQuery, with
  some example client code.

• Partial bindings to JavaScript strings and
  regexps and JavaScript
  dates.

• Some ad hoc test to exercise various features.

• An example of a self-contained program, a simple
  calculator, implementing local .bindings

Documentation

• Install and use

• Low-level binding to JavaScript

• Using gen_js_api to generate .ml from .mli

• Using gen_js_api as a ppx processor

• Default naming convention

• JS-able types and type declarations

• Value bindings

• Class-wrapping bindings

• TODO list

Related projects

• js_of_ocaml: The compiler
  and runtime system on which gen_js_api relies. (Note: gen_js_api
  doesn't depend on js_of_ocaml's OCaml library, nor on its language
  extension.)

• goji: A DSL to describe OCaml
  bindings for JavaScript libraries.

• DefinitelyMaybeTyped:
  A project to parse
  DefinitelyTyped
  interfaces and produce OCaml interfaces.

• ReScript:
  Another compiler from OCaml to JavaScript, featuring the genType ppx for generating TS / Flow types and runtime converters.

About

gen_js_api has been created by LexiFi for porting a web application
from JavaScript to OCaml. The tool has been used in production since
2015.

This gen_js_api package is licensed by LexiFi under the terms of the
MIT license.

See see Changelog

Contact: alain.frisch@lexifi.com

Contributors:

• Alain Frisch

• Sebastien Briais