Normalisasi Ayah dan `preBismillah`

Di dalam operate, array verses dibangun dari arab.ayahs.map (crawler/script.js:116-120¹). Iterasi itu bukan sekadar penyalinan: setiap ayat diubah menjadi objek baru dengan bentuk yang seragam, sementara teks dan tafsirnya diambil dari tiga edisi lain serta dari berkas lokal. Hasilnya adalah satu objek ayah dengan kunci number, meta, text, translation, audio, dan tafsir.

Empat edisi dan pembagian perannya

Keempat edisi diminta sekaligus lewat parameter editions pada satu URL, dengan urutan tetap (crawler/script.js:13-16²). Respons mentah dikonversi lebih dulu dengan mengganti \\u menjadi %u sebelum JSON.parse (crawler/script.js:53-55³), sehingga isi ayat tersimpan sebagai rangkaian persen selama proses berjalan. Konversi balik ke bentuk \\u baru dilakukan saat berkas ditulis (crawler/script.js:203⁴).

Berkas temp dimuat sebagai konstanta tingkat modul (crawler/script.js:10⁵) dan menjadi kunci pencarian per ayat: temp diindeks dengan \${arab.number}.${ayah.numberInSurah}``, yaitu gabungan nomor surah dan nomor ayat di dalam surah (crawler/script.js:116-120¹).

graph TD
  REQ["request editions: quran-simple-enhanced,ar.alafasy,en.transliteration,en.sahih"]
  PARSE["JSON.parse → data[0..3]"]
  SIMPLE["simple"]
  ARAB["arab"]
  TRANS["transliteration"]
  ENG["english"]
  TEMP["temp: quran-tafsir.json"]
  MAP["arab.ayahs.map"]
  OUT["satu objek ayah di verses"]
  REQ --> PARSE
  PARSE --> SIMPLE
  PARSE --> ARAB
  PARSE --> TRANS
  PARSE --> ENG
  ARAB --> MAP
  SIMPLE --> MAP
  TRANS --> MAP
  ENG --> MAP
  TEMP --> MAP
  MAP --> OUT
  style REQ fill:#f59e0b,color:#000
  style PARSE fill:#f59e0b,color:#000
  style ARAB fill:#336791,color:#fff
  style SIMPLE fill:#8b5cf6,color:#fff
  style TRANS fill:#8b5cf6,color:#fff
  style ENG fill:#8b5cf6,color:#fff
  style TEMP fill:#8b5cf6,color:#fff
  style MAP fill:#2d7d46,color:#fff
  style OUT fill:#2d7d46,color:#fff
%% fig: Empat edisi menuju satu objek ayah
%% desc: Satu request mengambil empat edisi, lalu setiap array ayah digabung per posisi oleh arab.ayahs.map menjadi objek verses.

Peta field per ayat

Field number (crawler/script.js:121-124⁶), meta (crawler/script.js:125-140⁷), text (crawler/script.js:141-148), translation (crawler/script.js:149-152), audio (crawler/script.js:153-156), dan tafsir (crawler/script.js:157-162) mengikuti tabel di atas tanpa perhitungan tambahan selain pemotongan spasi.

⚠️ Perataan antar edisi memakai idx dari iterasi arab.ayahs, bukan nomor ayat. Jika salah satu edisi mengembalikan jumlah ayat yang berbeda, ayat berikutnya pada edisi itu akan bergeser satu posisi dan teksnya tetap masuk tanpa error.

Konversi sajda

ayah.sajda tidak selalu berbentuk sama. Ketika bernilai objek, hanya recommended dan obligatory yang diambil, sedangkan id dibuang. Ketika bernilai boolean, kedua field diisi dengan nilai boolean tersebut (crawler/script.js:131-139¹²). Hasilnya selalu objek dua field, seperti yang terlihat pada berkas keluaran (data/quran.json:37-47¹³).

Pembersihan tag HTML pada tafsir

Ada dua jalur tafsir yang diperlakukan berbeda. Tafsir tingkat surah, yaitu keterangan dari sumber kedua, dibersihkan dari tag HTML dengan replace(/(<([^>]+)>)/gi, ''); untuk surah 13 dan 55, kata Makkiyyah di dalamnya juga diganti menjadi Madaniyyah, lalu hasilnya di-trim (crawler/script.js:88-96¹⁴). Tafsir tingkat ayat tidak melewati pembersihan itu: short dan long hanya di-trim (crawler/script.js:157-162¹¹).

Menghapus basmalah pembuka

Pada keluaran, basmalah disimpan satu kali di tingkat surah lewat field preBismillah, yang bernilai null untuk surah 1 dan surah 9 (crawler/script.js:97-107¹⁵). Karena itu teks Arab ayat pertama tidak boleh memuat basmalah lagi. Pembersihannya hanya dijalankan ketika arab.number !== 1 dan idx === 0 (crawler/script.js:141-148⁸); ayat pertama surah 1 dibiarkan utuh karena basmalah di sana adalah ayat pertama itu sendiri.

preBismillahHandler menyimpan dua varian basmalah dalam bentuk persen sebagai kunci replacer, masing-masing dengan turunan RegExp ber-flag gi (crawler/script.js:40-47¹⁶). Handler mencari kunci yang terkandung di dalam ayat melalui ayah.includes(key), mengambil pasangan regEx-nya, menjalankan ayah.replace(regEx, ''), lalu trim(). Varian kedua berbeda pada penulisan harakat, sehingga satu pola saja tidak cukup.

graph TD
  A{"arab.number !== 1 dan idx === 0"}
  A -- ya --> B["preBismillahHandler(arabText)"]
  A -- tidak --> Z["arabText.trim()"]
  B --> C{"Object.entries(replacer).find: ayah.includes(key)"}
  C -- ketemu --> D["ayah.replace(regEx, '') dengan flag gi"]
  C -- tidak ketemu --> E["regEx undefined: teks tidak diubah"]
  D --> F["trim()"]
  E --> F
  F --> G["text.arab"]
  Z --> G
  G --> H["preBismillah tingkat surah memuat basmalah"]
  style A fill:#f59e0b,color:#000
  style B fill:#f59e0b,color:#000
  style D fill:#2d7d46,color:#fff
  style G fill:#2d7d46,color:#fff
  style H fill:#336791,color:#fff
  style E fill:#dc2626,color:#fff
%% fig: Jalur keputusan preBismillahHandler
%% desc: Hanya ayat pertama pada surah selain surah 1 yang dibersihkan, dan pembersihan gagal secara diam bila tidak ada kunci yang cocok.

⚠️ Bila tidak ada kunci yang cocok, regEx bernilai undefined dan teks dikembalikan tanpa perubahan tanpa pesan apa pun. Basmalah akan tetap muncul di text.arab ayat pertama sekaligus di preBismillah, sehingga pengulangan ini hanya bisa terdeteksi dengan memeriksa data hasilnya.

Dua ketergantungan perlu diperhatikan sebelum menjalankan ulang normalisasi ini. Berkas ../data/quran-tafsir.json yang dipakai sebagai temp tidak disertakan di repository, karena namanya masuk daftar abaikan (.gitignore:2-2). Tanpa berkas itu, pengambilan activeAyah gagal dan galat ditangkap oleh blok catch milik operate (crawler/script.js:169-179¹⁷); mekanisme pengulangan antrean surah dibahas di Crawler: Pipeline Pengambilan Data.