rfc: bindings #777

jchavarri · 2023-10-13T13:17:04Z

A proposal to improve the bindings layer in Melange.

texastoland · 2023-10-15T21:44:10Z

I have some ad hoc bindings:

module Performance = struct
  external now : unit -> float = "performance.now"
end

module BigInt = struct
  type t
  type op = t -> t -> t

  external toString : t -> string = "toString" [@@mel.send]

  let zero : t = [%mel.raw "0n"]
  let one : t = [%mel.raw "1n"]
  let ( + ) : op = [%mel.raw "(x, y) => x + y"]
end

They'd become:

module Performance = struct
  let%js now : unit -> float = "performance.now()"
end

module BigInt = struct
  type t

  let%js zero : t = "0n"
  let%js one : t = "1n"

  let%js toString : this_:t -> string = "$this_.toString()"
  let%js ( + ) : x_:t -> y_:t -> t = "$x_ + $y_"
end

Correct? I like:

my operator doesn't require a closure
annotations don't feel like recalling physics equations
JS function invocation is explicit

Could you support positional arguments inspired by Swift?

let%js toString : t -> string = "$0.toString()"
let%js ( + ) : op = "$0 + $1"

jchavarri · 2023-10-16T08:06:06Z

@texastoland Your snippet looks good, but I think you're missing let%js in definitions of toString and +.

Could you support positional arguments inspired by Swift?

I thought about this, but it introduces some complexity if we mix positional and labeled arguments in the same expression. If I have let%js foo : x:t -> u -> v and I want to refer to the positional argument, would it be $0 (the first positional argument) or $1 (the second argument)? I would like users to not have to think about this kind of stuff, so maybe we could establish a rule that either one labels all arguments or leaves them all positional. Wdyt?

texastoland · 2023-10-16T16:01:48Z

I think you're missing let%js in definitions

Oops fixed 🙈

it introduces some complexity if we mix positional and labeled arguments in the same expression

My intuition is positional terms refer to unlabeled arguments otherwise you'd use $label.

maybe we could establish a rule that either one labels all arguments or leaves them all positional

That's a reasonable compromise if you think it'd be confusing. 1 labeled argument with many positional ones sounds undesirable anyway. I prefer vice versa.

I was just experimenting more and love that it generalizes arbitrary JS including ..., new, throw, or ~~await~~! It reminds me of Fable's FFI but simpler.

PureScript originally exposed a similar feature but removed it in purescript/purescript#887. Their reasoning was it tied libraries to specific compiler back ends. I assume Melange's solution is selective compilation with Dune?

PS this is 🔥

texastoland · 2023-10-19T00:09:37Z

1 additional note I like and prefer the js. convention compared to mel. (or bs.). I assume Melange won't be competing for that namespace.

johnhaley81 · 2023-10-21T00:00:40Z

This is a really great improvement towards a binding API that doesn't make me need to look up the docs each time I need to do it (even after like 6 years 😵‍💫).

So after reading through this I have 2 thoughts:

Mixing arg types

we could establish a rule that either one labels all arguments or leaves them all positional.

That would prevent things like t-middle bindings without some workarounds. Ex:

let%js slice : indexEnd:int -> string -> indexStart:int -> string = "$0.slice($indexStart, $indexEnd)"

Would have to become something like:

let%js slice : indexStart : int -> indexEnd : int option -> str : string -> string = "$str.slice($indexStart, $indexEnd)"
(* using shadowing to override the API *)
let slice ?indexEnd str ~indexStart => slice(indexStart, indexEnd, str)

Which might be ok but I wanted to present a valid use case for mixing labeled, optional labeled, and positional args.

Importing class modules

Before:

type t
external book : unit -> t = "Book" [@@mel.new] [@@mel.module]
let myBook = book ()

After:

type t
let%js.import book: t = "Book"
let%js create_book : ~t_:t -> unit -> t = "new $t_()"
let myBook = book |> create_book ()

Maybe the After was typo-ed but it is resulting in a more confusing API IMO. The module that is imported is of type t and you need that type to create the type t after calling create_book? Do I have to create a second type to pass into the first one?

Maybe we could have an import_constructor?

type t
let%js.import_constructor book: unit -> t = "Book" (* converts to "new Book(...args)" *)
let myBook = book()

wdyt?

johnhaley81 · 2023-10-21T00:02:14Z

Speaking of needing to reference the docs every time I make a binding...

Relevant XKCD

texastoland · 2023-10-21T03:43:55Z

I think your slice example would just be:

let%js slice : ?end_:int -> this_:string -> start:int -> string = "$this_.slice($start, $end_)"

Underscore is supposed to allow it to be used positionally (not sure why though). I'm not familiar with "t-middle" style?

texastoland · 2023-10-21T04:07:13Z

@johnhaley81 I think your book example should be:

(* Book module *)
type t

open struct (* private? *)
  let%js.import construct = "@book/lib"
end

let%js make : unit -> t = "new construct()"

(* in another file *)
let book = make ()

The issue I see with a special constructor annotation is it doesn't add labels, spread arguments in JS, etc.

jchavarri · 2023-10-21T09:25:48Z

Thanks for the feedback @texastoland @johnhaley81.

Mixing arg types

As Texas mentioned above, you can use the underscored labelled args to place positional arguments wherever in the signature. Using a shorter name like t_ would require to type a few extra characters (t_ :) more than the introduction of $0, $1 for positional args 🤔

let%js slice : indexStart : int ->  t_ : string -> indexEnd : int option -> string = "$t_.slice($indexStart, $indexEnd)"
(* no need for shadowing to override the API *)

Importing class modules

The module that is imported is of type t and you need that type to create the type t after calling create_book? Do I have to create a second type to pass into the first one?

I think the way I see it is: there is a type to represent the default value exported by the JavaScript module itself (the class), and another type to represent the values / instances created when the class is invoked:

(* the type of the js class "Book" *)
type c 
(* the type of instances created  *)
type i 
let%js.import book: c = "Book"
let%js create_book : ~c_:c -> unit -> i = "new $c_()"
let myBook = book |> create_book ()

I am not sure about adding import_constructor because it wouldn't solve the problem if there are multiple values being destructured from the JS module, e.g. let%js.import {foo = (hey : t); bar: u} = "./bar". What if foo is a class but bar isn't?

Maybe we could allow decorating types in the destructuring using new or some other attribute:

type t
let%js.import (book : (unit -> c[@new])) = "Book"
let myBook = book()

This would play well with more complex destructuring:

let%js.import {foo = (hey : (string -> int -> c[@new])); bar: u} = "./bar"

wdyt?

texastoland · 2023-10-21T12:31:35Z

@jchavarri Did you see my solution? Another way of using import is an imperative statement that introduces identifiers in the current JS environment. Its type can be inferred or unit.

type t
let%js.import construct = "@book/lib"
let%js make : unit -> t = "new construct()"

IFL the @new annotation:

Adds cognitive burden
Is less explicit (more magical)
Doesn't cover cases like spreading array arguments
Doesn't save that much typing

jchavarri · 2023-10-21T16:22:28Z

@texastoland yeah, I agree that @new somehow feels like going back.

Your solution could work, but it would need some changes to prevent breakages. Notice that Melange identifiers can compile to different JavaScript identifiers for various reasons. For example, this code:

let t = Js.Date.make()
let u b = t
let t = 3

Will produce:

var t = new Date();
function u(b) {
  return t;
}
var t$1 = 3;

The second t identifier is compiled into t$1.

So we can't directly reference Melange identifiers safely from the JavaScript code in the let%js string payload.

To work around this, maybe we can rely in the recently added mel.as functionality:

type t
let%js.import [@mel.as "Book"] book = "@book/lib"
let%js make : unit -> t = "new Book()"

Maybe there could be some other way to directly reference Melange identifiers in scope from the JavaScript strings, using $ as well as a way to tell the compiler, e.g.:

type t
let%js.import book = "@book/lib"
let%js make : unit -> t = "new $book()"

This solution looks more complex technically, as we would need to "resolve" the Melange identifiers into the JS ones, @anmonteiro must know if this could be done directly from a ppx, but I believe it would need a deep integration with the compiler.

texastoland · 2023-10-21T16:31:15Z

Thanks that makes sense. I guess I assumed @as (using the same name as OCaml) was implied. It reminds me of the Disord discussion about callbacks having @called_from_js by default. But I like the $ notation for consistency! In (my) perfect world no other annotations would be necessary.

anmonteiro · 2023-11-06T02:18:59Z