npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

reason-webapi

v0.7.0

Published

Reason / ReScript bindings to DOM

Downloads

5

Readme

rescript-webapi

npm

Bindings to the DOM and other browser-specific web APIs.

Stability

This project is in the process of being forked; until the library reaches 1.0, expect major breaking changes to the API. See the 1.0 project for the current progress towards that goal.

Installation

npm install rescript-webapi

Then add rescript-webapi to bs-dependencies in your bsconfig.json. A minimal example:

{
  "name": "my-thing",
  "sources": "src",
  "bs-dependencies": ["rescript-webapi"]
}

Usage

See the examples folder.

Please only use the modules exposed through the toplevel module Webapi, for example Webapi.Dom.Element. In particular, don't use the 'flat' modules like Webapi__Dom__Element as these are considered private and are not guaranteed to be backwards-compatible.

Some notes on the DOM API

The DOM API is mostly organized into interfaces and relies heavily on inheritance. The ergonomics of the API is also heavily dependent on dynamic typing, which makes it somewhat challenging to implement a thin binding layer that is both safe and ergonomic. To achieve this we employ subtyping and implementation inheritance, concepts which aren't very idiomatic to OCaml (or Reason), but all the more beneficial to understand in order to be able to use these bindings effectively.

Subtyping

The Dom types, and the relationships between them, are actually defined in the Dom module that ships with bs-platform (Source code), where you'll find a bunch of types that look like this:

type _element<'a>;
type element_like<'a> = node_like<_element<'a>>;
type element = element_like<_baseClass>;

This is subtyping implemented with abstract types and phantom arguments. The details of how this works isn't very important (but see #23 for a detailed explanation of how exactly this trickery works) in order to just use them, but there are a few things you should know:

  • If you expand the alias of a concrete DOM type, you'll discover it's actually a list of abstract types. e.g. element expands to _baseClass _element _node _eventTarget_like This means element is a subtype of _element, _node and _eventTarget_like.
  • The _like type are "open" (because they have a type variable). This means that a function accepting an 'a element_like will accept any "supertype" of element_like. A function accepting just an element will only accept an element (Technically element is actually a "supertype" of element_like too).

This system works exceptionally well, but has one significant flaw: It makes type errors even more complicated than they normally are. If you know what to look for it's not that bad, but unfortunately the formatting of these errors don't make looking for it any easier.

Implementation inheritance

If you've looked through the source code a bit, you've likely come across code like this:

include Webapi__Dom__EventTarget.Impl({ type t = t });
include Webapi__Dom__Node.Impl({ type t = t });
include Webapi__Dom__ParentNode.Impl({ type t = t });
include Webapi__Dom__NonDocumentTypeChildNode.Impl({ type t = t });
include Webapi__Dom__ChildNode.Impl({ type t = t });
include Webapi__Dom__Slotable.Impl({ type t = t });
include Impl({ type t = t });

This is the implementation inheritance. Each "inheritable" module defines an "Impl" module where all its exported functions are defined. include Webapi__Dom__Node.Impl({ type t = t }); means that all the functions in Webapi__Dom__Node.Impl should be included in this module, but with the t type of that module replaced by the t type of this one. And that's it, it now has all the functions.

Implementation inheritance is used instead of subtyping to make it easier to understand which functions operate on any given "subject". If you have an element and you need to use a function defined in Node, let's say removeChild you cannot just use Node.removeChild. Instead you need to use Element.removeChild, which you can since Element inherits from Node. As a general rule, always use the function in the module corresponding to the type you have. You'll find this makes it very easy to see what types you're dealing with just by reading the code.

Changes

See CHANGELOG.md.

License and Credits

All code is licensed as MIT. See LICENSE.

This project was forked from bs-webapi after it was mostly abandoned. We took the opportunity to make major changes to the API and bring it up to modern ReScript development practices by renaming it.

This project also forks bs-fetch and includes fetch as a first-class concept in the webapi.

Primary development on this project is sponsored by Tiny.