gen_js_api

The [@js.scope "path"] attribute on a module changes the reference to the global object by following the provided property path. Nested scopes are concatenated with dots.

Usage Patterns

• Singleton/Class members: Bind to values inside a specific object.

  module[@js.scope "console"] Console: sig
    val log: string -> unit [@@js.global]
  end

  This is equivalent to console.log.

• Nested Scopes: Use tuple notation [@js.scope (s1, ..., sn)] to define nested paths. This is equivalent to applying [@js.scope sn]...[@js.scope s1].

• Module Name Inference: When attached directly to a module, the payload may be omitted; it is implicitly filled with the module name (preserving capitalization).

module NestedScope0 : sig
  val f: string -> unit [@@js.global "outer.inner.f"]
end

module [@js.scope ("outer", "inner")] NestedScope1 : sig
  val f: string -> unit [@@js.global]
end

module NestedScope2 : sig
  val f: string -> unit [@@js.global]
end [@js.scope "inner"] [@js.scope "outer"]

To enforce JS/OCaml value conversion on polymorphic functions, use first-class modules annotated with [@js]. This tells the generator to use the module's conversion functions rather than passing the module itself to JS.

Requirements:

1. Annotation: Modules must be annotated with [@js].
2. Ordering: The first-class module must appear before any other normal types in the function signature.
3. Form: To convert a type variable 'x, it must be in the form (module[@js] Ojs.T with type t = 'x).
4. Location: They can only be used within value bindings, not type aliases.

Example:

module[@js.scope "Person"] Person : sig
  type t
  val t_to_js: t -> Ojs.t
  val t_of_js: Ojs.t -> t
  val create: string -> t [@@js.create]
end

let p = Person.create "Foo";;
Console.log (module Person) p;; (* Person { name: 'Foo' } *)

Built-in Modules:

Use Ojs modules for standard types:

• module Ojs.String
• module Ojs.Int
• module Ojs.List(Ojs.String)

module[@js.scope "console"] Console: sig
  val log: (module[@js] Ojs.T with type t = 'a) -> 'a -> unit [@@js.global]
end

(* Usage *)
Console.log (module Ojs.String) "hello, world!";;

A JS-able type is an OCaml type that can be automatically mapped to and from JavaScript objects.

Supported Types:

• Basic built-ins: string, int, bool, float, and Ojs.t.
• Tuples: Mapped to JS arrays.
• Sequences: array and list are both mapped to JS arrays (indexed 0..length-1).
• Options: option types map to the underlying type. None maps to JS null; both null and undefined map back to None.
• Polymorphic Variants: Used for enums, unions, and discriminated unions.
• Type Variables: Free variables like 'a involve no runtime mapping (identity coercion).

Manual Mapping

You can make an arbitrary non-parametrized type M.t JS-able by providing two functions in module M:

• t_to_js: t -> Ojs.t
• t_of_js: Ojs.t -> t

For parametrized types 'a t, the mapping functions must accept a mapper for the parameter:

• t_to_js: ('a -> Ojs.t) -> 'a t -> Ojs.t
• t_of_js: (Ojs.t -> 'a) -> Ojs.t -> 'a t

Unbound type variables (e.g., 'a) are processed via unsafe coercion to and from Ojs.t. This means the identity function is used during conversion.

Warning: Use with Caution

This approach should not be used for JS functions that expect the values to be converted to specific JS types. For example, a JsArray.t containing OCaml strings will not work with Array.join because the elements are OCaml string representations, not JS strings.

Safe Alternatives:

1. Functors: Pass the conversion logic via a functor argument to enforce value conversion.
2. First-class modules: Use module[@js.scope "..."] to provide safe bindings.
3. Manual bindings: Use the low-level functions in the Ojs module.

(* Unsafe approach: elements are not converted to JS types *) 
module JsArray : sig
  type 'a t = private Ojs.t
  val create: int -> 'a t [@@js.new "Array"]
  val push: 'a t -> 'a -> unit [@@js.call]
end

(* Safe approach: uses a functor to enforce conversion *) 
module JsArray (E: Ojs.T): sig
  type t
  val t_to_js: t -> Ojs.t
  val t_of_js: Ojs.t -> t
  val create: unit -> t [@@js.new "Array"]
  val push: t -> E.t -> unit [@@js.call]
end

To bind Node.js libraries that use require(...), you must first expose them as js_of_ocaml runtime primitives.

1. Create a JavaScript file (e.g., imports.js) that requires the desired modules.
2. Use the //Provides: <name> comment above each variable to register it with the js_of_ocaml linker.
3. If targeting WebAssembly, create a .wat shim to allow wasm_of_ocaml to import these primitives.
4. Include these files in your dune stanza under both js_of_ocaml and wasm_of_ocaml sections.

// runtime_primitives/imports.js
'use strict';

//Provides: node_path
var node_path = require('path');

//Provides: node_fs
var node_fs = require('fs');

//Provides: node_version
var node_version = require('process').version;

//Provides: node_console
var node_console = console.log;

;; runtime_primitives/imports.wat
(global (export "_node_path") (import "js" "node_path") anyref)
(global (export "_node_fs") (import "js" "node_fs") anyref)
(global (export "_node_version") (import "js" "node_version") anyref)
(global (export "_node_console") (import "js" "node_console") anyref)

; runtime_primitives/dune
(rule
 (targets bindings.ml)
 (deps bindings.mli)
 (action (run gen_js_api %{deps})))

(executable
 (name example)
 (libraries ojs)
 (preprocess (pps gen_js_api.ppx))
 (modes js wasm)
 (js_of_ocaml (javascript_files imports.js))
 (wasm_of_ocaml (javascript_files imports.js imports.wat)))