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

Move globals (ex WindowOrWorkerGlobalScope) under API/* #8351

Merged
merged 17 commits into from
Aug 31, 2021
146 changes: 79 additions & 67 deletions files/en-us/_redirects.txt

Large diffs are not rendered by default.

1,116 changes: 551 additions & 565 deletions files/en-us/_wikihistory.json

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion files/en-us/games/anatomy/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -207,7 +207,7 @@ <h3 id="Other_ways_to_handle_variable_refresh_rate_needs">Other ways to handle v
<p>One common technique is to update the simulation at a constant frequency and then draw as much (or as little) of the actual frames as possible. The update method can continue looping without care about what the user sees. The draw method can view the last update and when it happened. Since draw knows when it represents, and the simulation time for the last update, it can predict a plausible frame to draw for the user. It does not matter whether this is more frequent than the official update loop (or even less frequent). The update method sets checkpoints and, as frequently as the system allows, the render method draws instants of time around them. There are many ways to separate the update method in web standards:</p>

<ul>
<li>Draw on <code>requestAnimationFrame</code> and update on a {{ domxref("WindowOrWorkerGlobalScope/setInterval") }} or {{ domxref("WindowOrWorkerGlobalScope/setTimeout") }}.
<li>Draw on <code>requestAnimationFrame</code> and update on a {{ domxref("setInterval()") }} or {{ domxref("setTimeout()") }}.

<ul>
<li>This uses processor time even when unfocused or minimized, hogs the main thread, and is probably an artifact of traditional game loops (but it is simple.)</li>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ <h2 id="Help_the_browser_help_you">Help the browser help you</h2>

<h2 id="Use_requestAnimationFrame">Use requestAnimationFrame</h2>

<p>When you are animating {{ htmlelement("canvas") }} content, or when your DOM animations absolutely must synchronise with canvas content animations, do make sure to use {{ domxref("window.requestAnimationFrame") }}, and not older methods such as {{ domxref("WindowOrWorkerGlobalScope/setTimeout") }}. Assuming you are running in an arbitrary browsing session, you can never really know how long the browser will take to draw a particular frame. <code>requestAnimationFrame</code> causes the browser to redraw and call your function before that frame gets to the screen. The downside of using this vs. <code>setTimeout</code> is that your animations must be time-based instead of frame-based, i.e. you must keep track of time and set your animation properties based on elapsed time. <code>requestAnimationFrame</code> includes a {{ domxref("DOMHighResTimeStamp") }} in its callback function prototype, which you definitely should use (as opposed to using the {{ domxref("Date") }} object), as this will be the time the frame began rendering, and ought to make your animations look more fluid. You may have a callback that ends up looking something like this:</p>
<p>When you are animating {{ htmlelement("canvas") }} content, or when your DOM animations absolutely must synchronise with canvas content animations, do make sure to use {{ domxref("window.requestAnimationFrame") }}, and not older methods such as {{ domxref("setTimeout()") }}. Assuming you are running in an arbitrary browsing session, you can never really know how long the browser will take to draw a particular frame. <code>requestAnimationFrame</code> causes the browser to redraw and call your function before that frame gets to the screen. The downside of using this vs. <code>setTimeout</code> is that your animations must be time-based instead of frame-based, i.e. you must keep track of time and set your animation properties based on elapsed time. <code>requestAnimationFrame</code> includes a {{ domxref("DOMHighResTimeStamp") }} in its callback function prototype, which you definitely should use (as opposed to using the {{ domxref("Date") }} object), as this will be the time the frame began rendering, and ought to make your animations look more fluid. You may have a callback that ends up looking something like this:</p>

<pre class="brush: js">var startTime = -1;
var animationLength = 2000; // Animation length in milliseconds
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ <h3 id="Rendering_the_lives_display">Rendering the lives display</h3>

<h2 id="Improving_rendering_with_requestAnimationFrame">Improving rendering with requestAnimationFrame()</h2>

<p>Now let's work on something that is not connected to the game mechanics, but to the way it is being rendered. {{domxref("window.requestAnimationFrame", "requestAnimationFrame")}} helps the browser render the game better than the fixed framerate we currently have implemented using {{domxref("WindowOrWorkerGlobalScope/setInterval", "setInterval()")}}. Replace the following line:</p>
<p>Now let's work on something that is not connected to the game mechanics, but to the way it is being rendered. {{domxref("window.requestAnimationFrame", "requestAnimationFrame")}} helps the browser render the game better than the fixed framerate we currently have implemented using {{domxref("setInterval()")}}. Replace the following line:</p>

<pre class="brush: js">var interval = setInterval(draw, 10);</pre>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@

<h2 id="Defining_a_drawing_loop">Defining a drawing loop</h2>

<p>To keep constantly updating the canvas drawing on each frame, we need to define a drawing function that will run over and over again, with a different set of variable values each time to change sprite positions, etc. You can run a function over and over again using a JavaScript timing function such as {{domxref("WindowOrWorkerGlobalScope/setInterval", "setInterval()")}} or {{domxref("window.requestAnimationFrame()", "requestAnimationFrame()")}}.</p>
<p>To keep constantly updating the canvas drawing on each frame, we need to define a drawing function that will run over and over again, with a different set of variable values each time to change sprite positions, etc. You can run a function over and over again using a JavaScript timing function such as {{domxref("setInterval()")}} or {{domxref("window.requestAnimationFrame()", "requestAnimationFrame()")}}.</p>

<p>Delete all the JavaScript you currently have inside your HTML file except for the first two lines, and add the following below them. The <code>draw()</code> function will be executed within <code>setInterval</code> every 10 milliseconds:</p>

Expand Down
6 changes: 3 additions & 3 deletions files/en-us/glossary/base64/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,13 @@
<p>In JavaScript there are two functions respectively for decoding and encoding Base64 strings:</p>

<ul>
<li><code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa">btoa()</a></code>: creates a Base64-encoded ASCII string from a "string" of binary data ("btoa" should be read as "binary to ASCII").</li>
<li><code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/atob">atob()</a></code>: decodes a Base64-encoded string("atob" should be read as "ASCII to binary").</li>
<li><code><a href="/en-US/docs/Web/API/btoa">btoa()</a></code>: creates a Base64-encoded ASCII string from a "string" of binary data ("btoa" should be read as "binary to ASCII").</li>
<li><code><a href="/en-US/docs/Web/API/atob">atob()</a></code>: decodes a Base64-encoded string("atob" should be read as "ASCII to binary").</li>
</ul>

<p>The algorithm used by <code>atob()</code> and <code>btoa()</code> is specified in <a href="https://datatracker.ietf.org/doc/html/rfc4648">RFC 4648</a>, section 4.</p>

<p>Note that <code>btoa()</code> expects to be passed binary data, and will throw an exception if the given string contains any characters whose UTF-16 representation occupies more than one byte. For more details, see the documentation for <code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/btoa">btoa()</a></code>.</p>
<p>Note that <code>btoa()</code> expects to be passed binary data, and will throw an exception if the given string contains any characters whose UTF-16 representation occupies more than one byte. For more details, see the documentation for <code><a href="/en-US/docs/Web/API/btoa">btoa()</a></code>.</p>

<h2 id="Encoded_size_increase">Encoded size increase</h2>

Expand Down
2 changes: 1 addition & 1 deletion files/en-us/glossary/callback_function/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@

<p>The above example is a {{glossary("synchronous")}} callback, as it is executed immediately.</p>

<p>Note, however, that callbacks are often used to continue code execution after an {{glossary("asynchronous")}} operation has completed — these are called asynchronous callbacks. A good example is the callback functions executed inside a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then">.then()</a></code> block chained onto the end of a promise after that promise fulfills or rejects. This structure is used in many modern web APIs, such as <code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch">fetch()</a></code>.</p>
<p>Note, however, that callbacks are often used to continue code execution after an {{glossary("asynchronous")}} operation has completed — these are called asynchronous callbacks. A good example is the callback functions executed inside a <code><a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then">.then()</a></code> block chained onto the end of a promise after that promise fulfills or rejects. This structure is used in many modern web APIs, such as <code><a href="/en-US/docs/Web/API/fetch">fetch()</a></code>.</p>

<h2 id="Learn_more">Learn more</h2>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -212,7 +212,7 @@ <h3 id="Dynamic_content_updates">Dynamic content updates</h3>
&lt;/blockquote&gt;
&lt;/section&gt;</pre>

<p>Our JavaScript loads a JSON file via <code><a href="/en-US/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code> containing a series of random quotes and their authors. Once that is done, we start up a <code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval">setInterval()</a></code> loop that loads a new random quote into the quote box every 10 seconds:</p>
<p>Our JavaScript loads a JSON file via <code><a href="/en-US/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code> containing a series of random quotes and their authors. Once that is done, we start up a <code><a href="/en-US/docs/Web/API/setInterval">setInterval()</a></code> loop that loads a new random quote into the quote box every 10 seconds:</p>

<pre class="brush: js">let intervalID = window.setInterval(showQuote, 10000);</pre>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -320,7 +320,7 @@ <h2 id="handling_asyncawait_slowdown">Handling async/await slowdown</h2>

<p>As a result, your code could be slowed down by a significant number of awaited promises happening straight after one another. Each <code>await</code> will wait for the previous one to finish, whereas actually what you might want is for the promises to begin processing simultaneously, like they would do if we weren't using async/await.</p>

<p>Let's look at two examples — <a href="https://mdn.github.io/learning-area/javascript/asynchronous/async-await/slow-async-await.html">slow-async-await.html</a> (see <a href="https://github.com/mdn/learning-area/blob/master/javascript/asynchronous/async-await/slow-async-await.html">source code</a>) and <a href="https://mdn.github.io/learning-area/javascript/asynchronous/async-await/fast-async-await.html">fast-async-await.html</a> (see <a href="https://github.com/mdn/learning-area/blob/master/javascript/asynchronous/async-await/fast-async-await.html">source code</a>). Both of them start off with a custom promise function that fakes an async process with a <code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout">setTimeout()</a></code> call:</p>
<p>Let's look at two examples — <a href="https://mdn.github.io/learning-area/javascript/asynchronous/async-await/slow-async-await.html">slow-async-await.html</a> (see <a href="https://github.com/mdn/learning-area/blob/master/javascript/asynchronous/async-await/slow-async-await.html">source code</a>) and <a href="https://mdn.github.io/learning-area/javascript/asynchronous/async-await/fast-async-await.html">fast-async-await.html</a> (see <a href="https://github.com/mdn/learning-area/blob/master/javascript/asynchronous/async-await/fast-async-await.html">source code</a>). Both of them start off with a custom promise function that fakes an async process with a <code><a href="/en-US/docs/Web/API/setTimeout">setTimeout()</a></code> call:</p>

<pre class="brush: js">function timeoutPromise(interval) {
return new Promise((resolve, reject) =&gt; {
Expand Down Expand Up @@ -451,7 +451,7 @@ <h3 id="handling_errors">Handling errors</h3>

<p>In this example, we have an unhandled error in the console (after 2 seconds), and the alert appears after approximately 5 seconds.</p>

<p>To start the promises in parallel and catch the error properly, we could use <code>Promise.all()</code>, as discussed earlier:</p>
<p>To start the promises in parallel and catch the error properly, we could use <code>Promise.all()</code>, as discussed earlier:</p>

<pre class="brush: js">function timeoutPromiseResolve(interval) {
return new Promise((resolve, reject) => {
Expand Down Expand Up @@ -489,7 +489,7 @@ <h3 id="handling_errors">Handling errors</h3>

<p>In this example, the error is handled properly after around 2 seconds and we also see the alert after around 2 seconds.</p>

<p>The <code>Promise.all()</code> rejects when any of the input promises are rejected. If you want all the promises to settle and then use some of their fulfilled values, even when some of
<p>The <code>Promise.all()</code> rejects when any of the input promises are rejected. If you want all the promises to settle and then use some of their fulfilled values, even when some of
them are rejected, you could use <a href="/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled"><code>Promise.allSettled()</code></a> instead.</p>

<h2 id="Asyncawait_class_methods">Async/await class methods</h2>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ <h3 id="Further_information">Further information</h3>

<h2 id="setTimeout">setTimeout()</h2>

<p><code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout">setTimeout()</a></code> is a method that allows you to run a function after an arbitrary amount of time has passed.</p>
<p><code><a href="/en-US/docs/Web/API/setTimeout">setTimeout()</a></code> is a method that allows you to run a function after an arbitrary amount of time has passed.</p>

<table class="standard-table">
<caption>Useful for...</caption>
Expand Down Expand Up @@ -158,18 +158,18 @@ <h3 id="Pitfalls_2">Pitfalls</h3>

<h3 id="Browser_compatibility_2">Browser compatibility</h3>

<p>{{Compat("api.WindowOrWorkerGlobalScope.setTimeout")}}</p>
<p>{{Compat("api.setTimeout")}}</p>

<h3 id="Further_information_2">Further information</h3>

<ul>
<li><a href="/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals">Cooperative asynchronous JavaScript: Timeouts and intervals</a>, in particular <a href="/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals#settimeout()">setTimeout()</a></li>
<li><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout">setTimeout() reference</a></li>
<li><a href="/en-US/docs/Web/API/setTimeout">setTimeout() reference</a></li>
</ul>

<h2 id="setInterval">setInterval()</h2>

<p><code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval">setInterval()</a></code> is a method that allows you to run a function repeatedly with a set interval of time between each execution. Not as efficient as <code><a href="/en-US/docs/Web/API/window/requestAnimationFrame">requestAnimationFrame()</a></code>, but allows you to choose a running rate/frame rate.</p>
<p><code><a href="/en-US/docs/Web/API/setInterval">setInterval()</a></code> is a method that allows you to run a function repeatedly with a set interval of time between each execution. Not as efficient as <code><a href="/en-US/docs/Web/API/window/requestAnimationFrame">requestAnimationFrame()</a></code>, but allows you to choose a running rate/frame rate.</p>

<table class="standard-table">
<caption>Useful for...</caption>
Expand Down Expand Up @@ -209,13 +209,13 @@ <h3 id="Pitfalls_3">Pitfalls</h3>

<h3 id="Browser_compatibility_3">Browser compatibility</h3>

<p>{{Compat("api.WindowOrWorkerGlobalScope.setInterval")}}</p>
<p>{{Compat("api.setInterval")}}</p>

<h3 id="Further_information_3">Further information</h3>

<ul>
<li><a href="/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals">Cooperative asynchronous JavaScript: Timeouts and intervals</a>, in particular <a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval">setInterval()</a></li>
<li><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval">setInterval() reference</a></li>
<li><a href="/en-US/docs/Learn/JavaScript/Asynchronous/Timeouts_and_intervals">Cooperative asynchronous JavaScript: Timeouts and intervals</a>, in particular <a href="/en-US/docs/Web/API/setInterval">setInterval()</a></li>
<li><a href="/en-US/docs/Web/API/setInterval">setInterval() reference</a></li>
</ul>

<h2 id="requestAnimationFrame">requestAnimationFrame()</h2>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@ <h2 id="Async_callbacks">Async callbacks</h2>

<h2 id="Promises">Promises</h2>

<p>Promises are the new style of async code that you'll see used in modern Web APIs. A good example is the <code><a href="/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch">fetch()</a></code> API, which is basically like a modern, more efficient version of {{domxref("XMLHttpRequest")}}. Let's look at a quick example, from our <a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Fetching_data">Fetching data from the server</a> article:</p>
<p>Promises are the new style of async code that you'll see used in modern Web APIs. A good example is the <code><a href="/en-US/docs/Web/API/fetch">fetch()</a></code> API, which is basically like a modern, more efficient version of {{domxref("XMLHttpRequest")}}. Let's look at a quick example, from our <a href="/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Fetching_data">Fetching data from the server</a> article:</p>

<pre class="brush: js">fetch('products.json').then(function(response) {
  return response.json();
Expand Down
Loading