@sabiq/utils 0.0.1

package/dist/esm/utils/validation.js

@@ -0,0 +1,236 @@
+import { levenshteinDistance } from "./levenshtein";
+import { normalizeArabic } from "./arabic";
+import { wordAlternatives, getAlternativesFor, } from "./wordAlternatives";
+/**
+ * Standard threshold: 30% of the word's length, rounded up.
+ */
+export function defaultThreshold(word) {
+    return Math.ceil(word.length * 0.3);
+}
+function isBetterAsMerge(prevSpoken, currentSpoken, prevExpected, currentExpected) {
+    const currNorm = joinForAltCompare(currentSpoken);
+    if (currNorm.length === 0 || currNorm.length > 3)
+        return false;
+    const prevNorm = joinForAltCompare(prevSpoken);
+    const expPrevNorm = joinForAltCompare(prevExpected);
+    const expCurrNorm = joinForAltCompare(currentExpected);
+    if (prevNorm.length === 0 ||
+        expPrevNorm.length === 0 ||
+        expCurrNorm.length === 0) {
+        return false;
+    }
+    const allowedPrev = defaultThreshold(expPrevNorm);
+    const mergedLen = prevNorm.length + currNorm.length;
+    if (mergedLen > expPrevNorm.length + allowedPrev)
+        return false;
+    if (expPrevNorm.length > mergedLen + allowedPrev)
+        return false;
+    const dPrev = levenshteinDistance(prevNorm, expPrevNorm);
+    if (dPrev === 0)
+        return false;
+    const merged = prevNorm + currNorm;
+    const dMerged = levenshteinDistance(merged, expPrevNorm);
+    if (dMerged > allowedPrev || dMerged >= dPrev)
+        return false;
+    // Tiebreaker: only override CORRECT if merge fits prev STRICTLY better
+    // than current fits its own expected. Without this, a coincidentally
+    // similar current (e.g. "في" sharing a leading char with "ني" in "مكني")
+    // would falsely get absorbed.
+    const dCurrent = levenshteinDistance(currNorm, expCurrNorm);
+    return dMerged < dCurrent;
+}
+function matchesMain(spoken, expected) {
+    const a = normalizeArabic(spoken);
+    const b = normalizeArabic(expected);
+    return levenshteinDistance(a, b) <= defaultThreshold(b);
+}
+function isPrefixOfMain(spoken, expected) {
+    const a = normalizeArabic(spoken);
+    const b = normalizeArabic(expected);
+    if (a.length === 0 || a.length >= b.length)
+        return false;
+    const prefix = b.slice(0, a.length);
+    return levenshteinDistance(a, prefix) <= defaultThreshold(prefix);
+}
+function joinForAltCompare(s) {
+    return normalizeArabic(s).replace(/[\s\u200B-\u200F\u202A-\u202E\u00A0]/g, "");
+}
+function matchesAnyAlternative(spoken, alts) {
+    const a = joinForAltCompare(spoken);
+    for (const alt of alts) {
+        const altNorm = joinForAltCompare(alt);
+        const distance = levenshteinDistance(a, altNorm);
+        const allowed = defaultThreshold(altNorm);
+        const lenDiff = Math.abs(a.length - altNorm.length);
+        // For short joined alts (≤ 4 chars — the compact muqatta'at forms),
+        // require exact equality. Each char in a compact form represents one
+        // entire letter of the muqatta'at, so even a single edit completely
+        // changes the meaning. Without this, a single spoken letter like "الف"
+        // (3 chars) falsely full-matches the compact alt "الم" (3 chars, also
+        // 1 edit away), preventing the prefix path from collecting subsequent
+        // letters.
+        if (altNorm.length <= 4) {
+            if (distance === 0)
+                return true;
+            continue;
+        }
+        if (distance <= allowed && lenDiff <= Math.ceil(allowed / 2)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isPrefixOfAnyAlternative(spoken, alts) {
+    const a = joinForAltCompare(spoken);
+    if (a.length === 0)
+        return false;
+    for (const alt of alts) {
+        const altNorm = joinForAltCompare(alt);
+        if (a.length >= altNorm.length)
+            continue;
+        const prefix = altNorm.slice(0, a.length);
+        if (levenshteinDistance(a, prefix) <= defaultThreshold(prefix))
+            return true;
+    }
+    return false;
+}
+/**
+ * Inverse of isPrefixOfMain: is the EXPECTED word a prefix of SPOKEN?
+ * Detects when STT combined two mushaf words into one token.
+ */
+function isContainedIn(spoken, expected) {
+    const a = normalizeArabic(spoken);
+    const b = normalizeArabic(expected);
+    if (b.length < 2)
+        return false;
+    if (b.length >= a.length)
+        return false;
+    const remainderLen = a.length - b.length;
+    if (remainderLen < 2)
+        return false;
+    const prefix = a.slice(0, b.length);
+    // First-character anchor. The single most reliable signal that prefix
+    // is structurally aligned with expected, not coincidentally similar.
+    if (prefix[0] !== b[0])
+        return false;
+    return levenshteinDistance(prefix, b) <= defaultThreshold(b);
+}
+function splitContained(spoken, expected) {
+    const a = normalizeArabic(spoken);
+    const b = normalizeArabic(expected);
+    return a.slice(b.length);
+}
+/**
+ * Word-split merge detection.
+ *
+ * STT sometimes splits one mushaf word into two short tokens (e.g. "يَٰذَا"
+ * → "يا" + "ذا"). The first token may have been accepted as a fuzzy match
+ * for the mushaf word; the second now has nothing to match against.
+ *
+ * We detect this by checking whether `prevSpoken + currentSpoken` matches
+ * the previous expected word *strictly better* than `prevSpoken` alone.
+ *
+ * The strictness gate (dMerged < dPrev) is critical:
+ *   - If prev was an exact match (dPrev = 0), no merge is possible — current
+ *     must be a separate word.
+ *   - If prev was fuzzy (dPrev > 0), merge fires only when adding current
+ *     improves the distance, which is exactly the STT-split signal.
+ */
+function matchesAsMerge(prevSpoken, currentSpoken, prevExpected) {
+    const prevNorm = joinForAltCompare(prevSpoken);
+    const currNorm = joinForAltCompare(currentSpoken);
+    const expNorm = joinForAltCompare(prevExpected);
+    if (prevNorm.length === 0 || currNorm.length === 0 || expNorm.length === 0) {
+        return false;
+    }
+    if (currNorm.length > expNorm.length) {
+        return false;
+    }
+    const allowed = defaultThreshold(expNorm);
+    const mergedLen = prevNorm.length + currNorm.length;
+    // Length-difference lower bound on Levenshtein. If merged is too far
+    // from expected in raw length, distance can't be within threshold.
+    if (mergedLen > expNorm.length + allowed)
+        return false;
+    if (expNorm.length > mergedLen + allowed)
+        return false;
+    const merged = prevNorm + currNorm;
+    const dMerged = levenshteinDistance(merged, expNorm);
+    if (dMerged > allowed)
+        return false;
+    const dPrev = levenshteinDistance(prevNorm, expNorm);
+    // Improvement gate: merged must be strictly closer, OR same distance
+    // with strictly more length (which means current contributed signal
+    // that aligned with the tail of expected).
+    return dMerged < dPrev || (dMerged === dPrev && mergedLen > prevNorm.length);
+}
+/**
+ * Validate a buffered spoken token against the expected word at currentIndex.
+ *
+ * @param lastCorrectToken The raw token that produced the most recent
+ *        "correct" outcome at currentIndex - 1. Used by the merge mechanism
+ *        to detect STT word-splits. Pass null if not tracking, or if the
+ *        previous outcome was anything other than "correct".
+ */
+export function validateRecitation(buffer, expected, currentIndex, alternatives = wordAlternatives, lastCorrectToken = null) {
+    const trimmed = buffer.trim();
+    const target = expected[currentIndex];
+    if (!target) {
+        return { status: "wrong", advance: true, newBuffer: "" };
+    }
+    const position = { surah: target.surah, verse: target.verse };
+    const alts = getAlternativesFor(target.text, position.surah, position.verse, alternatives);
+    const tryMerge = () => {
+        if (!lastCorrectToken || currentIndex === 0)
+            return null;
+        const prevExpected = expected[currentIndex - 1];
+        if (!prevExpected)
+            return null;
+        if (matchesAsMerge(lastCorrectToken, trimmed, prevExpected.text)) {
+            return { status: "merge", advance: false, newBuffer: "" };
+        }
+        return null;
+    };
+    // === Muqatta'at path ===
+    if (alts.length > 0) {
+        if (matchesAnyAlternative(trimmed, alts)) {
+            return { status: "correct", advance: true, newBuffer: "" };
+        }
+        if (normalizeArabic(trimmed) === normalizeArabic(target.text)) {
+            return { status: "correct", advance: true, newBuffer: "" };
+        }
+        if (isPrefixOfAnyAlternative(trimmed, alts)) {
+            return { status: "pending", advance: false, newBuffer: trimmed };
+        }
+        const merge = tryMerge();
+        if (merge)
+            return merge;
+        return { status: "wrong", advance: true, newBuffer: "" };
+    }
+    // === Normal main-word path ===
+    if (matchesMain(trimmed, target.text)) {
+        if (lastCorrectToken && currentIndex > 0) {
+            const prevExpected = expected[currentIndex - 1];
+            if (prevExpected &&
+                isBetterAsMerge(lastCorrectToken, trimmed, prevExpected.text, target.text)) {
+                return { status: "merge", advance: false, newBuffer: "" };
+            }
+        }
+        return { status: "correct", advance: true, newBuffer: "" };
+    }
+    if (isContainedIn(trimmed, target.text)) {
+        return {
+            status: "split",
+            advance: true,
+            newBuffer: "",
+            remainder: splitContained(trimmed, target.text),
+        };
+    }
+    if (isPrefixOfMain(trimmed, target.text)) {
+        return { status: "pending", advance: false, newBuffer: trimmed };
+    }
+    const merge = tryMerge();
+    if (merge)
+        return merge;
+    return { status: "wrong", advance: true, newBuffer: "" };
+}

package/dist/esm/utils/wordAlternatives.d.ts

@@ -0,0 +1,41 @@
+export interface WordAlternative {
+    /** The expected word in the mushaf (or its normalized form). */
+    word: string;
+    /** Acceptable spoken alternatives. */
+    alternatives: string[];
+    /** Optional scope: only apply at this surah:verse. */
+    scope?: {
+        surah: number;
+        verse: number;
+    };
+}
+/**
+ * The الحروف المقطعة (muqatta'at) appear ONLY at ayah 1 of specific surahs
+ * (and in one case, ayah 2 of الشورى — عسق). They look identical to normal
+ * Arabic words like أَلَمْ in other contexts, so we must scope them.
+ *
+ * Each muqatta'at entry carries up to three alt forms, listed in order of
+ * expected real-world frequency. Whichever matches first wins, so order
+ * matters for performance only — correctness is unaffected by ordering.
+ *
+ *   1. Realistic hybrid — short letters compact (ك, ه, ط, ح, ر), long
+ *      letters spelled out (ميم, لام, سين, عين, صاد, قاف, نون, كاف).
+ *      This is what reciters actually say, and what STT actually delivers.
+ *
+ *   2. Pure compact — every letter as a single consonant char. After
+ *      joinForAltCompare strips spaces this becomes the mushaf form
+ *      itself, giving exact prefix matching for letter-by-letter input.
+ *
+ *   3. Full letter names — every letter spelled out (الف, ها, يا, etc.).
+ *      Backstop for STT that delivers full phonetic forms.
+ *
+ * Single-letter muqatta'at (ص، ق، ن) only need two forms since compact
+ * and mushaf collapse to the same single character.
+ */
+export declare const wordAlternatives: WordAlternative[];
+/**
+ * Look up alternatives for an expected word at a specific position.
+ * Returns alternatives only if a scoped entry matches the surah:verse,
+ * or if there's an unscoped entry (for future generic alternatives).
+ */
+export declare function getAlternativesFor(expected: string, surah: number, verse: number, alternatives?: WordAlternative[]): string[];

package/dist/esm/utils/wordAlternatives.js

@@ -0,0 +1,226 @@
+// utils/wordAlternatives.ts
+import { normalizeArabic } from "./arabic";
+/**
+ * The الحروف المقطعة (muqatta'at) appear ONLY at ayah 1 of specific surahs
+ * (and in one case, ayah 2 of الشورى — عسق). They look identical to normal
+ * Arabic words like أَلَمْ in other contexts, so we must scope them.
+ *
+ * Each muqatta'at entry carries up to three alt forms, listed in order of
+ * expected real-world frequency. Whichever matches first wins, so order
+ * matters for performance only — correctness is unaffected by ordering.
+ *
+ *   1. Realistic hybrid — short letters compact (ك, ه, ط, ح, ر), long
+ *      letters spelled out (ميم, لام, سين, عين, صاد, قاف, نون, كاف).
+ *      This is what reciters actually say, and what STT actually delivers.
+ *
+ *   2. Pure compact — every letter as a single consonant char. After
+ *      joinForAltCompare strips spaces this becomes the mushaf form
+ *      itself, giving exact prefix matching for letter-by-letter input.
+ *
+ *   3. Full letter names — every letter spelled out (الف, ها, يا, etc.).
+ *      Backstop for STT that delivers full phonetic forms.
+ *
+ * Single-letter muqatta'at (ص، ق، ن) only need two forms since compact
+ * and mushaf collapse to the same single character.
+ */
+export const wordAlternatives = [
+    // البقرة 2:1, آل عمران 3:1, العنكبوت 29:1, الروم 30:1, لقمان 31:1, السجدة 32:1
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 2, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 3, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 29, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 30, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 31, verse: 1 },
+    },
+    {
+        word: "الم",
+        alternatives: ["ا لام ميم", "ا ل م", "الف لام ميم"],
+        scope: { surah: 32, verse: 1 },
+    },
+    // الأعراف 7:1
+    {
+        word: "المص",
+        alternatives: ["ا لام ميم صاد", "ا ل م ص", "الف لام ميم صاد"],
+        scope: { surah: 7, verse: 1 },
+    },
+    // يونس 10:1, هود 11:1, يوسف 12:1, إبراهيم 14:1, الحجر 15:1
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 10, verse: 1 },
+    },
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 11, verse: 1 },
+    },
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 12, verse: 1 },
+    },
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 14, verse: 1 },
+    },
+    {
+        word: "الر",
+        alternatives: ["ا لام را", "ا ل ر", "الف لام را", "الف لام راء"],
+        scope: { surah: 15, verse: 1 },
+    },
+    // الرعد 13:1
+    {
+        word: "المر",
+        alternatives: [
+            "ا لام ميم را",
+            "ا ل م ر",
+            "الف لام ميم را",
+            "الف لام ميم راء",
+        ],
+        scope: { surah: 13, verse: 1 },
+    },
+    // مريم 19:1
+    {
+        word: "كهيعص",
+        alternatives: [
+            "ك ه يا عين صاد",
+            "ك ه ي ع ص",
+            "كاف ها يا عين صاد",
+            "كاف هاء ياء عين صاد",
+        ],
+        scope: { surah: 19, verse: 1 },
+    },
+    // طه 20:1
+    {
+        word: "طه",
+        alternatives: ["ط ها", "ط ه", "طا ها", "طا هاء"],
+        scope: { surah: 20, verse: 1 },
+    },
+    // الشعراء 26:1, القصص 28:1
+    {
+        word: "طسم",
+        alternatives: ["ط سين ميم", "ط س م", "طا سين ميم"],
+        scope: { surah: 26, verse: 1 },
+    },
+    {
+        word: "طسم",
+        alternatives: ["ط سين ميم", "ط س م", "طا سين ميم"],
+        scope: { surah: 28, verse: 1 },
+    },
+    // النمل 27:1
+    {
+        word: "طس",
+        alternatives: ["ط سين", "ط س", "طا سين"],
+        scope: { surah: 27, verse: 1 },
+    },
+    // يس 36:1 — realistic and full collapse to "يا سين"; ياسين covers the
+    // run-on form some reciters/STT produce.
+    {
+        word: "يس",
+        alternatives: ["يا سين", "ي س", "ياسين"],
+        scope: { surah: 36, verse: 1 },
+    },
+    // ص 38:1 — single letter; compact and mushaf form are identical.
+    {
+        word: "ص",
+        alternatives: ["صاد", "ص"],
+        scope: { surah: 38, verse: 1 },
+    },
+    // غافر 40:1, فصلت 41:1, الزخرف 43:1, الدخان 44:1, الجاثية 45:1, الأحقاف 46:1
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 40, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 41, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 43, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 44, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 45, verse: 1 },
+    },
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 46, verse: 1 },
+    },
+    // الشورى 42:1 = حم, 42:2 = عسق (split across two ayahs)
+    {
+        word: "حم",
+        alternatives: ["ح ميم", "ح م", "حا ميم", "حاء ميم"],
+        scope: { surah: 42, verse: 1 },
+    },
+    {
+        word: "عسق",
+        alternatives: ["عين سين قاف", "ع س ق"],
+        scope: { surah: 42, verse: 2 },
+    },
+    // ق 50:1 — single letter; compact and mushaf collapse.
+    {
+        word: "ق",
+        alternatives: ["قاف", "ق"],
+        scope: { surah: 50, verse: 1 },
+    },
+    // القلم 68:1 — single letter; compact and mushaf collapse.
+    {
+        word: "ن",
+        alternatives: ["نون", "ن"],
+        scope: { surah: 68, verse: 1 },
+    },
+];
+/**
+ * Look up alternatives for an expected word at a specific position.
+ * Returns alternatives only if a scoped entry matches the surah:verse,
+ * or if there's an unscoped entry (for future generic alternatives).
+ */
+export function getAlternativesFor(expected, surah, verse, alternatives = wordAlternatives) {
+    const normalized = normalizeArabic(expected);
+    const out = [];
+    for (const entry of alternatives) {
+        const wordMatches = entry.word === expected || entry.word === normalized;
+        if (!wordMatches)
+            continue;
+        // Unscoped entries always apply.
+        if (!entry.scope) {
+            out.push(...entry.alternatives);
+            continue;
+        }
+        // Scoped entries only apply at their position.
+        if (entry.scope.surah === surah && entry.scope.verse === verse) {
+            out.push(...entry.alternatives);
+        }
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@sabiq/utils",
+  "version": "0.0.1",
+  "description": "A library of utils for use with Sabiq applications.",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf ./dist/ && yarn build:esm && yarn build:cjs",
+    "build:esm": "tsc",
+    "build:cjs": "tsc --module commonjs --outDir dist/cjs",
+    "lint": "eslint \"{**/*,*}.{js,ts,jsx,tsx}\"",
+    "prettier": "prettier --write \"{src,tests,example/src}/**/*.{js,ts,jsx,tsx}\""
+  },
+  "homepage": "https://github.com/Sabiq-Quran-App/SabiqUtils",
+  "bugs": {
+    "url": "https://github.com/Sabiq-Quran-App/SabiqUtils/issues"
+  },
+  "repository": {
+    "url": "https://github.com/Sabiq-Quran-App/SabiqUtils.git",
+    "type": "git"
+  },
+  "author": "Shady Abdelaziz",
+  "keywords": [
+    "sabiq",
+    "quran",
+    "react",
+    "mushaf",
+    "religion"
+  ],
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.19.1",
+    "@types/react": "^18.0.18",
+    "@typescript-eslint/eslint-plugin": "^5.36.2",
+    "@typescript-eslint/parser": "^5.36.2",
+    "eslint": "^8.23.0",
+    "eslint-config-prettier": "^8.5.0",
+    "eslint-plugin-prettier": "^4.2.1",
+    "eslint-plugin-react": "^7.31.7",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "prettier": "^2.7.1",
+    "react": "^18.2.0",
+    "typescript": "^4.8.2"
+  },
+  "peerDependencies": {
+    "@sabiq/types": "^0.0.1",
+    "react": "^18.2.0"
+  },
+  "packageManager": "yarn@1.22.22"
+}