ip-address 10.7.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 pkg:npm/ip-address@10.7.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/ip-address@10.7.0
Demonstrate these symbols/APIs:
  - 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:f31caa37c5416831a50147fc5c45ca45cb10812a3fa2818fae1051447a3a2b93","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 with parseMessage highlighting invalid IPv6 syntax","Address4.fromAddressAndMask throws an instance of AddressError on non-contiguous subnet mask","safeParseIp helper returns parsed addresses for valid inputs and returns caught AddressError on invalid inputs"],"goal":"verify pkg:npm/ip-address@10.7.0","kind":"HOW","packages":["pkg:npm/ip-address@10.7.0"],"schemaVersion":1,"symbols":["AddressError"]},"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/ip-address@10.7.0"],"schemaVersion":1,"subject":"pkg:npm/ip-address@10.7.0","symbols":["AddressError"],"verifierAdapter":"node-typescript@1"}

import { Address4, Address6, AddressError } 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 parseMessage 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 };

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

{
  "name": "ip-address-error-sample",
  "version": "1.0.0",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "ip-address": "10.7.0"
  },
  "scripts": {
    "test": "node test/contract.mjs"
  }
}

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

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

// Contract 1: AddressError is an Error subclass with name property set to 'AddressError'
{
  const err = new AddressError('Invalid address');
  assert.equal(err instanceof Error, true);
  assert.equal(err instanceof AddressError, true);
  assert.equal(err.name, 'AddressError');
  assert.equal(err.message, 'Invalid address');
  assert.equal(err.parseMessage, undefined);
}

// Contract 2: AddressError constructor initializes message and optional parseMessage properties
{
  const parseMarkup = '2001<span class="parse-error">:::</span>1';
  const err = createAddressError('Address failed regex: :::', parseMarkup);
  assert.equal(err.name, 'AddressError');
  assert.equal(err.message, 'Address failed regex: :::');
  assert.equal(err.parseMessage, parseMarkup);
}

// Contract 3: Address4 constructor throws an instance of AddressError when given an invalid IPv4 address string
{
  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`
    );
  }
}

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

  // Specifically verify parseMessage highlights offending syntax
  try {
    new Address6('2001:::1');
    assert.fail('should have thrown');
  } catch (err) {
    assert.equal(err instanceof AddressError, true);
    assert.equal(err.parseMessage, '2001<span class="parse-error">:::</span>1');
  }
}

// Contract 5: Address4.fromAddressAndMask throws an instance of AddressError on non-contiguous subnet mask
{
  assert.throws(
    () => Address4.fromAddressAndMask('192.168.1.1', '255.0.255.0'),
    (err) => {
      return err instanceof AddressError && err.message === 'Invalid subnet mask.';
    }
  );

  // Valid contiguous mask succeeds
  const valid = Address4.fromAddressAndMask('192.168.1.1', '255.255.255.0');
  assert.equal(valid.subnetMask, 24);
}

// Contract 6: safeParseIp helper returns parsed addresses for valid inputs and returns caught AddressError on invalid inputs
{
  // Valid IPv4
  const v4Valid = safeParseIp('192.168.1.1', 'v4');
  assert.equal(v4Valid.ok, true);
  assert.equal(v4Valid.address.correctForm(), '192.168.1.1');

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

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

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

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

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

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

console.log('All contract assertions verified successfully.');