async-exit-hook 2.0.1: uncaughtExceptionHandler

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.uncaughtExceptionHandler 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.uncaughtExceptionHandler

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:eacc07814a13faa636032d5cb56a9640679fe566e7eaab32061855187352a880","contract":["uncaughtExceptionHandler is exported as a function on async-exit-hook","uncaughtExceptionHandler registers synchronous handler called with error on uncaughtException","uncaughtExceptionHandler registers asynchronous handler receiving error and completion callback","uncaughtExceptionHandler triggers standard exit hooks alongside error handlers on uncaught exception","uncaughtExceptionHandler exits process with status code 1 on uncaught exception"],"goal":"verify async-exit-hook.uncaughtExceptionHandler 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.uncaughtExceptionHandler"]},"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.uncaughtExceptionHandler"],"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.uncaughtExceptionHandler 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.uncaughtExceptionHandler in pkg:npm/async-exit-hook@2.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/async-exit-hook@2.0.1"
  ],
  "symbols": [
    "async-exit-hook.uncaughtExceptionHandler"
  ]
}

'use strict';

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

/**
 * Register an uncaught exception handler.
 *
 * @param {Function} handler - Exception handler function (sync: err => ..., async: (err, callback) => ...)
 */
function registerUncaughtHandler(handler) {
  exitHook.uncaughtExceptionHandler(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,
  uncaughtExceptionHandler: exitHook.uncaughtExceptionHandler,
  registerUncaughtHandler,
  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,
  uncaughtExceptionHandler,
  registerUncaughtHandler,
  registerExitHook,
  setForceExitTimeout
} = require('../src/index.js');

// 1. uncaughtExceptionHandler is exported as a function on async-exit-hook
assert.equal(typeof uncaughtExceptionHandler, 'function', 'uncaughtExceptionHandler must be exported as a function');
assert.equal(uncaughtExceptionHandler, exitHookPkg.uncaughtExceptionHandler, 'uncaughtExceptionHandler must match package export');
assert.equal(typeof registerUncaughtHandler, 'function', 'registerUncaughtHandler 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. uncaughtExceptionHandler registers synchronous handler called with error on uncaughtException
{
  const child = spawnSync(
    process.execPath,
    [
      '-e',
      `
      const { registerUncaughtHandler } = require('./src/index.js');
      registerUncaughtHandler((err) => {
        process.stdout.write('SYNC_HANDLER_RECEIVED:' + err.message);
      });
      throw new Error('test-sync-uncaught');
      `
    ],
    {
      encoding: 'utf8',
      cwd: new URL('..', import.meta.url).pathname
    }
  );

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

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

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

// 4. uncaughtExceptionHandler triggers standard exit hooks alongside error handlers on uncaught exception
{
  const child = spawnSync(
    process.execPath,
    [
      '-e',
      `
      const { registerExitHook, registerUncaughtHandler } = require('./src/index.js');
      registerExitHook(() => {
        process.stdout.write('STANDARD_EXIT_HOOK_CALLED;');
      });
      registerUncaughtHandler((err) => {
        process.stdout.write('ERR_HOOK_CALLED:' + err.message + ';');
      });
      throw 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('ERR_HOOK_CALLED:test-dual-hook;'),
    'Uncaught exception handler must be invoked'
  );
  assert.ok(
    child.stdout.includes('STANDARD_EXIT_HOOK_CALLED;'),
    'Standard exit hook must be invoked alongside uncaught exception handler'
  );
}

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

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

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