As mentioned on Discord earlier, we'll add these to all new functions
going forward - this is the backfill. Reasons:
- It makes you look at the spec, implementing based on MDN or V8
behavior is a no-go
- It makes finding the various functions that are non-compliant easier,
in the future everything should either have such a comment or, if it's
not from the spec at all, a comment explaining why that is the case
- It makes it easier to check whether a certain abstract operation is
implemented in LibJS, not all of them use the same name as the spec.
E.g. RejectPromise() is Promise::reject()
- It makes it easier to reason about vm.arguments(), e.g. when the
function has a rest parameter
- It makes it easier to see whether a certain function is from a
proposal or Annex B
Also:
- Add arguments to all functions and abstract operations that already
had a comment
- Fix some outdated section numbers
- Replace some ecma-international.org URLs with tc39.es
In hindsight declaring these prematurely wasn't the greatest idea - that
just makes any script checking for their existence believe they'll work,
and what follows next is a crash of the js or WebContent process. If we
omit the declarations, a polyfill can be provided instead.
This also affects the test262, which tests these - instead of reporting
a bunch of assertion crash errors, we should simply report test failure
for 'not a function', which in turn makes it easier to spot any actual
bugs causing crashes.
SPDX License Identifiers are a more compact / standardized
way of representing file license information.
See: https://spdx.dev/resources/use/#identifiers
This was done with the `ambr` search and replace tool.
ambr --no-parent-ignore --key-from-file --rep-from-file key.txt rep.txt *
Almost a year after first working on this, it's finally done: an
implementation of Promises for LibJS! :^)
The core functionality is working and closely following the spec [1].
I mostly took the pseudo code and transformed it into C++ - if you read
and understand it, you will know how the spec implements Promises; and
if you read the spec first, the code will look very familiar.
Implemented functions are:
- Promise() constructor
- Promise.prototype.then()
- Promise.prototype.catch()
- Promise.prototype.finally()
- Promise.resolve()
- Promise.reject()
For the tests I added a new function to test-js's global object,
runQueuedPromiseJobs(), which calls vm.run_queued_promise_jobs().
By design, queued jobs normally only run after the script was fully
executed, making it improssible to test handlers in individual test()
calls by default [2].
Subsequent commits include integrations into LibWeb and js(1) -
pretty-printing, running queued promise jobs when necessary.
This has an unusual amount of dbgln() statements, all hidden behind the
PROMISE_DEBUG flag - I'm leaving them in for now as they've been very
useful while debugging this, things can get quite complex with so many
asynchronously executed functions.
I've not extensively explored use of these APIs for promise-based
functionality in LibWeb (fetch(), Notification.requestPermission()
etc.), but we'll get there in due time.
[1]: https://tc39.es/ecma262/#sec-promise-objects
[2]: https://tc39.es/ecma262/#sec-jobs-and-job-queues
