Building a Rock-Paper-Scissors CLI with TypeScript — Union Types, Conditionals, and Jest

Introduction

This is my second article as a Java engineer learning TypeScript from scratch.

In my first article, I built a BMI Calculator CLI and learned about union types, function separation, and Vitest. This time, I built a Rock-Paper-Scissors game (CLI) and focused on:

• Expressing game "hands" and "results" with union types
• Understanding when to use if vs else if
• Writing unit tests with Jest + ts-jest (I used Vitest last time — this time I wrestled with Jest)
• Understanding the difference between the nullish coalescing operator ?? and type assertion as

Same as before — I write honestly about what I struggled with, what I figured out, and what I asked AI to help with.

---

My Learning Style (AI Transparency)

I use Claude Pro (for design discussions and Q&A) and Cursor Pro (for coding support) as learning companions.

However, I follow these rules for myself:

• I write all the code myself — I never ask AI to write code for me
• AI helps with hints, spec clarification, and bug spotting
• I make sure I understand why something works before moving on

In this article, I clearly separate "what I implemented myself" from "what I asked AI for."

---

What I Built

A CLI Rock-Paper-Scissors game where you play against the computer.

$ npm start

Enter your hand (rock, paper, scissors): rock
Player: rock
Computer: scissors
Result: win

Invalid input (anything other than rock, paper, or scissors) is rejected with a validation message.

📦 Repository: https://github.com/uya0526-design/janken-game

---

Project Structure

janken-game/
├── src/
│   ├── index.ts           # Entry point / CLI I/O
│   ├── game.ts            # Game logic (result determination, CPU hand generation)
│   ├── types.ts           # Type definitions
│   └── __tests__/
│       └── game.test.ts   # Unit tests (all 9 combinations)
├── jest.config.js
├── package.json
└── tsconfig.json

Same as my BMI project — responsibilities are separated by file.

---

Tech Stack

• TypeScript
• Node.js (readline module)
• Jest + ts-jest (unit testing)

---

What I Implemented Myself

types.ts — Type Definitions

export type Hand   = 'rock' | 'paper' | 'scissors';
export type Result = 'win'  | 'lose'  | 'draw';

I chose this design myself, based on experience from the previous project.

Why union types instead of enum?
With enum, the underlying values are numbers (0, 1, 2), which makes logs harder to read. With union types, the string values appear as-is — cleaner for debugging and more idiomatic TypeScript.

I also added export myself, knowing these types would be needed in other files.

---

game.ts — determineResult function

All 9 combinations (3×3) of win/lose/draw logic live here.

import type { Hand, Result } from './types.js';

export function determineResult(player: Hand, computer: Hand): Result {
  if (player === computer) return 'draw';
  if (
    (player === 'rock'     && computer === 'scissors') ||
    (player === 'scissors' && computer === 'paper')    ||
    (player === 'paper'    && computer === 'rock')
  ) {
    return 'win';
  }
  return 'lose';
}

if vs else if — where I got it wrong first:

My initial version looked like this:

// First attempt (not ideal)
if (player === computer) return 'draw';
if (player === 'rock' && computer === 'scissors') return 'win';
if (player === 'rock' && computer === 'paper') return 'lose';
// ... all 9 combinations as separate if statements

This works because of the return statements, but the intent is unclear — after matching 'draw', the other if blocks still get evaluated. AI pointed out that mutually exclusive conditions should use else if to signal that only one branch can be true. That feedback led me to the cleaner version above.

---

game.ts — getComputerHand function

export function getComputerHand(): Hand {
  const hands: Hand[] = ['rock', 'paper', 'scissors'];
  const index = Math.floor(Math.random() * hands.length);
  return hands[index] as Hand;
}

Design decisions:

• Used hands.length instead of hardcoding * 3
• Chose as Hand over ?? 'rock' after understanding the difference

The nullish coalescing operator ?? returns the right-hand side only when the left is null or undefined. Since hands[index] is always a valid Hand value within bounds, a fallback isn't needed. I used as Hand instead to explicitly tell the compiler "this is safe, I've validated it."

---

index.ts — CLI Input/Output

import * as readline from 'readline';
import { determineResult, getComputerHand } from './game.js';
import type { Hand } from './types.js';

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

const validHands: Hand[] = ['rock', 'paper', 'scissors'];

rl.question('Enter your hand (rock, paper, scissors): ', (input) => {
  if (!validHands.includes(input as Hand)) {
    console.log('Invalid input. Please enter rock, paper, or scissors.');
    rl.close();
    return;
  }

  const playerHand = input as Hand;
  const computerHand = getComputerHand();
  const result = determineResult(playerHand, computerHand);

  console.log(`Player: ${playerHand}`);
  console.log(`Computer: ${computerHand}`);
  console.log(`Result: ${result}`);

  rl.close();
});

One lesson from the previous project: always call rl.close() in every exit path. This time I made sure both the validation failure path and the happy path close properly.

---

game.test.ts — Unit Tests with Jest

The goal: cover all 9 combinations (3 wins + 3 losses + 3 draws).

import { determineResult } from '../game';

describe('determineResult', () => {
  // Win (3 patterns)
  test('rock beats scissors', () => {
    expect(determineResult('rock', 'scissors')).toBe('win');
  });
  test('scissors beats paper', () => {
    expect(determineResult('scissors', 'paper')).toBe('win');
  });
  test('paper beats rock', () => {
    expect(determineResult('paper', 'rock')).toBe('win');
  });

  // Lose (3 patterns)
  test('rock loses to paper', () => {
    expect(determineResult('rock', 'paper')).toBe('lose');
  });
  test('scissors loses to rock', () => {
    expect(determineResult('scissors', 'rock')).toBe('lose');
  });
  test('paper loses to scissors', () => {
    expect(determineResult('paper', 'scissors')).toBe('lose');
  });

  // Draw (3 patterns)
  test('rock vs rock is a draw', () => {
    expect(determineResult('rock', 'rock')).toBe('draw');
  });
  test('scissors vs scissors is a draw', () => {
    expect(determineResult('scissors', 'scissors')).toBe('draw');
  });
  test('paper vs paper is a draw', () => {
    expect(determineResult('paper', 'paper')).toBe('draw');
  });
});

Test results:

 PASS  src/__tests__/game.test.ts
  determineResult
    ✓ rock beats scissors
    ✓ scissors beats paper
    ✓ paper beats rock
    ✓ rock loses to paper
    ✓ scissors loses to rock
    ✓ paper loses to scissors
    ✓ rock vs rock is a draw
    ✓ scissors vs scissors is a draw
    ✓ paper vs paper is a draw

Tests: 9 passed, 9 total

The boundary value mindset I developed in the BMI project carried over here — for Rock-Paper-Scissors, full coverage means all 9 combinations.

---

What I Asked AI For

Topic	What AI helped with
Hand type design	Introduced me to union types and string literal types
if vs else if	Pointed out that mutually exclusive conditions should use else if
CPU random hand	Suggested the Math.random() + array approach and flagged the need for type assertion
Missing rl.close()	Spotted that the happy path was missing rl.close()
Jest basics	Showed me the describe / test / expect structure

---

Where I Got Stuck

1. Jest TypeScript error: TS5107: moduleResolution=node10 deprecated

Situation: Running npm test gave this error:

error TS5107: Option 'moduleResolution' value 'node10' is deprecated.

Investigation: I read the error message and figured out that tsconfig.json was using an outdated setting.

Fix: Updated module and moduleResolution in tsconfig.json to nodenext:

{
  "compilerOptions": {
    "module": "nodenext",
    "moduleResolution": "nodenext"
  }
}

Important caveat: I kept "type": "commonjs" in package.json. Changing it to "module" caused Jest compatibility errors. These two settings are independent — tsconfig.json controls the TypeScript compiler, while package.json controls how Node.js handles .js files at runtime. The right combination depends on the tooling version.

---

2. Three losses in a row — is Math.random broken?

Situation: After losing 3 times in a row out of 5 games, I started to wonder if the CPU hand wasn't actually random.

Investigation: I re-read the code — the implementation was correct.

Insight: With only 5 samples, variance is completely expected (law of large numbers). Over 100 games the distribution would even out. This wasn't a bug — it was a statistics lesson.

---

3. .js extension required with moduleResolution: nodenext

Situation: Importing from types.ts threw this error:

Cannot find module './types'

Fix: With moduleResolution: nodenext, TypeScript requires .js extensions even in .ts files:

// ❌ Does not work
import type { Hand, Result } from './types';

// ✅ Works
import type { Hand, Result } from './types.js';

The reason: TypeScript assumes you're referencing the compiled output (.js), not the source file (.ts). It felt strange at first, but once I understood the reasoning it made sense.

---

What I Learned

TypeScript Type System

Topic	Key Takeaway
Union types	Define a fixed set of allowed values as a type (e.g. Hand limited to rock, paper, or scissors)
String literal types	The string itself becomes the type. Lighter than enum and more idiomatic TypeScript
Type assertion as	Tells the compiler "trust me, I've validated this" — use only after validation
import type	Imports type information only — not included in the runtime bundle

Conditional Logic

Topic	Key Takeaway
if vs else if	Mutually exclusive conditions should use else if to make intent clear
Early return	Returning early on invalid input keeps nesting shallow and logic readable

Nullish Coalescing ??

Returns the right-hand side only when the left is null or undefined. Unlike ||, it does not trigger on 0 or "". Useful for fallback values when undefined is the only concern — but not needed when array bounds are guaranteed.

Jest Unit Testing

Topic	Key Takeaway
describe	Groups related tests (similar to @Nested in JUnit)
test	Defines an individual test case (similar to @Test in JUnit)
expect(...).toBe(...)	Strict equality check
Full coverage mindset	Rock-Paper-Scissors has 3×3 = 9 combinations — covering all of them gives confidence in the logic

Module System Configuration

A deeper understanding than the previous project:

• tsconfig.json (module / moduleResolution) — controls the TypeScript compiler
• package.json ("type") — controls how Node.js interprets .js files at runtime
• These are independent settings; the right combination depends on your toolchain

---

Reflection

Where my Java background helped: I naturally structured the logic before writing code (design-first thinking). Writing all 9 test cases proactively also reflects a quality-first mindset from Java development.

Where I got tripped up: The module resolution configuration (tsconfig.json vs package.json) has no real equivalent in Java. I was confused at first, but reading the error messages carefully led me to the fix — which felt like a real debugging win.

The "is this a bug?" moment: Suspecting Math.random after 3 losses taught me not to draw conclusions from small samples. That's a useful development instinct to build early.

---

Wrapping Up

This was my second TypeScript project — a Rock-Paper-Scissors CLI.

Progress since the BMI calculator:

1. Chose union types on my own, without being prompted
2. Understood else if and used it to express intent clearly
3. Designed and implemented all 9 test combinations myself
4. Read an error message, investigated, and fixed it independently

The full learning log is in LEARNING_LOG.md.

---

This article is part of my public learning journey using AI tools (Claude Pro / Cursor Pro). All code is written by me — AI is used for design discussions, bug hints, and spec clarification only.