cizgile 0.2.0 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <br>
-  <img src=".github/assets/cover.svg?v=f85c00e" alt="cizgile — Zero-dependency URL slug engine" width="100%">
+  <img src=".github/assets/cover.svg?v=7e268b8" alt="cizgile — Zero-dependency URL slug engine" width="100%">
   <br><br>
   <b style="font-size: 2em;">cizgile</b>
   <br><br>
@@ -30,23 +30,24 @@ slugify("Straße Über Ärger", { locale: "de" }) // "strasse-ueber-aerger"
 slugify("你好 World", { unicode: true }) // "你好-world"
 ```
 
-No dependencies. ESM only. Node 20+, Bun, Deno, browsers, edge workers.
+No dependencies. ESM only. Node 20+ and Bun are exercised in CI; the code touches no host API, so browsers and edge workers run it as-is.
 
 ## Why cizgile
 
 - **Slugs that are correct by construction.** Every ASCII slug is a valid URL path segment (RFC 3986 `segment-nz-nc`) — no percent-encoding needed, no `.` or `..`, no accidental scheme prefix.
-- **Speaks your language.** 36 locales (`tr`, `de`, `pl`, `sv`, `uk`, `ja`, `ko`, …) and 10 scripts (Latin, Cyrillic, Greek, Arabic, Armenian, Georgian, Dhivehi, Hebrew, Hangul, kana). `ß` → `ss`, `İ` → `i`, `Щ` → `shch`, `서울` → `seoul`.
+- **Speaks your language.** 50 locales (`tr`, `de`, `pl`, `sv`, `uk`, `hi`, `ta`, `th`, `ja`, `ko`, …) and 24 scripts (Latin, Cyrillic, Greek, Arabic, Armenian, Georgian, Dhivehi, Hebrew, Hangul, kana, Devanagari and the seven other Indic scripts, Sinhala, Thai, Lao, Khmer, Myanmar). `ß` → `ss`, `İ` → `i`, `Щ` → `shch`, `서울` → `seoul`.
 - **Unicode slugs when you want them.** `你好-world` stays readable, and `iriToUri` gives you the exact percent-encoded form for the wire.
 - **A real URL toolkit underneath.** Resolve, normalise, compare, validate and relativise URLs by the RFC, cross-checked against the WHATWG `URL` parser.
 - **Small and tree-shakeable.** `import { slugify }` ships the Latin table only; other scripts load only when you import them.
 
-## Three entry points
+## Four entry points
 
-| import                  | what you get                                                                                  |
-| ----------------------- | --------------------------------------------------------------------------------------------- |
-| `cizgile`               | `slugify`, `isSlug`, `createSlugger`, `truncateSlug`, `decamelize`, script and bidi guards    |
-| `cizgile/transliterate` | `transliterate`, per-script tables, locales, `defineLocale`                                   |
-| `cizgile/uri`           | percent-encoding, `resolveUri`, `normalizeUri`, `relativize`, validators, IRI ↔ URI, punycode |
+| import                  | what you get                                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| `cizgile`               | `slugify`, `isSlug`, `createSlugger`, `truncateSlug`, `measure`, `decamelize`, script and bidi guards |
+| `cizgile/transliterate` | `transliterate`, per-script tables, locales, `defineLocale`                                           |
+| `cizgile/uri`           | percent-encoding, `resolveUri`, `normalizeUri`, `relativize`, validators, IRI ↔ URI, punycode         |
+| `cizgile/uri/idna`      | full UTS #46 `idnaToAscii` / `idnaToUnicode`: status table, CONTEXTJ/CONTEXTO, RFC 5893 bidi rule     |
 
 ## Slugs
 
@@ -62,12 +63,14 @@ slugify("Hello World", { separator: "_" }) // "hello_world"
 slugify("Donald E. Knuth", { lowercase: false }) // "Donald-E-Knuth"
 slugify("getHTTPResponse", { decamelize: true }) // "get-http-response"
 slugify("the quick brown fox", { maxLength: 9 }) // "the-quick"
+slugify("Ünïcödé Büro", { unicode: true, maxLength: 11, maxLengthUnit: "bytes" }) // "ünïcödé"
+slugify("!!!", { fallback: "untitled" }) // "untitled"
 slugify("C++ & Rust", { replacements: [["C++", "cpp"]] }) // "cpp-and-rust"
 ```
 
 ### Languages and scripts
 
-Locale ids for Latin-script languages; Cyrillic locales and other scripts come from `cizgile/transliterate` so they only end up in your bundle when you use them.
+Locale ids for Latin-script languages; Cyrillic locales and other scripts come from `cizgile/transliterate` so they only end up in your bundle when you use them (or register them once with `registerLocale` and use their ids as strings).
 
 ```ts
 import { slugify } from "cizgile"
@@ -87,7 +90,7 @@ const swiss = defineLocale(de, { id: "de-CH", table: { ß: "ss" } })
 slugify("Straße", { locale: swiss }) // "strasse"
 ```
 
-Locale ids: `az ca cs da de es et fi fr hr hu is it lt lv nb nl pl pt ro sk sl sv tr vi`. Locale objects: those plus `be bg kk mk ru sr uk` (Cyrillic) and `el he ja ko` (Greek, Hebrew, kana, Hangul).
+Locale ids: `az ca cs da de es et fi fr hr hu is it lt lv nb nl pl pt ro sk sl sv tr vi`. Locale objects: those plus `be bg kk mk ru sr uk` (Cyrillic) and `el he hi ja ko` (Greek, Hebrew, Devanagari, kana, Hangul), `bn pa gu or ta te kn ml si` (Bengali, Gurmukhi, Gujarati, Odia, Tamil, Telugu, Kannada, Malayalam, Sinhala) and `th lo km my` (Thai, Lao, Khmer, Burmese). `registerLocale(ru, uk)` makes those ids usable as strings too. Every Latin and Cyrillic locale spells `&`, `%`, `$` and `£` in its language: `slugify("50% off", { locale: "de" })` is `"50-prozent-off"`, without a locale `"50-off"`.
 
 ### Unicode slugs
 
@@ -136,39 +139,41 @@ isSlug("你好-world", { unicode: true }) // true
 
 ### All options
 
-| option                      | default   | what it does                                                                                                                          |
-| --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `separator`                 | `"-"`     | Joins words. Any URL-safe punctuation (`- _ . ~ !$&'()*+,;= @`), several of them (`"--"`), or `""`.                                   |
-| `lowercase`                 | `true`    | `false` keeps the original case.                                                                                                      |
-| `unicode`                   | `false`   | Keep letters from every script instead of transliterating to ASCII.                                                                   |
-| `locale`                    | —         | Language-specific rules: a locale id or a `Locale` object.                                                                            |
-| `transliterate`             | `true`    | `false` skips the Latin and symbol tables (the locale table and accent folding still apply); an array adds script tables.             |
-| `decamelize`                | `false`   | `fooBar` → `foo-bar`, `HTMLParser` → `html-parser`.                                                                                   |
-| `replacements`              | `[]`      | `[from, to]` pairs applied first; spaces in `to` become separators.                                                                   |
-| `remove`                    | `/['’]/g` | A global regex of characters to delete rather than turn into separators (`don't` → `dont`); `false` keeps them.                       |
-| `preserveCharacters`        | `[]`      | Extra URL-safe single characters to keep, e.g. `["."]` for version numbers. The separator or anything outside `segment-nz-nc` throws. |
-| `preserveLeadingUnderscore` | `false`   | `_draft` → `_draft`.                                                                                                                  |
-| `preserveTrailingSeparator` | `false`   | Keep a trailing separator while the user is still typing.                                                                             |
-| `maxLength`                 | —         | Cut at a word boundary, never inside a character (emoji sequences, combining marks). Counts UTF-16 code units like `.length`.         |
-| `scripts`                   | `"any"`   | Unicode mode: UTS #39 mixed-script restriction level.                                                                                 |
-| `bidi`                      | `"allow"` | Unicode mode: RFC 3987 §4.2 direction rule — `"encode"` or `"throw"` on violation.                                                    |
+| option                      | default   | what it does                                                                                                                                                                       |
+| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `separator`                 | `"-"`     | Joins words. Any URL-safe punctuation (`- _ . ~ !$&'()*+,;= @`), several of them (`"--"`), or `""`.                                                                                |
+| `lowercase`                 | `true`    | `false` keeps the original case.                                                                                                                                                   |
+| `unicode`                   | `false`   | Keep letters from every script instead of transliterating to ASCII.                                                                                                                |
+| `locale`                    | —         | Language-specific rules: a locale id or a `Locale` object.                                                                                                                         |
+| `transliterate`             | `true`    | `false` skips the Latin and symbol tables (the locale table and accent folding still apply); `"none"` keeps only accent folding and the symbol words; an array adds script tables. |
+| `decamelize`                | `false`   | `fooBar` → `foo-bar`, `HTMLParser` → `html-parser`.                                                                                                                                |
+| `replacements`              | `[]`      | `[from, to]` pairs applied first; spaces in `to` become separators.                                                                                                                |
+| `remove`                    | `/['’]/g` | A global regex of characters to delete rather than turn into separators (`don't` → `dont`); `false` keeps them.                                                                    |
+| `preserveCharacters`        | `[]`      | Extra URL-safe single characters to keep, e.g. `["."]` for version numbers. The separator or anything outside `segment-nz-nc` throws.                                              |
+| `preserveLeadingUnderscore` | `false`   | `_draft` → `_draft`.                                                                                                                                                               |
+| `preserveTrailingSeparator` | `false`   | Keep a trailing separator while the user is still typing.                                                                                                                          |
+| `maxLength`                 | —         | Cut at a word boundary, never inside a character (emoji sequences, combining marks).                                                                                               |
+| `maxLengthUnit`             | `"units"` | What `maxLength` counts: UTF-16 code units like `.length`, `"code-points"`, `"graphemes"`, or UTF-8 `"bytes"` for a column or filename budget.                                     |
+| `fallback`                  | —         | Used when the result would be `""`: a string or a function of the input, slugified with the same options (`"untitled"`, then `untitled-2` in a slugger).                           |
+| `scripts`                   | `"any"`   | Unicode mode: UTS #39 mixed-script restriction level.                                                                                                                              |
+| `bidi`                      | `"allow"` | Unicode mode: RFC 3987 §4.2 direction rule — `"encode"` or `"throw"` on violation.                                                                                                 |
 
 The pipeline runs in this order: strip control/format characters → NFC → `replacements` → NFKC → `decamelize` → transliterate (locale → your tables → Latin → symbols → strip accents) → lowercase → `remove` → separators → `maxLength` → guards. Output is idempotent: `slugify(slugify(x)) === slugify(x)`.
 
 ## Transliteration on its own
 
 ```ts
-import { transliterate, cyrillic, hangul, kana, locales } from "cizgile/transliterate"
+import { transliterate, cyrillic, hangul, kana, devanagari, locales } from "cizgile/transliterate"
 
 transliterate("Straße Ærø") // "Strasse AEro"
 transliterate("Привет", { tables: [cyrillic] }) // "Privet"
 transliterate("Ängsö", { locale: locales.sv }) // "Aengsoe"
-transliterate("서울 ひらがな", { tables: [hangul, kana] }) // "seoul hiragana"
+transliterate("서울 ひらがな नमस्ते", { tables: [hangul, kana, devanagari] }) // "seoul hiragana namaste"
 transliterate("नमस्ते 你好") // "नमस्ते 你好" — unknown scripts are kept intact (use unknown: "drop" to remove)
 transliterate("final x² Ⅷ", { nfkc: true }) // "final x2 VIII"
 ```
 
-Tables: `latin symbols cyrillic cyrillicUk cyrillicBg cyrillicMk cyrillicSr greek arabic persian urdu pashto armenian georgian dhivehi hebrew hangul kana`, plus `allScripts`. Where a letter is spelled differently at the start of a word (Armenian `ե`, Ukrainian `є ї й ю я`), the capital carries the word-initial form. Hangul is romanised jamo by jamo (Revised Romanization without sound-change rules, so `한국어` is `hangukeo`), kana with Hepburn (the long-vowel mark and sokuon are dropped); kanji and Han are left as they are. `defineLocale` and `mergeTables` return new objects — nothing global is ever mutated.
+Tables: `latin symbols cyrillic cyrillicUk cyrillicBg cyrillicMk cyrillicSr greek arabic persian urdu pashto armenian georgian dhivehi hebrew devanagari bengali gurmukhi gujarati oriya tamil telugu kannada malayalam sinhala thai lao khmer myanmar hangul kana`, plus `allScripts`. Where a letter is spelled differently at the start of a word (Armenian `ե`, Ukrainian `є ї й ю я`), the capital carries the word-initial form. Devanagari and the other Indic scripts are romanised syllable by syllable (inherent `a`, no vowel length, no schwa deletion: `भारत` is `bharata`; Sinhala `කොළඹ` is `kolamba`), Hangul jamo by jamo (Revised Romanization without sound-change rules, so `한국어` is `hangukeo`), kana with Hepburn (the long-vowel mark and sokuon are dropped); kanji and Han are left as they are. The Thai, Lao, Khmer and Myanmar tables need context, so besides letters they carry rules (a table key starting with U+0001 is a regular expression, its value the replacement). Thai follows the Royal Thai General System without tone marks or vowel length: the vowels written before the consonant (`เ แ โ ใ ไ`) move behind it, a consonant is read as initial or final from its neighbours, a bare consonant takes `a` or, before the final, `o`, and silent letters under `์` are dropped (`ไทย` is `thai`, `เมือง` is `mueang`, `โรงเรียน` is `rongrian`, `กรุงเทพ` is `krungthep`). Lao uses the same logic with a simple BGN/PCGN-style spelling (`ວຽງຈັນ` is `viangchan`), Khmer reads each vowel sign by the series of its base consonant, UNGEGN-style (`ភ្នំពេញ` is `phnumpenh`, `កម្ពុជា` is `kampuchea`), and Myanmar keeps the inherent `a` unless the asat, a vowel sign or a stacked consonant follows (`မြန်မာ` is `myanma`, `ရန်ကုန်` is `yankun`). None of them has a dictionary or word segmentation: words are not split, the repetition mark `ๆ` is dropped, and irregular spellings, linking syllables (`พัทยา` is `phatya`, not `phatthaya`), Khmer and Lao silent letters and the Myanmar rhyme and tone rules are not handled, so output is a deterministic transcription of the spelling rather than of the pronunciation. `defineLocale` and `mergeTables` return new objects — nothing global is ever mutated.
 
 ## URL toolkit
 
@@ -187,12 +192,18 @@ import {
   isAbsoluteUri,
   isIPv6Address,
   extractUri,
+  getOrigin,
+  sortQuery,
+  joinPaths,
   iriToUri,
   uriToIri,
   domainToAscii,
 } from "cizgile/uri"
 
 resolveUri("http://a/b/c/d;p?q", "../../g") // "http://a/g"
+getOrigin("HTTP://Example.com:80/a?b") // "http://example.com"
+sortQuery("http://a/p?b=2&a=1") // "http://a/p?a=1&b=2"
+joinPaths("/api/", "/v1", "../v2/") // "/api/v2/"
 relativize("http://a/b/c/d;p?q", "http://a/b/g") // "../g"
 normalizeUri("HTTP://www.EXAMPLE.com:80/%7e%41/./b/../c") // "http://www.example.com/~A/c"
 equivalentUris("http://example.com", "http://example.com:80/") // true
@@ -214,13 +225,14 @@ iriToUri("http://例え.jp/résumé", { host: "punycode" }) // "http://xn--r8jz4
 `encodePathSegment(seg, { noColon })`, `encodePath(path, { relative })`, `encodeQuery`, `encodeFragment`, `encodeForm`.
 
 **Hosts (§3.2.2)**
-`isIPv4Address` `isIPv6Address` `isIPvFuture` `isIPLiteral` `isRegName` `isHost` `parseHost` `parseAuthority` `serializeAuthority`. `0x7f.0.0.1` and `2130706433` are registered names, not addresses (§7.4).
+`isIPv4Address` `isIPv6Address` `isIPvFuture` `isIPLiteral` `isRegName` `isHost` `parseHost` `parseAuthority` `serializeAuthority` `normalizeIPv6Address` (RFC 5952). `0x7f.0.0.1` and `2130706433` are registered names, not addresses (§7.4).
 
 **Parsing and validation (§4, Appendix A/B)**
-`parseUri` `serializeUri` — components stay distinct from "absent"; the serializer inserts `/.` or `./` where the grammar requires it.
+`parseUri(uri, { authority })` `serializeUri` — components stay distinct from "absent"; `authority: true` also gives `userinfo`, `host`, `port` and `portNumber`, and the serializer accepts those in place of `authority` and inserts `/.` or `./` where the grammar requires it.
 `isUriReference` `isUri` `isAbsoluteUri` `isRelativeReference` `classifyReference` `pathForm` — validating parser built from the ABNF.
 `isIriReference` `isIri` `isIunreserved` `isIpchar` — the same for IRIs (RFC 3987 §2.2).
 `extractUri(text)` — Appendix C: strips `<>`, quotes, `URL:` prefixes, trailing punctuation and line-wrap whitespace; a markdown link or an `href`/`src` attribute yields its URL.
+`findUris(text)` — the URIs in ordinary prose (`scheme://`, `www.`, `mailto:` and friends) with their offsets, trailing punctuation trimmed.
 
 **Resolution (§5)**
 `resolveUri(base, ref, { strict, allowRelativeBase })` — every §5.4 example passes; strict by default (`http:g` stays `http:g`).
@@ -229,7 +241,10 @@ iriToUri("http://例え.jp/résumé", { host: "punycode" }) // "http://xn--r8jz4
 `isSameDocumentReference(base, ref, { normalize })`.
 
 **Normalisation and comparison (§6)**
-`normalizeUri(uri, { defaultPorts, schemeBased, userinfo })` — case, percent-encoding, dot segments, default ports, empty path → `/`; `userinfo: "strip-password" | "strip"` for logs.
+`normalizeUri(uri, { defaultPorts, schemeBased, userinfo, trailingSlash, emptyQuery, emptyFragment, host, strict })` — case, percent-encoding, dot segments, default ports, empty path → `/`, IPv6 hosts in RFC 5952 form (`[0:0:0:0:0:0:0:1]` → `[::1]`); `userinfo: "strip-password" | "strip"` for logs; `trailingSlash: "add" | "remove"`, `emptyQuery`/`emptyFragment: "remove"`, `host: "idna" | "unicode"` and `strict` (throw on a bad host or port) are opt-in.
+`getOrigin(uri)` `isSameOrigin(a, b)` — RFC 6454 origins with default-port elision. `stripFragment(uri)`.
+`parseQuery(query)` `stringifyQuery(pairs)` `sortQuery(uri)` — `application/x-www-form-urlencoded` pairs in order, and a URI with its parameters sorted by name then value.
+`joinPaths(...pieces)` — single slashes, no dot segments, the first piece's leading and the last piece's trailing slash kept.
 `normalizePath(path, { trailingSlash })`.
 `equivalentUris(a, b, { level, base, ignoreFragment, defaultPorts })` — `"simple"`, `"syntax"` or `"scheme"` (default). Never maps IRIs to URIs (RFC 3987 §5.3.1).
 
@@ -239,7 +254,39 @@ iriToUri("http://例え.jp/résumé", { host: "punycode" }) // "http://xn--r8jz4
 `uriToIri(uri)` — decodes only what §3.2 allows, per component.
 `punycodeEncode` `punycodeDecode` `domainToAscii` `domainToUnicode` — RFC 3492, no dependencies. `domainToAscii` maps and lowercases labels the way UTS #46 does, then rejects what no DNS name may carry: empty labels, labels over 63 octets, names over 253, leading or trailing hyphens, non-LDH characters and `xn--` labels that do not round-trip.
 
-Deliberately not implemented: RFC 6874 IPv6 zone identifiers (reverted by RFC 9844), the network-based normalisation of §6.2.4, and the UTS #46 status table, CONTEXTJ/CONTEXTO and the RFC 5893 bidi rule for domains.
+Deliberately not implemented: RFC 6874 IPv6 zone identifiers (reverted by RFC 9844) and the network-based normalisation of §6.2.4. The UTS #46 status table, CONTEXTJ/CONTEXTO and the RFC 5893 bidi rule live in the optional `cizgile/uri/idna` entry below, so `cizgile/uri` stays small.
+
+### Full IDNA (`cizgile/uri/idna`)
+
+`domainToAscii` in `cizgile/uri` approximates UTS #46: it removes format characters, applies NFKC and lowercases, so it does not know which code points are disallowed, ignored or deviations, and it does not check joiners or the bidi rule. `cizgile/uri/idna` carries the real Unicode 16.0.0 table (about 45 KB minified, which is why it is a separate import) and passes every case of the official `IdnaTestV2.txt`, nontransitional and transitional, down to the error codes.
+
+```ts
+import { idnaToAscii, idnaToUnicode, idnaToAsciiResult } from "cizgile/uri/idna"
+
+idnaToAscii("Bücher.DE") // "xn--bcher-kva.de"
+idnaToAscii("faß.de", { transitionalProcessing: true }) // "fass.de"
+idnaToUnicode("xn--r8jz45g.jp") // "例え.jp"
+idnaToAscii("a_b.com", { beStrict: true }) // throws RangeError: "a_b.com" is not valid (U1)
+idnaToAsciiResult("aא") // { result: "xn--a-...", errors: ["B5", "B6"] }
+```
+
+`idnaToAscii` and `idnaToUnicode` throw a `RangeError` that lists the error codes, like `domainToAscii`. `idnaToAsciiResult` and `idnaToUnicodeResult` never throw: they return `{ result, errors }` with the best-effort result and every UTS #46 code (`P4`, `V1` to `V7`, `U1`, `B1` to `B6`, `C1`, `C2`, `A3`, `A4_1`, `A4_2`, `X4_2`, and `O1` for CONTEXTO). `codePointStatus(cp)` exposes the table itself.
+
+Options default to the WHATWG URL Standard's domain to ASCII:
+
+| option                   | default | effect                                                                                   |
+| ------------------------ | ------- | ---------------------------------------------------------------------------------------- |
+| `beStrict`               | `false` | turns on `useSTD3ASCIIRules`, `checkHyphens` and `verifyDnsLength` unless set explicitly |
+| `useSTD3ASCIIRules`      | `false` | only `a-z`, `0-9`, `-` among ASCII characters (`U1`)                                     |
+| `checkHyphens`           | `false` | no `--` in positions 3 and 4, no hyphen at either end (`V2`, `V3`)                       |
+| `checkBidi`              | `true`  | RFC 5893 rules 1 to 6 for every label of a bidi domain name (`B1` to `B6`)               |
+| `checkJoiners`           | `true`  | RFC 5892 CONTEXTJ for U+200C and U+200D (`C1`, `C2`)                                     |
+| `checkContextO`          | `false` | RFC 5892 A.3 to A.9: middle dot, keraia, geresh, gershayim, katakana middle dot, digits  |
+| `transitionalProcessing` | `false` | IDNA2003 mapping of `ß`, `ς`, U+200C, U+200D (deprecated)                                |
+| `verifyDnsLength`        | `false` | labels 1 to 63, name 1 to 253 without the root dot (`A4_1`, `A4_2`; `X4_2` in ToUnicode) |
+| `ignoreInvalidPunycode`  | `false` | keep an undecodable `xn--` label instead of `P4`                                         |
+
+Unicode 16 folded the old `disallowed_STD3_*` statuses into the validity criteria, so the table has five statuses and `useSTD3ASCIIRules` is a plain check. `String.prototype.normalize` (NFC) comes from the runtime; everything else is data generated by `scripts/gen-idna.mjs`, which also refreshes the test fixture. CONTEXTO is not part of UTS #46 and `IdnaTestV2.txt` does not test it, so `checkContextO` is separate from `beStrict`.
 
 </details>
 
@@ -292,6 +339,10 @@ nothing after the first call.
 
 RFC 3986 (with errata 2033, 4547, 4789, 5428), RFC 3987, RFC 3492 (all nineteen §7.1 sample strings), RFC 8820, RFC 9844, the UTS #46 mapping step, the WHATWG URL Standard's percent-encode sets, Unicode UTS #39 restriction levels and UAX #29 grapheme boundaries, Google Search Central's URL guidance. The test suite runs every example those documents contain.
 
+## Changelog
+
+Release notes live on the [GitHub Releases page](https://github.com/productdevbook/cizgile/releases); each release lists the commits since the previous tag. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to work on the library and [SECURITY.md](SECURITY.md) for reporting a vulnerability.
+
 ## Development
 
 ```sh
@@ -299,6 +350,8 @@ bun install
 bun run test      # oxlint, oxfmt, tsc, vitest under node, then vitest under bun
 bun run build     # rolldown → dist/*.mjs + dist/*.d.mts
 bun run coverage
+bun run bench     # vitest bench against @sindresorhus/slugify, simov/slugify and the built-ins
+bun run bench:baseline  # write bench/baseline.json locally; the Bench workflow compares each run with the last successful one on main
 bun run release   # bumpp: bump, tag, push — the tag publishes to npm
 ```
 
@@ -307,7 +360,7 @@ bun run release   # bumpp: bump, tag, push — the tag publishes to npm
 - [simov/slugify](https://github.com/simov/slugify) — the charmap + per-locale override idea and most Cyrillic, Greek, Arabic and symbol values.
 - [sindresorhus/slugify](https://github.com/sindresorhus/slugify) and [sindresorhus/transliterate](https://github.com/sindresorhus/transliterate) — `decamelize`, custom replacements, the counter slugger, and the Armenian, Georgian and Dhivehi tables.
 - [Django](https://github.com/django/django) and [Rails](https://github.com/rails/rails) — the reference behaviours the parity tests are written against.
-- The [WHATWG URL Standard](https://url.spec.whatwg.org/) — percent-encode sets and the parser every result is cross-checked with.
+- The [WHATWG URL Standard](https://url.spec.whatwg.org/) — percent-encode sets and the parser every result is cross-checked with, and the RFC 3986-compatible subset of its [`urltestdata.json`](https://github.com/web-platform-tests/wpt/blob/master/url/resources/urltestdata.json) (web-platform-tests, BSD 3-Clause) vendored as a fixture.
 - [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) by Berners-Lee, Fielding and Masinter, and [RFC 3987](https://datatracker.ietf.org/doc/html/rfc3987) by Duerst and Suignard.
 - [Rolldown](https://rolldown.rs), [Oxc](https://oxc.rs), [Vitest](https://vitest.dev), [Bun](https://bun.sh) and [TypeScript](https://www.typescriptlang.org).
 

package/dist/idna.d.mts

@@ -0,0 +1,60 @@
+//#region src/idna/data.d.ts
+/** The Unicode version of the tables behind `cizgile/uri/idna`. */
+export declare const IDNA_UNICODE_VERSION = "16.0.0";
+//#endregion
+//#region src/idna/process.d.ts
+/** Options of the UTS #46 processing. The defaults are those of the WHATWG URL Standard's domain to ASCII. */
+interface IdnaOptions {
+  /** Turn on `useSTD3ASCIIRules`, `checkHyphens` and `verifyDnsLength` unless they are set explicitly. Default `false`. */
+  beStrict?: boolean;
+  /** Only `a-z`, `0-9` and `-` among ASCII characters (error `U1`). Default `false`, or `true` with `beStrict`. */
+  useSTD3ASCIIRules?: boolean;
+  /** No hyphen in positions 3 and 4 and none at either end (`V2`, `V3`); when off, a label may not start with `xn--` (`V4`). Default `false`, or `true` with `beStrict`. */
+  checkHyphens?: boolean;
+  /** The RFC 5893 bidi rule for labels of a bidi domain name (`B1` to `B6`). Default `true`. */
+  checkBidi?: boolean;
+  /** RFC 5892 CONTEXTJ: where U+200C and U+200D may appear (`C1`, `C2`). Default `true`. */
+  checkJoiners?: boolean;
+  /** RFC 5892 CONTEXTO, appendix A.3 to A.9: middle dot, keraia, geresh, gershayim, katakana middle dot, Arabic-Indic digits (`O1`). Not part of UTS #46. Default `false`. */
+  checkContextO?: boolean;
+  /** Map `ß`, `ς`, U+200C and U+200D the IDNA2003 way (deprecated). Default `false`. */
+  transitionalProcessing?: boolean;
+  /** Label length 1 to 63, name length 1 to 253 without the root dot (`A4_1`, `A4_2`), and empty labels in `idnaToUnicode` (`X4_2`). Default `false`, or `true` with `beStrict`. */
+  verifyDnsLength?: boolean;
+  /** Keep an `xn--` label whose Punycode does not decode as it is instead of reporting `P4`. Default `false`. */
+  ignoreInvalidPunycode?: boolean;
+}
+/** The outcome of UTS #46 processing: the converted domain, always produced, and the error codes it recorded. */
+interface IdnaResult {
+  /** The converted domain, as far as processing got. */
+  readonly result: string;
+  /** Error codes such as `V7`, `B1`, `C1` or `A4_2`, sorted; empty when the domain is valid. */
+  readonly errors: readonly string[];
+}
+/** UTS #46 ToASCII: maps, normalizes, validates and Punycode-encodes `domain`, and reports every error code instead of throwing. `result` is produced even when `errors` is not empty. */
+export declare function idnaToAsciiResult(domain: string, options?: IdnaOptions): IdnaResult;
+/** UTS #46 ToUnicode: maps, normalizes, validates and decodes the `xn--` labels of `domain`, and reports every error code instead of throwing. */
+export declare function idnaToUnicodeResult(domain: string, options?: IdnaOptions): IdnaResult;
+/**
+ * UTS #46 ToASCII with the full Unicode 16 status table. Unlike `domainToAscii` in `cizgile/uri` it knows every valid, ignored, mapped, deviation and disallowed code point, and checks CONTEXTJ and the bidi rule.
+ * @throws {RangeError} when processing records an error; the message lists the codes.
+ */
+export declare function idnaToAscii(domain: string, options?: IdnaOptions): string;
+/**
+ * UTS #46 ToUnicode with the full Unicode 16 status table.
+ * @throws {RangeError} when processing records an error; the message lists the codes.
+ */
+export declare function idnaToUnicode(domain: string, options?: IdnaOptions): string;
+//#endregion
+//#region src/idna/tables.d.ts
+/** The UTS #46 status of a code point and, for `mapped` and `deviation`, what it maps to. */
+type CodePointStatus = {
+  readonly status: "valid" | "ignored" | "disallowed";
+} | {
+  readonly status: "mapped" | "deviation";
+  readonly to: readonly number[];
+};
+/** Looks up the UTS #46 status of one code point. */
+export declare function codePointStatus(cp: number): CodePointStatus;
+//#endregion
+export type { CodePointStatus, IdnaOptions, IdnaResult };