domma-cms 1.8.45 → 1.9.0

package/plugins/quiz/lib/engine.js

@@ -1,115 +0,0 @@
-/**
- * Quiz - one play moving forward, by the server's clock. PURE: each function
- * takes the quiz, the play and `now`, changes the play in place and says
- * whether it changed (the route then saves it).
- *
- *   catchUp(quiz, play, now)            time that has run out while nobody asked: a question
- *                                       past its limit is marked as not answered; past the
- *                                       quiz's limit, the play ends
- *   serve(quiz, play, now)              the current question is now in front of the player
- *   answer(quiz, play, qid, given, now) one answer, marked; the play moves on (or ends)
- *   view(quiz, play, now)               what the player may know of their play now
- *
- * @module quiz/lib/engine
- */
-
-import {GRACE_MS, leftOf, overdue} from '../../_lib/games/timing.js';
-import {mark, publicQuestion, questionLimitMs, rightText} from './quiz.js';
-
-const questionOf = (quiz, play) => {
-    const slot = play.state.order[play.state.index];
-    return slot ? quiz.questions.find(q => q.id === slot.q) || null : null;
-};
-
-const scoreOf = (play) => play.state.answers.reduce((s, a) => s + (a.points || 0), 0);
-
-/** Ends the play. Out of time: the time counted is the limit itself, never more. */
-export function end(quiz, play, now, {timeUp = false} = {}) {
-    const limit = (quiz.timeLimit || 0) * 1000;
-    play.status = 'finished';
-    play.finishedAt = new Date(now).toISOString();
-    play.score = scoreOf(play);
-    const spent = Math.max(0, now - Date.parse(play.startedAt));
-    play.timeMs = limit ? Math.min(spent, limit) : spent;
-    play.state.timeUp = timeUp;
-    return true;
-}
-
-function skip(quiz, play, now, why) {
-    const q = questionOf(quiz, play);
-    play.state.answers.push({q: q?.id || '', given: null, correct: false, points: 0, late: true, why, at: new Date(now).toISOString()});
-    play.state.index += 1;
-    if (play.state.index >= play.state.order.length) end(quiz, play, now);
-}
-
-/** Bring the play up to date with the clock. */
-export function catchUp(quiz, play, now = Date.now()) {
-    if (play.status !== 'playing') return false;
-    let changed = false;
-    if (overdue(play.startedAt, (quiz.timeLimit || 0) * 1000, now)) return end(quiz, play, now, {timeUp: true});
-    // Only a question that was SHOWN can run out: one never fetched has not started its clock.
-    while (play.status === 'playing') {
-        const q = questionOf(quiz, play);
-        if (!q) { end(quiz, play, now); return true; }
-        const served = play.state.servedAt[play.state.index];
-        if (!served || !overdue(served, questionLimitMs(quiz, q), now)) break;
-        skip(quiz, play, now, 'time');
-        changed = true;
-    }
-    return changed;
-}
-
-/** The current question is on the player's screen from now - the first time only, so a reload does not reset its clock. */
-export function serve(quiz, play, now = Date.now()) {
-    if (play.status !== 'playing' || play.state.servedAt[play.state.index]) return false;
-    play.state.servedAt[play.state.index] = new Date(now).toISOString();
-    return true;
-}
-
-/**
- * An answer to question `qid`. Refused (`error`) when it is not the question
- * they are on - an old tab, a replayed request. Late is marked wrong.
- *
- * @returns {{error?: string, correct?: boolean, late?: boolean, points?: number, q?: object}}
- */
-export function answer(quiz, play, qid, given, now = Date.now()) {
-    if (play.status !== 'playing') return {error: 'This play has finished.'};
-    const q = questionOf(quiz, play);
-    if (!q || q.id !== String(qid)) return {error: 'That is not the question you are on. Carry on from where you are.', code: 'not-current'};
-    const served = play.state.servedAt[play.state.index];
-    if (!served) return {error: 'That question has not been shown yet.', code: 'not-current'};
-    const late = overdue(served, questionLimitMs(quiz, q), now) || overdue(play.startedAt, (quiz.timeLimit || 0) * 1000, now);
-    const result = late ? {correct: false, given: null} : mark(q, given);
-    const points = result.correct ? q.points : 0;
-    play.state.answers.push({q: q.id, given: result.given, correct: result.correct, points, late, at: new Date(now).toISOString()});
-    play.state.index += 1;
-    play.score = scoreOf(play);
-    if (play.state.index >= play.state.order.length) end(quiz, play, now);
-    else if (overdue(play.startedAt, (quiz.timeLimit || 0) * 1000, now)) end(quiz, play, now, {timeUp: true});
-    return {correct: result.correct, late, points, q};
-}
-
-/** Feedback straight after an answer, when the quiz shows answers as you go. */
-export function feedbackFor(quiz, q, outcome) {
-    if (quiz.showAnswers !== 'after-each' || !q) return null;
-    return {correct: outcome.correct, late: outcome.late, rightAnswer: rightText(q), explanation: q.explanation || ''};
-}
-
-/** What the player may know of their play right now. */
-export function view(quiz, play, now = Date.now()) {
-    const total = play.state.order.length;
-    const base = {
-        status: play.status, index: Math.min(play.state.index, total), total,
-        elapsedMs: Math.max(0, (play.status === 'playing' ? now : Date.parse(play.finishedAt)) - Date.parse(play.startedAt)),
-        score: play.score || 0, grace: GRACE_MS
-    };
-    if (play.status !== 'playing') return base;
-    const q = publicQuestion(quiz, play.state);
-    const served = play.state.servedAt[play.state.index];
-    return {
-        ...base,
-        question: q,
-        questionLeftMs: served ? leftOf(served, questionLimitMs(quiz, questionOf(quiz, play)), now) : null,
-        totalLeftMs: leftOf(play.startedAt, (quiz.timeLimit || 0) * 1000, now)
-    };
-}

package/plugins/quiz/lib/quiz.js

@@ -1,225 +0,0 @@
-/**
- * Quiz - the rules. PURE: no I/O, so the same decisions run in the routes and
- * the tests.
- *
- *   cleanQuiz(input)          -> {quiz, errors}     what the admin saved, made safe
- *   isOpen(quiz, now)         -> {open, reason}     can people play it now?
- *   planPlay(quiz, rand)      -> state              this player's questions, in their order
- *   publicQuestion(...)       -> what the player may see of a question (never the answer)
- *   mark(question, given)     -> {correct, given}   one answer marked
- *   answerText(question, ids) -> "Paris"            an answer in words, for feedback and review
- *
- * @module quiz/lib/quiz
- */
-
-export const KINDS = ['single', 'multiple', 'truefalse', 'text'];
-export const STATUSES = ['draft', 'open', 'closed'];
-export const SHOW_ANSWERS = ['never', 'after-each', 'end'];
-
-export const LIMITS = {questions: 200, options: 8, text: 1000, option: 200, accepted: 20, seconds: 3600, timeLimit: 4 * 3600, points: 100};
-
-const str = (v, max) => String(v ?? '').replace(/\r\n?/g, '\n').trim().slice(0, max);
-const int = (v, min, max, dflt = 0) => {
-    const n = Math.round(Number(v));
-    return Number.isFinite(n) ? Math.max(min, Math.min(max, n)) : dflt;
-};
-const iso = (v) => {
-    const t = Date.parse(String(v || ''));
-    return Number.isFinite(t) ? new Date(t).toISOString() : '';
-};
-const shortId = () => Math.random().toString(36).slice(2, 10);
-const idOf = (v) => (/^[a-z0-9_-]{1,40}$/i.test(String(v || '')) ? String(v) : shortId());
-
-/** "Capital Cities 2026" -> "capital-cities-2026". */
-export function slugify(s) {
-    return String(s || '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
-        .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60);
-}
-
-/** For comparing typed answers: case, accents, punctuation and spacing do not matter; a leading "the"/"a" neither. */
-export function foldAnswer(s) {
-    return String(s ?? '').normalize('NFKD').replace(/[̀-ͯ]/g, '').toLowerCase()
-        .replace(/&/g, ' and ').replace(/[^\p{L}\p{N}]+/gu, ' ').trim().replace(/^(the|a|an) /, '');
-}
-
-function cleanQuestion(q, n, errors) {
-    const kind = KINDS.includes(q?.kind) ? q.kind : 'single';
-    const out = {
-        id: idOf(q?.id), kind,
-        text: str(q?.text, LIMITS.text),
-        image: str(q?.image, 500),
-        points: int(q?.points ?? 1, 0, LIMITS.points, 1),
-        seconds: int(q?.seconds, 0, LIMITS.seconds),
-        explanation: str(q?.explanation, LIMITS.text),
-        options: [],
-        accepted: []
-    };
-    const where = `Question ${n}`;
-    if (!out.text) errors[`q${n}`] = `${where} has no question.`;
-    if (out.image && !/^(\/(?!\/)|https:\/\/)/.test(out.image)) errors[`q${n}`] = `${where}: the picture must be on this site (/media/...) or an https:// address.`;
-
-    if (kind === 'text') {
-        const raw = Array.isArray(q?.accepted) ? q.accepted : String(q?.accepted || '').split('\n');
-        out.accepted = [...new Set(raw.map(a => str(a, LIMITS.option)).filter(Boolean))].slice(0, LIMITS.accepted);
-        if (!out.accepted.length) errors[`q${n}`] ??= `${where} needs at least one accepted answer.`;
-        return out;
-    }
-    if (kind === 'truefalse') {
-        const isTrue = Array.isArray(q?.options) ? q.options.find(o => o?.id === 'true')?.correct !== false : true;
-        out.options = [{id: 'true', text: 'True', correct: isTrue}, {id: 'false', text: 'False', correct: !isTrue}];
-        return out;
-    }
-    const seen = new Set();
-    for (const o of (Array.isArray(q?.options) ? q.options : []).slice(0, LIMITS.options)) {
-        const text = str(o?.text, LIMITS.option);
-        if (!text) continue;
-        let id = idOf(o?.id);
-        while (seen.has(id)) id = shortId();
-        seen.add(id);
-        out.options.push({id, text, correct: o?.correct === true});
-    }
-    const right = out.options.filter(o => o.correct).length;
-    if (out.options.length < 2) errors[`q${n}`] ??= `${where} needs at least two answers to choose from.`;
-    else if (!right) errors[`q${n}`] ??= `${where}: tick the right answer.`;
-    else if (kind === 'single' && right > 1) errors[`q${n}`] ??= `${where} allows one answer but has ${right} ticked. Make it "more than one answer" or untick the others.`;
-    return out;
-}
-
-/**
- * The quiz as the admin saved it, cleaned. `errors` keyed by field (`title`, `q3`...).
- *
- * @returns {{quiz: object, errors: Object<string, string>}}
- */
-export function cleanQuiz(input = {}) {
-    const errors = {};
-    const quiz = {
-        title: str(input.title, 120),
-        slug: slugify(input.slug || input.title),
-        intro: str(input.intro, 2000),
-        status: STATUSES.includes(input.status) ? input.status : 'draft',
-        opensAt: iso(input.opensAt),
-        closesAt: iso(input.closesAt),
-        timeLimit: int(input.timeLimit, 0, LIMITS.timeLimit),
-        questionSeconds: int(input.questionSeconds, 0, LIMITS.seconds),
-        shuffleQuestions: input.shuffleQuestions === true,
-        shuffleOptions: input.shuffleOptions === true,
-        draw: int(input.draw, 0, LIMITS.questions),
-        showAnswers: SHOW_ANSWERS.includes(input.showAnswers) ? input.showAnswers : 'end',
-        leaderboard: input.leaderboard !== false,
-        leaderboardSize: int(input.leaderboardSize ?? 10, 3, 100, 10),
-        attemptsPerName: int(input.attemptsPerName, 0, 100),
-        questions: []
-    };
-    if (!quiz.title) errors.title = 'Give the quiz a title.';
-    if (!quiz.slug) errors.slug = 'Give the quiz a short name for its address (letters and numbers).';
-    if (quiz.opensAt && quiz.closesAt && quiz.closesAt <= quiz.opensAt) errors.closesAt = 'It has to close after it opens.';
-    const raw = Array.isArray(input.questions) ? input.questions.slice(0, LIMITS.questions) : [];
-    const ids = new Set();
-    raw.forEach((q, i) => {
-        const clean = cleanQuestion(q, i + 1, errors);
-        while (ids.has(clean.id)) clean.id = shortId();
-        ids.add(clean.id);
-        quiz.questions.push(clean);
-    });
-    if (quiz.status === 'open' && !quiz.questions.length) errors.questions = 'Add at least one question before opening the quiz.';
-    if (quiz.draw && quiz.draw > quiz.questions.length) quiz.draw = 0;
-    return {quiz, errors};
-}
-
-/** Can people play it right now? `reason` is said to them when not. */
-export function isOpen(quiz, now = Date.now()) {
-    if (!quiz || quiz.status === 'draft') return {open: false, reason: 'This quiz is not open yet.', state: 'draft'};
-    if (quiz.status === 'closed') return {open: false, reason: 'This quiz has closed.', state: 'closed'};
-    if (quiz.opensAt && Date.parse(quiz.opensAt) > now) return {open: false, reason: 'This quiz opens soon.', state: 'scheduled', opensAt: quiz.opensAt};
-    if (quiz.closesAt && Date.parse(quiz.closesAt) <= now) return {open: false, reason: 'This quiz has closed.', state: 'ended'};
-    if (!quiz.questions?.length) return {open: false, reason: 'This quiz has no questions yet.', state: 'empty'};
-    return {open: true, reason: '', state: 'open'};
-}
-
-/** Fisher-Yates with the caller's random (tests pass a fixed one). */
-export function shuffle(list, rand = Math.random) {
-    const a = [...list];
-    for (let i = a.length - 1; i > 0; i--) {
-        const j = Math.floor(rand() * (i + 1));
-        [a[i], a[j]] = [a[j], a[i]];
-    }
-    return a;
-}
-
-/**
- * This player's quiz: which questions (all, or `draw` of them), in what order,
- * and each one's answers in what order. Fixed at the start so a reload shows
- * the same thing.
- */
-export function planPlay(quiz, rand = Math.random) {
-    let qs = quiz.shuffleQuestions || quiz.draw ? shuffle(quiz.questions, rand) : [...quiz.questions];
-    if (quiz.draw) qs = qs.slice(0, quiz.draw);
-    return {
-        order: qs.map(q => ({q: q.id, opts: (quiz.shuffleOptions && q.kind !== 'truefalse' ? shuffle(q.options, rand) : q.options).map(o => o.id)})),
-        index: 0,
-        servedAt: [],
-        answers: []
-    };
-}
-
-export const maxScoreOf = (quiz, state) => state.order.reduce((sum, o) => sum + (quiz.questions.find(q => q.id === o.q)?.points ?? 0), 0);
-
-/** A question's time limit in ms (its own, else the quiz's default), 0 = none. */
-export const questionLimitMs = (quiz, q) => ((q?.seconds || quiz.questionSeconds || 0) * 1000);
-
-/** What the player sees: the question and its choices - never which is right. */
-export function publicQuestion(quiz, state) {
-    const slot = state.order[state.index];
-    const q = slot && quiz.questions.find(x => x.id === slot.q);
-    if (!q) return null;
-    const byId = new Map(q.options.map(o => [o.id, o]));
-    return {
-        id: q.id, kind: q.kind, text: q.text, image: q.image, points: q.points,
-        options: q.kind === 'text' ? [] : slot.opts.map(id => byId.get(id)).filter(Boolean).map(o => ({id: o.id, text: o.text})),
-        seconds: questionLimitMs(quiz, q) / 1000
-    };
-}
-
-/**
- * One answer marked. `given`: an option id (single, truefalse), a list of ids
- * (multiple), or what they typed (text). Anything else is simply wrong.
- *
- * @returns {{correct: boolean, given: string|string[]}}
- */
-export function mark(q, given) {
-    if (!q) return {correct: false, given: ''};
-    if (q.kind === 'text') {
-        const typed = String(given ?? '').slice(0, LIMITS.option);
-        const f = foldAnswer(typed);
-        return {correct: Boolean(f) && q.accepted.some(a => foldAnswer(a) === f), given: typed};
-    }
-    const ids = new Set(q.options.map(o => o.id));
-    if (q.kind === 'multiple') {
-        const picked = [...new Set((Array.isArray(given) ? given : [given]).map(String).filter(id => ids.has(id)))];
-        const right = q.options.filter(o => o.correct).map(o => o.id);
-        return {correct: picked.length === right.length && right.every(id => picked.includes(id)), given: picked};
-    }
-    const one = ids.has(String(given)) ? String(given) : '';
-    return {correct: Boolean(one) && q.options.find(o => o.id === one)?.correct === true, given: one};
-}
-
-/** An answer (option ids, or typed text) in words. */
-export function answerText(q, given) {
-    if (!q) return '';
-    if (q.kind === 'text') return String(given ?? '');
-    const list = Array.isArray(given) ? given : [given];
-    return list.map(id => q.options.find(o => o.id === id)?.text).filter(Boolean).join(', ');
-}
-
-/** The right answer in words. */
-export const rightText = (q) => (q?.kind === 'text' ? q.accepted[0] || '' : q?.options.filter(o => o.correct).map(o => o.text).join(', ') || '');
-
-/** The quiz as a list row in the admin. */
-export function summary(quiz, plays = []) {
-    const finished = plays.filter(p => p.status === 'finished');
-    return {
-        id: quiz.id, title: quiz.title, slug: quiz.slug, status: quiz.status, opensAt: quiz.opensAt, closesAt: quiz.closesAt,
-        questions: quiz.questions?.length || 0, plays: plays.length, finished: finished.length,
-        best: finished.reduce((m, p) => Math.max(m, p.score || 0), 0), updatedAt: quiz.updatedAt || ''
-    };
-}

package/plugins/quiz/lib/store.js

@@ -1,56 +0,0 @@
-/**
- * Quiz - where quizzes and plays are kept: the collections `quiz-quizzes` and
- * `quiz-plays` (made at every boot when missing; API access all off - a quiz
- * holds its answers, a play the player's name).
- *
- * @module quiz/lib/store
- */
-
-import fs from 'node:fs/promises';
-import {createCollection, createEntry, deleteEntry, getCollection, getEntry, listEntries, updateEntry} from '../../../server/services/collections.js';
-import {PlayStore} from '../../_lib/games/plays.js';
-
-export const QUIZZES = 'quiz-quizzes';
-export const PLAYS = 'quiz-plays';
-
-export const plays = new PlayStore(PLAYS, {order: 'score'});
-
-export async function ensureCollections(log = console) {
-    for (const slug of [QUIZZES, PLAYS]) {
-        if (await getCollection(slug)) continue;
-        const schema = JSON.parse(await fs.readFile(new URL(`../collections/${slug}.json`, import.meta.url), 'utf8'));
-        await createCollection(schema);
-        log.info?.(`[quiz] Created collection: ${slug}`);
-    }
-}
-
-const flat = (e) => (e ? {id: e.id, ...e.data, createdAt: e.meta?.createdAt, updatedAt: e.meta?.updatedAt} : null);
-
-let cache = null;
-export async function allQuizzes() {
-    cache ??= listEntries(QUIZZES, {limit: 100000}).then(r => (r.entries || []).map(flat)).catch(() => []);
-    return cache;
-}
-const forget = () => { cache = null; };
-
-export const getQuiz = async (id) => flat(await getEntry(QUIZZES, String(id)).catch(() => null));
-export const quizBySlug = async (slug) => (await allQuizzes()).find(q => q.slug === String(slug)) || null;
-
-/** A short name no other quiz has. */
-export async function uniqueSlug(slug, selfId = '') {
-    const taken = new Set((await allQuizzes()).filter(q => q.id !== selfId).map(q => q.slug));
-    if (!taken.has(slug)) return slug;
-    for (let n = 2; ; n++) if (!taken.has(`${slug}-${n}`)) return `${slug}-${n}`;
-}
-
-export async function saveQuiz(id, data) {
-    const saved = id ? await updateEntry(QUIZZES, id, data) : await createEntry(QUIZZES, data);
-    forget();
-    return flat(saved);
-}
-
-export async function removeQuiz(id) {
-    await deleteEntry(QUIZZES, String(id));
-    forget();
-    return plays.reset(String(id));
-}