Let's build JS Promise from scratch

Press Space for next page

Speaker: Fabrizio A. Vitale

Let's build JS Promise from scratch

Press Space for next page

Speaker: Fabrizio A. Vitale

Goals

Build a Promise A+ spec compliant Promise in Typescript.
Learn Javascript Promises.
Have fun!

From

export class PinkyPromise<T> { 
  // TODO add implementation
}
export class PinkyPromise<T> { 
  // TODO add implementation
}

source

To

/**
 * A [Promise A+](https://promisesaplus.com/) spec compliant implementation written in typescript.
 */
export class PinkyPromise<T> implements PromiseLike<T> {
  #state: PromiseState<T> = { status: "pending" };
  #fulfilledListeners: ((value: unknown) => unknown)[] = [];
  #rejectedListeners: ((reason: unknown) => unknown)[] = [];

  constructor(executor: PinkyPromiseExecutor<T>) {
    if (typeof executor !== "function") {
      throw new TypeError(`${executor} is not a function`);
    }

    try {
      executor(this.#resolve, this.#reject);
    } catch (executorError) {
      this.#reject(executorError);
    }
  }

  /**
   * Notifies the subscribed listeners if the promise is settled.
   */
  #notify() {
  // Continue...
}
/**
 * A [Promise A+](https://promisesaplus.com/) spec compliant implementation written in typescript.
 */
export class PinkyPromise<T> implements PromiseLike<T> {
  #state: PromiseState<T> = { status: "pending" };
  #fulfilledListeners: ((value: unknown) => unknown)[] = [];
  #rejectedListeners: ((reason: unknown) => unknown)[] = [];

  constructor(executor: PinkyPromiseExecutor<T>) {
    if (typeof executor !== "function") {
      throw new TypeError(`${executor} is not a function`);
    }

    try {
      executor(this.#resolve, this.#reject);
    } catch (executorError) {
      this.#reject(executorError);
    }
  }

  /**
   * Notifies the subscribed listeners if the promise is settled.
   */
  #notify() {
  // Continue...
}

source

Ready?

So… what’s a Promise?

A promise is an object that represents the eventual result of an asynchronous operation.

So… what’s a Promise?

Allows the subscription of listeners to the result of an asynchronous action or the reason why it has failed.

A bit of history / 1

Based on paper written in the 1976 by Daniel P. Friedman, David, S. Wise.
Popularized in Javascript by JQuery in 2011.

A bit of history / 2

A specification, Promise A+ written by Domenic Denicola was created in 2012.
Standardized in ECMAScript2015 (ES6) in 2015.

Promise states

A Promise is in one of these states:

😴 pending: initial state
✅ fulfilled: the operation was completed successfully.
❌ rejected : the operation failed.

MDN

Promise states

Promise states implementation / 1

/**
 * A Promise is in one of these states:
 *
 * - pending: initial state, neither fulfilled nor rejected.
 * - fulfilled: meaning that the operation was completed successfully.
 * - rejected: meaning that the operation failed.
 */
type PromiseState<T> =
  | { readonly status: "pending" }
  | { readonly status: "fulfilled"; readonly value: T }
  | { readonly status: "rejected"; readonly reason: any };

export class PinkyPromise<T> {
  #state: PromiseState<T> = { status: "pending" };
}
/**
 * A Promise is in one of these states:
 *
 * - pending: initial state, neither fulfilled nor rejected.
 * - fulfilled: meaning that the operation was completed successfully.
 * - rejected: meaning that the operation failed.
 */
type PromiseState<T> =
  | { readonly status: "pending" }
  | { readonly status: "fulfilled"; readonly value: T }
  | { readonly status: "rejected"; readonly reason: any };

export class PinkyPromise<T> {
  #state: PromiseState<T> = { status: "pending" };
}

Promise states implementation / 2

export class PinkyPromise<T> {
  #state: PromiseState<T> = { status: "pending" };

  /**
   * Settles promise, transitioning it from state pending to either `fulfilled` or `rejected`.
   */
  static #transition(
    pinkyPromise: PinkyPromise<any>,
    state: PromiseState<any>,
  ) {
    if (pinkyPromise.#state.status === "pending") {
      pinkyPromise.#state = state;
    }
  }
}
export class PinkyPromise<T> {
  #state: PromiseState<T> = { status: "pending" };

  /**
   * Settles promise, transitioning it from state pending to either `fulfilled` or `rejected`.
   */
  static #transition(
    pinkyPromise: PinkyPromise<any>,
    state: PromiseState<any>,
  ) {
    if (pinkyPromise.#state.status === "pending") {
      pinkyPromise.#state = state;
    }
  }
}

Create a Promise

JS Promise constructor

Synchronously throws error if it’s invoked without new.
Synchronously throws error if input executor is not a function.
Synchronously calls the input with resolve and reject.
Rejects the promise if executor raises an error.

Spec - MDN

JS Promise constructor implementation

export class PinkyPromise<T> {
  #state: PromiseState<T> = { status: "pending" };

  constructor(executor: PinkyPromiseExecutor<T>) {
    if (typeof executor !== "function") {
      throw new TypeError(`${executor} is not a function`);
    }

    try {
      executor(this.#resolve, this.#reject);
    } catch (executorError) {
      this.#reject(executorError);
    }
  }

  #transition(pinkyPromise: PinkyPromise<any>, state: PromiseState<any>) { /* implementation */ }

  #resolve = (value: T | PromiseLike<T>): void => {
    PinkyPromise.#transition(this, { status: "fulfilled", value });
  };
  #reject = (reason: unknown): void => {
    PinkyPromise.#transition(this, { status: "rejected", reason });
  };
}
export class PinkyPromise<T> {
  #state: PromiseState<T> = { status: "pending" };

  constructor(executor: PinkyPromiseExecutor<T>) {
    if (typeof executor !== "function") {
      throw new TypeError(`${executor} is not a function`);
    }

    try {
      executor(this.#resolve, this.#reject);
    } catch (executorError) {
      this.#reject(executorError);
    }
  }

  #transition(pinkyPromise: PinkyPromise<any>, state: PromiseState<any>) { /* implementation */ }

  #resolve = (value: T | PromiseLike<T>): void => {
    PinkyPromise.#transition(this, { status: "fulfilled", value });
  };
  #reject = (reason: unknown): void => {
    PinkyPromise.#transition(this, { status: "rejected", reason });
  };
}

Notify Promise resolution

.then() method

Notifies when a Promise settles either onFulfill(value) or onRejection(reason) once.
Returns the unwrapped output of the invoked promise in a new Promise.

.then() method

Chaining Promises

new Promise(resolve => resolve(5))
  .then(a => a + 5)
  .then(a => a + 6)
  .then(console.log)

// Logs 16

new Promise((_, reject) => reject(5))
  .then(a => a + 5)
  .then(a => a + 6)
  .catch(console.log)

// Logs 5
new Promise(resolve => resolve(5))
  .then(a => a + 5)
  .then(a => a + 6)
  .then(console.log)

// Logs 16

new Promise((_, reject) => reject(5))
  .then(a => a + 5)
  .then(a => a + 6)
  .catch(console.log)

// Logs 5

then(onFulfill, onRejection)

returns a new Promise that contains the output of computation of either onFulfill or onRejection.

.then() method implementation / 1

export class PinkyPromise<T> implements PromiseLike<T> {
  #notify() { /* TO DO add implemetation */ }

  static #transition(
    pinkyPromise: PinkyPromise<any>,
    state: PromiseState<any>,
  ) {
    if (pinkyPromise.#state.status === "pending") {
      pinkyPromise.#state = state;
      pinkyPromise.#notify();
    }
  }

  then<TResult1 = T, TResult2 = never>(
    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined,
  ): PinkyPromise<TResult1 | TResult2> {
    return  new PinkyPromise<TResult1 | TResult2>((resolve, reject) => {
      // do something then resolve
      this.#notify();
    });
  }
}
export class PinkyPromise<T> implements PromiseLike<T> {
  #notify() { /* TO DO add implemetation */ }

  static #transition(
    pinkyPromise: PinkyPromise<any>,
    state: PromiseState<any>,
  ) {
    if (pinkyPromise.#state.status === "pending") {
      pinkyPromise.#state = state;
      pinkyPromise.#notify();
    }
  }

  then<TResult1 = T, TResult2 = never>(
    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null | undefined,
    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null | undefined,
  ): PinkyPromise<TResult1 | TResult2> {
    return  new PinkyPromise<TResult1 | TResult2>((resolve, reject) => {
      // do something then resolve
      this.#notify();
    });
  }
}

.then() method implementation / 2

export class PinkyPromise<T> implements PromiseLike<T> {
  #state: PromiseState<T> = { status: "pending" };
  #fulfilledListeners: ((value: unknown) => unknown)[] = [];
  #rejectedListeners: ((reason: unknown) => unknown)[] = [];
  // Notify listeners if the Promise is settled
  #notify() {
    switch (this.#state.status) {
      case "pending":
        break;
      case "fulfilled": {
        this.#fulfilledListeners.forEach((cb) => queueMicrotask(() => cb(this.#state.value)));
        break;
      }
      case "rejected": {
        this.#rejectedListeners.forEach((cb) => queueMicrotask(() => cb(this.#state.reason)));
        break;
      }
    }
    // remove listeners at the end if the Promise is not settled
    if (this.#state.status !== "pending") {
      this.#fulfilledListeners.splice(0, this.#fulfilledListeners.length);
      this.#rejectedListeners.splice(0, this.#rejectedListeners.length);
    }
  }
}
export class PinkyPromise<T> implements PromiseLike<T> {
  #state: PromiseState<T> = { status: "pending" };
  #fulfilledListeners: ((value: unknown) => unknown)[] = [];
  #rejectedListeners: ((reason: unknown) => unknown)[] = [];
  // Notify listeners if the Promise is settled
  #notify() {
    switch (this.#state.status) {
      case "pending":
        break;
      case "fulfilled": {
        this.#fulfilledListeners.forEach((cb) => queueMicrotask(() => cb(this.#state.value)));
        break;
      }
      case "rejected": {
        this.#rejectedListeners.forEach((cb) => queueMicrotask(() => cb(this.#state.reason)));
        break;
      }
    }
    // remove listeners at the end if the Promise is not settled
    if (this.#state.status !== "pending") {
      this.#fulfilledListeners.splice(0, this.#fulfilledListeners.length);
      this.#rejectedListeners.splice(0, this.#rejectedListeners.length);
    }
  }
}

Unwrapping Promises

Quiz: What's logged in console?

Q-1

Promise.resolve(
  new Promise(resolve => Promise.resolve(5))
).then(console.log)
Promise.resolve(
  new Promise(resolve => Promise.resolve(5))
).then(console.log)

Q-2

Promise.resolve(
  new Promise((_ ,reject) => reject(10))
 ).then(
    a => Promise.resolve(a + 10), 
    a => Promise.resolve(a + 2)
  )
  .then(console.log)
Promise.resolve(
  new Promise((_ ,reject) => reject(10))
 ).then(
    a => Promise.resolve(a + 10), 
    a => Promise.resolve(a + 2)
  )
  .then(console.log)

A-1

Promise.resolve(
  new Promise(resolve => Promise.resolve(5))
).then(console.log)  // Logs 5
Promise.resolve(
  new Promise(resolve => Promise.resolve(5))
).then(console.log)  // Logs 5

A-2

Promise.resolve(
  new Promise((_ ,reject) => reject(10))
 ).then(
    a => Promise.resolve(a + 10), 
    a => Promise.resolve(a + 2)
  )
  .then(console.log) // Logs 12
Promise.resolve(
  new Promise((_ ,reject) => reject(10))
 ).then(
    a => Promise.resolve(a + 10), 
    a => Promise.resolve(a + 2)
  )
  .then(console.log) // Logs 12

Promise resolution procedure / 1

The output of .then() callbacks and the argument passed to resolve and reject is always unwrapped,
i.e not a Promise.

The algorithm has to conform to the
Promise A+ Promise resolution procedure.

PinkyPromise implementation.

Promise A+ spec

Putting all the pieces together

Test suite

Our Implementation passes all tests of the Promise A+ Compliance test suite 🚀.

pnpm test:a-plus
# Several skipped lines
# [...]
    The value is `true` with `Boolean.prototype` modified to have a `then` method
      ✓ already-fulfilled
      ✓ immediately-fulfilled
      ✓ eventually-fulfilled
      ✓ already-rejected
      ✓ immediately-rejected
      ✓ eventually-rejected
    The value is `1` with `Number.prototype` modified to have a `then` method
      ✓ already-fulfilled
      ✓ immediately-fulfilled
      ✓ eventually-fulfilled
      ✓ already-rejected
      ✓ immediately-rejected
      ✓ eventually-rejected

  872 passing (13s)
pnpm test:a-plus
# Several skipped lines
# [...]
    The value is `true` with `Boolean.prototype` modified to have a `then` method
      ✓ already-fulfilled
      ✓ immediately-fulfilled
      ✓ eventually-fulfilled
      ✓ already-rejected
      ✓ immediately-rejected
      ✓ eventually-rejected
    The value is `1` with `Number.prototype` modified to have a `then` method
      ✓ already-fulfilled
      ✓ immediately-fulfilled
      ✓ eventually-fulfilled
      ✓ already-rejected
      ✓ immediately-rejected
      ✓ eventually-rejected

  872 passing (13s)

The full Promise A+ implementation is available at
https://github.com/FaberVitale/pinky-promise/blob/main/lib/pinky-promise.ts

Let's build JS Promise from scratch

Speaker: Fabrizio A. Vitale

Goals

Let's build JS Promise from scratch

Speaker: Fabrizio A. Vitale

Goals

From

To

Ready?

So… what’s a Promise?

So… what’s a Promise?

A bit of history / 1

A bit of history / 2

Promise states

Promise states

Promise states

Promise states implementation / 1

Promise states implementation / 2

Create a Promise

JS Promise constructor

JS Promise constructor implementation

Notify Promise resolution

.then() method

.then() method

Chaining Promises

.then() method implementation / 1

.then() method implementation / 2

Unwrapping Promises

Quiz: What's logged in console?

Q-1

Q-2

A-1

A-2

Promise resolution procedure / 1

Putting all the pieces together

Test suite

Thank you!

Slides

Full Promise implementation

Promise A+