Consider adding useful extension module

[nojaf]

While the aspiration of this project is to have bindings for anything available in the browser, it might be interesting consider having an additional auxiliary module.

Or to phrase it differently: some API methods are shit. Like https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement. You pass it any string and get an element back. Maybe you want to create something more specific and get a better type back like document.createElement("input") and get HTMLInputElement back.

So having something like:

type document

type htmlInputElement

@scope("document")
external createInputElement: (unit, @as("input") _) => htmlInputElement =
  "createElement"

let i = createInputElement()

The input string can't be misspelled and the return type is better.
Perhaps each current API module can have an APIExt companion module?
Let me know what you thoughts.

[zth]

I think this type of thing should go in the module directly. I'd say that's an idiomatic binding.

[nojaf]

There will be other examples:

type document

type element = {tag: string}

type htmlInputElement

@scope("document")
external querySelector: string => element = "querySelector"

external unsafeCast: 'i => 'o = "%identity"

let querySelectorInputElement = (selector: string): option<
  htmlInputElement,
> => {
  let i = querySelector(selector)
  i.tag === "input" ? Some(unsafeCast(i)) : None
}

This is not strictly a binding but does provide a safe API.

[zth]

Well, I think we definitely should ship "improved" APIs/helpers. Maybe others have differing opinions on this, but I think so at least. It'll increase the usefulness a lot for the lib.

We need to figure out where to draw the line obviously.
If we go for it, then I think we should find a way to pull completions from the "helper"/extension modules too.

Here's an example of something similar that might fit here - helpers for working efficiently with FormData: https://github.com/zth/res-x/blob/main/src/FormDataHelpers.res