defer-to-connect 2.0.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/defer-to-connect@2.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/defer-to-connect@2.0.1

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:ca833fd5e2ed71521b26286ad5e8211aa1f49cf6a3f3dd1ba6994d08aa0125f7","contract":["deferToConnect attaches a connect listener that is invoked when a connecting socket connects","deferToConnect immediately invokes the connect listener when called on an already connected socket","deferToConnect invokes listeners.connect and listeners.close when passed a listeners object","deferToConnect immediately invokes listeners.close when called on an already destroyed socket","deferToConnect invokes secureConnect when attached to an encrypted TLS socket","waitForSocketConnection resolves when socket connection completes"],"goal":"verify pkg:npm/defer-to-connect@2.0.1","kind":"HOW","packages":["pkg:npm/defer-to-connect@2.0.1"],"schemaVersion":1},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/defer-to-connect@2.0.1"],"schemaVersion":1,"subject":"pkg:npm/defer-to-connect@2.0.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-defer-to-connect",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-defer-to-connect",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "defer-to-connect": "2.0.1"
      }
    },
    "node_modules/defer-to-connect": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/defer-to-connect/-/defer-to-connect-2.0.1.tgz",
      "integrity": "sha512-4tvttepXG1VaYGrRibk5EwJd1t4udunSOVMdLSAL6mId1ix438oPwPZMALY41FCijukO1L0twNcGsdzS7dHgDg==",
      "license": "MIT",
      "engines": {
        "node": ">=10"
      }
    }
  }
}

{
  "name": "sample-defer-to-connect",
  "version": "1.0.0",
  "private": true,
  "main": "src/index.js",
  "license": "MIT-0",
  "dependencies": {
    "defer-to-connect": "2.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/defer-to-connect@2.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/defer-to-connect@2.0.1"
  ]
}

const deferToConnect = require('defer-to-connect');

/**
 * Attaches a connection listener to a socket safely using defer-to-connect.
 * @param {import('net').Socket | import('tls').TLSSocket} socket
 * @param {Function | object} fnOrListeners
 */
function attachDeferToConnect(socket, fnOrListeners) {
  deferToConnect(socket, fnOrListeners);
}

/**
 * Returns a Promise that resolves when the socket is connected.
 * @param {import('net').Socket | import('tls').TLSSocket} socket
 * @returns {Promise<void>}
 */
function waitForSocketConnection(socket) {
  return new Promise((resolve) => {
    deferToConnect(socket, () => {
      resolve();
    });
  });
}

module.exports = {
  deferToConnect,
  attachDeferToConnect,
  waitForSocketConnection
};

import assert from 'node:assert/strict';
import net from 'node:net';
import { EventEmitter } from 'node:events';
import { createRequire } from 'node:module';

const require = createRequire(import.meta.url);
const {
  deferToConnect,
  attachDeferToConnect,
  waitForSocketConnection
} = require('../src/index.js');

// Helper to create test server
function createTestServer(onConnection) {
  const sockets = new Set();
  const server = net.createServer((socket) => {
    sockets.add(socket);
    socket.on('error', () => {});
    socket.on('close', () => sockets.delete(socket));
    if (onConnection) onConnection(socket);
  });
  server.on('error', () => {});
  return {
    server,
    async listen() {
      await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
      return server.address().port;
    },
    async close() {
      for (const s of sockets) {
        s.destroy();
      }
      await new Promise((resolve) => server.close(resolve));
    }
  };
}

// 1. deferToConnect attaches a connect listener that is invoked when a connecting socket connects
{
  const srv = createTestServer((s) => s.end());
  const port = await srv.listen();

  const client = net.createConnection(port, '127.0.0.1');
  client.on('error', () => {});
  assert.strictEqual(client.connecting, true, 'client should initially be in connecting state');

  let connected = false;
  deferToConnect(client, () => {
    connected = true;
  });

  await new Promise((resolve) => {
    client.once('connect', resolve);
  });

  assert.strictEqual(connected, true, 'deferToConnect callback should be called on connect');

  client.destroy();
  await srv.close();
}

// 2. deferToConnect immediately invokes the connect listener when called on an already connected socket
{
  const srv = createTestServer();
  const port = await srv.listen();

  const client = net.createConnection(port, '127.0.0.1');
  client.on('error', () => {});
  await new Promise((resolve) => {
    client.once('connect', resolve);
  });

  assert.strictEqual(client.connecting, false, 'client should not be connecting');
  assert.strictEqual(client.writable, true, 'client should be writable');

  let connectedImmediately = false;
  deferToConnect(client, () => {
    connectedImmediately = true;
  });

  assert.strictEqual(connectedImmediately, true, 'deferToConnect should invoke listener synchronously for connected socket');

  client.destroy();
  await srv.close();
}

// 3. deferToConnect invokes listeners.connect and listeners.close when passed a listeners object
{
  const srv = createTestServer();
  const port = await srv.listen();

  const client = net.createConnection(port, '127.0.0.1');
  client.on('error', () => {});
  let connectCalled = false;
  let closeCalled = false;
  let closeHadError = null;

  attachDeferToConnect(client, {
    connect: () => {
      connectCalled = true;
    },
    close: (hadError) => {
      closeCalled = true;
      closeHadError = hadError;
    }
  });

  await new Promise((resolve) => {
    client.once('connect', resolve);
  });
  assert.strictEqual(connectCalled, true, 'listeners.connect should be called');

  client.destroy();
  await new Promise((resolve) => {
    client.once('close', resolve);
  });

  assert.strictEqual(closeCalled, true, 'listeners.close should be called on socket close');
  assert.strictEqual(closeHadError, false, 'close hadError argument should be false');

  await srv.close();
}

// 4. deferToConnect immediately invokes listeners.close when called on an already destroyed socket
{
  const mockSocket = new EventEmitter();
  mockSocket.destroyed = true;
  mockSocket._hadError = false;

  let closeInvoked = false;
  let errorReceived = null;

  deferToConnect(mockSocket, {
    close: (hadError) => {
      closeInvoked = true;
      errorReceived = hadError;
    }
  });

  assert.strictEqual(closeInvoked, true, 'listeners.close should be invoked immediately on destroyed socket');
  assert.strictEqual(errorReceived, false, 'hadError should be passed correctly');
}

// 5. deferToConnect invokes secureConnect when attached to an encrypted TLS socket
{
  const mockTlsSocket = new EventEmitter();
  mockTlsSocket.encrypted = true;
  mockTlsSocket.connecting = true;
  mockTlsSocket.authorized = true;

  let connectFired = false;
  let secureConnectFired = false;

  deferToConnect(mockTlsSocket, {
    connect: () => {
      connectFired = true;
    },
    secureConnect: () => {
      secureConnectFired = true;
    }
  });

  mockTlsSocket.emit('connect');
  assert.strictEqual(connectFired, true, 'connect listener should fire');
  assert.strictEqual(secureConnectFired, true, 'secureConnect listener should fire when authorized is true');
}

// 6. waitForSocketConnection resolves when socket connection completes
{
  const srv = createTestServer((s) => s.end());
  const port = await srv.listen();

  const client = net.createConnection(port, '127.0.0.1');
  client.on('error', () => {});
  await waitForSocketConnection(client);

  assert.strictEqual(client.connecting, false, 'client should be connected after waitForSocketConnection');

  client.destroy();
  await srv.close();
}

console.log('Contract tests passed successfully.');