tdk-api-wrapper 1.3.1 → 1.5.0

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;
@@ -115,6 +123,7 @@ interface WordComparisonSide {
     origin: string | null;
     syllables: string[];
     harmony: boolean;
+    labialHarmony?: boolean;
 }
 interface WordComparison {
     a: WordComparisonSide;
@@ -125,6 +134,38 @@ interface WordAnalysis {
     found: boolean;
     meaning: string | null;
     origin: string | null;
+    root?: string;
+    isInflected?: boolean;
+}
+interface ProofreadIssue {
+    type: "spelling" | "conjunction_da" | "conjunction_ki" | "question_particle";
+    word: string;
+    startIndex: number;
+    endIndex: number;
+    suggestion?: string;
+    message: string;
+}
+interface ProofreadResult {
+    text: string;
+    issues: ProofreadIssue[];
+    isCorrect: boolean;
+}
+interface PatternSearchOptions {
+    maxResults?: number;
+}
+interface AnagramOptions {
+    exactLength?: boolean;
+    maxResults?: number;
+}
+interface RhymeOptions {
+    minLetters?: number;
+    maxResults?: number;
+}
+interface TDKConfig {
+    timeoutMs?: number;
+    retries?: number;
+    cache?: boolean;
+    maxCacheSize?: number;
 }
 interface KubbealtiEntry {
     kelime: string;
@@ -158,10 +199,19 @@ declare class TDK {
      * fail-closed contract as the rest of this file's fragile integrations.
      */
     private static readonly KUBBEALTI_EXTRA_CA;
+    private static defaultTimeoutMs;
+    private static defaultRetries;
+    private static maxCacheSize;
     private static isCacheEnabled;
     private static wordCache;
     private static dailyContentCache;
     private static autocompleteCache;
+    private static autocompleteSet;
+    private static stemCache;
+    /**
+     * Configures global client options such as network timeout, retries, and cache size.
+     */
+    static configure(config: TDKConfig): void;
     /**
      * Enables or disables in-memory caching for API requests.
      */
@@ -170,7 +220,12 @@ declare class TDK {
      * Clears the internal cache.
      */
     static clearCache(): void;
+    private static setBoundedCache;
     private static delay;
+    /**
+     * Internal helper that performs HTTP fetch with timeout and automatic retry on network/5xx errors.
+     */
+    private static fetchWithRetry;
     /**
      * Fetches detailed information for a given word from the TDK Dictionary.
      */
@@ -191,6 +246,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 +257,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.
      */
@@ -434,6 +514,8 @@ declare class TDK {
     static getWordsBatch(words: string[]): Promise<WordInfo[][]>;
     /**
      * 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: string): string[];
     /**
@@ -443,6 +525,65 @@ declare class TDK {
      * (dotless) as the front vowel "i" (dotted).
      */
     static checkVowelHarmony(word: string): boolean;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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 patternSearch(pattern: string, options?: PatternSearchOptions): Promise<string[]>;
+    /**
+     * 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 findAnagrams(letters: string, options?: AnagramOptions): Promise<string[]>;
+    /**
+     * 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 findRhymes(word: string, options?: RhymeOptions): Promise<string[]>;
+    /**
+     * 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 proofread(text: string): Promise<ProofreadResult>;
+}
+/**
+ * Configurable instance-based client for TDK API.
+ * Useful for multi-tenant applications or backend services requiring isolated configurations.
+ */
+declare class TDKClient {
+    constructor(config?: TDKConfig);
+    getWord(word: string): Promise<WordInfo[]>;
+    getMeanings(word: string): Promise<string[]>;
+    checkSpelling(word: string): Promise<SpellCheckResult>;
+    findRoot(word: string): Promise<string | null>;
+    stem(word: string): Promise<StemResult | null>;
+    proofread(text: string): Promise<ProofreadResult>;
+    patternSearch(pattern: string, options?: PatternSearchOptions): Promise<string[]>;
+    findAnagrams(letters: string, options?: AnagramOptions): Promise<string[]>;
+    findRhymes(word: string, options?: RhymeOptions): Promise<string[]>;
+    syllabicate(word: string): string[];
+    checkVowelHarmony(word: string): boolean;
+    checkLabialHarmony(word: string): boolean;
 }
 
 /**
@@ -470,4 +611,68 @@ 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[];
+/**
+ * Reverses Turkish consonant gemination (ünsüz türemesi / ikizleşmesi):
+ * In words of Arabic/foreign origin, when receiving a vowel-initial suffix, the final consonant doubles:
+ * e.g. hak->hakkı, his->hissi, sır->sırrı, af->affı, ret->reddi, tıp->tıbbı, zam->zammı, hat->hattı.
+ * Restores the single consonant form and checks consonant softening on the result (e.g. redd -> red -> ret).
+ */
+declare function restoreGemination(stem: string): string[];
+/**
+ * Reverses Turkish vowel narrowing (ünlü daralması):
+ * Verbs ending in wide vowels 'a' or 'e' narrow to 'ı', 'i', 'u', 'ü' before the continuous tense suffix -yor:
+ * e.g. başla-yor -> başlıyor, bekle-yor -> bekliyor, özle-yor -> özlüyor, anla-yor -> anlıyor.
+ * Also handles irregular monosyllabic verbs: de-yor -> diyor, ye-yor -> yiyor.
+ */
+declare function restoreVowelNarrowing(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 AnagramOptions, type Author, type DailyContent, type DailyPick, type Example, type Feature, type KubbealtiEntry, type Meaning, type PatternSearchOptions, type ProofreadIssue, type ProofreadResult, type Proverb, type RhymeOptions, type SpellCheckResult, type StemResult, TDK, TDKClient, type TDKConfig, 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, restoreGemination, restoreInfinitive, restoreVowelDrop, restoreVowelNarrowing };