Give your feedback about rescript-webapi!

Development
1

Hello everyone,

We know the current situation around WebAPI in rescript is not ideal and we would really like to improve it.

Please give your feedback about rescript-webapi, tell us the things that work, the things that don’t, how would you make things ideally if you could rewrite everything from scratch. Think about it in a broad way, not just the API but also the documentation, the discoverability, the editor support, etc!

Thanks a lot!

3 Likes
2

I’ll briefly summarize the points that already got reported:

  1. the existing API is too far from the JS one (from window.location.origin in JS to Webapi.Dom.window->Webapi.Dom.Window.location->Webapi.Dom.Location.origin in rescript)
  2. we could change the types to base them on private spreaded records instead of abstract types, this would play well with simple and imperative APIs (this would allow to write window.location.origin in rescript as well), but could cause issues with more polymorphic/dynamic APIs (how would we write multiple bindings of the same JS function?).
  3. we could improve the current bindings by making use of features from >= v11 (multiple optional arguments to replace several bindings)
  4. we could improve the inheritance modelling (type spreading and coercion could be a solution) that is quite a pain right now
  5. we could add docstrings and examples to have top notch API doc like Core has
  6. we could improve the editor tooling and Core to improve discoverability/DX
  7. we could ship rescript with @rescript/webapi directly
  8. or ask a question in create-rescript-app to include the relevant bindings (webapi, node, deno, bun)
4 Likes
3
4

Just reiterating things already mentioned here, but ergonomics is the most important here I think. Like mentioned, it’s a world of difference between doing:

Webapi.Dom.window->Webapi.Dom.Window.location->Webapi.Dom.Location.origin

and doing:

window.location.origin

And even if we could make the argument that the first one is “more correct/idiomatic” in our world, it’s just not good enough ergonomics wise, in my opinion.

I think one of the biggest issues I’ve experienced with Webapi is that it’s so different to how you’d use the same things in JS. The big problem for me with that is that my general knowledge with how to work with the DOM doesn’t translate fully to ReScript. And that creates a scenario where I’m significantly slower.

6 Likes
5

My two cents:

  • Most people that will use this API will have existing JavaScript knowledge, so the spreaded record idea would make this a lot closer to what people are familiar with.
  • I would organize all the modules as they are listed on Web APIs | MDN. And really try to go broad and include the Fetch API for example.
  • From a tooling point of view it would be great if we could autocomplete a list of functions that take the current type as first argument when people press ..
    The list should show ->someFunctionX, ->someFunctionY and just mimic what folks expect to find when they would dot into the object.
  • We should strive for an easy to contribute process with frequent automated releases. For example, contribute a fix + changelog entry => publish to npm via CI.
4 Likes
6

What is the desired way to call these?

// Nested modules
WebApi.Navigator.cookieEnabled

// An object
WebApi.navigator.cookieEnabled


// If you have WebApi open it could match JS
navigator.cookieEnabled

I think the first one looks more like ReScript code, but the second one would match the web api docs.

7

I ran into the same question when writing our jest bindings - is it Jest.Fn.make(), Jest.fn() or jest.fn()?

My vote would go for Navigator.cookieEnabled. It has the same ergonomics but is namespaced nicer. As much as I like the direct navigator.cookieEnabled, when you need to add function bindings the former makes it more clear where you can look for those functions (i.e. Location.assign)

1 Like
8

Hi folks, I’m experimenting with creating new bindings over at GitHub - rescript-lang/experimental-rescript-webapi: Experimental successor to rescript-webapi

I’m creating issues as questions arise, feel free to chime in!

6 Likes
9

I’ve just seen this thread and find GitHub - rescript-lang/experimental-rescript-webapi: Experimental successor to rescript-webapi 's approach super interesting. Bravo @nojaf :clap:

At my work, we were initially based on GitHub - TheSpyder/rescript-webapi: ReScript bindings to the DOM and other Web APIs and then decided to recreate our own bindings with only the basics. The rescript-webapi bindings were incomplete, vscode integration was poor and difficult to use for beginners.

I have 3 feedbacks to give:

ReScript is going in a great direction!

4 Likes
10

Hi Leo,

Thanks for the feedback!
I can’t answer anything official but here are some of my thoughts:

  • @zth is trying to tackle completion @z-th.bsky.social on Bluesky
  • Dom.* can hopefully be deprecated. Richer version of these types will exist in the new webapi.
  • As for Fetch, the way I see it is that webapi should contain everything that is present in the browser, so ideally we can get FetchAPI good enough so it is usable. fetch is available in the browser and the bindings should reflect that.

@fham @cknitt once I made some more progress of these bindings, we could maybe have a community stream about this?

1 Like
11

We’re actively exploring how to make the DX a lot better. Some promising ideas and experimentation so far! The linked editor experiment being one of them.

3 Likes
12

Early usage of the new bindings: Use new webapi by nojaf · Pull Request #1 · nojaf/my-pkmn-rescript-app · GitHub

It’s quite minimal and doesn’t provide much information, but I’m liking it so far.

1 Like
13

Hello, everyone! A first version of the new bindings has been published to npm: @rescript/webapi.

You can find early documentation here: ReScript WebAPI Documentation.

The key thing to do now is to experiment with this and provide feedback via GitHub issues. What works, what doesn’t? Which APIs are you missing?

Please use GitHub issues to maintain a single source of truth when collaborating on this!

7 Likes
14

Hello again,

As we develop these new bindings, I’ve paused the generation process. Moving forward, we will accept manual tweaks to the bindings.

A good example can be found here: Improve fetch binding by nojaf · Pull Request #15 · rescript-lang/experimental-rescript-webapi · GitHub

Many of you trying out the new bindings will likely encounter this situation. While it may be close to what you need, it might not be ideal. I encourage everyone to send small PRs with any missing features so we can gradually improve these bindings together.

I’ve documented the entire process of adjusting the bindings at Project setup | Experimental WebAPI

Please give it a try and collaborate with us!

4 Likes