tdk-api-wrapper 1.3.1 → 1.4.0

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   TDK
-} from "./chunk-ACMGCL7T.mjs";
+} from "./chunk-5TYJDVHK.mjs";
 
 // src/cli.ts
 var rawArgs = process.argv.slice(2);
@@ -15,6 +15,9 @@ var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
   "hece",
   "uyum",
   "yazim",
+  "kok",
+  "stem",
+  "deyim",
   "gunun",
   "rastgele",
   "esanlam",
@@ -53,7 +56,7 @@ async function run() {
   if (!command || command === "--help" || command === "-h") {
     console.log("Kullan\u0131m: tdk [komut] <kelime> [--json]");
     console.log(
-      "Komutlar: ara, anlam, koken, ornek, hece, uyum, yazim, gunun, rastgele, esanlam, karsit, yabanci, kurallar, kural, karsilastir, analiz, oneri, kubbealti, nisanyan, viki"
+      "Komutlar: ara, anlam, koken, ornek, hece, uyum, yazim, kok, deyim, gunun, rastgele, esanlam, karsit, yabanci, kurallar, kural, karsilastir, analiz, oneri, kubbealti, nisanyan, viki"
     );
     console.log("Not: Komut belirtilmezse do\u011Frudan kelime anlam\u0131 aran\u0131r (\xF6rn: tdk selam)");
     process.exit(command ? 0 : 1);
@@ -121,13 +124,46 @@ async function run() {
         const spellResult = await TDK.checkSpelling(word);
         printResult(spellResult, () => {
           if (spellResult.isCorrect) {
-            console.log("Do\u011Fru yaz\u0131m.");
+            if (spellResult.isInflected && spellResult.root) {
+              console.log(`Do\u011Fru yaz\u0131m (\xE7ekimli bi\xE7im, k\xF6k: ${spellResult.root}).`);
+            } else {
+              console.log("Do\u011Fru yaz\u0131m.");
+            }
           } else {
             console.log(`Yanl\u0131\u015F yaz\u0131m.${spellResult.suggestion ? " Do\u011Frusu: " + spellResult.suggestion : ""}`);
           }
         });
         break;
       }
+      case "kok":
+      case "stem": {
+        if (!word)
+          throw new Error("Kelime belirtmelisiniz.");
+        const stemResult = await TDK.stem(word);
+        printResult(stemResult, () => {
+          if (!stemResult) {
+            console.log("K\xF6k bulunamad\u0131.");
+          } else if (stemResult.isInflected) {
+            console.log(`K\xF6k: ${stemResult.root} (\xE7ekimli bi\xE7im)`);
+          } else {
+            console.log(`K\xF6k: ${stemResult.root} (yal\u0131n bi\xE7im)`);
+          }
+        });
+        break;
+      }
+      case "deyim": {
+        if (!word)
+          throw new Error("Kelime belirtmelisiniz.");
+        const proverbs = await TDK.getProverbs(word);
+        printResult(proverbs, () => {
+          if (proverbs.length === 0) {
+            console.log("Atas\xF6z\xFC/deyim bulunamad\u0131.");
+          } else {
+            proverbs.forEach((p, i) => console.log(`${i + 1}. ${p}`));
+          }
+        });
+        break;
+      }
       case "gunun": {
         const wotd = await TDK.getWordOfTheDay();
         printResult(wotd, () => {
@@ -234,7 +270,8 @@ async function run() {
           } else {
             analysis.forEach((a) => {
               if (a.found) {
-                console.log(`${a.word}: ${a.meaning ?? "-"} (${a.origin})`);
+                const rootLabel = a.isInflected && a.root ? ` (k\xF6k: ${a.root})` : "";
+                console.log(`${a.word}${rootLabel}: ${a.meaning ?? "-"} (${a.origin})`);
               } else {
                 console.log(`${a.word}: bulunamad\u0131`);
               }

package/dist/index.d.mts

@@ -95,6 +95,14 @@ interface SpellCheckResult {
     isCorrect: boolean;
     word: string;
     suggestion?: string;
+    isInflected?: boolean;
+    root?: string;
+}
+interface StemResult {
+    word: string;
+    root: string;
+    isInflected: boolean;
+    candidates?: string[];
 }
 interface WordOfTheDay {
     word: string;
@@ -125,6 +133,8 @@ interface WordAnalysis {
     found: boolean;
     meaning: string | null;
     origin: string | null;
+    root?: string;
+    isInflected?: boolean;
 }
 interface KubbealtiEntry {
     kelime: string;
@@ -162,6 +172,8 @@ declare class TDK {
     private static wordCache;
     private static dailyContentCache;
     private static autocompleteCache;
+    private static autocompleteSet;
+    private static stemCache;
     /**
      * Enables or disables in-memory caching for API requests.
      */
@@ -191,6 +203,10 @@ declare class TDK {
      * this, this fails closed to `[]` rather than throwing.
      */
     private static fetchAutocompleteData;
+    /**
+     * Ensures TDK's ~81k headword list is loaded in memory for fast O(1) set operations.
+     */
+    private static ensureAutocompleteLoaded;
     /**
      * Returns autocomplete suggestions for a given prefix, searched over TDK's
      * full headword list (see `fetchAutocompleteData`). The list is fetched
@@ -198,6 +214,27 @@ declare class TDK {
      * caching behavior as before — and only cleared by `clearCache()`.
      */
     static getSuggestions(prefix: string): Promise<string[]>;
+    /**
+     * 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 isHeadword(word: string): Promise<boolean>;
+    /**
+     * Generates candidate roots for a given Turkish word using progressive BFS suffix stripping,
+     * consonant mutation restoration, and vowel drop restoration.
+     */
+    static getStemCandidates(word: string): string[];
+    /**
+     * 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 findRoot(word: string): Promise<string | null>;
+    /**
+     * Performs morphological stemming on a Turkish word.
+     * Returns a StemResult containing the original word, resolved root, and whether it is inflected.
+     */
+    static stem(word: string): Promise<StemResult | null>;
     /**
      * Returns a list of proverbs and idioms containing the word.
      */
@@ -470,4 +507,54 @@ declare class TDKNetworkError extends TDKError {
     });
 }
 
-export { type Author, type DailyContent, type DailyPick, type Example, type Feature, type KubbealtiEntry, type Meaning, type Proverb, type SpellCheckResult, TDK, TDKError, TDKNetworkError, type TDKResponse, type TDKRule, TDKValidationError, type WiktionaryEntry, type WordAnalysis, type WordComparison, type WordComparisonSide, type WordInfo, type WordOfTheDay };
+/**
+ * Turkish Morphology Engine & Stem Candidate Generator.
+ *
+ * Implements heuristic-based progressive suffix stripping (BFS) with:
+ * 1. Comprehensive Turkish suffix catalogue (inflectional, derivational, composite)
+ * 2. Reverse consonant mutation (ünsüz yumuşaması / sertleşmesi: b->p, c->ç, d->t, ğ->k, g->k)
+ * 3. Reverse vowel drop (ünlü düşmesi: akl->akıl, şehr->şehir, omz->omuz)
+ * 4. Infinitive restoration (-mek / -mak for verbal stems)
+ * 5. Apostrophe stripping for proper nouns (İstanbul'da -> İstanbul)
+ */
+declare const TURKISH_VOWELS = "ae\u0131io\u00F6u\u00FC";
+declare function isVowel(ch: string): boolean;
+/**
+ * Turkish suffixes ordered strictly by descending length so that longer
+ * composite suffixes match before their individual subcomponents.
+ */
+declare const TURKISH_SUFFIXES: readonly string[];
+/**
+ * Reverses Turkish consonant softening (ünsüz yumuşaması):
+ * When a root ends with p, ç, t, k, it softens to b, c, d, ğ, g before a vowel.
+ * This restores the hardened dictionary headword form.
+ */
+declare function restoreConsonantSoftening(stem: string): string[];
+/**
+ * Reverses Turkish vowel drop (ünlü düşmesi):
+ * In words like akıl->aklım, şehir->şehre, burun->burnu, omuz->omzum,
+ * the narrow vowel in the second syllable drops when receiving a vowel-initial suffix.
+ * This restores the harmonic dropped vowel between the final consonant cluster.
+ */
+declare function restoreVowelDrop(stem: string): string[];
+/**
+ * Restores verb infinitive headword form (-mek / -mak):
+ * Since TDK registers verbs in their infinitive form (e.g. okumak, gelmek, yazmak),
+ * conjugated verb stems (e.g. oku, gel, yaz) need -mak/-mek appended according to vowel harmony.
+ */
+declare function restoreInfinitive(stem: string): string[];
+/**
+ * Generates candidate roots for a given Turkish word using progressive BFS suffix stripping,
+ * consonant mutation restoration, vowel drop restoration, and infinitive restoration.
+ *
+ * Candidates are sorted so that longer base stems (less aggressive stripping) are checked first,
+ * preventing spurious 2-letter roots from overshadowing genuine headwords.
+ *
+ * @param word The input word to analyze
+ * @param minStemLength Minimum allowed length for candidate stems (default: 2)
+ * @param maxDepth Maximum levels of progressive suffix stripping (default: 4)
+ * @returns Array of unique candidate roots in prioritized order
+ */
+declare function getStemCandidates(word: string, minStemLength?: number, maxDepth?: number): string[];
+
+export { type Author, type DailyContent, type DailyPick, type Example, type Feature, type KubbealtiEntry, type Meaning, type Proverb, type SpellCheckResult, type StemResult, TDK, TDKError, TDKNetworkError, type TDKResponse, type TDKRule, TDKValidationError, TURKISH_SUFFIXES, TURKISH_VOWELS, type WiktionaryEntry, type WordAnalysis, type WordComparison, type WordComparisonSide, type WordInfo, type WordOfTheDay, getStemCandidates, isVowel, restoreConsonantSoftening, restoreInfinitive, restoreVowelDrop };

package/dist/index.d.ts

@@ -95,6 +95,14 @@ interface SpellCheckResult {
     isCorrect: boolean;
     word: string;
     suggestion?: string;
+    isInflected?: boolean;
+    root?: string;
+}
+interface StemResult {
+    word: string;
+    root: string;
+    isInflected: boolean;
+    candidates?: string[];
 }
 interface WordOfTheDay {
     word: string;
@@ -125,6 +133,8 @@ interface WordAnalysis {
     found: boolean;
     meaning: string | null;
     origin: string | null;
+    root?: string;
+    isInflected?: boolean;
 }
 interface KubbealtiEntry {
     kelime: string;
@@ -162,6 +172,8 @@ declare class TDK {
     private static wordCache;
     private static dailyContentCache;
     private static autocompleteCache;
+    private static autocompleteSet;
+    private static stemCache;
     /**
      * Enables or disables in-memory caching for API requests.
      */
@@ -191,6 +203,10 @@ declare class TDK {
      * this, this fails closed to `[]` rather than throwing.
      */
     private static fetchAutocompleteData;
+    /**
+     * Ensures TDK's ~81k headword list is loaded in memory for fast O(1) set operations.
+     */
+    private static ensureAutocompleteLoaded;
     /**
      * Returns autocomplete suggestions for a given prefix, searched over TDK's
      * full headword list (see `fetchAutocompleteData`). The list is fetched
@@ -198,6 +214,27 @@ declare class TDK {
      * caching behavior as before — and only cleared by `clearCache()`.
      */
     static getSuggestions(prefix: string): Promise<string[]>;
+    /**
+     * 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 isHeadword(word: string): Promise<boolean>;
+    /**
+     * Generates candidate roots for a given Turkish word using progressive BFS suffix stripping,
+     * consonant mutation restoration, and vowel drop restoration.
+     */
+    static getStemCandidates(word: string): string[];
+    /**
+     * 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 findRoot(word: string): Promise<string | null>;
+    /**
+     * Performs morphological stemming on a Turkish word.
+     * Returns a StemResult containing the original word, resolved root, and whether it is inflected.
+     */
+    static stem(word: string): Promise<StemResult | null>;
     /**
      * Returns a list of proverbs and idioms containing the word.
      */
@@ -470,4 +507,54 @@ declare class TDKNetworkError extends TDKError {
     });
 }
 
-export { type Author, type DailyContent, type DailyPick, type Example, type Feature, type KubbealtiEntry, type Meaning, type Proverb, type SpellCheckResult, TDK, TDKError, TDKNetworkError, type TDKResponse, type TDKRule, TDKValidationError, type WiktionaryEntry, type WordAnalysis, type WordComparison, type WordComparisonSide, type WordInfo, type WordOfTheDay };
+/**
+ * Turkish Morphology Engine & Stem Candidate Generator.
+ *
+ * Implements heuristic-based progressive suffix stripping (BFS) with:
+ * 1. Comprehensive Turkish suffix catalogue (inflectional, derivational, composite)
+ * 2. Reverse consonant mutation (ünsüz yumuşaması / sertleşmesi: b->p, c->ç, d->t, ğ->k, g->k)
+ * 3. Reverse vowel drop (ünlü düşmesi: akl->akıl, şehr->şehir, omz->omuz)
+ * 4. Infinitive restoration (-mek / -mak for verbal stems)
+ * 5. Apostrophe stripping for proper nouns (İstanbul'da -> İstanbul)
+ */
+declare const TURKISH_VOWELS = "ae\u0131io\u00F6u\u00FC";
+declare function isVowel(ch: string): boolean;
+/**
+ * Turkish suffixes ordered strictly by descending length so that longer
+ * composite suffixes match before their individual subcomponents.
+ */
+declare const TURKISH_SUFFIXES: readonly string[];
+/**
+ * Reverses Turkish consonant softening (ünsüz yumuşaması):
+ * When a root ends with p, ç, t, k, it softens to b, c, d, ğ, g before a vowel.
+ * This restores the hardened dictionary headword form.
+ */
+declare function restoreConsonantSoftening(stem: string): string[];
+/**
+ * Reverses Turkish vowel drop (ünlü düşmesi):
+ * In words like akıl->aklım, şehir->şehre, burun->burnu, omuz->omzum,
+ * the narrow vowel in the second syllable drops when receiving a vowel-initial suffix.
+ * This restores the harmonic dropped vowel between the final consonant cluster.
+ */
+declare function restoreVowelDrop(stem: string): string[];
+/**
+ * Restores verb infinitive headword form (-mek / -mak):
+ * Since TDK registers verbs in their infinitive form (e.g. okumak, gelmek, yazmak),
+ * conjugated verb stems (e.g. oku, gel, yaz) need -mak/-mek appended according to vowel harmony.
+ */
+declare function restoreInfinitive(stem: string): string[];
+/**
+ * Generates candidate roots for a given Turkish word using progressive BFS suffix stripping,
+ * consonant mutation restoration, vowel drop restoration, and infinitive restoration.
+ *
+ * Candidates are sorted so that longer base stems (less aggressive stripping) are checked first,
+ * preventing spurious 2-letter roots from overshadowing genuine headwords.
+ *
+ * @param word The input word to analyze
+ * @param minStemLength Minimum allowed length for candidate stems (default: 2)
+ * @param maxDepth Maximum levels of progressive suffix stripping (default: 4)
+ * @returns Array of unique candidate roots in prioritized order
+ */
+declare function getStemCandidates(word: string, minStemLength?: number, maxDepth?: number): string[];
+
+export { type Author, type DailyContent, type DailyPick, type Example, type Feature, type KubbealtiEntry, type Meaning, type Proverb, type SpellCheckResult, type StemResult, TDK, TDKError, TDKNetworkError, type TDKResponse, type TDKRule, TDKValidationError, TURKISH_SUFFIXES, TURKISH_VOWELS, type WiktionaryEntry, type WordAnalysis, type WordComparison, type WordComparisonSide, type WordInfo, type WordOfTheDay, getStemCandidates, isVowel, restoreConsonantSoftening, restoreInfinitive, restoreVowelDrop };