lafzi_dart 1.0.0

Al-Quran phonetic search engine. Search Quran verses by Latin transliteration using trigram indexing and phonetic matching. Pure Dart, works with Flutter.

lafzi_dart

Al-Quran phonetic search engine for Dart & Flutter. Search Quran verses by Latin transliteration (e.g. "kunfayakun", "bismillah") using trigram indexing and phonetic matching.

Pure Dart — no Flutter dependency required. Works as a standalone Dart package.

Ported from lafzi.js with SQLite backend for fast, efficient search.

Features

• Phonetic search with Latin transliteration input
• Two modes: vocal (with harakat) and nonvocal (consonants only)
• Configurable match threshold (0.3 - 0.95)
• Text highlighting of matched regions
• SQLite backend — fast, 50ms per query
• Optional gzip compression for database (~45% smaller)
• Pure Dart, works standalone and in Flutter

Installation

dependencies:
  lafzi_dart: ^1.0.0

Database

You need a lafzi.sqlite database file. Either:

1. Download pre-built from GitHub Releases
2. Build from source using the included tool:

   dart run tool/build_db.dart <source_dir> data/lafzi.sqlite
   dart run tool/build_db.dart <source_dir> data/lafzi_compressed.sqlite --compress
   

Source data files are from lafzi.js/.uncompressed_data.

Usage

import 'package:lafzi_dart/lafzi_dart.dart';

final db = await LafziDatabase.open('path/to/lafzi_compressed.sqlite');

final results = await search(
  db,
  'kunfayakun',
  options: SearchOptions(
    mode: 'v',          // 'v' = vocal, 'nv' = nonvocal
    threshold: 0.95,    // 0.3 - 0.95
    isHilight: true,    // generate highlighted text
  ),
);

for (final verse in results) {
  print('${verse.surahName} ${verse.ayatNo}');
  print('  ${verse.textArabic}');
  print('  ${verse.textIndonesian}');
  print('  Score: ${verse.score}');
}

db.close();

Phonetic Conversion Only

No database needed for phonetic conversion:

import 'package:lafzi_dart/lafzi_dart.dart';

print(convert('bismillah'));        // BISMILAH
print(convertNoVowel('bismillah')); // BSMLH
print(convert('alhamdulillah'));    // XALHAMDULILAH

Search Options

Option	Type	Default	Description
mode	String	'v'	'v' = with vowels, 'nv' = consonants only
threshold	double	0.95	Match threshold (0.3 - 0.95). Lower = more results
isHilight	bool	true	Generate <span> highlighted text
multipleHighlightPos	bool	false	Return all highlight spans

QuranVerse Fields

Field	Type	Description
surahNo	int	Surah number (1-114)
surahName	String	Surah name
ayatNo	int	Verse number
textArabic	String	Arabic text
textIndonesian	String	Indonesian translation
score	double	Match score (higher = better)
highlightPositions	List<int>	Highlight positions
textHilight	String?	HTML-highlighted text
muqathaatText	String?	Muqathaat text (if applicable)

Compressed Database

Use --compress flag to build a smaller database:

Uncompressed: 14.3 MB
Compressed:    7.9 MB (-45%)

Search overhead: ~6-13ms per query

The library auto-detects compressed vs uncompressed databases.

Flutter Example

See example/flutter_example/ for a complete Flutter app with:

• Async database download with progress indicator
• Cached database (downloads only once)
• Non-blocking search
• Vocal/nonvocal mode toggle
• Adjustable threshold

cd example/flutter_example
flutter pub get
flutter run

CLI Example

# From repo root
dart run example/cli_search.dart data/lafzi.sqlite "kunfayakun"
dart run example/cli_search.dart data/lafzi.sqlite "bismillah" v 0.8
dart run example/cli_search.dart data/lafzi.sqlite "alhamdulillah" nv 0.7

Project Structure

lafzi_dart/
├── lib/
│   ├── lafzi_dart.dart        # Public API
│   └── src/
│       ├── phonetics.dart      # Phonetic conversion
│       ├── trigram.dart        # Trigram extraction
│       ├── array.dart          # LCS, contiguity, highlight span
│       ├── database.dart       # SQLite layer + QuranVerse
│       ├── searcher.dart       # Search pipeline
│       └── hilight.dart        # Text highlighting
├── tool/
│   └── build_db.dart           # Build SQLite from source data
├── example/
│   ├── cli_search.dart         # Dart CLI example
│   └── flutter_example/        # Flutter app example
└── test/
    └── lafzi_test.dart         # Unit + integration tests

Credit

• Original algorithm: lafzi.js by Sigit Prabowo

License

MIT License