bare-signals 5.0.0: errors

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

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:583de6399e6c1d4978edd99091f80b303f3f0d2da81dc4c6b0faee24eb5520b6","contract":["package manifest exports errors submodule pointing to lib/errors.js in bare-signals@5.0.0","TypeScript definitions in index.d.ts declare SignalError class with code property exported as errors","SignalError is exported from bare-signals/errors submodule and exposed as Signal.errors","SignalError constructor sets code and name property returning SignalError","SignalError.UNKNOWN_SIGNAL factory instantiates SignalError with code UNKNOWN_SIGNAL","SignalError.SIGNAL_CLOSED factory instantiates SignalError with code SIGNAL_CLOSED","SignalError instances inherit from Error and capture runtime stack traces","Signal constructor throws SignalError with code UNKNOWN_SIGNAL for invalid signal names","calling start on a closed Signal throws SignalError with code SIGNAL_CLOSED","helper isSignalError accurately identifies SignalError instances","helper classifySignalError distinguishes UNKNOWN_SIGNAL and SIGNAL_CLOSED from generic errors"],"goal":"verify bare-signals.errors in pkg:npm/bare-signals@5.0.0","kind":"HOW","packages":["pkg:npm/bare-signals@5.0.0"],"schemaVersion":1,"symbols":["bare-signals.errors"]},"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.errors"],"verifierAdapter":"node-typescript@1"}

{
  "name": "bare-signals-errors-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "bare-signals-errors-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-errors-sample",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "bare-signals": "5.0.0"
  }
}

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

import { createRequire } from 'node:module';

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

/**
 * Checks whether an error is a bare-signals SignalError.
 * @param {unknown} err
 * @returns {boolean}
 */
export function isSignalError(err) {
  return (
    err !== null &&
    typeof err === 'object' &&
    err.name === 'SignalError' &&
    typeof err.code === 'string'
  );
}

/**
 * Creates a SignalError using the appropriate static factory.
 * @param {'UNKNOWN_SIGNAL' | 'SIGNAL_CLOSED'} type
 * @param {string} message
 * @returns {Error}
 */
export function createSignalError(type, message) {
  const SignalError = require('bare-signals/errors');
  if (type === 'UNKNOWN_SIGNAL') {
    return SignalError.UNKNOWN_SIGNAL(message);
  }
  if (type === 'SIGNAL_CLOSED') {
    return SignalError.SIGNAL_CLOSED(message);
  }
  throw new Error(`Unsupported SignalError type: ${type}`);
}

/**
 * Classifies an error into a bare-signals error code or 'OTHER'.
 * @param {unknown} err
 * @returns {'UNKNOWN_SIGNAL' | 'SIGNAL_CLOSED' | 'OTHER'}
 */
export function classifySignalError(err) {
  if (!isSignalError(err)) {
    return 'OTHER';
  }
  if (err.code === 'UNKNOWN_SIGNAL') {
    return 'UNKNOWN_SIGNAL';
  }
  if (err.code === 'SIGNAL_CLOSED') {
    return 'SIGNAL_CLOSED';
  }
  return 'OTHER';
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';
import {
  isSignalError,
  createSignalError,
  classifySignalError,
} from '../src/index.mjs';

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

// 1. Contract: package manifest exports errors submodule pointing to lib/errors.js in bare-signals@5.0.0
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 export must specify lib/errors.js'
);

const pkgDir = path.dirname(pkgPath);

// 2. Contract: TypeScript definitions in index.d.ts declare SignalError class with code property exported as errors
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 extending Error'
);
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. Contract: SignalError is exported from bare-signals/errors submodule and exposed as Signal.errors
const SignalError = require('bare-signals/errors');
assert.equal(typeof SignalError, 'function', 'SignalError must be a class constructor');

// 4. Contract: SignalError constructor sets code and name property returning SignalError
const directErr = new SignalError('test custom message', SignalError, 'CUSTOM_CODE');
assert.equal(directErr.name, 'SignalError', 'SignalError name property must be SignalError');
assert.equal(directErr.code, 'CUSTOM_CODE', 'SignalError code property must match');
assert.equal(directErr.message, 'CUSTOM_CODE: test custom message', 'Formatted message');

// 5. Contract: SignalError.UNKNOWN_SIGNAL factory instantiates SignalError with code UNKNOWN_SIGNAL
const unkErr = SignalError.UNKNOWN_SIGNAL("Unknown signal 'SIGTEST'");
assert.equal(unkErr.name, 'SignalError', 'Error name property must be SignalError');
assert.equal(unkErr.code, 'UNKNOWN_SIGNAL', 'Error code must be UNKNOWN_SIGNAL');
assert.equal(unkErr.message, "UNKNOWN_SIGNAL: Unknown signal 'SIGTEST'", 'Error message formatting');

// 6. Contract: SignalError.SIGNAL_CLOSED factory instantiates SignalError with code SIGNAL_CLOSED
const closedErr = SignalError.SIGNAL_CLOSED('Signal is closed');
assert.equal(closedErr.name, 'SignalError', 'Error name property must be SignalError');
assert.equal(closedErr.code, 'SIGNAL_CLOSED', 'Error code must be SIGNAL_CLOSED');
assert.equal(closedErr.message, 'SIGNAL_CLOSED: Signal is closed', 'Error message formatting');

// 7. Contract: SignalError instances inherit from Error and capture runtime stack traces
assert.ok(unkErr instanceof Error, 'SignalError instance must be an instance of Error');
assert.ok(unkErr instanceof SignalError, 'SignalError instance must be an instance of SignalError');
assert.ok(
  typeof unkErr.stack === 'string' && unkErr.stack.length > 0,
  'SignalError must capture stack trace'
);

// 8. Mock binding to test Signal integration offline
const bindingPath = path.join(pkgDir, 'binding.js');
const mockSignals = {
  SIGHUP: 1,
  SIGINT: 2,
  SIGTERM: 15,
};

require.cache[bindingPath] = {
  id: bindingPath,
  filename: bindingPath,
  loaded: true,
  exports: {
    signals: mockSignals,
    init: (ctx, onsignal, onclose) => {
      return { ctx, onsignal, onclose };
    },
    start: () => {},
    stop: () => {},
    ref: () => {},
    unref: () => {},
    close: (handle) => {
      if (handle && typeof handle.onclose === 'function') {
        handle.onclose.call(handle.ctx);
      }
    },
  },
};

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

// Contract: Signal constructor throws SignalError with code UNKNOWN_SIGNAL for invalid signal names
assert.throws(
  () => new Signal('SIGUNKNOWN'),
  (err) => {
    return (
      err instanceof SignalError &&
      err.code === 'UNKNOWN_SIGNAL' &&
      err.message === "UNKNOWN_SIGNAL: Unknown signal 'SIGUNKNOWN'"
    );
  },
  'Signal constructor must throw SignalError with code UNKNOWN_SIGNAL'
);

// Contract: calling start on a closed Signal throws SignalError with code SIGNAL_CLOSED
const sig = new Signal('SIGINT');
sig.close();
assert.throws(
  () => sig.start(),
  (err) => {
    return (
      err instanceof SignalError &&
      err.code === 'SIGNAL_CLOSED' &&
      err.message === 'SIGNAL_CLOSED: Signal is closed'
    );
  },
  'Calling start on closed signal must throw SignalError with code SIGNAL_CLOSED'
);

// 9. Contract: helper isSignalError accurately identifies SignalError instances
assert.equal(isSignalError(unkErr), true, 'Identifies UNKNOWN_SIGNAL as SignalError');
assert.equal(isSignalError(closedErr), true, 'Identifies SIGNAL_CLOSED as SignalError');
assert.equal(isSignalError(directErr), true, 'Identifies direct SignalError instance');
assert.equal(isSignalError(new Error('generic')), false, 'Rejects generic Error');
assert.equal(isSignalError(null), false, 'Rejects null');
assert.equal(isSignalError(undefined), false, 'Rejects undefined');
assert.equal(isSignalError({ name: 'SignalError' }), false, 'Rejects object without code');

// 10. Contract: helper classifySignalError distinguishes UNKNOWN_SIGNAL and SIGNAL_CLOSED from generic errors
const createdUnk = createSignalError('UNKNOWN_SIGNAL', 'bad signal');
const createdClosed = createSignalError('SIGNAL_CLOSED', 'shut down');
assert.equal(classifySignalError(createdUnk), 'UNKNOWN_SIGNAL');
assert.equal(classifySignalError(createdClosed), 'SIGNAL_CLOSED');
assert.equal(classifySignalError(directErr), 'OTHER');
assert.equal(classifySignalError(new Error('standard')), 'OTHER');

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