tdk-api-wrapper 1.3.1 → 1.5.0

package/dist/index.js

@@ -31,9 +31,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   TDK: () => TDK,
+  TDKClient: () => TDKClient,
   TDKError: () => TDKError,
   TDKNetworkError: () => TDKNetworkError,
-  TDKValidationError: () => TDKValidationError
+  TDKValidationError: () => TDKValidationError,
+  TURKISH_SUFFIXES: () => TURKISH_SUFFIXES,
+  TURKISH_VOWELS: () => TURKISH_VOWELS,
+  getStemCandidates: () => getStemCandidates,
+  isVowel: () => isVowel,
+  restoreConsonantSoftening: () => restoreConsonantSoftening,
+  restoreGemination: () => restoreGemination,
+  restoreInfinitive: () => restoreInfinitive,
+  restoreVowelDrop: () => restoreVowelDrop,
+  restoreVowelNarrowing: () => restoreVowelNarrowing
 });
 module.exports = __toCommonJS(src_exports);
 
@@ -64,6 +74,559 @@ 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",
+  "sen",
+  "san",
+  "sem",
+  "sam",
+  "sek",
+  "sak",
+  "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 restoreGemination(stem) {
+  if (stem.length < 3)
+    return [];
+  const c1 = stem[stem.length - 2];
+  const c2 = stem[stem.length - 1];
+  if (c1 === c2 && !isVowel(c1)) {
+    const single = stem.slice(0, -1);
+    const hardened = restoreConsonantSoftening(single);
+    return [single, ...hardened];
+  }
+  return [];
+}
+function restoreVowelNarrowing(stem) {
+  if (stem.length < 2)
+    return [];
+  if (stem === "di")
+    return ["de"];
+  if (stem === "yi")
+    return ["ye"];
+  const lastChar = stem[stem.length - 1];
+  const isLastNarrow = "\u0131iu\xFC".includes(lastChar);
+  if (isLastNarrow) {
+    const vowelsInBase = stem.slice(0, -1).split("").filter(isVowel);
+    const lastVowel = vowelsInBase.length > 0 ? vowelsInBase[vowelsInBase.length - 1] : lastChar;
+    const widened = "a\u0131ou".includes(lastVowel) ? "a" : "e";
+    return [stem.slice(0, -1) + widened];
+  }
+  if (!isVowel(lastChar)) {
+    const vowelsInBase = stem.split("").filter(isVowel);
+    if (vowelsInBase.length > 0) {
+      const lastVowel = vowelsInBase[vowelsInBase.length - 1];
+      const widened = "a\u0131ou".includes(lastVowel) ? "a" : "e";
+      return [stem + widened];
+    }
+  }
+  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 geminated = restoreGemination(stem);
+          const isNarrowingSuffix = suffix.startsWith("yor") || suffix.includes("iyor") || suffix.includes("\u0131yor") || suffix.includes("uyor") || suffix.includes("\xFCyor");
+          const isDeYeBuffer = (stem === "di" || stem === "yi") && suffix.startsWith("y");
+          const narrowed = isNarrowingSuffix || isDeYeBuffer ? restoreVowelNarrowing(stem) : [];
+          const isVerbSuffix = isNarrowingSuffix || suffix.includes("ecek") || suffix.includes("acak") || suffix.includes("mi\u015F") || suffix.includes("m\u0131\u015F") || suffix.includes("m\xFC\u015F") || suffix.includes("mu\u015F") || suffix.includes("mek") || suffix.includes("mak") || suffix.includes("erek") || suffix.includes("arak") || suffix.includes("dik") || suffix.includes("d\u0131k") || suffix.includes("duk") || suffix.includes("d\xFCk") || suffix.includes("tik") || suffix.includes("t\u0131k") || suffix.includes("tuk") || suffix.includes("t\xFCk") || suffix.includes("sen") || suffix.includes("san") || suffix.includes("sem") || suffix.includes("sam") || suffix.includes("sek") || suffix.includes("sak");
+          const verbalBases = [stem, ...hardened, ...narrowed];
+          const infinitives = verbalBases.flatMap((v) => restoreInfinitive(v));
+          const variants = [stem, ...hardened, ...vowelDropped, ...geminated, ...narrowed];
+          for (const variant of variants) {
+            if (!seen.has(variant) && variant !== normalized) {
+              seen.add(variant);
+              nextFrontier.push(variant);
+              candidatesWithWeight.push({ candidate: variant, baseLength: stem.length });
+            }
+          }
+          for (const inf of infinitives) {
+            if (!seen.has(inf) && inf !== normalized) {
+              seen.add(inf);
+              nextFrontier.push(inf);
+              const weight = isVerbSuffix ? stem.length + 5 : stem.length;
+              candidatesWithWeight.push({ candidate: inf, baseLength: weight });
+            }
+          }
+        }
+      }
+    }
+    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"));
@@ -150,11 +713,30 @@ M71DMi+y1+TRSJVClEMwvA4yL++7q9XZx5r5wBRWB4kQTKH5qyoZnDw7iiuh1lID
 yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
 -----END CERTIFICATE-----`
   ];
+  // Configuration
+  static defaultTimeoutMs = 8e3;
+  static defaultRetries = 1;
+  static maxCacheSize = 1e3;
   // Cache Mechanism
   static isCacheEnabled = false;
   static wordCache = /* @__PURE__ */ new Map();
   static dailyContentCache = null;
   static autocompleteCache = [];
+  static autocompleteSet = /* @__PURE__ */ new Set();
+  static stemCache = /* @__PURE__ */ new Map();
+  /**
+   * Configures global client options such as network timeout, retries, and cache size.
+   */
+  static configure(config) {
+    if (config.timeoutMs !== void 0)
+      this.defaultTimeoutMs = Math.max(100, config.timeoutMs);
+    if (config.retries !== void 0)
+      this.defaultRetries = Math.max(0, config.retries);
+    if (config.cache !== void 0)
+      this.enableCache(config.cache);
+    if (config.maxCacheSize !== void 0)
+      this.maxCacheSize = Math.max(10, config.maxCacheSize);
+  }
   /**
    * Enables or disables in-memory caching for API requests.
    */
@@ -171,10 +753,53 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     this.wordCache.clear();
     this.dailyContentCache = null;
     this.autocompleteCache = [];
+    this.autocompleteSet.clear();
+    this.stemCache.clear();
+  }
+  static setBoundedCache(map, key, value) {
+    if (map.size >= this.maxCacheSize) {
+      const firstKey = map.keys().next().value;
+      if (firstKey !== void 0)
+        map.delete(firstKey);
+    }
+    map.set(key, value);
   }
   static delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
+  /**
+   * Internal helper that performs HTTP fetch with timeout and automatic retry on network/5xx errors.
+   */
+  static async fetchWithRetry(url, options = {}, retries = this.defaultRetries, timeoutMs = this.defaultTimeoutMs) {
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const signal = AbortSignal.timeout(timeoutMs);
+        const headers = {
+          "User-Agent": "TDK-API-Nodejs-Wrapper/1.0",
+          ...options.headers || {}
+        };
+        const res = await fetch(url, { ...options, headers, signal });
+        if (res.ok || res.status >= 400 && res.status < 500) {
+          return res;
+        }
+        if (attempt < retries) {
+          await this.delay(200 * (attempt + 1));
+          continue;
+        }
+        return res;
+      } catch (err) {
+        lastError = err;
+        if (attempt < retries) {
+          await this.delay(200 * (attempt + 1));
+          continue;
+        }
+      }
+    }
+    throw new TDKNetworkError(`Request to ${url} failed after ${retries + 1} attempts.`, {
+      cause: lastError
+    });
+  }
   /**
    * Fetches detailed information for a given word from the TDK Dictionary.
    */
@@ -189,9 +814,7 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     const url = `${this.BASE_URL}/gts?ara=${encodeURIComponent(cleanWord)}`;
     let response;
     try {
-      response = await fetch(url, {
-        headers: { "User-Agent": "TDK-API-Nodejs-Wrapper/1.0" }
-      });
+      response = await this.fetchWithRetry(url);
     } catch (error) {
       throw new TDKNetworkError("Failed to fetch word from TDK: request failed.", { cause: error });
     }
@@ -208,12 +831,12 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     }
     if (!Array.isArray(data) && data && "error" in data) {
       if (this.isCacheEnabled)
-        this.wordCache.set(cleanWord, []);
+        this.setBoundedCache(this.wordCache, cleanWord, []);
       return [];
     }
     const results = data;
     if (this.isCacheEnabled) {
-      this.wordCache.set(cleanWord, results);
+      this.setBoundedCache(this.wordCache, cleanWord, results);
     }
     return results;
   }
@@ -277,6 +900,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 +920,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.setBoundedCache(this.stemCache, clean, clean);
+      return clean;
+    }
+    const candidates = getStemCandidates(clean);
+    for (const candidate of candidates) {
+      if (await this.isHeadword(candidate)) {
+        this.setBoundedCache(this.stemCache, clean, candidate);
+        return candidate;
+      }
+    }
+    this.setBoundedCache(this.stemCache, 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 +1211,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();
     }
@@ -935,14 +1649,16 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
         meaningCount: meaningsA.length,
         origin: originA,
         syllables: this.syllabicate(a),
-        harmony: this.checkVowelHarmony(a)
+        harmony: this.checkVowelHarmony(a),
+        labialHarmony: this.checkLabialHarmony(a)
       },
       b: {
         word: b,
         meaningCount: meaningsB.length,
         origin: originB,
         syllables: this.syllabicate(b),
-        harmony: this.checkVowelHarmony(b)
+        harmony: this.checkVowelHarmony(b),
+        labialHarmony: this.checkLabialHarmony(b)
       }
     };
   }
@@ -1004,13 +1720,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);
     }
@@ -1058,9 +1789,12 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
   }
   /**
    * Syllabicates a Turkish word based on general grammar rules.
+   * Handles syllable separation for vowels, single consonants, double consonants,
+   * and western loanword three-consonant clusters (e.g. e-lek-trik, kon-trol, or-kes-tra).
    */
   static syllabicate(word) {
     const vowels = /[aeıioöuüAEIİOÖUÜ]/;
+    const ONSET_CLUSTERS = /* @__PURE__ */ new Set(["tr", "pr", "kr", "gr", "br", "fr", "dr", "pl", "kl", "fl", "bl", "gl"]);
     const result = [];
     let currentSyllable = "";
     for (let i = word.length - 1; i >= 0; i--) {
@@ -1071,8 +1805,13 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
             currentSyllable = word[i - 1] + currentSyllable;
             i--;
           } else if (i - 2 >= 0 && !vowels.test(word[i - 2])) {
-            currentSyllable = word[i - 1] + currentSyllable;
-            i--;
+            if (i - 3 >= 0 && !vowels.test(word[i - 3]) && ONSET_CLUSTERS.has((word[i - 2] + word[i - 1]).toLowerCase())) {
+              currentSyllable = word[i - 2] + word[i - 1] + currentSyllable;
+              i -= 2;
+            } else {
+              currentSyllable = word[i - 1] + currentSyllable;
+              i--;
+            }
           }
         }
         result.unshift(currentSyllable);
@@ -1102,11 +1841,307 @@ yDFx8r7i9vIJU5HS3moZLkYWAOilMaV9N56A9Bgb6dNcHkvg3NoaYA==
     const hasFront = frontVowels.test(lower);
     return !(hasBack && hasFront);
   }
+  /**
+   * Checks if a word follows Turkish Minor Vowel Harmony (Küçük Ünlü Uyumu / Labial Harmony).
+   * Rules:
+   * 1. After an unrounded vowel (a, e, ı, i), only unrounded vowels (a, e, ı, i) can follow.
+   * 2. After a rounded vowel (o, ö, u, ü), either an unrounded wide (a, e) or rounded narrow (u, ü) vowel can follow.
+   * Single-syllable words and words with <=1 vowel are considered compliant by convention.
+   */
+  static checkLabialHarmony(word) {
+    const lower = word.toLocaleLowerCase("tr-TR");
+    const vowels = lower.split("").filter((ch) => "ae\u0131io\xF6u\xFC".includes(ch));
+    if (vowels.length <= 1)
+      return true;
+    for (let i = 0; i < vowels.length - 1; i++) {
+      const v1 = vowels[i];
+      const v2 = vowels[i + 1];
+      if ("ae\u0131i".includes(v1)) {
+        if (!"ae\u0131i".includes(v2))
+          return false;
+      } else if ("o\xF6u\xFC".includes(v1)) {
+        if (!"aeu\xFC".includes(v2))
+          return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Searches TDK headwords using a wildcard / pattern string.
+   * Wildcards:
+   *   '_' or '?' matches any single character
+   *   '*' matches zero or more characters
+   * Example: "k_l_m" matches "kalem", "kelam", "kilim".
+   * Runs in-memory against TDK's 81k headword list.
+   */
+  static async patternSearch(pattern, options) {
+    if (!pattern || pattern.trim() === "")
+      return [];
+    await this.ensureAutocompleteLoaded();
+    const cleanPattern = pattern.trim().toLocaleLowerCase("tr-TR");
+    const escaped = cleanPattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/[_?]/g, "[\\p{L}]").replace(/\*/g, "[\\p{L}]*");
+    const regex = new RegExp(`^${escaped}$`, "u");
+    const max = options?.maxResults ?? 50;
+    const matches = [];
+    for (const headword of this.autocompleteCache) {
+      const lower = headword.toLocaleLowerCase("tr-TR");
+      if (regex.test(lower)) {
+        matches.push(headword);
+        if (matches.length >= max)
+          break;
+      }
+    }
+    return matches;
+  }
+  /**
+   * Finds headwords in TDK that can be formed from the given letters (anagrams).
+   * If exact-length anagrams exist, they are returned.
+   * If none exist (or exactLength is false), valid sub-anagrams (words using a subset of the letters,
+   * minimum 3 letters) are returned, sorted by length descending.
+   */
+  static async findAnagrams(letters, options) {
+    if (!letters || letters.trim() === "")
+      return [];
+    await this.ensureAutocompleteLoaded();
+    const clean = letters.trim().toLocaleLowerCase("tr-TR").replace(/[^a-zçğıöşüâîû]/gi, "");
+    if (clean.length === 0)
+      return [];
+    const forceExact = options?.exactLength === true;
+    const max = options?.maxResults ?? 50;
+    const getFrequency = (str) => {
+      const freq = {};
+      for (const ch of str) {
+        freq[ch] = (freq[ch] || 0) + 1;
+      }
+      return freq;
+    };
+    const targetFreq = getFrequency(clean);
+    const exactMatches = [];
+    const subMatches = [];
+    for (const headword of this.autocompleteCache) {
+      const lower = headword.toLocaleLowerCase("tr-TR");
+      if (lower.includes(" ") || lower.includes("-"))
+        continue;
+      if (lower.length > clean.length || lower.length < 3)
+        continue;
+      const wordFreq = getFrequency(lower);
+      let isValid = true;
+      for (const [ch, count] of Object.entries(wordFreq)) {
+        if (!targetFreq[ch] || targetFreq[ch] < count) {
+          isValid = false;
+          break;
+        }
+      }
+      if (isValid && lower !== clean) {
+        if (lower.length === clean.length) {
+          exactMatches.push(headword);
+        } else {
+          subMatches.push(headword);
+        }
+      }
+    }
+    if (exactMatches.length > 0 || forceExact) {
+      return exactMatches.slice(0, max);
+    }
+    subMatches.sort((a, b) => b.length - a.length || a.localeCompare(b, "tr-TR"));
+    return subMatches.slice(0, max);
+  }
+  /**
+   * Finds words in TDK that rhyme with the given word (sharing the same ending suffix/letters).
+   * @param word The target word
+   * @param options.minLetters Minimum number of ending characters that must match (default: 3)
+   * @param options.maxResults Maximum number of rhyme results to return (default: 50)
+   */
+  static async findRhymes(word, options) {
+    if (!word || word.trim() === "")
+      return [];
+    await this.ensureAutocompleteLoaded();
+    const clean = word.trim().toLocaleLowerCase("tr-TR");
+    const minLetters = Math.min(options?.minLetters ?? 3, clean.length);
+    const max = options?.maxResults ?? 50;
+    const suffix = clean.slice(-minLetters);
+    const results = [];
+    for (const headword of this.autocompleteCache) {
+      const lower = headword.toLocaleLowerCase("tr-TR");
+      if (lower !== clean && lower.endsWith(suffix) && !lower.includes(" ")) {
+        results.push(headword);
+        if (results.length >= max)
+          break;
+      }
+    }
+    return results;
+  }
+  /**
+   * Performs comprehensive spelling, grammar, and syntax proofreading on a Turkish text.
+   * Detects:
+   * 1. Conjunction 'da/de' erroneously joined to verbs or words (e.g. "gitsende" -> "gitsen de")
+   * 2. Conjunction 'ki' erroneously joined to verbs (e.g. "gördümki" -> "gördüm ki"), respecting SOMBAHÇEMİ exceptions
+   * 3. Question particle 'mi/mı/mu/mü' erroneously joined to words (e.g. "geldimi" -> "geldi mi")
+   * 4. Misspelled words with dictionary suggestions (via edit-distance & morphology)
+   */
+  static async proofread(text) {
+    if (!text || text.trim() === "") {
+      return { text: text || "", issues: [], isCorrect: true };
+    }
+    await this.ensureAutocompleteLoaded();
+    const issues = [];
+    const SOMBAHCEMI = /* @__PURE__ */ new Set([
+      "sanki",
+      "oysaki",
+      "mademki",
+      "belki",
+      "halbuki",
+      "\xE7\xFCnk\xFC",
+      "me\u011Ferki",
+      "illaki"
+    ]);
+    const tokenRegex = /[\p{L}0-9'’]+/gu;
+    let match;
+    while ((match = tokenRegex.exec(text)) !== null) {
+      const rawWord = match[0];
+      const startIndex = match.index;
+      const endIndex = startIndex + rawWord.length;
+      const lower = rawWord.toLocaleLowerCase("tr-TR");
+      if (/^\d+$/.test(lower))
+        continue;
+      let flagged = false;
+      const questionMatch = lower.match(/^(.+?)(m[ıiuü](?:sin|sın|sun|sün|siniz|sınız|sunuz|sünüz|yiz|yız|yuz|yüz|m|k)?)$/);
+      if (questionMatch) {
+        const base = questionMatch[1];
+        const particle = questionMatch[2];
+        if (base.length >= 2 && (await this.isHeadword(base) || await this.findRoot(base) !== null)) {
+          if (!await this.isHeadword(lower)) {
+            issues.push({
+              type: "question_particle",
+              word: rawWord,
+              startIndex,
+              endIndex,
+              suggestion: `${base} ${particle}`,
+              message: `'${particle}' soru eki kendinden \xF6nceki kelimeden ayr\u0131 yaz\u0131lmal\u0131d\u0131r.`
+            });
+            flagged = true;
+          }
+        }
+      }
+      const VERB_CONJUGATION_REGEX = /(?:d[ıiuü][kmmn]?|t[ıiuü][kmmn]?|d[ıiuü]n[ıiuü]z?|t[ıiuü]n[ıiuü]z?|m[ıiuü]ş(?:[szn][ıiuü]z?|lar)?|yor(?:um|sun|uz|lar)?|ecek(?:sin|iz|ler)?|acak(?:sın|ız|lar)?|s[ae][mnk]|s[ae]n[ıiz]?|meli|malı|me[mz]|ma[mz])$/i;
+      if (!flagged && lower.endsWith("ki") && lower.length > 3) {
+        const base = lower.slice(0, -2);
+        if (!SOMBAHCEMI.has(lower)) {
+          if (!await this.isHeadword(lower)) {
+            const root = await this.findRoot(base);
+            const isVerb = root && (root.endsWith("mek") || root.endsWith("mak")) || base === "demek" || base === "kald\u0131" || base === "yeter" || base === "bilmem" || VERB_CONJUGATION_REGEX.test(base);
+            if (isVerb) {
+              issues.push({
+                type: "conjunction_ki",
+                word: rawWord,
+                startIndex,
+                endIndex,
+                suggestion: `${base} ki`,
+                message: `'ki' ba\u011Flac\u0131 ayr\u0131 yaz\u0131lmal\u0131d\u0131r.`
+              });
+              flagged = true;
+            }
+          }
+        }
+      }
+      if (!flagged && (lower.endsWith("de") || lower.endsWith("da") || lower.endsWith("te") || lower.endsWith("ta")) && lower.length > 3) {
+        const base = lower.slice(0, -2);
+        const ending = lower.slice(-2);
+        if (!await this.isHeadword(lower)) {
+          const root = await this.findRoot(base);
+          const isVerb = root && (root.endsWith("mek") || root.endsWith("mak")) || VERB_CONJUGATION_REGEX.test(base);
+          if (isVerb) {
+            const correctEnding = ending.startsWith("t") ? ending === "te" ? "de" : "da" : ending;
+            issues.push({
+              type: "conjunction_da",
+              word: rawWord,
+              startIndex,
+              endIndex,
+              suggestion: `${base} ${correctEnding}`,
+              message: `'da/de' ba\u011Flac\u0131 fiillerden sonra her zaman ayr\u0131 yaz\u0131l\u0131r (ba\u011Fla\xE7 olan da/de sertle\u015Fmez).`
+            });
+            flagged = true;
+          }
+        }
+      }
+      if (!flagged) {
+        const check = await this.checkSpelling(rawWord);
+        if (!check.isCorrect) {
+          issues.push({
+            type: "spelling",
+            word: rawWord,
+            startIndex,
+            endIndex,
+            suggestion: check.suggestion,
+            message: check.suggestion ? `'${rawWord}' yanl\u0131\u015F yaz\u0131lm\u0131\u015F olabilir. \xD6neri: '${check.suggestion}'` : `'${rawWord}' s\xF6zl\xFCkte bulunamad\u0131.`
+          });
+        }
+      }
+    }
+    return {
+      text,
+      issues,
+      isCorrect: issues.length === 0
+    };
+  }
+};
+var TDKClient = class {
+  constructor(config) {
+    if (config) {
+      TDK.configure(config);
+    }
+  }
+  getWord(word) {
+    return TDK.getWord(word);
+  }
+  getMeanings(word) {
+    return TDK.getMeanings(word);
+  }
+  checkSpelling(word) {
+    return TDK.checkSpelling(word);
+  }
+  findRoot(word) {
+    return TDK.findRoot(word);
+  }
+  stem(word) {
+    return TDK.stem(word);
+  }
+  proofread(text) {
+    return TDK.proofread(text);
+  }
+  patternSearch(pattern, options) {
+    return TDK.patternSearch(pattern, options);
+  }
+  findAnagrams(letters, options) {
+    return TDK.findAnagrams(letters, options);
+  }
+  findRhymes(word, options) {
+    return TDK.findRhymes(word, options);
+  }
+  syllabicate(word) {
+    return TDK.syllabicate(word);
+  }
+  checkVowelHarmony(word) {
+    return TDK.checkVowelHarmony(word);
+  }
+  checkLabialHarmony(word) {
+    return TDK.checkLabialHarmony(word);
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TDK,
+  TDKClient,
   TDKError,
   TDKNetworkError,
-  TDKValidationError
+  TDKValidationError,
+  TURKISH_SUFFIXES,
+  TURKISH_VOWELS,
+  getStemCandidates,
+  isVowel,
+  restoreConsonantSoftening,
+  restoreGemination,
+  restoreInfinitive,
+  restoreVowelDrop,
+  restoreVowelNarrowing
 });