MakeenCore

Deterministic TypeScript scheduling engine for Quran memorization (Hifz) and review tracking.

MakeenCore generates day-by-day study plans that balance new memorization, minor review (recent material), and major review (full-cycle review). Designed as a standalone library for integration into backend systems (NestJS, Express, etc.).

Quick Start

Installation

npm install @zakhm_sa/makeen-core

Minimal Example

import { MakeenEngine } from '@zakhm_sa/makeen-core';

const result = MakeenEngine.generatePlan({
    name: "30-Day Hifz",
    direction: "FORWARD",
    daysPerWeek: 5,
    tracks: [{
        type: "HIFZ",
        priority: 1,
        amountUnit: "LINES",
        amountValue: 10,
        start: { surah: 1, ayah: 1 }
    }],
    startDate: "2026-04-01"
});

if (result.success) {
    console.log(`Plan: ${result.data.totalDays} days`);
    console.log(result.data.plan); // Array of daily events
}

Builder Pattern (Advanced)

import { PlanBuilder, WindowMode } from '@zakhm_sa/makeen-core';

const manager = new PlanBuilder()
    .setSchedule({
        startDate: "2026-04-01",
        daysPerWeek: 6,
        isReverse: false,
        maxAyahPerDay: 8
    })
    .planByDailyAmount({
        from: { surah: 2, ayah: 1 },
        to: { surah: 2, ayah: 286 },
        dailyLines: 12
    })
    .addMinorReview(5, WindowMode.GRADUAL)
    .stopWhenCompleted()
    .build();

const days = manager.generatePlan();

Core Capabilities

| Feature | Description | |---------|-------------| | Multi-track scheduling | Hifz (new), Minor Review (recent), Major Review (full cycle) | | Canonical Quran indexing | Directional prefix-sum calculations for any range | | Pedagogical rules | Ayah integrity, surah continuity, consolidation days | | Planning modes | By duration ("finish in X days") or by daily amount ("Y lines/day") | | Library-first design | Pure TypeScript, no dependencies, deterministic output |

Configuration

Schedule Options

.setSchedule({
    startDate: "2026-04-01",     // ISO date
    daysPerWeek: 5,              // 1-7
    isReverse: false,            // false = Al-Fatiha → An-Nas
    maxAyahPerDay: 10,           // Hard cap (5-20)
    sequentialSurahMode: true,   // Complete surah before next
    strictSequentialMode: false, // Never switch until 100% done
    consolidationDayInterval: 6, // Every Nth day = review only
    surahBoundedMinorReview: false, // Keep review in current surah
    minorReviewPagesCount: 5,   // Pages to review (15 lines = 1 page)
    includeHijri: false         // Attach an Umm al-Qura Hijri date to each day
})

| Option | Type | Default | Description | |--------|------|---------|-------------| | startDate | string | required | Plan start date (YYYY-MM-DD) | | daysPerWeek | number | required | Study days per week | | isReverse | boolean | false | Direction: true = An-Nas → Al-Fatiha | | maxAyahPerDay | number | 10 | Daily memorization cap | | sequentialSurahMode | boolean | true | Complete surah before next | | strictSequentialMode | boolean | false | Never change surah until 100% | | consolidationDayInterval | number | 6 | Review-only day interval (0=off) | | surahBoundedMinorReview | boolean | false | Minor review stays in current surah | | minorReviewPagesCount | number | — | Review amount in pages | | includeHijri | boolean | false | Attach an Umm al-Qura Hijri date to each day (display-only) |

Planning Modes

1. Plan By Duration

Provide: from, to, durationDays, daysPerWeek
Engine derives: dailyLines, limitDays

const manager = new PlanBuilder()
    .setSchedule({
        startDate: '2026-02-01',
        daysPerWeek: 5,
        isReverse: true,
        maxAyahPerDay: 5
    })
    .planByDuration({
        from: { surah: 66, ayah: 1 },
        to: { surah: 58, ayah: 8 },
        durationDays: 30
    })
    .addMinorReview(3, WindowMode.GRADUAL)
    .addMajorReview(15 * 5, { surah: 114, ayah: 1 })
    .stopWhenCompleted()
    .build();

2. Plan By Daily Amount

Provide: from, to, dailyLines, daysPerWeek
Engine derives: required study days, calendar limitDays

const manager = new PlanBuilder()
    .setSchedule({
        startDate: '2026-02-01',
        daysPerWeek: 6,
        isReverse: true,
        maxAyahPerDay: 12
    })
    .planByDailyAmount({
        from: { surah: 66, ayah: 1 },
        to: { surah: 55, ayah: 78 },
        dailyLines: 14
    })
    .addMinorReview(7, WindowMode.GRADUAL)
    .addMajorReview(15 * 10, { surah: 114, ayah: 1 })
    .stopWhenCompleted()
    .build();

Advanced Features

Major Review Horizon (sliding window)

By default the Major Review loops from a fixed origin up to the memorized "wall" and back. For long plans you often want it to stay on the most recently memorized N lines instead of always restarting from the beginning. Pass horizonLines to bound how far behind the Hifz front the review may reach — as memorization advances, the window slides forward with it.

new PlanBuilder()
    .setSchedule({ startDate: '2026-04-01', daysPerWeek: 6 })
    .addHifz(15, { surah: 1, ayah: 1 })
    // Major review never reaches further back than 150 lines (~10 pages) behind the front:
    .addMajorReview(30, { surah: 1, ayah: 1 }, undefined, { horizonLines: 150 })
    .build();

Via the DTO API, set it on the major-review track's config:

{ type: "MAJOR_REVIEW", amountValue: 30, config: { horizonLines: 150 } }

Omit horizonLines for the classic fixed-origin cycle (fully backward compatible).

Snapshot & Resume (intermittent students)

Real students pause for weeks and come back. Instead of re-simulating from the original start date, export the live track state, persist it in your own store, then resume from the real position later. The snapshot carries the full history (required for the minor-review window to stay correct).

// ...after generating some days:
const snapshot = manager.exportSnapshot();   // serializable — store it anywhere (JSON)

// Later, when the student returns — rebuild the SAME plan at the real resume date:
const resumed = new PlanBuilder()
    .setSchedule({ startDate: '2026-06-01', daysPerWeek: 6 }) // the REAL resume date
    .addHifz(15, { surah: 1, ayah: 1 })
    .addMinorReview(3)
    .build();
resumed.importSnapshot(snapshot);            // restore positions + history
const nextDays = resumed.generatePlan();     // continues from where the student stopped

Hijri Calendar (opt-in, zero-dependency)

Attach an Umm al-Qura Hijri date to every generated day — handy for Ramadan khatmah plans. It is display-only (scheduling stays Gregorian) and adds no dependencies (uses the built-in Intl).

new PlanBuilder()
    .setSchedule({ startDate: '2026-02-18', daysPerWeek: 7, includeHijri: true })
    .addHifz(15, { surah: 1, ayah: 1 })
    .build()
    .generatePlan(); // each PlanDay now has hijriDate, e.g. "١ رمضان ١٤٤٧ هـ"

Or via the DTO API, pass includeHijri: true in the request; each PlanDayDTO then carries a hijriDate field. The standalone HijriDateUtils helper is also exported (toHijri, toHijriISO).

Output

The engine returns daily plan entries with event categories:

| Event Type | Description | |------------|-------------| | MEMORIZATION | New material to memorize | | REVIEW | Scheduled review events | | CATCH_UP | Overflow/adjustment events | | BREAK | Rest/consolidation days |

if (result.success) {
    const planDays = result.data.plan;
    // Persist to your database (Prisma, etc.)
}

Documentation

| Document | Purpose | |----------|---------| | API Contracts | TypeScript integration contracts | | Planning Modes & Phases | Implementation phases and milestones | | Pedagogical Rules Guide | Rule behavior and configuration | | PRD | Product and architecture details |

Testing

npm install
npm test

Total automated tests: 63/63 (100% Passing).

Notes for Library Consumers

• Scenario launchers and Excel scripts in /src are for internal QA only
• For production: consume planDays and handle persistence in your host application
• Full technical details in the /doc folder

Built with 💜 by Zakhm

Zakhm — Empowering Islamic education through technology.

We believe great tools should be accessible to all. Use MakeenCore freely, and consider contributing back to help the community grow.

📄 Licensed under Zakhm Attribution License (ZAL) 1.0