Changeset 489 for Dev/trunk/src/node_modules/q/README.md

Timestamp:

03/08/14 11:41:10 (11 years ago)

Author:

hendrikvanantwerpen

Message:

Update node modules

File:

• Dev/trunk/src/node_modules/q/README.md (modified) (10 diffs)

Dev/trunk/src/node_modules/q/README.md

@@ -35 +35 @@
 
 ```javascript
-Q.fcall(step1)
-.then(step2)
-.then(step3)
-.then(step4)
+Q.fcall(promisedStep1)
+.then(promisedStep2)
+.then(promisedStep3)
+.then(promisedStep4)
 .then(function (value4) {
     // Do something with value4
-}, function (error) {
-    // Handle any error from step1 through step4
+})
+.catch(function (error) {
+    // Handle any error from all above steps
 })
 .done();
 ```
 
-With this approach, you also get implicit error propagation,
-just like ``try``, ``catch``, and ``finally``.  An error in
-``step1`` will flow all the way to ``step5``, where it’s
-caught and handled.
+With this approach, you also get implicit error propagation, just like `try`,
+`catch`, and `finally`.  An error in `promisedStep1` will flow all the way to
+the `catch` function, where it’s caught and handled.  (Here `promisedStepN` is
+a version of `stepN` that returns a promise.)
 
 The callback approach is called an “inversion of control”.
@@ -77 +78 @@
 
 Q can exchange promises with jQuery, Dojo, When.js, WinJS, and more.
-Additionally, there are many libraries that produce and consume Q promises for
-everything from file system/database access or RPC to templating. For a list of
-some of the more popular ones, see [Libraries][].
-
-Please join the Q-Continuum [mailing list](https://groups.google.com/forum/#!forum/q-continuum).
-
+
+## Resources
+
+Our [wiki][] contains a number of useful resources, including:
+
+- A method-by-method [Q API reference][reference].
+- A growing [examples gallery][examples], showing how Q can be used to make
+  everything better. From XHR to database access to accessing the Flickr API,
+  Q is there for you.
+- There are many libraries that produce and consume Q promises for everything
+  from file system/database access or RPC to templating. For a list of some of
+  the more popular ones, see [Libraries][].
+- If you want materials that introduce the promise concept generally, and the
+  below tutorial isn't doing it for you, check out our collection of
+  [presentations, blog posts, and podcasts][resources].
+- A guide for those [coming from jQuery's `$.Deferred`][jquery].
+
+We'd also love to have you join the Q-Continuum [mailing list][].
+
+[wiki]: https://github.com/kriskowal/q/wiki
+[reference]: https://github.com/kriskowal/q/wiki/API-Reference
+[examples]: https://github.com/kriskowal/q/wiki/Examples-Gallery
 [Libraries]: https://github.com/kriskowal/q/wiki/Libraries
+[resources]: https://github.com/kriskowal/q/wiki/General-Promise-Resources
+[jquery]: https://github.com/kriskowal/q/wiki/Coming-from-jQuery
+[mailing list]: https://groups.google.com/forum/#!forum/q-continuum
 
 
@@ -109 +129 @@
 guarantee when mentally tracing the flow of your code, namely that
 ``then`` will always return before either handler is executed.
+
+In this tutorial, we begin with how to consume and work with promises. We'll
+talk about how to create them, and thus create functions like
+`promiseMeSomething` that return promises, [below](#the-beginning).
 
 
@@ -321 +345 @@
 var funcs = [foo, bar, baz, qux];
 
-var result = Q.resolve(initialVal);
+var result = Q(initialVal);
 funcs.forEach(function (f) {
     result = result.then(f);
@@ -333 +357 @@
 return funcs.reduce(function (soFar, f) {
     return soFar.then(f);
-}, Q.resolve(initialVal));
+}, Q(initialVal));
 ```
 
@@ -518 +542 @@
     var deferred = Q.defer();
     Q.when(promise, deferred.resolve);
-    Q.when(delay(ms), function () {
+    delay(ms).then(function () {
         deferred.reject(new Error("Timed out"));
     });
@@ -617 +641 @@
 
 ```javascript
-return Q.when($.ajax(...))
+return Q($.ajax(...))
 .then(function () {
 });
@@ -685 +709 @@
 
 If you're working with functions that make use of the Node.js callback pattern,
-Q provides a few useful utility functions for converting between them. The
-most straightforward are probably `Q.nfcall` and `Q.nfapply` ("Node function
-call/apply") for calling Node.js-style functions and getting back a promise:
+where callbacks are in the form of `function(err, result)`, Q provides a few
+useful utility functions for converting between them. The most straightforward
+are probably `Q.nfcall` and `Q.nfapply` ("Node function call/apply") for calling
+Node.js-style functions and getting back a promise:
 
 ```javascript
@@ -776 +801 @@
 to many users, you should probably keep it off. But in development, go for it!
 
-## Reference
-
-A method-by-method [Q API reference][reference] is available on the wiki.
-
-[reference]: https://github.com/kriskowal/q/wiki/API-Reference
-
-## More Examples
-
-A growing [examples gallery][examples] is available on the wiki, showing how Q
-can be used to make everything better. From XHR to database access to accessing
-the Flickr API, Q is there for you.
-
-[examples]: https://github.com/kriskowal/q/wiki/Examples-Gallery
-
 ## Tests
 
@@ -796 +807 @@
 [tests]: https://rawgithub.com/kriskowal/q/master/spec/q-spec.html
 
----
-
-Copyright 2009-2012 Kristopher Michael Kowal
+## License
+
+Copyright 2009–2013 Kristopher Michael Kowal
 MIT License (enclosed)