Learning jQuery Deferreds

Preface

The world of JavaScript has changed significantly in recent years with more sophistication in client-side JavaScript applications and the arrival of server-side JavaScript using node.js.

In building increasingly complex applications, JavaScript programmers have had to become more adept at dealing with asynchronous APIs. In earlier years, JavaScript was all client side. Programmers were only required to deal with single, independent asynchronous function calls, whose results were used to update an HTML user interface.

The situation today is far richer. Server-side JavaScript applications regularly make multiple asynchronous calls to many other services to produce responses: to databases, caches, load balancers, the filesystem, authentication systems, third-party APIs, etc. Meanwhile, client-side JavaScript now has routine access to dozens of asynchronous APIs, such as those provided by HTML5 as well as good old AJAX (remember, the first A in AJAX stands for asynchronous). Applications need to be able to coordinate simultaneous calls to multiple asynchronous APIs: to get the fastest result, to combine information, to wait for multiple calls to complete, to execute calls in specific orders, to alter the flow of control depending on results, to deal with errors, to fall back to alternate services (e.g., on cache misses), to retry failing network calls, and so on.

“Callback hell,” a phrase with about 10,000 Google hits, describes what happens when programmers try to build modern applications with old-school single-callback programming. For many programmers, this pain is their daily reality. Using single callbacks to build applications that need to do even basic coordination of asynchronous calls can be very difficult. You have to think hard and often end up with complicated, brittle, and opaque solutions. These contain hard-to-find bugs, are hard to document, and can be very hard to extend when additional asynchronous requirements enter the picture. Coding for multiple asynchronous events with the single-callback model is a real challenge, even for very smart and experienced programmers.

About You

Firstly, we’re writing for jQuery programmers who do not know about deferreds. We’ve found that most programmers who use jQuery have never heard of deferreds. Among those who have, there are many who find deferreds confusing or who are under the false impression that they are too abstract or difficult to understand. Deferreds are a misunderstood yet powerful programming paradigm. Recently, deferreds have been added to many JavaScript libraries and frameworks, and are now attracting widespread attention. A search for “deferreds” on StackOverflow currently gives over 18,000 hits, up 40% in the six months since we started this book.

We also want to help JavaScript programmers, both client side and server side, who know about deferreds but aren’t making heavy use of them. If you’d like to beef up your practical knowledge, to see more examples in action, and to think about deferreds from different angles, we’d love to have you as a reader. We want to help you stretch your mind, in both breadth and depth; the book has 18 real-world examples of deferred use along with 75 challenges (and their solutions) to push your thinking.

Finally, and most ambitiously, we hope we’ve written a book that will be useful and stimulating to programmers using deferreds and promises beyond those in jQuery and even beyond JavaScript. The conceptual underpinnings of deferreds are almost identical across the many JavaScript packages and other programming languages that support them. Because the concepts are so similar and so few, you’ll find it straightforward to port code between implementations. Virtually everything you learn in this book will be useful for working with other flavors of deferreds. We want it to be a fun and valuable read, no matter what your preferred language is. We’ve tried to write the book we wish had been available as we learned deferreds ourselves.

Our Aims

In this book we’ll teach you how to avoid callback hell by using deferreds.

But there’s much more to deferreds than that. Deferreds provide something that was not there before: a simple mechanism for dealing with future results. This gives you the opportunity to do things in different ways that go beyond mere simplification of syntax. It gives you the opportunity to really think about the practice of programming and to broaden your mental toolkit. The thinking can of course be critical, including conclusions about which deferred package to use or whether it is even sensible to use deferreds in a given situation. For us, the process of learning about and beginning to appreciate programming with deferreds was a feeling of our brains growing new muscles.

Our primary aim is to introduce deferreds to programmers who have had no exposure to them. We’re aiming to give you a really strong general and concrete understanding of what deferreds are and how to wield them. If we succeed, you’ll be fully confident when encountering deferreds in any other context: whether with another JavaScript deferred package or in a different programming language.

A secondary aim is to provide a broad collection of examples of nontrivial real-world deferred uses. We’ve been programming with deferreds (in Python and JavaScript) for the last 7 years and have pulled together some of the most useful examples we’ve built in that time. These are usually relatively short snippets of code, around 100 lines, but sometimes require careful thought to develop. We hope the detailed recipes in Chapter 3 will be a place you’ll return to for ideas on how to approach deferred problems you face.

Challenges

The deferred recipes in Chapter 3 all leave you with a set of challenges. These are meant to encourage you to engage with and think more deeply about the material just presented. If you want to write code as well, that’s a bonus. The main point, however, is to think. Don’t be a passive reader! Working with deferreds very often requires focused thinking about how problems, and small variations on them, might be solved. Once you “get” deferreds, solving puzzles with them can be very engaging. The more you do it, the better you get, and the more you see their flexibility and power. Above all though, figuring out how to do things with deferreds is just plain fun!

If you’re stuck on a challenge, you’ll find hints and solutions in Appendix A.

jQuery Deferreds

We chose to focus on jQuery deferreds because jQuery is ubiquitous and because two important and familiar aspects of jQuery ($.ajax and animations) already have deferred support built in.

However, jQuery deferreds are certainly not the last word on the subject. As you will see, they differ markedly in one important respect from the many (at least 35) other deferred packages for JavaScript: jQuery deferreds do not currently follow the excellent Promises/A+ specification (see Promises/A+).

This book was written for the 1.10.2 or 2.0.3 versions of jQuery. Because the jQuery deferred API has changed several times, it is important to know where you stand, as we’ll see in Changes in the jQuery Deferred API. Server side, we’re using version 1.9.1 of the jQuery-deferred node module. The node module and much of the jQuery deferred code was written by Julian Aubourg.

Our JavaScript Coding Style, or Lack Thereof

JavaScript is not a “there’s only one way to do it” language. As a result, almost every line of code in the book could have been written differently. To keep the focus on deferreds, we’ve chosen to write code in the simplest/clearest possible way. It will be up to you to slightly change our examples to fit whatever coding style or framework you’re using to, for example, create JavaScript objects (via new, using self-calling anonymous functions, global variables, etc.), loop (for loop, $.map, [].forEach etc.), write variable declarations, log via console.log, and so on. Also, in the name of keeping the focus on deferreds, we often ignore (or almost ignore) error processing.

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, email addresses, filenames, and file extensions.

Constant width

Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.

Constant width bold

Shows commands or other text that should be typed literally by the user.

Constant width italic

Shows text that should be replaced with user-supplied values or by values determined by context.

Note

This icon signifies a general note.

Warning

This icon indicates a warning or caution.

Using Code Examples

Supplemental material (code examples, exercises, etc.) is available for download at https://github.com/jquery-deferreds/code.

This book is here to help you get your job done. In general, if example code is offered with this book, you may use it in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. Attribution usually includes the title, author, publisher, and ISBN. For example: “Learning jQuery Deferreds, by Terry Jones and Nicholas H. Tollervey (O’Reilly). Copyright 2014 Terry Jones and Nicholas H. Tollervey, 978-1-4493-6939-2.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [e-mail].

Safari® Books Online

Note

Safari Books Online is an on-demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business.

Technology professionals, software developers, web designers, and business and creative professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training.

Safari Books Online offers a range of product mixes and pricing programs for organizations, government agencies, and individuals. Subscribers have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers including O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology, and dozens more. For more information about Safari Books Online, please visit us online.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

O’Reilly Media, Inc.

1005 Gravenstein Highway North

Sebastopol, CA 95472

800-998-9938 (in the United States or Canada)

707-829-0515 (international or local)

707-829-0104 (fax).

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at http://oreil.ly/learn-jquery-deferreds.

To comment or ask technical questions about this book, send email to [e-mail].

For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

Acknowledgments

Thanks to the Python Twisted community, who have helped with our ongoing deferred education, and whose thinking has enormously influenced the design of deferreds in other languages.

Thanks to Fluidinfo for the various open source (Twisted) deferred code it has published, and for the opportunity to work with and learn about deferreds in depth.

Thanks to Justin Wohlstadter of Wayfinder for allowing us to adapt some Coffeescript examples one of us wrote for him.

Thanks to the jQuery developers and especially to Julian Aubourg for adding deferreds to jQuery and for extracting that code to produce the jQuery-deferred node module.

Thanks to Francesco Agati, Michael Chermside, Jonathan Dobson, Tim Golden, Peter Inglesby, Robert Rees, David Semeria, and Justin Wohlstadter for their careful and useful reviews.

Thanks to the professional and efficient editing and production team at O’Reilly: Meghan Blanchette, Kristen Brown, Charles Roumeliotis, and Simon St. Laurent.

Terry would like to thank Ana, Sofia, Lucas, Findus, and the Flying Spaghetti Monster.

Nicholas would like to thank Mary, Penelope, Sam, and William for their continued support and leg-pulling.