Model Data `quran.json` dan `juz.json`

data/quran.json dan data/juz.json adalah sumber seluruh materi API. Berkas pertama menyimpan array surah yang bersarang array ayat; berkas kedua hanya menyimpan 30 entri batas rentang juz. Keduanya dimuat utuh saat modul di-require, jadi schema di memori sama dengan schema di berkas (api/handlers/surah.js:1¹, api/lib/juz.js:1-2²).

Urutan elemen data pada quran.json mengikuti nomor surah. Handler membacanya dengan quran[surah - 1], sehingga indeks array selalu berselisih satu dari nomor surah (api/handlers/surah.js:19-21³).

Kerangka Berkas

quran.json dibangun crawler dengan JSON.stringify({ ... }, null, 2), lalu setiap %u diganti \u (crawler/script.js:196-203⁶). Karena itu seluruh teks Arab tersimpan sebagai escape sequence, bukan huruf Arab mentah. Kunci audioEdition hanya ada di quran.json dan bernilai "Syekh. Mishary Rashid Al-Afasy" (data/quran.json:1-5⁴).

Objek Surah

sequence bukan turunan dari number. Surah 114 punya number 114 tetapi sequence 21, sedangkan surah 9 punya sequence 113 (data/quran.json:254369-254391⁷, data/quran.json:49756-49780⁸). Jangan memakai sequence sebagai indeks array surah.

Objek Ayat

Setiap ayat membawa meta posisi mushafnya sendiri, termasuk meta.juz. Label juz per ayat karena itu sudah tersedia tanpa membaca juz.json; perhitungan yang memakai batas rentang dibahas di Komputasi Rentang Juz.

Nilai tertinggi yang benar-benar muncul pada ayat terakhir: inQuran 6236, juz 30, page 604, ruku 556, hizbQuarter 240, dan inSurah 6 karena ayat itu berada di surah 114 (data/quran.json:254612-254655⁹).

Satu asimetri kecil: name.transliteration punya kunci en dan id, sedangkan text.transliteration hanya punya en (data/quran.json:6-21¹⁰, data/quran.json:48-70¹¹).

Blok yang Dipakai Ulang

tafsir.id muncul dalam dua bentuk berbeda:

preBismillah adalah blok tanpa number, meta, dan tafsir: isinya hanya text, translation, dan audio (data/quran.json:338-356¹³). Nilainya null pada surah 1 dan surah 9, lalu berisi objek pada surah lain seperti surah 114 (data/quran.json:22-30¹², data/quran.json:49756-49780⁸, data/quran.json:254392-254408¹⁴).

⚠️ preBismillah.audio menyalin audio ayat 1. primary selalu berakhir .../ayah/1 dan secondary selalu menunjuk .../ar.alafasy/1.mp3, pada surah mana pun (data/quran.json:338-356¹³, data/quran.json:254392-254408¹⁴). Jangan memakai URL itu untuk mengidentifikasi surah, dan jangan deduplikasi audio berdasarkan URL tersebut.

Handler menyusun ulang blok yang sama menjadi bentuk response:

graph LR
    V["satu ayat di verses[i]"] -->|"spread"| R["data ayah pada response"]
    S["objek surah tanpa verses"] -->|"field surah"| R
    A["semua 114 surah"] -->|"delete verses dan preBismillah"| G["data daftar surah"]
    style V fill:#8b5cf6,color:#fff
    style S fill:#8b5cf6,color:#fff
    style A fill:#336791,color:#fff
    style R fill:#2d7d46,color:#fff
    style G fill:#2d7d46,color:#fff
%% fig: Tiga rupa data dari satu sumber
%% desc: Ayat utuh digabung dengan objek surah tanpa verses untuk response ayah, sedangkan daftar surah membuang verses dan preBismillah.

Objek surah pada response ayah dibentuk dari salinan yang sudah dibuang verses-nya, lalu digabung sebagai field surah di samping field ayat (api/handlers/surah.js:49-61¹⁵). Daftar surah membuang dua field sekaligus, yaitu verses dan preBismillah (api/handlers/surah.js:5-9¹⁶). Bentuk amplop response-nya dibahas di Kontrak Response dan Penanganan Error.

Tabel Batas Juz

start.index dan end.index adalah nomor surah, bukan indeks array; verse adalah nomor ayat di dalam surah tersebut. api/lib/juz.js:9-12¹⁹ menurunkan keempat nilai itu menjadi indeks array dengan mengurangi satu.

Satu entri juz dapat seluruhnya berada di dalam satu surah, seperti juz 2 yang mulai dan berakhir di surah 2. Konversi batas akhir menjadi batas eksklusif untuk slice dibahas di Komputasi Rentang Juz.

Relasi Surah, Ayat, dan Juz

erDiagram
    QURAN_DATA ||--|{ SURAH : "data[]"
    SURAH ||--|{ AYAH : "verses[]"
    SURAH |o--o| PRE_BISMILLAH : "preBismillah"
    JUZ_DATA ||--|{ JUZ : "data[]"
    JUZ ||..o{ SURAH : "start.index dan end.index"
    SURAH {
        int number
        int sequence
        int numberOfVerses
        object name
        object revelation
        string tafsir
    }
    AYAH {
        int inQuran
        int inSurah
        object meta
        object text
        object translation
        object audio
        object tafsir
    }
    PRE_BISMILLAH {
        object text
        object translation
        object audio
    }
    JUZ {
        int index
        object start
        object end
    }
    style QURAN_DATA fill:#336791,color:#fff
    style JUZ_DATA fill:#336791,color:#fff
    style JUZ fill:#f59e0b,color:#000
    style PRE_BISMILLAH fill:#8b5cf6,color:#fff
%% fig: Relasi surah, ayat, dan batas juz
%% desc: Satu surah memuat banyak ayat dan satu blok preBismillah opsional, sedangkan setiap entri juz hanya menunjuk koordinat surah dan ayat.

data pada kedua berkas adalah array, verses hanya ada di dalam surah, dan preBismillah bersifat opsional (data/quran.json:6-21¹⁰, data/quran.json:31-47²⁰). Entri juz tidak menyimpan ayat sama sekali; ia hanya menunjuk pasangan index dan verse (data/juz.json:16-26¹⁷).

Contoh di dokumentasi ini memakai surah 1, 2, 9, dan 114 beserta juz 1, 2, dan 30.