text-sanctifier 1.3.4 → 1.3.6

package/dist/types/sanctifyText.d.ts

@@ -1,18 +1,83 @@
 /**
- * @typedef {Object} SanctifyOptions
- * @property {boolean} [purgeInvisibleChars]
- * @property {boolean} [purgeEmojis]
- * @property {boolean} [nukeControls]
- * @property {boolean} [keyboardOnlyFilter]
- * @property {boolean} [normalizeNewlines]
- * @property {boolean} [trimSpacesAroundNewlines]
- * @property {boolean} [collapseNewLines]
- * @property {boolean} [preserveParagraphs]
- * @property {boolean} [collapseSpaces]
- * @property {boolean} [finalTrim]
- * @property {number} [maxLength]
- * @property {'throw'|'truncate'|'noop'} [onMaxLength]
+ * Strict sanitizer:
+ * - Purge emojis
+ * - Collapse all newlines
+ * - Collapse spaces
+ * - Nuke control characters
+ * @param {string} text
+ * @returns {string}
  */
+export function sanctifyStrict(text: string): string;
+/**
+ * Loose sanitizer:
+ * - Collapse spaces
+ * - Preserve paragraphs
+ * - Normalize newlines
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanctifyLoose(text: string): string;
+/**
+ * Keyboard-only (with emojis):
+ * - Keeps emojis and printable ASCII
+ * - Strips non-standard characters
+ * - Normalizes typographic trash
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanctifyKeyboardOnlyEmoji(text: string): string;
+/**
+ * Keyboard-only (strict):
+ * - Removes emojis
+ * - Collapses all whitespace
+ * - Restricts to printable ASCII only
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanctifyKeyboardOnly(text: string): string;
+/**
+ * Pasted text and model output:
+ * - Look-alike spaces (NBSP, narrow NBSP, typographic spaces) become ordinary spaces,
+ *   so words never run together
+ * - Zero-width spaces, word joiners and BOMs are removed
+ * - Newlines are normalized to `\n`
+ * Keeps emoji joiners, variation selectors, bidi marks, indentation and line breaks.
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanctifyPasted(text: string): string;
+/**
+ * Text Sanctifier
+ *
+ * Brutal text normalizer and invisible trash scrubber,
+ * configurable to kill whatever ghosts you want dead.
+ *
+ * ⚠️ Note: This is plain-text normalization/filtering — not an HTML/XSS sanitizer.
+ *
+ * @param {string} text
+ * @param {boolean} [purgeInvisibleChars=false] - Remove ZWSP, NBSP, bidi, tags, variation selectors, etc.
+ * @param {boolean} [purgeEmojis=false] - Remove emoji characters entirely.
+ * @param {boolean} [nukeControls=false] - Remove non-whitespace control characters.
+ * @param {boolean} [keyboardOnlyFilter=false] - Keep printable ASCII + full emoji sequences only (drops other Unicode).
+ * @param {boolean} [normalizeNewlines=false] - Convert all newlines to `\n`.
+ * @param {boolean} [trimSpacesAroundNewlines=false] - Remove spaces/tabs around newlines.
+ * @param {boolean} [collapseNewLines=false] - Collapse `\n` runs (optionally preserve paragraphs).
+ * @param {boolean} [preserveParagraphs=false] - Preserve paragraph breaks when collapsing newlines.
+ * @param {boolean} [collapseSpaces=false] - Collapse multiple spaces into one.
+ * @param {boolean} [finalTrim=false] - `.trim()` the final output (head/tail).
+ * @param {number} [maxLength=Infinity] - Hard input length cap (UTF-16 code units via `text.length`).
+ * @param {'throw'|'truncate'|'noop'} [onMaxLength='throw'] - Behavior when `text.length` exceeds `maxLength`:
+ *   - `'throw'`: throw a `RangeError`
+ *   - `'truncate'`: slice to `maxLength` before processing
+ *   - `'noop'`: return the original input unchanged (skips processing)
+ * @param {boolean} [normalizeSpaces=false] - Replace look-alike spaces with an ordinary space. Runs first,
+ *   so `purgeInvisibleChars` no longer joins the words around them.
+ * @param {boolean} [purgeZeroWidthSpaces=false] - Remove zero-width spaces, word joiners and BOMs only.
+ * @returns {string}
+ * @throws {TypeError} If `text` is not a string.
+ * @throws {RangeError} If input exceeds `maxLength` and `onMaxLength` is `'throw'`.
+ */
+export function sanctifyText(text: string, purgeInvisibleChars?: boolean, purgeEmojis?: boolean, nukeControls?: boolean, keyboardOnlyFilter?: boolean, normalizeNewlines?: boolean, trimSpacesAroundNewlines?: boolean, collapseNewLines?: boolean, preserveParagraphs?: boolean, collapseSpaces?: boolean, finalTrim?: boolean, maxLength?: number, onMaxLength?: "throw" | "truncate" | "noop", normalizeSpaces?: boolean, purgeZeroWidthSpaces?: boolean): string;
 /**
  * Summons a customized sanctifier function with pre-bound booleans.
  *
@@ -31,9 +96,36 @@
  * @param {boolean} [defaultOptions.finalTrim]
  * @param {number} [defaultOptions.maxLength=Infinity] - Hard input length cap (UTF-16 code units).
  * @param {'throw' | 'truncate' | 'noop'} [defaultOptions.onMaxLength='throw'] - Behavior when input exceeds maxLength.
+ * @param {boolean} [defaultOptions.normalizeSpaces]
+ * @param {boolean} [defaultOptions.purgeZeroWidthSpaces]
  * @returns {(text: string) => string}
+ *
+ * The presets are attached as properties (`summonSanctifier.strict`, `.loose`,
+ * `.keyboardOnlyEmoji`, `.keyboardOnly`, `.pasted`) and are also standalone exports.
+ * Built in a call marked pure, so a bundle that imports only a preset leaves it out.
+ * @type {typeof createSanctifier & {
+ *   strict: typeof sanctifyStrict,
+ *   loose: typeof sanctifyLoose,
+ *   keyboardOnlyEmoji: typeof sanctifyKeyboardOnlyEmoji,
+ *   keyboardOnly: typeof sanctifyKeyboardOnly,
+ *   pasted: typeof sanctifyPasted,
+ * }}
  */
-export function summonSanctifier(defaultOptions?: {
+export const summonSanctifier: typeof createSanctifier & {
+    strict: typeof sanctifyStrict;
+    loose: typeof sanctifyLoose;
+    keyboardOnlyEmoji: typeof sanctifyKeyboardOnlyEmoji;
+    keyboardOnly: typeof sanctifyKeyboardOnly;
+    pasted: typeof sanctifyPasted;
+};
+/**
+ * Look-alike spaces: the `nonbreaking_space` category except U+3000, the ordinary
+ * space of CJK text. A test checks this against the category table.
+ */
+export const SPACE_LOOKALIKES_REGEX: RegExp;
+/** Zero-width space, word joiner and BOM: invisible and never needed in plain text. */
+export const ZERO_WIDTH_SPACES_REGEX: RegExp;
+export type SanctifyOptions = {
     purgeInvisibleChars?: boolean;
     purgeEmojis?: boolean;
     nukeControls?: boolean;
@@ -46,87 +138,60 @@ export function summonSanctifier(defaultOptions?: {
     finalTrim?: boolean;
     maxLength?: number;
     onMaxLength?: "throw" | "truncate" | "noop";
-}): (text: string) => string;
-export namespace summonSanctifier {
-    /**
-     * Strict sanitizer:
-     * - Purge emojis
-     * - Collapse all newlines
-     * - Collapse spaces
-     * - Nuke control characters
-     */
-    /** @param {string} text @returns {string} */
-    function strict(text: string): string;
-    /**
-     * Loose sanitizer:
-     * - Collapse spaces
-     * - Preserve paragraphs
-     * - Normalize newlines
-     */
-    /** @param {string} text @returns {string} */
-    function loose(text: string): string;
     /**
-     * Keyboard-only (with emojis):
-     * - Keeps emojis and printable ASCII
-     * - Strips non-standard characters
-     * - Normalizes typographic trash
+     * - Replace look-alike spaces with an ordinary space (runs first).
      */
-    /** @param {string} text @returns {string} */
-    function keyboardOnlyEmoji(text: string): string;
+    normalizeSpaces?: boolean;
     /**
-     * Keyboard-only (strict):
-     * - Removes emojis
-     * - Collapses all whitespace
-     * - Restricts to printable ASCII only
+     * - Remove U+200B, U+2060 and U+FEFF only, keeping joiners and selectors.
      */
-    /** @param {string} text @returns {string} */
-    function keyboardOnly(text: string): string;
-}
-/**
- * Text Sanctifier
- *
- * Brutal text normalizer and invisible trash scrubber,
- * configurable to kill whatever ghosts you want dead.
- *
- * ⚠️ Note: This is plain-text normalization/filtering — not an HTML/XSS sanitizer.
- *
- * @param {string} text
- * @param {boolean} [purgeInvisibleChars=false] - Remove ZWSP, NBSP, bidi, tags, variation selectors, etc.
- * @param {boolean} [purgeEmojis=false] - Remove emoji characters entirely.
- * @param {boolean} [nukeControls=false] - Remove non-whitespace control characters.
- * @param {boolean} [keyboardOnlyFilter=false] - Keep printable ASCII + full emoji sequences only (drops other Unicode).
- * @param {boolean} [normalizeNewlines=false] - Convert all newlines to `\n`.
- * @param {boolean} [trimSpacesAroundNewlines=false] - Remove spaces/tabs around newlines.
- * @param {boolean} [collapseNewLines=false] - Collapse `\n` runs (optionally preserve paragraphs).
- * @param {boolean} [preserveParagraphs=false] - Preserve paragraph breaks when collapsing newlines.
- * @param {boolean} [collapseSpaces=false] - Collapse multiple spaces into one.
- * @param {boolean} [finalTrim=false] - `.trim()` the final output (head/tail).
- * @param {number} [maxLength=Infinity] - Hard input length cap (UTF-16 code units via `text.length`).
- * @param {'throw'|'truncate'|'noop'} [onMaxLength='throw'] - Behavior when `text.length` exceeds `maxLength`:
- *   - `'throw'`: throw a `RangeError`
- *   - `'truncate'`: slice to `maxLength` before processing
- *   - `'noop'`: return the original input unchanged (skips processing)
- * @returns {string}
- * @throws {TypeError} If `text` is not a string.
- * @throws {RangeError} If input exceeds `maxLength` and `onMaxLength` is `'throw'`.
- */
-export function sanctifyText(text: string, purgeInvisibleChars?: boolean, purgeEmojis?: boolean, nukeControls?: boolean, keyboardOnlyFilter?: boolean, normalizeNewlines?: boolean, trimSpacesAroundNewlines?: boolean, collapseNewLines?: boolean, preserveParagraphs?: boolean, collapseSpaces?: boolean, finalTrim?: boolean, maxLength?: number, onMaxLength?: "throw" | "truncate" | "noop"): string;
+    purgeZeroWidthSpaces?: boolean;
+};
+import { CONTROL_CHARS_REGEX } from './categories.generated.js';
+import { INVISIBLE_TRASH_REGEX } from './categories.generated.js';
+import { ASCII_KEYBOARD_SAFE_REGEX } from './textPatterns.js';
+import { EMOJI_REGEX } from './textPatterns.js';
+import { normalizeTypographicJank } from './textPatterns.js';
 /**
- * Normalizes typographic Unicode punctuation into ASCII equivalents.
- * @param {string} text
- * @returns {string}
+ * @typedef {Object} SanctifyOptions
+ * @property {boolean} [purgeInvisibleChars]
+ * @property {boolean} [purgeEmojis]
+ * @property {boolean} [nukeControls]
+ * @property {boolean} [keyboardOnlyFilter]
+ * @property {boolean} [normalizeNewlines]
+ * @property {boolean} [trimSpacesAroundNewlines]
+ * @property {boolean} [collapseNewLines]
+ * @property {boolean} [preserveParagraphs]
+ * @property {boolean} [collapseSpaces]
+ * @property {boolean} [finalTrim]
+ * @property {number} [maxLength]
+ * @property {'throw'|'truncate'|'noop'} [onMaxLength]
+ * @property {boolean} [normalizeSpaces] - Replace look-alike spaces with an ordinary space (runs first).
+ * @property {boolean} [purgeZeroWidthSpaces] - Remove U+200B, U+2060 and U+FEFF only, keeping joiners and selectors.
  */
-export function normalizeTypographicJank(text: string): string;
 /**
- * Matches any character that is NOT:
- * - Printable ASCII (U+0020–U+007E)
- * - Newline characters: \n (LF), \r (CR)
- * This allows for \n, \r, and \r\n line endings.
+ * Summons a customized sanctifier function with pre-bound booleans.
+ *
+ * Accepts full flag names and returns a text-cleaning function.
+ *
+ * @param {Object} [defaultOptions={}]
+ * @param {boolean} [defaultOptions.purgeInvisibleChars]
+ * @param {boolean} [defaultOptions.purgeEmojis]
+ * @param {boolean} [defaultOptions.nukeControls]
+ * @param {boolean} [defaultOptions.keyboardOnlyFilter]
+ * @param {boolean} [defaultOptions.normalizeNewlines]
+ * @param {boolean} [defaultOptions.trimSpacesAroundNewlines]
+ * @param {boolean} [defaultOptions.collapseNewLines]
+ * @param {boolean} [defaultOptions.preserveParagraphs]
+ * @param {boolean} [defaultOptions.collapseSpaces]
+ * @param {boolean} [defaultOptions.finalTrim]
+ * @param {number} [defaultOptions.maxLength=Infinity] - Hard input length cap (UTF-16 code units).
+ * @param {'throw' | 'truncate' | 'noop'} [defaultOptions.onMaxLength='throw'] - Behavior when input exceeds maxLength.
+ * @param {boolean} [defaultOptions.normalizeSpaces]
+ * @param {boolean} [defaultOptions.purgeZeroWidthSpaces]
+ * @returns {(text: string) => string}
  */
-export const ASCII_KEYBOARD_SAFE_REGEX: RegExp;
-/** @type {RegExp} */
-export let EMOJI_REGEX: RegExp;
-export type SanctifyOptions = {
+declare function createSanctifier(defaultOptions?: {
     purgeInvisibleChars?: boolean;
     purgeEmojis?: boolean;
     nukeControls?: boolean;
@@ -139,7 +204,7 @@ export type SanctifyOptions = {
     finalTrim?: boolean;
     maxLength?: number;
     onMaxLength?: "throw" | "truncate" | "noop";
-};
-import { CONTROL_CHARS_REGEX } from './categories.generated.js';
-import { INVISIBLE_TRASH_REGEX } from './categories.generated.js';
-export { CONTROL_CHARS_REGEX, INVISIBLE_TRASH_REGEX };
+    normalizeSpaces?: boolean;
+    purgeZeroWidthSpaces?: boolean;
+}): (text: string) => string;
+export { CONTROL_CHARS_REGEX, INVISIBLE_TRASH_REGEX, ASCII_KEYBOARD_SAFE_REGEX, EMOJI_REGEX, normalizeTypographicJank };

package/dist/types/textPatterns.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalizes typographic Unicode punctuation into ASCII equivalents.
+ * @param {string} text
+ * @returns {string}
+ */
+export function normalizeTypographicJank(text: string): string;
+/**
+ * Matches any character that is NOT:
+ * - Printable ASCII (U+0020–U+007E)
+ * - Newline characters: \n (LF), \r (CR)
+ * This allows for \n, \r, and \r\n line endings.
+ */
+export const ASCII_KEYBOARD_SAFE_REGEX: RegExp;
+/** @type {RegExp} */
+export const EMOJI_REGEX: RegExp;

package/dist/types/version.generated.d.ts

@@ -0,0 +1,2 @@
+/** The installed version of text-sanctifier, as in its package.json. */
+export const VERSION: "1.3.6";

package/package.json

@@ -1,80 +1,79 @@
-{
-  "name": "text-sanctifier",
-  "version": "1.3.4",
-  "type": "module",
-  "description": "A brutal text normalizer and invisible trash scrubber for modern web projects.",
-  "engines": {
-    "node": ">=18"
-  },
-  "main": "./src/index.js",
-  "module": "./src/index.js",
-  "browser": "./dist/text-sanctifier.min.js",
-  "bin": {
-    "text-sanctifier": "bin/text-sanctifier.js"
-  },
-  "files": [
-    "src",
-    "bin",
-    "dist/text-sanctifier.min.js",
-    "dist/types",
-    "LICENSE",
-    "README.md",
-    "ADDITIONAL_TERMS.md",
-    "robots.txt"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/types/index.d.ts",
-      "default": "./src/index.js"
-    },
-    "./hidden": {
-      "types": "./dist/types/hiddenText.d.ts",
-      "default": "./src/hiddenText.js"
-    },
-    "./browser": {
-      "types": "./dist/types/index.d.ts",
-      "default": "./dist/text-sanctifier.min.js"
-    }
-  },
-  "types": "./dist/types/index.d.ts",
-  "sideEffects": false,
-  "scripts": {
-    "gen": "node scripts/gen-categories.js",
-    "gen:check": "node scripts/gen-categories.js --check",
-    "build": "node scripts/buildc.js",
-    "build:types": "tsc -p tsconfig.types.json",
-    "test:types": "tsc -p tests/types/tsconfig.json",
-    "test": "node tests/sanctifyText.test.js && node tests/inspectTextDetailed.test.js && node tests/cli.test.js",
-    "test-min": "node tests/sanctifyText.test.min.js",
-    "ci": "npm run gen:check && npm run test && npm run build && npm run build:types && npm run test:types && npm run test-min"
-  },
-  "keywords": [
-    "text",
-    "sanitize",
-    "normalize",
-    "invisible",
-    "scrubber",
-    "unicode",
-    "clean",
-    "sanctify"
-  ],
-  "author": "WATT3D <WATT3D@protonmail.com>",
-  "license": "SEE LICENSE IN LICENSE",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/iWhatty/text-sanctifier.git"
-  },
-  "bugs": {
-    "url": "https://github.com/iWhatty/text-sanctifier/issues"
-  },
-  "homepage": "https://github.com/iWhatty/text-sanctifier#readme",
-  "directories": {
-    "test": "tests"
-  },
-  "devDependencies": {
-    "esbuild": "^0.25.3",
-    "google-closure-compiler": "^20240317.0.0",
-    "terser": "^5.39.0",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "text-sanctifier",
+  "version": "1.3.6",
+  "type": "module",
+  "description": "A brutal text normalizer and invisible trash scrubber for modern web projects.",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "browser": "./dist/text-sanctifier.min.js",
+  "bin": {
+    "text-sanctifier": "bin/text-sanctifier.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "dist/text-sanctifier.min.js",
+    "dist/types",
+    "LICENSE",
+    "README.md",
+    "ADDITIONAL_TERMS.md",
+    "robots.txt"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./hidden": {
+      "types": "./dist/types/hiddenText.d.ts",
+      "default": "./src/hiddenText.js"
+    },
+    "./browser": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/text-sanctifier.min.js"
+    }
+  },
+  "types": "./dist/types/index.d.ts",
+  "sideEffects": false,
+  "scripts": {
+    "gen": "node scripts/gen-categories.js && node scripts/gen-version.js",
+    "gen:check": "node scripts/gen-categories.js --check && node scripts/gen-version.js --check",
+    "build": "node scripts/build.js",
+    "build:types": "tsc -p tsconfig.types.json",
+    "test:types": "tsc -p tests/types/tsconfig.json",
+    "test": "node tests/sanctifyText.test.js && node tests/inspectTextDetailed.test.js && node --expose-gc tests/hiddenText.test.js && node tests/cli.test.js",
+    "test-min": "node tests/sanctifyText.test.min.js",
+    "ci": "npm run gen:check && npm run test && npm run build && npm run size && npm run build:types && npm run test:types && npm run test-min",
+    "size": "node scripts/check-size.js"
+  },
+  "keywords": [
+    "text",
+    "sanitize",
+    "normalize",
+    "invisible",
+    "scrubber",
+    "unicode",
+    "clean",
+    "sanctify"
+  ],
+  "author": "WATT3D <WATT3D@protonmail.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iWhatty/text-sanctifier.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iWhatty/text-sanctifier/issues"
+  },
+  "homepage": "https://github.com/iWhatty/text-sanctifier#readme",
+  "directories": {
+    "test": "tests"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.3",
+    "typescript": "^5.9.3"
+  }
+}