Trivia Q&A Application (TypeScript)

A production-ready console-based trivia game in TypeScript that fetches questions from the Open Trivia Database API and provides an interactive Q&A experience.

Architecture & Design Principles

This application follows enterprise-grade best practices using modern TypeScript features:

Observability

Structured logging with timestamps and severity levels (DEBUG, INFO, WARNING, ERROR)
Request tracing with attempt counters
Comprehensive error reporting with stack traces

Reliability

Strong type safety with strict TypeScript configuration
Comprehensive error handling and validation
Graceful degradation on API failures
Input validation with type guards

Resilience

Automatic retry logic with exponential backoff (configurable)
Timeout handling for network requests (10 seconds)
Connection error recovery with 3 retry attempts
Promise-based async/await pattern

Accuracy

HTML entity decoding for proper question/answer display
Answer verification with immediate feedback
Score tracking and detailed results reporting
Type-safe game state management

Agility

Modular class-based architecture (Client, Game, UI, Logger)
Interface-based abstractions for easy extension
Easy to configure (constants at the top)
Support for both CLI and library usage

Technology Stack

TypeScript 5.0+ - Strict mode with advanced type checking
Node.js 20+ - Built on modern JavaScript runtime
Builtin APIs: https for HTTP requests, readline for CLI interaction
Zero external dependencies for production runtime

Installation

# Clone or download the project
cd trivia-qa-typescript

# Install dependencies
npm install

# Or use yarn
yarn install

Quick Start

Option 1: Run Demo (No Network Required)

Perfect for testing without internet access:

# Compile TypeScript to JavaScript
npm run build

# Run the demo version with mock data
node dist/trivia_app_demo.js

Or with ts-node (no compilation needed):

npm install -g ts-node
ts-node trivia_app_demo.ts

Option 2: Run Live Version (Requires Internet)

Fetches real questions from Open Trivia Database:

# Compile and run
npm start

# Or with ts-node
npm run dev

Option 3: Manual Compilation and Execution

# Compile TypeScript
npm run build

# Run the compiled application
node dist/trivia_app.js

Project Structure

├── trivia_app.ts              # Main application with API integration
├── trivia_app_demo.ts         # Demo version with mock data
├── package.json               # NPM configuration
├── tsconfig.json             # TypeScript compiler options
└── README.md                 # This file

Key Features

✓ Fetches 10 random trivia questions from Open Trivia Database
✓ Displays questions with difficulty level and category
✓ Presents multiple-choice answers (randomized for each question)
✓ Immediate feedback on answer correctness
✓ Final score report with question-by-question breakdown
✓ Comprehensive error handling and logging
✓ Clean, intuitive console UI
✓ Graceful handling of network errors and timeouts
✓ Type-safe implementation with strict TypeScript

Architecture Overview

trivia_app.ts / trivia_app_demo.ts
├── Logger (Observability)
│   └── LogLevel enum
├── Domain Models (Accuracy)
│   ├── Question (encapsulates question logic)
│   ├── TriviaResponse (API response wrapper)
│   └── Interfaces (TriviaQuestion, TriviaResponseData)
├── API Client (Resilience)
│   └── TriviaAPIClient (with retry logic)
├── Game Logic (Accuracy)
│   └── TriviaGame (state management)
├── Console UI (UX)
│   └── ConsoleUI (readline wrapper)
├── Mock Data Provider (Testing)
│   └── MockTriviaProvider (for demo mode)
└── Main (Orchestration)
    └── main() async function

Configuration

Edit these constants in the source files to customize behavior:

const API_ENDPOINT = "https://opentdb.com/api.php?amount=10";
const REQUEST_TIMEOUT = 10000; // milliseconds
const MAX_RETRIES = 3; // retry attempts
const RETRY_DELAY = 1000; // milliseconds between retries

To change logging level:

const logger = new Logger("trivia_app", LogLevel.DEBUG); // More verbose
const logger = new Logger("trivia_app", LogLevel.WARNING); // Less verbose

TypeScript Features Used

Strong Type Safety

Strict null checks (strictNullChecks)
No implicit any (noImplicitAny)
Function type checking (strictFunctionTypes)

Advanced Types

Enums for ResponseCode and LogLevel
Interfaces for API contracts
Discriminated unions for proper type narrowing
Generic shuffle function <T>(array: T[]): T[]

ES2020 Features

Async/await for promises
Arrow functions
Template literals
Destructuring
Spread operator

Object-Oriented Design

Encapsulation with private/public methods
Single responsibility principle (each class has one job)
Dependency injection (classes receive dependencies)
Interface-based contracts

Error Handling

The application handles:

Connection Errors: Network unavailability with retry logic
Timeout Errors: Requests taking too long (10s limit)
JSON Parse Errors: Invalid API responses
HTTP Errors: Non-200 status codes
Input Validation: User input bounds checking
Game State Errors: Invalid game state transitions

All errors are logged with appropriate detail levels:

ERROR - HTTP 500 Connection error
WARNING - Connection error on attempt 1
INFO - Successfully fetched 10 questions
DEBUG - Correct answer. Score: 5/10

Logging Levels

enum LogLevel {
  DEBUG = 0, // Verbose - all messages
  INFO = 1, // Standard - info+ messages
  WARNING = 2, // Errors only - warning+ messages
  ERROR = 3, // Critical - errors only
}

Game Flow

Initialization: User runs the application
Loading: Fetch questions from API (or mock data for demo)
Game Loop: For each question:
- Display question with category and difficulty
- Show randomized answer options
- Get user input (1-4)
- Validate and verify answer
- Show immediate feedback
- Move to next question
Results: Display final score and detailed breakdown
Cleanup: Close readline interface gracefully

Extension Points

Add a Custom Logger

class FileLogger extends Logger {
  error(message: string, error?: Error): void {
    super.error(message, error);
    // Also write to file
    fs.appendFileSync("error.log", message);
  }
}

Add a New Data Source

class TriviaDatabaseClient extends TriviaAPIClient {
  constructor() {
    super("https://custom-trivia-api.com/questions");
  }
}

Add Game Modes

class TimedTriviaGame extends TriviaGame {
  private timePerQuestion = 30; // seconds

  async getAnswer(): Promise<string> {
    // Implement timed input
  }
}

Customize UI

class ColoredConsoleUI extends ConsoleUI {
  printHeader(text: string): void {
    console.log("\x1b[36m" + text + "\x1b[0m"); // Cyan color
  }
}

Building for Production

# Build with optimizations
npm run build

# Check for TypeScript errors
npx tsc --noEmit

# Run the compiled app
node dist/trivia_app.js

# Bundle size check (minimal - only std library used)
ls -lh dist/

Dependencies

Production Runtime

Node.js builtin modules only
- https - HTTP requests
- readline - CLI interaction

Development Dependencies

typescript - TypeScript compiler
ts-node - TypeScript execution engine
@types/node - Node.js type definitions

Performance Characteristics

Startup Time: < 100ms
API Request: ~500ms-2s (depending on network)
Retry Logic: Up to 3 seconds for failed requests (3 retries × 1 second)
Memory Usage: ~10MB
Binary Size (compiled): ~5KB (without node_modules)

Testing

Unit Test Considerations

The modular design allows easy unit testing:

// Mock the API client
class MockAPIClient extends TriviaAPIClient {
  async fetchQuestions(): Promise<TriviaResponse | null> {
    return MockTriviaProvider.getMockData();
  }
}

// Test game logic
const game = new TriviaGame(mockQuestions);
game.submitAnswer("correct");
assert(game.getScore() === 1);

Troubleshooting

"Cannot find module 'readline'"

Ensure you're running Node.js 14+
Use builtin readline module (no installation needed)

"ECONNREFUSED" or "ENOTFOUND"

Check internet connection
Try demo version: npm run build && node dist/trivia_app_demo.js
Verify API endpoint is accessible

"Input validation failed"

Ensure you're entering numbers 1-4 only
Try again with valid input

TypeScript compilation errors

Run npm install to ensure dependencies are installed
Check tsconfig.json is in project root
Use npm run build for proper compilation

Future Enhancements

Leaderboard/score persistence to JSON
Difficulty filtering (?difficulty=easy|medium|hard)
Category selection
Timed modes (e.g., 30 seconds per question)
Multiple language support
Web UI variant (React/Vue)
API metrics collection
Configuration file support
Save/resume game functionality
Multiplayer support

License

MIT

Contributing

This is a demonstration project. Feel free to modify and extend it for your needs.

Performance Tips

For High-Volume Usage

Increase REQUEST_TIMEOUT for slower networks
Adjust MAX_RETRIES based on infrastructure
Consider connection pooling for multiple games

For CI/CD Integration

Use mock data for automated tests
Run with --no-color for cleaner logs
Capture output for test reporting

Support

For issues or questions:

Check the troubleshooting section
Review the TypeScript source code (well-commented)
Consult Node.js https and readline documentation
Test with demo version first

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
README.md		README.md
package.json		package.json
trivia_app.ts		trivia_app.ts
trivia_app_demo.ts		trivia_app_demo.ts
tsconfig.json		tsconfig.json

fbrcode-ent/trivia-typescript

Folders and files

Latest commit

History

Repository files navigation