Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
2f1f9dc
docs: harden alpha docs and local link validation
jderochervlk Nov 5, 2026
488b730
docs: clarify alpha crypto migrations and release checks
jderochervlk Nov 5, 2026
7ca0ea4
test(docs): validate stylesheet asset references
jderochervlk Nov 5, 2026
1d2c2b9
docs: name public notification permission type
jderochervlk Nov 5, 2026
5c6d5aa
docs: close alpha review findings and migration gaps
jderochervlk Nov 7, 2026
2d2b31c
docs: finalize alpha contract and link validation
jderochervlk Nov 7, 2026
2279aea
docs: clarify release artifact transfer path
jderochervlk Nov 7, 2026
aa602cf
docs: reconcile final alpha release migration guidance
jderochervlk Nov 7, 2026
9ddf12d
docs: document isolated browser runner port
jderochervlk Nov 7, 2026
16a6313
test(docs): cover final link-checker boundaries
jderochervlk Nov 7, 2026
efcdddc
fix(docs): handle browser link parsing edge cases
jderochervlk Nov 7, 2026
95a298a
fix(docs): align link checks with browser parsing
jderochervlk Nov 7, 2026
ade48ed
test(docs): preserve HTML entity decoding semantics
jderochervlk Nov 7, 2026
37df48f
fix(docs): complete browser-compatible link parsing
jderochervlk Nov 7, 2026
d4bafb2
build(docs): declare HTML entity decoder dependency
jderochervlk Nov 7, 2026
19bb420
docs(webapi): describe native crypto algorithm inputs
jderochervlk Nov 7, 2026
8b51db9
fix(docs): preserve BOMs in encoded fragments
jderochervlk Nov 7, 2026
00133f1
docs(webapi): document byte-only body streams
jderochervlk Nov 7, 2026
fa4931f
docs(release): explain metadata and registry checks
jderochervlk Nov 8, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,9 @@ jobs:
- name: Build documentation
run: npm run build:docs

- name: Check documentation links
run: npm run check:docs-links

- name: Upload documentation
uses: actions/upload-pages-artifact@v5
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,9 @@ jobs:
- name: Build documentation
run: npm run build:docs

- name: Check documentation links
run: npm run check:docs-links

- name: Validate alpha package metadata
run: npm run check:release

Expand Down
62 changes: 62 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Changelog

This file records user-visible changes. Alpha releases may contain breaking changes, and
changes may occur between alpha versions. Version numbers and publication-channel instructions
are maintained by the release workflow; see the [alpha release readiness tracker](https://github.com/rescript-lang/experimental-rescript-webapi/issues/382).

## 1.0.0-alpha.1 (candidate)

Planned first release in the `1.0.0-alpha.N` series. ReScript `13.0.0-alpha.5` is the tested
compiler baseline. This alpha is not a stable API; review the migration notes below before
upgrading from earlier prereleases. The release workflow is the source of truth for actual
versioning and publication.

### Migration notes

- WebSocket sends and worker `Request` fetches now preserve their native receiver (`this`) rather
than calling receiver-bound methods unbound.
- `WebAPI.Request.bytes`, `WebAPI.Response.bytes`, `WebAPI.Blob.bytes`,
`WebAPI.Blob.stream`, and `WebAPI.SafeFetch.bytes` expose
native `Uint8Array.t` values or chunks instead of `array<int>`. Use the typed-array API
directly; the bytes are not copied into a ReScript integer array. `SafeFetch.bytes` keeps its
existing result and response wrapper; only the byte payload changes.
- `BodyInit.fromReadableStream` and `Response.fromReadableStream` now require
`ReadableStream.t<Uint8Array.t>` input. These HTTP-body adapters accept byte chunks, not arbitrary
or string chunks; `ReadableStream` itself remains generic for other uses.
- `ResizeObserver` callbacks now receive `(entries, observer)` as two arguments rather than a
curried callback.
- Web Audio analyser float buffers, `AudioBuffer` channel and copy APIs, and Biquad/IIR filter
frequency-response buffers use `Float32Array.t`; analyser byte buffers use `Uint8Array.t`.
`DOMMatrix` and `DOMMatrixReadOnly` Float32 conversions also use `Float32Array.t`. Use native
typed-array values rather than ordinary ReScript arrays for these calls.
- `Element.closest` returns `Null.t<DOMTree.element>` and is no longer polymorphic. Narrow the
result with the relevant public classifier when a more specific HTML interface is required.
- WebCrypto signatures now reflect native results: `sign` and `digest` return `ArrayBuffer.t`,
`verify` returns `bool`, `deriveKey` returns `WebAPI.SubtleCrypto.cryptoKey`, and `deriveBits`
and `wrapKey` return `ArrayBuffer.t`. Key and algorithm support types are available through
`WebAPI.SubtleCrypto`. Use `algorithmString` for a native algorithm name and `algorithmObject`
for parameter dictionaries such as AES-GCM's `iv` and `tagLength`; the object helper preserves
typed-array values rather than copying them into a closed algorithm-name variant.
- Generic `SubtleCrypto.generateKey` and `generateKey2` now return `unknown` because the result
depends on the algorithm. Use `generateKeySymmetric` for HMAC keys
(`SubtleCrypto.cryptoKey`) or `generateEcdsaKeyPair` for ECDSA pairs
(`SubtleCrypto.cryptoKeyPair`). Generic `exportKey` also returns `unknown`; use
`exportKeyBinary` for `Raw`, `Pkcs8`, or `Spki` formats (`ArrayBuffer.t`), and
`exportKeyJwk` for `Jwk` format (`JSON.t`).
- `DOMTree.element` no longer exposes a generic `className`. Specific HTML interfaces retain a
string `className`; `SVGElement.t.className` is `SVGElement.svgAnimatedString` with
`baseVal` and `animVal`.
- `CustomElementRegistry.define` takes a `DOM.customElementConstructor`; it does not take an
element instance.
- Request destination, referrer-policy, and media `canPlayType` result types now include `Empty`
for native empty-string values. `HTMLCanvasElement.toBlob` callbacks receive a
`Null.t<WebAPI.Blob.t>` because the browser can return null (including for a zero-sized
canvas). An `ifAvailable` Web Locks callback receives a nullable lock when the lock is
unavailable. `IDBFactory.deleteDatabase` has an operation-specific `unit` result because the
browser's successful result is `undefined`, not a database.
- `WebAPI.Notification.t` no longer contains a static permission field. Read that value through
`WebAPI.Notification.permission`.

For the intended installation, compiler range, runtime/browser checks, and known limitations,
see the [project status](https://rescript-lang.github.io/experimental-rescript-webapi/project-status/)
and [API surface guide](https://rescript-lang.github.io/experimental-rescript-webapi/api-surface/).
36 changes: 28 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,50 @@ Experimental successor to [rescript-webapi](https://github.com/TheSpyder/rescrip

## Getting started

Install the package using your favorite package manager:
ReScript `13.0.0-alpha.5` is the tested compiler baseline. Library alpha releases may contain
breaking changes. See the [project status](https://rescript-lang.github.io/experimental-rescript-webapi/project-status/)
for the accepted peer range and its testing limits.

Install the library and compiler in your application:

```shell
npm i @rescript/webapi@alpha
npm install @rescript/webapi@alpha
npm install --save-dev rescript@13.0.0-alpha.5
```

and add `@rescript/webapi` to your `rescript.json`:
The `@alpha` command targets the published alpha dist-tag. The planned `1.0.0-alpha.1` candidate
is not published yet; see [project status](https://rescript-lang.github.io/experimental-rescript-webapi/project-status/)
for the current tag and note that candidate installation is verified from its packed tarball.

Add a source directory and the package dependency to `rescript.json`:

```json
{
"dependencies": [
"@rescript/webapi"
]
"name": "webapi-consumer",
"sources": [{ "dir": "src" }],
"dependencies": ["@rescript/webapi"]
}
```

## Usage
In `src/Main.res`:

```rescript
let location = WebAPI.DOM.window->WebAPI.Window.location
let href = location.href
location->WebAPI.Location.reload
```

Compile the consumer with:

```shell
npx rescript build
```

The namespace is flat under `WebAPI`; internal implementation modules are not public API.

## Documentation

More information can be found on https://rescript-lang.github.io/experimental-rescript-webapi/
More information can be found on https://rescript-lang.github.io/experimental-rescript-webapi/.
See the [alpha release checklist](https://github.com/rescript-lang/experimental-rescript-webapi/issues/382)
and [migration notes](https://github.com/rescript-lang/experimental-rescript-webapi/blob/main/CHANGELOG.md)
for known limitations and breaking changes.
17 changes: 9 additions & 8 deletions astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,9 @@ import { readFileSync } from "node:fs";
import { defineConfig } from "astro/config";
import starlight from "@astrojs/starlight";
import { apiModules } from "./docs/utils";
import { docsBase, docsSite } from "./docs/siteConfig.js";

const rescriptTM = JSON.parse(
readFileSync("./docs/assets/rescript.tmLanguage.json", "utf-8"),
);
const rescriptTM = JSON.parse(readFileSync("./docs/assets/rescript.tmLanguage.json", "utf-8"));

const apiSidebarItems = apiModules.map(({ moduleName, link }) => ({
label: moduleName,
Expand All @@ -15,8 +14,8 @@ const apiSidebarItems = apiModules.map(({ moduleName, link }) => ({
export default defineConfig({
srcDir: "docs",
publicDir: "docs/public",
site: "https://rescript-lang.github.io",
base: "experimental-rescript-webapi",
site: docsSite,
base: docsBase,
integrations: [
starlight({
title: "Experimental WebAPI",
Expand All @@ -31,8 +30,7 @@ export default defineConfig({
},
],
editLink: {
baseUrl:
"https://github.com/rescript-lang/experimental-rescript-webapi/edit/main/",
baseUrl: "https://github.com/rescript-lang/experimental-rescript-webapi/edit/main/",
},
sidebar: [
{
Expand All @@ -44,6 +42,9 @@ export default defineConfig({
{
slug: "api-surface",
},
{
slug: "font-attribution",
},
{
label: "Examples",
link: "examples",
Expand Down Expand Up @@ -75,7 +76,7 @@ export default defineConfig({
},
},
],
customCss: ["./docs/styles/fonts.css", "./docs/styles/theme.css"],
customCss: ["./docs/styles/theme.css"],
expressiveCode: {
shiki: {
langs: [rescriptTM],
Expand Down
16 changes: 13 additions & 3 deletions docs/components/signatureItem.astro
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
import { createAPIModuleLink } from "../utils.js";
import { apiModules, createAPIModuleLink, publicTypeTargets } from "../utils.js";
const { item, typesInOwnModule } = Astro.props;

let link;
Expand All @@ -9,8 +9,18 @@ if (typesInOwnModule && typesInOwnModule.has(item.path)) {

if (item.path.startsWith("WebAPI.")) {
const paths = item.path.split(".");
if (paths.length === 3) {
link = `${import.meta.env.BASE_URL}/${createAPIModuleLink(paths[1])}#${paths[2]}`;
const moduleName = paths[1];
if (
paths.length === 3 &&
moduleName &&
apiModules.some((apiModule) => apiModule.moduleName === moduleName)
) {
link = `${import.meta.env.BASE_URL}/${createAPIModuleLink(moduleName)}#${paths[2]}`;
} else if (paths.length === 3 && moduleName && paths[2]) {
const publicType = publicTypeTargets.get(`${moduleName}.${paths[2]}`);
if (publicType) {
link = `${import.meta.env.BASE_URL}/${createAPIModuleLink(publicType.moduleName)}#${publicType.typeName}`;
}
}
}

Expand Down
15 changes: 13 additions & 2 deletions docs/content/docs/api-surface.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,19 @@ description: A practical summary of how to use the public @rescript/webapi modul
slug: "api-surface"
---

The package exposes browser APIs under the `WebAPI` namespace. In normal application code,
add the package to `rescript.json`:
The package exposes browser APIs under the `WebAPI` namespace. ReScript `13.0.0-alpha.5` is
the tested compiler baseline, and alpha releases may contain breaking changes. See
[project status](../project-status/) for the accepted peer range and its testing limits, and
the [migration notes](https://github.com/rescript-lang/experimental-rescript-webapi/blob/main/CHANGELOG.md)
for API changes.

Install `@rescript/webapi@alpha` and `rescript@13.0.0-alpha.5`, then add the package dependency.
Feature bundles are optional when consumers need to restrict compiled modules:

```json
{
"name": "webapi-consumer",
"sources": [{ "dir": "src" }],
"dependencies": ["@rescript/webapi"]
}
```
Expand All @@ -24,6 +32,9 @@ let href = location.href
location->WebAPI.Location.reload
```

For the compiler range, alpha compatibility contract, and breaking changes to byte, observer,
DOM, and crypto types, read the [alpha migration notes](https://github.com/rescript-lang/experimental-rescript-webapi/blob/main/CHANGELOG.md).

## Public module shape

The public API is flat under `WebAPI`. Use owner modules directly rather than generated
Expand Down
Loading
Loading