on-finished 2.4.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/on-finished@2.4.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/on-finished@2.4.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:f0befe24570cade94b95d244cce277c99f75edc018acaf6fe272827acd829b80","constraints":{"executionContext":"node"},"contract":["onFinished(res, listener) executes callback when HTTP response completes and isFinished returns true","onFinished(req, listener) executes callback when HTTP request stream ends and isFinished returns true","onFinished(res, listener) on already-finished response executes listener asynchronously on next tick","onFinished(res, listener) executes listener with error when socket connection is destroyed or aborted"],"goal":"verify pkg:npm/on-finished@2.4.1","kind":"HOW","packages":["pkg:npm/on-finished@2.4.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/on-finished@2.4.1"],"schemaVersion":1,"verifierAdapter":"node-typescript@1"}

{
  "name": "csx-sample-on-finished",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "csx-sample-on-finished",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "on-finished": "2.4.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"
    },
    "node_modules/on-finished": {
      "version": "2.4.1",
      "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz",
      "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==",
      "license": "MIT",
      "dependencies": {
        "ee-first": "1.1.1"
      },
      "engines": {
        "node": ">= 0.8"
      }
    }
  }
}

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

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/on-finished@2.4.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/on-finished@2.4.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 http = require('http');
const onFinished = require('on-finished');

async function runTests() {
  // Test 1: Response finish notification and isFinished state
  await new Promise((resolve, reject) => {
    const server = http.createServer((req, res) => {
      assert.strictEqual(onFinished.isFinished(res), false, 'isFinished(res) should be false before end');

      let finishedFired = false;
      onFinished(res, (err, finishedRes) => {
        assert.ifError(err);
        assert.strictEqual(finishedRes, res, 'callback passes response object');
        assert.strictEqual(onFinished.isFinished(res), true, 'isFinished(res) should be true after finish');
        finishedFired = true;
      });

      res.writeHead(200, { 'Content-Type': 'text/plain' });
      res.end('ok');

      // Verify callback fired after end
      setImmediate(() => {
        assert.strictEqual(finishedFired, true, 'onFinished callback should have fired');
        server.close(() => resolve());
      });
    });

    server.listen(0, '127.0.0.1', () => {
      const port = server.address().port;
      http.get(`http://127.0.0.1:${port}`, (res) => {
        res.resume();
      }).on('error', reject);
    });
  });

  // Test 2: Request stream finish notification and isFinished state
  await new Promise((resolve, reject) => {
    const server = http.createServer((req, res) => {
      assert.strictEqual(onFinished.isFinished(req), false, 'isFinished(req) should be false initially');

      let reqFinished = false;
      onFinished(req, (err, finishedReq) => {
        assert.ifError(err);
        assert.strictEqual(finishedReq, req, 'callback passes request object');
        assert.strictEqual(onFinished.isFinished(req), true, 'isFinished(req) should be true when request ended');
        reqFinished = true;
      });

      req.on('data', () => {});
      req.on('end', () => {
        setImmediate(() => {
          assert.strictEqual(reqFinished, true, 'onFinished callback for req should have fired');
          res.end('done');
        });
      });
    });

    server.listen(0, '127.0.0.1', () => {
      const port = server.address().port;
      const clientReq = http.request({
        hostname: '127.0.0.1',
        port: port,
        method: 'POST',
        headers: { 'Content-Type': 'text/plain' }
      }, (res) => {
        res.resume();
        res.on('end', () => {
          server.close(() => resolve());
        });
      });
      clientReq.on('error', reject);
      clientReq.write('payload');
      clientReq.end();
    });
  });

  // Test 3: Already finished response triggers callback asynchronously
  await new Promise((resolve, reject) => {
    const server = http.createServer((req, res) => {
      res.end('immediate');
      setImmediate(() => {
        assert.strictEqual(onFinished.isFinished(res), true, 'isFinished must be true');
        let asyncFired = false;
        onFinished(res, (err, finishedRes) => {
          assert.ifError(err);
          assert.strictEqual(finishedRes, res);
          asyncFired = true;
        });
        assert.strictEqual(asyncFired, false, 'callback must be asynchronous');
        setImmediate(() => {
          assert.strictEqual(asyncFired, true, 'callback should fire on subsequent tick');
          server.close(() => resolve());
        });
      });
    });

    server.listen(0, '127.0.0.1', () => {
      const port = server.address().port;
      http.get(`http://127.0.0.1:${port}`, (res) => {
        res.resume();
      }).on('error', reject);
    });
  });

  // Test 4: Socket error / destruction invokes callback with error
  await new Promise((resolve, reject) => {
    const server = http.createServer((req, res) => {
      let errored = false;
      onFinished(res, (err) => {
        assert(err, 'error should be passed to listener when socket is abruptly destroyed');
        errored = true;
      });

      req.socket.destroy(new Error('abrupt connection reset'));

      setImmediate(() => {
        assert.strictEqual(errored, true, 'onFinished error callback should have fired');
        server.close(() => resolve());
      });
    });

    server.listen(0, '127.0.0.1', () => {
      const port = server.address().port;
      const req = http.get(`http://127.0.0.1:${port}`);
      req.on('error', () => {
        // Expected client-side error due to socket destruction
      });
    });
  });

  console.log('All on-finished contract assertions passed successfully.');
}

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