/** * Spaced repetition with FSRS (the algorithm Anki adopted in 2023), via ts-fsrs. * Scheduling state lives on each card row; every review is logged so it can be undone * and analysed later. */ import { createEmptyCard, fsrs, Rating, State, type Card as FsrsCard, type Grade } from 'ts-fsrs'; import type { DB } from '../db.ts'; import { badRequest, notFound } from '../http.ts'; import type { AppSettings } from '../settings.ts'; import { DAY_MS, now as clock, parseJson, startOfDay } from '../util.ts'; import { mapCard, type CardRow } from './content.ts'; export const LEARN_AHEAD_MS = 20 * 60_000; export type RatingValue = 1 | 2 | 3 | 4; export const RATING_LABELS: Record = { 1: 'Again', 2: 'Hard', 3: 'Good', 4: 'Easy' }; const schedulers = new Map>(); function scheduler(retention: number, fuzz: boolean) { const key = `${retention}:${fuzz}`; let s = schedulers.get(key); if (!s) { s = fsrs({ request_retention: retention, enable_fuzz: fuzz, enable_short_term: true, maximum_interval: 36500 }); schedulers.set(key, s); } return s; } function toFsrs(row: CardRow, at: number): FsrsCard { if (row.state === State.New || row.due === null) return createEmptyCard(new Date(at)); return { due: new Date(row.due), stability: row.stability, difficulty: row.difficulty, scheduled_days: row.scheduled_days, learning_steps: row.learning_steps, reps: row.reps, lapses: row.lapses, state: row.state as State, last_review: row.last_review ? new Date(row.last_review) : undefined, } as FsrsCard; } export function intervalLabel(ms: number): string { if (ms < 60_000) return '<1m'; const minutes = ms / 60_000; if (minutes < 60) return `${Math.round(minutes)}m`; const hours = minutes / 60; if (hours < 24) return `${Math.round(hours)}h`; const days = hours / 24; if (days < 30.5) return `${Math.round(days)}d`; const months = days / 30.44; if (months < 12) return `${months.toFixed(months < 3 ? 1 : 0).replace(/\.0$/, '')}mo`; return `${(days / 365.25).toFixed(1).replace(/\.0$/, '')}y`; } export interface RatingPreview { rating: RatingValue; label: string; interval: string; due: number; } export function previewRatings(row: CardRow, settings: AppSettings, at: number): RatingPreview[] { // Previews never use fuzz so the labels are stable while the card is on screen. const options = scheduler(settings.desiredRetention, false).repeat(toFsrs(row, at), new Date(at)); return ([1, 2, 3, 4] as RatingValue[]).map((rating) => { const due = options[rating as Grade].card.due.getTime(); return { rating, label: RATING_LABELS[rating], interval: intervalLabel(due - at), due }; }); } export interface QueueScope { deckId?: string; classId?: string; } function scopeSql(scope: QueueScope): { where: string; params: string[] } { if (scope.deckId) return { where: 'AND c.deck_id = ?', params: [scope.deckId] }; if (scope.classId) return { where: 'AND d.class_id = ?', params: [scope.classId] }; return { where: '', params: [] }; } const BASE = `FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id WHERE c.suspended = 0 AND k.archived = 0`; export interface DueCounts { learning: number; review: number; new: number; total: number; } /** New cards still allowed today under the global daily limit. */ export function newCardsLeftToday(db: DB, settings: AppSettings, at: number): number { const since = startOfDay(at, settings.timezone); const introduced = db.get<{ n: number }>('SELECT COUNT(*) AS n FROM cards WHERE introduced_at >= ?', since)?.n ?? 0; return Math.max(0, settings.newCardsPerDay - introduced); } export function dueCounts(db: DB, scope: QueueScope, settings: AppSettings, at = clock()): DueCounts { const { where, params } = scopeSql(scope); const endOfDay = startOfDay(at, settings.timezone) + DAY_MS; const row = db.get<{ learning: number; review: number; fresh: number }>( `SELECT COALESCE(SUM(CASE WHEN c.state IN (1,3) AND c.due <= ? THEN 1 ELSE 0 END), 0) AS learning, COALESCE(SUM(CASE WHEN c.state = 2 AND c.due < ? THEN 1 ELSE 0 END), 0) AS review, COALESCE(SUM(CASE WHEN c.state = 0 THEN 1 ELSE 0 END), 0) AS fresh ${BASE} ${where}`, at + LEARN_AHEAD_MS, endOfDay, ...params, )!; const fresh = Math.min(row.fresh, newCardsLeftToday(db, settings, at)); return { learning: row.learning, review: row.review, new: fresh, total: row.learning + row.review + fresh }; } export interface QueueCard { card: ReturnType; deckTitle: string; classId: string; className: string; classColor: string; previews: RatingPreview[]; } type JoinedRow = CardRow & { deck_title: string; class_id: string; class_name: string; class_color: string }; const SELECT = `SELECT c.*, d.title AS deck_title, d.class_id AS class_id, k.name AS class_name, k.color AS class_color`; function toQueueCard(row: JoinedRow, settings: AppSettings, at: number): QueueCard { return { card: mapCard(row), deckTitle: row.deck_title, classId: row.class_id, className: row.class_name, classColor: row.class_color, previews: previewRatings(row, settings, at), }; } /** * Builds the study queue: learning cards first (they are time-critical), then reviews * due today with new cards spread evenly among them. */ export function buildQueue(db: DB, scope: QueueScope, settings: AppSettings, limit = 100, at = clock()): { cards: QueueCard[]; counts: DueCounts } { const { where, params } = scopeSql(scope); const endOfDay = startOfDay(at, settings.timezone) + DAY_MS; const learning = db.all(`${SELECT} ${BASE} ${where} AND c.state IN (1,3) AND c.due <= ? ORDER BY c.due LIMIT ?`, ...params, at + LEARN_AHEAD_MS, limit); const reviews = db.all(`${SELECT} ${BASE} ${where} AND c.state = 2 AND c.due < ? ORDER BY c.due LIMIT ?`, ...params, endOfDay, limit); const newLeft = newCardsLeftToday(db, settings, at); const fresh = newLeft > 0 ? db.all( `${SELECT} ${BASE} ${where} AND c.state = 0 ORDER BY k.sort_order, d.sort_order, d.created_at, c.sort_order, c.created_at LIMIT ?`, ...params, Math.min(newLeft, limit), ) : []; const mixed: JoinedRow[] = []; const every = fresh.length > 0 ? Math.max(1, Math.floor(reviews.length / fresh.length)) : 0; let f = 0; reviews.forEach((r, i) => { mixed.push(r); if (every > 0 && (i + 1) % every === 0 && f < fresh.length) mixed.push(fresh[f++]); }); while (f < fresh.length) mixed.push(fresh[f++]); const cards = [...learning, ...mixed].slice(0, limit).map((r) => toQueueCard(r, settings, at)); return { cards, counts: dueCounts(db, scope, settings, at) }; } const SCHEDULE_FIELDS = ['state', 'due', 'stability', 'difficulty', 'scheduled_days', 'learning_steps', 'reps', 'lapses', 'last_review', 'introduced_at'] as const; export function answerCard( db: DB, cardId: string, rating: RatingValue, settings: AppSettings, opts: { at?: number; fuzz?: boolean } = {}, ): QueueCard { const at = opts.at ?? clock(); const row = db.get(`${SELECT} FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id WHERE c.id = ?`, cardId); if (!row) throw notFound('Card'); if (![1, 2, 3, 4].includes(rating)) throw badRequest('Rating must be 1-4'); const result = scheduler(settings.desiredRetention, opts.fuzz ?? true).next(toFsrs(row, at), new Date(at), rating as Grade); const next = result.card; const prev: Record = {}; for (const f of SCHEDULE_FIELDS) prev[f] = row[f]; db.tx(() => { db.run( `UPDATE cards SET state = ?, due = ?, stability = ?, difficulty = ?, scheduled_days = ?, learning_steps = ?, reps = ?, lapses = ?, last_review = ?, introduced_at = COALESCE(introduced_at, ?) WHERE id = ?`, next.state, next.due.getTime(), next.stability, next.difficulty, next.scheduled_days, next.learning_steps, next.reps, next.lapses, at, at, cardId, ); db.run( 'INSERT INTO reviews (card_id, deck_id, class_id, rating, state_before, scheduled_days, mode, prev, reviewed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)', cardId, row.deck_id, row.class_id, rating, row.state, next.scheduled_days, 'srs', JSON.stringify(prev), at, ); }); const updated = db.get(`${SELECT} FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id WHERE c.id = ?`, cardId)!; return toQueueCard(updated, settings, at); } /** Reverts the most recent scheduled review of a card and returns it to its previous state. */ export function undoReview(db: DB, cardId: string, settings: AppSettings, at = clock()): QueueCard { const review = db.get<{ id: number; prev: string }>(`SELECT id, prev FROM reviews WHERE card_id = ? AND mode = 'srs' ORDER BY id DESC LIMIT 1`, cardId); if (!review || !review.prev) throw badRequest('Nothing to undo for this card'); const prev = parseJson>(review.prev, {}); db.tx(() => { db.run( `UPDATE cards SET state = ?, due = ?, stability = ?, difficulty = ?, scheduled_days = ?, learning_steps = ?, reps = ?, lapses = ?, last_review = ?, introduced_at = ? WHERE id = ?`, prev.state ?? 0, prev.due ?? null, prev.stability ?? 0, prev.difficulty ?? 0, prev.scheduled_days ?? 0, prev.learning_steps ?? 0, prev.reps ?? 0, prev.lapses ?? 0, prev.last_review ?? null, prev.introduced_at ?? null, cardId, ); db.run('DELETE FROM reviews WHERE id = ?', review.id); }); const row = db.get(`${SELECT} FROM cards c JOIN decks d ON d.id = c.deck_id JOIN classes k ON k.id = d.class_id WHERE c.id = ?`, cardId); if (!row) throw notFound('Card'); return toQueueCard(row, settings, at); } export function resetCards(db: DB, where: { cardId?: string; deckId?: string }): number { const sql = `UPDATE cards SET state = 0, due = NULL, stability = 0, difficulty = 0, scheduled_days = 0, learning_steps = 0, reps = 0, lapses = 0, last_review = NULL, introduced_at = NULL WHERE `; if (where.cardId) return db.run(`${sql} id = ?`, where.cardId).changes; if (where.deckId) return db.run(`${sql} deck_id = ?`, where.deckId).changes; return 0; } /** Logs a self-graded cram flip so it counts toward activity without touching the schedule. */ export function logCram(db: DB, cardId: string, known: boolean, at = clock()): void { const row = db.get<{ deck_id: string; class_id: string; state: number }>( 'SELECT c.deck_id, d.class_id, c.state FROM cards c JOIN decks d ON d.id = c.deck_id WHERE c.id = ?', cardId, ); if (!row) return; db.run( `INSERT INTO reviews (card_id, deck_id, class_id, rating, state_before, scheduled_days, mode, prev, reviewed_at) VALUES (?, ?, ?, ?, ?, 0, 'cram', '', ?)`, cardId, row.deck_id, row.class_id, known ? Rating.Good : Rating.Again, row.state, at, ); } export interface DeckStats { total: number; new: number; learning: number; young: number; mature: number; suspended: number; dueNow: number; } export function deckStats(db: DB, deckId: string, settings: AppSettings, at = clock()): DeckStats { const endOfDay = startOfDay(at, settings.timezone) + DAY_MS; const r = db.get>( `SELECT COUNT(*) AS total, COALESCE(SUM(suspended), 0) AS suspended, COALESCE(SUM(CASE WHEN suspended = 0 AND state = 0 THEN 1 ELSE 0 END), 0) AS fresh, COALESCE(SUM(CASE WHEN suspended = 0 AND state IN (1,3) THEN 1 ELSE 0 END), 0) AS learning, COALESCE(SUM(CASE WHEN suspended = 0 AND state = 2 AND scheduled_days < 21 THEN 1 ELSE 0 END), 0) AS young, COALESCE(SUM(CASE WHEN suspended = 0 AND state = 2 AND scheduled_days >= 21 THEN 1 ELSE 0 END), 0) AS mature, COALESCE(SUM(CASE WHEN suspended = 0 AND ((state IN (1,3) AND due <= ?) OR (state = 2 AND due < ?)) THEN 1 ELSE 0 END), 0) AS due_now FROM cards WHERE deck_id = ?`, at + LEARN_AHEAD_MS, endOfDay, deckId, )!; return { total: r.total, new: r.fresh, learning: r.learning, young: r.young, mature: r.mature, suspended: r.suspended, dueNow: r.due_now }; } /** Reviews coming due per day for the next `days` days (index 0 = today, including overdue). */ export function forecast(db: DB, scope: QueueScope, settings: AppSettings, days = 14, at = clock()): number[] { const { where, params } = scopeSql(scope); const start = startOfDay(at, settings.timezone); const rows = db.all<{ due: number }>(`SELECT c.due AS due ${BASE} ${where} AND c.state != 0 AND c.due < ?`, ...params, start + days * DAY_MS); const out = new Array(days).fill(0); for (const r of rows) out[Math.max(0, Math.min(days - 1, Math.floor((r.due - start) / DAY_MS)))] += 1; return out; }