learngraph 0.4.0 → 0.7.0

package/dist/cjs/query/index.js

@@ -2,11 +2,30 @@
 /**
  * Query and traversal engines
  *
+ * This module provides intelligent query engines for:
+ * - Zone of Proximal Development (ZPD) calculation
+ * - Learning path generation
+ * - Spaced repetition scheduling
+ *
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-// Query engines will be implemented in Phase 6
-// export { ZPDCalculator } from './zpd.js';
-// export { PathGenerator } from './path.js';
-// export { SkillQueryBuilder } from './builder.js';
+exports.SM2_CONSTANTS = exports.REVIEW_DEFAULTS = exports.calculateSM2 = exports.createSpacedRepetitionScheduler = exports.SpacedRepetitionScheduler = exports.PATH_DEFAULTS = exports.createPathGenerator = exports.PathGenerator = exports.ZPD_DEFAULTS = exports.createZPDCalculator = exports.ZPDCalculator = void 0;
+// ZPD Calculator
+var zpd_js_1 = require("./zpd.js");
+Object.defineProperty(exports, "ZPDCalculator", { enumerable: true, get: function () { return zpd_js_1.ZPDCalculator; } });
+Object.defineProperty(exports, "createZPDCalculator", { enumerable: true, get: function () { return zpd_js_1.createZPDCalculator; } });
+Object.defineProperty(exports, "ZPD_DEFAULTS", { enumerable: true, get: function () { return zpd_js_1.ZPD_DEFAULTS; } });
+// Learning Path Generator
+var path_js_1 = require("./path.js");
+Object.defineProperty(exports, "PathGenerator", { enumerable: true, get: function () { return path_js_1.PathGenerator; } });
+Object.defineProperty(exports, "createPathGenerator", { enumerable: true, get: function () { return path_js_1.createPathGenerator; } });
+Object.defineProperty(exports, "PATH_DEFAULTS", { enumerable: true, get: function () { return path_js_1.PATH_DEFAULTS; } });
+// Spaced Repetition Scheduler
+var spaced_repetition_js_1 = require("./spaced-repetition.js");
+Object.defineProperty(exports, "SpacedRepetitionScheduler", { enumerable: true, get: function () { return spaced_repetition_js_1.SpacedRepetitionScheduler; } });
+Object.defineProperty(exports, "createSpacedRepetitionScheduler", { enumerable: true, get: function () { return spaced_repetition_js_1.createSpacedRepetitionScheduler; } });
+Object.defineProperty(exports, "calculateSM2", { enumerable: true, get: function () { return spaced_repetition_js_1.calculateSM2; } });
+Object.defineProperty(exports, "REVIEW_DEFAULTS", { enumerable: true, get: function () { return spaced_repetition_js_1.REVIEW_DEFAULTS; } });
+Object.defineProperty(exports, "SM2_CONSTANTS", { enumerable: true, get: function () { return spaced_repetition_js_1.SM2_CONSTANTS; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/query/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/query/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAmBH,+CAA+C;AAC/C,4CAA4C;AAC5C,6CAA6C;AAC7C,oDAAoD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/query/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;AAmBH,iBAAiB;AACjB,mCAKkB;AAJhB,uGAAA,aAAa,OAAA;AACb,6GAAA,mBAAmB,OAAA;AACnB,sGAAA,YAAY,OAAA;AAId,0BAA0B;AAC1B,qCAKmB;AAJjB,wGAAA,aAAa,OAAA;AACb,8GAAA,mBAAmB,OAAA;AACnB,wGAAA,aAAa,OAAA;AAIf,8BAA8B;AAC9B,+DASgC;AAR9B,iIAAA,yBAAyB,OAAA;AACzB,uIAAA,+BAA+B,OAAA;AAC/B,oHAAA,YAAY,OAAA;AACZ,uHAAA,eAAe,OAAA;AACf,qHAAA,aAAa,OAAA"}

package/dist/cjs/query/path.js

@@ -0,0 +1,313 @@
+"use strict";
+/**
+ * Learning Path Generator
+ *
+ * Generates personalized learning paths from current state to target skills.
+ * Uses topological sorting and groups skills into manageable sessions.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PathGenerator = exports.PATH_DEFAULTS = void 0;
+exports.createPathGenerator = createPathGenerator;
+/**
+ * Default options for path generation
+ */
+exports.PATH_DEFAULTS = {
+    sessionMinutes: 30,
+    maxPathLength: 100,
+    includeReview: false,
+};
+/**
+ * Learning Path Generator
+ *
+ * Generates optimal learning paths to reach target skills by:
+ * 1. Finding all unmastered prerequisites
+ * 2. Topologically sorting based on dependencies
+ * 3. Grouping into sessions based on cognitive load
+ *
+ * @example
+ * ```typescript
+ * const generator = new PathGenerator(storage);
+ *
+ * const path = await generator.generatePath(
+ *   'advanced-skill',
+ *   learnerState,
+ *   { sessionMinutes: 45 }
+ * );
+ *
+ * console.log(`Path has ${path.skills.length} skills`);
+ * console.log(`Estimated time: ${path.totalMinutes} minutes`);
+ * ```
+ */
+class PathGenerator {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Generate a learning path to a target skill
+     *
+     * @param targetId - The skill to learn
+     * @param learner - Current learner state
+     * @param options - Path generation options
+     * @returns Learning path with skills grouped into sessions
+     */
+    async generatePath(targetId, learner, options = {}) {
+        const opts = { ...exports.PATH_DEFAULTS, ...options };
+        const target = await this.storage.getSkill(targetId);
+        if (!target) {
+            return null;
+        }
+        // Check if already mastered
+        const targetMastery = learner.masteryStates.get(targetId);
+        if (targetMastery && targetMastery.mastery >= target.masteryThreshold) {
+            // Already mastered - return empty path
+            return {
+                target,
+                skills: [],
+                totalMinutes: 0,
+                sessions: [],
+                checkpoints: [],
+            };
+        }
+        // Get all prerequisites (transitive)
+        const allPrereqs = await this.getTransitivePrerequisites(targetId);
+        // Filter to unmastered skills
+        const skillsToLearn = await this.filterUnmastered([...allPrereqs, target], learner, opts.includeReview);
+        // Topologically sort
+        const sorted = await this.topologicalSort(skillsToLearn);
+        // Apply max length limit
+        const limited = opts.maxPathLength
+            ? sorted.slice(0, opts.maxPathLength)
+            : sorted;
+        // Calculate total time
+        const totalMinutes = limited.reduce((sum, skill) => sum + skill.estimatedMinutes, 0);
+        // Group into sessions
+        const sessions = this.groupIntoSessions(limited, opts.sessionMinutes);
+        // Identify checkpoints (threshold concepts)
+        const checkpoints = limited.filter((skill) => skill.isThresholdConcept);
+        return {
+            target,
+            skills: limited,
+            totalMinutes,
+            sessions,
+            checkpoints,
+        };
+    }
+    /**
+     * Generate paths to multiple target skills
+     *
+     * @param targetIds - Skills to learn
+     * @param learner - Current learner state
+     * @param options - Path generation options
+     * @returns Array of learning paths
+     */
+    async generatePaths(targetIds, learner, options = {}) {
+        const paths = [];
+        for (const targetId of targetIds) {
+            const path = await this.generatePath(targetId, learner, options);
+            if (path) {
+                paths.push(path);
+            }
+        }
+        return paths;
+    }
+    /**
+     * Get a merged learning path for multiple targets
+     * Combines all required skills and eliminates duplicates
+     */
+    async generateMergedPath(targetIds, learner, options = {}) {
+        const opts = { ...exports.PATH_DEFAULTS, ...options };
+        // Get all target skills
+        const targets = [];
+        for (const id of targetIds) {
+            const skill = await this.storage.getSkill(id);
+            if (skill) {
+                targets.push(skill);
+            }
+        }
+        if (targets.length === 0) {
+            return null;
+        }
+        // Collect all unmastered prerequisites from all targets
+        const allSkillsSet = new Set();
+        const allSkills = [];
+        for (const target of targets) {
+            const prereqs = await this.getTransitivePrerequisites(target.id);
+            const allForTarget = [...prereqs, target];
+            for (const skill of allForTarget) {
+                if (!allSkillsSet.has(skill.id)) {
+                    allSkillsSet.add(skill.id);
+                    allSkills.push(skill);
+                }
+            }
+        }
+        // Filter to unmastered
+        const skillsToLearn = await this.filterUnmastered(allSkills, learner, opts.includeReview);
+        // Topologically sort
+        const sorted = await this.topologicalSort(skillsToLearn);
+        // Apply max length
+        const limited = opts.maxPathLength
+            ? sorted.slice(0, opts.maxPathLength)
+            : sorted;
+        const totalMinutes = limited.reduce((sum, skill) => sum + skill.estimatedMinutes, 0);
+        const sessions = this.groupIntoSessions(limited, opts.sessionMinutes);
+        const checkpoints = limited.filter((skill) => skill.isThresholdConcept);
+        // Use first target as the primary target
+        return {
+            target: targets[0],
+            skills: limited,
+            totalMinutes,
+            sessions,
+            checkpoints,
+        };
+    }
+    /**
+     * Get all transitive prerequisites of a skill
+     */
+    async getTransitivePrerequisites(skillId) {
+        const visited = new Set();
+        const result = [];
+        const visit = async (id) => {
+            if (visited.has(id)) {
+                return;
+            }
+            visited.add(id);
+            const prereqs = await this.storage.getPrerequisitesOf(id);
+            for (const prereq of prereqs) {
+                await visit(prereq.id);
+                if (!result.some((s) => s.id === prereq.id)) {
+                    result.push(prereq);
+                }
+            }
+        };
+        await visit(skillId);
+        return result;
+    }
+    /**
+     * Filter skills to only unmastered ones
+     */
+    async filterUnmastered(skills, learner, includeReview) {
+        return skills.filter((skill) => {
+            const mastery = learner.masteryStates.get(skill.id);
+            const level = mastery?.mastery ?? 0;
+            if (includeReview) {
+                // Include if below 100% mastery
+                return level < 1.0;
+            }
+            // Include if below mastery threshold
+            return level < skill.masteryThreshold;
+        });
+    }
+    /**
+     * Topologically sort skills based on prerequisites
+     * Skills with no unmastered prerequisites come first
+     */
+    async topologicalSort(skills) {
+        const skillMap = new Map(skills.map((s) => [s.id, s]));
+        const result = [];
+        const visited = new Set();
+        const visiting = new Set(); // For cycle detection
+        const visit = async (skill) => {
+            if (visited.has(skill.id)) {
+                return;
+            }
+            if (visiting.has(skill.id)) {
+                // Cycle detected - skip to avoid infinite loop
+                return;
+            }
+            visiting.add(skill.id);
+            // Visit prerequisites first (only those in our skill set)
+            const prereqs = await this.storage.getPrerequisitesOf(skill.id);
+            for (const prereq of prereqs) {
+                const prereqSkill = skillMap.get(prereq.id);
+                if (prereqSkill && !visited.has(prereq.id)) {
+                    await visit(prereqSkill);
+                }
+            }
+            visiting.delete(skill.id);
+            visited.add(skill.id);
+            result.push(skill);
+        };
+        // Visit all skills
+        for (const skill of skills) {
+            if (!visited.has(skill.id)) {
+                await visit(skill);
+            }
+        }
+        return result;
+    }
+    /**
+     * Group skills into learning sessions based on target duration
+     */
+    groupIntoSessions(skills, targetMinutes) {
+        const sessions = [];
+        let currentSession = [];
+        let currentDuration = 0;
+        for (const skill of skills) {
+            // Start new session if current would exceed target
+            if (currentDuration + skill.estimatedMinutes > targetMinutes &&
+                currentSession.length > 0) {
+                sessions.push(this.createSession(sessions.length + 1, currentSession));
+                currentSession = [];
+                currentDuration = 0;
+            }
+            currentSession.push(skill);
+            currentDuration += skill.estimatedMinutes;
+        }
+        // Add final session if not empty
+        if (currentSession.length > 0) {
+            sessions.push(this.createSession(sessions.length + 1, currentSession));
+        }
+        return sessions;
+    }
+    /**
+     * Create a learning session from a group of skills
+     */
+    createSession(sessionNumber, skills) {
+        const durationMinutes = skills.reduce((sum, s) => sum + s.estimatedMinutes, 0);
+        // Determine focus from most common tag or domain
+        const focus = this.determineFocus(skills);
+        // Build session object, only include focus if defined
+        const session = {
+            sessionNumber,
+            skills,
+            durationMinutes,
+        };
+        if (focus !== undefined) {
+            session.focus = focus;
+        }
+        return session;
+    }
+    /**
+     * Determine the focus/theme of a session
+     */
+    determineFocus(skills) {
+        // Count tag occurrences
+        const tagCounts = new Map();
+        for (const skill of skills) {
+            for (const tag of skill.tags) {
+                tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+            }
+        }
+        // Find most common tag
+        let maxCount = 0;
+        let focus;
+        for (const [tag, count] of tagCounts) {
+            if (count > maxCount) {
+                maxCount = count;
+                focus = tag;
+            }
+        }
+        return focus;
+    }
+}
+exports.PathGenerator = PathGenerator;
+/**
+ * Create a path generator
+ */
+function createPathGenerator(storage) {
+    return new PathGenerator(storage);
+}
+//# sourceMappingURL=path.js.map

package/dist/cjs/query/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../../src/query/path.ts"],"names":[],"mappings":"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"}

package/dist/cjs/query/spaced-repetition.js

@@ -0,0 +1,298 @@
+"use strict";
+/**
+ * Spaced Repetition Scheduler (SM-2 Algorithm)
+ *
+ * Implements the SuperMemo SM-2 algorithm for optimal review scheduling.
+ * Schedules reviews at increasing intervals based on performance.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpacedRepetitionScheduler = exports.SM2_CONSTANTS = exports.REVIEW_DEFAULTS = void 0;
+exports.createSpacedRepetitionScheduler = createSpacedRepetitionScheduler;
+exports.calculateSM2 = calculateSM2;
+/**
+ * Default options for review scheduling
+ */
+exports.REVIEW_DEFAULTS = {
+    includeUpcoming: true,
+    upcomingDays: 7,
+    maxReviews: 50,
+};
+/**
+ * SM-2 algorithm constants
+ */
+exports.SM2_CONSTANTS = {
+    /** Minimum easiness factor */
+    MIN_EASINESS: 1.3,
+    /** Default easiness factor */
+    DEFAULT_EASINESS: 2.5,
+    /** Maximum easiness factor */
+    MAX_EASINESS: 3.5,
+    /** Initial interval (days) after first review */
+    INITIAL_INTERVAL: 1,
+    /** Second interval (days) after second review */
+    SECOND_INTERVAL: 6,
+};
+/**
+ * Spaced Repetition Scheduler
+ *
+ * Uses the SM-2 algorithm to schedule optimal review times.
+ * The algorithm adjusts intervals based on recall quality:
+ * - Quality 5: Perfect response
+ * - Quality 4: Correct with hesitation
+ * - Quality 3: Correct with difficulty
+ * - Quality 2: Incorrect but easily recalled
+ * - Quality 1: Incorrect, remembered when shown
+ * - Quality 0: Complete blackout
+ *
+ * @example
+ * ```typescript
+ * const scheduler = new SpacedRepetitionScheduler(storage);
+ *
+ * // Get review schedule
+ * const schedule = await scheduler.getSchedule(learnerState);
+ * console.log(`${schedule.dueNow.length} reviews due now`);
+ *
+ * // Update after a review
+ * const result = scheduler.calculateNextReview(masteryState, 4); // quality 4
+ * console.log(`Next review in ${result.intervalDays} days`);
+ * ```
+ */
+class SpacedRepetitionScheduler {
+    storage;
+    constructor(storage) {
+        this.storage = storage;
+    }
+    /**
+     * Get the review schedule for a learner
+     *
+     * @param learner - Current learner state
+     * @param options - Schedule options
+     * @returns Review schedule with due and upcoming items
+     */
+    async getSchedule(learner, options = {}) {
+        const opts = { ...exports.REVIEW_DEFAULTS, ...options };
+        const now = new Date();
+        const upcomingCutoff = new Date(now.getTime() + opts.upcomingDays * 24 * 60 * 60 * 1000);
+        // Get all skills that have been practiced
+        const allSkills = await this.storage.findSkills({});
+        const dueNow = [];
+        const upcoming = [];
+        for (const skill of allSkills) {
+            const mastery = learner.masteryStates.get(skill.id);
+            if (!mastery) {
+                continue; // Never practiced
+            }
+            // Only schedule reviews for skills with some mastery
+            if (mastery.mastery < 0.1) {
+                continue;
+            }
+            const nextReview = this.calculateNextReviewDate(mastery);
+            const priority = this.calculatePriority(mastery, nextReview, now);
+            const reviewItem = {
+                skill,
+                state: {
+                    mastery: mastery.mastery,
+                    lastAttempt: mastery.lastAttempt,
+                    streak: mastery.streak,
+                },
+                nextReview,
+                priority,
+            };
+            if (nextReview <= now) {
+                dueNow.push(reviewItem);
+            }
+            else if (opts.includeUpcoming && nextReview <= upcomingCutoff) {
+                upcoming.push(reviewItem);
+            }
+        }
+        // Sort by priority (highest first)
+        dueNow.sort((a, b) => b.priority - a.priority);
+        upcoming.sort((a, b) => a.nextReview.getTime() - b.nextReview.getTime());
+        // Apply limits
+        const limitedDue = opts.maxReviews ? dueNow.slice(0, opts.maxReviews) : dueNow;
+        const remainingLimit = opts.maxReviews
+            ? Math.max(0, opts.maxReviews - limitedDue.length)
+            : undefined;
+        const limitedUpcoming = remainingLimit !== undefined
+            ? upcoming.slice(0, remainingLimit)
+            : upcoming;
+        // Calculate total review time
+        const totalReviewMinutes = [...limitedDue, ...limitedUpcoming].reduce((sum, item) => sum + Math.ceil(item.skill.estimatedMinutes * 0.3), // Reviews are ~30% of initial learning time
+        0);
+        return {
+            dueNow: limitedDue,
+            upcoming: limitedUpcoming,
+            totalReviewMinutes,
+        };
+    }
+    /**
+     * Calculate the next review interval using SM-2 algorithm
+     *
+     * @param currentState - Current mastery state
+     * @param quality - Review quality (0-5)
+     * @returns Updated SM-2 parameters
+     */
+    calculateNextReview(currentState, quality) {
+        const now = new Date();
+        // Get current SM-2 state
+        let easiness = currentState.easinessFactor ?? exports.SM2_CONSTANTS.DEFAULT_EASINESS;
+        let repetitions = currentState.streak;
+        let interval;
+        // Quality must be >= 3 for successful recall
+        if (quality >= 3) {
+            // Successful recall
+            if (repetitions === 0) {
+                interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+            }
+            else if (repetitions === 1) {
+                interval = exports.SM2_CONSTANTS.SECOND_INTERVAL;
+            }
+            else {
+                // Get previous interval from last attempt
+                const lastInterval = this.estimatePreviousInterval(currentState);
+                interval = Math.round(lastInterval * easiness);
+            }
+            repetitions++;
+        }
+        else {
+            // Failed recall - reset to beginning
+            repetitions = 0;
+            interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        }
+        // Update easiness factor
+        // EF = EF + (0.1 - (5 - q) * (0.08 + (5 - q) * 0.02))
+        const easinessChange = 0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02);
+        easiness = Math.max(exports.SM2_CONSTANTS.MIN_EASINESS, Math.min(exports.SM2_CONSTANTS.MAX_EASINESS, easiness + easinessChange));
+        // Calculate next review date
+        const nextReview = new Date(now.getTime() + interval * 24 * 60 * 60 * 1000);
+        return {
+            easinessFactor: easiness,
+            intervalDays: interval,
+            nextReview,
+            repetitions,
+        };
+    }
+    /**
+     * Convert review quality to mastery update
+     *
+     * @param quality - Review quality (0-5)
+     * @returns Mastery level adjustment
+     */
+    qualityToMasteryAdjustment(quality) {
+        // Map quality to mastery change
+        switch (quality) {
+            case 5: return 0.1; // Perfect - increase mastery
+            case 4: return 0.05; // Correct with hesitation
+            case 3: return 0.0; // Correct with difficulty - maintain
+            case 2: return -0.1; // Incorrect but close
+            case 1: return -0.2; // Poor recall
+            case 0: return -0.3; // Complete failure
+        }
+    }
+    /**
+     * Calculate next review date based on current mastery state
+     */
+    calculateNextReviewDate(mastery) {
+        if (!mastery.lastAttempt) {
+            return new Date(); // Due immediately
+        }
+        const easiness = mastery.easinessFactor ?? exports.SM2_CONSTANTS.DEFAULT_EASINESS;
+        const streak = mastery.streak;
+        // Calculate interval based on streak
+        let interval;
+        if (streak === 0) {
+            interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        }
+        else if (streak === 1) {
+            interval = exports.SM2_CONSTANTS.SECOND_INTERVAL;
+        }
+        else {
+            // Exponential growth based on streak and easiness
+            interval = Math.round(exports.SM2_CONSTANTS.SECOND_INTERVAL * Math.pow(easiness, streak - 1));
+        }
+        // Clamp to reasonable bounds (1 day to 1 year)
+        interval = Math.max(1, Math.min(365, interval));
+        return new Date(mastery.lastAttempt.getTime() + interval * 24 * 60 * 60 * 1000);
+    }
+    /**
+     * Estimate previous interval from mastery state
+     */
+    estimatePreviousInterval(mastery) {
+        const streak = mastery.streak;
+        const easiness = mastery.easinessFactor ?? exports.SM2_CONSTANTS.DEFAULT_EASINESS;
+        if (streak <= 1) {
+            return exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        }
+        else if (streak === 2) {
+            return exports.SM2_CONSTANTS.SECOND_INTERVAL;
+        }
+        else {
+            return Math.round(exports.SM2_CONSTANTS.SECOND_INTERVAL * Math.pow(easiness, streak - 2));
+        }
+    }
+    /**
+     * Calculate review priority
+     * Higher priority = more urgent to review
+     */
+    calculatePriority(mastery, nextReview, now) {
+        // Base priority on how overdue the review is
+        const overdueDays = (now.getTime() - nextReview.getTime()) / (24 * 60 * 60 * 1000);
+        // Higher mastery items get slightly lower priority (we want to maintain them)
+        const masteryFactor = 1 - mastery.mastery * 0.3;
+        // Combine factors
+        // Overdue items get positive priority, upcoming items get negative
+        return overdueDays * masteryFactor * 10;
+    }
+}
+exports.SpacedRepetitionScheduler = SpacedRepetitionScheduler;
+/**
+ * Create a spaced repetition scheduler
+ */
+function createSpacedRepetitionScheduler(storage) {
+    return new SpacedRepetitionScheduler(storage);
+}
+/**
+ * Standalone SM-2 calculation (for use without storage)
+ *
+ * @param quality - Review quality (0-5)
+ * @param previousEasiness - Previous easiness factor
+ * @param previousInterval - Previous interval in days
+ * @param repetitions - Number of previous successful repetitions
+ * @returns Updated SM-2 parameters
+ */
+function calculateSM2(quality, previousEasiness = exports.SM2_CONSTANTS.DEFAULT_EASINESS, previousInterval = 0, repetitions = 0) {
+    const now = new Date();
+    let easiness = previousEasiness;
+    let interval;
+    let newRepetitions = repetitions;
+    if (quality >= 3) {
+        // Successful recall
+        if (newRepetitions === 0) {
+            interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        }
+        else if (newRepetitions === 1) {
+            interval = exports.SM2_CONSTANTS.SECOND_INTERVAL;
+        }
+        else {
+            interval = Math.round(previousInterval * easiness);
+        }
+        newRepetitions++;
+    }
+    else {
+        // Failed - reset
+        interval = exports.SM2_CONSTANTS.INITIAL_INTERVAL;
+        newRepetitions = 0;
+    }
+    // Update easiness
+    const easinessChange = 0.1 - (5 - quality) * (0.08 + (5 - quality) * 0.02);
+    easiness = Math.max(exports.SM2_CONSTANTS.MIN_EASINESS, Math.min(exports.SM2_CONSTANTS.MAX_EASINESS, easiness + easinessChange));
+    return {
+        easinessFactor: easiness,
+        intervalDays: interval,
+        nextReview: new Date(now.getTime() + interval * 24 * 60 * 60 * 1000),
+        repetitions: newRepetitions,
+    };
+}
+//# sourceMappingURL=spaced-repetition.js.map