async-exit-hook 2.0.1: unhandledRejectionHandler

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify async-exit-hook.unhandledRejectionHandler in pkg:npm/async-exit-hook@2.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/async-exit-hook@2.0.1
Demonstrate these symbols/APIs:
  - async-exit-hook.unhandledRejectionHandler

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:d5d9ce94b9d07e91f704df5a68b74a61320ac5dc32e694427ca5e4dbe7fdd16d","contract":["unhandledRejectionHandler is exported as a function on async-exit-hook","unhandledRejectionHandler registers synchronous handler called with error on unhandledRejection","unhandledRejectionHandler registers asynchronous handler receiving error and completion callback","unhandledRejectionHandler triggers standard exit hooks alongside rejection handlers on unhandled rejection","unhandledRejectionHandler exits process with status code 1 on unhandled rejection"],"goal":"verify async-exit-hook.unhandledRejectionHandler in pkg:npm/async-exit-hook@2.0.1","kind":"HOW","packages":["pkg:npm/async-exit-hook@2.0.1"],"schemaVersion":1,"symbols":["async-exit-hook.unhandledRejectionHandler"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/async-exit-hook@2.0.1"],"schemaVersion":1,"subject":"pkg:npm/async-exit-hook@2.0.1","symbols":["async-exit-hook.unhandledRejectionHandler"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-async-exit-hook",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-async-exit-hook",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "async-exit-hook": "2.0.1"
      }
    },
    "node_modules/async-exit-hook": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/async-exit-hook/-/async-exit-hook-2.0.1.tgz",
      "integrity": "sha512-NW2cX8m1Q7KPA7a5M2ULQeZ2wR5qI5PAbw5L0UOMxdioVk9PMZ0h1TmyZEkPYrCvYjDlFICusOu1dlEKAAeXBw==",
      "license": "MIT",
      "engines": {
        "node": ">=0.12.0"
      }
    }
  }
}

{
  "name": "sample-async-exit-hook",
  "version": "1.0.0",
  "private": true,
  "description": "verify async-exit-hook.unhandledRejectionHandler in pkg:npm/async-exit-hook@2.0.1",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "async-exit-hook": "2.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify async-exit-hook.unhandledRejectionHandler in pkg:npm/async-exit-hook@2.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/async-exit-hook@2.0.1"
  ],
  "symbols": [
    "async-exit-hook.unhandledRejectionHandler"
  ]
}

'use strict';

const exitHook = require('async-exit-hook');

/**
 * Register an unhandled promise rejection handler.
 *
 * @param {Function} handler - Rejection handler function (sync: err => ..., async: (err, callback) => ...)
 */
function registerUnhandledRejectionHandler(handler) {
  exitHook.unhandledRejectionHandler(handler);
}

/**
 * Register a standard process exit hook.
 *
 * @param {Function} handler - Exit hook callback (sync: () => ..., async: (callback) => ...)
 */
function registerExitHook(handler) {
  exitHook(handler);
}

/**
 * Configure the timeout for asynchronous exit hooks.
 *
 * @param {number} ms - Timeout in milliseconds
 */
function setForceExitTimeout(ms) {
  exitHook.forceExitTimeout(ms);
}

module.exports = {
  exitHook,
  unhandledRejectionHandler: exitHook.unhandledRejectionHandler,
  registerUnhandledRejectionHandler,
  registerExitHook,
  setForceExitTimeout
};

import assert from 'node:assert/strict';
import { spawnSync } from 'node:child_process';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const exitHookPkg = require('async-exit-hook');
const {
  exitHook,
  unhandledRejectionHandler,
  registerUnhandledRejectionHandler,
  registerExitHook,
  setForceExitTimeout
} = require('../src/index.js');

// 1. unhandledRejectionHandler is exported as a function on async-exit-hook
assert.equal(typeof unhandledRejectionHandler, 'function', 'unhandledRejectionHandler must be exported as a function');
assert.equal(unhandledRejectionHandler, exitHookPkg.unhandledRejectionHandler, 'unhandledRejectionHandler must match package export');
assert.equal(typeof registerUnhandledRejectionHandler, 'function', 'registerUnhandledRejectionHandler helper must be a function');
assert.equal(typeof registerExitHook, 'function', 'registerExitHook helper must be a function');
assert.equal(typeof setForceExitTimeout, 'function', 'setForceExitTimeout helper must be a function');

// 2. unhandledRejectionHandler registers synchronous handler called with error on unhandledRejection
{
  const child = spawnSync(
    process.execPath,
    [
      '-e',
      `
      const { registerUnhandledRejectionHandler } = require('./src/index.js');
      registerUnhandledRejectionHandler((err) => {
        process.stdout.write('SYNC_HANDLER_RECEIVED:' + err.message);
      });
      Promise.reject(new Error('test-sync-unhandled'));
      `
    ],
    {
      encoding: 'utf8',
      cwd: new URL('..', import.meta.url).pathname
    }
  );

  assert.equal(child.status, 1, 'Process should exit with code 1 on unhandled rejection');
  assert.ok(
    child.stdout.includes('SYNC_HANDLER_RECEIVED:test-sync-unhandled'),
    'Synchronous unhandledRejectionHandler must receive the error'
  );
}

// 3. unhandledRejectionHandler registers asynchronous handler receiving error and completion callback
{
  const child = spawnSync(
    process.execPath,
    [
      '-e',
      `
      const { registerUnhandledRejectionHandler } = require('./src/index.js');
      registerUnhandledRejectionHandler((err, callback) => {
        setTimeout(() => {
          process.stdout.write('ASYNC_HANDLER_RECEIVED:' + err.message);
          callback();
        }, 20);
      });
      Promise.reject(new Error('test-async-unhandled'));
      `
    ],
    {
      encoding: 'utf8',
      cwd: new URL('..', import.meta.url).pathname
    }
  );

  assert.equal(child.status, 1, 'Process should exit with code 1 on async unhandled rejection');
  assert.ok(
    child.stdout.includes('ASYNC_HANDLER_RECEIVED:test-async-unhandled'),
    'Asynchronous unhandledRejectionHandler must receive error and callback'
  );
}

// 4. unhandledRejectionHandler triggers standard exit hooks alongside rejection handlers on unhandled rejection
{
  const child = spawnSync(
    process.execPath,
    [
      '-e',
      `
      const { registerExitHook, registerUnhandledRejectionHandler } = require('./src/index.js');
      registerExitHook(() => {
        process.stdout.write('STANDARD_EXIT_HOOK_CALLED;');
      });
      registerUnhandledRejectionHandler((err) => {
        process.stdout.write('REJECTION_HOOK_CALLED:' + err.message + ';');
      });
      Promise.reject(new Error('test-dual-hook'));
      `
    ],
    {
      encoding: 'utf8',
      cwd: new URL('..', import.meta.url).pathname
    }
  );

  assert.equal(child.status, 1, 'Process should exit with code 1');
  assert.ok(
    child.stdout.includes('REJECTION_HOOK_CALLED:test-dual-hook;'),
    'Unhandled rejection handler must be invoked'
  );
  assert.ok(
    child.stdout.includes('STANDARD_EXIT_HOOK_CALLED;'),
    'Standard exit hook must be invoked alongside unhandled rejection handler'
  );
}

// 5. unhandledRejectionHandler exits process with status code 1 on unhandled rejection
{
  const child = spawnSync(
    process.execPath,
    [
      '-e',
      `
      const exitHook = require('async-exit-hook');
      exitHook.unhandledRejectionHandler(() => {});
      Promise.reject(new Error('exit-code-test'));
      `
    ],
    {
      encoding: 'utf8',
      cwd: new URL('..', import.meta.url).pathname
    }
  );

  assert.equal(child.status, 1, 'Unhandled rejection with handler must exit with status 1');
}

console.log('Contract assertions passed.');