slugkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tung Tran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# slugkit
+
+> Tiny, type-safe **slugify** — Unicode accent folding, symbol words, and a **unique-slug** generator. **Zero dependencies**.
+
+[![CI](https://github.com/trananhtung/slugkit/actions/workflows/ci.yml/badge.svg)](https://github.com/trananhtung/slugkit/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/slugkit.svg)](https://www.npmjs.com/package/slugkit)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/slugkit)](https://bundlephobia.com/package/slugkit)
+[![types](https://img.shields.io/npm/types/slugkit.svg)](https://www.npmjs.com/package/slugkit)
+[![license](https://img.shields.io/npm/l/slugkit.svg)](./LICENSE)
+
+Turning a title into a clean URL sounds trivial until the title is `Crème brûlée
+& coffee` or `Đặng Văn A`, or until two headings slugify to the same anchor.
+`slugkit` folds accents to ASCII, turns symbols into words, and — when you need
+it — guarantees every slug in a document is unique. **Zero dependencies**, Node
+and browser.
+
+```ts
+import { slug } from "slugkit";
+
+slug("Hello, World!");          // "hello-world"
+slug("Crème brûlée & coffee");  // "creme-brulee-and-coffee"
+slug("Đặng Văn A");             // "dang-van-a"
+```
+
+## Why slugkit?
+
+- **Real Unicode folding.** Accents are normalized away (`café` → `cafe`), and the
+  letters normalization misses (`đ`, `ø`, `ß`, `æ`, `ł`, …) are mapped explicitly.
+- **Symbol words.** `&` → `and`, `%` → `percent`, `@` → `at` — opt out with
+  `symbols: false`.
+- **Unique slugs.** The `Slugger` appends `-2`, `-3`, … so a page full of repeated
+  headings still gets collision-free anchors.
+- **Configurable.** Custom separator, preserve case, `maxLength` that truncates on
+  a **word boundary**, and your own character overrides.
+- **Typed & tiny.** Full types, ESM + CJS, zero dependencies.
+
+## Install
+
+```bash
+npm install slugkit
+# or: pnpm add slugkit  /  yarn add slugkit  /  bun add slugkit
+```
+
+## `slug(input, options?)`
+
+```ts
+import { slug } from "slugkit";
+
+slug("Top 10 Tips");                          // "top-10-tips"
+slug("Müller Straße");                        // "muller-strasse"
+slug("Hello World", { separator: "_" });      // "hello_world"
+slug("Hello World", { lower: false });        // "Hello-World"
+slug("Bread & Butter", { symbols: false });   // "bread-butter"
+slug("the quick brown fox", { maxLength: 13 }); // "the-quick" (no half-words)
+slug("I ♥ JS", { charMap: { "♥": "love" } });   // "i-love-js"
+```
+
+```ts
+interface SlugOptions {
+  separator?: string;   // default "-"
+  lower?: boolean;      // default true
+  symbols?: boolean;    // default true (& → and, % → percent, …)
+  maxLength?: number;   // truncate on a word boundary
+  charMap?: Record<string, string>; // extra replacements
+}
+```
+
+## Unique slugs with `Slugger`
+
+```ts
+import { Slugger } from "slugkit";
+
+const slugger = new Slugger();
+slugger.slug("Introduction"); // "introduction"
+slugger.slug("Introduction"); // "introduction-2"
+slugger.slug("Introduction"); // "introduction-3"
+
+slugger.has("introduction-2"); // true
+slugger.reset();               // start over
+```
+
+`new Slugger(options)` applies those `SlugOptions` to every call (overridable
+per call). `createSlugger(options?)` is a factory shorthand. Perfect for building
+a table of contents:
+
+```ts
+const slugger = new Slugger();
+const anchors = headings.map((h) => ({ text: h, id: slugger.slug(h) }));
+```
+
+## Notes
+
+- Iterates by code point, so multi-byte characters and emoji are handled safely.
+- Anything that isn't a letter or number becomes a separator boundary; runs are
+  collapsed and the ends are trimmed.
+
+## Pairs well with
+
+| Need | Use |
+| --- | --- |
+| Generate a unique id (not derived from text) | [`idkit`](https://www.npmjs.com/package/idkit) |
+| Redact secrets/PII from text | [`scrubtext`](https://www.npmjs.com/package/scrubtext) |
+
+## License
+
+[MIT](./LICENSE) © Tung Tran

package/dist/index.cjs

@@ -0,0 +1,157 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  CHAR_MAP: () => CHAR_MAP,
+  Slugger: () => Slugger,
+  createSlugger: () => createSlugger,
+  slug: () => slug
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/charmap.ts
+var CHAR_MAP = {
+  // Latin letters without a clean NFKD decomposition.
+  \u0111: "d",
+  \u0110: "D",
+  \u00F0: "d",
+  \u00D0: "D",
+  \u00F8: "o",
+  \u00D8: "O",
+  \u0142: "l",
+  \u0141: "L",
+  \u00DF: "ss",
+  "\u1E9E": "SS",
+  \u00E6: "ae",
+  \u00C6: "AE",
+  \u0153: "oe",
+  \u0152: "OE",
+  \u00FE: "th",
+  \u00DE: "TH",
+  \u0131: "i",
+  \u0149: "n",
+  // Common symbols people expect to read as words.
+  "&": "and",
+  "@": "at",
+  "%": "percent",
+  "\u20AB": "dong",
+  "\u20AC": "euro",
+  $: "dollar",
+  "\xA3": "pound",
+  "\xA9": "c",
+  "\xAE": "r",
+  "\u2122": "tm"
+};
+
+// src/slug.ts
+var COMBINING_MARKS = /[̀-ͯ]/g;
+function slug(input, options = {}) {
+  const separator = options.separator ?? "-";
+  const lower = options.lower ?? true;
+  const symbols = options.symbols ?? true;
+  const map = options.charMap ? { ...CHAR_MAP, ...options.charMap } : CHAR_MAP;
+  let result = "";
+  for (const char of input.normalize("NFKC")) {
+    if (!Object.prototype.hasOwnProperty.call(map, char)) {
+      result += char;
+      continue;
+    }
+    const replacement = map[char];
+    if (new RegExp("^\\p{L}", "u").test(char)) {
+      result += replacement;
+    } else if (symbols) {
+      result += ` ${replacement} `;
+    } else {
+      result += " ";
+    }
+  }
+  result = result.normalize("NFKD").replace(COMBINING_MARKS, "");
+  if (lower) result = result.toLowerCase();
+  result = result.replace(/[^\p{L}\p{N}]+/gu, separator).replace(new RegExp(`\\${separator}{2,}`, "g"), separator);
+  result = trimSeparator(result, separator);
+  if (options.maxLength !== void 0 && result.length > options.maxLength) {
+    let cut = result.slice(0, options.maxLength);
+    const nextChar = result.slice(options.maxLength, options.maxLength + separator.length);
+    if (separator !== "" && nextChar !== separator) {
+      const lastSep = cut.lastIndexOf(separator);
+      if (lastSep > 0) cut = cut.slice(0, lastSep);
+    }
+    result = trimSeparator(cut, separator);
+  }
+  return result;
+}
+function trimSeparator(value, separator) {
+  if (separator === "") return value;
+  let start = 0;
+  let end = value.length;
+  while (value.startsWith(separator, start)) start += separator.length;
+  while (end >= start + separator.length && value.endsWith(separator, end)) {
+    end -= separator.length;
+  }
+  return value.slice(start, end);
+}
+
+// src/slugger.ts
+var Slugger = class {
+  #seen = /* @__PURE__ */ new Map();
+  #options;
+  constructor(options = {}) {
+    this.#options = options;
+  }
+  /** Slugify `input`, appending a counter when the base slug was already used. */
+  slug(input, options) {
+    const separator = options?.separator ?? this.#options.separator ?? "-";
+    const base = slug(input, { ...this.#options, ...options });
+    const count = this.#seen.get(base);
+    if (count === void 0) {
+      this.#seen.set(base, 1);
+      return base;
+    }
+    let n = count + 1;
+    let candidate = `${base}${separator}${n}`;
+    while (this.#seen.has(candidate)) {
+      n += 1;
+      candidate = `${base}${separator}${n}`;
+    }
+    this.#seen.set(base, n);
+    this.#seen.set(candidate, 1);
+    return candidate;
+  }
+  /** Whether a fully-resolved slug has been produced already. */
+  has(value) {
+    return this.#seen.has(value);
+  }
+  /** Forget all previously seen slugs. */
+  reset() {
+    this.#seen.clear();
+  }
+};
+function createSlugger(options) {
+  return new Slugger(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CHAR_MAP,
+  Slugger,
+  createSlugger,
+  slug
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/charmap.ts","../src/slug.ts","../src/slugger.ts"],"sourcesContent":["export { slug, type SlugOptions } from \"./slug.js\";\nexport { Slugger, createSlugger } from \"./slugger.js\";\nexport { CHAR_MAP } from \"./charmap.js\";\n","/**\n * Characters that Unicode NFKD normalization does **not** decompose into an\n * ASCII base letter plus combining marks, so we map them explicitly. Most\n * accented letters (é, ñ, ü, …) are handled by normalization; this covers the\n * stubborn ones (đ, ø, ß, æ, ł, …) and a few useful symbol words.\n */\nexport const CHAR_MAP: Readonly<Record<string, string>> = {\n  // Latin letters without a clean NFKD decomposition.\n  đ: \"d\",\n  Đ: \"D\",\n  ð: \"d\",\n  Ð: \"D\",\n  ø: \"o\",\n  Ø: \"O\",\n  ł: \"l\",\n  Ł: \"L\",\n  ß: \"ss\",\n  ẞ: \"SS\",\n  æ: \"ae\",\n  Æ: \"AE\",\n  œ: \"oe\",\n  Œ: \"OE\",\n  þ: \"th\",\n  Þ: \"TH\",\n  ı: \"i\",\n  ʼn: \"n\",\n  // Common symbols people expect to read as words.\n  \"&\": \"and\",\n  \"@\": \"at\",\n  \"%\": \"percent\",\n  \"₫\": \"dong\",\n  \"€\": \"euro\",\n  $: \"dollar\",\n  \"£\": \"pound\",\n  \"©\": \"c\",\n  \"®\": \"r\",\n  \"™\": \"tm\",\n};\n","import { CHAR_MAP } from \"./charmap.js\";\n\nexport interface SlugOptions {\n  /** Word separator. Default `\"-\"`. */\n  separator?: string;\n  /** Lowercase the result. Default `true`. */\n  lower?: boolean;\n  /** Expand symbols like `&` → `and`, `%` → `percent`. Default `true`. */\n  symbols?: boolean;\n  /** Truncate to at most this many characters (never ends on a separator). */\n  maxLength?: number;\n  /** Extra replacements applied before slugifying (merged over the defaults). */\n  charMap?: Record<string, string>;\n}\n\nconst COMBINING_MARKS = /[̀-ͯ]/g;\n\n/**\n * Convert arbitrary text into a clean, URL-safe slug.\n *\n * Folds Unicode accents (`café` → `cafe`, `Việt Nam` → `viet-nam`), maps\n * stubborn letters and symbols (`đ` → `d`, `&` → `and`), lowercases, and joins\n * words with a separator. Zero dependencies.\n *\n * ```ts\n * slug(\"Hello, World!\");          // \"hello-world\"\n * slug(\"Crème brûlée & coffee\");  // \"creme-brulee-and-coffee\"\n * slug(\"Đặng Văn A\");             // \"dang-van-a\"\n * ```\n */\nexport function slug(input: string, options: SlugOptions = {}): string {\n  const separator = options.separator ?? \"-\";\n  const lower = options.lower ?? true;\n  const symbols = options.symbols ?? true;\n  const map = options.charMap ? { ...CHAR_MAP, ...options.charMap } : CHAR_MAP;\n\n  let result = \"\";\n  // Iterate by code point so multi-byte characters map correctly.\n  for (const char of input.normalize(\"NFKC\")) {\n    if (!Object.prototype.hasOwnProperty.call(map, char)) {\n      result += char;\n      continue;\n    }\n    const replacement = map[char] as string;\n    if (/^\\p{L}/u.test(char)) {\n      // Letter substitution (đ → d): glue it to its neighbours.\n      result += replacement;\n    } else if (symbols) {\n      // Symbol word (& → and): pad so it becomes its own slug word.\n      result += ` ${replacement} `;\n    } else {\n      result += \" \";\n    }\n  }\n\n  // Decompose remaining accents and strip the combining marks.\n  result = result.normalize(\"NFKD\").replace(COMBINING_MARKS, \"\");\n\n  if (lower) result = result.toLowerCase();\n\n  // Everything that is not a letter or number becomes a separator boundary.\n  result = result\n    .replace(/[^\\p{L}\\p{N}]+/gu, separator)\n    .replace(new RegExp(`\\\\${separator}{2,}`, \"g\"), separator);\n\n  // Trim separators from both ends.\n  result = trimSeparator(result, separator);\n\n  if (options.maxLength !== undefined && result.length > options.maxLength) {\n    let cut = result.slice(0, options.maxLength);\n    // If the cut landed mid-word, fall back to the last whole word.\n    const nextChar = result.slice(options.maxLength, options.maxLength + separator.length);\n    if (separator !== \"\" && nextChar !== separator) {\n      const lastSep = cut.lastIndexOf(separator);\n      if (lastSep > 0) cut = cut.slice(0, lastSep);\n    }\n    result = trimSeparator(cut, separator);\n  }\n  return result;\n}\n\nfunction trimSeparator(value: string, separator: string): string {\n  if (separator === \"\") return value;\n  let start = 0;\n  let end = value.length;\n  while (value.startsWith(separator, start)) start += separator.length;\n  while (end >= start + separator.length && value.endsWith(separator, end)) {\n    end -= separator.length;\n  }\n  return value.slice(start, end);\n}\n","import { slug, type SlugOptions } from \"./slug.js\";\n\n/**\n * A stateful slug generator that guarantees **unique** output. Repeated inputs\n * get a numeric suffix (`-2`, `-3`, …) — ideal for headings, anchors, or any\n * set of slugs that must not collide.\n *\n * ```ts\n * const slugger = new Slugger();\n * slugger.slug(\"Hello\");  // \"hello\"\n * slugger.slug(\"Hello\");  // \"hello-2\"\n * slugger.slug(\"Hello\");  // \"hello-3\"\n * ```\n */\nexport class Slugger {\n  #seen = new Map<string, number>();\n  #options: SlugOptions;\n\n  constructor(options: SlugOptions = {}) {\n    this.#options = options;\n  }\n\n  /** Slugify `input`, appending a counter when the base slug was already used. */\n  slug(input: string, options?: SlugOptions): string {\n    const separator = options?.separator ?? this.#options.separator ?? \"-\";\n    const base = slug(input, { ...this.#options, ...options });\n\n    const count = this.#seen.get(base);\n    if (count === undefined) {\n      this.#seen.set(base, 1);\n      return base;\n    }\n\n    // Find the next free `${base}${separator}${n}`.\n    let n = count + 1;\n    let candidate = `${base}${separator}${n}`;\n    while (this.#seen.has(candidate)) {\n      n += 1;\n      candidate = `${base}${separator}${n}`;\n    }\n    this.#seen.set(base, n);\n    this.#seen.set(candidate, 1);\n    return candidate;\n  }\n\n  /** Whether a fully-resolved slug has been produced already. */\n  has(value: string): boolean {\n    return this.#seen.has(value);\n  }\n\n  /** Forget all previously seen slugs. */\n  reset(): void {\n    this.#seen.clear();\n  }\n}\n\n/** Convenience factory for {@link Slugger}. */\nexport function createSlugger(options?: SlugOptions): Slugger {\n  return new Slugger(options);\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+interface SlugOptions {
+    /** Word separator. Default `"-"`. */
+    separator?: string;
+    /** Lowercase the result. Default `true`. */
+    lower?: boolean;
+    /** Expand symbols like `&` → `and`, `%` → `percent`. Default `true`. */
+    symbols?: boolean;
+    /** Truncate to at most this many characters (never ends on a separator). */
+    maxLength?: number;
+    /** Extra replacements applied before slugifying (merged over the defaults). */
+    charMap?: Record<string, string>;
+}
+/**
+ * Convert arbitrary text into a clean, URL-safe slug.
+ *
+ * Folds Unicode accents (`café` → `cafe`, `Việt Nam` → `viet-nam`), maps
+ * stubborn letters and symbols (`đ` → `d`, `&` → `and`), lowercases, and joins
+ * words with a separator. Zero dependencies.
+ *
+ * ```ts
+ * slug("Hello, World!");          // "hello-world"
+ * slug("Crème brûlée & coffee");  // "creme-brulee-and-coffee"
+ * slug("Đặng Văn A");             // "dang-van-a"
+ * ```
+ */
+declare function slug(input: string, options?: SlugOptions): string;
+
+/**
+ * A stateful slug generator that guarantees **unique** output. Repeated inputs
+ * get a numeric suffix (`-2`, `-3`, …) — ideal for headings, anchors, or any
+ * set of slugs that must not collide.
+ *
+ * ```ts
+ * const slugger = new Slugger();
+ * slugger.slug("Hello");  // "hello"
+ * slugger.slug("Hello");  // "hello-2"
+ * slugger.slug("Hello");  // "hello-3"
+ * ```
+ */
+declare class Slugger {
+    #private;
+    constructor(options?: SlugOptions);
+    /** Slugify `input`, appending a counter when the base slug was already used. */
+    slug(input: string, options?: SlugOptions): string;
+    /** Whether a fully-resolved slug has been produced already. */
+    has(value: string): boolean;
+    /** Forget all previously seen slugs. */
+    reset(): void;
+}
+/** Convenience factory for {@link Slugger}. */
+declare function createSlugger(options?: SlugOptions): Slugger;
+
+/**
+ * Characters that Unicode NFKD normalization does **not** decompose into an
+ * ASCII base letter plus combining marks, so we map them explicitly. Most
+ * accented letters (é, ñ, ü, …) are handled by normalization; this covers the
+ * stubborn ones (đ, ø, ß, æ, ł, …) and a few useful symbol words.
+ */
+declare const CHAR_MAP: Readonly<Record<string, string>>;
+
+export { CHAR_MAP, type SlugOptions, Slugger, createSlugger, slug };

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+interface SlugOptions {
+    /** Word separator. Default `"-"`. */
+    separator?: string;
+    /** Lowercase the result. Default `true`. */
+    lower?: boolean;
+    /** Expand symbols like `&` → `and`, `%` → `percent`. Default `true`. */
+    symbols?: boolean;
+    /** Truncate to at most this many characters (never ends on a separator). */
+    maxLength?: number;
+    /** Extra replacements applied before slugifying (merged over the defaults). */
+    charMap?: Record<string, string>;
+}
+/**
+ * Convert arbitrary text into a clean, URL-safe slug.
+ *
+ * Folds Unicode accents (`café` → `cafe`, `Việt Nam` → `viet-nam`), maps
+ * stubborn letters and symbols (`đ` → `d`, `&` → `and`), lowercases, and joins
+ * words with a separator. Zero dependencies.
+ *
+ * ```ts
+ * slug("Hello, World!");          // "hello-world"
+ * slug("Crème brûlée & coffee");  // "creme-brulee-and-coffee"
+ * slug("Đặng Văn A");             // "dang-van-a"
+ * ```
+ */
+declare function slug(input: string, options?: SlugOptions): string;
+
+/**
+ * A stateful slug generator that guarantees **unique** output. Repeated inputs
+ * get a numeric suffix (`-2`, `-3`, …) — ideal for headings, anchors, or any
+ * set of slugs that must not collide.
+ *
+ * ```ts
+ * const slugger = new Slugger();
+ * slugger.slug("Hello");  // "hello"
+ * slugger.slug("Hello");  // "hello-2"
+ * slugger.slug("Hello");  // "hello-3"
+ * ```
+ */
+declare class Slugger {
+    #private;
+    constructor(options?: SlugOptions);
+    /** Slugify `input`, appending a counter when the base slug was already used. */
+    slug(input: string, options?: SlugOptions): string;
+    /** Whether a fully-resolved slug has been produced already. */
+    has(value: string): boolean;
+    /** Forget all previously seen slugs. */
+    reset(): void;
+}
+/** Convenience factory for {@link Slugger}. */
+declare function createSlugger(options?: SlugOptions): Slugger;
+
+/**
+ * Characters that Unicode NFKD normalization does **not** decompose into an
+ * ASCII base letter plus combining marks, so we map them explicitly. Most
+ * accented letters (é, ñ, ü, …) are handled by normalization; this covers the
+ * stubborn ones (đ, ø, ß, æ, ł, …) and a few useful symbol words.
+ */
+declare const CHAR_MAP: Readonly<Record<string, string>>;
+
+export { CHAR_MAP, type SlugOptions, Slugger, createSlugger, slug };

package/dist/index.js

@@ -0,0 +1,127 @@
+// src/charmap.ts
+var CHAR_MAP = {
+  // Latin letters without a clean NFKD decomposition.
+  \u0111: "d",
+  \u0110: "D",
+  \u00F0: "d",
+  \u00D0: "D",
+  \u00F8: "o",
+  \u00D8: "O",
+  \u0142: "l",
+  \u0141: "L",
+  \u00DF: "ss",
+  "\u1E9E": "SS",
+  \u00E6: "ae",
+  \u00C6: "AE",
+  \u0153: "oe",
+  \u0152: "OE",
+  \u00FE: "th",
+  \u00DE: "TH",
+  \u0131: "i",
+  \u0149: "n",
+  // Common symbols people expect to read as words.
+  "&": "and",
+  "@": "at",
+  "%": "percent",
+  "\u20AB": "dong",
+  "\u20AC": "euro",
+  $: "dollar",
+  "\xA3": "pound",
+  "\xA9": "c",
+  "\xAE": "r",
+  "\u2122": "tm"
+};
+
+// src/slug.ts
+var COMBINING_MARKS = /[̀-ͯ]/g;
+function slug(input, options = {}) {
+  const separator = options.separator ?? "-";
+  const lower = options.lower ?? true;
+  const symbols = options.symbols ?? true;
+  const map = options.charMap ? { ...CHAR_MAP, ...options.charMap } : CHAR_MAP;
+  let result = "";
+  for (const char of input.normalize("NFKC")) {
+    if (!Object.prototype.hasOwnProperty.call(map, char)) {
+      result += char;
+      continue;
+    }
+    const replacement = map[char];
+    if (new RegExp("^\\p{L}", "u").test(char)) {
+      result += replacement;
+    } else if (symbols) {
+      result += ` ${replacement} `;
+    } else {
+      result += " ";
+    }
+  }
+  result = result.normalize("NFKD").replace(COMBINING_MARKS, "");
+  if (lower) result = result.toLowerCase();
+  result = result.replace(/[^\p{L}\p{N}]+/gu, separator).replace(new RegExp(`\\${separator}{2,}`, "g"), separator);
+  result = trimSeparator(result, separator);
+  if (options.maxLength !== void 0 && result.length > options.maxLength) {
+    let cut = result.slice(0, options.maxLength);
+    const nextChar = result.slice(options.maxLength, options.maxLength + separator.length);
+    if (separator !== "" && nextChar !== separator) {
+      const lastSep = cut.lastIndexOf(separator);
+      if (lastSep > 0) cut = cut.slice(0, lastSep);
+    }
+    result = trimSeparator(cut, separator);
+  }
+  return result;
+}
+function trimSeparator(value, separator) {
+  if (separator === "") return value;
+  let start = 0;
+  let end = value.length;
+  while (value.startsWith(separator, start)) start += separator.length;
+  while (end >= start + separator.length && value.endsWith(separator, end)) {
+    end -= separator.length;
+  }
+  return value.slice(start, end);
+}
+
+// src/slugger.ts
+var Slugger = class {
+  #seen = /* @__PURE__ */ new Map();
+  #options;
+  constructor(options = {}) {
+    this.#options = options;
+  }
+  /** Slugify `input`, appending a counter when the base slug was already used. */
+  slug(input, options) {
+    const separator = options?.separator ?? this.#options.separator ?? "-";
+    const base = slug(input, { ...this.#options, ...options });
+    const count = this.#seen.get(base);
+    if (count === void 0) {
+      this.#seen.set(base, 1);
+      return base;
+    }
+    let n = count + 1;
+    let candidate = `${base}${separator}${n}`;
+    while (this.#seen.has(candidate)) {
+      n += 1;
+      candidate = `${base}${separator}${n}`;
+    }
+    this.#seen.set(base, n);
+    this.#seen.set(candidate, 1);
+    return candidate;
+  }
+  /** Whether a fully-resolved slug has been produced already. */
+  has(value) {
+    return this.#seen.has(value);
+  }
+  /** Forget all previously seen slugs. */
+  reset() {
+    this.#seen.clear();
+  }
+};
+function createSlugger(options) {
+  return new Slugger(options);
+}
+export {
+  CHAR_MAP,
+  Slugger,
+  createSlugger,
+  slug
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/charmap.ts","../src/slug.ts","../src/slugger.ts"],"sourcesContent":["/**\n * Characters that Unicode NFKD normalization does **not** decompose into an\n * ASCII base letter plus combining marks, so we map them explicitly. Most\n * accented letters (é, ñ, ü, …) are handled by normalization; this covers the\n * stubborn ones (đ, ø, ß, æ, ł, …) and a few useful symbol words.\n */\nexport const CHAR_MAP: Readonly<Record<string, string>> = {\n  // Latin letters without a clean NFKD decomposition.\n  đ: \"d\",\n  Đ: \"D\",\n  ð: \"d\",\n  Ð: \"D\",\n  ø: \"o\",\n  Ø: \"O\",\n  ł: \"l\",\n  Ł: \"L\",\n  ß: \"ss\",\n  ẞ: \"SS\",\n  æ: \"ae\",\n  Æ: \"AE\",\n  œ: \"oe\",\n  Œ: \"OE\",\n  þ: \"th\",\n  Þ: \"TH\",\n  ı: \"i\",\n  ʼn: \"n\",\n  // Common symbols people expect to read as words.\n  \"&\": \"and\",\n  \"@\": \"at\",\n  \"%\": \"percent\",\n  \"₫\": \"dong\",\n  \"€\": \"euro\",\n  $: \"dollar\",\n  \"£\": \"pound\",\n  \"©\": \"c\",\n  \"®\": \"r\",\n  \"™\": \"tm\",\n};\n","import { CHAR_MAP } from \"./charmap.js\";\n\nexport interface SlugOptions {\n  /** Word separator. Default `\"-\"`. */\n  separator?: string;\n  /** Lowercase the result. Default `true`. */\n  lower?: boolean;\n  /** Expand symbols like `&` → `and`, `%` → `percent`. Default `true`. */\n  symbols?: boolean;\n  /** Truncate to at most this many characters (never ends on a separator). */\n  maxLength?: number;\n  /** Extra replacements applied before slugifying (merged over the defaults). */\n  charMap?: Record<string, string>;\n}\n\nconst COMBINING_MARKS = /[̀-ͯ]/g;\n\n/**\n * Convert arbitrary text into a clean, URL-safe slug.\n *\n * Folds Unicode accents (`café` → `cafe`, `Việt Nam` → `viet-nam`), maps\n * stubborn letters and symbols (`đ` → `d`, `&` → `and`), lowercases, and joins\n * words with a separator. Zero dependencies.\n *\n * ```ts\n * slug(\"Hello, World!\");          // \"hello-world\"\n * slug(\"Crème brûlée & coffee\");  // \"creme-brulee-and-coffee\"\n * slug(\"Đặng Văn A\");             // \"dang-van-a\"\n * ```\n */\nexport function slug(input: string, options: SlugOptions = {}): string {\n  const separator = options.separator ?? \"-\";\n  const lower = options.lower ?? true;\n  const symbols = options.symbols ?? true;\n  const map = options.charMap ? { ...CHAR_MAP, ...options.charMap } : CHAR_MAP;\n\n  let result = \"\";\n  // Iterate by code point so multi-byte characters map correctly.\n  for (const char of input.normalize(\"NFKC\")) {\n    if (!Object.prototype.hasOwnProperty.call(map, char)) {\n      result += char;\n      continue;\n    }\n    const replacement = map[char] as string;\n    if (/^\\p{L}/u.test(char)) {\n      // Letter substitution (đ → d): glue it to its neighbours.\n      result += replacement;\n    } else if (symbols) {\n      // Symbol word (& → and): pad so it becomes its own slug word.\n      result += ` ${replacement} `;\n    } else {\n      result += \" \";\n    }\n  }\n\n  // Decompose remaining accents and strip the combining marks.\n  result = result.normalize(\"NFKD\").replace(COMBINING_MARKS, \"\");\n\n  if (lower) result = result.toLowerCase();\n\n  // Everything that is not a letter or number becomes a separator boundary.\n  result = result\n    .replace(/[^\\p{L}\\p{N}]+/gu, separator)\n    .replace(new RegExp(`\\\\${separator}{2,}`, \"g\"), separator);\n\n  // Trim separators from both ends.\n  result = trimSeparator(result, separator);\n\n  if (options.maxLength !== undefined && result.length > options.maxLength) {\n    let cut = result.slice(0, options.maxLength);\n    // If the cut landed mid-word, fall back to the last whole word.\n    const nextChar = result.slice(options.maxLength, options.maxLength + separator.length);\n    if (separator !== \"\" && nextChar !== separator) {\n      const lastSep = cut.lastIndexOf(separator);\n      if (lastSep > 0) cut = cut.slice(0, lastSep);\n    }\n    result = trimSeparator(cut, separator);\n  }\n  return result;\n}\n\nfunction trimSeparator(value: string, separator: string): string {\n  if (separator === \"\") return value;\n  let start = 0;\n  let end = value.length;\n  while (value.startsWith(separator, start)) start += separator.length;\n  while (end >= start + separator.length && value.endsWith(separator, end)) {\n    end -= separator.length;\n  }\n  return value.slice(start, end);\n}\n","import { slug, type SlugOptions } from \"./slug.js\";\n\n/**\n * A stateful slug generator that guarantees **unique** output. Repeated inputs\n * get a numeric suffix (`-2`, `-3`, …) — ideal for headings, anchors, or any\n * set of slugs that must not collide.\n *\n * ```ts\n * const slugger = new Slugger();\n * slugger.slug(\"Hello\");  // \"hello\"\n * slugger.slug(\"Hello\");  // \"hello-2\"\n * slugger.slug(\"Hello\");  // \"hello-3\"\n * ```\n */\nexport class Slugger {\n  #seen = new Map<string, number>();\n  #options: SlugOptions;\n\n  constructor(options: SlugOptions = {}) {\n    this.#options = options;\n  }\n\n  /** Slugify `input`, appending a counter when the base slug was already used. */\n  slug(input: string, options?: SlugOptions): string {\n    const separator = options?.separator ?? this.#options.separator ?? \"-\";\n    const base = slug(input, { ...this.#options, ...options });\n\n    const count = this.#seen.get(base);\n    if (count === undefined) {\n      this.#seen.set(base, 1);\n      return base;\n    }\n\n    // Find the next free `${base}${separator}${n}`.\n    let n = count + 1;\n    let candidate = `${base}${separator}${n}`;\n    while (this.#seen.has(candidate)) {\n      n += 1;\n      candidate = `${base}${separator}${n}`;\n    }\n    this.#seen.set(base, n);\n    this.#seen.set(candidate, 1);\n    return candidate;\n  }\n\n  /** Whether a fully-resolved slug has been produced already. */\n  has(value: string): boolean {\n    return this.#seen.has(value);\n  }\n\n  /** Forget all previously seen slugs. */\n  reset(): void {\n    this.#seen.clear();\n  }\n}\n\n/** Convenience factory for {@link Slugger}. */\nexport function createSlugger(options?: SlugOptions): Slugger {\n  return new Slugger(options);\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "slugkit",
+  "version": "0.1.0",
+  "description": "Tiny, type-safe slugify — Unicode accent folding, symbol words, and a unique-slug generator. Zero dependencies.",
+  "keywords": [
+    "slug",
+    "slugify",
+    "url-slug",
+    "permalink",
+    "unicode",
+    "diacritics",
+    "transliterate",
+    "unique",
+    "anchor",
+    "typescript",
+    "zero-dependency"
+  ],
+  "license": "MIT",
+  "author": "Tung Tran (https://github.com/trananhtung)",
+  "homepage": "https://github.com/trananhtung/slugkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/trananhtung/slugkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/trananhtung/slugkit/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.10",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}