ip-address 10.1.0: Address4

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.Address4 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.Address4

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:986c7c875861dfb5a321c712da430d40b6c10905342210e40b4eff6f2f482f90","contract":["Address4.isValid validates valid IPv4 addresses and rejects invalid strings","Address4 constructor parses IPv4 address and CIDR subnet mask correctly","Address4 calculates startAddress and endAddress for a given subnet","Address4.isInSubnet determines whether an address belongs to a specified subnet","Address4 bigInt and fromBigInt convert IPv4 addresses to and from BigInt representations","Address4 fromHex and toHex convert IPv4 addresses to and from hex representations","Address4 fromInteger creates an Address4 instance from an integer","Address4 correctForm returns the normalized dotted-decimal IP address string","Address4 throws AddressError when instantiated with an invalid IP address string"],"goal":"verify ip-address.Address4 in pkg:npm/ip-address@10.1.0","kind":"HOW","packages":["pkg:npm/ip-address@10.1.0"],"schemaVersion":1,"symbols":["ip-address.Address4"]},"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.1.0"],"schemaVersion":1,"subject":"pkg:npm/ip-address@10.1.0","symbols":["ip-address.Address4"],"verifierAdapter":"node-typescript@1"}

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

export { Address4, AddressError };

export function parseIPv4(ip) {
  return new Address4(ip);
}

export function isValidIPv4(ip) {
  return Address4.isValid(ip);
}

{
  "name": "sample-ip-address",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-ip-address",
      "version": "1.0.0",
      "license": "MIT-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",
  "version": "1.0.0",
  "type": "module",
  "main": "index.mjs",
  "license": "MIT-0",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "ip-address": "10.1.0"
  }
}

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

import assert from 'node:assert/strict';
import { Address4, AddressError } from 'ip-address';
import { parseIPv4, isValidIPv4 } from '../index.mjs';

// 1. Address4.isValid validates valid IPv4 addresses and rejects invalid strings
assert.equal(Address4.isValid('192.168.1.100'), true);
assert.equal(Address4.isValid('10.0.0.1'), true);
assert.equal(Address4.isValid('127.0.0.1'), true);
assert.equal(Address4.isValid('999.1.1.1'), false);
assert.equal(Address4.isValid('256.0.0.1'), false);
assert.equal(Address4.isValid('invalid-ip'), false);
assert.equal(Address4.isValid(''), false);
assert.equal(isValidIPv4('192.168.1.100'), true);
assert.equal(isValidIPv4('invalid'), false);

// 2. Address4 constructor parses IPv4 address and CIDR subnet mask correctly
const ipv4 = new Address4('192.168.1.100/24');
assert.equal(ipv4.address, '192.168.1.100/24');
assert.equal(ipv4.subnet, '/24');
assert.equal(ipv4.subnetMask, 24);
assert.deepEqual(ipv4.parsedAddress, ['192', '168', '1', '100']);
const helperIpv4 = parseIPv4('192.168.1.100/24');
assert.equal(helperIpv4.address, '192.168.1.100/24');

// 3. Address4 calculates startAddress and endAddress for a given subnet
assert.equal(ipv4.startAddress().correctForm(), '192.168.1.0');
assert.equal(ipv4.endAddress().correctForm(), '192.168.1.255');
assert.equal(ipv4.startAddressExclusive().correctForm(), '192.168.1.1');
assert.equal(ipv4.endAddressExclusive().correctForm(), '192.168.1.254');

// 4. Address4.isInSubnet determines whether an address belongs to a specified subnet
const member4 = new Address4('192.168.1.50');
const nonMember4 = new Address4('192.168.2.1');
assert.equal(member4.isInSubnet(ipv4), true);
assert.equal(nonMember4.isInSubnet(ipv4), false);

// 5. Address4 bigInt and fromBigInt convert IPv4 addresses to and from BigInt representations
const v4BigInt = ipv4.bigInt();
assert.equal(typeof v4BigInt, 'bigint');
assert.equal(Address4.fromBigInt(v4BigInt).correctForm(), '192.168.1.100');

// 6. Address4 fromHex and toHex convert IPv4 addresses to and from hex representations
assert.equal(ipv4.toHex(), 'c0:a8:01:64');
assert.equal(Address4.fromHex('c0:a8:01:64').correctForm(), '192.168.1.100');

// 7. Address4 fromInteger creates an Address4 instance from an integer
assert.equal(Address4.fromInteger(0x7f000001).correctForm(), '127.0.0.1');

// 8. Address4 correctForm returns the normalized dotted-decimal IP address string
const addrWithSubnet = new Address4('192.168.1.1/24');
assert.equal(addrWithSubnet.correctForm(), '192.168.1.1');
assert.equal(addrWithSubnet.isCorrect(), true);
const plainAddr = new Address4('10.0.0.1');
assert.equal(plainAddr.correctForm(), '10.0.0.1');
const leadingZeroAddr = new Address4('192.168.001.001');
assert.equal(leadingZeroAddr.isCorrect(), false);
assert.equal(leadingZeroAddr.correctForm(), '192.168.1.1');

// 9. Address4 throws AddressError when instantiated with an invalid IP address string
assert.throws(
  () => new Address4('not-an-ip'),
  (err) => {
    return err instanceof AddressError || err.name === 'AddressError' || /Invalid/i.test(err.message);
  }
);
assert.throws(
  () => new Address4('300.1.1.1'),
  (err) => {
    return err instanceof AddressError || err.name === 'AddressError' || /Invalid/i.test(err.message);
  }
);
assert.throws(
  () => new Address4('192.168.1.1.1'),
  (err) => {
    return err instanceof AddressError || err.name === 'AddressError' || /Invalid/i.test(err.message);
  }
);

console.log('All ip-address.Address4 contract assertions passed.');