Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove all reason-promise mentions except the package #81

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
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
32 changes: 16 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,18 @@ Promise.resolved("Hello")
As you can see on the first line, `Promise.t` maps directly to familiar JS
promises from your JS runtime. That means...

- You can use `reason-promise` directly to [write JS bindings](#Bindings).
- All JS tooling for promises immediately works with `reason-promise`.
- You can use `Promise` directly to [write JS bindings](#Bindings).
- All JS tooling for promises immediately works with `Promise`.
- Even if you do something exotic, like switch out the promise implementation at
the JS level, for, say, better stack traces, `reason-promise` still binds to
the JS level, for, say, better stack traces, `Promise` still binds to
it!

<br/>

There is only one exception to the rule that `Promise.t` maps directly to JS
promises: when there is a promise nested inside another promise. JS [breaks the
type safety](#JSPromiseFlattening) of promises in a misguided attempt to
disallow nesting. [`reason-promise` instead emulates it in a way that makes
disallow nesting. [`Promise` instead emulates it in a way that makes
promises type-safe again](#TypeSafety). This is in contrast to BuckleScript's
built-in `Js.Promise`, which directly exposes the JS behavior, and so is not
type-safe.
Expand All @@ -40,10 +40,10 @@ type-safe.

In addition:

- `reason-promise` offers a clean functional API, which replaces rejection with
- `Promise` offers a clean functional API, which replaces rejection with
[helpers for `Result` and `Option`](#Errors).
- `reason-promise` is tiny. It weighs in at about [1K bundled][bundle-size].
- `reason-promise` also has a full, standalone [pure-OCaml
- `Promise` is tiny. It weighs in at about [1K bundled][bundle-size].
- `Promise` also has a full, standalone [pure-OCaml
implementation][native], which passes all the same tests. It can be used for
native code or in JS.

Expand All @@ -65,7 +65,7 @@ In addition:
- [**Advanced: Rejection**](#Rejection)
- [**Advanced: Bindings**](#Bindings)
- [**Discussion: Why JS promises are unsafe**](#JSPromiseFlattening)
- [**Discussion: How `reason-promise` makes promises type-safe**](#TypeSafety)
- [**Discussion: How `Promise` makes promises type-safe**](#TypeSafety)

<br/>

Expand Down Expand Up @@ -569,7 +569,7 @@ directly, safely be used from ReScript.
<br/>

<a id="TypeSafety"></a>
### Discussion: How `reason-promise` makes promises type-safe
### Discussion: How `Promise` makes promises type-safe

The [previous section](#JSPromiseFlattening) shows that JS promise functions are
broken. An important observation is that it is only the *functions* that are
Expand All @@ -579,14 +579,14 @@ safe replacement functions to use with it in ReScript. This is good news
for interop :)

To fix the functions, only the [special-case flattening](#JSPromiseFlattening)
has to be undone. So, when you call `reason-promise`'s
has to be undone. So, when you call `Promise`'s
[`Promise.resolved(value)`][resolved], it checks whether `value` is a promise
or not, and...

- If `value` *is not* a promise, `reason-promise` just passes it to JS's
- If `value` *is not* a promise, `Promise` just passes it to JS's
[`Promise.resolve`][Promise.resolve], because JS will do the right thing.
- If `value` *is* a promise, it's not safe to simply pass it to JS, because it
will trigger the special-casing. So, `reason-promise` boxes the nested
will trigger the special-casing. So, `Promise` boxes the nested
promise:

```rescript
Expand All @@ -600,17 +600,17 @@ or not, and...
enough to suppress the special-casing.

Whenever you try to take the value out of this resulting structure (for
example, by calling [`Promise.get`][get] on it), `reason-promise`
example, by calling [`Promise.get`][get] on it), `Promise`
transparently unboxes the `PromiseBox` and passes the nested promise to your
callback &mdash; as your callback would expect.

This conditional boxing and unboxing is done throughout `reason-promise`. It
This conditional boxing and unboxing is done throughout `Promise`. It
only happens for nested promises, and anything else with a `.then` method. For
all other values, `reason-promise` behaves, internally, exactly like JS
all other values, `Promise` behaves, internally, exactly like JS
`Promise` (though with a cleaner outer API). This is enough to make promises
type-safe.

This is a simple scheme, but `reason-promise` includes a very thorough
This is a simple scheme, but `Promise` includes a very thorough
[test suite][tests] to be extra sure that it always manages the boxing
correctly.

Expand Down
2 changes: 1 addition & 1 deletion src/js/promise.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down
2 changes: 1 addition & 1 deletion src/js/promise.rei
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down
2 changes: 1 addition & 1 deletion src/native/mutableList.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down
4 changes: 2 additions & 2 deletions src/native/mutableList.rei
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */



/* Mutable doubly-linked lists, like in a typical imperative language. These are
used for callback lists, because reason-promise needs fast append and fast
used for callback lists, because Promise needs fast append and fast
deletion of any node in the list, when the reference to the target node is
already be held by the deleting code. */

Expand Down
2 changes: 1 addition & 1 deletion src/native/promise.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down
4 changes: 2 additions & 2 deletions src/native/promise.rei
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down Expand Up @@ -281,7 +281,7 @@ let onUnhandledException: ref(exn => unit);
module ReadyCallbacks: {
let callbacksPending: unit => bool;

/* When about to iterate over the ready callbacks, reason-promise first takes
/* When about to iterate over the ready callbacks, Promise first takes
a snapshot of them, and iterates over the snapshot. This is to prevent new
ready callbacks, that may be created by the processing of the current ones,
from being processed immediately. That could lead to I/O loop starvation
Expand Down
2 changes: 1 addition & 1 deletion test/framework/js/run.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down
2 changes: 1 addition & 1 deletion test/framework/native/run.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down
2 changes: 1 addition & 1 deletion test/js/benchmark.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down
6 changes: 3 additions & 3 deletions test/js/test_ffi.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down Expand Up @@ -69,14 +69,14 @@ let interopTests = Framework.suite("interop", [
Promise.resolved(isPromise(p));
}),

test("js promise is reason-promise", () => {
test("js promise is Promise", () => {
let js_promise: Promise.t(int) = [%bs.raw {|Promise.resolve(1)|}];
js_promise
->Promise.flatMap(n => Promise.resolved(n + 1))
->Promise.flatMap(n => Promise.resolved(n == 2));
}),

test("reason-promise as js argument", () => {
test("Promise as js argument", () => {
module Then = {
[@bs.send.pipe: Promise.t('a)]
external js_then: ('a => Promise.t('b)) => Promise.t('b) =
Expand Down
2 changes: 1 addition & 1 deletion test/native/test_ffi.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down
4 changes: 2 additions & 2 deletions test/test_main.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand All @@ -9,4 +9,4 @@ let tests =
@ Test_ffi.suites;

let () =
Framework.run("reason-promise", tests);
Framework.run("Promise", tests);
2 changes: 1 addition & 1 deletion test/test_promise.re
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
/* This file is part of reason-promise, released under the MIT license. See
/* This file is part of Promise, released under the MIT license. See
LICENSE.md for details, or visit
https://github.com/aantron/promise/blob/master/LICENSE.md. */

Expand Down