disarm 0.15.0 → 0.17.0

package/README.md

@@ -10,7 +10,7 @@ prebuilt native addons install with no Rust toolchain.
 npm install disarm
 ```
 
-Ships TypeScript types (`.d.ts`) — no `@types/disarm` needed. Requires Node 14+.
+Ships TypeScript types (`.d.ts`) — no `@types/disarm` needed. Requires Node 22+.
 
 ## Quick start
 

package/binding.d.ts

@@ -1,5 +1,14 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
+
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
 /**
  * A reusable, opaque lexicon handle (HAI-SDLC 6.1).
  *
@@ -27,6 +36,17 @@ export declare class Lexicon {
 export declare class Pipeline {
   /** Run the named pipeline over `text`, returning the cleaned string. */
   process(text: string): string
+  /**
+   * What the named profile this was built from is for, in one sentence (#860).
+   * `null` for a pipeline not built from a profile.
+   */
+  get purpose(): string | null
+  /**
+   * A copy of this pipeline whose confusable passes fold under `digitPolicy` (#646).
+   * Throws when the profile has no confusables step and the policy is not the default:
+   * a setting that would never run is refused rather than kept.
+   */
+  withDigitPolicy(digitPolicy: string): Pipeline
 }
 
 /**
@@ -71,7 +91,7 @@ export interface AutoLangInspection {
  * WHEN the word also carries an ASCII letter, which is the gate that keeps ordinary
  * non-Latin text from firing; a delimiter-only string is not reported.
  */
-export declare function canonicalize(text: string): string
+export declare function canonicalize(text: string, digitPolicy: string): string
 
 /**
  * Strip the non-interchange and invisible classes while KEEPING the script (#698).
@@ -88,20 +108,42 @@ export declare function canonicalize(text: string): string
  * — the point of the preset.
  * Canonicalize, but fail rather than silently normalize a structural difference away.
  */
-export declare function canonicalizeStrict(text: string): string
+export declare function canonicalizeStrict(text: string, digitPolicy: string): string
 
 /**
  * Library catalog deduplication key (like `searchKey` plus confusable folding).
  * `lang` selects the transliteration table; `strict_iso9` picks the ISO 9:1995
  * Cyrillic scheme.
  */
-export declare function catalogKey(text: string, lang: string | undefined | null, strictIso9: boolean): string
+export declare function catalogKey(text: string, lang: string | undefined | null, strictIso9: boolean, digitPolicy: string): string
 
 export declare function collapseWhitespace(text: string): string
 
+/**
+ * TR39 sources whose prototype is in `script`, and how many the bundled tables fold
+ * (#963). The denominator `unmappedConfusables` does not have: it measures one table
+ * against the whole source population, so a script disarm ships no table for reports a
+ * number determined by that absence. An unknown name raises a
+ * `DisarmInvalidArgument`-tagged error.
+ */
+export declare function confusableCoverage(script: string): ConfusableCoverage
+
+/** Per-script confusable coverage — the fair denominator (#963). */
+export interface ConfusableCoverage {
+  /** The script the figures are about, in disarm's spelling. */
+  script: string
+  /** TR39 sources whose prototype is in this script. */
+  sources: number
+  /** How many of those `sources` a bundled fold table reaches. */
+  folded: number
+}
+
 export declare function confusablesVersion(): string
 
-/** Replace emoji with their plain names; `strip_modifiers` drops skin-tone marks. */
+/**
+ * Replace emoji with their plain names; `strip_modifiers` drops skin-tone marks. An
+ * emoji CLDR cannot name becomes `[?]`, as in every binding.
+ */
 export declare function demojize(text: string, stripModifiers: boolean): string
 
 /**
@@ -110,6 +152,9 @@ export declare function demojize(text: string, stripModifiers: boolean): string
  */
 export declare function detectScripts(text: string): Array<string>
 
+/** Levenshtein edit distance between `a` and `b`, in characters (#894). */
+export declare function editDistance(a: string, b: string): number
+
 /** One reason a token is anomalous (a single finding). */
 export interface Finding {
   /** Which branch fired: `"invisible"` | `"bidi"` | `"zalgo"` | `"mixed_script"` | `"bidi_mixed"` | `"leet"` | `"segmentation"`. */
@@ -256,6 +301,9 @@ export declare function inspectAnomalies(text: string, lexicon: Array<string> |
 /** Explain how auto-language detection resolves `text`. */
 export declare function inspectAutoLang(text: string): AutoLangInspection
 
+/** Whether `text` is already its own canonical form under `preset` (#730). */
+export declare function isCanonical(text: string, preset: string): boolean
+
 /**
  * Whether case folding and simple lowercasing agree, so the value is a stable
  * identity key (#619).
@@ -279,7 +327,11 @@ export declare function isNormalized(text: string, form: string): boolean
  */
 export declare function isSuspiciousHostname(host: string): boolean
 
-export declare function isZalgo(text: string, threshold: number): boolean
+/**
+ * Whether any base carries more than `threshold` marks; omitted, the core's default
+ * (`api::DEFAULT_ZALGO_THRESHOLD`, 3).
+ */
+export declare function isZalgo(text: string, threshold?: number | undefined | null): boolean
 
 /** One group of distinct inputs that reduce to the same key (#620). */
 export interface KeyCollision {
@@ -327,8 +379,9 @@ export declare function listContextLangs(): Array<string>
 export declare function listScripts(): Array<string>
 
 /**
- * ML/NLP normalization: NFKC → emoji→text → transliterate → strip accents →
- * [case fold] → strip control → strip zero-width → collapse whitespace.
+ * ML/NLP normalization: resolve deletions → NFKC → emoji→text → transliterate →
+ * strip accents → emoji→text → [case fold] → strip control → strip zero-width →
+ * collapse whitespace → NFC.
  *
  * `fold_case` defaults to `true`. Pass `false` in front of a CASED model: the fold is
  * destructive, cannot be undone downstream, and an uncased evaluation harness cannot
@@ -336,12 +389,34 @@ export declare function listScripts(): Array<string>
  */
 export declare function mlNormalize(text: string, lang: string | undefined | null, emojiStyle: string, foldCase: boolean): string
 
+/**
+ * The candidate closest to `value`, with its distance, or `null` beyond `max_distance`
+ * (#894). An exact match is reported with distance 0; ties go to the first candidate at
+ * the lowest distance.
+ */
+export declare function nearestMatch(value: string, candidates: Array<string>, maxDistance: number): NearestMatch | null
+
+/** A candidate and how far `nearestMatch` found it from the value asked about (#894). */
+export interface NearestMatch {
+  /** The candidate, in the spelling the caller supplied. */
+  value: string
+  /** Its edit distance from the value asked about; `0` means the value *is* this candidate. */
+  distance: number
+}
+
 /** Apply a normalization form: `"NFC"` | `"NFD"` | `"NFKC"` | `"NFKD"`. */
 export declare function normalize(text: string, form: string): string
 
 /** Fold cross-script confusables toward `target` (`"latin"` | `"cyrillic"` | `"arabic"` | `"hebrew"`). */
 export declare function normalizeConfusables(text: string, target: string, digitPolicy: string): string
 
+/**
+ * Replace every emoji with `replacement`, verbatim (#972). The counterpart to
+ * `demojize`: that names an emoji from the CLDR table, which is wider than the emoji
+ * set, and this replaces what the UCD calls an emoji and nothing else.
+ */
+export declare function replaceEmoji(text: string, replacement: string): string
+
 /** Reverse-transliterate Latin → native script. `lang` is `"el"` | `"ru"` | `"uk"`. */
 export declare function reverseTransliterate(text: string, lang: string): string
 
@@ -352,8 +427,12 @@ export declare function reverseTransliterate(text: string, lang: string): string
  * A safe **filename**, not a safe URL path segment. `%` is legal in a filename, so one
  * the caller typed is kept — `sanitizeFilename("..%2Fetc")` returns `"%2Fetc"` — and a
  * consumer that percent-decodes the result must validate *after* decoding. What this
- * will not do is manufacture one: `%` never appears in the output unless it appeared in
- * the input (#721).
+ * will not do is manufacture one: every `%` in the output is one the input contained, or
+ * part of the separator (#721).
+ *
+ * `separator` must be printable, non-space ASCII with no character illegal on
+ * `platform` and no path separator (`/`, `\`); anything else throws
+ * `DisarmInvalidArgument`. `""` is allowed.
  */
 export declare function sanitizeFilename(text: string, separator: string, maxLength: number, platform: string, lang: string | undefined | null, preserveExtension: boolean): string
 
@@ -379,7 +458,15 @@ export interface ScriptMeta {
  * Case/accent/script-insensitive search lookup key. `lang` selects the
  * transliteration table (omit for none).
  */
-export declare function searchKey(text: string, lang?: string | undefined | null): string
+export declare function searchKey(text: string, lang: string | undefined | null, digitPolicy: string): string
+
+/**
+ * The TR39 identifier skeleton plus the two prototype classes disarm's table keeps apart
+ * (#650). A spoof key: its only job is to make confusable identifiers collide, and its
+ * output is never for display. `digit_policy` is `"numeric"` (the letter half only),
+ * `"tr39"` (adds `1 ≡ l` and `0 ≡ O`) or `"preserve"`.
+ */
+export declare function skeletonKey(text: string, digitPolicy: string): string
 
 /** Generate a URL-safe slug. */
 export declare function slugify(text: string, opts: SlugOptions): string
@@ -404,7 +491,7 @@ export interface SlugOptions {
  * Collation sort key (like `searchKey` but preserves base accented characters
  * for correct ordering). `lang` selects the transliteration table.
  */
-export declare function sortKey(text: string, lang?: string | undefined | null): string
+export declare function sortKey(text: string, lang: string | undefined | null, digitPolicy: string): string
 
 export declare function stripAccents(text: string): string
 
@@ -417,7 +504,7 @@ export declare function stripFormat(text: string): string
 /** Strip every Unicode noncharacter (#413). */
 export declare function stripNoncharacters(text: string): string
 
-export declare function stripObfuscation(text: string): string
+export declare function stripObfuscation(text: string, digitPolicy: string): string
 
 /** Strip every Private Use Area code point (#413). */
 export declare function stripPua(text: string): string
@@ -428,7 +515,11 @@ export declare function stripTags(text: string): string
 /** Strip every variation selector (VS1–VS256) (#413). */
 export declare function stripVariationSelectors(text: string): string
 
-export declare function stripZalgo(text: string, maxMarks: number): string
+/**
+ * Cap combining marks per base at `max_marks`; omitted, the core's default
+ * (`api::DEFAULT_ZALGO_MAX_MARKS`, 3), so this binding never restates it (B1).
+ */
+export declare function stripZalgo(text: string, maxMarks?: number | undefined | null): string
 
 export declare function stripZeroWidthChars(text: string): string
 
@@ -439,7 +530,8 @@ export declare function transliterate(text: string): string
 
 /**
  * Transliterate with a scheme (`"default"` | `"strict_iso9"` | `"gost7034"`)
- * and/or a language profile (`lang`), via the core's builder.
+ * and/or a language profile (`lang`), via the core's builder. An unknown `lang`
+ * throws `DisarmInvalidArgument`, as the key builders' always has.
  */
 export declare function transliterateOpts(text: string, scheme: string, lang?: string | undefined | null): string