Using ipv6-parse in TypeScript

Install and initialize

npm install ipv6-parse
npm install --save-dev typescript

Save this as example.ts. Import IPv6Address as a type, and obtain runtime classes from createParser() after WebAssembly has loaded.

import { createParser, type IPv6Address } from 'ipv6-parse';

function describe(addr: IPv6Address): string {
    const port = addr.port === null ? 'no port' : `port ${addr.port}`;
    const prefix = addr.mask === null ? 'no prefix length' : `/${addr.mask}`;
    return `${addr.formatted} (${port}, ${prefix})`;
}

async function main(): Promise<void> {
    const { parser } = await createParser();
    const addr = parser.parse('[fe80::7/64%eth0]:8080');
    console.log(describe(addr));
}

main().catch(console.error);

For a CommonJS Node.js project, compile and run:

npx tsc example.ts --strict --target ES2020 --module commonjs --skipLibCheck
node example.js

--strict checks application types, including nullable fields. --skipLibCheck skips checking the package's declaration files themselves; the current declarations contain conflicts that otherwise prevent compilation.

Narrow optional fields before using them

port and mask have type number | null; zone has type string | null. An explicit null check preserves valid zero values. Checking hasPort alone does not narrow the TypeScript type of port.

import { createParser } from 'ipv6-parse';

async function main(): Promise<void> {
    const { parser } = await createParser();
    const addr = parser.tryParse('[::1]:0');
    if (addr === null) {
        console.log('Invalid address');
        return;
    }
    if (addr.port !== null) {
        console.log(addr.port.toFixed(0)); // "0"
    }
    if (addr.zone !== null) {
        console.log(addr.zone);
    }
}

main().catch(console.error);

tryParse() returns IPv6Address | null. The package-level tryParse() returns Promise<IPv6Address | null>; await it before narrowing.

Narrow a caught error

Under strict checking, a caught value is unknown. Check its class before reading parser fields.

import { createParser } from 'ipv6-parse';

async function main(): Promise<void> {
    const { parser, IPv6ParseError } = await createParser();
    try {
        parser.parse('2001:gggg::7');
    } catch (error: unknown) {
        if (error instanceof IPv6ParseError) {
            console.error(error.message, error.input);
        } else {
            throw error;
        }
    }
}

main().catch(console.error);

Use typed comparison options

import { createParser, type ComparisonOptions } from 'ipv6-parse';

async function main(): Promise<void> {
    const { parser } = await createParser();
    const options: ComparisonOptions = { ignorePort: true };
    console.log(parser.equals('[::1]:80', '[::1]:443', options)); // true
}

main().catch(console.error);

The current npm declarations lag behind the runtime in a few places. ignorePort and ignoreMask work in both. The declared ignoreZone does not control runtime behavior: zones are always excluded. The runtime's ignoreFormat option and detailed error properties are not currently declared in the npm types. See the JavaScript comparison guide for behavior.

TypeScript in the browser

Compile TypeScript to JavaScript and use the browser loading sequence. The browser wrapper has its own declarations in docs/ipv6-parse-api.d.ts. Types do not load WebAssembly: wait for createIPv6Module() before constructing a parser.

For the exact declarations, see the npm types and browser types.