`@truffle/promise-tracker`

This library is used for keeping track of asynchronous work that needs to complete prior to the process exiting.

Usage

IMPORTANT Only use this library as a last resort. Typically you're better off architecting things so that you don't need process-level tracking of outstanding tasks.

Some alternatives to consider before using this module:

Wherever possible, only make asynchronous calls from within an asynchronous context (aka, avoid using .then and .catch callbacks).
Implement timeouts for long-running processes using Promise.race
Unref any best-effort/speculative timers (immediate, timeout to prevent them from keeping your process alive when everything else is done

Tracking asynchronous operations

For the moment promise tracking is implemented as a method decorator, meaning it must be applied to method declaration on a class.

It can be applied to any method, and it will only add special handling when methods return promises

import { tracked } from "@truffle/promise-tracker";

class Foo {
  // totally fine, even though it doesn't return a promise
  @tracked
  synchronousBar(): "-" {
    return "-";
  }

  @tracked
  async asyncBar(): Promise<"-"> {
    return "-";
  }

  // this works the same as with `asyncBar`, even though it's not explicitly an
  // async method
  @tracked
  promiseBar(): Promise<"-"> {
    return new Promise<"-">(resolve => resolve("-"));
  }
}

Waiting for tracked operations to complete (async)

import { waitForOutstandingPromises } from "@truffle/promiseTracker";

let exitCode = 0;

// If no catchHandler is passed, rejected promises are handled silently.
// This is because these promise rejections should already be handled by the
// caller that created the promise.
await waitForOutstandingPromises({ catchHandler: () => (exitCode = 1) });
process.exit(exitCode);

Waiting for tracked operations to complete (synchronous)

import { waitForOutstandingPromises } from "@truffle/promiseTracker";

let exitCode = 0;

// If no catchHandler is passed, rejected promises are handled silently.
// This is because these promise rejections should already be handled by the
// caller that created the promise.
waitForOutstandingPromises({ catchHandler: () => (exitCode = 1) }).then(() => {
  process.exit(exitCode);
});