tdk-api-wrapper 1.3.1 → 1.4.0

package/dist/index.js

@@ -33,7 +33,14 @@ __export(src_exports, {
   TDK: () => TDK,
   TDKError: () => TDKError,
   TDKNetworkError: () => TDKNetworkError,
-  TDKValidationError: () => TDKValidationError
+  TDKValidationError: () => TDKValidationError,
+  TURKISH_SUFFIXES: () => TURKISH_SUFFIXES,
+  TURKISH_VOWELS: () => TURKISH_VOWELS,
+  getStemCandidates: () => getStemCandidates,
+  isVowel: () => isVowel,
+  restoreConsonantSoftening: () => restoreConsonantSoftening,
+  restoreInfinitive: () => restoreInfinitive,
+  restoreVowelDrop: () => restoreVowelDrop
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -64,6 +71,503 @@ var TDKNetworkError = class extends TDKError {
   }
 };
 
+// src/morphology.ts
+var TURKISH_VOWELS = "ae\u0131io\xF6u\xFC";
+function isVowel(ch) {
+  return TURKISH_VOWELS.includes(ch);
+}
+var TURKISH_SUFFIXES = [
+  // 9-letter composite suffixes
+  "lerimizden",
+  "lar\u0131m\u0131zdan",
+  "lerinizden",
+  "lar\u0131n\u0131zdan",
+  // 8-letter composite suffixes
+  "lerinin",
+  "lar\u0131n\u0131n",
+  "lerinde",
+  "lar\u0131nda",
+  "lerinden",
+  "lar\u0131ndan",
+  "leriyle",
+  "lar\u0131yla",
+  "lerini",
+  "lar\u0131n\u0131",
+  "lerimize",
+  "lar\u0131m\u0131za",
+  "lerimizle",
+  "lar\u0131m\u0131zla",
+  "lerinizin",
+  "lar\u0131n\u0131z\u0131n",
+  "lerinizde",
+  "lar\u0131n\u0131zda",
+  "d\u0131\u011F\u0131ndan",
+  "di\u011Finden",
+  "du\u011Fundan",
+  "d\xFC\u011F\xFCnden",
+  "t\u0131\u011F\u0131ndan",
+  "ti\u011Finden",
+  "tu\u011Fundan",
+  "t\xFC\u011F\xFCnden",
+  // 7-letter composite suffixes
+  "ecektir",
+  "acakt\u0131r",
+  "ece\u011Fim",
+  "aca\u011F\u0131m",
+  "eceksin",
+  "acaks\u0131n",
+  "ece\u011Fiz",
+  "aca\u011F\u0131z",
+  "lerimiz",
+  "lar\u0131m\u0131z",
+  "leriniz",
+  "lar\u0131n\u0131z",
+  "umuzdan",
+  "\xFCm\xFCzden",
+  "inizden",
+  "\u0131n\u0131zdan",
+  "\xFCn\xFCzden",
+  "d\u0131\u011F\u0131nda",
+  "di\u011Finde",
+  "du\u011Funda",
+  "d\xFC\u011F\xFCnde",
+  "t\u0131\u011F\u0131nda",
+  "ti\u011Finde",
+  "tu\u011Funda",
+  "t\xFC\u011F\xFCnde",
+  "mas\u0131na",
+  "mesine",
+  "\u0131yorsunuz",
+  "iyorsunuz",
+  "uyorsunuz",
+  "\xFCyorsunuz",
+  "yorsunuz",
+  // 6-letter composite suffixes
+  "iyorsa",
+  "iyorduk",
+  "iyordu",
+  "iyormu\u015F",
+  "\u0131yorsa",
+  "\u0131yorduk",
+  "\u0131yordu",
+  "\u0131yormu\u015F",
+  "uyorsa",
+  "uyorduk",
+  "uyordu",
+  "uyormu\u015F",
+  "\xFCyorsa",
+  "\xFCyorduk",
+  "\xFCyordu",
+  "\xFCyormu\u015F",
+  "\u0131yorsun",
+  "iyorsun",
+  "uyorsun",
+  "\xFCyorsun",
+  "\u0131yorlar",
+  "iyorlar",
+  "uyorlar",
+  "\xFCyorlar",
+  "iyoruz",
+  "\u0131yoruz",
+  "uyoruz",
+  "\xFCyoruz",
+  "imizin",
+  "\u0131m\u0131z\u0131n",
+  "umuzun",
+  "\xFCm\xFCz\xFCn",
+  "imizde",
+  "\u0131m\u0131zda",
+  "umuzda",
+  "\xFCm\xFCzde",
+  "imizden",
+  "\u0131m\u0131zdan",
+  "imizle",
+  "\u0131m\u0131zla",
+  "umuzla",
+  "\xFCm\xFCzle",
+  "lerdir",
+  "lard\u0131r",
+  "mu\u015Ftur",
+  "mi\u015Ftir",
+  "mu\u015Ftur",
+  "m\xFC\u015Ft\xFCr",
+  "lerden",
+  "lardan",
+  "lerine",
+  "lar\u0131na",
+  "leriyle",
+  "lar\u0131yla",
+  "seniz",
+  "san\u0131z",
+  "diniz",
+  "d\u0131n\u0131z",
+  "dunuz",
+  "d\xFCn\xFCz",
+  "tiniz",
+  "t\u0131n\u0131z",
+  "tunuz",
+  "t\xFCn\xFCz",
+  "siniz",
+  "s\u0131n\u0131z",
+  "sunuz",
+  "s\xFCn\xFCz",
+  "d\u0131k\xE7a",
+  "dik\xE7e",
+  "duk\xE7a",
+  "d\xFCk\xE7e",
+  "t\u0131k\xE7a",
+  "tik\xE7e",
+  "tuk\xE7a",
+  "t\xFCk\xE7e",
+  "\u0131rken",
+  "irken",
+  "urken",
+  "\xFCrken",
+  "arken",
+  "erken",
+  // 5-letter suffixes
+  "lerde",
+  "larda",
+  "lerle",
+  "larla",
+  "lerin",
+  "lar\u0131n",
+  "lerim",
+  "lar\u0131m",
+  "dirler",
+  "d\u0131rlar",
+  "d\xFCrler",
+  "durlar",
+  "tirler",
+  "t\u0131rlar",
+  "t\xFCrler",
+  "turlar",
+  "siniz",
+  "s\u0131n\u0131z",
+  "sunuz",
+  "s\xFCn\xFCz",
+  "yorum",
+  "yorsun",
+  "uyoruz",
+  "yorsunuz",
+  "yorlar",
+  "eceks",
+  "acaks",
+  "eyim",
+  "ay\u0131m",
+  "indik",
+  "\u0131nd\u0131k",
+  "unduk",
+  "\xFCnd\xFCk",
+  "ildik",
+  "\u0131ld\u0131k",
+  "ulduk",
+  "\xFCld\xFCk",
+  "meden",
+  "madan",
+  "y\u0131n\u0131z",
+  "yiniz",
+  "yunuz",
+  "y\xFCn\xFCz",
+  // 4-letter suffixes
+  "imiz",
+  "\u0131m\u0131z",
+  "umuz",
+  "\xFCm\xFCz",
+  "iniz",
+  "\u0131n\u0131z",
+  "unuz",
+  "\xFCn\xFCz",
+  "leri",
+  "lar\u0131",
+  "idir",
+  "\u0131d\u0131r",
+  "udur",
+  "\xFCd\xFCr",
+  "ecek",
+  "acak",
+  "erek",
+  "arak",
+  "ince",
+  "\u0131nca",
+  "unca",
+  "\xFCnce",
+  "ken",
+  "meli",
+  "mal\u0131",
+  "iyor",
+  "\u0131yor",
+  "uyor",
+  "\xFCyor",
+  "mi\u015Fti",
+  "m\u0131\u015Ft\u0131",
+  "mu\u015Ftu",
+  "m\xFC\u015Ft\xFC",
+  "seydi",
+  "sayd\u0131",
+  "ydim",
+  "yd\u0131m",
+  "ydum",
+  "yd\xFCm",
+  "tiler",
+  "t\u0131lar",
+  "diler",
+  "d\u0131lar",
+  "ikten",
+  "\u0131ktan",
+  "uktan",
+  "\xFCkten",
+  // 3-letter suffixes
+  "ler",
+  "lar",
+  "den",
+  "dan",
+  "ten",
+  "tan",
+  "dir",
+  "d\u0131r",
+  "dur",
+  "d\xFCr",
+  "tir",
+  "t\u0131r",
+  "tur",
+  "t\xFCr",
+  "nin",
+  "n\u0131n",
+  "nun",
+  "n\xFCn",
+  "yle",
+  "yla",
+  "mi\u015F",
+  "m\u0131\u015F",
+  "mu\u015F",
+  "m\xFC\u015F",
+  "dim",
+  "d\u0131m",
+  "dum",
+  "d\xFCm",
+  "tim",
+  "t\u0131m",
+  "tum",
+  "t\xFCm",
+  "din",
+  "d\u0131n",
+  "dun",
+  "d\xFCn",
+  "tin",
+  "t\u0131n",
+  "tun",
+  "t\xFCn",
+  "dik",
+  "d\u0131k",
+  "duk",
+  "d\xFCk",
+  "tik",
+  "t\u0131k",
+  "tuk",
+  "t\xFCk",
+  "ydi",
+  "yd\u0131",
+  "ydu",
+  "yd\xFC",
+  "yim",
+  "y\u0131m",
+  "yum",
+  "y\xFCm",
+  "sin",
+  "s\u0131n",
+  "sun",
+  "s\xFCn",
+  "siz",
+  "s\u0131z",
+  "suz",
+  "s\xFCz",
+  "lik",
+  "l\u0131k",
+  "luk",
+  "l\xFCk",
+  "ici",
+  "\u0131c\u0131",
+  "ucu",
+  "\xFCc\xFC",
+  "gen",
+  "gan",
+  "ken",
+  "kan",
+  "len",
+  "lan",
+  "le\u015F",
+  "la\u015F",
+  "mek",
+  "mak",
+  "yor",
+  // 2-letter suffixes
+  "de",
+  "da",
+  "te",
+  "ta",
+  "im",
+  "\u0131m",
+  "um",
+  "\xFCm",
+  "in",
+  "\u0131n",
+  "un",
+  "\xFCn",
+  "iz",
+  "\u0131z",
+  "uz",
+  "\xFCz",
+  "si",
+  "s\u0131",
+  "su",
+  "s\xFC",
+  "ye",
+  "ya",
+  "le",
+  "la",
+  "di",
+  "d\u0131",
+  "du",
+  "d\xFC",
+  "ti",
+  "t\u0131",
+  "tu",
+  "t\xFC",
+  "se",
+  "sa",
+  "ce",
+  "ca",
+  "\xE7e",
+  "\xE7a",
+  "me",
+  "ma",
+  "ip",
+  "\u0131p",
+  "up",
+  "\xFCp",
+  "en",
+  "an",
+  "i\u015F",
+  "\u0131\u015F",
+  "u\u015F",
+  "\xFC\u015F",
+  "li",
+  "l\u0131",
+  "lu",
+  "l\xFC",
+  "ci",
+  "c\u0131",
+  "cu",
+  "c\xFC",
+  "\xE7i",
+  "\xE7\u0131",
+  "\xE7u",
+  "\xE7\xFC",
+  // 1-letter suffixes (vowels / basic case endings)
+  "e",
+  "a",
+  "i",
+  "\u0131",
+  "u",
+  "\xFC"
+];
+function restoreConsonantSoftening(stem) {
+  if (stem.length < 2)
+    return [];
+  const last = stem.slice(-1);
+  const base = stem.slice(0, -1);
+  switch (last) {
+    case "b":
+      return [base + "p"];
+    case "c":
+      return [base + "\xE7"];
+    case "d":
+      return [base + "t"];
+    case "\u011F":
+      return [base + "k"];
+    case "g":
+      return [base + "k"];
+    default:
+      return [];
+  }
+}
+function restoreVowelDrop(stem) {
+  if (stem.length < 3)
+    return [];
+  const c1 = stem[stem.length - 2];
+  const c2 = stem[stem.length - 1];
+  if (!isVowel(c1) && !isVowel(c2)) {
+    const vowelsInBase = stem.slice(0, -2).split("").filter(isVowel);
+    if (vowelsInBase.length > 0) {
+      const lastVowel = vowelsInBase[vowelsInBase.length - 1];
+      let inserted = "i";
+      if ("a\u0131".includes(lastVowel))
+        inserted = "\u0131";
+      else if ("ei".includes(lastVowel))
+        inserted = "i";
+      else if ("ou".includes(lastVowel))
+        inserted = "u";
+      else if ("\xF6\xFC".includes(lastVowel))
+        inserted = "\xFC";
+      return [stem.slice(0, -1) + inserted + c2];
+    }
+  }
+  return [];
+}
+function restoreInfinitive(stem) {
+  if (stem.length < 2)
+    return [];
+  const vowelsInBase = stem.split("").filter(isVowel);
+  if (vowelsInBase.length === 0)
+    return [];
+  const lastVowel = vowelsInBase[vowelsInBase.length - 1];
+  return "a\u0131ou".includes(lastVowel) ? [stem + "mak"] : [stem + "mek"];
+}
+function getStemCandidates(word, minStemLength = 2, maxDepth = 4) {
+  if (!word || word.trim().length === 0)
+    return [];
+  const raw = word.trim();
+  const normalized = raw.toLocaleLowerCase("tr-TR");
+  const candidatesWithWeight = [];
+  const seen = /* @__PURE__ */ new Set();
+  if (raw.includes("'") || raw.includes("\u2019")) {
+    const apostropheStem = normalized.split(/['’]/)[0];
+    if (apostropheStem.length >= minStemLength) {
+      candidatesWithWeight.push({ candidate: apostropheStem, baseLength: apostropheStem.length + 10 });
+      seen.add(apostropheStem);
+    }
+  }
+  let frontier = [normalized];
+  for (let depth = 0; depth < maxDepth; depth++) {
+    const nextFrontier = [];
+    for (const current of frontier) {
+      for (const suffix of TURKISH_SUFFIXES) {
+        if (current.length - suffix.length >= minStemLength && current.endsWith(suffix)) {
+          const stem = current.slice(0, -suffix.length);
+          const hardened = restoreConsonantSoftening(stem);
+          const vowelDropped = restoreVowelDrop(stem);
+          const verbalBases = [stem, ...hardened];
+          const infinitives = verbalBases.flatMap((v) => restoreInfinitive(v));
+          const variants = [stem, ...hardened, ...vowelDropped, ...infinitives];
+          for (const variant of variants) {
+            if (!seen.has(variant) && variant !== normalized) {
+              seen.add(variant);
+              nextFrontier.push(variant);
+              candidatesWithWeight.push({ candidate: variant, baseLength: stem.length });
+            }
+          }
+        }
+      }
+    }
+    if (nextFrontier.length === 0)
+      break;
+    frontier = nextFrontier;
+  }
+  candidatesWithWeight.sort((a, b) => b.baseLength - a.baseLength);
+  return [...new Set(candidatesWithWeight.map((c) => c.candidate))];
+}
+
 // src/tdk.ts
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
@@ -155,6 +659,8 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
   static wordCache = /* @__PURE__ */ new Map();
   static dailyContentCache = null;
   static autocompleteCache = [];
+  static autocompleteSet = /* @__PURE__ */ new Set();
+  static stemCache = /* @__PURE__ */ new Map();
   /**
    * Enables or disables in-memory caching for API requests.
    */
@@ -171,6 +677,8 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     this.wordCache.clear();
     this.dailyContentCache = null;
     this.autocompleteCache = [];
+    this.autocompleteSet.clear();
+    this.stemCache.clear();
   }
   static delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -277,6 +785,17 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
       return [];
     }
   }
+  /**
+   * Ensures TDK's ~81k headword list is loaded in memory for fast O(1) set operations.
+   */
+  static async ensureAutocompleteLoaded() {
+    if (this.autocompleteCache.length === 0) {
+      this.autocompleteCache = await this.fetchAutocompleteData();
+      this.autocompleteSet = new Set(
+        this.autocompleteCache.map((w) => w.toLocaleLowerCase("tr-TR"))
+      );
+    }
+  }
   /**
    * Returns autocomplete suggestions for a given prefix, searched over TDK's
    * full headword list (see `fetchAutocompleteData`). The list is fetched
@@ -286,12 +805,81 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
   static async getSuggestions(prefix) {
     if (!prefix || prefix.trim() === "")
       return [];
-    if (this.autocompleteCache.length === 0) {
-      this.autocompleteCache = await this.fetchAutocompleteData();
-    }
+    await this.ensureAutocompleteLoaded();
     const cleanPrefix = prefix.trim().toLocaleLowerCase("tr-TR");
     return this.autocompleteCache.filter((w) => w.toLocaleLowerCase("tr-TR").startsWith(cleanPrefix)).slice(0, 10);
   }
+  /**
+   * Checks whether a word exists as a known headword in TDK dictionary.
+   * Checks in-memory autocompleteSet (81k headwords) if loaded, or queries TDK API.
+   */
+  static async isHeadword(word) {
+    if (!word || word.trim() === "")
+      return false;
+    const clean = word.trim().toLocaleLowerCase("tr-TR");
+    await this.ensureAutocompleteLoaded();
+    if (this.autocompleteSet.size > 0) {
+      return this.autocompleteSet.has(clean);
+    }
+    try {
+      const results = await this.getWord(clean);
+      return results.length > 0;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Generates candidate roots for a given Turkish word using progressive BFS suffix stripping,
+   * consonant mutation restoration, and vowel drop restoration.
+   */
+  static getStemCandidates(word) {
+    return getStemCandidates(word);
+  }
+  /**
+   * Finds the dictionary root (headword) of a word by checking direct existence
+   * and evaluating candidate stems generated by morphological analysis.
+   * Returns the root headword string if found, or null if no match in TDK.
+   */
+  static async findRoot(word) {
+    if (!word || word.trim() === "")
+      return null;
+    const clean = word.trim().toLocaleLowerCase("tr-TR");
+    if (this.stemCache.has(clean)) {
+      return this.stemCache.get(clean);
+    }
+    if (await this.isHeadword(clean)) {
+      this.stemCache.set(clean, clean);
+      return clean;
+    }
+    const candidates = getStemCandidates(clean);
+    for (const candidate of candidates) {
+      if (await this.isHeadword(candidate)) {
+        this.stemCache.set(clean, candidate);
+        return candidate;
+      }
+    }
+    this.stemCache.set(clean, null);
+    return null;
+  }
+  /**
+   * Performs morphological stemming on a Turkish word.
+   * Returns a StemResult containing the original word, resolved root, and whether it is inflected.
+   */
+  static async stem(word) {
+    if (!word || word.trim() === "")
+      return null;
+    const clean = word.trim().toLocaleLowerCase("tr-TR");
+    const root = await this.findRoot(word);
+    if (!root) {
+      return null;
+    }
+    return {
+      word,
+      root,
+      isInflected: root !== clean,
+      candidates: getStemCandidates(word)
+    };
+  }
   /**
    * Returns a list of proverbs and idioms containing the word.
    */
@@ -508,6 +1096,17 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
         return { isCorrect: false, word, suggestion: mixMatch.dogru };
       }
     }
+    const root = await this.findRoot(word);
+    if (root) {
+      const cleanWord2 = word.trim().toLocaleLowerCase("tr-TR");
+      const isInflected = root !== cleanWord2;
+      return {
+        isCorrect: true,
+        word,
+        isInflected,
+        root
+      };
+    }
     if (this.autocompleteCache.length === 0) {
       this.autocompleteCache = await this.fetchAutocompleteData();
     }
@@ -1004,13 +1603,28 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     const unique = [...new Set(words)];
     const analyses = [];
     for (const word of unique) {
-      const results = await this.getWord(word);
-      const found = results.length > 0;
+      let results = await this.getWord(word);
+      let found = results.length > 0;
+      let root;
+      let isInflected;
+      if (!found) {
+        const resolvedRoot = await this.findRoot(word);
+        if (resolvedRoot) {
+          results = await this.getWord(resolvedRoot);
+          if (results.length > 0) {
+            found = true;
+            root = resolvedRoot;
+            isInflected = true;
+          }
+        }
+      }
       analyses.push({
         word,
         found,
         meaning: found ? this.firstMeaning(results) : null,
-        origin: found ? results[0].lisan || "T\xFCrk\xE7e" : null
+        origin: found ? results[0].lisan || "T\xFCrk\xE7e" : null,
+        root,
+        isInflected
       });
       await this.delay(200);
     }
@@ -1108,5 +1722,12 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
   TDK,
   TDKError,
   TDKNetworkError,
-  TDKValidationError
+  TDKValidationError,
+  TURKISH_SUFFIXES,
+  TURKISH_VOWELS,
+  getStemCandidates,
+  isVowel,
+  restoreConsonantSoftening,
+  restoreInfinitive,
+  restoreVowelDrop
 });