V1 remains intact on main and in history. This branch replaces it with a new application: node:sqlite storage with migrations, scrypt auth and sessions, content/SRS/attempt/stats services, document extraction and chunking, a provider-neutral AI layer (OpenAI, Anthropic, Gemini, OpenAI-compatible, Ollama), the generation pipeline and the tool-using assistant. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
309 lines
13 KiB
TypeScript
309 lines
13 KiB
TypeScript
/**
|
|
* 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<RatingValue, string> = { 1: 'Again', 2: 'Hard', 3: 'Good', 4: 'Easy' };
|
|
|
|
const schedulers = new Map<string, ReturnType<typeof fsrs>>();
|
|
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<typeof mapCard>;
|
|
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<JoinedRow>(`${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<JoinedRow>(`${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<JoinedRow>(
|
|
`${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<JoinedRow>(`${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<string, unknown> = {};
|
|
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<JoinedRow>(`${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<Record<string, number | null>>(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<JoinedRow>(`${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<Record<string, number>>(
|
|
`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<number>(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;
|
|
}
|