bare-signals 5.0.0: SIGNAL_CLOSED

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 bare-signals.SIGNAL_CLOSED in pkg:npm/bare-signals@5.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/bare-signals@5.0.0
Demonstrate these symbols/APIs:
  - bare-signals.SIGNAL_CLOSED

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:c04893941e6da64fec749537e03efa1966a323f18308376ea01fd3e7bd29bde8","contract":["bare-signals package exports ./errors subpath and declares SignalError with readonly code in TypeScript definitions","SignalError.SIGNAL_CLOSED static factory creates a SignalError instance with code SIGNAL_CLOSED and name SignalError","Signal class exports errors.SIGNAL_CLOSED matching the SignalError constructor method","calling start on a Signal instance in closing or closed state throws SignalError with code SIGNAL_CLOSED","Signal close initiates native handle shutdown returning a Promise that resolves on close event","calling stop, ref, or unref on a closed Signal instance does not throw and returns the Signal instance"],"goal":"verify bare-signals.SIGNAL_CLOSED in pkg:npm/bare-signals@5.0.0","kind":"HOW","packages":["pkg:npm/bare-signals@5.0.0"],"schemaVersion":1,"symbols":["bare-signals.SIGNAL_CLOSED"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/bare-signals@5.0.0"],"schemaVersion":1,"subject":"pkg:npm/bare-signals@5.0.0","symbols":["bare-signals.SIGNAL_CLOSED"],"verifierAdapter":"node-typescript@1"}

{
  "name": "bare-signals-signal-closed-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "bare-signals-signal-closed-sample",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "bare-signals": "5.0.0"
      }
    },
    "node_modules/bare-events": {
      "version": "2.9.2",
      "resolved": "https://registry.npmjs.org/bare-events/-/bare-events-2.9.2.tgz",
      "integrity": "sha512-AIPKioV7/Y/8KfZ3AAhjPJxLLbY49S64Ym5DakZlUg75qQiTgUq9hEJoEwa4eUezPUlXRy/i5NpsKvo9jgKmoA==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "bare-abort-controller": "*"
      },
      "peerDependenciesMeta": {
        "bare-abort-controller": {
          "optional": true
        }
      }
    },
    "node_modules/bare-signals": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/bare-signals/-/bare-signals-5.0.0.tgz",
      "integrity": "sha512-8Gn8bBFUh2AUCJ9wWWFjSGWIo1HIUSIQnXRJGSm/f7GCDMqsuJhRmR1dT+HtDaDBkeu2l8Koxt2JLurfJ5yHVw==",
      "license": "Apache-2.0",
      "dependencies": {
        "bare-events": "^2.5.3"
      },
      "engines": {
        "bare": ">=1.7.0"
      }
    }
  }
}

{
  "name": "bare-signals-signal-closed-sample",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-signals": "5.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify bare-signals.SIGNAL_CLOSED in pkg:npm/bare-signals@5.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/bare-signals@5.0.0"
  ],
  "symbols": [
    "bare-signals.SIGNAL_CLOSED"
  ]
}

import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);

/**
 * Checks whether an error is a SIGNAL_CLOSED SignalError.
 * @param {unknown} err
 * @returns {boolean}
 */
export function isSignalClosedError(err) {
  if (!err || typeof err !== 'object') return false;
  return err.name === 'SignalError' && err.code === 'SIGNAL_CLOSED';
}

/**
 * Safely starts a Signal instance, catching and identifying SIGNAL_CLOSED.
 * @param {object} signal - The bare-signals Signal instance.
 * @returns {{ started: boolean, closed: boolean }}
 */
export function safeStartSignal(signal) {
  try {
    signal.start();
    return { started: true, closed: false };
  } catch (err) {
    if (isSignalClosedError(err)) {
      return { started: false, closed: true };
    }
    throw err;
  }
}

/**
 * Factory to construct a SIGNAL_CLOSED error using bare-signals errors module.
 * @param {string} message
 * @returns {Error}
 */
export function createSignalClosedError(message) {
  const SignalError = require('bare-signals/errors');
  return SignalError.SIGNAL_CLOSED(message);
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';
import {
  isSignalClosedError,
  safeStartSignal,
  createSignalClosedError,
} from '../src/index.mjs';

const require = createRequire(import.meta.url);

// 1. Verify package structure and exports for errors
const pkgPath = require.resolve('bare-signals/package');
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));

assert.equal(pkg.name, 'bare-signals', 'Package name must be bare-signals');
assert.equal(pkg.version, '5.0.0', 'Package version must be 5.0.0');
assert.ok(pkg.exports, 'Package must define exports map');
assert.equal(pkg.exports['./errors'], './lib/errors.js', 'Errors subpath must point to ./lib/errors.js');

const pkgDir = path.dirname(pkgPath);

// 2. Verify TypeScript type definitions for SignalError and errors export
const indexDts = fs.readFileSync(path.join(pkgDir, 'index.d.ts'), 'utf8');
assert.ok(indexDts.includes('declare class SignalError extends Error'), 'index.d.ts must declare SignalError class');
assert.ok(indexDts.includes('readonly code: string'), 'index.d.ts must declare readonly code property on SignalError');
assert.ok(indexDts.includes('export { SignalEmitter as Emitter, SignalError as errors }'), 'index.d.ts must export SignalError as errors');

// 3. Verify SignalError.SIGNAL_CLOSED static factory
const SignalError = require('bare-signals/errors');
assert.equal(typeof SignalError.SIGNAL_CLOSED, 'function', 'SignalError.SIGNAL_CLOSED must be a function');

const errorFromModule = SignalError.SIGNAL_CLOSED('Signal handle is closed');
assert.equal(errorFromModule.name, 'SignalError', 'SignalError.name must be SignalError');
assert.equal(errorFromModule.code, 'SIGNAL_CLOSED', 'SignalError.code must be SIGNAL_CLOSED');
assert.equal(errorFromModule.message, 'SIGNAL_CLOSED: Signal handle is closed', 'SignalError.message must include code prefix');
assert.ok(errorFromModule instanceof Error, 'SignalError must inherit from Error');

// 4. Mock binding to test Signal instance lifecycle under offline conditions
const bindingPath = path.join(pkgDir, 'binding.js');
const mockSignals = {
  SIGINT: 2,
  SIGTERM: 15,
};

let closeCallback = null;
let bindingCloseCalled = false;

require.cache[bindingPath] = {
  id: bindingPath,
  filename: bindingPath,
  loaded: true,
  exports: {
    signals: mockSignals,
    init: (ctx, onsignal, onclose) => {
      closeCallback = onclose.bind(ctx);
      return { id: 1, ctx, onsignal, onclose, active: false };
    },
    start: (handle, signum) => {
      handle.active = true;
    },
    stop: (handle) => {
      handle.active = false;
    },
    ref: (handle) => {},
    unref: (handle) => {},
    close: (handle) => {
      bindingCloseCalled = true;
      setImmediate(() => {
        if (closeCallback) closeCallback();
      });
    },
  },
};

const Signal = require('bare-signals');
assert.equal(Signal.errors.SIGNAL_CLOSED, SignalError.SIGNAL_CLOSED, 'Signal.errors.SIGNAL_CLOSED must match SignalError.SIGNAL_CLOSED');

// Test active signal can start and stop normally
const sig = new Signal('SIGINT');
assert.equal(sig.start(), sig, 'start() returns signal instance when active');
assert.equal(sig.stop(), sig, 'stop() returns signal instance');

// Initiate close on Signal instance
let closeEmitted = false;
sig.on('close', () => {
  closeEmitted = true;
});

const closingPromise = sig.close();
assert.ok(closingPromise instanceof Promise, 'close() must return a Promise');
assert.equal(bindingCloseCalled, true, 'binding.close must be called');

// Immediate start() while closing must throw SIGNAL_CLOSED
assert.throws(
  () => sig.start(),
  (err) => {
    return (
      err.name === 'SignalError' &&
      err.code === 'SIGNAL_CLOSED' &&
      err.message === 'SIGNAL_CLOSED: Signal is closed'
    );
  },
  'start() on closing signal must throw SignalError with code SIGNAL_CLOSED'
);

// Await completion of close event
await closingPromise;
assert.equal(closeEmitted, true, 'close event must have been emitted');

// Subsequent start() after close resolved must also throw SIGNAL_CLOSED
assert.throws(
  () => sig.start(),
  (err) => {
    return (
      err.name === 'SignalError' &&
      err.code === 'SIGNAL_CLOSED' &&
      err.message === 'SIGNAL_CLOSED: Signal is closed'
    );
  },
  'start() on fully closed signal must throw SignalError with code SIGNAL_CLOSED'
);

// Calling stop, ref, unref on closed signal should not throw and return this
assert.equal(sig.stop(), sig, 'stop() on closed signal returns this');
assert.equal(sig.ref(), sig, 'ref() on closed signal returns this');
assert.equal(sig.unref(), sig, 'unref() on closed signal returns this');

// 5. Verify helper functions from src/index.mjs
assert.equal(isSignalClosedError(errorFromModule), true, 'isSignalClosedError identifies SIGNAL_CLOSED');
assert.equal(isSignalClosedError(new Error('other')), false, 'isSignalClosedError rejects standard Error');
assert.equal(isSignalClosedError(null), false, 'isSignalClosedError rejects null');

const customClosedErr = createSignalClosedError('test custom message');
assert.equal(isSignalClosedError(customClosedErr), true, 'createSignalClosedError creates valid error');
assert.equal(customClosedErr.code, 'SIGNAL_CLOSED', 'createSignalClosedError sets code');

const safeStartClosedResult = safeStartSignal(sig);
assert.deepEqual(
  safeStartClosedResult,
  { started: false, closed: true },
  'safeStartSignal handles closed signal without throwing'
);

const freshSig = new Signal('SIGTERM');
const safeStartFreshResult = safeStartSignal(freshSig);
assert.deepEqual(
  safeStartFreshResult,
  { started: true, closed: false },
  'safeStartSignal succeeds on fresh signal'
);

console.log('All bare-signals.SIGNAL_CLOSED contract assertions passed successfully.');