Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
10 changes: 9 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,21 @@ are maintained by the release workflow; see the [alpha release readiness tracker

## 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
Planned first release in the `1.0.0-alpha.N` series. ReScript `13.0.0-alpha.7` 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

- The minimum supported ReScript compiler is now `13.0.0-alpha.7` (peer range
`>=13.0.0-alpha.7 <13.0.0`). Coercing a different type into a private record is now rejected
by the compiler; use supported conversion helpers for native derived-to-base conversions.
This does not make all native records package-wide private. Typed arrays now have distinct
types: use their specific module operations, or explicitly upcast to `TypedArray.t` when a
binding requires the generic type.
- ReScript `13.0.0-alpha.7` no longer supports Intel Macs (`darwin-x64`). This package's new
compiler minimum therefore also excludes native compilation on Intel Macs.
- 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`,
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ Experimental successor to [rescript-webapi](https://github.com/TheSpyder/rescrip

## Getting started

ReScript `13.0.0-alpha.5` is the tested compiler baseline. Library alpha releases may contain
ReScript `13.0.0-alpha.7` is the 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 install @rescript/webapi@alpha
npm install --save-dev rescript@13.0.0-alpha.5
npm install --save-dev rescript@13.0.0-alpha.7
```

The `@alpha` command targets the published alpha dist-tag. The planned `1.0.0-alpha.1` candidate
Expand Down
50 changes: 20 additions & 30 deletions docs/components/signatureItem.astro
Original file line number Diff line number Diff line change
@@ -1,44 +1,34 @@
---
import { apiModules, createAPIModuleLink, publicTypeTargets } from "../utils.js";
import { signatureParts } from "../signatureParts.js";
const { item, typesInOwnModule } = Astro.props;

let link;
if (typesInOwnModule && typesInOwnModule.has(item.path)) {
link = `#${item.path}`;
}

if (item.path.startsWith("WebAPI.")) {
const paths = item.path.split(".");
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}`;
function typeLink(typePath) {
if (!typePath) return;
if (typesInOwnModule?.has(typePath)) return `#${typePath}`;
if (typePath.startsWith("WebAPI.")) {
const paths = typePath.split(".");
const moduleName = paths[1];
if (
paths.length === 3 &&
moduleName &&
apiModules.some((apiModule) => apiModule.moduleName === moduleName)
) {
return `${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) {
return `${import.meta.env.BASE_URL}/${createAPIModuleLink(publicType.moduleName)}#${publicType.typeName}`;
}
}
}
}

const genericTypeParameters = item.genericTypeParameters || [];
const parts = signatureParts(item).map((part) => ({ ...part, link: typeLink(part.path) }));
---

<span>
{link ? <a href={link}>{item.path}</a> : item.path}{
genericTypeParameters.length > 0 && (
<>
{"<"}
{genericTypeParameters.map((subItem) => (
<Astro.self typesInOwnModule={typesInOwnModule} item={subItem} />
))}
{">"}
</>
)
}
{parts.map((part) => part.link ? <a href={part.link}>{part.text}</a> : part.text)}
</span>
<style>
span {
Expand Down
6 changes: 5 additions & 1 deletion docs/components/value.astro
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,11 @@ function showValue(detail) {
<div class="value_detail">
<h4>Parameters</h4>
{details.parameters.map((p) => (
<SignatureItem item={p} typesInOwnModule={typesInOwnModule} />
<div class="parameter">
{p.label && <span>~{p.label}: </span>}
<SignatureItem item={p.type} typesInOwnModule={typesInOwnModule} />
{p.optional && <span>=?</span>}
</div>
))}
<h4>Return type</h4>
<SignatureItem item={details.returnType} typesInOwnModule={typesInOwnModule} />
Expand Down
6 changes: 3 additions & 3 deletions docs/content/docs/api-surface.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@ 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. ReScript `13.0.0-alpha.5` is
the tested compiler baseline, and alpha releases may contain breaking changes. See
The package exposes browser APIs under the `WebAPI` namespace. ReScript `13.0.0-alpha.7` is
the 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.
Install `@rescript/webapi@alpha` and `rescript@13.0.0-alpha.7`, then add the package dependency.
Feature bundles are optional when consumers need to restrict compiled modules:

```json
Expand Down
2 changes: 1 addition & 1 deletion docs/content/docs/contributing/releasing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ slug: "08-alpha-releases"

The release checklist for `@rescript/webapi` is tracked in
[#382](https://github.com/rescript-lang/experimental-rescript-webapi/issues/382). ReScript
`13.0.0-alpha.5` is the tested compiler baseline. A stable compiler is not a prerequisite;
`13.0.0-alpha.7` is the compiler baseline. A stable compiler is not a prerequisite;
library alpha releases may include breaking changes between versions.

## Prepare a candidate
Expand Down
7 changes: 6 additions & 1 deletion docs/content/docs/contributing/testing.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -74,9 +74,14 @@ Run `npm run check:consumer` to pack the current package, install that artifact
ReScript compiler in a fresh temporary project, and compile representative feature consumers.
This verifies the installed tarball rather than copied source files or local compiler links.
The development compiler and the exact version exercised by this check are ReScript
`13.0.0-alpha.5`. The peer range `>=13.0.0-alpha.5 <13.0.0` admits later `13.0.0` prereleases;
`13.0.0-alpha.7`. The peer range `>=13.0.0-alpha.7 <13.0.0` admits later `13.0.0` prereleases;
it does not claim support for earlier compilers or stable `13.0.0`.

The consumer checks reject installation with ReScript 12 and the former alpha.5 baseline.
They also verify that a public record shape cannot be coerced into the private native Response
type, while native construction, field reads, outward coercion to a public shape, and the
supported File-to-Blob conversion still work.

## Why add tests?

Sometimes adding a test can feel like a bit of a hassle. But we insist that you add tests for the following reasons:
Expand Down
6 changes: 3 additions & 3 deletions docs/content/docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ import { Tabs, TabItem, Code } from "@astrojs/starlight/components";

## Installation

ReScript `13.0.0-alpha.5` is the tested compiler baseline, and library alpha releases may
ReScript `13.0.0-alpha.7` is the compiler baseline, and library alpha releases may
include breaking changes. See [project status](./project-status/) for the accepted peer range
and its testing limits.

Expand All @@ -34,14 +34,14 @@ Install the package and tested compiler:
<Code
lang="shell"
frame="none"
code="npm install @rescript/webapi@alpha && npm install --save-dev rescript@13.0.0-alpha.5"
code="npm install @rescript/webapi@alpha && npm install --save-dev rescript@13.0.0-alpha.7"
/>
</TabItem>
<TabItem label="bun">
<Code
lang="shell"
frame="none"
code="bun i @rescript/webapi@alpha && bun add --dev rescript@13.0.0-alpha.5"
code="bun i @rescript/webapi@alpha && bun add --dev rescript@13.0.0-alpha.7"
/>
</TabItem>
</Tabs>
Expand Down
2 changes: 1 addition & 1 deletion docs/content/docs/philosophy.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The core idea of these ReScript bindings is that each interface is modeled as a

## ReScript 13 alpha compatibility

This project currently supports ReScript `13.0.0-alpha.5`. ReScript 13 is still an alpha, and
This project currently supports ReScript `13.0.0-alpha.7`. ReScript 13 is still an alpha, and
the library may continue to publish `1.0.0-alpha.N` releases alongside it. Library alpha releases
may include breaking API changes; a stable ReScript compiler is not required to use or release
this library's alpha versions. See the [API surface](../api-surface/) for the public module layout
Expand Down
8 changes: 6 additions & 2 deletions docs/content/docs/project-status.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,15 @@ varies by API and browser support is determined by the host runtime, not by whet
module compiles.

`@rescript/webapi` alpha versions can make breaking API changes between releases. ReScript
`13.0.0-alpha.5` is the tested compiler baseline. The package peer range accepts
`>=13.0.0-alpha.5 <13.0.0`, which allows later `13.0.0` prereleases but does not claim each one
`13.0.0-alpha.7` is the compiler baseline. The package peer range accepts
`>=13.0.0-alpha.7 <13.0.0`, which allows later `13.0.0` prereleases but does not claim each one
is tested; stable ReScript is not currently included in that range or required to ship this
alpha.

ReScript `13.0.0-alpha.7` no longer supports Intel Macs (`darwin-x64`), so this compiler
baseline cannot compile the package natively on Intel Macs. CI validates Linux with Node 26;
it does not establish a cross-platform compiler support matrix.

The install example uses the `alpha` dist-tag intended for `1.0.0-alpha.1`. At the time of this
candidate, npm's public `alpha` tag still resolves to `0.1.0-alpha-b1d58f9` with the old
`rescript: >=13` peer range, which excludes prerelease compilers. The `1.0.0-alpha.1` candidate is
Expand Down
39 changes: 39 additions & 0 deletions docs/signatureParts.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
const text = (value) => ({ text: value });

const separated = (items, render) =>
items.flatMap((item, index) => [...(index === 0 ? [] : [text(", ")]), ...render(item)]);

export const parameterParts = (parameter) => [
...(parameter.label ? [text(`~${parameter.label}: `)] : []),
...signatureParts(parameter.type),
...(parameter.optional ? [text("=?")] : []),
];

export const signatureParts = (item) => {
switch (item.kind) {
// Record field signatures parsed by signature.astro have no kind discriminator.
case undefined:
case "constructor":
return [
{ text: item.path, path: item.path },
...(item.genericTypeParameters?.length
? [text("<"), ...separated(item.genericTypeParameters, signatureParts), text(">")]
: []),
];
case "variable":
return [text(`'${item.name}`)];
case "rendered":
return [text(item.signature)];
case "tuple":
return [text("("), ...separated(item.elements, signatureParts), text(")")];
case "function":
return [
text("("),
...separated(item.parameters, parameterParts),
text(") => "),
...signatureParts(item.returnType),
];
default:
throw new Error(`Unsupported documentation signature kind: ${item.kind}`);
}
};
Loading
Loading