idn-hostname

Portable verification

This patch restores executable verification for the Unicode 17 release line through shared public workspace data.

• Adds the generic, version-aware node:test dispatcher and npm test entry point.
• Runs 122 eligible package fixtures across the Unicode 15.1, 16, and 17 delta layers.
• Restores the authoritative Unicode 17.0.0 IdnaTestV2.txt concern with 6,202 applicable nontransitional vectors.
• Exercises both isIdnHostname and idnHostname, including exact expected ToASCII output for valid vectors.
• Keeps explicit conformance concerns exact-scoped while numeric callback fixtures accumulate from compatible older layers.

Benchmarks

• Adds npm run benchmark with isolated package loading and five function scenarios.
• Measures ASCII and internationalized validation and conversion plus UTS #46 mapping.
• Reports five initial calls, warmed latency statistics, integer throughput, workload counts, arguments, and environment metadata.
• Supports quick, JSON, and direct custom-iteration modes.

Runtime and CI

• Declares Node.js >=24.13.1 <25 || >=26.0.0.
• Node.js 24.13.1 is the first LTS release with ICU 78.2 and Unicode 17 data; Node.js 25 is excluded because it uses ICU 77.1.
• Adds a six-job CI matrix covering Node.js 24.13.1 and 26 on Ubuntu, Windows, and macOS.
• Materializes public tests and the gh-workspace-data v0.4.1 runtime helper explicitly.

Compatibility

There are no runtime API or validator behavior changes. This package remains on the Unicode 17 data line.

Published on npm as latest.

Performance

Add a validated fast path for non-reserved ASCII LDH hostnames. Hostnames whose labels contain only ASCII letters, digits, and internal hyphens, satisfy the 63-character label and 253-character presentation limits, and do not contain -- in positions 3 and 4 now avoid Unicode mapping, Punycode, contextual, and bidi validation.

Reserved labels, including xn-- A-label candidates, continue through the complete IDNA pipeline. idnHostname continues to apply UTS #46 mapping when producing output, including lowercase conversion of uppercase ASCII input.

On Node.js 24.20.0, the fast path validated the representative 86-character ASCII hostnames at approximately 1.14 million validations per second on the benchmark system.

Verification

• All 122 package tests passed.
• All 6,190 applicable nontransitional Unicode 17.0 IdnaTestV2.txt vectors passed.

Unicode 17.0

Upgrade the bundled UTS #46 and IDNA2008 data from Unicode 16.0.0 to Unicode 17.0.0. This release continues to use nontransitional processing with STD3 rules disabled during preprocessing and ships one deterministic Unicode table.

Install this release line explicitly with:

npm install idn-hostname@17

Compatibility with 16.0

Unicode 17.0 expands the accepted repertoire. Exhaustive comparison of the complete compact tables found no change to final eligibility, preprocessing behavior, existing mappings, viramas, bidi classes, or joining types that invalidates an input accepted by the Unicode 16 release line.

Runtime compatibility and selection of the appropriate package release remain the consumer's responsibility.

Verification

Qualification used Node.js 24.13.1 with Unicode 17.0 and ICU 78.2.

• All 118 package tests passed, including seven Unicode 17-specific fixtures.
• All 6,190 applicable nontransitional IdnaTestV2.txt vectors passed.
• Compact Unicode 17.0.0 table source-fidelity and deterministic-rebuild verification passed.
• The deployed table is byte-identical to the verified Unicode 17 build artifact.

DNS root separators

• Accepts one terminal U+002E, U+FF0E, U+3002, or U+FF61 separator as the DNS root marker.
• Preserves the root marker as U+002E in ASCII Compatible Encoding output.
• Applies the RFC 1034 DNS size limits to the non-root labels and complete domain name.
• Rejects root-only input and leading, consecutive, or multiple terminal separators.
• Includes applicable Unicode IdnaTestV2.txt trailing-root vectors in conformance testing.

All 6,327 tests and six benchmark scenarios passed.

Published on npm with the unicode-16.0 tag.

Verification infrastructure

• Migrates test and benchmark dispatchers to the gh-workspace-data v0.5.0 traversal APIs.
• Uses shared exact/cumulative layer selection, numbered-fixture discovery, and explicit concern discovery.
• Preserves cumulative package fixtures, exact Unicode conformance concerns, semantic layer order, and numeric-before-concern ordering.
• Updates CI to materialize the v0.5.0 runtime explicitly.

All 6,315 tests and six benchmark scenarios passed. There are no runtime API or Unicode 16 validator behavior changes.

Published on npm with the unicode-16.0 tag.

Portable verification

This patch restores executable verification for the Unicode 16 release line through shared public workspace data.

• Adds the generic, version-aware node:test dispatcher and npm test entry point.
• Runs 115 eligible package fixtures: 108 inherited Unicode 15.1 cases and seven Unicode 16 additions.
• Restores the authoritative Unicode 16.0.0 IdnaTestV2.txt concern with 6,200 applicable nontransitional vectors.
• Exercises both isIdnHostname and idnHostname, including exact expected ToASCII output for valid vectors.
• Keeps explicit conformance concerns exact-scoped while numeric callback fixtures accumulate from compatible older layers.

Benchmarks

• Adds npm run benchmark with isolated package loading and five function scenarios.
• Measures ASCII and internationalized validation and conversion plus UTS #46 mapping.
• Reports five initial calls, warmed latency statistics, integer throughput, workload counts, arguments, and environment metadata.
• Supports quick, JSON, and direct custom-iteration modes.

Runtime and CI

• Declares Node.js >=22.12.0 <23 || >=24.0.0.
• Node.js 22.12.0 is the first LTS release with ICU 76.1 and Unicode 16 data.
• Adds a nine-job CI matrix covering Node.js 22.12.0, 24, and 26 on Ubuntu, Windows, and macOS.
• Materializes public tests and the gh-workspace-data v0.4.1 runtime helper explicitly.

Compatibility

There are no runtime API or validator behavior changes. This package remains on the Unicode 16 data line.

Published on npm with the unicode-16.0 tag.

Performance

Add a validated fast path for non-reserved ASCII LDH hostnames. Hostnames whose labels contain only ASCII letters, digits, and internal hyphens, satisfy the 63-character label and 253-character presentation limits, and do not contain -- in positions 3 and 4 now avoid Unicode mapping, Punycode, contextual, and bidi validation.

Reserved labels, including xn-- A-label candidates, continue through the complete IDNA pipeline. idnHostname continues to apply UTS #46 mapping when producing output, including lowercase conversion of uppercase ASCII input.

Verification

• All 115 package tests passed.
• All 6,188 applicable nontransitional Unicode 16.0 IdnaTestV2.txt vectors passed.

Unicode 16.0

Upgrade the bundled UTS #46 and IDNA2008 data from Unicode 15.1.0 to Unicode 16.0.0. This release continues to use nontransitional processing with STD3 rules disabled during preprocessing and ships one deterministic Unicode table.

Install this release line explicitly with:

npm install idn-hostname@16

Compatibility with 15.1

Unicode 16.0 expands the accepted repertoire. Existing mappings and final/preprocessing eligibility remain additive, with one relevant property correction:

U+1171E AHOM CONSONANT SIGN MEDIAL RA
Bidi_Class:   NSM -> L
Joining_Type: T   -> U

Consequently, labels whose validity depends on the Unicode 15.1 properties of U+1171E can become invalid under RFC 5893 bidi or RFC 5892 CONTEXTJ validation. The README includes examples for both cases.

Runtime compatibility and selection of the appropriate package release remain the consumer's responsibility.

Verification

• All 111 package tests passed, including seven Unicode 16-specific fixtures.
• All 6,188 applicable nontransitional IdnaTestV2.txt vectors passed.
• Compact Unicode 16.0.0 table source-fidelity and deterministic-rebuild verification passed.
• The deployed table is byte-identical to the verified Unicode 16 build artifact.

DNS root separators

• Accepts one terminal U+002E, U+FF0E, U+3002, or U+FF61 separator as the DNS root marker.
• Preserves the root marker as U+002E in ASCII Compatible Encoding output.
• Applies the RFC 1034 DNS size limits to the non-root labels and complete domain name.
• Rejects root-only input and leading, consecutive, or multiple terminal separators.
• Includes applicable Unicode IdnaTestV2.txt trailing-root vectors in conformance testing.

All 6,248 tests and six benchmark scenarios passed.

Published on npm with the unicode-15.1 tag.

Verification infrastructure

• Migrates test and benchmark dispatchers to the gh-workspace-data v0.5.0 traversal APIs.
• Uses shared exact/cumulative layer selection, numbered-fixture discovery, and explicit concern discovery.
• Preserves cumulative package fixtures, exact Unicode conformance concerns, semantic layer order, and numeric-before-concern ordering.
• Updates CI to materialize the v0.5.0 runtime explicitly.

All 6,197 tests and six benchmark scenarios passed. There are no runtime API or Unicode 15.1 validator behavior changes.

Published on npm with the unicode-15.1 tag.

Portable verification

This patch restores executable verification for the Unicode 15.1 release line through shared public workspace data.

• Adds the generic, version-aware node:test dispatcher and npm test entry point.
• Runs 108 version-scoped package fixtures through the backwards-compatible isIdnHostname callback.
• Restores the authoritative Unicode 15.1.0 IdnaTestV2.txt concern with 6,089 applicable nontransitional vectors.
• Exercises both isIdnHostname and idnHostname, including exact expected ToASCII output for valid vectors.
• Keeps explicit conformance concerns exact-scoped while numeric callback fixtures accumulate from compatible older layers.

Benchmarks

• Adds npm run benchmark with isolated package loading and five function scenarios.
• Measures ASCII and internationalized validation and conversion plus UTS #46 mapping.
• Reports five initial calls, warmed latency statistics, integer throughput, workload counts, arguments, and environment metadata.
• Supports quick, JSON, and direct custom-iteration modes.

Runtime and CI

• Declares Node.js >=20.12.0 <21 || >=22.0.0.
• Node.js 20.12.0 is the first LTS release with ICU 74.2 and Unicode 15.1 data.
• Adds a 12-job CI matrix covering Node.js 20.12.0, 22, 24, and 26 on Ubuntu, Windows, and macOS.
• Materializes public tests and the gh-workspace-data v0.4.1 runtime helper explicitly.

Compatibility

There are no runtime API or validator behavior changes. This package remains on the Unicode 15.1 data line.

Published on npm with the unicode-15.1 tag.

Performance

Add a validated fast path for non-reserved ASCII LDH hostnames. Hostnames whose labels contain only ASCII letters, digits, and internal hyphens, satisfy the 63-character label and 253-character presentation limits, and do not contain -- in positions 3 and 4 now avoid Unicode mapping, Punycode, contextual, and bidi validation.

Reserved labels, including xn-- A-label candidates, continue through the complete IDNA pipeline. idnHostname continues to apply UTS #46 mapping when producing output, including lowercase conversion of uppercase ASCII input.

Verification

• All 108 package tests passed.
• All 6,077 applicable nontransitional Unicode 15.1 IdnaTestV2.txt vectors passed.

Fix

Correct RFC 5892 Appendix A.4 validation for U+0375 GREEK LOWER NUMERAL SIGN. The validator now checks the Script property of the immediately following character rather than matching the complete remaining label suffix.

This fixes both boundaries:

• a following Greek character remains valid when additional characters follow;
• an intervening non-Greek combining mark is rejected.

Documentation

• Pin UTS #46 to stable Unicode 15.1 revision 31.
• Clarify that named SyntaxError objects apply to the three validator functions, not the separately exported low-level Punycode dependency.
• Clarify the bundled-table wording and update the package-test count.

The bundled Unicode target remains Unicode 15.1.0.

Verification

• All 104 package tests passed.
• All 6,077 applicable nontransitional IdnaTestV2.txt vectors passed.
• Compact Unicode 15.1.0 table source-fidelity verification passed.

Installation guidance

The README installation command now selects the Unicode 15.1 release line explicitly:

npm install idn-hostname@15.1

This installs the latest 15.1.x patch without automatically selecting a different Unicode release line.

This patch changes documentation and package metadata only. Validation behavior and the bundled Unicode 15.1.0 table are unchanged.

Verification

• Compact Unicode 15.1.0 table source-fidelity verification passed.
• All 6,077 applicable nontransitional IdnaTestV2.txt vectors passed.

Versioning policy

• The package major and minor version components identify the targeted Unicode major and minor version.
• The package patch component identifies fixes and revisions that retain the same Unicode target.
• Each release ships one Unicode data table without runtime table selection. Runtime compatibility and release-line selection remain the consumer's responsibility.
• Releases that change the Unicode target will document compatibility with the preceding release line and identify known inputs that become invalid.

The 15.1.x release line continues to target Unicode 15.1.0. This patch changes documentation and package metadata only; validation behavior and the bundled Unicode table are unchanged.

Verification

• Compact Unicode 15.1.0 table source-fidelity verification passed.
• All 6,077 applicable nontransitional IdnaTestV2.txt vectors passed.

Changed

• Moved the package validation fixtures out of the canonical repository and into public workspace data.
• Replaced the previous ignore rules with the root #/ exclusion used for materialized workspace data.
• Consolidated qualification and test-access documentation under the Tests section.
• Added a folded guide for materializing the package tests through gh-workspace-data.

UTS #46 preprocessing

Summary

This update separates UTS #46 preprocessing from final IDNA eligibility.

A source code point may be permitted during nontransitional preprocessing but still be invalid after mapping and NFC. Conversely, a preprocessing sequence such as Hangul Jamo may normalize into a valid final syllable. The validator now represents and checks those phases independently without adding another label scan.

The update also corrects ACE handling and the RFC 5892 ZWNJ joining-context check.

What is new

Two-phase IDNA processing

• UTS #46 preprocessing uses sparse uts46_ranges overrides and falls back to ranges.
• Final post-NFC validation uses only ranges.
• Every non-empty UTS #46 preprocessing mapping is available, even when its result must later be rejected.
• Final eligibility is checked in the existing per-code-point contextual loop, preserving one label code-point spread and one loop.
• Processing remains nontransitional, with STD3 rules disabled.

This resolves cases that one combined property could not represent:

• U+00BC VULGAR FRACTION ONE QUARTER is allowed to map, but its result contains ineligible U+2044 FRACTION SLASH and is rejected afterward.
• Hangul Jamo are permitted during preprocessing when NFC can compose them into an eligible Hangul syllable.
• U+0133 LATIN SMALL LIGATURE IJ maps to ij.
• U+180C MONGOLIAN FREE VARIATION SELECTOR THREE is removed, so a᠌b validates as ab.

ACE and normalization

• Ordinary input is mapped and normalized before ACE-prefix recognition.
• Mixed-case ACE labels are canonicalized by preprocessing before the existing strict round-trip comparison.
• An xn-- prefix created by mapping is recognized and validated as ACE.
• Decoded Punycode is validated without remapping or normalization.
• A decoded A-label that is not already NFC is rejected. For example, xn--u-ccb no longer passes by being normalized into validity.
• The existing raw apparent-A-label/non-ASCII error retains its precedence.

Final eligibility

Mapped/NFC output and decoded ACE output are checked against the final/default ranges. Only valid and nontransitional deviation properties are accepted at this stage.

The final check reuses the existing IdnaUnicodeError and runs inside the existing contextual loop. Length, hyphen, and leading-mark checks retain their current ordering.

ZWNJ joining context

The RFC 5892 Appendix A.1 check now correctly requires:

• L or D as the nearest non-transparent joining type on the left; and
• R or D as the nearest non-transparent joining type on the right.

A ZWNJ immediately following a virama remains accepted. The correction preserves the existing joining-type accumulator, loop, exception type, and error text.

The compact condition was compared with the RFC rule across 597,870 synthetic joining sequences, including transparent characters and both joining types found among Unicode 15.1 viramas, with no mismatch.

Unicode data

The compact table is generated directly from authoritative Unicode 15.1.0 text files:

• IdnaMappingTable.txt;
• DerivedCombiningClass.txt;
• DerivedJoiningType.txt;
• DerivedBidiClass.txt.

IdnaTestV2.txt provides the official qualification vectors.

The validator continues to ship one immutable table and does not select a Unicode version at runtime. Unicode text files remain the source of truth; generation and exhaustive source-fidelity checks stay outside the validator package.

Current compact data totals:

The preprocessing overrides cover 8,900 valid and 590 mapped code points.

Qualification

The exact candidate implementation and Unicode 15.1 table pass:

Validator test suite          102 / 102
Applicable IdnaTestV2 cases  6077 / 6077

The 102-case validator suite includes focused coverage for:

1. U+00A0 mapping to invalid U+0020 SPACE;
2. U+00BC mapping through invalid U+2044 FRACTION SLASH;
3. mapped-range interior U+0133;
4. ignored-range interior U+180C.

The qualification adapter separately records:

• 137 successful pure-UTS NV8/XV8 cases outside the validator's final policy;
• 37 successful trailing-root cases outside the validator's intentional empty-final-label policy.

The runtime versions record test provenance; classification remains based on the bundled Unicode 15.1 table.

The generated data also passes exhaustive source-fidelity, range coverage, ordering, overlap, scalar, derived-property, and deterministic-rebuild checks.

Release notes

• Correct mapped and ignored range-interior handling.
• Permit preprocessing sequences that NFC transforms into eligible output.
• Reject mapped output that remains IDNA-ineligible after NFC.
• Accept mixed-case and mapping-created ACE prefixes after preprocessing.
• Reject decoded A-labels that are not already NFC.
• Correct invalid ZWNJ joining-context acceptance.
• Preserve existing APIs, error behavior, nontransitional processing, disabled STD3 preprocessing, and trailing-root policy.