TypeScript SDK
Fully typed client for Node.js, Deno, Bun, and edge runtimes.
Installation
npm install kalimalabClient initialization
import KalimaLab from 'kalimalab'const client = new KalimaLab({ apiKey: process.env.KALIMALAB_API_KEY,})Methods
client.words.searchSearch Arabic words by query text with optional filters.
client.words.search(params: { q: string limit?: number offset?: number root?: string pattern?: string pos?: string letters?: number}): Promise<SearchResult>| Param | Type | Req | Description |
|---|---|---|---|
q | string | Yes | Search query — Arabic text or Latin characters |
limit | number | No | 1–100 results per page. Default: 20. |
offset | number | No | Pagination offset. Default: 0. |
root | string | No | Filter by Arabic root (e.g. كتب) |
pattern | string | No | Filter by morphological pattern |
pos | string | No | Part of speech: noun, verb, adjective, adverb |
letters | number | No | Filter by exact letter count |
Returns: Promise<SearchResult> — { data: Word[], total: number, offset: number, limit: number }
const result = await client.words.search({ q: 'كتب', limit: 10 })console.log(result.total) // 47console.log(result.data[0]) // { id, word, meaning_en, root, ... }client.words.getFetch full linguistic details for a single word by its slug.
client.words.get(slug: string): Promise<Word>| Param | Type | Req | Description |
|---|---|---|---|
slug | string | Yes | Word slug or ID (from search results) |
Returns: Promise<Word>
const word = await client.words.get('كتب')console.log(word.meaning_en) // 'to write'console.log(word.root) // 'كتب'client.words.dailyGet the word of the day.
client.words.daily(): Promise<Word>Returns: Promise<Word>
const word = await client.words.daily()console.log(word.word) // 'الأَمَل'console.log(word.meaning_en) // 'hope'client.words.randomGet randomly selected Arabic words.
client.words.random(params?: { count?: number }): Promise<Word[]>| Param | Type | Req | Description |
|---|---|---|---|
count | number | No | 1–20 words. Default: 1. |
Returns: Promise<Word[]>
const words = await client.words.random({ count: 5 })words.forEach(w => console.log(w.word))client.words.validateCheck whether Arabic strings exist in the KalimaLab database.
client.words.validate(words: string[]): Promise<ValidationResult>| Param | Type | Req | Description |
|---|---|---|---|
words | string[] | Yes | Up to 100 Arabic words to validate |
Returns: Promise<{ valid: string[], invalid: string[], count: { valid: number, invalid: number } }>
const result = await client.words.validate(['كتب', 'xyz123', 'مدرسة'])console.log(result.valid) // ['كتب', 'مدرسة']console.log(result.invalid) // ['xyz123']client.text.analyzeAnalyze a passage of Arabic text.
client.text.analyze(text: string): Promise<TextAnalysis>| Param | Type | Req | Description |
|---|---|---|---|
text | string | Yes | Arabic text to analyze (max 5,000 characters) |
Returns: Promise<TextAnalysis> — { wordCount, letterCount, uniqueWords, frequency }
const analysis = await client.text.analyze('بسم الله الرحمن الرحيم')console.log(analysis.wordCount) // 4client.stats.getReturn database statistics.
client.stats.get(): Promise<Stats>Returns: Promise<{ totalWords: number, totalRoots: number, totalPatterns: number }>
const stats = await client.stats.get()console.log(stats.totalWords) // 477000Error handling
import KalimaLab, { KalimaLabError } from 'kalimalab'try { const result = await client.words.search({ q: 'كتب' })} catch (err) { if (err instanceof KalimaLabError) { console.error(err.status) // 401, 429, 500 console.error(err.code) // 'unauthorized' | 'rate_limited' | ... console.error(err.message) }}TypeScript types
import type { Word, SearchResult, TextAnalysis, ValidationResult, Stats, KalimaLabError,} from 'kalimalab'