entity-predictor 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Entity Predictor
 
-A lightweight, zero-dependency (almost) Node.js library for entity name prediction and normalization.
+A lightweight, **Zero Dependency** Node.js library for entity name prediction and normalization.
 
 It uses **fuzzy matching** to identify entities from messy input, supporting:
 
@@ -135,6 +135,7 @@ predictor.addEntity("PUNJAB NATIONAL BANK", ["PNB"]);
   - `ignoreStopWords`: boolean (default `false`)
   - `stopWords`: string[] (optional, defaults to internal list)
   - `normalizer`: (text: string) => string
+- **Throws**: `TypeError` if `entities` is not an array.
 
 ### `predict(input, threshold)`
 

package/index.d.ts

@@ -18,7 +18,7 @@ export interface PredictionResult {
 export class EntityPredictor {
     constructor(entities: (string | EntityOption)[], options?: PredictorOptions);
 
-    predict(input: string, threshold?: number): PredictionResult;
+    predict(input: string, threshold?: number): PredictionResult | null;
 
     predictTop(input: string, limit?: number, threshold?: number): PredictionResult[];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "entity-predictor",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Lightweight entity prediction with fuzzy matching, aliases, and confidence scoring.",
   "types": "index.d.ts",
   "type": "module",
@@ -13,8 +13,5 @@
   ],
   "author": "Sahil",
   "email": "dev.sahilkumar02@gmail.com",
-  "license": "MIT",
-  "dependencies": {
-    "string-similarity": "^4.0.4"
-  }
+  "license": "MIT"
 }

package/src/predictor.js

@@ -1,4 +1,4 @@
-import stringSimilarity from "string-similarity";
+import { findBestMatch } from "./string-similarity.js";
 
 const DEFAULT_STOP_WORDS = [
   "the",
@@ -30,8 +30,24 @@ function defaultNormalize(
   return processed.replace(/[^a-z]/g, "").trim();
 }
 
+/**
+ * EntityPredictor class for fuzzy matching entities.
+ */
 export class EntityPredictor {
+  /**
+   * Creates an instance of EntityPredictor.
+   * @param {Array<string | {name: string, aliases: string[]}>} entities - List of entities.
+   * @param {Object} [options] - Configuration options.
+   * @param {boolean} [options.ignoreStopWords=false] - Whether to ignore stop words.
+   * @param {string[]} [options.stopWords] - Custom list of stop words.
+   * @param {function(string): string} [options.normalizer] - Custom normalizer function.
+   * @throws {TypeError} If entities is not an array.
+   */
   constructor(entities = [], options = {}) {
+    if (!Array.isArray(entities)) {
+      throw new TypeError("Entities must be an array.");
+    }
+
     this.entities = [];
     this.searchCandidates = [];
     this.candidateToEntity = [];
@@ -41,10 +57,15 @@ export class EntityPredictor {
     this.customNormalizer = options.normalizer;
 
     entities.forEach((item) => {
-      this.addEntity(item, true); // true = internal call, delay re-indexing if needed (not needed here)
+      this.addEntity(item, true); // true = internal call
     });
   }
 
+  /**
+   * Normalizes text for comparison.
+   * @param {string} text - The text to normalize.
+   * @returns {string} Normalized text.
+   */
   normalize(text) {
     if (this.customNormalizer) {
       return this.customNormalizer(text);
@@ -52,6 +73,11 @@ export class EntityPredictor {
     return defaultNormalize(text, this.ignoreStopWords, this.stopWords);
   }
 
+  /**
+   * Adds an entity to the predictor.
+   * @param {string | {name: string, aliases: string[]}} item - The entity to add.
+   * @param {boolean} [isInternal=false] - Internal flag.
+   */
   addEntity(item, isInternal = false) {
     let entityName;
     let aliases = [];
@@ -64,6 +90,7 @@ export class EntityPredictor {
         aliases = item.aliases;
       }
     } else {
+      // Invalid entity format, skip silently or could warn in future
       return;
     }
 
@@ -82,6 +109,12 @@ export class EntityPredictor {
     });
   }
 
+  /**
+   * Predicts the best match for the input.
+   * @param {string} input - The input string.
+   * @param {number} [threshold=0.6] - The confidence threshold.
+   * @returns {{entity: string, confidence: number, confidenceLevel: string} | null} The best match or null/UNKNOWN.
+   */
   predict(input, threshold = 0.6) {
     if (!input || typeof input !== "string") {
       return null;
@@ -97,16 +130,20 @@ export class EntityPredictor {
     };
   }
 
+  /**
+   * Predicts the top N best matches.
+   * @param {string} input - The input string.
+   * @param {number} [limit=5] - The number of results to return.
+   * @param {number} [threshold=0.6] - The confidence threshold.
+   * @returns {Array<{entity: string, confidence: number, confidenceLevel: string}>} Array of matches.
+   */
   predictTop(input, limit = 5, threshold = 0.6) {
     if (!input || typeof input !== "string") {
       return [];
     }
 
     const normalizedInput = this.normalize(input);
-    const matches = stringSimilarity.findBestMatch(
-      normalizedInput,
-      this.searchCandidates
-    );
+    const matches = findBestMatch(normalizedInput, this.searchCandidates);
 
     // Map all ratings to our format and sort
     const sortedMatches = matches.ratings

package/src/string-similarity.js

@@ -0,0 +1,83 @@
+/**
+ * Compares two strings using bigram comparison (Dice Coefficient).
+ *
+ * @param {string} first - The first string to compare.
+ * @param {string} second - The second string to compare.
+ * @returns {number} A fraction between 0 and 1, which indicates the degree of similarity.
+ */
+export function compareTwoStrings(first, second) {
+  first = first.replace(/\s+/g, "");
+  second = second.replace(/\s+/g, "");
+
+  if (first === second) return 1; // identical or empty
+  if (first.length < 2 || second.length < 2) return 0; // if either is a 0-letter or 1-letter string
+
+  let firstBigrams = new Map();
+  for (let i = 0; i < first.length - 1; i++) {
+    const bigram = first.substring(i, i + 2);
+    const count = firstBigrams.has(bigram) ? firstBigrams.get(bigram) + 1 : 1;
+
+    firstBigrams.set(bigram, count);
+  }
+
+  let intersectionSize = 0;
+  for (let i = 0; i < second.length - 1; i++) {
+    const bigram = second.substring(i, i + 2);
+    const count = firstBigrams.has(bigram) ? firstBigrams.get(bigram) : 0;
+
+    if (count > 0) {
+      firstBigrams.set(bigram, count - 1);
+      intersectionSize++;
+    }
+  }
+
+  return (2.0 * intersectionSize) / (first.length + second.length - 2);
+}
+
+/**
+ * Finds the best match for a main string from a target list of strings.
+ *
+ * @param {string} mainString - The string to match.
+ * @param {string[]} targetStrings - The array of strings to match against.
+ * @returns {{ ratings: Array<{target: string, rating: number}>, bestMatch: {target: string, rating: number}, bestMatchIndex: number }}
+ * @throws {TypeError} If arguments are invalid.
+ */
+export function findBestMatch(mainString, targetStrings) {
+  if (!areArgsValid(mainString, targetStrings))
+    throw new TypeError(
+      "Bad arguments: First argument should be a string, second should be an array of strings"
+    );
+
+  const ratings = [];
+  let bestMatchIndex = 0;
+
+  for (let i = 0; i < targetStrings.length; i++) {
+    const currentTargetString = targetStrings[i];
+    const currentRating = compareTwoStrings(mainString, currentTargetString);
+    ratings.push({ target: currentTargetString, rating: currentRating });
+    if (currentRating > ratings[bestMatchIndex].rating) {
+      bestMatchIndex = i;
+    }
+  }
+
+  const bestMatch = ratings[bestMatchIndex];
+
+  return {
+    ratings: ratings,
+    bestMatch: bestMatch,
+    bestMatchIndex: bestMatchIndex,
+  };
+}
+
+function areArgsValid(mainString, targetStrings) {
+  if (typeof mainString !== "string") return false;
+  if (!Array.isArray(targetStrings)) return false;
+  if (!targetStrings.length) return false;
+  if (
+    targetStrings.find(function (s) {
+      return typeof s !== "string";
+    })
+  )
+    return false;
+  return true;
+}