ee-first 1.1.1

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/ee-first@1.1.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ee-first@1.1.1
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:6c0343e4d57b2fcbd83fdcd4c2d5b68133f3069ee97d2423c3f8600cd1a0c22a","constraints":{"executionContext":"node"},"contract":["first(pairs, listener) invokes listener with emitted event name, emitter, and arguments when the first event fires","first(pairs, listener) automatically cleans up all event listeners across all tracked emitters once an event has fired","first(pairs, listener) invokes listener with error when an error event fires on any emitter","thunk.cancel() removes all attached listeners from all emitters and prevents callback execution","first(pairs) without initial callback returns a thunk function to attach a listener"],"goal":"verify pkg:npm/ee-first@1.1.1","kind":"HOW","packages":["pkg:npm/ee-first@1.1.1"],"schemaVersion":1},"contractCommand":["node","test/contract.js"],"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/ee-first@1.1.1"],"schemaVersion":1,"verifierAdapter":"node-typescript@1"}

{
  "name": "csx-sample-ee-first",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "csx-sample-ee-first",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "ee-first": "1.1.1"
      }
    },
    "node_modules/ee-first": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz",
      "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==",
      "license": "MIT"
    }
  }
}

{
  "name": "csx-sample-ee-first",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification for ee-first",
  "main": "test/contract.js",
  "scripts": {
    "test": "node test/contract.js"
  },
  "dependencies": {
    "ee-first": "1.1.1"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/ee-first@1.1.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ee-first@1.1.1"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

const assert = require('assert');
const { EventEmitter } = require('events');
const first = require('ee-first');

async function runTests() {
  // Test 1: first(pairs, listener) invokes listener with emitted event name, emitter, and arguments when the first event fires
  await new Promise((resolve, reject) => {
    const ee1 = new EventEmitter();
    const ee2 = new EventEmitter();

    let called = false;
    first([
      [ee1, 'close', 'finish'],
      [ee2, 'data', 'end']
    ], (err, ee, event, args) => {
      try {
        assert.ifError(err);
        assert.strictEqual(ee, ee2, 'expected ee2 to be the emitter');
        assert.strictEqual(event, 'data', 'expected event to be data');
        assert.deepStrictEqual(args, ['payload', 123], 'expected args to match emitted values');
        called = true;
        resolve();
      } catch (e) {
        reject(e);
      }
    });

    ee2.emit('data', 'payload', 123);
    assert.strictEqual(called, true, 'callback should have been called synchronously on emit');
  });

  // Test 2: first(pairs, listener) automatically cleans up all event listeners across all tracked emitters once an event has fired
  await new Promise((resolve, reject) => {
    const ee1 = new EventEmitter();
    const ee2 = new EventEmitter();

    let callCount = 0;
    first([
      [ee1, 'a', 'b'],
      [ee2, 'c', 'd']
    ], (err, ee, event, args) => {
      callCount++;
    });

    // Before firing, listeners should be attached
    assert.strictEqual(ee1.listenerCount('a'), 1);
    assert.strictEqual(ee1.listenerCount('b'), 1);
    assert.strictEqual(ee2.listenerCount('c'), 1);
    assert.strictEqual(ee2.listenerCount('d'), 1);

    // Fire first event
    ee1.emit('a');
    assert.strictEqual(callCount, 1, 'callback should have fired once');

    // After firing, all listeners must be removed
    assert.strictEqual(ee1.listenerCount('a'), 0, 'ee1 event a listener removed');
    assert.strictEqual(ee1.listenerCount('b'), 0, 'ee1 event b listener removed');
    assert.strictEqual(ee2.listenerCount('c'), 0, 'ee2 event c listener removed');
    assert.strictEqual(ee2.listenerCount('d'), 0, 'ee2 event d listener removed');

    // Subsequent emits should not trigger callback
    ee1.emit('b');
    ee2.emit('c');
    ee2.emit('d');
    assert.strictEqual(callCount, 1, 'callback should not fire again');
    resolve();
  });

  // Test 3: first(pairs, listener) invokes listener with error when an error event fires on any emitter
  await new Promise((resolve, reject) => {
    const ee1 = new EventEmitter();
    const ee2 = new EventEmitter();
    const testError = new Error('simulated failure');

    let errorFired = false;
    first([
      [ee1, 'finish'],
      [ee2, 'error', 'end']
    ], (err, ee, event, args) => {
      try {
        assert.strictEqual(err, testError, 'expected error to match emitted error');
        assert.strictEqual(ee, ee2, 'expected ee2 as emitting emitter');
        assert.strictEqual(event, 'error', 'expected event name error');
        assert.strictEqual(args[0], testError, 'expected args[0] to be testError');
        errorFired = true;
        resolve();
      } catch (e) {
        reject(e);
      }
    });

    ee2.emit('error', testError);
    assert.strictEqual(errorFired, true, 'error callback should fire synchronously');
    assert.strictEqual(ee1.listenerCount('finish'), 0, 'listeners should be cleaned up on error');
    assert.strictEqual(ee2.listenerCount('error'), 0, 'error listener should be cleaned up');
  });

  // Test 4: thunk.cancel() removes all attached listeners from all emitters and prevents callback execution
  await new Promise((resolve, reject) => {
    const ee1 = new EventEmitter();
    const ee2 = new EventEmitter();

    let callbackTriggered = false;
    const thunk = first([
      [ee1, 'open', 'close'],
      [ee2, 'ping', 'pong']
    ], (err, ee, event, args) => {
      callbackTriggered = true;
    });

    assert.strictEqual(ee1.listenerCount('open'), 1);
    assert.strictEqual(ee2.listenerCount('ping'), 1);

    // Cancel listening
    thunk.cancel();

    assert.strictEqual(ee1.listenerCount('open'), 0, 'listener should be removed after cancel');
    assert.strictEqual(ee1.listenerCount('close'), 0, 'listener should be removed after cancel');
    assert.strictEqual(ee2.listenerCount('ping'), 0, 'listener should be removed after cancel');
    assert.strictEqual(ee2.listenerCount('pong'), 0, 'listener should be removed after cancel');

    // Emitting events now should not invoke callback
    ee1.emit('open');
    ee2.emit('ping');
    assert.strictEqual(callbackTriggered, false, 'callback should not run after cancel');
    resolve();
  });

  // Test 5: first(pairs) without initial callback returns a thunk function to attach a listener
  await new Promise((resolve, reject) => {
    const ee = new EventEmitter();
    const thunk = first([
      [ee, 'custom']
    ]);

    let thunkFired = false;
    thunk((err, emitter, event, args) => {
      try {
        assert.ifError(err);
        assert.strictEqual(emitter, ee);
        assert.strictEqual(event, 'custom');
        assert.deepStrictEqual(args, ['value1', 'value2']);
        thunkFired = true;
        resolve();
      } catch (e) {
        reject(e);
      }
    });

    ee.emit('custom', 'value1', 'value2');
    assert.strictEqual(thunkFired, true, 'thunk callback should fire on emit');
  });

  console.log('All ee-first contract assertions passed successfully.');
}

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