README.md

domain-parent 👪

Adds a parent Node.js domain reference (parentDomain property) to all domains.

• domain-parent 👪
  • Motivation
  • Implementation
  • Usage
    • Do not use in distributed packages

Motivation

Domains provide a way to add context to a chain of asynchronous calls. Having a reference to the parentDomain allows to collect context from all parent domains.

Roarr logger demonstrates how parentDomain can be used to create comprehensive logs.

Implementation

domain-parent monkey-patches Node.js domain create method. All domains that are created after Node.js has been shimmed will have parentDomain property. Top-level domain will have parentDomain set to NULL.

Usage

To shim Node.js, import domain-parent/auto, e.g.

import 'domain-parent/auto';
import domain from 'domain';

domain.parentDomain === null;

const d0 = domain.create();

d0.run(() => {
  process.domain.parentDomain === null;

  const d1 = domain.create();

  d1.run(() => {
    process.domain.parentDomain === d0;
  });
});

Do not use in distributed packages

Do not shim Node.js in distributable NPM package. If your package depends on parentDomain, then:

1. Check if Node.js is shimmed (require('domain').parentDomain !== undefined) and warn if Node.js is not shimmed.
2. Document that your package depends on parentDomain and provide instructions for adding domain-parent shim.