ip-address 10.1.0: AddressError

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 ip-address.AddressError in pkg:npm/ip-address@10.1.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ip-address@10.1.0
Demonstrate these symbols/APIs:
  - ip-address.AddressError

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:729e84d9c9a932ad110aaff4b3b5c98784e85f623aa47a17002adb4c6cf4d429","contract":["AddressError is an Error subclass with name property set to 'AddressError'","AddressError constructor initializes message and optional parseMessage properties","Address4 constructor throws an instance of AddressError when given an invalid IPv4 address string","Address6 constructor throws an instance of AddressError when given an invalid IPv6 address string","safeParseIp helper returns parsed addresses for valid inputs and returns caught AddressError on invalid inputs"],"goal":"verify ip-address.AddressError in pkg:npm/ip-address@10.1.0","kind":"HOW","packages":["pkg:npm/ip-address@10.1.0"],"schemaVersion":1,"symbols":["ip-address.AddressError"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","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/ip-address@10.1.0"],"schemaVersion":1,"subject":"pkg:npm/ip-address@10.1.0","symbols":["ip-address.AddressError"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-ip-address-error",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-ip-address-error",
      "version": "1.0.0",
      "dependencies": {
        "ip-address": "10.1.0"
      }
    },
    "node_modules/ip-address": {
      "version": "10.1.0",
      "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz",
      "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==",
      "license": "MIT",
      "engines": {
        "node": ">= 12"
      }
    }
  }
}

{
  "name": "sample-ip-address-error",
  "version": "1.0.0",
  "type": "module",
  "dependencies": {
    "ip-address": "10.1.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify ip-address.AddressError in pkg:npm/ip-address@10.1.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/ip-address@10.1.0"
  ],
  "symbols": [
    "ip-address.AddressError"
  ]
}

import { AddressError, Address4, Address6 } from 'ip-address';

/**
 * Safely parses an IP address (IPv4 or IPv6), returning the parsed instance or capturing AddressError.
 *
 * @param {string} address - The IP address string to parse.
 * @param {'v4' | 'v6' | 'auto'} [version='auto'] - Expected IP version format.
 * @returns {{ ok: true, address: Address4 | Address6 } | { ok: false, error: AddressError }}
 */
export function safeParseIp(address, version = 'auto') {
  try {
    if (version === 'v4') {
      return { ok: true, address: new Address4(address) };
    }
    if (version === 'v6') {
      return { ok: true, address: new Address6(address) };
    }
    try {
      return { ok: true, address: new Address4(address) };
    } catch {
      return { ok: true, address: new Address6(address) };
    }
  } catch (err) {
    if (err instanceof AddressError) {
      return { ok: false, error: err };
    }
    throw err;
  }
}

/**
 * Creates a new AddressError with a descriptive message and optional parse context.
 *
 * @param {string} message - Descriptive error message.
 * @param {string} [parseMessage] - Detailed parse context message.
 * @returns {AddressError}
 */
export function createAddressError(message, parseMessage) {
  return new AddressError(message, parseMessage);
}

export { AddressError, Address4, Address6 };

import assert from 'node:assert';
import {
  AddressError,
  Address4,
  Address6,
  safeParseIp,
  createAddressError,
} from '../src/index.mjs';

// 1. AddressError class inheritance and properties
{
  const err = new AddressError('Invalid address');
  assert.strictEqual(err instanceof Error, true, 'AddressError must inherit from Error');
  assert.strictEqual(err instanceof AddressError, true, 'err must be instance of AddressError');
  assert.strictEqual(err.name, 'AddressError', 'name property must be AddressError');
  assert.strictEqual(err.message, 'Invalid address', 'message must match constructor argument');
  assert.strictEqual(err.parseMessage, undefined, 'parseMessage should be undefined when omitted');
}

// 2. AddressError constructor with parseMessage
{
  const parseInfo = 'parse context information';
  const err = createAddressError('Parsing failed', parseInfo);
  assert.strictEqual(err.name, 'AddressError');
  assert.strictEqual(err.message, 'Parsing failed');
  assert.strictEqual(err.parseMessage, parseInfo);
}

// 3. Address4 throws AddressError on invalid IPv4 addresses
{
  const invalidV4Inputs = ['invalid-ip', '256.0.0.1', '1.2.3', '1.2.3.4.5', '1.2.3.999'];
  for (const input of invalidV4Inputs) {
    assert.throws(
      () => new Address4(input),
      (err) => {
        return err instanceof AddressError && err.name === 'AddressError';
      },
      `Address4("${input}") must throw AddressError`
    );
  }
}

// 4. Address6 throws AddressError on invalid IPv6 addresses
{
  const invalidV6Inputs = ['not-an-ipv6', '2001:::1', '12345::1', 'fe80::1::2', '::ffff:999.999.999.999'];
  for (const input of invalidV6Inputs) {
    assert.throws(
      () => new Address6(input),
      (err) => {
        return err instanceof AddressError && err.name === 'AddressError';
      },
      `Address6("${input}") must throw AddressError`
    );
  }
}

// 5. safeParseIp handling of valid and invalid addresses
{
  // Valid IPv4
  const v4Valid = safeParseIp('192.168.1.1', 'v4');
  assert.strictEqual(v4Valid.ok, true);
  assert.strictEqual(v4Valid.address.correctForm(), '192.168.1.1');

  // Invalid IPv4
  const v4Invalid = safeParseIp('999.999.999.999', 'v4');
  assert.strictEqual(v4Invalid.ok, false);
  assert.strictEqual(v4Invalid.error instanceof AddressError, true);
  assert.strictEqual(v4Invalid.error.name, 'AddressError');

  // Valid IPv6
  const v6Valid = safeParseIp('2001:db8::1', 'v6');
  assert.strictEqual(v6Valid.ok, true);
  assert.strictEqual(v6Valid.address.correctForm(), '2001:db8::1');

  // Invalid IPv6
  const v6Invalid = safeParseIp('invalid-ipv6-string', 'v6');
  assert.strictEqual(v6Invalid.ok, false);
  assert.strictEqual(v6Invalid.error instanceof AddressError, true);
  assert.strictEqual(v6Invalid.error.name, 'AddressError');

  // Auto detection valid
  const autoV4 = safeParseIp('10.0.0.1');
  assert.strictEqual(autoV4.ok, true);
  assert.strictEqual(autoV4.address.correctForm(), '10.0.0.1');

  const autoV6 = safeParseIp('::1');
  assert.strictEqual(autoV6.ok, true);
  assert.strictEqual(autoV6.address.correctForm(), '::1');

  // Auto detection invalid
  const autoInvalid = safeParseIp('completely-invalid-address');
  assert.strictEqual(autoInvalid.ok, false);
  assert.strictEqual(autoInvalid.error instanceof AddressError, true);
}

console.log('Contract test passed.');