DEV Community: Vincas Stonys

10 Tips to Succeed as a Junior Developer

Vincas Stonys — Tue, 07 Feb 2023 10:12:39 +0000

Being a junior developer is hard. At the start of my career, I used to feel overwhelmed, like I didn't know what I was doing. And that it was only a matter of time until I got exposed as the imposter that I was.

While I was at school and university, I seemed to have it all figured out - as long as you go to classes and maybe study a little, you're good. But when you're on your first day at work - what the hell do you do?

There were all these people I'd never met before (everyone was so serious), following some processes I didn't know (scrum-what?) And the codebase - larger and scarier than I've ever seen. Not to mention written in programming languages and frameworks I've never heard of (does anyone code in Groovy or use Ext.js anyway?)

I wish there was someone to reassure me or some sort of guidelines I could follow to not only survive but succeed. Well then...

After having been a professional software developer for over 7 years now, here's what I wish I knew at the beginning of my career as a junior developer.

1) First, Relax

When you're at your first job as a junior developer it's easy to get the impression you're expected to deliver results (and quickly). At least that's how it was for me - people around me were stressed, constantly talking about some deadline they have.

Don't get caught up in it. You as a junior developer are there to learn.

// Detect dark theme var iframe = document.getElementById('tweet-1571400877029605376-637'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1571400877029605376&theme=dark" }

Nobody expects you to deliver. For the company - you're an investment. And to be a good investment - you need to grow (no... I meant your skills 🤦‍♂️).

Take your time with whatever you're doing, learn as much as you can, ask questions and try to enjoy the process.

2) Solve Problems Yourself

I remember when I discovered GitHub I wanted to use a 3rd party library for any problem I had. After all, why write the code yourself, if someone else already has?

Wrong. Your early career is a time for investments. You should try to solve every problem yourself even if it isn't optimal.

Over time you'll build up a database of go-to solutions in your head. And for the more complex problems, you'll know what to look for in a 3rd party solution - because you're familiar with the problem and know what a good solution should look like.

Again, your job as a junior developer is to learn first, and you learn nothing if you never try solving problems yourself.

3) Ask For Help Early

As a junior developer, you're bound to get stuck eventually (a lot, actually). This is where many junior developers get into trouble. They think they mustn't bother anyone with their stupid issues and instead pretend they're fine.

That's a huge red flag 🚩.

Always ask for help early. As a rule of thumb, if you're stuck, feel free to spend 15-30 minutes trying to figure it out yourself, but then please ask for help.

There's nothing worse than junior developers who're struggling but are pretending they're fine.

4) Ask For Help Correctly

As a junior developer, I was scared to ask for help because I thought the senior devs will be annoyed with my questions. And frankly, they probably were. But there is a way to make the experience pleasant for both you and the senior devs.

Here is what worked well for me 👇

Batch your questions.

Don't bother the senior dev every time you run into a problem. Write your question down and work on something else for a while. Once you have 3 or more questions (or some reasonable time has passed), go and ask them for help.

Do your part

Try to solve the problem first, then look for a solution online (e.g. documentation) and when you eventually ask for help - explain what you've tried. It's very frustrating when junior devs run into a problem, try nothing to solve it, then expect you to solve the problem for them.

Show willingness to learn

Never ask for the answer. Show them that you want to solve the problem yourself, and ask for a roadmap instead. You may ask for steps to find the solution, but if you're just asking for their solution, you're learning nothing (see tip #2).

5) Practice Humility

Senior developers know better (even if they don't). Don't be a rebel. Understand that you most likely know less than someone who's been doing this thing for years, and follow their instructions exactly.

Yes, there are stupid senior engineers. And yes, there are people who're just mean. Accept their criticism, learn what you can from them, and ignore the rest. Don't get discouraged by criticism.

These realizations have helped me tremendously in dealing with imposter syndrome and negative feedback:

Your code is not you.
Nobody really knows what they're doing.

Your time to shine will come - there will be opportunities for you to take on responsibility and show your creativity. When that time comes - overdeliver.

6) Take Ownership and Responsibility

This is the best way to shake off the "junior" label. From the start, I was happy to help other junior developers, which in the eyes of others has made me the most "senior" of the lot (even though we started at the same time with no prior experience).

Over time, I've learned some cool new tech by myself, which got popular (TypeScript), so then even senior devs went to me for help (huge confidence boost). In 2 of the companies I've worked at I was known as "The TypeScript Guy". Creating a niche for yourself is an excellent way to level up your career.

Voice your opinions, share your learnings, and when the opportunity for you to step up and show initiative comes - take it.

Here's a tip from me - write end-to-end tests. Nobody likes setting them up, nobody likes writing them, and nobody likes to be responsible for them. That's the perfect opportunity for a junior dev to show initiative 😉.

7) Build Side Projects

Most good developers I know build stuff in their own time. And I know many bad ones that don't. Building side projects is the best way to fast-track your career.

Let me put it this way - when you go to an interview, the interviewer is looking for proof that you're good, that you can get shit done. When you can point him to a real-world app you've built and deployed by yourself - you have undeniable proof that you can build and release apps.

I improved the most as a developer when I was building my side project mediabits.io. Also, it's been invaluable for my career - it has quite literally doubled my salary.

Instead of being a mere coding monkey, you become someone who builds products.

Ideally, the stuff you build should be something you need yourself and something you've built on your own (don't just follow a tutorial). Here are some ideas 👇

// Detect dark theme var iframe = document.getElementById('tweet-1558158514618507268-58'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1558158514618507268&theme=dark" }

8) Focus on Fundamentals

Once you start building side-projects it's easy to get caught up trying to learn all the new technologies. This is overwhelming.

Make it your goal to deliver a working app, instead of learning the latest-greatest shiny new framework. Just pick a solid technology that's been around for a while and use that. New technologies come and go, but fundamentals stay.

Guess what, most new tech is just a flavor of the same old thing with some sprinkles on top. It's a lot better to spend time mastering JavaScript instead of learning about the nitty-gritty details of react-router.

Don't make it harder than it needs to be. You're inevitably going to learn a lot anyway.

9) Learn in Public

Not writing a blog or creating YouTube videos is the biggest regret I have from my early career. Even as I'm writing this blog, I've already forgotten a lot of the struggles I've had as a beginner.

Two things are well-known:

We learn best when we teach what we learn.
We learn best not from experts, but from someone who's only one step ahead.

Somebody else will find your content invaluable, and as a bonus, you'll be building an audience that you can monetize later to earn some side income.

At the moment, hashnode.dev and dev.to are the easiest way to start blogging for developers.

10) Don’t Stay In Your First Job for Too Long

This one is a bit controversial and you're free to ignore it, but it's something I regret doing early in my career.

I think it's best to change your first job after 1-2 years in the company (unless you landed a job at Google in which case, ignore what I tell you). Here's why:

Your opportunities for learning will be mostly exhausted.
You'll forever be junior in the eyes of the devs you first worked with.
You were underpaid when you started, and you will stay that way until you get a new job.

Money should not be the reason to leave your first job, but just keep in mind that salary grows relative to your current salary (usually around 5-10%). A market-level salary for a developer with 2-3 years of exp is at least 2x higher than an entry-level salary (quick math 🤔 ~50% increase for every year).

If you feel like you're becoming stagnant, don't let the fear or "loyalty" stop you from getting another job. Your company is not your family, as much as they wish it were true.

Conclusion

Early career as a junior developer is a scary period, but it gets very rewarding later on. I'm glad I had a few friends doing the same thing and struggling with the same feelings. I can't imagine how lonely it would've felt otherwise.

If you don't, I want you to at least have the guidelines I wish I had when I was just starting out. It all comes down to:

Learn as much as you can;
Share what you learn;
Build a solid foundation both in terms of skills and career.

Introduce yourself in the comments and let me know what you're struggling with. Feel free to connect with me on Twitter, where I share regular tips for junior developers building their first web app with React.

This is a repost from my blog at codefrontend.com, come say hi.

Learn to Use React Portals in the Real World

Vincas Stonys — Fri, 29 Jul 2022 06:55:05 +0000

Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component. - React Docs

In simple terms - portals allow you to render the component’s content into an element that’s outside of where the component’s content is rendered normally.

In the real world, they allow us to implement tooltips, dropdowns, modals, and overlays that are not affected by positioning and overflow rules of other elements.

In this post I’ll show:

how portals work through an example;
an example of a tooltip with a problem that portals may help solve;
an example of such a tooltip implemented using portals.

ℹ If you’re a beginner, who’s just starting out, don’t worry about portals. You most likely won’t need to use them for a long time. Just keep building your app and if you’re faced with problems implementing modals, toasts, dropdowns, overlays, or tooltips - come back to read this post.

How do React portals work?

Let’s say we have a yellow disc and two boxes - blue and green:

function YellowDisc() {
  return (
    <div
      style={{
        width: 50,
        height: 50,
        background: "yellow",
        borderRadius: "50%"
      }}
    />
  );
}

function BlueBox() {
  return (
    <div
      style={{
        width: 100,
        height: 100,
        background: "blue"
      }}
    />
  );
}

function GreenBox() {
  return (
    <div
      style={{
        width: 100,
        height: 100,
        background: "green"
      }}
    />
  );
}

function App() {
  return (
    <div>
      <YellowDisc />
      <BlueBox />
      <GreenBox />
    </div>
  );
}

Here's the resulting yellow disc, blue box, and green box.
‌

If we wanted to add the yellow disc into the blue box, the simplest way to do that is to have the blue ball render the disc:

function BlueBox() {
  return (
    <div
      style={{
        width: 100,
        height: 100,
        background: "blue"
      }}
    >
      <YellowDisc />
    </div>
  );
}

function App() {
  return (
    <div>
      <BlueBox />
      <GreenBox />
    </div>
  );
}

The yellow disc is in the blue box:

The blue box now owns the yellow disc.

Let’s say that the green box wants to borrow the yellow disc, but the blue box won’t simply let the green box render it. The blue box wants to “own” the disc and stay informed about what happens with it, but it will allow the green box borrow it.

Portals allow the blue box to render the yellow disc into the green box, without the green box owning the yellow disc:

import { useEffect, useState } from "react";
import ReactDOM from "react-dom";

function BlueBox() {
  const [element, setElement] = useState<HTMLElement>();

  useEffect(() => {
    const el = document.getElementById("green-box");
    if (el) {
      setElement(el);
    }
  }, []);

  if (!element) {
    return null;
  }

  return (
    <div
      style={{
        width: 100,
        height: 100,
        background: "blue"
      }}
    >
      {ReactDOM.createPortal(<YellowDisc />, element)}
    </div>
  );
}

function GreenBox() {
  return (
    <div
      id="green-box"
      style={{
        width: 100,
        height: 100,
        background: "green"
      }}
    />
  );
}

The yellow disc is now in the green box:

Here’s what happened:

I gave the green box an id attribute so that I could query the DOM element for the portal to render into.
The blue box uses the portal to render the yellow disk inside the green box.
I used the state to keep track of the reference to the green box and useEffect to find the element after both boxes have been rendered. If I tried to find the green box by id outside of useEffect, then I might not find it. Depending on the nesting and element order, the green box might not be rendered yet. However, in the real world, we usually render into document.body which always exists and we can query it directly without the useEffect.

React event propagation using portals

Well, rendering the element is not something special. In fact, you may achieve the same result without using portals, by using refs.

However, portals give us one advantage - they allow the React events to bubble up the React component tree to their parent React elements.

This is what allows the blue box to keep tabs on the events from the yellow disc, even though it’s rendered inside of the green box.

In fact, to observe this behavior, add onClick={() => console.log("blue clicked!")} to the blue box div and onClick={() => console.log("green clicked!")} to the green box div.

You will notice that the click event on the yellow disc bubbles up and triggers a click event handler on the blue box. But it doesn’t trigger it on the green box. That’s what I mean when I say that the blue box owns the yellow disc.

See it in action here:

‌
If you inspect the DOM now, you will see that the green box now contains the disc even if the blue box owns it:

How come the blue box receives the events and not the green box?

There is no magic here. This is simply because React uses its own event system which works in parallel with the DOM event system. React events bubble up the React component tree, and DOM events bubble up the DOM tree.

$ What problems do portals solve?

At this point, you may understand how portals work, but how do you know when to use them?

You won’t need to use portals often. If you’re a beginner, you most likely won’t need to use them at all for a long time. Even in the above example, if we just let the green box render the circle, we’d have no problems. However, there are some cases where portals can be life-savers.

Tooltips in the real world

Let’s say you’re building a tooltip:

import React, { useState } from "react";

interface Props {
  text: string;
  children: React.ReactNode;
}

function Tooltip({ text, children }: Props) {
  const [isVisible, setVisible] = useState(false);

  const handleMouseOver = () => setVisible(true);
  const handleMouseOut = () => setVisible(false);

  return (
    <div
      style={{ position: "relative" }}
      onMouseOver={handleMouseOver}
      onMouseOut={handleMouseOut}
    >
      {children}
      {isVisible && (
        <div
          style={{
            top: "100%",
            left: 0,
            position: "absolute",
            paddingTop: 5,
            zIndex: 10
          }}
        >
          <div
            style={{
              background: "black",
              color: "white"
            }}
          >
            {text}
          </div>
        </div>
      )}
    </div>
  );
}

function App() {
  return (
    <div>
      <Tooltip text="Clicky clicky">
        <button>Button</button>
      </Tooltip>
    </div>
  );
}

export default App;

‌
If you hover the button, you get a tooltip below that says Clicky clicky. It’s basic but works fine. That’s how I would start out building a simple tooltip.

‌
However, what if at some point we need to use it in a container, that hides the overflowing content? To see the problem, add style={{ height: 35, overflow: "hidden" }} to the div in App component. Our tooltip gets cut off.

That’s a real-world issue that portals can help us solve. Also, you may have noticed that the tooltip component wraps its children with a relatively positioned div. This can make it difficult to use such tooltips in practice because you’d need to put extra effort to ensure they don’t mess up the layout.

See it in action:

How do portals help to implement tooltips?

The general way to solve the clipping issue is:

On hover, determine the anchor point for the tooltip on-screen, normally using getBoundingClientRect or offsetLeft and offsetTop properties on the element.
Render the tooltip as close to <body> element as possible.
Use fixed position on the tooltip and position it near the anchor element using the anchor point coordinates we got previously.
Whoa, this quickly got a lot more complex. And because the tooltip is now a free-floating element on the screen, we may need to handle edge cases, such as:

The tooltip position may need to update when we scroll;
The tooltip should re-position itself near the screen edges if it goes out of the screen.
The tooltip should work well with other free-floating elements such as modals.

None of these issues are trivial to solve, that’s why we have libraries whose sole purpose is to manage the positioning of floating elements, like react-laag and popperjs. In fact, you’re probably better off not building a custom tooltip solution of your own. Been there, done that…

Here’s what such a tooltip implementation may look like in the real world:
‌

import React, { useState } from "react";
import ReactDOM from "react-dom";

interface Props {
  text: string;
  children: React.ReactNode;
}

function Tooltip({ text, children }: Props) {
  // Position of the bottom edge of the anchor element.
  // Doubles as isVisible state: null means hidden
  const [position, setPosition] = useState<{
    x: number;
    y: number;
  } | null>(null);

  const handleMouseOver = (
    e: React.MouseEvent<HTMLElement>
  ) => {
    // Place the tooltip near the anchor's bottom edge on the screen
    const bounds = e.currentTarget.getBoundingClientRect();
    setPosition({
      x: bounds.x,
      y: bounds.y + bounds.height
    });
  };

  const handleMouseOut = () => setPosition(null);

  const anchorProps = {
    onMouseOver: handleMouseOver,
    onMouseOut: handleMouseOut
  };

  // Clones the child element to remove the div wrapper around it.
  // Child node must accept or forward mouse events.
  // We can't set even handlers on text, so we wrap it with <span>.
  const anchor = React.isValidElement(children) ? (
    React.cloneElement(children, anchorProps)
  ) : (
    <span {...anchorProps}>{children}</span>
  );

  // We use react portal to render the tooltip into document.body.
  // To place it near the button, we use the position from the event.
  // The position is "fixed" so it won't be affected by overflow rules.
  return (
    <>
      {anchor}
      {position &&
        ReactDOM.createPortal(
          <div
            style={{
              top: position.y,
              left: position.x,
              position: "fixed",
              paddingTop: 5,
              zIndex: 10
            }}
          >
            <div
              style={{
                background: "black",
                color: "white"
              }}
            >
              {text}
            </div>
          </div>,
          document.body
        )}
    </>
  );
}

‌
Here’s what I did:

I’ve replaced isVisible with the tooltip’s position on the screen. If the position is set, it means the tooltip is visible, otherwise, it’s hidden.
I changed the hover event handler to get the button’s height and position on the screen. Then I use them to place the tooltip at the bottom edge of the button.
I assigned the event handlers to the anchor, by cloning it first. This allows me to remove the div wrapper from the tooltip, so it doesn’t affect the layout in any way. You could leave the wrapper and pass it the event handlers, but I don’t like it when commonly used components, such as tooltips, make me think about how they will affect layouts.
Finally, I used a React portal to render the tooltip into document.body, so that it’s not affected by the parent elements’ layout rules. Then I changed its position to fixed, and set its coordinates on the screen to be at the bottom of the button.

If you test it now, you will see that the tooltip works exactly the same, but it’s not affected by the overflow: hidden that we set on the button’s container div. If you implemented dropdowns, modals, and toasts in a similar fashion, they would also be unaffected by the layout rules.

However, it is important to realize the tradeoffs of this implementation:

The code is now harder to understand.
We need to do more work because we need to sync the tooltip's position with its anchor element. It can be hard:
- If the anchor or the tooltip is animated or change sizes frequently.
- When we scroll the page we should reposition or hide the tooltip.
- If the tooltip is near the edge of the screen, we may want to adjust its placement to stay inside the screen.

Here’s the final implementation in action:

Conclusion

The problems and solutions, where we may apply React portals, follow a similar pattern:

An element is affected by the parent element’s positioning or overflow rules.
Using portals, we render the component in another place, where it’s no more affected by those rules.

Here are some common real-world use cases for portals: tooltips, dropdowns, modals, overlays, and toasts.

Portals often make the implementation more complex and introduce edge cases, so I would only use them if no simpler method is available. Honestly, I don’t see much wrong with the original implementation of the tooltip in my example, and I would start with that.

In the real world, when faced with the above use cases, it’s probably simpler to use a reliable UI component for modal, dropdown, or tooltip instead of building your own.

Nevertheless, it’s a worthwhile exercise to try to build your own implementation to get familiar with the problems. Solving them will make you a better developer, no matter what skill level you’re at.

Though it’s probably best if you do that in your own sandbox project...

This article is republished from my programming blog. Follow me on Twitter to learn how to build real-world web applications using React.

If you want to master Promises, the best way to do that is by implementing them from scratch. I explain how in this article: Asynchronous Javascript - Learn Promises From Scratch.

Asynchronous Javascript - Learn Promises From Scratch

Vincas Stonys — Tue, 19 Jul 2022 07:21:52 +0000

JavaScript is a synchronous language at its core, meaning that only a single line of code runs at any time. That means that time spent executing some part of the code delays the execution of other code. This includes painting things on the screen, handling user input, or doing math.

When building frontend applications we often need to deal with asynchronous operations, such as user input or HTTP requests. In the browser they may run on a separate thread, so how do we deal with this asynchronicity in a synchronous language like JavaScript?

Understanding this part of JavaScript is essential to building real-world applications. And that's what we're going to take a look at in this article.

We'll learn about:

Callbacks - how callbacks can be used to deal with asynchronous code, and how they lead to callback hell.
Promises - how to use promises to make callbacks manageable. We'll also write our own implementation of the basic promise API to understand how they work.
Async/await - how to use the new await/async API to make promises even easier to work with.

📚 Synchronicity reduces the cognitive load when writing JavaScript code since you don't need to concern yourself with multiple threads accessing and updating the same data. However, sometimes it's necessary to break out of the single thread for computationally expensive operations. To understand how to execute your own code asynchronously learn about Web Workers in the browser and Worker Threads in Node.js.

Callback functions

It would be impractical if making an HTTP request blocked the code until we got a response. Even if it came back in 100 milliseconds, that's still ages in computer time. Luckily, JavaScript allows us to provide callback functions to asynchronous APIs.

📌 A callback is a function that's passed as an argument to another function to be called by that function at a later time. Often, to indicate that some action has been finished.

In fact, you probably use callbacks without even thinking about it.

For instance, user events are asynchronous in nature, and you register callback functions that handle those events, like this:

const btn = document.querySelector("button");

btn.addEventListener("click", () => {
  // Called when the user clicks the button
});

The example code registers a callback to be executed when the user clicks the button. In the meantime, the program continues running other code and doesn't keep waiting for user input.

📚 It's useful to know that the event handler code might not start executing immediately after the user clicks the button. Learn about the event loop to understand why.

Problems with callbacks

Callbacks are the most basic way to deal with asynchronous code. They can actually get you quite far, but at some point, they will start to feel limiting:

Callbacks create code-flow indirection because the function result is not returned but instead passed into a callback. This makes code harder to follow.
Handling errors in callbacks is a matter of convention rather than API, which creates inconsistencies and cognitive load.
Nested callbacks may lead to 'callback hell'. That's when callbacks are nested within other callbacks, several levels deep, often making the code hard to read and understand.

Consider this example of asynchronous JavaScript code using callbacks:

function makeTea(done) {
  const teapot = getTeapot();
  const kettle = getKettle();

  kettle.fill();

  kettle.boil((error, water) => {
    if (error) {
      done(new Error('Kettle broke 😭'));
    } else { 
      kettle.pour(water, teapot);
      waitMinutes(5, () => {
        const cup = getCup();
        const tea = teapot.pourInto(cup);
        waitMinutes(5, () => {
            done(tea)
        });
      });
    }
  });

  // Executed right after putting on a kettle:
  addTeaLeaves(teapot);
}

It's only 3 levels deep, but the nesting is already becoming excessive.

The code isn't overly complicated, but it's already unpleasant to read, because of the nesting. Now consider that in real-world applications we need to deal with asynchronous code quite a bit, and you will realize why it soon feels like being in hell.

😅 This pyramid shape that's formed by nesting callbacks is affectionately called 'the pyramid of doom', because of the indentation that looks like a sideways pyramid.

Promises

A Promise is a JavaScript object representing a value that will be available after an asynchronous operation completes. Promises can be returned synchronously like regular values, but the value may be supplied at a later point.

It also provides an API to access the "promised" value by binding callbacks for different promise states.

const promise = new Promise((resolve, reject) => {
  // This function runs an asyncronous operation that will call:
  // resolve(value) - if it succeeded, with the resolved value;
  // reject(reason) - if it failed, with the error set as value;
});

Promise states

Depending on the outcome of the asynchronous operation, promises can be in three states:

pending: set initially, while the asynchronous operation is in progress;
fulfilled: the asynchronous operation has finished successfully;
rejected: the operation has failed.

new Promise((resolve, reject) => {
  setTimeout(() => resolve("done!"), 1000);
});

The promise is pending for 1 second, then it's fulfilled with the string value "done!".

When a promise enters either fulfilled or rejected state it is said to be settled. The promise is formally said to be resolved if it is settled or resolved with a promise so that further resolving or rejecting it has no effect. However, colloquially it is often meant that the promise is fulfilled.

📚 If you're interested in formal definitions, check out the ECMAScript specification and Promise/A+ specification.

Working with promises

A promise acts as a synchronous value - it can be passed as an argument or returned by functions as usual. However, to read its eventual value you need to "subscribe" to it. To allow that, promises have public methods:

promise.then - is a primary method that accepts callbacks to run on success and failure;
promise.catch - is a method to register callbacks for when the promise is rejected;
promise.finally - is a method to register callbacks to be executed after the promise is fulfilled or rejected.

This is how it looks in practice:

const promise = new Promise((resolve, reject) => {
  // run async code
})

promise.then(
  (value) => { /* handle a fulfilled promise result */ },
  (reason) => { /* handle a rejected promise result */ }
)

promise.catch(
  (reason) => { /* handle a rejected promise result */ },
)

promise.finally(
  () => { /* handle a any result */ }
)

As long as the promise is pending, the callbacks will not be executed. Once the promise has been resolved, it will always hold the result value. In case a handler is attached to a resolved handler, the handler simply runs right away and receives the promise value.

Promise chains

A very useful feature of promises is that .then, .catch and .finally calls return promises, which means that we can attach multiple handlers by simply stringing the calls together:

const promise = new Promise((resolve, reject) => {
  // handle async code
});

promise
  .then(handleFulfilledA, handleRejectedA)
  .then(handleFulfilledB)
  .then(handleFulfilledC, handleRejectedC)
  .catch(handleRejectedAny)
  .finally(handleResolved)

Each handleFulfilled handler will receive the result returned of calling the previous handler. In case an error is thrown in either hander, the promise will enter the rejected state and any further handlers called will be handleRejected and .catch.

Note: a common beginner mistake is to attach multiple handlers on the original promise when trying to chain, it won't work, but it may be a useful feature in some cases:

const promise = new Promise((resolve, reject) => {
  resolve(1);
});

promise.then((result) => {
  console.log(result); // 1
  return result + 1;
});

promise.then((result) => {
  console.log(result); // 1
  return result + 1;
});

promise.then((result) => {
  console.log(result); // 1
  return result + 1;
});

Every .then call returns a new promise with the incremented value, but the handlers are attached to the original promise which was resolved with value 1.

Remember our function that made tea? Let's see how it looks when rewritten to use promises:

function makeTea() {
  const teapot = getTeapot();
  const kettle = getKettle();

  kettle.fill();

  const teaPromise = kettle
    .boil() // Assuming boil function returns a promise
    .catch((error) => {
      // Only handles kettle issues
      // Rethrows the error keep the rejected the promise state
      throw new Error("Kettle broke 😭");
    })
    .then(water => {
      kettle.pour(water, teapot);
      return waitMinutes(5); // Assuming waitMinutes returns a promise
    }).then(() => {
      const cup = getCup();
      const tea = teapot.pourInto(cup);
      return waitMinutes(5)
        .then(() => tea); // Our promise chain must return the cup of tea
    });

  addTeaLeaves(teapot);

  return teaPromise;
}

Frankly, it's still not that pretty, but there's less nesting and it doesn't keep going deeper, because the promises are being chained onto the original promise for the most part.

Static methods

Promises have a couple of static methods to help make working with them easier. The most important ones are:

Promise.resolve(value) - creates a resolved promise with the provided value;
Promise.reject(reason) - creates a rejected promise with the provided value;
Promise.race([...promises]) - creates a promise with the value of the first fulfilled or rejected promise in the provided array;
Promise.any([...promises]) - creates a promise with the value of the first fulfilled promise in the array, if none are, then the promise is rejected.
Promise.all([...promises]) - creates a promise that resolves to an array of the fulfilled promise values. If any promise in the array rejects, the returned promise is rejected.
Promise.allSettled([...promises]) - creates a promise that's resolved when all of the promises in the array have been resolved (fulfilled or rejected). As a value, it receives an array of objects, that contain status and value or reason properties, representing the outcomes of each promise.

To really understand how promises work, I recommend you to understand how they can be implemented. I guarantee that most frontend developers won't be able to implement promises, simply because they don't understand them.

Well, now you will.

Implementing the Basic Promise API

Promises are the foundation for doing asynchronous work in JavaScript, so it's imperative to understand them completely. When I was just beginning with JavaScript, some aspects of promises seemed magical. However, that only pointed to my incomplete understanding.

The best way to dispel any magic is to build something from scratch. That way, we can understand how things work under the hood. Trust me when I say this - if you learn how to implement the promise API from scratch you will understand them better than most software developers.

For our purposes, I'll call our promise Futurable, with otherwise the same API.

1) Tests

Let's first start by writing some tests, so that we're sure we cover the complete API. We'll not spend time on this part, so if you're following along just copy-paste the code. We want to test at least these cases:

The promise can be resolved with a value;
The promise can be rejected by calling reject() or throwing an error;
The promise can be rejected or resolved with another promise;
Resolved and rejected promises can't be further rejected or resolved;
Multiple then(), catch(), finally() handlers can be chained;
finally() must be invoked on either rejection or fulfillment.
Promise operations should always be asynchronous;

Here's the test suite I will be using:

import Futurable from "./Futurable";

describe("Futurable <constructor>", () => {
  it(`returns a promise-like object,
      that resolves it's chain after invoking <resolve>`, (done) => {
    new Futurable<string>((resolve) => {
      setTimeout(() => {
        resolve("testing");
      }, 20);
    }).then((val) => {
      expect(val).toBe("testing");
      done();
    });
  });

  it("is always asynchronous", () => {
    let value = "no";
    new Futurable<string>((resolve) => {
      value = "yes;";
      resolve(value);
    });
    expect(value).toBe("no");
  });

  it("resolves with the returned value", (done) => {
    new Futurable<string>((resolve) => resolve("testing")).then((val) => {
      expect(val).toBe("testing");
      done();
    });
  });

  it("resolves a Futurable before calling <then>", (done) => {
    new Futurable<string>((resolve) =>
      resolve(new Futurable((resolve) => resolve("testing")))
    ).then((val) => {
      expect(val).toBe("testing");
      done();
    });
  });

  it("resolves a Futurable before calling <catch>", (done) => {
    new Futurable<string>((resolve) =>
      resolve(new Futurable((_, reject) => reject("fail")))
    ).catch((reason) => {
      expect(reason).toBe("fail");
      done();
    });
  });

  it("catches errors from <reject>", (done) => {
    const error = new Error("Why u fail?");

    new Futurable((_, reject) => {
      return reject(error);
    }).catch((err: Error) => {
      expect(err).toBe(error);
      done();
    });
  });

  it("catches errors from <throw>", (done) => {
    const error = new Error("Why u fail?");

    new Futurable(() => {
      throw error;
    }).catch((err) => {
      expect(err).toBe(error);
      done();
    });
  });

  it("does not change state anymore after promise is fulfilled", (done) => {
    new Futurable((resolve, reject) => {
      resolve("success");
      reject("fail");
    })
      .catch(() => {
        done.fail(new Error("Should not be called"));
      })
      .then((value) => {
        expect(value).toBe("success");
        done();
      });
  });

  it("does not change state anymore after promise is rejected", (done) => {
    new Futurable((resolve, reject) => {
      reject("fail");
      resolve("success");
    })
      .then(() => {
        done.fail(new Error("Should not be called"));
      })
      .catch((err) => {
        expect(err).toBe("fail");
        done();
      });
  });
});

describe("Futurable chaining", () => {
  it("resolves chained <then>", (done) => {
    new Futurable<number>((resolve) => {
      resolve(0);
    })
      .then((value) => value + 1)
      .then((value) => value + 1)
      .then((value) => value + 1)
      .then((value) => {
        expect(value).toBe(3);
        done();
      });
  });

  it("resolves <then> chain after <catch>", (done) => {
    new Futurable<number>(() => {
      throw new Error("Why u fail?");
    })
      .catch(() => {
        return "testing";
      })
      .then((value) => {
        expect(value).toBe("testing");
        done();
      });
  });

  it("catches errors thrown in <then>", (done) => {
    const error = new Error("Why u fail?");

    new Futurable((resolve) => {
      resolve();
    })
      .then(() => {
        throw error;
      })
      .catch((err) => {
        expect(err).toBe(error);
        done();
      });
  });

  it("catches errors thrown in <catch>", (done) => {
    const error = new Error("Final error");

    new Futurable((_, reject) => {
      reject(new Error("Initial error"));
    })
      .catch(() => {
        throw error;
      })
      .catch((err) => {
        expect(err).toBe(error);
        done();
      });
  });

  it("short-circuits <then> chain on error", (done) => {
    const error = new Error("Why u fail?");

    new Futurable(() => {
      throw error;
    })
      .then(() => {
        done.fail(new Error("Should not be called"));
      })
      .catch((err) => {
        expect(err).toBe(error);
        done();
      });
  });

  it("passes value through undefined <then>", (done) => {
    new Futurable((resolve) => {
      resolve("testing");
    })
      .then()
      .then((value) => {
        expect(value).toBe("testing");
        done();
      });
  });

  it("passes value through undefined <catch>", (done) => {
    const error = new Error("Why u fail?");

    new Futurable((_, reject) => {
      reject(error);
    })
      .catch()
      .catch((err) => {
        expect(err).toBe(error);
        done();
      });
  });
});

describe("Futurable <finally>", () => {
  it("it is called when Futurable is resolved", (done) => {
    new Futurable((resolve) => resolve("success")).finally(() => {
      done();
    });
  });

  it("it is called when Futurable is rejected", (done) => {
    new Futurable((_, reject) => reject("fail")).finally(() => {
      done();
    });
  });

  it("it preserves a resolved promise state", (done) => {
    let finallyCalledTimes = 0;

    new Futurable((resolve) => resolve("success"))
      .finally(() => {
        finallyCalledTimes += 1;
      })
      .then((value) => {
        expect(value).toBe("success");
        expect(finallyCalledTimes).toBe(1);
        done();
      });
  });

  it("it preserves a rejected promise state", (done) => {
    let finallyCalledTimes = 0;

    new Futurable((_, reject) => reject("fail"))
      .finally(() => {
        finallyCalledTimes += 1;
      })
      .catch((reason) => {
        expect(reason).toBe("fail");
        expect(finallyCalledTimes).toBe(1);
        done();
      });
  });
});

👉 If you want to follow along, feel free to create a typescript codesandbox and paste this code. Or fork mine and delete the Futurable.ts file if you want to start fresh. Switch to "Tests" tab to see the results.

2) The interface

Now we move on to the implementation, and the first thing we need to do is to define the public API.

class Futurable<T> {
  constructor(
    executor: (
      resolve: (value: T | Futurable<T>) => void,
      reject: (reason?: any) => void
    ) => void
  ) {
    // TODO: implement
  }

  then = <R1 = T, R2 = never>(
    onFulfilled?: (value: T) => R1 | Futurable<R1>,
    onRejected?: (reason: any) => R2 | Futurable<R2>
  ) => {
    // TODO: implement
  };

  catch = <R = never>(onRejected?: (reason: any) => R | Futurable<R>) => {
    // TODO: implement
  };

  finally = (onFinally: () => void): Futurable<T> => {
    // TODO: implement
  };
}

export default Futurable<T>;

I took the types mostly from the ES6 promise type definitions so that our implementation gets as close to the standard as possible.

Our constructor will take the callback as a parameter and call it passing resolve and reject functions.

Remember how I mentioned that then() accepts callbacks for both fulfillment and rejection? Well, that's what we define here. It's going to be the basis for registering our handlers - catch and finally is only 'sugar', as you will see later.

3) State machine

I've already mentioned how a promise has 3 states: fulfilled, rejected, and pending. This can be expressed as a state machine:

The promise starts off as pending and moves into resolved state or rejected state. After it makes the transition, it can no longer be resolved, rejected, or enter the pending state.

To implement this, first, we need to define the internal state and the result of the promise, let's do that:

enum FuturableState {
  Pending,
  Resolved,
  Rejected
}

class Futurable<T> {
  private state = FuturableState.Pending;
  private result?: any;

  // ...
}

Now we can implement a function that handles these transitions:

const isThenable = (obj: any): obj is Futurable<any> =>
  typeof obj?.then === "function";

class Futurable<T> {
  // ...

  private resolve = (value: T | Futurable<T>) => {
    // TODO: implement
  };

  private reject = (reason?: any) => {
    // TODO: implement
  };

  private setResult = (value: any, state: FuturableState) => {
    if (this.state !== FuturableState.Pending) {
      return;
    }

    if (isThenable(value)) {
      value.then(this.resolve, this.reject);
      return;
    }

    this.state = state;
    this.result = value;
  };
}

The setResult method is now responsible for making a transition and setting the promise result, let's understand what the code does.

We only need to allow transitions from pending state, otherwise, calling setResult will do nothing, so we exit the function by returning.
We check if the value provided was in itself a promise and resolve it instead of transitioning the state. We also defined the resolve and reject internal functions, which we'll implement later.
If the value was not a promise, we transition the state and value.

📌 According to the promise standard, if an object contains a then method, then it should act like a promise, even if it isn't an instance of a Promise class - it's called a thenable. Now that's pretty cool! That means, that we could resolve Futurable with new Promise(...) as a result and it would still work, and vice versa.

4) Resolve / Reject

Now that we have a function that handles our promise's state transitions, we can use it to implement the constructor and resolve/reject functions. It's as simple as calling our setResult function in resolve and reject function and then using them in our constructor:

  constructor(
    executor: (
      resolve: (value: T | Futurable<T>) => void,
      reject: (reason?: any) => void
    ) => void
  ) {
      executor(this.resolve, this.reject);
    } catch (e) {
      this.reject(e);
    }
  }

  // ...

  private resolve = (value: T | Futurable<T>) => {
    this.setResult(value, FuturableState.Resolved);
  };

  private reject = (reason?: any) => {
    this.setResult(reason, FuturableState.Rejected);
  };

You may notice the try-catch block and wonder why we need it in the constructor. That's because calling reject is not the only way to reject a promise, we can also throw an error. Doing that will trigger our catch block, and we handle the error by rejecting the promise.

Now we have the ability to create a new Futurable promise and run the callback. Resolving or rejecting it in the callback will change the internal promise state and set the value:

const resolvedPromise = new Futurable((resolve, reject) => {
  resolve('success!')
})

const rejectedPromise = new Futurable((resolve, reject) => {
  reject('fail...')
})

However, there's one issue...

5) Executing promises asynchronously

Constructing a new promise will immediately execute the callback. This means that our Promises are blocking the code execution, which means they're not actually asynchronous operations.

If you want to see the problem in action, run this code:

let called = false;

new Futurable((resolve) => {
  called = true;
  resolve();
});

console.log(called); // Prints: "true"

The constructor is being run synchronously, asynchronous code would not run the callback immediately.

Let's fix that.

Without going deep into how the event loop works, we should at least know that our code is being run synchronously in these phases:

Executing tasks - your code;
Executing jobs - native ES6 Promise callbacks;
Executing messages - events, callbacks, ajax requests, etc.

If you want a thorough explanation of how the event loop works, watch this excellent presentation:

%[https://www.youtube.com/watch?v=8aGhZQkoFbQ]

What this means in practice is that your code is run synchronously at the highest priority - as long as it's running, it will block the execution of any code that follows. When the code execution phase is over, it will process any jobs and messages that have been received in the meanwhile.

😉 If you want to see what I mean by blocking code, run (true) { console.log('blocking'); console.log('not blocking'); } in your browser console for example. You will never see the message 'not blocking'. Do it at your own peril though, you may not be able to close the tab anymore and may have to kill the browser.

Since we're doing a custom implementation of the promises, we assume that there's no native support for Promises, but we still need to execute the Futurable callbacks asynchronously. To do that we can utilize a well-known hack: setTimeout(callback, 0);

This would delegate the execution of the callback to run immediately after any synchronous code, hence zero milliseconds. Let's write a utility function:

const runAsync = (callback: () => void) => {
  setTimeout(callback, 0);
};

We can now wrap our constructor and execute code with this utility to run them asynchronously as such:

// ...

constructor(
  executor: (
    resolve: (value: T | Futurable<T>) => void,
    reject: (reason?: any) => void
  ) => void
) {
  runAsync(() => {
    // ...
  });
}

private setResult = (value: any, state: FuturableState) => {
  runAsync(() => {
    // ...
  }
};

// ...

If you test the previous example again, you will see that it prints false, which means that the promise callback code isn't run immediately and doesn't block the code execution anymore.

6) Executing handlers

Promises allow us to access their value by attaching then or catch handlers and providing them with callbacks which then receive value asynchronously. Because the callbacks are supposed to be executed one by one sequentially, we can put them in a queue.

type Handler<T> = {
  handleThen: (value: T) => void;
  handleCatch: (reason?: any) => void;
};

export default class Futurable<T> {
  private handlers: Handler<T>[] = [];

  // ...
}

How this is going to work:

Whenever .then or .catch is called, we'll push the callback handler into a queue. There will always be a handler for both, except one of them will simply pass the promise value through as a result, like this (value) => value. This will ensure, that the whole chain of handlers gets executed, but irrelevant handlers are "skipped", e.g. skip all .catch calls in case there was no error.
We will execute all of the handlers when the promise is fulfilled or rejected.
We will execute the resolvers as soon as a handler is pushed into the queue, in case the handler is attached to the promise that has already been resolved. However, we should remember not to execute the handlers until the promise has resolved.
We will remove all handlers as soon as they finished executing.

Let's write the function to execute the handlers first:

private executeResolvers = () => {
  if (this.state === FuturableState.Pending) {
    return;
  }

  this.handlers.forEach((resolver) => {
    if (this.state === FuturableState.Resolved) {
      resolver.handleThen(this.result);
    } else {
      resolver.handleCatch(this.result);
    }
  });

  this.handlers = [];
};

private setResult = (value: any, state: FuturableState) => {
  // ...
  this.executeResolvers();
};

First, we check if the promise has resolved already, if it hasn't we skip it. We only want to execute .then and .catch handlers only on resolved promises.

Then we run all of the handlers for .then or .catch depending on whether the promise is resolved or rejected. Afterward, we clean all of the handlers so that they don't get executed again.

Finally, we need to run the resolvers as soon as we set the result of the promise, which will execute the promise chain.

7) Implementing .then

We can run the handlers, but we still need a way to push the handlers to the queue. That's where .then handler comes in:

then = <R1 = T, R2 = never>(
  onFulfilled?: null | ((value: T) => R1 | Futurable<R1>),
  onRejected?: null | ((reason: any) => R2 | Futurable<R2>)
) => {
  return new Futurable<R1 | R2>((resolve, reject) => {
    this.resolvers.push({
      handleThen: (value) => {
        if (!onFulfilled) {
          resolve(value as any);
        } else {
          try {
            resolve(onFulfilled(value) as R1 | Futurable<R1 | R2>);
          } catch (e) {
            reject(e);
          }
        }
      },
      handleCatch: (reason) => {
        if (!onRejected) {
          reject(reason);
        } else {
          try {
            resolve(onRejected(reason) as R2 | Futurable<R1 | R2>);
          } catch (e) {
            reject(e);
          }
        }
      }
    });
    this.executeResolvers();
  });
};

The code looks daunting, but it is actually pretty simple when broken down.

By specification, .then is supposed to be able to handle both fulfill and reject callbacks, and the types come directly from the ES6 Promise interface. The handlers must always return a promise so that they can be chained, so as a result, we return a new Futurable.

We push .then and .catch handlers, that are basically identical, except one is calling the resolve callback, and the other one - reject.

We resolve the promise with the result returned from the callback. In case the callback is not provided, we simply pass through the original value of the promise, which allows us to chain promises even if we omit either handler, essentially replacing it with (value) => value.

Then we wrap everything in try/catch, because we should be able to reject the promise by throwing an error in the handler, as an alternative to calling reject.

Finally, as mentioned earlier, we need to execute the resolvers after adding pushing the promise into the queue, so that if the promise was already resolved, the new handler would still run.

Let's test:

new Futurable((resolve) => resolve("ok"))
  .then((value) => {
    console.log(value);
    throw new Error("fail");
  })
  .then(null, (error) => console.log(error.message));

If you run this code, you should see both ok and fail, on the screen, which means that our Futurable promise is chainable and can handle both fulfillment and rejection.

8) Implementing .catch and .finally

We already have a fully functional Promise now, but let's add some sugar: .catch and .finally.

From the above test, you can see, that catch is equivalent to then without the onFulfill handler:

catch = <R = never>(onRejected?: (reason: any) => R | Futurable<R>) => {
  return this.then(null, onRejected);
};

And .finally is as simple as executing a callback no matter if the promise was fulfilled or rejected:

finally = (onFinally: () => void): Futurable<T> => {
  return this.then(
    (value) => {
      onFinally();
      return value;
    },
    (reason) => {
      onFinally();
      throw reason;
    }
  );
};

The only caveat is that .finally must not change the promise status, so it passes through whatever the result was - it returns the value if the promise was resolved or rethrows the error in case it was rejected.

You can see the full implementation here:

%[https://codesandbox.io/embed/futurable-codefrontend-com-glt0qq?fontsize=14&hidenavigation=1&theme=dark]

There we have it - the basic premise implementation we built ourselves. As a fun experiment, try to use it interchangeably with the native promise and see if it works. If you wish to refine the implementation further and deepen the understanding of promises, try to implement these static methods:

Promise.resolve
Promise.reject
Promise.race
Promise.any
Promise.all
Promise.allSettled if you really want to go advanced.

Async/await

By now you might have gathered, that promises solve some of the issues of working with asynchronous operations in JavaScript, yet they're not perfect:

They don't completely eliminate the nesting;
Their readability is not great;
While the promise can be returned synchronously, its result can't be accessed synchronously;
Regular language constructs are not straightforward to use (e.g. try/catch block).

Well, recently a more convenient way of handling asynchronous operations was introduced - async/await, and promises are the heart of it.

Async functions

When declaring a function, we can mark it as async, which will allow us to return any value the same as always, but the result would automatically be considered a promise:

async function doAsyncStuff() {
  return 1;
}

const promise = doAsyncStuff()
  .then((result) => console.log(result)) // Prints: 1

As we see in the example, returning a value is equivalent to resolving a promise. Even if there's no value returned, the result will still be a promise, except with undefined as the result. Similarly, throwing an error is equivalent to rejecting the promise:

// Inline functions can also be async
const doAsyncStuff = async () => {
  throw new Error("don't wanna");
}

const promise = doAsyncStuff()
  .catch((error) => console.log(error.message)) // Prints: "don't wanna"

Await

What's cool about async functions, is that inside of them you can use the await keyword to synchronously resolve promises:

async function doAsyncStuff() {
  return 1;
}

const timeoutPromise = new Promise((resolve, reject) => {
  setTimeout(() => resolve("done!"), 1000);
});

async function useAsyncStuff() {
  const asyncStuff = await doAsyncStuff();
  const timeoutResult = await timeoutPromise();
  console.log(asyncStuff, timeoutResult); // Prints: "1 done!"
}

useAsyncStuff();

The await keyword makes the code blocking until the promise is resolved, essentially waiting for the operation to complete until it proceeds with code execution. This allows us to get results from asynchronous functions in much the same way as regular ones.

But that's not it. When you use await the error will be thrown synchronously as well, so the regular try/catch block will work:

async function doAsyncStuff() {
  throw new Error("Ah damn...");
}

async function useAsyncStuff() {
  try {
    await doAsyncStuff();
  } catch(err) {
    console.log(err); // Prints: "Ah damn..."
  }
}

useAsyncStuff();

However, in the end, it's all promises, so async/await can be used with .then, .catch and .finally interchangeably:

async function doAsyncStuff() {
  throw new Error("Ah damn...");
}

async function useAsyncStuff() {
  await doAsyncStuff().catch(() => {
    console.log(err); // Prints: "Ah damn..."
  });
}

useAsyncStuff();

As a final exercise, let's rewrite our tea preparation function using async/await:

async function makeTea() {
  const teapot = getTeapot();
  const kettle = getKettle();

  kettle.fill();

  const hotWaterPromise = kettle.boil().catch(() => {
    throw new Error("Kettle broke 😭");
  });

  // Add tea leaves while we wait for the water to boil, like previously
  const [water] = await Promise.all([
    hotWaterPromise,
    addTeaLeaves(teapot)
  ]);

  kettle.pour(water, teapot);
  await waitMinutes(5);

  const cup = getCup();
  const tea = teapot.pourInto(cup);

  await waitMinutes(5);

  return tea;
}

As you see async/await has eliminated excessive nesting and is generally simpler to read and understand.

Caveat

As you can imagine, async/await solves most of the remaining issues with promises. However, there are some common mistakes that beginners run into.

You can't use await at the root level or regular functions, only in async functions:

function doAsyncStuff() {
  const promise = Promise.resolve("done!");
  const result = await promise; // Syntax error
}

const result = await new Promise((resolve) => resolve("done!")); // Syntax error

Although, some modern JavaScript runtimes (modern browsers, latest node versions) allow async at the root level. As a workaround for older JS runtimes, wrap the call in a self-invoking anonymous async function:

(async () => {
  const result = await new Promise((resolve) => resolve("done!")); // Works
})();

Final thoughts

Modern JavaScript provides ways to work with asynchronous operations conveniently. However, promises are the basis of everything that's async in JavaScript, so it's essential to understand them completely.

I've shown how you would implement promises yourself and hopefully, the process has shown you that there's no magic involved when you break them down.

If it was your first involvement with promises, you might have gotten a bit overwhelmed, but don't worry, with practice, using promises will become second nature, and you can always use this post as a reference if you want to revisit the implementation with fresh eyes after a while.

This article is reposted from my blog at codefrontend.com, check it out for other deep dives and quick guides. Follow me on Twitter @VincasStonys for web development tips.