The Type-Safe Quiz Engine — TypeScript Milestone Project

You are ready to build a small quiz engine, a program that stores questions, checks submitted answers, and prints a score report. The goal is not a fancy interface. The goal is to make wrong question shapes impossible and scoring logic easy to trust.

The playground is standing in for command-line output. It uses fixed sample answers so every run is repeatable.

What you'll build

You will build one quiz workspace with:

Three question shapes: multiple choice, true/false, and fill-in.
A discriminated union that keeps each question's fields honest.
A scorer that uses switch narrowing and a never checklist.
A tiny type predicate for submitted answers.
A sample run that prints per-question feedback and the final score.

A scaffold is starter code with comments that show where each part belongs. The acceptance criteria are checks you can run yourself to prove a stage works.

typescript — playgroundtype-checked

type MultipleChoiceQuestion = {
kind: "multiple_choice";
id: string;
prompt: string;
choices: string[];
correctIndex: number;
points: number;
};

type TrueFalseQuestion = {
kind: "true_false";
id: string;
prompt: string;
correctAnswer: boolean;
points: number;
};

type FillInQuestion = {
kind: "fill_in";
id: string;
prompt: string;
acceptedAnswers: string[];
points: number;
};

type Question = MultipleChoiceQuestion | TrueFalseQuestion | FillInQuestion;

type SubmittedAnswer = {
questionId: string;
value: string;
};

type CorrectResult = {
status: "correct";
questionId: string;
pointsEarned: number;
pointsPossible: number;
feedback: string;
};

type IncorrectResult = {
status: "incorrect";
questionId: string;
pointsEarned: 0;
pointsPossible: number;
feedback: string;
};

type MissingResult = {
status: "missing";
questionId: string;
pointsEarned: 0;
pointsPossible: number;
feedback: string;
};

type GradeResult = CorrectResult | IncorrectResult | MissingResult;

type QuizReport = {
results: GradeResult[];
score: number;
total: number;
};

const questions: Question[] = [
{
  kind: "multiple_choice",
  id: "q1",
  prompt: "Which TypeScript type means one of these exact strings?",
  choices: ["boolean", "literal union", "Date"],
  correctIndex: 1,
  points: 2,
},
{
  kind: "true_false",
  id: "q2",
  prompt: "A discriminated union uses one shared literal property.",
  correctAnswer: true,
  points: 1,
},
{
  kind: "fill_in",
  id: "q3",
  prompt: "What type is the empty set of possible values?",
  acceptedAnswers: ["never"],
  points: 1,
},
];

const submittedAnswers: SubmittedAnswer[] = [
{ questionId: "q1", value: "2" },
{ questionId: "q2", value: "true" },
{ questionId: "q3", value: "void" },
];

function normalizeAnswer(value: string): string {
return value.trim().toLowerCase();
}

function hasSubmittedAnswer(
answer: SubmittedAnswer | undefined,
): answer is SubmittedAnswer {
return answer !== undefined && answer.value.trim() !== "";
}

function findAnswer(
answers: SubmittedAnswer[],
questionId: string,
): SubmittedAnswer | undefined {
return answers.find((answer) => answer.questionId === questionId);
}

function acceptedFillIn(question: FillInQuestion, value: string): boolean {
const normalized = normalizeAnswer(value);

for (const accepted of question.acceptedAnswers) {
  if (normalizeAnswer(accepted) === normalized) {
    return true;
  }
}

return false;
}

function correct(
question: Question,
feedback: string,
): CorrectResult {
return {
  status: "correct",
  questionId: question.id,
  pointsEarned: question.points,
  pointsPossible: question.points,
  feedback,
};
}

function incorrect(
question: Question,
feedback: string,
): IncorrectResult {
return {
  status: "incorrect",
  questionId: question.id,
  pointsEarned: 0,
  pointsPossible: question.points,
  feedback,
};
}

function missing(question: Question): MissingResult {
return {
  status: "missing",
  questionId: question.id,
  pointsEarned: 0,
  pointsPossible: question.points,
  feedback: "No answer submitted.",
};
}

function gradeQuestion(
question: Question,
answers: SubmittedAnswer[],
): GradeResult {
const answer = findAnswer(answers, question.id);

if (!hasSubmittedAnswer(answer)) {
  return missing(question);
}

switch (question.kind) {
  case "multiple_choice": {
    const chosenIndex = Number(answer.value) - 1;
    if (chosenIndex === question.correctIndex) {
      return correct(question, "Choice " + answer.value + " is correct.");
    }
    return incorrect(question, "Expected " + expectedAnswer(question) + ".");
  }
  case "true_false": {
    const cleaned = normalizeAnswer(answer.value);
    if (cleaned !== "true" && cleaned !== "false") {
      return incorrect(question, "Answer true or false.");
    }

function gradeQuiz(
quizQuestions: Question[],
answers: SubmittedAnswer[],
): QuizReport {
const results = quizQuestions.map((question) => gradeQuestion(question, answers));
let score = 0;
let total = 0;

for (const result of results) {
  score = score + result.pointsEarned;
  total = total + result.pointsPossible;
}

return { results, score, total };
}

function printReport(title: string, report: QuizReport): void {
console.log(title);

for (const result of report.results) {
  console.log(resultLine(result));
}

console.log("Score: " + report.score + "/" + report.total);
}

// TODO stage 1: add one more question to the questions array.
// TODO stage 2: add the matching submitted answer.
// TODO stage 3: change one answer and watch the score update.
// TODO stage 4: add a new question kind, then follow every never error.

const report = gradeQuiz(questions, submittedAnswers);
printReport("TypeScript Foundations Quiz", report);

// break it: uncomment the next line, then hit Run
// const brokenQuestion: Question = { kind: "multiple_choice", id: "bad", prompt: "Pick one", choices: ["A", "B"], correctAnswer: true, points: 1 };

⌘/Ctrl + Enter to run

Checkpoint 1: model the question set

Start with the question types. A multiple-choice question needs choices and a correct index. A true/false question needs a boolean answer. A fill-in question needs accepted text answers.

Acceptance criteria:

The Question type is a discriminated union.
Every question has kind, id, prompt, and points.
Each question kind has only the fields it needs.
Uncommenting brokenQuestion fails before the program runs.

Checkpoint 2: find and clean answers

The submitted answers are fixed data for now. That keeps the project focused on types instead of input timing.

Acceptance criteria:

findAnswer returns SubmittedAnswer | undefined.
hasSubmittedAnswer narrows away undefined.
Blank answers count as missing.
Fill-in answers compare lowercase trimmed text.

Checkpoint 3: score with narrowing

The scorer is the heart of the project. Each case is a safe room: TypeScript knows the exact question shape in that branch.

Acceptance criteria:

gradeQuestion uses switch (question.kind).
Multiple-choice answers use correctIndex.
True/false answers reject text that is not true or false.
Fill-in answers use acceptedAnswers.
The default branch assigns the leftover question to never.

Checkpoint 4: print the report

A score report is the final summary of each graded answer plus the total. This stage proves your engine works end to end.

Acceptance criteria:

The first run prints three result lines.
The sample score is 3/4.
Changing q3 from void to never changes the score to 4/4.
Changing a question's points changes the total everywhere.

Stretch goals

Choose one after the base engine works:

Add a second multiple-choice question with four choices.
Add a missing answer by removing one item from submittedAnswers.
Add a "short_answer" question kind and let the never checklist guide every required edit.
Add a category field so the report can print Types, Functions, or Narrowing.
Move the sample answers into a different order and confirm lookup still uses questionId.

How to get unstuck

If a union member rejects a field, revisit the literal-union model from Union Types & Literal Types. If a branch cannot use a field yet, compare it to Narrowing: How TypeScript Thinks. If the switch feels noisy, reread Discriminated Unions and follow the never checklist. If SubmittedAnswer | undefined is confusing, use Type Predicates & in / instanceof to trace the answer is SubmittedAnswer promise.

Part I is complete when this engine feels readable. Next, Part II moves deeper into object types, classes, and generics so your shapes and reusable code can grow without giving up the checker.