bare-signals 5.0.0: prototype

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

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:cf6fb707d76df35c100e0c44876648d4a629d443bea393e0de9a59815b0cc3b4","contract":["package manifest exports Signal class extending EventEmitter and defines exports in bare-signals@5.0.0","TypeScript definitions in index.d.ts declare Signal interface extending EventEmitter with prototype methods start, stop, ref, unref, and close","Signal.prototype inherits from EventEmitter.prototype establishing the prototype hierarchy","Signal.prototype exposes own methods start, stop, ref, unref, close, _onsignal, and _onclose","Signal.prototype.start initiates signal listening via binding handle and returns the instance for chaining","Signal.prototype.stop halts signal listening via binding handle and returns the instance for chaining","Signal.prototype.ref and unref control event loop reference tracking on the binding handle","Signal.prototype.close initiates teardown, returns a Promise resolving on close event, and is idempotent","Signal.prototype.start throws SIGNAL_CLOSED error when invoked after close has been called","Signal.prototype._onsignal emits signal event with the configured signum to listeners registered on the prototype","helper functions inspect and validate Signal prototype chain and method presence"],"goal":"verify bare-signals.prototype in pkg:npm/bare-signals@5.0.0","kind":"HOW","packages":["pkg:npm/bare-signals@5.0.0"],"schemaVersion":1,"symbols":["bare-signals.prototype"]},"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.prototype"],"verifierAdapter":"node-typescript@1"}

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

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

import { createRequire } from 'node:module';

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

/**
 * Returns list of method names defined directly on the Signal prototype.
 *
 * @param {Function} SignalClass
 * @returns {string[]}
 */
export function getSignalPrototypeMethods(SignalClass) {
  if (!SignalClass || !SignalClass.prototype) return [];
  return Object.getOwnPropertyNames(SignalClass.prototype).filter(
    (prop) => typeof SignalClass.prototype[prop] === 'function' && prop !== 'constructor'
  );
}

/**
 * Checks whether the Signal prototype defines a specific method.
 *
 * @param {Function} SignalClass
 * @param {string} methodName
 * @returns {boolean}
 */
export function hasPrototypeMethod(SignalClass, methodName) {
  if (!SignalClass || !SignalClass.prototype) return false;
  return typeof SignalClass.prototype[methodName] === 'function';
}

/**
 * Validates that an instance inherits from Signal.prototype.
 *
 * @param {object} instance
 * @param {Function} SignalClass
 * @returns {boolean}
 */
export function isSignalInstance(instance, SignalClass) {
  if (!instance || !SignalClass || !SignalClass.prototype) return false;
  return instance instanceof SignalClass && Object.getPrototypeOf(instance) === SignalClass.prototype;
}

/**
 * Checks whether Signal.prototype inherits from EventEmitter.prototype.
 *
 * @param {Function} SignalClass
 * @param {Function} EventEmitterClass
 * @returns {boolean}
 */
export function inheritsFromEventEmitter(SignalClass, EventEmitterClass) {
  if (!SignalClass || !SignalClass.prototype || !EventEmitterClass || !EventEmitterClass.prototype) {
    return false;
  }
  return Object.getPrototypeOf(SignalClass.prototype) === EventEmitterClass.prototype;
}

import assert from 'node:assert/strict';
import { createRequire } from 'node:module';
import fs from 'node:fs';
import path from 'node:path';
import EventEmitter from 'bare-events';
import {
  getSignalPrototypeMethods,
  hasPrototypeMethod,
  isSignalInstance,
  inheritsFromEventEmitter,
} from '../src/index.mjs';

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

// 1. Resolve package manifest and verify package structure
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.equal(pkg.license, 'Apache-2.0', 'Package license must be Apache-2.0');
assert.equal(pkg.addon, true, 'Package must be marked as addon');
assert.equal(pkg.engines?.bare, '>=1.7.0', 'Package must specify Bare engine requirement');

assert.ok(pkg.exports, 'Package must define exports map');
assert.equal(pkg.exports['.'].types, './index.d.ts', 'Root export must specify index.d.ts types');
assert.equal(pkg.exports['.'].default, './index.js', 'Root export must specify index.js default');
assert.equal(pkg.exports['./errors'], './lib/errors.js', 'Errors export must specify lib/errors.js');
assert.equal(pkg.exports['./emitter'], './lib/emitter.js', 'Emitter export must specify lib/emitter.js');

const pkgDir = path.dirname(pkgPath);

// 2. Verify TypeScript type definitions in index.d.ts
const indexDts = fs.readFileSync(path.join(pkgDir, 'index.d.ts'), 'utf8');
assert.ok(indexDts.includes("import EventEmitter from 'bare-events'"), 'index.d.ts must import EventEmitter');
assert.ok(indexDts.includes('interface Signal extends EventEmitter'), 'index.d.ts must declare Signal extending EventEmitter');
assert.ok(indexDts.includes('start(): this'), 'Signal interface must declare start(): this');
assert.ok(indexDts.includes('stop(): this'), 'Signal interface must declare stop(): this');
assert.ok(indexDts.includes('ref(): this'), 'Signal interface must declare ref(): this');
assert.ok(indexDts.includes('unref(): this'), 'Signal interface must declare unref(): this');
assert.ok(indexDts.includes('close(): Promise<void>'), 'Signal interface must declare close(): Promise<void>');
assert.ok(indexDts.includes('declare class Signal'), 'index.d.ts must declare Signal class');
assert.ok(indexDts.includes('export = Signal'), 'index.d.ts must export Signal');

// 3. Mock binding to load bare-signals in Node offline runtime
const bindingPath = path.join(pkgDir, 'binding.js');
const mockSignals = {
  SIGHUP: 1,
  SIGINT: 2,
  SIGQUIT: 3,
  SIGKILL: 9,
  SIGUSR1: 10,
  SIGUSR2: 12,
  SIGTERM: 15,
};

const calls = [];
let nextHandleId = 1;
const handles = new Map();

require.cache[bindingPath] = {
  id: bindingPath,
  filename: bindingPath,
  loaded: true,
  exports: {
    signals: mockSignals,
    init: (ctx, onsignal, onclose) => {
      const handle = { id: nextHandleId++, ctx, onsignal, onclose, active: false, refed: true };
      handles.set(handle.id, handle);
      calls.push({ op: 'init', handleId: handle.id });
      return handle;
    },
    start: (handle, signum) => {
      calls.push({ op: 'start', handleId: handle.id, signum });
      handle.active = true;
    },
    stop: (handle) => {
      calls.push({ op: 'stop', handleId: handle.id });
      handle.active = false;
    },
    ref: (handle) => {
      calls.push({ op: 'ref', handleId: handle.id });
      handle.refed = true;
    },
    unref: (handle) => {
      calls.push({ op: 'unref', handleId: handle.id });
      handle.refed = false;
    },
    close: (handle) => {
      calls.push({ op: 'close', handleId: handle.id });
      setImmediate(() => {
        handle.onclose.call(handle.ctx);
      });
    },
  },
};

const Signal = require('bare-signals');

// 4. Verify prototype hierarchy and properties
assert.equal(typeof Signal, 'function', 'bare-signals export must be a constructor function');
assert.ok(Signal.prototype, 'Signal must have a prototype');
assert.equal(Signal.prototype.constructor, Signal, 'Signal.prototype.constructor must point back to Signal');

// Check prototype inheritance from EventEmitter
assert.equal(
  Object.getPrototypeOf(Signal.prototype),
  EventEmitter.prototype,
  'Signal.prototype must directly inherit from EventEmitter.prototype'
);
assert.ok(inheritsFromEventEmitter(Signal, EventEmitter), 'helper inheritsFromEventEmitter returns true');

// Verify prototype methods exist directly on Signal.prototype
const expectedMethods = ['start', 'stop', 'ref', 'unref', 'close', '_onsignal', '_onclose'];
const ownPrototypeMethods = getSignalPrototypeMethods(Signal);
for (const method of expectedMethods) {
  assert.ok(hasPrototypeMethod(Signal, method), `Signal.prototype must have method ${method}`);
  assert.equal(typeof Signal.prototype[method], 'function', `${method} on Signal.prototype must be a function`);
  assert.ok(ownPrototypeMethods.includes(method), `getSignalPrototypeMethods must include ${method}`);
}

// 5. Test prototype method execution on Signal instances
const sig = new Signal('SIGINT');
assert.ok(isSignalInstance(sig, Signal), 'sig must be instance of Signal with correct prototype');
assert.equal(Object.getPrototypeOf(sig), Signal.prototype, 'Object.getPrototypeOf(sig) must be Signal.prototype');
assert.equal(sig._signum, 2, 'Signal constructor resolves SIGINT to signum 2');

// Test start() chaining and binding interaction
const startResult = sig.start();
assert.equal(startResult, sig, 'start() must return this for method chaining');
assert.equal(calls[calls.length - 1].op, 'start', 'start() invokes binding.start');
assert.equal(calls[calls.length - 1].signum, 2, 'start() passes resolved signum');

// Test stop() chaining and binding interaction
const stopResult = sig.stop();
assert.equal(stopResult, sig, 'stop() must return this for method chaining');
assert.equal(calls[calls.length - 1].op, 'stop', 'stop() invokes binding.stop');

// Test ref() and unref() chaining
const unrefResult = sig.unref();
assert.equal(unrefResult, sig, 'unref() must return this for method chaining');
assert.equal(calls[calls.length - 1].op, 'unref', 'unref() invokes binding.unref');

const refResult = sig.ref();
assert.equal(refResult, sig, 'ref() must return this for method chaining');
assert.equal(calls[calls.length - 1].op, 'ref', 'ref() invokes binding.ref');

// 6. Test event emission through prototype methods and EventEmitter inheritance
let signalReceived = null;
sig.on('signal', (signum) => {
  signalReceived = signum;
});
sig._onsignal();
assert.equal(signalReceived, 2, '_onsignal() must emit "signal" event with signum');

// 7. Test close() lifecycle and post-close method behaviors on prototype
let closeFired = false;
sig.on('close', () => {
  closeFired = true;
});

const closePromise1 = sig.close();
assert.ok(closePromise1 instanceof Promise, 'close() must return a Promise');

// Idempotent close(): calling close again returns identical Promise
const closePromise2 = sig.close();
assert.equal(closePromise1, closePromise2, 'Subsequent close() calls must return the same Promise');

await closePromise1;
assert.equal(closeFired, true, 'close event must fire upon handle closing');
assert.equal(sig._handle, null, '_handle must be null after close');

// Post-close method behaviors
assert.throws(
  () => sig.start(),
  (err) => err.name === 'SignalError' && err.code === 'SIGNAL_CLOSED',
  'start() on closed signal must throw SIGNAL_CLOSED error'
);

// stop, ref, unref on closed signal should safely return this without throwing
assert.equal(sig.stop(), sig, 'stop() on closed signal safely returns this');
assert.equal(sig.ref(), sig, 'ref() on closed signal safely returns this');
assert.equal(sig.unref(), sig, 'unref() on closed signal safely returns this');

// 8. Verify native C binding source has corresponding functions
const bindingC = fs.readFileSync(path.join(pkgDir, 'binding.c'), 'utf8');
assert.ok(bindingC.includes('bare_signals_start'), 'binding.c must implement bare_signals_start');
assert.ok(bindingC.includes('bare_signals_stop'), 'binding.c must implement bare_signals_stop');
assert.ok(bindingC.includes('bare_signals_ref'), 'binding.c must implement bare_signals_ref');
assert.ok(bindingC.includes('bare_signals_unref'), 'binding.c must implement bare_signals_unref');
assert.ok(bindingC.includes('bare_signals_close'), 'binding.c must implement bare_signals_close');

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