Skip to content

Commit f8eb264

Browse files
committedJan 26, 2021
Clarify stdlib usage
1 parent aaa193c commit f8eb264

File tree

4 files changed

+31
-43
lines changed

4 files changed

+31
-43
lines changed
 

‎pages/docs/manual/latest/api.mdx

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
# Overview
22

3-
This section currently covers a small subset of available modules relevant for ReScript development.
3+
ReScript ships 3 modules in its standard library.
44

5-
The API documentation is still under revision and will be improved in the future.
5+
- [Js](api/js): bindings for all your familiar JavaScript APIs.
6+
- [Belt](api/belt): extra collections and helpers not available in JavaScript.
7+
- [Dom](api/dom): Dom related types and modules.
68

7-
**List of important modules:**
9+
Usage heuristics:
810

9-
- [Js](api/js): Bindings for Common Browser APIs
10-
- [Belt](api/belt): The ReScript Standard Library
11-
- [Dom](api/dom): Dom related types and modules
11+
- Default to using the `Js` module. Most of the APIs in it are runtime-free and compile down to clean, readable JavaScript, which is our priority.
12+
- For other APIs that aren't available in regular JavaScript (and thus don't exist in our `Js` bindings), use Belt. For example, prefer `Js.Array2` over `Belt.Array`.
13+
- The `Dom` module contains our standardized types used by various userland DOM bindings. Due to the complexity of DOM, we don't mind that you ignore this module and build your application-specific DOM bindings.
14+
15+
**Note**: we do not recommend other userland standard library alternatives (unless it's DOM bindings). These cause confusion and split points for the community.

‎pages/docs/manual/latest/api/js.mdx

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,14 @@
11
# Js
22

3-
The Js module mostly contains Reason bindings to _standard JavaScript APIs_
3+
The Js module mostly contains ReScript bindings to _standard JavaScript APIs_
44
like [console.log](https://developer.mozilla.org/en-US/docs/Web/API/Console/log),
55
or the JavaScript
66
[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String),
77
[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), and
88
[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
99
classes.
1010

11-
It is meant as a zero-abstraction interop layer and directly exposes
12-
JavaScript functions as they are, even when their behavior should be considered unsafe
13-
(e.g. modifying an array in place using [Js.Array.push](js/array#push)).
14-
15-
Therefore, when a corresponding module is available in the [Belt](belt) standard library,
16-
it is recommended to use the Belt version rather than the Js version.
17-
For example, you should prefer [Belt.Array](belt/array)
18-
to [Js.Array](js/array)
19-
and [Belt.Map.String](belt/map-string)
20-
to [Js.Dict](js/dict).
11+
It is meant as a zero-abstraction interop layer and directly exposes JavaScript functions as they are. If you can find your API in this module, prefer this over an equivalent Belt helper. For example, prefer [Js.Array2](js/array2) over [Belt.Array](belt/array)
2112

2213
## Argument Order
2314

@@ -34,15 +25,15 @@ In the meantime, there are several options for dealing with the data-last APIs:
3425
```res example
3526
/* Js.String (data-last API used with pipe last operator) */
3627
Js.log("2019-11-10" |> Js.String.split("-"))
37-
Js.log("Reason" |> Js.String.startsWith("Re"))
28+
Js.log("ReScript" |> Js.String.startsWith("Re"))
3829
3930
/* Js.String (data-last API used with pipe first operator) */
4031
Js.log("2019-11-10"->Js.String.split("-", _))
41-
Js.log("Reason"->Js.String.startsWith("Re", _))
32+
Js.log("ReScript"->Js.String.startsWith("Re", _))
4233
4334
/* Js.String (data-last API used without any piping) */
4435
Js.log(Js.String.split("-", "2019-11-10"))
45-
Js.log(Js.String.startsWith("Re", "Reason"))
36+
Js.log(Js.String.startsWith("Re", "ReScript"))
4637
```
4738

4839
## Object

‎pages/docs/manual/v8.0.0/api.mdx

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
# Overview
22

3-
This section currently covers a very small subset of available modules relevant
4-
for JavaScript development.
5-
6-
Please note that most of the API documentation is
7-
still under revision and will be improved in the future.
3+
We ship 3 modules in our standard library.
84

9-
**List of important modules:**
5+
- [Js](api/js): bindings for all your familiar JavaScript APIs.
6+
- [Belt](api/belt): extra collections and helpers not available in JavaScript.
7+
- [Dom](api/dom): Dom related types and modules.
108

11-
- [Belt](api/belt): The Reason Standard Library for the Web
12-
- [Js](api/js): Bindings for Common Browser APIs
13-
- [Dom](api/dom): Dom related types and modules
9+
Usage heuristics:
10+
11+
- Default to using the `Js` module. Most of the APIs in it are runtime-free and compile down to clean, readable JavaScript, which is our priority.
12+
- For other APIs that aren't available in regular JavaScript (and thus don't exist in our `Js` bindings), use Belt. For example, prefer `Js.Array2` over `Belt.Array`.
13+
- The `Dom` module contains our standardized types used by various userland DOM bindings. Due to the complexity of DOM, we don't mind that you ignore this module and build your application-specific DOM bindings.
14+
15+
**Note**: we do not recommend other userland standard library alternatives (unless it's DOM bindings). These cause confusion and split points for the community.

‎pages/docs/manual/v8.0.0/api/js.mdx

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,14 @@
11
# Js
22

3-
The Js module mostly contains Reason bindings to _standard JavaScript APIs_
3+
The Js module mostly contains ReScript bindings to _standard JavaScript APIs_
44
like [console.log](https://developer.mozilla.org/en-US/docs/Web/API/Console/log),
55
or the JavaScript
66
[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String),
77
[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), and
88
[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
99
classes.
1010

11-
It is meant as a zero-abstraction interop layer and directly exposes
12-
JavaScript functions as they are, even when their behavior should be considered unsafe
13-
(e.g. modifying an array in place using [Js.Array.push](./js/array#push)).
14-
15-
Therefore, when a corresponding module is available in the [Belt](./belt) standard library,
16-
it is recommended to use the Belt version rather than the Js version.
17-
For example, you should prefer [Belt.Array](./belt/array)
18-
to [Js.Array](./js/array)
19-
and [Belt.Map.String](./belt/map-string)
20-
to [Js.Dict](./js/dict).
11+
It is meant as a zero-abstraction interop layer and directly exposes JavaScript functions as they are. If you can find your API in this module, prefer this over an equivalent Belt helper. For example, prefer [Js.Array2](js/array2) over [Belt.Array](belt/array)
2112

2213
## Argument Order
2314

@@ -34,15 +25,15 @@ In the meantime, there are several options for dealing with the data-last APIs:
3425
```re example
3526
/* Js.String (data-last API used with pipe last operator) */
3627
Js.log("2019-11-10" |> Js.String.split("-"));
37-
Js.log("Reason" |> Js.String.startsWith("Re"));
28+
Js.log("ReScript" |> Js.String.startsWith("Re"));
3829

3930
/* Js.String (data-last API used with pipe first operator) */
4031
Js.log("2019-11-10"->Js.String.split("-", _));
41-
Js.log("Reason"->Js.String.startsWith("Re", _));
32+
Js.log("ReScript"->Js.String.startsWith("Re", _));
4233

4334
/* Js.String (data-last API used without any piping) */
4435
Js.log(Js.String.split("-", "2019-11-10"));
45-
Js.log(Js.String.startsWith("Re", "Reason"));
36+
Js.log(Js.String.startsWith("Re", "ReScript"));
4637
```
4738

4839
## Js.Xxx2 Modules

0 commit comments

Comments
 (0)
Please sign in to comment.