tdk-api-wrapper 1.3.0 → 1.4.0

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   TDK
-} from "./chunk-SLNXKZKR.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.
      */
@@ -325,14 +362,29 @@ declare class TDK {
      * `null` on any error — network, TLS, HTTP, or JSON parse.
      */
     private static fetchKubbealtiJson;
+    /**
+     * Kubbealtı indexes headwords with full classical Turkish orthography,
+     * including letters that a plain-ASCII-ish query tends to drop — most
+     * commonly ü/ö/ç/ğ/ş, but also the circumflex ("düzeltme işareti") used in
+     * Arabic/Persian loanwords like "rüzgâr". A search for "ruzgar" misses
+     * entirely (verified: even "ruzgâr" alone still misses — it's the missing
+     * ü, not the missing â, that actually breaks the match). This generates
+     * single-letter-substitution variants to retry, one substitution per
+     * variant (not combinatorial) — covers the overwhelmingly common case of
+     * one "de-Turkished" letter without an explosion of API calls for words
+     * with several.
+     */
+    private static readonly TURKISH_DEASCII_MAP;
+    private static generateTurkishVariants;
     /**
      * Returns Kubbealtı Lugatı ("Misalli Büyük Türkçe Sözlük") entries for a
      * word, scraped from the site's own data API — undocumented, and Kubbealtı
      * Lugatı is a commercial dictionary product, unlike TDK's or Wiktionary's
      * openly-published data, so use this in line with their terms. `anlam` is
      * raw HTML (rich typography markup); use `getKubbealtiMeanings()` for
-     * plain text. Returns `null` on any fetch/parse failure, `[]` if the word
-     * isn't found.
+     * plain text. Falls back to `generateTurkishVariants()` if the exact query
+     * comes up empty (see its doc comment). Returns `null` on any fetch/parse
+     * failure, `[]` if no variant matches either.
      */
     static getKubbealti(word: string): Promise<KubbealtiEntry[] | null>;
     /**
@@ -354,14 +406,20 @@ declare class TDK {
      * case) or the request fails.
      */
     static getNisanyan(word: string): Promise<string | null>;
+    private static fetchWiktionaryEntry;
     /**
      * Returns the Turkish Wiktionary (`tr.wiktionary.org`) entry for a word,
      * via MediaWiki's official Action API (`action=query&prop=extracts`) — no
      * scraping involved, this is a stable, documented public API. `sections`
      * splits the plain-text extract on its `== Heading ==`/`=== Heading ===`
      * markers (e.g. "Köken", "Söyleniş", "Ad") for convenience; `raw` has the
-     * unsplit text. Returns `null` if the page doesn't exist or the request
-     * fails.
+     * unsplit text. This wiki has title capitalization turned off
+     * ($wgCapitalLinks=false — common for Wiktionaries, since case is
+     * meaningful for a dictionary: "Türkiye" the country vs. a lowercase
+     * common word), so an exact-case miss retries with the first letter
+     * uppercased (Turkish-locale-aware, so "istanbul" tries "İstanbul", not
+     * "Istanbul") before giving up. Returns `null` if neither is found or the
+     * request fails.
      */
     static getWiktionary(word: string): Promise<WiktionaryEntry | null>;
     /**
@@ -449,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.
      */
@@ -325,14 +362,29 @@ declare class TDK {
      * `null` on any error — network, TLS, HTTP, or JSON parse.
      */
     private static fetchKubbealtiJson;
+    /**
+     * Kubbealtı indexes headwords with full classical Turkish orthography,
+     * including letters that a plain-ASCII-ish query tends to drop — most
+     * commonly ü/ö/ç/ğ/ş, but also the circumflex ("düzeltme işareti") used in
+     * Arabic/Persian loanwords like "rüzgâr". A search for "ruzgar" misses
+     * entirely (verified: even "ruzgâr" alone still misses — it's the missing
+     * ü, not the missing â, that actually breaks the match). This generates
+     * single-letter-substitution variants to retry, one substitution per
+     * variant (not combinatorial) — covers the overwhelmingly common case of
+     * one "de-Turkished" letter without an explosion of API calls for words
+     * with several.
+     */
+    private static readonly TURKISH_DEASCII_MAP;
+    private static generateTurkishVariants;
     /**
      * Returns Kubbealtı Lugatı ("Misalli Büyük Türkçe Sözlük") entries for a
      * word, scraped from the site's own data API — undocumented, and Kubbealtı
      * Lugatı is a commercial dictionary product, unlike TDK's or Wiktionary's
      * openly-published data, so use this in line with their terms. `anlam` is
      * raw HTML (rich typography markup); use `getKubbealtiMeanings()` for
-     * plain text. Returns `null` on any fetch/parse failure, `[]` if the word
-     * isn't found.
+     * plain text. Falls back to `generateTurkishVariants()` if the exact query
+     * comes up empty (see its doc comment). Returns `null` on any fetch/parse
+     * failure, `[]` if no variant matches either.
      */
     static getKubbealti(word: string): Promise<KubbealtiEntry[] | null>;
     /**
@@ -354,14 +406,20 @@ declare class TDK {
      * case) or the request fails.
      */
     static getNisanyan(word: string): Promise<string | null>;
+    private static fetchWiktionaryEntry;
     /**
      * Returns the Turkish Wiktionary (`tr.wiktionary.org`) entry for a word,
      * via MediaWiki's official Action API (`action=query&prop=extracts`) — no
      * scraping involved, this is a stable, documented public API. `sections`
      * splits the plain-text extract on its `== Heading ==`/`=== Heading ===`
      * markers (e.g. "Köken", "Söyleniş", "Ad") for convenience; `raw` has the
-     * unsplit text. Returns `null` if the page doesn't exist or the request
-     * fails.
+     * unsplit text. This wiki has title capitalization turned off
+     * ($wgCapitalLinks=false — common for Wiktionaries, since case is
+     * meaningful for a dictionary: "Türkiye" the country vs. a lowercase
+     * common word), so an exact-case miss retries with the first letter
+     * uppercased (Turkish-locale-aware, so "istanbul" tries "İstanbul", not
+     * "Istanbul") before giving up. Returns `null` if neither is found or the
+     * request fails.
      */
     static getWiktionary(word: string): Promise<WiktionaryEntry | null>;
     /**
@@ -449,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 };