idn-hostname

For each hostname, the implementation:

1. Requires a JavaScript string.
2. Accepts a hostname satisfying the non-reserved ASCII LDH fast-path constraints without Unicode table, contextual, Punycode, or bidi validation.
3. For remaining input, splits labels on U+002E, U+FF0E, U+3002, and U+FF61.
4. Rejects leading, trailing, or consecutive separators because they create an empty label.
5. Determines whether the hostname requires RFC 5893 bidi enforcement.
6. Preserves the existing raw non-ASCII A-label syntax check before preprocessing.
7. Applies uts46map and NFC to ordinary input.
8. If the preprocessed label starts with xn--:
   • requires ASCII input;
   • decodes the Punycode payload;
   • rejects an empty or all-ASCII decoded U-label;
   • requires the decoded U-label to already be NFC;
   • requires exact decode/re-encode agreement after preprocessing has normalized the ACE label's case.
9. Converts the resulting label to ASCII for length accounting and requires at most 63 ASCII octets.
10. Rejects a leading or trailing hyphen and hyphens in positions 3 and 4 of a U-label.
11. Rejects a leading Unicode mark.
12. Spreads the label into code points once and uses the existing per-code-point loop to:
    • require final valid or nontransitional deviation eligibility;
    • enforce CONTEXTJ and CONTEXTO rules;
    • enforce RFC 5893 bidi rules when the hostname is bidi.
13. Requires the complete ASCII presentation form, without a trailing root dot, to contain at most 253 octets.

The 63-octet label limit and 255-octet DNS wire-format limit come from the DNS size limits described by RFC 1035 and RFC 5890. The implementation's 253-character presentation-form limit accounts for separators while intentionally disallowing a trailing root dot.

• A label cannot begin or end with U+002D HYPHEN-MINUS.
• A U-label cannot contain hyphens in positions 3 and 4.
• A label cannot begin with a Unicode character in General Category M.
• An apparent A-label must contain only ASCII after preprocessing and must decode successfully.
• A decoded A-label must produce a non-ASCII U-label in NFC and round-trip through Punycode.
• Final code points must be eligible after preprocessing and normalization.

References: RFC 5890 §2.3.2.1; RFC 5891 §4.2.3 and §5.4; UTS #46 §4.1.

The validator implements checks for every RFC 5892 Appendix A contextual-rule family, including CONTEXTO checks that lookup-only applications are not universally required to evaluate:

• U+200C ZWNJ: accepted after a virama or when its joining-type context satisfies RFC 5892 Appendix A.1.
• U+200D ZWJ: accepted only immediately after a virama.
• U+00B7 MIDDLE DOT: accepted only between two lowercase ASCII l characters after preprocessing. An uppercase L in ordinary input is mapped to lowercase before this check.
• U+0375 GREEK LOWER NUMERAL SIGN: must be followed by a Greek-script character.
• U+05F3/U+05F4 Hebrew punctuation: must follow a Hebrew-script character.
• U+30FB KATAKANA MIDDLE DOT: requires at least one Hiragana, Katakana, or Han character in the label.
• Arabic digit sets: U+0660–U+0669 and U+06F0–U+06F9 cannot occur together in one label.

Reference: RFC 5892 Appendix A.1–A.9.

If the hostname contains an RTL label, every label is checked under RFC 5893:

• an RTL label must begin with R or AL, use only the permitted classes, and end with R, AL, EN, or AN, followed by optional NSM characters;
• an RTL label cannot mix EN and AN digits;
• an LTR label must begin with L, use only the permitted classes, and end with L or EN, followed by optional NSM characters.

Reference: RFC 5893 §2.

idnaMappingTableCompact.json contains:

During preprocessing, uts46_ranges takes precedence and lookup falls back to ranges. After mapping and NFC—or after unmodified ACE decoding—final validation consults only ranges and accepts valid or deviation.

Missing final/default ranges are treated as disallowed or unassigned. Deviation mappings are omitted because processing is nontransitional and leaves deviation code points unchanged.

Messages include the relevant RFC or UTS reference. Error precedence follows the validator's processing order and is part of its current behavior.

[
    'example',
    'sub.example',
    'mañana',
    'xn--maana-pta',
    'bücher',
    'пример.рф',
    'مثال',
    'דוגמה',
    '例子',
    'l·l',
    'L·l',        // uppercase ASCII is mapped to lowercase first
    'क्‍ष',       // virama + ZWJ
    'क्‌ष',       // virama + ZWNJ
    'a⁠b',        // U+2060 is ignored during preprocessing
    '가',        // Hangul Jamo normalize to 가
]

[
    '',
    '.example',
    'example.',       // trailing root labels are intentionally rejected
    'a..b',
    '-abc',
    'abc-',
    'a b',
    'emoji😀',
    'a·l',            // U+00B7 is not between two l characters
    'a‌',              // ZWNJ lacks a valid context
    'a‍',              // ZWJ is not preceded by a virama
    '̀hello',          // begins with a combining mark
    '٠۰',              // mixes the two Arabic digit sets
    '¼',               // maps through finally ineligible U+2044
]

Some examples contain invisible format characters. Keep source encoding intact when copying them.

Install the GitHub CLI extension once:

gh extension install SorinGFS/gh-workspace-data

Initialize and load workspace data from the cloned project repository:

gh workspace-data init
gh workspace-data load

The extension materializes ordinary local files under #/public/tests/ and #/public/benchmarks/, while #/version-layers.js provides deterministic version-layer discovery. The generated #/ namespace remains excluded from the canonical Git repository and npm package.

Run gh workspace-data load again to refresh materialized data after public-data changes or an extension upgrade.

Install package dependencies and run the materialized suite:

npm install
npm test

The suite uses the node:test module built into Node.js and requires no separate test-runner dependency. Its deterministic dispatcher delegates exact/cumulative layer selection, numbered-fixture traversal, and explicit concern discovery to the gh-workspace-data v0.5.0 runtime. #/public/tests/index.json selects the package's isIdnHostname callback and declares it backwards compatible, so numeric package fixtures accumulate semantically without being copied between version folders. Explicit concern suites retain exact-scope selection, and the matching Unicode conformance concern receives the complete package API from the root dispatcher.

Each applicable IdnaTestV2.txt vector exercises both isIdnHostname and idnHostname; valid conversions must equal the expected nontransitional ToASCII result. Applicability excludes otherwise-valid NV8/XV8 inputs permitted by default UTS #46 but rejected by this package's IDNA2008 policy and valid trailing-root inputs rejected by the package's presentation policy. U1 statuses are ignored because preprocessing uses UseSTD3ASCIIRules=false. CONTEXTO classification remains covered by the version-specific package fixtures rather than by the Unicode concern's applicability logic.

The Unicode fixture registrar verifies that the runtime's Unicode data is at least version 17.0 before registering vectors. The materialized #/public/tests/README.md documents the portable layout, and #/public/tests/v17.0/idna-test-v2/README.md documents source provenance and applicability rules.

npm test exits unsuccessfully when configuration, fixture loading, suite registration, conversion output, or a test fails. Continuous integration is configured to run the suite on the exact minimum Node.js 24.13.1 LTS runtime and the current compatible Node.js 26 release across Ubuntu, Windows, and macOS.

Run the standard workload:

npm run benchmark

Run a reduced workload with machine-readable output for CI smoke checks or artifacts:

node ./#/public/benchmarks --quick --json

Direct invocation also supports an explicit iteration count; npm run benchmark retains the standard 100,000 iterations per sample:

node ./#/public/benchmarks --iterations 250000

The harness records five initial calls, warmed minimum/median/p95/maximum latency in milliseconds with six decimal places, integer operations per second, representative arguments, workload counts, and environment metadata. Its generic coordinator delegates exact or cumulative layer selection and ordered concern discovery to the gh-workspace-data v0.5.0 runtime. The materialized #/public/benchmarks/README.md documents concern registration, version eligibility, workload controls, output fields, and guidance for noisy CI runners. Benchmark values are observations rather than correctness assertions.