This course has been updated! We now recommend you take the API Design in Node.js, v4 course.

Check out a free preview of the full API Design in Node.js (using Express & Mongo) course:
The "Creating Promises" Lesson is part of the full, API Design in Node.js (using Express & Mongo) course featured in this preview video. Here's what you'd learn in this lesson:

Before moving on, Scott spends a few minutes explaining the basics of promises. He starts with a simple example showing how to create a promise with the native JavaScript API.

Get Unlimited Access Now

Transcript from the "Creating Promises" Lesson

>> [MUSIC]

>> Speaker 1: I could have written a lot of notes on promises, but I think this is just one of those things where you just have to show people. If you don't, that's just the way I learn. I've read on it, I have people, I've read tutorials and stuff. And it was great, but I really didn't understand it until I was like all right let me just start working with this stuff.

[00:00:17] So that's what we're going to do. We're just going to work through som examples of promises for a couple minutes until everyone feels like they're up to speed on them. So we're just going to make a new file. And you can follow along if you want or you can just look.

[00:00:30] We'll just call it promises.js. Luckily for us, the native promise is built into node, at least the version I'm on. So we'll just use that but there are other third party libraries out there that are pretty cool. So the thing about promises are, or the thing that they are trying to solve, say that we have a function called action and this is a, this is a very, very naive example but this is gonna show you what they do.

[00:00:59] And actually takes a call back. And then on some time in the future, let's say five seconds, it's going to call that call back with like some art. And then we can just call action. Passing the call back.
>> Speaker 1: All right, so if I run this, I should see, hey oops.

[00:01:30] Get rid of that. I should see hey in five seconds, right. So if I run node promises.js, in five seconds.
>> Speaker 1: Hey, right. So we had to use the callback for that. That's nothing new. That's how JavaScript works. It uses callbacks versus a vending system. Promises pretty much give us the same thing without have to use the callback.

[00:01:58] Instead of function control, we take back control. And we're able to say now we want to be notified about this or notify me when this does come back. So we jut get more control. And it's better for when you have nested things. So if this call back took another call back.

[00:02:12] And that call back to another call back. Eventually you'll have something that looks like a upside down pyramid, those goes like this. And then they'll come back out like this. All these call backs and call backs and call backs and call backs. Then you start running out of names for your variables and then you got all these closers and you're like, wait.

[00:02:28] Which error am I referencing? You don't even know anymore. So promises were made because of that. There are other alternatives to promises that are coming out. Generators, we have a sync functions, which are part of the ES7 spec, which are really awesome. There's a lot of stuff coming out, but promises has been here for a while and they finally made it native in our environments.

[00:02:48] So what we're going to do is we're going to refractor, I guess I'll go back, we'll refractor this example using a promise instead of a callback. So the first thing we'll do, we'll just get rid of the callback argument. We'll get rid of the call to the callback here.

[00:03:03] And then what we'll do is make a new promise. So, a promise is all it is, is just an object that has methods on it. And these methods notify us about what's happening during this [INAUDIBLE] operation. These methods will either let us know that the value that we're interested in has resolved or it errored along the way.

[00:03:26] That's gonna make more sense as we right this. So a promise is just an object with notification methods on it, that's it.
>> Speaker 1: So to get started making a new promise with new promise library.
>> Speaker 1: All we have to do is have a function that returns a new promise using the promise constructor.

[00:03:48] So they say return a new promise. Then this promise actually takes a call back. Every single thing that we want to be wrapped inside this promise we just need to make sure we placing that call back. So that's step one. If you wanted to switch your function over, have your function return a new promise and have the body of your function be inside that promises callback.

[00:04:11] Step two is to use the built in methods that I talked about, resolve and reject. So again, this is how we're gonna let the promise object knows what values we;re interested in, when the operation has been done. So for instance, if I call resolve after five seconds has passed, I'll be able to get access to the data that I told the promise I want.

[00:04:35] If I call reject, what's going to happen is, the promise is going to tell me that an error happened. I'll show you what that means. So inside this setTimeout, if I just say resolve('hey', same thing we had before. To show you what that's going to look like, now what I am going to do is to refactor that function out here.

[00:04:58] All I would do is I would get rid of this callback function.
>> Speaker 1: And now, what is action returning? It's returning your promise, right? So it's not doing what it did before. It doesn't take a callback. It's actually returning your promise. It takes no arguments. So what I could do is, because it returns a promise, I get access to a few methods I could use .then.

[00:05:23] So that's what you've been seeing this whole time. When you see .then that's because the function's returning a promise. And most libraries use this syntax because there's a specification out there called the A+ promise specification that specifies how promises should be built, and they should have these methods that do certain things.

[00:05:42] You got a question Micheal?
>> Speaker 2: Yeah, just wondering generally, is the promise a functional programming concept or is it something that was invented for JavaScript?
>> Speaker 1: It was definitely something that was invented for JavaScript for single threaded environments, specifically in JavaScript but I wouldn't say it's a functional thing.

>> Speaker 1: There are, if you wanna get hard core functional, there are better alternatives out there like generators or stuff like that. But, you-
>> Speaker 2: Do we have observables, Chris?
>> Speaker 1: Yeah, observables, of course, yeah.
>> Speaker 2: Like Jaffer?
>> Speaker 1: How could I forget about that? Yeah, so I wouldn't say, it's definitely something made for JavaScript and maybe other languages have adopted it because it works for single threaded environments.

>> Speaker 1: So we can call .then which also takes a call back and this call back, this is gonna take an argument. I'll just call it word. By the name of the argument you already know what it is. So, what's happening here, is let's just walk through it. I am calling action.

[00:06:47] Which is going to return this new promise, which takes a callback. And is going to start this setTimeout here. After five seconds, we're going to resolve hey. So whatever I pass into resolve, after five seconds, I have access to it inside this then right here. So whatever is an argument inside this resolve is now accessible right here.

[00:07:09] So if I cancel that log where, and you'll see the same thing will happen. It's hanging, it's hanging, I should probably change it for five seconds. This is too long. Then hit.
>> Speaker 1: So, resolve allows us to ask our promise about something. So, saying .then is like okay, so I'm gonna call action and then when it's ready give me the data that I'm interested in.

[00:07:42] So I can do what I want. So, because of that now we can store this in the variable, right? We can say var promise,
>> Speaker 1: = action. And then some time in the future, somewhere else in our code we can be like okay, now can you just give me what I'm interested in?

[00:08:02] All right? That's the sweet thing about promises. So we can do that. The other thing is.
>> Speaker 1: Is the reject. So let's say that, we don't wanna resolve something, we're just gonna reject. We'll just say, reject. I should just say new Error.
>> Speaker 1: So the way this is gonna work is, so that then is gonna give us the result property of the resolve data that we want.

[00:08:39] Depending on the library that you're using, this next method is different, but for the native promise one it's .catch. So if we do .catch, we get access to error that might have happened. So the way this works is either .then is called or .catch, but not both. It's gonna be either/or.

[00:09:00] So I can do. The way you can do it is you would do .then.
>> Speaker 1: And then you also do .catch. Because both these methods return the promise itself. So if we can just chain them. So what's gonna happen is okay, I want the word, I want a council.log, a word, this may or may not happen we don't know and then if we have an error I want to console.log the error.

[00:09:30] This may or may not happen I'm not sure it's depending on what's happening up here. On line four, I'm rejecting it, so we know for sure that .catch is gonna happen, so let's just run it. So, after five seconds, we get the error no. That's because .catch. That's what's logging right here.

>> Speaker 1: And I'm just gonna change that. That's just too long. Let's just do one second.
>> Speaker 1: All right, .catch is finding an error.