cizgile 0.2.0 → 0.3.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=bcfc1d9" alt="cizgile — Zero-dependency URL slug engine" width="100%">
   <br><br>
   <b style="font-size: 2em;">cizgile</b>
   <br><br>
@@ -30,23 +30,23 @@ 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+, Bun and Deno 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.** 45 locales (`tr`, `de`, `pl`, `sv`, `uk`, `hi`, `ta`, `ja`, `ko`, …) and 19 scripts (Latin, Cyrillic, Greek, Arabic, Armenian, Georgian, Dhivehi, Hebrew, Hangul, kana, Devanagari and the seven other Indic scripts). `ß` → `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
 
-| 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         |
 
 ## Slugs
 
@@ -62,12 +62,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 +89,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` (Bengali, Gurmukhi, Gujarati, Odia, Tamil, Telugu, Kannada, Malayalam). `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 +138,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 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`), 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. `defineLocale` and `mergeTables` return new objects — nothing global is ever mutated.
 
 ## URL toolkit
 
@@ -187,12 +191,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 +224,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 +240,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).
 
@@ -292,6 +306,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 +317,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 +327,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/index.d.mts

@@ -1,4 +1,4 @@
-import { i as LocaleId, n as LatinLocaleId, o as TransliterationTable, r as Locale } from "./shared/types-DbyhfPRc.mjs";
+import { i as LocaleId, n as LatinLocaleId, o as TransliterationTable, r as Locale } from "./shared/types-B3EVWvDh.mjs";
 //#region src/slug/bidi.d.ts
 /** RFC 3987 section 4.2: whether `text` can be a URL component without mixing text directions in a way that renders ambiguously. */
 export declare function isBidiSafeComponent(text: string): boolean;
@@ -22,6 +22,14 @@ export declare function detectScripts(text: string): string[];
 /** Applies a UTS #39 restriction `level` to the scripts in `text`; `ok` is false when the mix exceeds it. */
 export declare function checkScripts(text: string, level?: ScriptRestriction): ScriptCheck;
 //#endregion
+//#region src/slug/truncate.d.ts
+/** How `maxLength` counts: UTF-16 code units (like `.length`), code points, grapheme clusters, or UTF-8 bytes. */
+type LengthUnit = "units" | "code-points" | "graphemes" | "bytes";
+/** The length of `text` in the given unit. */
+export declare function measure(text: string, unit?: LengthUnit): number;
+/** Cuts `slug` to at most `maxLength` in the given `unit` (UTF-16 code units by default) at a `separator` boundary, never inside a grapheme cluster. */
+export declare function truncateSlug(slug: string, maxLength: number, separator?: string, unit?: LengthUnit): string;
+//#endregion
 //#region src/slug/options.d.ts
 /** Options for `slugify` and `createSlugger`. Every option has a default; an empty object is the everyday call. */
 interface SlugifyOptions {
@@ -31,10 +39,10 @@ interface SlugifyOptions {
   readonly lowercase?: boolean;
   /** Keeps letters from every script instead of transliterating to ASCII; `false` by default. */
   readonly unicode?: boolean;
-  /** Language rules: a Latin locale id such as `"tr"`, or a `Locale` object from `cizgile/transliterate`. */
-  readonly locale?: LatinLocaleId | Locale;
-  /** `false` skips the Latin and symbol tables (the locale table and accent folding still apply); an array adds script tables such as `cyrillic`. */
-  readonly transliterate?: boolean | readonly TransliterationTable[];
+  /** Language rules: a Latin locale id such as `"tr"`, the id of a locale passed to `registerLocale`, or a `Locale` object from `cizgile/transliterate`. */
+  readonly locale?: LatinLocaleId | (string & {}) | Locale;
+  /** `false` skips the Latin and symbol tables (the locale table and accent folding still apply); `"none"` skips every letter table and keeps only accent folding and the symbol words; an array adds script tables such as `cyrillic`. */
+  readonly transliterate?: boolean | "none" | readonly TransliterationTable[];
   /** Splits camelCase before slugging: `"fooBar"` becomes `"foo-bar"`; `false` by default. */
   readonly decamelize?: boolean;
   /** `[from, to]` pairs applied before anything else; spaces in `to` become separators. */
@@ -47,15 +55,19 @@ interface SlugifyOptions {
   readonly preserveLeadingUnderscore?: boolean;
   /** Keeps a trailing separator, for input still being typed. */
   readonly preserveTrailingSeparator?: boolean;
-  /** Cuts at a word boundary, never inside a grapheme cluster. Counts UTF-16 code units like `.length`. */
+  /** Cuts at a word boundary, never inside a grapheme cluster. Counts in `maxLengthUnit`, UTF-16 code units like `.length` by default. */
   readonly maxLength?: number;
+  /** What `maxLength` counts: `"units"` (default), `"code-points"`, `"graphemes"` or UTF-8 `"bytes"`. */
+  readonly maxLengthUnit?: LengthUnit;
+  /** Used when the result would be `""`: a string, or a function of the input; the value is slugified with the same options. */
+  readonly fallback?: string | ((input: string) => string);
   /** Unicode mode only: the UTS #39 restriction level the result must satisfy; `"any"` by default. */
   readonly scripts?: ScriptRestriction;
   /** Unicode mode only: what to do when the result mixes text directions (RFC 3987 section 4.2); `"allow"` by default. */
   readonly bidi?: "allow" | "encode" | "throw";
 }
 /** The `slugify` options that shape what a valid slug looks like. */
-type IsSlugOptions = Pick<SlugifyOptions, "separator" | "lowercase" | "unicode" | "locale" | "preserveCharacters" | "preserveLeadingUnderscore" | "preserveTrailingSeparator" | "maxLength" | "scripts" | "bidi">;
+type IsSlugOptions = Pick<SlugifyOptions, "separator" | "lowercase" | "unicode" | "locale" | "preserveCharacters" | "preserveLeadingUnderscore" | "preserveTrailingSeparator" | "maxLength" | "maxLengthUnit" | "scripts" | "bidi">;
 //#endregion
 //#region src/slug/is-slug.d.ts
 /** Whether `input` is exactly what `slugify` would produce under the same options. */
@@ -87,8 +99,4 @@ export declare const slugifyWithCounter: (defaults?: SlugifyOptions) => Slugger;
  */
 export declare function slugify(input: string, options?: SlugifyOptions): string;
 //#endregion
-//#region src/slug/truncate.d.ts
-/** Cuts `slug` to at most `maxLength` UTF-16 code units at a `separator` boundary, never inside a grapheme cluster. */
-export declare function truncateSlug(slug: string, maxLength: number, separator?: string): string;
-//#endregion
-export type { IsSlugOptions, LatinLocaleId, Locale, LocaleId, ScriptCheck, ScriptRestriction, Slugger, SlugifyOptions, TransliterationTable };
+export type { IsSlugOptions, LatinLocaleId, LengthUnit, Locale, LocaleId, ScriptCheck, ScriptRestriction, Slugger, SlugifyOptions, TransliterationTable };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { A as fold, D as DEFAULT_TABLES, F as symbols, O as applyCompat, k as compileTables, m as latinLocales } from "./shared/locales-latin-Bm94HAeL.mjs";
+import { M as applyCompat, N as compileTables, P as fold, j as DEFAULT_TABLES, n as registeredLocale, r as registryVersion, v as latinLocales, z as symbols } from "./shared/registry-_m94akct.mjs";
 import { h as isSegmentNzNc, r as percentEncode } from "./shared/percent-DG-pZhJI.mjs";
 
 //#region src/slug/bidi.ts
@@ -168,14 +168,15 @@ let cache$1;
 function resolveLocale(locale) {
 	if (locale === void 0) return void 0;
 	if (typeof locale === "string") {
-		const found = latinLocales[locale];
-		if (found === void 0) throw new TypeError(`slugify: unknown locale "${locale}"; pass a Locale object exported by cizgile/transliterate`);
+		const found = latinLocales[locale] ?? registeredLocale(locale);
+		if (found === void 0) throw new TypeError(`slugify: unknown locale "${locale}"; pass a Locale object exported by cizgile/transliterate, or register it with registerLocale()`);
 		return found;
 	}
 	return locale;
 }
 function resolveTables(option, unicode, locale) {
 	if (unicode) return void 0;
+	if (option === "none") return (locale === void 0 ? [symbols] : [locale.table, symbols]).map(symbolEntries);
 	const out = [];
 	if (locale !== void 0) {
 		out.push(locale.table);
@@ -207,6 +208,15 @@ function build(options) {
 	}
 	const maxLength = options.maxLength;
 	if (maxLength !== void 0 && (!Number.isInteger(maxLength) || maxLength < 0)) throw new RangeError("slugify: maxLength must be a non-negative integer");
+	const maxLengthUnit = options.maxLengthUnit ?? "units";
+	if (![
+		"units",
+		"code-points",
+		"graphemes",
+		"bytes"
+	].includes(maxLengthUnit)) throw new TypeError(`slugify: unknown maxLengthUnit ${JSON.stringify(maxLengthUnit)}`);
+	const fallback = options.fallback;
+	if (fallback !== void 0 && typeof fallback !== "string" && typeof fallback !== "function") throw new TypeError("slugify: fallback must be a string or a function");
 	const wordExtra = preserveCharacters.map(escapeClassChar).join("");
 	const wordClass = unicode ? `\\p{L}\\p{N}\\p{M}${wordExtra}` : `a-z0-9${lowercase ? "" : "A-Z"}${wordExtra}`;
 	const allowedClass = wordClass + separatorChars.map(escapeClassChar).join("");
@@ -227,6 +237,8 @@ function build(options) {
 		preserveLeadingUnderscore: options.preserveLeadingUnderscore ?? false,
 		preserveTrailingSeparator: options.preserveTrailingSeparator ?? false,
 		maxLength,
+		maxLengthUnit,
+		fallback,
 		scripts: options.scripts ?? "any",
 		bidi: options.bidi ?? "allow",
 		allowedClass,
@@ -257,6 +269,7 @@ function optionsKey(options) {
 	const locale = options.locale;
 	const transliterate = options.transliterate;
 	const remove = options.remove;
+	const fallback = options.fallback;
 	return JSON.stringify([
 		options.separator,
 		options.lowercase,
@@ -270,60 +283,31 @@ function optionsKey(options) {
 		options.preserveLeadingUnderscore,
 		options.preserveTrailingSeparator,
 		options.maxLength,
+		options.maxLengthUnit,
+		typeof fallback === "function" ? `#${objectId(fallback)}` : fallback,
 		options.scripts,
 		options.bidi
 	]);
 }
 function resolveOptions(options = DEFAULT_OPTIONS$1) {
 	cache$1 ??= /* @__PURE__ */ new WeakMap();
-	const cached = cache$1.get(options);
-	if (cached !== void 0) return cached;
+	const registered = typeof options.locale === "string" && !(options.locale in latinLocales);
+	if (!registered) {
+		const cached = cache$1.get(options);
+		if (cached !== void 0) return cached;
+	}
 	byKey ??= /* @__PURE__ */ new Map();
-	const key = optionsKey(options);
+	const key = registered ? `${registryVersion()}:${optionsKey(options)}` : optionsKey(options);
 	let resolved = byKey.get(key);
 	if (resolved === void 0) {
 		resolved = build(options);
 		if (byKey.size > 512) byKey.clear();
 		byKey.set(key, resolved);
 	}
-	cache$1.set(options, resolved);
+	if (!registered) cache$1.set(options, resolved);
 	return resolved;
 }
 
-//#endregion
-//#region src/slug/is-slug.ts
-let cache;
-function patternFor(options) {
-	cache ??= /* @__PURE__ */ new WeakMap();
-	const cached = cache.get(options);
-	if (cached !== void 0) return cached;
-	const o = resolveOptions(options);
-	const char = `[${o.wordClass}]`;
-	const separator = escapeRegExp$1(o.separator);
-	const lead = o.preserveLeadingUnderscore ? "_?" : "";
-	const word = o.unicode ? `(?!\\p{M})${char}+` : `${char}+`;
-	const body = o.separator === "" ? word : `${word}(?:${separator}${word})*`;
-	const tail = o.preserveTrailingSeparator && o.separator !== "" ? `(?:${separator})?` : "";
-	const pattern = new RegExp(`^${lead}${body}${tail}$`, "u");
-	cache.set(options, pattern);
-	return pattern;
-}
-const DEFAULT_OPTIONS = {};
-/** Whether `input` is exactly what `slugify` would produce under the same options. */
-function isSlug(input, options = DEFAULT_OPTIONS) {
-	if (typeof input !== "string" || input === "" || input === "." || input === "..") return false;
-	const o = resolveOptions(options);
-	if (o.maxLength !== void 0 && input.length > o.maxLength) return false;
-	if (o.separator !== "" && input.includes(o.separator + o.separator)) return false;
-	if (o.unicode) {
-		if (input !== input.normalize("NFKC")) return false;
-		if (o.lowercase && input !== lowercaseOf(input, o)) return false;
-		if (o.scripts !== "any" && !checkScripts(input, o.scripts).ok) return false;
-		if (o.bidi !== "allow" && !isBidiSafeComponent(input)) return false;
-	}
-	return patternFor(options).test(input);
-}
-
 //#endregion
 //#region src/slug/truncate.ts
 let segmenter;
@@ -339,6 +323,53 @@ function isJoinerBefore(text, index) {
 function isClusterExtender(cp) {
 	return cp >= 56320 && cp <= 57343 || cp === 8205 || cp >= 65024 && cp <= 65039 || cp >= 127995 && cp <= 127999 || cp >= 4448 && cp <= 4607 || cp >= 917536 && cp <= 917631 || /\p{M}/u.test(String.fromCodePoint(cp));
 }
+function utf8Length(cp) {
+	return cp < 128 ? 1 : cp < 2048 ? 2 : cp < 65536 ? 3 : 4;
+}
+/** The length of `text` in the given unit. */
+function measure(text, unit = "units") {
+	if (unit === "units") return text.length;
+	let count = 0;
+	if (unit === "graphemes") {
+		const seg = graphemeSegmenter();
+		if (seg !== void 0) {
+			for (const _ of seg.segment(text)) count += 1;
+			return count;
+		}
+		let index = 0;
+		for (const ch of text) {
+			if (!(isClusterExtender(ch.codePointAt(0) ?? 0) || isJoinerBefore(text, index)) || index === 0) count += 1;
+			index += ch.length;
+		}
+		return count;
+	}
+	for (const ch of text) count += unit === "bytes" ? utf8Length(ch.codePointAt(0) ?? 0) : 1;
+	return count;
+}
+function prefixEnd(text, limit, unit) {
+	if (unit === "units") return Math.min(limit, text.length);
+	let used = 0;
+	if (unit === "graphemes") {
+		const seg = graphemeSegmenter();
+		if (seg !== void 0) {
+			let end = 0;
+			for (const { index, segment } of seg.segment(text)) {
+				if (used === limit) break;
+				used += 1;
+				end = index + segment.length;
+			}
+			return end;
+		}
+	}
+	let end = 0;
+	for (const ch of text) {
+		const cost = unit === "bytes" ? utf8Length(ch.codePointAt(0) ?? 0) : 1;
+		if (used + cost > limit) break;
+		used += cost;
+		end += ch.length;
+	}
+	return unit === "graphemes" ? graphemeBoundary(text, end, { fallback: true }) : end;
+}
 function graphemeBoundary(text, limit, options = {}) {
 	const seg = options.fallback === true ? void 0 : graphemeSegmenter();
 	if (seg !== void 0) {
@@ -361,13 +392,14 @@ function stripTrailingSeparator(text, separator) {
 	for (let k = separator.length - 1; k > 0; k--) if (out.endsWith(separator.slice(0, k))) return out.slice(0, -k);
 	return out;
 }
-/** Cuts `slug` to at most `maxLength` UTF-16 code units at a `separator` boundary, never inside a grapheme cluster. */
-function truncateSlug(slug, maxLength, separator = "-") {
+/** Cuts `slug` to at most `maxLength` in the given `unit` (UTF-16 code units by default) at a `separator` boundary, never inside a grapheme cluster. */
+function truncateSlug(slug, maxLength, separator = "-", unit = "units") {
 	if (!Number.isInteger(maxLength) || maxLength < 0) throw new RangeError("truncateSlug: maxLength must be a non-negative integer");
-	if (slug.length <= maxLength) return slug;
+	if (measure(slug, unit) <= maxLength) return slug;
 	if (maxLength === 0) return "";
-	let cut = slug.slice(0, maxLength);
-	if (separator !== "" && !slug.startsWith(separator, maxLength)) {
+	const limit = prefixEnd(slug, maxLength, unit);
+	let cut = slug.slice(0, limit);
+	if (separator !== "" && !slug.startsWith(separator, limit)) {
 		const last = cut.lastIndexOf(separator);
 		if (last > 0) cut = cut.slice(0, last);
 	}
@@ -375,6 +407,40 @@ function truncateSlug(slug, maxLength, separator = "-") {
 	return stripTrailingSeparator(cut, separator);
 }
 
+//#endregion
+//#region src/slug/is-slug.ts
+let cache;
+function patternFor(options) {
+	cache ??= /* @__PURE__ */ new WeakMap();
+	const cached = cache.get(options);
+	if (cached !== void 0) return cached;
+	const o = resolveOptions(options);
+	const char = `[${o.wordClass}]`;
+	const separator = escapeRegExp$1(o.separator);
+	const lead = o.preserveLeadingUnderscore ? "_?" : "";
+	const word = o.unicode ? `(?!\\p{M})${char}+` : `${char}+`;
+	const body = o.separator === "" ? word : `${word}(?:${separator}${word})*`;
+	const tail = o.preserveTrailingSeparator && o.separator !== "" ? `(?:${separator})?` : "";
+	const pattern = new RegExp(`^${lead}${body}${tail}$`, "u");
+	cache.set(options, pattern);
+	return pattern;
+}
+const DEFAULT_OPTIONS = {};
+/** Whether `input` is exactly what `slugify` would produce under the same options. */
+function isSlug(input, options = DEFAULT_OPTIONS) {
+	if (typeof input !== "string" || input === "" || input === "." || input === "..") return false;
+	const o = resolveOptions(options);
+	if (o.maxLength !== void 0 && measure(input, o.maxLengthUnit) > o.maxLength) return false;
+	if (o.separator !== "" && input.includes(o.separator + o.separator)) return false;
+	if (o.unicode) {
+		if (input !== input.normalize("NFKC")) return false;
+		if (o.lowercase && input !== lowercaseOf(input, o)) return false;
+		if (o.scripts !== "any" && !checkScripts(input, o.scripts).ok) return false;
+		if (o.bidi !== "allow" && !isBidiSafeComponent(input)) return false;
+	}
+	return patternFor(options).test(input);
+}
+
 //#endregion
 //#region src/slug/slugify.ts
 const NON_ASCII = /[^\x00-\x7F]/;
@@ -414,10 +480,15 @@ function slugify(input, options) {
 	if (o.leadingMarks !== void 0 && !ascii) s = s.replace(o.leadingMarks, "$1");
 	const hadTrailingSeparator = o.separator !== "" && s.endsWith(o.separator);
 	s = collapse(s, o);
-	if (o.maxLength !== void 0) s = truncateSlug(s, o.maxLength, o.separator);
+	if (o.maxLength !== void 0) s = truncateSlug(s, o.maxLength, o.separator, o.maxLengthUnit);
 	if (s === "." || s === "..") s = "";
 	if (o.preserveLeadingUnderscore && hadLeadingUnderscore && s !== "" && !s.startsWith("_")) s = "_" + s;
 	if (o.preserveTrailingSeparator && hadTrailingSeparator && s !== "") s += o.separator;
+	if (s === "" && o.fallback !== void 0) {
+		const text = typeof o.fallback === "string" ? o.fallback : o.fallback(input);
+		const { fallback: _fallback, ...rest } = options ?? {};
+		return slugify(text, rest);
+	}
 	if (o.unicode && s !== "") {
 		if (o.scripts !== "any") {
 			const check = checkScripts(s, o.scripts);
@@ -433,11 +504,11 @@ function slugify(input, options) {
 
 //#endregion
 //#region src/slug/slugger.ts
-function withSuffix(base, separator, n, maxLength) {
+function withSuffix(base, separator, n, maxLength, unit) {
 	const suffix = separator + String(n);
-	if (maxLength === void 0 || base.length + suffix.length <= maxLength) return base + suffix;
-	const room = maxLength - suffix.length;
-	const head = room > 0 ? truncateSlug(base, room, separator) : "";
+	if (maxLength === void 0 || measure(base + suffix, unit) <= maxLength) return base + suffix;
+	const room = maxLength - measure(suffix, unit);
+	const head = room > 0 ? truncateSlug(base, room, separator, unit) : "";
 	return head === "" ? String(n).slice(0, maxLength) : head + suffix;
 }
 /** A slugger that never repeats a slug: the second `"Hello"` becomes `"hello-2"`. `defaults` apply to every call. */
@@ -460,7 +531,7 @@ function createSlugger(defaults = {}) {
 		let candidate;
 		do {
 			n += 1;
-			candidate = withSuffix(base, separator, n, merged.maxLength);
+			candidate = withSuffix(base, separator, n, merged.maxLength, merged.maxLengthUnit ?? "units");
 		} while (issued.has(candidate));
 		counters.set(base, n);
 		issued.add(candidate);
@@ -483,4 +554,4 @@ function createSlugger(defaults = {}) {
 const slugifyWithCounter = createSlugger;
 
 //#endregion
-export { checkScripts, createSlugger, decamelize, detectScripts, isBidiSafeComponent, isSlug, slugify, slugifyWithCounter, truncateSlug };
+export { checkScripts, createSlugger, decamelize, detectScripts, isBidiSafeComponent, isSlug, measure, slugify, slugifyWithCounter, truncateSlug };