Merge pull request #88 from Vexxo-Dev/develop

feat(worker): offload browser search to web worker

Author: adelpro

README.md

@@ -37,6 +37,7 @@ Stateless, UI-agnostic Quran (Qur'an) search engine for Arabic text in pure Type
 - [Multi-word search](#multi-word-search)
 - [Caching with LRUCache](#caching-with-lrucache)
 - [Performance Optimization](#performance-optimization-advanced)
+- [Web Worker Offloading](#web-worker-offloading-browser)
 - [Core types](#core-types)
 - [Non-goals](#non-goals)
 - [Example apps](#example-apps)
@@ -1226,10 +1227,12 @@ src/
 │   ├── search.test.ts       # Search algorithm, inverted index, LRU cache, and Fuse tests
 │   ├── lru-cache.test.ts    # LRU cache tests
 │   └── tokenization.test.ts # Token matching tests
-└── utils/
-    ├── loader.test.ts       # Data loading tests
-    ├── normalization.test.ts # Text processing tests
-    └── highlight.ts         # Highlighting utilities
+├── utils/
+│   ├── loader.test.ts       # Data loading tests
+│   ├── normalization.test.ts # Text processing tests
+│   └── highlight.ts         # Highlighting utilities
+└── worker/
+    └── searchWorkerClient.test.ts # Worker client + fallback tests
 ```
 
 ## Development

eslint.config.mjs

@@ -2,6 +2,10 @@ import js from '@eslint/js';
 import tseslint from 'typescript-eslint';
 import prettier from 'eslint-plugin-prettier/recommended';
 import globals from 'globals';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export default tseslint.config(
   {
@@ -24,6 +28,9 @@ export default tseslint.config(
     languageOptions: {
       ecmaVersion: 2020,
       sourceType: 'module',
+      parserOptions: {
+        tsconfigRootDir: __dirname,
+      },
       globals: {
         ...globals.node,
         ...globals.jest,

examples/angular/src/app/app.component.ts

@@ -8,12 +8,15 @@ import {
   loadWordMap,
   search,
   LRUCache,
+  createSearchWorker,
+  supportsWorkers,
   type AdvancedSearchOptions,
   type MatchType,
   type MorphologyAya,
   type QuranText,
   type ScoredVerse,
   type SearchResponse,
+  type SearchWorkerClient,
   type WordMap,
 } from 'quran-search-engine';
 
@@ -375,21 +378,37 @@ export class AppComponent implements OnInit, OnDestroy {
 
   private debounceHandle: number | null = null;
   private searchCache = new LRUCache<string, SearchResponse<QuranText>>(50);
+  private workerClient: SearchWorkerClient | null = null;
 
   async ngOnInit(): Promise<void> {
     this.loadState = 'loading';
     this.errorMessage = '';
 
     try {
-      const [quranData, morphologyMap, wordMap] = await Promise.all([
-        loadQuranData(),
-        loadMorphology(),
-        loadWordMap(),
-      ]);
-
-      this.quranData = quranData;
-      this.morphologyMap = morphologyMap;
-      this.wordMap = wordMap;
+      if (supportsWorkers()) {
+        try {
+          const client = createSearchWorker({
+            workerUrl: new URL('quran-search-engine/worker', import.meta.url),
+          });
+          await client.initData();
+          this.workerClient = client;
+        } catch (err) {
+          console.warn('Web Worker init failed, falling back to main thread:', err);
+        }
+      }
+
+      if (!this.workerClient) {
+        const [quranData, morphologyMap, wordMap] = await Promise.all([
+          loadQuranData(),
+          loadMorphology(),
+          loadWordMap(),
+        ]);
+
+        this.quranData = quranData;
+        this.morphologyMap = morphologyMap;
+        this.wordMap = wordMap;
+      }
+
       this.loadState = 'ready';
     } catch (err: unknown) {
       this.loadState = 'error';
@@ -401,6 +420,7 @@ export class AppComponent implements OnInit, OnDestroy {
     if (this.debounceHandle !== null) {
       window.clearTimeout(this.debounceHandle);
     }
+    this.workerClient?.terminate();
   }
 
   onQueryChange(): void {
@@ -414,8 +434,6 @@ export class AppComponent implements OnInit, OnDestroy {
   }
 
   runSearch(resetPage: boolean): void {
-    if (!this.quranData || !this.morphologyMap || !this.wordMap) return;
-
     const trimmed = this.query.trim();
     if (!trimmed) {
       this.response = null;
@@ -429,22 +447,34 @@ export class AppComponent implements OnInit, OnDestroy {
       lemma: this.options.lemma,
       root: this.options.root,
       fuzzy: this.options.fuzzy,
-      //+
       suraId: this.options.suraId,
       juzId: this.options.juzId,
       suraName: this.options.suraName,
       semantic: this.options.semantic,
     };
 
+    if (this.workerClient) {
+      this.workerClient
+        .runSearch(trimmed, searchOptions, { page: this.page, limit: this.limit })
+        .then((res) => {
+          this.response = res;
+          this.rebuildHighlightCache();
+        })
+        .catch((err) => console.error('Worker search error:', err));
+      return;
+    }
+
+    if (!this.quranData || !this.morphologyMap || !this.wordMap) return;
+
     this.response = search(
       trimmed,
       this.quranData,
       this.morphologyMap,
       this.wordMap,
       searchOptions,
       { page: this.page, limit: this.limit },
-      undefined, // preComputedFuseIndex
-      this.searchCache, // LRU cache — identical queries return cached results
+      undefined,
+      this.searchCache,
     );
 
     this.rebuildHighlightCache();

examples/vanilla-ts/src/main.ts

@@ -4,10 +4,13 @@ import {
   loadWordMap,
   search,
   LRUCache,
+  createSearchWorker,
+  supportsWorkers,
   type QuranText,
   type MorphologyAya,
   type WordMap,
   type SearchResponse,
+  type SearchWorkerClient,
   getHighlightRanges,
 } from 'quran-search-engine';
 
@@ -17,6 +20,7 @@ class QuranSearchApp {
   private wordMap: WordMap | null = null;
   private loading = true;
   private cache = new LRUCache<string, SearchResponse>(50);
+  private workerClient: SearchWorkerClient | null = null;
 
   private searchInput: HTMLInputElement;
   private lemmaCheckbox: HTMLInputElement;
@@ -46,14 +50,29 @@ class QuranSearchApp {
   private async init() {
     try {
       this.showLoading();
-      const [data, morphology, dictionary] = await Promise.all([
-        loadQuranData(),
-        loadMorphology(),
-        loadWordMap(),
-      ]);
-      this.quranData = data;
-      this.morphologyMap = morphology;
-      this.wordMap = dictionary;
+
+      if (supportsWorkers()) {
+        try {
+          const client = createSearchWorker({
+            workerUrl: new URL('quran-search-engine/worker', import.meta.url),
+          });
+          await client.initData();
+          this.workerClient = client;
+        } catch (err) {
+          console.warn('Web Worker init failed, falling back to main thread:', err);
+        }
+      }
+
+      if (!this.workerClient) {
+        const [data, morphology, dictionary] = await Promise.all([
+          loadQuranData(),
+          loadMorphology(),
+          loadWordMap(),
+        ]);
+        this.quranData = data;
+        this.morphologyMap = morphology;
+        this.wordMap = dictionary;
+      }
     } catch (error) {
       console.error('Failed to load Quran data:', error);
       this.showError('Failed to load Quran data');
@@ -79,7 +98,7 @@ class QuranSearchApp {
     }) as T;
   }
 
-  private handleSearch() {
+  private async handleSearch() {
     const query = this.searchInput.value.trim();
     if (!query || this.loading) {
       this.resultsDiv.innerHTML = '';
@@ -91,23 +110,28 @@ class QuranSearchApp {
       root: this.rootCheckbox.checked,
       fuzzy: this.fuzzyCheckbox.checked,
       semantic: this.semanticCheckbox.checked,
-      //new
       suraId: this.suraIdInput.value ? parseInt(this.suraIdInput.value) : undefined,
       juzId: this.juzIdInput.value ? parseInt(this.juzIdInput.value) : undefined,
       suraName: this.suraNameInput.value || undefined,
     };
 
     try {
-      const response = search(
-        query,
-        this.quranData,
-        this.morphologyMap!,
-        this.wordMap!,
-        options,
-        { page: 1, limit: 20 },
-        undefined, // preComputedFuseIndex
-        this.cache, // LRU cache
-      );
+      let response: SearchResponse;
+
+      if (this.workerClient) {
+        response = await this.workerClient.runSearch(query, options, { page: 1, limit: 20 });
+      } else {
+        response = search(
+          query,
+          this.quranData,
+          this.morphologyMap!,
+          this.wordMap!,
+          options,
+          { page: 1, limit: 20 },
+          undefined,
+          this.cache,
+        );
+      }
 
       this.renderResults(response);
     } catch (error) {