signal-exit 4.1.0

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 pkg:npm/signal-exit@4.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/signal-exit@4.1.0

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:4637b57bf82ee0b7f3c90d194a0fa984ea9ab3b5abb35de338c7226fa79affbd","contract":["onExit registers an exit callback and returns an unregister function","calling the returned unregister function prevents the exit callback from firing","onExit callback receives the numeric exit code when process.exit is called","onExit callback receives exit code 0 when the Node.js event loop terminates naturally","onExit callback receives the signal name when the process receives a termination signal","onExit with alwaysLast option executes after standard exit listeners","signals export provides an array of standard POSIX termination signal names","load and unload functions control the lifecycle of process exit listeners"],"goal":"verify pkg:npm/signal-exit@4.1.0","kind":"HOW","packages":["pkg:npm/signal-exit@4.1.0"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/signal-exit@4.1.0"],"schemaVersion":1,"subject":"pkg:npm/signal-exit@4.1.0","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-signal-exit",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-signal-exit",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "signal-exit": "4.1.0"
      }
    },
    "node_modules/signal-exit": {
      "version": "4.1.0",
      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
      "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
      "license": "ISC",
      "engines": {
        "node": ">=14"
      },
      "funding": {
        "url": "https://github.com/sponsors/isaacs"
      }
    }
  }
}

{
  "name": "sample-signal-exit",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room code sample for signal-exit@4.1.0",
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "signal-exit": "4.1.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/signal-exit@4.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/signal-exit@4.1.0"
  ]
}

const signalExit = require('signal-exit');

/**
 * Registers an exit listener callback to run when process terminates.
 *
 * @param {Function} callback - Function called with (code, signal) on process exit.
 * @param {Object} [options] - Optional configuration like alwaysLast.
 * @returns {Function} Unregister function to remove the listener.
 */
function registerExit(callback, options) {
  return signalExit.onExit(callback, options);
}

/**
 * Returns list of standard POSIX signals tracked by signal-exit.
 *
 * @returns {string[]} List of signal names.
 */
function getMonitoredSignals() {
  return signalExit.signals;
}

/**
 * Explicitly loads exit and signal listeners.
 */
function loadListeners() {
  signalExit.load();
}

/**
 * Explicitly unloads exit and signal listeners.
 */
function unloadListeners() {
  signalExit.unload();
}

module.exports = {
  signalExit,
  onExit: signalExit.onExit,
  signals: signalExit.signals,
  load: signalExit.load,
  unload: signalExit.unload,
  registerExit,
  getMonitoredSignals,
  loadListeners,
  unloadListeners
};

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

const require = createRequire(import.meta.url);
const {
  signalExit,
  onExit,
  signals,
  load,
  unload,
  registerExit,
  getMonitoredSignals,
  loadListeners,
  unloadListeners
} = require('../src/index.js');

async function runContract() {
  // 1. onExit registers an exit callback and returns an unregister function
  assert.equal(typeof onExit, 'function', 'onExit should be a function');
  assert.equal(typeof registerExit, 'function', 'registerExit should be a function');
  const dummyFn = () => {};
  const unregister = onExit(dummyFn);
  assert.equal(typeof unregister, 'function', 'onExit must return an unregister function');
  unregister();

  // 2. calling the returned unregister function prevents the exit callback from firing
  const unregisterChild = spawnSync(process.execPath, [
    '-e',
    `
    const { onExit } = require('signal-exit');
    const unregister = onExit(() => {
      console.log('SHOULD_NOT_EXECUTE');
    });
    unregister();
    process.exit(0);
    `
  ], { encoding: 'utf8' });
  assert.equal(unregisterChild.status, 0);
  assert.ok(!unregisterChild.stdout.includes('SHOULD_NOT_EXECUTE'), 'Unregistered callback must not execute');

  // 3. onExit callback receives the numeric exit code when process.exit is called
  const exitCodeChild = spawnSync(process.execPath, [
    '-e',
    `
    const { onExit } = require('signal-exit');
    onExit((code, signal) => {
      console.log('EXIT_INFO:' + code + ':' + signal);
    });
    process.exit(42);
    `
  ], { encoding: 'utf8' });
  assert.equal(exitCodeChild.status, 42);
  assert.ok(exitCodeChild.stdout.includes('EXIT_INFO:42:null'), `Expected EXIT_INFO:42:null, got ${exitCodeChild.stdout}`);

  // 4. onExit callback receives exit code 0 when the Node.js event loop terminates naturally
  const naturalExitChild = spawnSync(process.execPath, [
    '-e',
    `
    const { onExit } = require('signal-exit');
    onExit((code, signal) => {
      console.log('NATURAL_EXIT:' + code + ':' + signal);
    });
    `
  ], { encoding: 'utf8' });
  assert.equal(naturalExitChild.status, 0);
  assert.ok(naturalExitChild.stdout.includes('NATURAL_EXIT:0:null'), `Expected NATURAL_EXIT:0:null, got ${naturalExitChild.stdout}`);

  // 5. onExit callback receives the signal name when the process receives a termination signal
  const signalChild = spawnSync(process.execPath, [
    '-e',
    `
    const { onExit } = require('signal-exit');
    onExit((code, signal) => {
      console.log('SIGNAL_RECEIVED:' + code + ':' + signal);
    });
    setTimeout(() => {}, 5000);
    process.kill(process.pid, 'SIGINT');
    `
  ], { encoding: 'utf8' });
  assert.ok(signalChild.stdout.includes('SIGNAL_RECEIVED:null:SIGINT'), `Expected SIGNAL_RECEIVED:null:SIGINT, got ${signalChild.stdout}`);

  // 6. onExit with alwaysLast option executes after standard exit listeners
  const orderChild = spawnSync(process.execPath, [
    '-e',
    `
    const { onExit } = require('signal-exit');
    const order = [];
    onExit(() => { order.push('last'); }, { alwaysLast: true });
    onExit(() => { order.push('first'); });
    onExit(() => {
      console.log('ORDER:' + order.join(','));
    }, { alwaysLast: true });
    process.exit(0);
    `
  ], { encoding: 'utf8' });
  assert.equal(orderChild.status, 0);
  assert.ok(orderChild.stdout.includes('ORDER:first,last'), `Expected ORDER:first,last, got ${orderChild.stdout}`);

  // 7. signals export provides an array of standard POSIX termination signal names
  assert.ok(Array.isArray(signals), 'signals should be an array');
  assert.ok(signals.includes('SIGINT'), 'signals array should include SIGINT');
  assert.ok(signals.includes('SIGTERM'), 'signals array should include SIGTERM');
  assert.ok(signals.includes('SIGHUP'), 'signals array should include SIGHUP');
  assert.deepEqual(getMonitoredSignals(), signals, 'getMonitoredSignals must return signals array');

  // 8. load and unload functions control the lifecycle of process exit listeners
  assert.equal(typeof load, 'function', 'load must be a function');
  assert.equal(typeof unload, 'function', 'unload must be a function');
  assert.equal(typeof loadListeners, 'function', 'loadListeners must be a function');
  assert.equal(typeof unloadListeners, 'function', 'unloadListeners must be a function');
  loadListeners();
  unloadListeners();

  console.log('All signal-exit contract tests passed successfully.');
}

runContract().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});