Skip to content
This repository was archived by the owner on Jan 22, 2024. It is now read-only.

Promises: Update browser support #921

Merged
merged 1 commit into from
Jan 27, 2014
Merged

Promises: Update browser support #921

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
42 changes: 19 additions & 23 deletions content/tutorials/es6/promises/en/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ <h2 id="toc-async">What's all the fuss about?</h2>
<p>You've probably used events and callbacks to get around this. Here are events:</p>

<pre class="prettyprint">var img1 = document.querySelector('.img-1');

img1.addEventListener('load', function() {
// woo yey image loaded
});
Expand Down Expand Up @@ -142,7 +142,7 @@ <h2 id="toc-promise-terminology">Promise terminology</h2>
<dd>Has fulfilled or rejected</dd>
</dl>

<p>The spec also uses the term <strong>thenable</strong> to describe an object that is promise-like, in that it has a "then" method. This term reminds me of ex-England Football Manager <a href="http://en.wikipedia.org/wiki/Terry_Venables">Terry Venables</a> so I'll be using it as little as possible.</p>
<p><a href="http://people.mozilla.org/~jorendorff/es6-draft.html#sec-promise-objects">The spec</a> also uses the term <strong>thenable</strong> to describe an object that is promise-like, in that it has a <code>then</code> method. This term reminds me of ex-England Football Manager <a href="http://en.wikipedia.org/wiki/Terry_Venables">Terry Venables</a> so I'll be using it as little as possible.</p>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Link no longer works.


<h2 id="toc-javascript-promises">Promises arrive in JavaScript!</h2>
<p>Promises have been around for a while in the form of libraries, such as:</p>
Expand All @@ -159,7 +159,7 @@ <h2 id="toc-javascript-promises">Promises arrive in JavaScript!</h2>

<pre class="prettyprint">var promise = new Promise(function(resolve, reject) {
// do a thing, possibly async, then…

if (/* everything turned out fine */) {
resolve("Stuff worked!");
}
Expand All @@ -183,14 +183,13 @@ <h2 id="toc-javascript-promises">Promises arrive in JavaScript!</h2>
<p>Although they're a JavaScript feature, the DOM isn't afraid to use them. In fact, all new DOM APIs with async success/failure methods will use promises. This is happening already with <a href="https://dvcs.w3.org/hg/quota/raw-file/tip/Overview.html#idl-def-StorageQuota">Quota Management</a>, <a href="http://dev.w3.org/csswg/css-font-load-events/#dom-fontface-ready">Font Load Events</a>,<a href="https://github.com/slightlyoff/ServiceWorker/blob/cf459d473ae09f6994e8539113d277cbd2bce939/service_worker.ts#L17"> ServiceWorker</a>, <a href="http://webaudio.github.io/web-midi-api/#widl-Navigator-requestMIDIAccess-Promise-MIDIOptions-options">Web MIDI</a>, <a href="https://github.com/whatwg/streams#basereadablestream">Streams</a>, and more.</p>

<h2 id="toc-browser-support">Browser support &amp; polyfill</h2>
<p>There are already (partial) implementations of promises in browsers today.</p>
<p>When in Chrome, do as the Chromans do. <a href="https://www.google.com/intl/en/chrome/browser/canary.html">Download Canary</a>, which has promises enabled by default. Alternatively, if you're of the Firefox persuasion, <a href="http://nightly.mozilla.org/">grab their latest nightly</a>, which also features promises.</p>
<p>There are already implementations of promises in browsers today.</p>
<p>As of Chrome 32 and Opera 19, promises are enabled by default. Alternatively, if you're of the Firefox persuasion, <a href="http://nightly.mozilla.org/">grab their latest nightly</a>, which has <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=918806">partial</a> promises support.</p>
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So sorry I had to get rid of the joke here :( You can probably work it back in somehow.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jaffathecake - can you sort this merge.
On 27 Jan 2014 10:05, "Mathias Bynens" [email protected] wrote:

In content/tutorials/es6/promises/en/index.html:

@@ -183,14 +183,13 @@

Promises arrive in JavaScript!

Although they're a JavaScript feature, the DOM isn't afraid to use them. In fact, all new DOM APIs with async success/failure methods will use promises. This is happening already with Quota Management, Font Load Events, ServiceWorker, Web MIDI, Streams, and more.

Browser support & polyfill

-

There are already (partial) implementations of promises in browsers today.

-

When in Chrome, do as the Chromans do. Download Canary, which has promises enabled by default. Alternatively, if you're of the Firefox persuasion, grab their latest nightly, which also features promises.

+

There are already implementations of promises in browsers today.

+

As of Chrome 32 and Opera 19, promises are enabled by default. Alternatively, if you're of the Firefox persuasion, grab their latest nightly, which has partial promises support.

So sorry I had to get rid of the joke here :( You can probably work it
back in somehow.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/921/files#r9197279
.


<p>Neither has a complete or fully compliant implementation. You can track <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=918806">Firefox's development on bugzilla</a>, and <a href="http://www.chromestatus.com/features/5681726336532480">Chrome's on the feature dashboard</a>.</p>
<p>To bring those browsers up to spec compliance, or add promises to other browsers and Node.js, check out <a href="https://github.com/jakearchibald/ES6-Promises/blob/master/README.md">the polyfill</a> (2k gzipped).</p>
<p>To bring browsers that lack a complete promises implementation up to spec compliance, or add promises to other browsers and Node.js, check out <a href="https://github.com/jakearchibald/ES6-Promises#readme">the polyfill</a> (2k gzipped).</p>

<h2 id="toc-lib-compatibility">Compatibility with other libraries</h2>
<p>The JavaScript promises API will treat anything with a "then" method as promise-like (or <em>thenable</em> in promise-speak <em>*sigh*</em>), and with the exception of <code>Promise.cast</code> there's no distinction made between JavaScript promise instances and things that are promise-like. So if you use a library that returns a Q promise, that's fine, it'll play nice with the new JavaScript promises.</p>
<p>The JavaScript promises API will treat anything with a <code>then</code> method as promise-like (or <em>thenable</em> in promise-speak <em>*sigh*</em>), and with the exception of <code>Promise.cast</code> there's no distinction made between JavaScript promise instances and things that are promise-like. So if you use a library that returns a Q promise, that's fine, it'll play nice with the new JavaScript promises.</p>
<p>Although, as I mentioned, jQuery's Deferreds are a bit… unhelpful. Thankfully you can cast them to standard promises, which is worth doing as soon as possible:</p>

<pre class="prettyprint">var jsPromise = Promise.cast($.ajax('/whatever.json'));</pre>
Expand Down Expand Up @@ -332,14 +331,14 @@ <h3 id="toc-promises-queues">Queuing asynchronous actions</h3>
});</pre>

<p>Here we make an async request to "story.json", which gives us a set of URLs to request, then we request the first of those. This is when promises really start to stand out from simple callback patterns.

You could even make a shortcut method to get chapters:</p>

<pre class="prettyprint">var storyPromise;

function getChapter(i) {
storyPromise = storyPromise || getJSON('story.json');

return storyPromise.then(function(story) {
return getJSON(story.chapterUrls[i]);
})
Expand Down Expand Up @@ -739,39 +738,36 @@ <h2 class="toc-generators">Bonus round: Promises and Generators</h2>
document.querySelector('.spinner').style.display = 'none';
});</pre>

<p>This works exactly as before, but so much easier to read. This works in Chrome Canary today (<a href="async-generators-example.html">see example</a>), but first you need to go to <strong>about:flags</strong> and turn on <strong>Enable experimental JavaScript</strong>.</p>
<p>This works exactly as before, but the code is so much easier to read. It works in Chrome and Opera today (<a href="async-generators-example.html">see example</a>).</p>

<p>This throws together a lot of new ES6 stuff: promises, generators, let, for-of. When we yield a promise, the spawn helper waits for the promise to resolve and returns the final value. If the promise rejects, spawn causes our yield statement to throw an exception, which we can catch with normal JavaScript try/catch. Amazingly simple async coding!</p>

<h2 id="toc-api">Promise API Reference</h2>

<p>All methods work in the nightly versions of Chrome and Firefox unless otherwise noted. <a href="https://github.com/jakearchibald/ES6-Promises/blob/master/README.md">The polyfill</a> provides the below for all browers.</p>
<p>All methods work in Chrome, Opera and in Firefox Nightly unless otherwise noted. <a href="https://github.com/jakearchibald/ES6-Promises#readme">The polyfill</a> provides the below for all browers.</p>

<h3>Static Methods</h3>
<dl>
<dt><code>Promise.cast(promise);</code></dt>
<dd>Returns promise (only if <code>promise.constructor == Promise</code>)
<p class="notice"><b>Note:</b> Only implemented in Chrome so far</p></dd>
<p class="notice"><b>Note:</b> Only implemented in Chrome and Opera so far</p></dd>
<dt><code>Promise.cast(obj);</code></dt>
<dd>Make a promise that fulfills to obj.
<p class="notice"><b>Note:</b> Only implemented in Chrome so far</p></dd>
<p class="notice"><b>Note:</b> Only implemented in Chrome and Opera so far</p></dd>
<dt><code>Promise.resolve(thenable);</code></dt>
<dd>Make a new promise from the thenable. A thenable is promise-like in as far as it has a "then" method. This also creates a new promise if you pass it a genuine JavaScript promise, making it less efficient for casting than <code>Promise.cast</code>.
<p class="notice"><b>Note:</b> Chrome incorrectly calls this <code>Promise.resolved</code></p>
</dd>
<dt><code>Promise.resolve(obj);</code></dt>
<dd>Make a promise that fulfills to obj. Same as <code>Promise.cast(obj)</code> in this situation.
<p class="notice"><b>Note:</b> Chrome incorrectly calls this <code>Promise.resolved</code></p></dd>
<dd>Make a promise that fulfills to <code>obj</code>. Same as <code>Promise.cast(obj)</code> in this situation.
<dt><code>Promise.reject(obj);</code></dt>
<dd>Make a promise that rejects to obj. For consistency and debugging (eg stack traces), obj should be an <code>instanceof Error</code>
<p class="notice"><b>Note:</b> Chrome incorrectly calls this <code>Promise.rejected</code></p>
<dd>Make a promise that rejects to <code>obj</code>. For consistency and debugging (e.g. stack traces), <code>obj</code> should be an <code>instanceof Error</code>.
<dt>
<dt><code>Promise.all(array);</code></dt>
<dd>Make a promise that fulfills when every item in the array fulfills, and rejects if (and when) any item rejects. Each array item is passed to Promise.cast, so the array can be a mixture of promise-like objects and other objects. The fulfillment value is an array (in order) of fulfillment values. The rejection value is the first rejection value.
<p class="notice"><b>Note:</b> Only implemented in Chrome so far</p></dd>
<dd>Make a promise that fulfills when every item in the array fulfills, and rejects if (and when) any item rejects. Each array item is passed to <code>Promise.cast</code>, so the array can be a mixture of promise-like objects and other objects. The fulfillment value is an array (in order) of fulfillment values. The rejection value is the first rejection value.
<p class="notice"><b>Note:</b> Only implemented in Chrome and Opera so far</p></dd>
<dt><code>Promise.race(array);</code></dt>
<dd>Make a Promise that fulfills when any item fulfills, and rejects if any item rejects.
<p class="notice"><b>Note:</b> Only implemented in Chrome as <code>Promise.one</code>. Also, I'm unconvinced of it's usefulness, I'd rather have an opposite of <code>Promise.all</code> that only rejected if all items rejected.</p></dd>
<dd>Make a Promise that fulfills as soon as any item fulfills, or rejects as soon as any item rejects, whichever happens first.
<p class="notice"><b>Note:</b> Only implemented in Chrome and Opera. Also, I'm unconvinced of its usefulness; I'd rather have an opposite of <code>Promise.all</code> that only rejected if all items rejected.</p></dd>
</dl>

<h3>Constructor</h3>
Expand Down