feat(text): add ability for user to control word comparison function (denoland#5448)

Author: iuioiua

text/closest_string.ts

@@ -2,16 +2,30 @@
 // This module is browser compatible.
 import { levenshteinDistance } from "./levenshtein_distance.ts";
 
-// NOTE: this metric may change in future versions (e.g. better than levenshteinDistance)
-const getWordDistance = levenshteinDistance;
+/** Options for {@linkcode closestString}. */
+export interface ClosestStringOptions {
+  /**
+   * Whether the distance should include case.
+   *
+   * @default {false}
+   */
+  caseSensitive?: boolean;
+  /**
+   * A custom comparison function to use for comparing strings.
+   *
+   * @param a The first string for comparison.
+   * @param b The second string for comparison.
+   * @returns The distance between the two strings.
+   * @default {levenshteinDistance}
+   */
+  compareFn?: (a: string, b: string) => number;
+}
 
 /**
  * Finds the most similar string from an array of strings.
  *
- * Note: the ordering of words may change with version-updates
- * E.g. word-distance metric may change (improve)
- * use a named-distance (e.g. levenshteinDistance) to
- * guarantee a particular ordering.
+ * By default, calculates the distance between words using the
+ * {@link https://en.wikipedia.org/wiki/Levenshtein_distance | Levenshtein distance}.
  *
  * @example Usage
  * ```ts
@@ -26,23 +40,20 @@ const getWordDistance = levenshteinDistance;
  *
  * @param givenWord The string to measure distance against
  * @param possibleWords The string-array to pick the closest string from
- * @param options An options bag containing a `caseSensitive` flag indicating
- * whether the distance should include case. Default is false.
+ * @param options The options for the comparison.
  * @returns The closest string
  */
 export function closestString(
   givenWord: string,
   possibleWords: ReadonlyArray<string>,
-  options?: {
-    caseSensitive?: boolean;
-  },
+  options?: ClosestStringOptions,
 ): string {
   if (possibleWords.length === 0) {
     throw new TypeError(
       "When using closestString(), the possibleWords array must contain at least one word",
     );
   }
-  const { caseSensitive } = { ...options };
+  const { caseSensitive, compareFn = levenshteinDistance } = { ...options };
 
   if (!caseSensitive) {
     givenWord = givenWord.toLowerCase();
@@ -52,13 +63,12 @@ export function closestString(
   let closestStringDistance = Infinity;
   for (const each of possibleWords) {
     const distance = caseSensitive
-      ? getWordDistance(givenWord, each)
-      : getWordDistance(givenWord, each.toLowerCase());
+      ? compareFn(givenWord, each)
+      : compareFn(givenWord, each.toLowerCase());
     if (distance < closestStringDistance) {
       nearestWord = each;
       closestStringDistance = distance;
     }
   }
-  // this distance metric could be swapped/improved in the future
   return nearestWord;
 }

text/compare_similarity.ts

@@ -2,9 +2,6 @@
 // This module is browser compatible.
 import { levenshteinDistance } from "./levenshtein_distance.ts";
 
-// Note: this metric may change in future versions (e.g. better than levenshteinDistance)
-const getWordDistance = levenshteinDistance;
-
 /** Options for {@linkcode compareSimilarity}. */
 export interface CompareSimilarityOptions {
   /**
@@ -13,16 +10,23 @@ export interface CompareSimilarityOptions {
    * @default {false}
    */
   caseSensitive?: boolean;
+  /**
+   * A custom comparison function to use for comparing strings.
+   *
+   * @param a The first string for comparison.
+   * @param b The second string for comparison.
+   * @returns The distance between the two strings.
+   * @default {levenshteinDistance}
+   */
+  compareFn?: (a: string, b: string) => number;
 }
 
 /**
  * Takes a string and generates a comparator function to determine which of two
  * strings is more similar to the given one.
  *
- * Note: the ordering of words may change with version-updates
- * E.g. word-distance metric may change (improve)
- * use a named-distance (e.g. levenshteinDistance) to
- * guarantee a particular ordering.
+ * By default, calculates the distance between words using the
+ * {@link https://en.wikipedia.org/wiki/Levenshtein_distance | Levenshtein distance}.
  *
  * @param givenWord The string to measure distance against.
  * @param options Options for the sort.
@@ -48,12 +52,13 @@ export function compareSimilarity(
   givenWord: string,
   options?: CompareSimilarityOptions,
 ): (a: string, b: string) => number {
+  const { compareFn = levenshteinDistance } = { ...options };
   if (options?.caseSensitive) {
     return (a: string, b: string) =>
-      getWordDistance(givenWord, a) - getWordDistance(givenWord, b);
+      compareFn(givenWord, a) - compareFn(givenWord, b);
   }
   givenWord = givenWord.toLowerCase();
   return (a: string, b: string) =>
-    getWordDistance(givenWord, a.toLowerCase()) -
-    getWordDistance(givenWord, b.toLowerCase());
+    compareFn(givenWord, a.toLowerCase()) -
+    compareFn(givenWord, b.toLowerCase());
 }

text/word_similarity_sort.ts

@@ -11,10 +11,8 @@ export interface WordSimilaritySortOptions extends CompareSimilarityOptions {}
 /**
  * Sorts a string-array by similarity to a given string.
  *
- * Note: the ordering of words may change with version-updates
- * E.g. word-distance metric may change (improve)
- * use a named-distance (e.g. levenshteinDistance) to
- * guarantee a particular ordering.
+ * By default, calculates the distance between words using the
+ * {@link https://en.wikipedia.org/wiki/Levenshtein_distance | Levenshtein distance}.
  *
  * @example Basic usage
  *