deghost 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Unicode character categories that deghost can target.
+ *
+ * Each maps to a Unicode general category or a curated set of codepoints:
+ * - `format`    — \p{Cf}: zero-width joiners, directional marks, soft hyphens
+ * - `control`   — \p{Cc}: C0/C1 control characters (NULL through DELETE, 0x80–0x9F)
+ * - `spaces`    — \p{Zs}: space separators (NBSP, en/em space, thin space, ideographic space)
+ * - `tag`       — U+E0001–U+E007F: Unicode tag characters (deprecated, used in flag sequences)
+ * - `bom`       — U+FEFF: byte order mark / zero-width no-break space
+ * - `fillers`   — Script-specific fillers (Hangul, Khmer, Mongolian, Ogham)
+ * - `math`      — Invisible math operators (U+2061–U+2064)
+ */
+type Category = 'format' | 'control' | 'spaces' | 'tag' | 'bom' | 'fillers' | 'math';
+/** Action to take on matched characters. */
+type Action = 'strip' | 'normalize' | 'replace';
+/** A single detected invisible character with metadata. */
+interface Detection {
+    /** The invisible character itself. */
+    char: string;
+    /** Unicode codepoint as hex string (e.g., "U+200B"). */
+    codepoint: string;
+    /** Unicode character name (e.g., "ZERO WIDTH SPACE"). */
+    name: string;
+    /** Which deghost category this character belongs to. */
+    category: Category;
+    /** Zero-based offset in the input string. */
+    offset: number;
+}
+/** Configuration for a single rule in a cleaner pipeline. */
+type Rule = {
+    category: Category;
+    action: 'strip';
+} | {
+    category: Category;
+    action: 'normalize';
+    replacement?: string;
+} | {
+    category: Category;
+    action: 'replace';
+    mapper: (detection: Detection) => string;
+};
+/** A reusable cleaning function built from a set of rules. */
+type CleanerFn = (input: string) => string;
+/** Options for highlight(). */
+interface HighlightOptions {
+    /** Only highlight characters in these categories. Defaults to all. */
+    categories?: Category[];
+    /** Custom formatter for each detection. Defaults to `[U+XXXX]`. */
+    formatter?: (detection: Detection) => string;
+}
+/** Options for the deghost() entry point. */
+interface DeghostOptions {
+    /** Trim leading/trailing whitespace from the result. Default: true */
+    trim?: boolean;
+}
+
+/**
+ * Fluent chain for composing text cleaning operations.
+ *
+ * Each method returns a new DeghostChain (immutable), so you can
+ * branch chains without side effects.
+ *
+ * @example
+ * ```ts
+ * new DeghostChain('text\u00A0with\u200Bghosts')
+ *   .strip('format')
+ *   .normalize('spaces')
+ *   .trim()
+ *   .toString()
+ * // 'text with ghosts'
+ * ```
+ */
+declare class DeghostChain {
+    #private;
+    constructor(value: string);
+    /** Remove all characters in the given category. */
+    strip(category: Category): DeghostChain;
+    /** Replace all characters in the given category with a substitute. */
+    normalize(category: Category, replacement?: string): DeghostChain;
+    /** Replace matched ghosts in a category using a mapper function. */
+    replace(category: Category, mapper: (detection: Detection) => string): DeghostChain;
+    /** Replace ghosts with visible markers like `[U+200B]`. */
+    highlight(category?: Category, formatter?: (detection: Detection) => string): DeghostChain;
+    /** Return detections for the current chain value. */
+    detect(categories?: Category[]): Detection[];
+    /** Check if the current chain value contains invisible characters. */
+    hasGhosts(categories?: Category[]): boolean;
+    /** Count invisible characters by category in the current chain value. */
+    count(categories?: Category[]): Partial<Record<Category, number>>;
+    /** Returns true if the current chain value has no invisible characters. */
+    isClean(categories?: Category[]): boolean;
+    /** Return a human-readable report of ghosts in the current chain value. */
+    summary(categories?: Category[]): string;
+    /** Collapse runs of whitespace into a single space. */
+    collapse(): DeghostChain;
+    /** Trim leading and trailing whitespace. */
+    trim(): DeghostChain;
+    /** Apply the default cleaning preset: strip format + control, normalize spaces, trim. */
+    clean(): DeghostChain;
+    /** Extract the cleaned string. */
+    toString(): string;
+    /** Extract the cleaned string (alias for toString). */
+    valueOf(): string;
+    /** Support JSON.stringify. */
+    toJSON(): string;
+}
+
+/**
+ * Builder for creating reusable cleaning functions.
+ *
+ * Compile a cleaning pipeline once, apply it to many strings.
+ *
+ * @example
+ * ```ts
+ * const clean = cleaner()
+ *   .strip('format')
+ *   .strip('control')
+ *   .normalize('spaces')
+ *   .trim()
+ *   .build()
+ *
+ * clean('dirty\u00A0string')  // 'dirty string'
+ * clean('another\u200Bone')   // 'anotherone'
+ * ```
+ */
+declare class CleanerBuilder {
+    #private;
+    /** Add a strip rule — remove all characters in this category. */
+    strip(category: Category): this;
+    /** Add a normalize rule — replace characters in this category. */
+    normalize(category: Category, replacement?: string): this;
+    /** Add a replace rule — transform characters using detection metadata. */
+    replace(category: Category, mapper: (detection: Detection) => string): this;
+    /** Add a highlight step — annotate characters with visible markers. */
+    highlight(category: Category, formatter?: (detection: Detection) => string): this;
+    /** Enable whitespace trimming as a final step. */
+    trim(): this;
+    /** Enable collapsing runs of whitespace as a final step. */
+    collapse(): this;
+    /** Compile the pipeline into a reusable function. */
+    build(): CleanerFn;
+}
+/** Create a new cleaner builder. */
+declare function cleaner(): CleanerBuilder;
+
+/**
+ * Scan a string for invisible Unicode characters and return metadata for each.
+ *
+ * Optionally pass a list of categories to restrict detection.
+ *
+ * @example
+ * ```ts
+ * detect('hello\u200Bworld')
+ * // [{ char: '\u200B', codepoint: 'U+200B', name: 'ZERO WIDTH SPACE', category: 'format', offset: 5 }]
+ *
+ * detect('a\u00a0b\u200Bc', ['format'])
+ * // [{ char: '\u200B', ..., category: 'format' }]
+ * ```
+ */
+/**
+ * Lazily scan a string for invisible Unicode characters, yielding metadata for each.
+ *
+ * Like `detect()` but returns a generator — useful for large strings where you
+ * may not need all results, or want to break early.
+ */
+declare function scan(input: string, categories?: Category[]): Generator<Detection>;
+declare function detect(input: string, categories?: Category[]): Detection[];
+/**
+ * Return the first invisible character detected, or `undefined` if clean.
+ *
+ * Uses `scan()` internally — stops at the first match.
+ */
+declare function first(input: string, categories?: Category[]): Detection | undefined;
+/**
+ * Returns true if the string contains any invisible Unicode characters.
+ *
+ * Faster than `detect()` when you don't need metadata.
+ */
+declare function hasGhosts(input: string, categories?: Category[]): boolean;
+/**
+ * Returns true if the string contains no invisible Unicode characters.
+ *
+ * Inverse of `hasGhosts()`.
+ */
+declare function isClean(input: string, categories?: Category[]): boolean;
+/**
+ * Count invisible characters by category.
+ *
+ * @example
+ * ```ts
+ * count('a\u00A0b\u200Bc')
+ * // { spaces: 1, format: 1 }
+ * ```
+ */
+declare function count(input: string, categories?: Category[]): Partial<Record<Category, number>>;
+/** Result of identifying a single character. */
+interface CharInfo {
+    codepoint: string;
+    name: string;
+    category: Category;
+}
+/**
+ * Identify a single character or codepoint — returns its category and name,
+ * or `undefined` if it's not an invisible character deghost tracks.
+ *
+ * @example
+ * ```ts
+ * identify('\u200B')
+ * // { codepoint: 'U+200B', name: 'ZERO WIDTH SPACE', category: 'format' }
+ *
+ * identify(0x00A0)
+ * // { codepoint: 'U+00A0', name: 'NO-BREAK SPACE', category: 'spaces' }
+ * ```
+ */
+declare function identify(input: string | number): CharInfo | undefined;
+
+/**
+ * Replace invisible characters with visible markers for debugging.
+ *
+ * By default each ghost is replaced with its codepoint in brackets,
+ * e.g. `[U+200B]`. Pass a custom formatter or an options object to
+ * filter by category.
+ *
+ * @example
+ * ```ts
+ * highlight('hello\u200Bworld')
+ * // 'hello[U+200B]world'
+ *
+ * highlight('a\u200Bb', (d) => `{${d.name}}`)
+ * // 'a{ZERO WIDTH SPACE}b'
+ *
+ * highlight('a\u00a0b\u200Bc', { categories: ['format'] })
+ * // 'a\u00a0b[U+200B]c'
+ * ```
+ */
+declare function highlight(input: string): string;
+declare function highlight(input: string, formatter: (detection: Detection) => string): string;
+declare function highlight(input: string, options: HighlightOptions): string;
+
+/**
+ * Return a human-readable report of all invisible characters in a string.
+ *
+ * @example
+ * ```ts
+ * summary('hello\u200Bworld')
+ * // "1 invisible character found.\n\nBy category:\n  format: 1\n\nDetails:\n  U+200B  ZERO WIDTH SPACE  (format, offset 5)"
+ * ```
+ */
+declare function summary(input: string, categories?: Category[]): string;
+
+/**
+ * Pre-built cleaning functions for common use cases.
+ *
+ * @example
+ * ```ts
+ * import { presets } from 'deghost'
+ *
+ * presets.clean('text\u00A0with\u200Bghosts')
+ * // 'text with ghosts'
+ * ```
+ */
+declare const presets: {
+    /**
+     * Default clean: strip format + control + BOM, normalize spaces, collapse, trim.
+     *
+     * The right choice for most text processing — catches invisible chars from
+     * binary formats (Garmin FIT, PDFs), APIs, and copy-paste while preserving
+     * word boundaries.
+     */
+    clean: CleanerFn;
+    /**
+     * Aggressive: strip everything invisible, including fillers, math operators, and tags.
+     *
+     * Use when you want maximally clean output and don't need to preserve any
+     * invisible Unicode semantics (ligature joiners, bidi marks, etc.).
+     */
+    aggressive: CleanerFn;
+    /**
+     * Spaces only: normalize Unicode whitespace to ASCII space.
+     *
+     * Leaves format/control characters alone. Useful when you only care about
+     * NBSP and exotic spaces (common in data from Garmin, Strava, etc.).
+     */
+    spaces: CleanerFn;
+};
+
+/**
+ * Regex patterns for each invisible character category.
+ *
+ * Uses ES2018 Unicode property escapes where possible (\p{Cf}, \p{Cc}, \p{Zs}).
+ * Falls back to explicit codepoint ranges for categories not covered by a
+ * single Unicode general category.
+ */
+declare const patterns: Record<Category, RegExp>;
+/** All category names as a readonly array. */
+declare const categories: readonly Category[];
+/** Human-readable descriptions for each category. */
+declare const descriptions: Record<Category, string>;
+/**
+ * Unicode character names for well-known invisible codepoints.
+ *
+ * This is not exhaustive — \p{Cf} alone covers 170+ characters.
+ * We map the ~40 most commonly encountered ones for the detect() API.
+ */
+declare const charNames: Record<number, string>;
+/** Resolve the deghost category for a given codepoint. */
+declare function categorize(codepoint: number): Category | undefined;
+
+/**
+ * Clean a string of invisible Unicode characters.
+ *
+ * With no chaining, applies the default preset (strip format + control + BOM,
+ * normalize spaces, collapse, trim). Chain methods for fine-grained control.
+ *
+ * @example
+ * ```ts
+ * // Quick clean — sensible defaults
+ * deghost('Plant\u00a064\u00a0-\u00a0Woodbridge')
+ * // → 'Plant 64 - Woodbridge'
+ *
+ * // Tagged template literal
+ * deghost`text\u200B\u00a0here`
+ * // → 'text here'
+ *
+ * // Chainable — pick what to handle
+ * deghost('text\u200B\u00a0here')
+ *   .strip('format')
+ *   .normalize('spaces')
+ *   .trim()
+ *   .toString()
+ * ```
+ */
+declare function deghost(strings: TemplateStringsArray, ...values: unknown[]): DeghostChain & string;
+declare function deghost(input: string, options?: DeghostOptions): DeghostChain & string;
+
+export { type Action, type Category, type CharInfo, CleanerBuilder, type CleanerFn, DeghostChain, type DeghostOptions, type Detection, type HighlightOptions, type Rule, categories, categorize, charNames, cleaner, count, deghost, descriptions, detect, first, hasGhosts, highlight, identify, isClean, patterns, presets, scan, summary };