/** * Quiz sessions. An attempt freezes its questions (and their shuffled answer order) in a * snapshot when it starts, so editing or deleting the quiz later can never corrupt a session * in progress or the review of a finished one. */ import { z } from 'zod'; import { isFullyCorrect, scoreQuestion, seededShuffle, type Option, type QuestionType, type SataScoring } from '../../shared/content.ts'; import type { DB } from '../db.ts'; import { HttpError, badRequest, notFound } from '../http.ts'; import { newId, now, parseJson } from '../util.ts'; import { getClass, getQuiz, mapQuestion, type QuestionRow } from './content.ts'; export interface SnapshotQuestion { id: string; quizId: string | null; quizTitle: string; type: QuestionType; stem: string; options: Option[]; rationale: string; topic: string; difficulty: string; } export interface AnswerState { selected: string[]; /** Practice mode: the answer has been checked and feedback shown. */ checked: boolean; at: number; } export interface AttemptSettings { shuffleQuestions: boolean; shuffleOptions: boolean; timeLimitSec: number | null; sataScoring: SataScoring; /** * Wall-clock end of a timed session (epoch ms), fixed when it starts. The clock keeps * running while the session is closed; answers after it are refused and the session is * submitted with what was saved. Sessions from before this field use the active clock. */ deadlineAt?: number | null; } /** Saves sent a few seconds after the deadline (network delay, the final autosave) still count. */ export const DEADLINE_GRACE_MS = 5_000; const DEFAULT_SETTINGS: AttemptSettings = { shuffleQuestions: true, shuffleOptions: true, timeLimitSec: null, sataScoring: 'partial' }; interface AttemptRow { id: string; quiz_id: string | null; class_id: string | null; title: string; mode: 'practice' | 'exam'; kind: string; status: 'active' | 'completed'; settings: string; snapshot: string; answers: string; flags: string; current_index: number; elapsed_sec: number; question_count: number; score: number | null; max_score: number | null; started_at: number; updated_at: number; completed_at: number | null; } export const attemptCreateSchema = z.object({ mode: z.enum(['practice', 'exam']).default('practice'), source: z.discriminatedUnion('type', [ z.object({ type: z.literal('quiz'), quizId: z.string() }), /** Questions missed in one finished attempt. */ z.object({ type: z.literal('retake'), attemptId: z.string() }), /** Questions answered wrong most often, across a class or everything. */ z.object({ type: z.literal('missed'), classId: z.string().optional(), quizId: z.string().optional() }), /** Every question on the given topics within a class. */ z.object({ type: z.literal('topics'), classId: z.string(), topics: z.array(z.string()).min(1).max(50) }), z.object({ type: z.literal('questions'), questionIds: z.array(z.string()).min(1).max(1000), title: z.string().max(200).optional() }), ]), shuffleQuestions: z.boolean().default(true), shuffleOptions: z.boolean().default(true), count: z.number().int().min(1).max(1000).optional(), timeLimitMin: z.number().min(1).max(600).nullish(), }); export type AttemptCreate = z.input; const PINNED_OPTION = /^(all|none|both|neither)\b.*\b(above|these|options|answers)\b|^(a|b|c|d)\s*(and|&)\s*(a|b|c|d)\b/i; /** Shuffles options but keeps "All of the above"-style choices at the end. */ function shuffleOptions(options: Option[], seed: number): Option[] { const pinned = options.filter((o) => PINNED_OPTION.test(o.text.trim())); const free = options.filter((o) => !PINNED_OPTION.test(o.text.trim())); return [...seededShuffle(free, seed), ...pinned]; } function loadQuestionRows(db: DB, ids: string[]): (QuestionRow & { quiz_title: string })[] { if (ids.length === 0) return []; const out: (QuestionRow & { quiz_title: string })[] = []; for (let i = 0; i < ids.length; i += 400) { const batch = ids.slice(i, i + 400); out.push( ...db.all( `SELECT q.*, z.title AS quiz_title FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE q.id IN (${batch.map(() => '?').join(',')})`, ...batch, ), ); } const order = new Map(ids.map((id, i) => [id, i])); return out.sort((a, b) => (order.get(a.id) ?? 0) - (order.get(b.id) ?? 0)); } /** Question ids ordered from most to least troublesome, using recent responses. */ export function missedQuestionIds(db: DB, scope: { classId?: string; quizId?: string }, limit = 200): string[] { const where = scope.quizId ? 'AND r.quiz_id = ?' : scope.classId ? 'AND r.class_id = ?' : ''; const params = scope.quizId ? [scope.quizId] : scope.classId ? [scope.classId] : []; const rows = db.all<{ question_id: string }>( `SELECT r.question_id, COUNT(*) AS seen, SUM(CASE WHEN r.correct = 0 THEN 1 ELSE 0 END) AS wrong, (SELECT r2.correct FROM responses r2 WHERE r2.question_id = r.question_id ORDER BY r2.answered_at DESC LIMIT 1) AS last_correct FROM responses r JOIN questions q ON q.id = r.question_id WHERE 1 = 1 ${where} GROUP BY r.question_id HAVING wrong > 0 AND (last_correct = 0 OR wrong * 2 >= seen) ORDER BY last_correct ASC, (wrong * 1.0 / seen) DESC, wrong DESC LIMIT ?`, ...params, limit, ); return rows.map((r) => r.question_id); } export function createAttempt(db: DB, input: AttemptCreate, sataScoring: SataScoring): string { const opts = attemptCreateSchema.parse(input); const src = opts.source; let quizId: string | null = null; let classId: string | null = null; let title = ''; let kind = 'full'; let rows: (QuestionRow & { quiz_title: string })[] = []; let frozen: SnapshotQuestion[] | null = null; if (src.type === 'quiz') { const quiz = getQuiz(db, src.quizId); quizId = quiz.id; classId = quiz.class_id; title = quiz.title; rows = db .all('SELECT * FROM questions WHERE quiz_id = ? ORDER BY sort_order, created_at', quiz.id) .map((r) => ({ ...r, quiz_title: quiz.title })); } else if (src.type === 'retake') { const prev = db.get('SELECT * FROM attempts WHERE id = ?', src.attemptId); if (!prev) throw notFound('Attempt'); const snap = parseJson<{ questions: SnapshotQuestion[] }>(prev.snapshot, { questions: [] }); const answers = parseJson>(prev.answers, {}); const prevSettings = parseJson(prev.settings, { shuffleQuestions: true, shuffleOptions: true, timeLimitSec: null, sataScoring }); const missed = snap.questions.filter((q) => !isFullyCorrect(scoreQuestion(q, answers[q.id]?.selected ?? [], prevSettings.sataScoring))); const current = new Map(loadQuestionRows(db, missed.map((q) => q.id)).map((r) => [r.id, r])); // Prefer the live question (it may have been corrected since); fall back to the frozen copy. frozen = missed.map((q) => { const live = current.get(q.id); if (!live) return q; const m = mapQuestion(live); return { id: m.id, quizId: m.quizId, quizTitle: live.quiz_title, type: m.type, stem: m.stem, options: m.options, rationale: m.rationale, topic: m.topic, difficulty: m.difficulty }; }); quizId = prev.quiz_id; classId = prev.class_id; title = `${prev.title.replace(/ · missed$/, '')} · missed`; kind = 'retake'; } else if (src.type === 'missed') { const ids = missedQuestionIds(db, { classId: src.classId, quizId: src.quizId }); rows = loadQuestionRows(db, ids); kind = 'missed'; if (src.quizId) { const quiz = getQuiz(db, src.quizId); quizId = quiz.id; classId = quiz.class_id; title = `${quiz.title} · missed`; } else if (src.classId) { classId = src.classId; title = `${getClass(db, src.classId).name} · missed questions`; } else { title = 'Missed questions'; } } else if (src.type === 'topics') { const cls = getClass(db, src.classId); classId = cls.id; rows = db.all( `SELECT q.*, z.title AS quiz_title FROM questions q JOIN quizzes z ON z.id = q.quiz_id WHERE z.class_id = ? AND q.topic IN (${src.topics.map(() => '?').join(',')}) ORDER BY z.sort_order, q.sort_order`, cls.id, ...src.topics, ); title = src.topics.length === 1 ? `${src.topics[0]} · practice` : `${cls.name} · ${src.topics.length} topics`; kind = 'topics'; } else { rows = loadQuestionRows(db, src.questionIds); title = src.title ?? 'Custom practice'; kind = 'custom'; const classes = new Set(rows.map((r) => db.get<{ class_id: string }>('SELECT class_id FROM quizzes WHERE id = ?', r.quiz_id)?.class_id)); if (classes.size === 1) classId = [...classes][0] ?? null; } let questions: SnapshotQuestion[] = frozen ?? rows.map((r) => { const m = mapQuestion(r); return { id: m.id, quizId: m.quizId, quizTitle: r.quiz_title, type: m.type, stem: m.stem, options: m.options, rationale: m.rationale, topic: m.topic, difficulty: m.difficulty }; }); if (questions.length === 0) { throw badRequest(src.type === 'quiz' ? 'This quiz has no questions yet' : src.type === 'missed' || src.type === 'retake' ? 'No missed questions to review' : 'No questions matched'); } const seed = (Math.random() * 2 ** 32) >>> 0; if (opts.shuffleQuestions) questions = seededShuffle(questions, seed); if (opts.count && opts.count < questions.length) questions = questions.slice(0, opts.count); if (opts.shuffleOptions) questions = questions.map((q, i) => ({ ...q, options: shuffleOptions(q.options, seed + i + 1) })); const id = newId(); const at = now(); const timeLimitSec = opts.timeLimitMin ? Math.round(opts.timeLimitMin * 60) : null; const settings: AttemptSettings = { shuffleQuestions: opts.shuffleQuestions, shuffleOptions: opts.shuffleOptions, timeLimitSec, sataScoring, deadlineAt: timeLimitSec ? at + timeLimitSec * 1000 : null, }; db.run( `INSERT INTO attempts (id, quiz_id, class_id, title, mode, kind, status, settings, snapshot, question_count, started_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?)`, id, quizId, classId, title, opts.mode, kind, JSON.stringify(settings), JSON.stringify({ questions }), questions.length, at, at, ); return id; } function loadRaw(db: DB, id: string): AttemptRow { const row = db.get('SELECT * FROM attempts WHERE id = ?', id); if (!row) throw notFound('Session'); return row; } /** Loads a session, first submitting it if its deadline has passed. */ function loadAttempt(db: DB, id: string): AttemptRow { const row = loadRaw(db, id); if (isOverdue(row)) { completeAttempt(db, row.id); return db.get('SELECT * FROM attempts WHERE id = ?', id)!; } return row; } function isOverdue(row: AttemptRow, at = now()): boolean { if (row.status !== 'active') return false; const deadline = parseJson(row.settings, DEFAULT_SETTINGS).deadlineAt; return typeof deadline === 'number' && at > deadline + DEADLINE_GRACE_MS; } /** Submits every timed session whose deadline has passed. Returns how many were submitted. */ export function expireOverdueAttempts(db: DB): number { const rows = db.all<{ id: string }>( `SELECT id FROM attempts WHERE status = 'active' AND json_extract(settings, '$.deadlineAt') IS NOT NULL AND json_extract(settings, '$.deadlineAt') < ?`, now() - DEADLINE_GRACE_MS, ); for (const r of rows) completeAttempt(db, r.id); return rows.length; } function recordResponse(db: DB, row: AttemptRow, q: SnapshotQuestion, selected: string[], sata: SataScoring, at: number): void { const score = scoreQuestion(q, selected, sata); db.run( `INSERT INTO responses (attempt_id, question_id, quiz_id, class_id, topic, score, correct, answered_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?) ON CONFLICT(attempt_id, question_id) DO UPDATE SET score = excluded.score, correct = excluded.correct, answered_at = excluded.answered_at`, row.id, q.id, q.quizId ?? row.quiz_id, row.class_id, q.topic, score, isFullyCorrect(score) ? 1 : 0, at, ); } export function mapAttempt(row: AttemptRow) { const settings = parseJson(row.settings, DEFAULT_SETTINGS); const snapshot = parseJson<{ questions: SnapshotQuestion[] }>(row.snapshot, { questions: [] }); const answers = parseJson>(row.answers, {}); const results = row.status === 'completed' ? Object.fromEntries( snapshot.questions.map((q) => { const selected = answers[q.id]?.selected ?? []; const score = scoreQuestion(q, selected, settings.sataScoring); return [q.id, { score, correct: isFullyCorrect(score), answered: selected.length > 0 }]; }), ) : null; return { id: row.id, quizId: row.quiz_id, classId: row.class_id, title: row.title, mode: row.mode, kind: row.kind, status: row.status, settings, questions: snapshot.questions, answers, flags: parseJson(row.flags, []), currentIndex: row.current_index, elapsedSec: row.elapsed_sec, score: row.score, maxScore: row.max_score, startedAt: row.started_at, updatedAt: row.updated_at, completedAt: row.completed_at, results, /** Server clock when this was produced, so clients can correct for clock skew. */ serverNow: now(), }; } export type AttemptDto = ReturnType; export const mapAttemptSummary = (row: AttemptRow) => { const answers = parseJson>(row.answers, {}); return { id: row.id, quizId: row.quiz_id, classId: row.class_id, title: row.title, mode: row.mode, kind: row.kind, status: row.status, questionCount: row.question_count, answeredCount: Object.values(answers).filter((a) => a.selected.length > 0).length, currentIndex: row.current_index, elapsedSec: row.elapsed_sec, score: row.score, maxScore: row.max_score, startedAt: row.started_at, updatedAt: row.updated_at, completedAt: row.completed_at, }; }; export type AttemptSummary = ReturnType; export function getAttempt(db: DB, id: string): AttemptDto { return mapAttempt(loadAttempt(db, id)); } export const attemptPatchSchema = z.object({ answers: z .record(z.string(), z.object({ selected: z.array(z.string().max(80)).max(12), checked: z.boolean().optional().default(false) })) .optional(), flags: z.array(z.string()).max(1000).optional(), currentIndex: z.number().int().min(0).optional(), elapsedSec: z.number().int().min(0).max(1_000_000).optional(), }); export function patchAttempt(db: DB, id: string, input: z.input): AttemptDto { const patch = attemptPatchSchema.parse(input); const overdue = isOverdue(loadRaw(db, id)); const row = loadAttempt(db, id); if (overdue) throw new HttpError(409, 'time_up', 'Time is up. The exam was submitted with the answers saved before the deadline.'); if (row.status !== 'active') throw badRequest('This session is already finished'); const snapshot = parseJson<{ questions: SnapshotQuestion[] }>(row.snapshot, { questions: [] }); const settings = parseJson(row.settings, DEFAULT_SETTINGS); const answers = parseJson>(row.answers, {}); const at = now(); db.tx(() => { if (patch.answers) { const byId = new Map(snapshot.questions.map((q) => [q.id, q])); for (const [qid, a] of Object.entries(patch.answers)) { const q = byId.get(qid); if (!q) continue; const prev = answers[qid]; // A checked practice answer is final: feedback has been shown. if (prev?.checked && row.mode === 'practice') continue; const valid = new Set(q.options.map((o) => o.id)); // Numeric questions store what was typed; choice questions store option ids. const selected = q.type === 'numeric' ? a.selected.slice(0, 1).map((s) => s.trim().slice(0, 60)).filter(Boolean) : [...new Set(a.selected.filter((s) => valid.has(s)))]; const checked = row.mode === 'practice' && a.checked && selected.length > 0; answers[qid] = { selected, checked, at }; if (checked) recordResponse(db, row, q, selected, settings.sataScoring, at); } } db.run( 'UPDATE attempts SET answers = ?, flags = ?, current_index = ?, elapsed_sec = ?, updated_at = ? WHERE id = ?', JSON.stringify(answers), patch.flags ? JSON.stringify(patch.flags) : row.flags, patch.currentIndex !== undefined ? Math.min(patch.currentIndex, Math.max(0, snapshot.questions.length - 1)) : row.current_index, patch.elapsedSec !== undefined ? Math.max(row.elapsed_sec, patch.elapsedSec) : row.elapsed_sec, at, id, ); }); return getAttempt(db, id); } /** * Finishes a session. Exams score every question (blank = wrong). Practice sessions that are * ended early are scored on the questions actually answered. */ export function completeAttempt(db: DB, id: string, elapsedSec?: number): AttemptDto { const row = loadRaw(db, id); if (row.status === 'completed') return mapAttempt(row); const snapshot = parseJson<{ questions: SnapshotQuestion[] }>(row.snapshot, { questions: [] }); const settings = parseJson(row.settings, DEFAULT_SETTINGS); const answers = parseJson>(row.answers, {}); const at = now(); let elapsed = elapsedSec !== undefined ? Math.max(row.elapsed_sec, elapsedSec) : row.elapsed_sec; if (settings.deadlineAt && settings.timeLimitSec) { // Timed sessions run on the wall clock: time used is time since the start, capped at the limit. elapsed = Math.min(settings.timeLimitSec, Math.max(0, Math.round((at - row.started_at) / 1000))); } let score = 0; let max = 0; db.tx(() => { for (const q of snapshot.questions) { const selected = answers[q.id]?.selected ?? []; const answered = selected.length > 0; if (row.mode === 'practice' && !answered) continue; max += 1; score += scoreQuestion(q, selected, settings.sataScoring); const already = row.mode === 'practice' && answers[q.id]?.checked; if (!already) recordResponse(db, row, q, selected, settings.sataScoring, answers[q.id]?.at ?? at); } db.run( `UPDATE attempts SET status = 'completed', score = ?, max_score = ?, completed_at = ?, updated_at = ?, elapsed_sec = ? WHERE id = ?`, score, max, at, at, elapsed, id, ); }); return getAttempt(db, id); } export function deleteAttempt(db: DB, id: string): void { const row = loadAttempt(db, id); db.run('DELETE FROM attempts WHERE id = ?', row.id); } export function listAttempts(db: DB, filter: { status?: 'active' | 'completed'; quizId?: string; classId?: string; limit?: number }): AttemptSummary[] { const where: string[] = []; const params: (string | number)[] = []; if (filter.status) { where.push('status = ?'); params.push(filter.status); } if (filter.quizId) { where.push('quiz_id = ?'); params.push(filter.quizId); } if (filter.classId) { where.push('class_id = ?'); params.push(filter.classId); } const rows = db.all( `SELECT * FROM attempts ${where.length ? `WHERE ${where.join(' AND ')}` : ''} ORDER BY COALESCE(completed_at, updated_at) DESC LIMIT ?`, ...params, Math.min(filter.limit ?? 50, 500), ); return rows.map(mapAttemptSummary); }