Forem: Uya

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

Uya — Mon, 25 May 2026 13:46:33 +0000

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:

Chose union types on my own, without being prompted
Understood else if and used it to express intent clearly
Designed and implemented all 9 test combinations myself
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.

Building a BMI Calculator CLI with TypeScript — Types, Functions, and Vitest

Uya — Sat, 23 May 2026 16:05:50 +0000

Introduction

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

I've been writing Java professionally, but I got interested in modern tech stacks and started learning TypeScript and Python. My approach is simple: build small projects one by one, and write honestly about everything — what I struggled with, what I figured out, and what I asked AI to help with.

This article is for people on a similar learning journey. It's not a showcase of perfect code — it's an honest record of the process.

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 tool that calculates BMI from height and weight input.

$ npm start

Enter your height (cm): 170
Enter your weight (kg): 70
BMI result: 24.22 (Normal)

BMI Classification

BMI	Label
< 18.5	Underweight
18.5 – 24.9	Normal
≥ 25.0	Obese

📦 Repository: https://github.com/uya0526-design/bmi-calculator

Project Structure

bmi-calculator/
├── src/
│   ├── index.ts              # Entry point / CLI I/O
│   ├── calculator.ts         # BMI calculation and classification logic
│   ├── types.ts              # Type definitions
│   └── __tests__/
│       ├── calculator.test.ts # Unit tests
│       └── types.test.ts      # Type tests (skipped with describe.skip)
├── package.json
├── tsconfig.json
└── LEARNING_LOG.md

Separating responsibilities by file made it much clearer where everything lived.

Tech Stack

TypeScript
Node.js (readline module)
Vitest (unit testing)

What I Implemented Myself

types.ts — Type Definitions

// Type aliases for height, weight, and BMI value
type Height = number;
type Weight = number;
type BmiValue = number;

// Union type for classification labels
type BmiLabel = "Underweight" | "Normal" | "Obese";

// Object type to hold the calculation result
export type BmiOutput = {
  bmi: BmiValue;
  label: BmiLabel;
};

The key decision here was using a union type for BmiLabel. Any string outside of "Underweight" | "Normal" | "Obese" causes a type error at compile time.

calculator.ts — Calculation Logic

import type { BmiOutput } from "./types";

function getBmiLabel(bmi: number): string {
  if (bmi < 18.5) return "Underweight";
  if (bmi < 25) return "Normal";
  return "Obese";
}

export function calculateBmi(height: number, weight: number): BmiOutput {
  const heightInM = height / 100;
  const bmi = weight / heightInM ** 2;
  const label = getBmiLabel(bmi);
  return { bmi, label };  // shorthand property notation
}

I decided not to export getBmiLabel since it's only used internally — and I made that call myself.

index.ts — CLI Input/Output

import * as readline from "readline";
import { calculateBmi } from "./calculator";

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

function main() {
  rl.question("Enter your height (cm): ", (heightInput) => {
    if (isNaN(Number(heightInput))) {
      console.log("Please enter a number.");
      rl.close();
      return;
    }
    rl.question("Enter your weight (kg): ", (weightInput) => {
      if (isNaN(Number(weightInput))) {
        console.log("Please enter a number.");
        rl.close();
        return;
      }
      const result = calculateBmi(Number(heightInput), Number(weightInput));
      console.log(`BMI result: ${result.bmi.toFixed(2)} (${result.label})`);
      rl.close();  // ← position matters (see "Where I Got Stuck")
    });
  });
}

main();

calculator.test.ts — Unit Tests with Vitest

import { describe, it, expect } from "vitest";
import { calculateBmi } from "../calculator";

describe("calculateBmi", () => {
  it("BMI 18.49 → Underweight", () => {
    const result = calculateBmi(170, 53.5);
    expect(result.label).toBe("Underweight");
  });

  it("BMI 18.5 → Normal", () => {
    const result = calculateBmi(170, 53.52);
    expect(result.label).toBe("Normal");
  });

  it("BMI 25 or above → Obese", () => {
    const result = calculateBmi(170, 72.25);
    expect(result.label).toBe("Obese");
  });

  it("BMI calculation accuracy", () => {
    const result = calculateBmi(170, 70);
    expect(result.bmi).toBeCloseTo(24.22, 1);
  });
});

I deliberately chose boundary values (18.49 / 18.5 / 25) to verify the branching logic.

What I Asked AI For

Topic	Details
Type design thinking	Asked about the difference between tuple types and object types
tsconfig.json options	Learned what `module`, `target`, and `strict` each do
Vitest setup	Confirmed the setup steps and `package.json` config
Test design principles	Learned the difference between `toBe` and `toBeOneOf`, and the one-case-per-test rule

Where I Got Stuck

1. `npm` wouldn't run in PowerShell

Cause: The default execution policy was Restricted (no scripts allowed).

Fix:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

Using -Scope Process applies the change only to the current session — no permanent system changes.

2. Mismatch between `package.json` `"type"` and `tsconfig.json` `"module"`

Situation: package.json had "type": "module" but tsconfig.json had "module": "commonjs" — they were out of sync.

Fix: Changed package.json to "type": "commonjs". These two settings always need to match.

3. `rl.close()` in the wrong place

Situation: I put rl.close() at the end of the outer callback, but it was closing readline before the inner rl.question could finish.

Insight: rl.question is asynchronous. Writing code after it doesn't mean it runs after the callback completes.

Fix: Moved rl.close() inside the inner callback, after all processing is done.

What I Learned

TypeScript

Topic	Key Takeaway
Union types	Union types restrict strings to allowed values, catching mistakes at compile time
Limits of type aliases	`Height = number` and `Weight = number` are both just `number` at runtime — swapping arguments doesn't cause a type error (Branded Types can fix this)
`import type`	Explicitly imports types only — useful with `verbatimModuleSyntax`
Shorthand properties	`{ bmi, label }` works when variable names match property names

Testing (Vitest)

Topic	Key Takeaway
TypeScript types don't exist at runtime	Testing types with Vitest is unnecessary — the compiler already guarantees them
`toBe` vs `toBeOneOf`	`toBeOneOf` passes if any value matches — it can't verify correctness. Use `toBe` with a specific expected value
Boundary value testing	Testing around thresholds (18.5, 25) verifies that branching logic is correct
`describe.skip`	Keeps the file in place while skipping tests — useful for preserving learning notes

Wrapping Up

This was my first TypeScript project — a simple BMI calculator CLI.

Two things stood out from this experience:

Designing types first made implementation smoother
Async callbacks are easy to misplace — position matters

Next up: a Rock-Paper-Scissors game (union types, conditionals, enums).

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.

Forem: Uya

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

Introduction

My Learning Style (AI Transparency)

What I Built

Project Structure

Tech Stack

What I Implemented Myself

types.ts — Type Definitions

game.ts — determineResult function

game.ts — getComputerHand function

index.ts — CLI Input/Output

game.test.ts — Unit Tests with Jest

What I Asked AI For

Where I Got Stuck

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

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

3. .js extension required with moduleResolution: nodenext

What I Learned

TypeScript Type System

Conditional Logic

Nullish Coalescing ??

Jest Unit Testing

Module System Configuration

Reflection

Wrapping Up

Building a BMI Calculator CLI with TypeScript — Types, Functions, and Vitest

Introduction

My Learning Style (AI Transparency)

What I Built

Project Structure

Tech Stack

What I Implemented Myself

types.ts — Type Definitions

calculator.ts — Calculation Logic

index.ts — CLI Input/Output

calculator.test.ts — Unit Tests with Vitest

What I Asked AI For

Where I Got Stuck

1. npm wouldn't run in PowerShell

2. Mismatch between package.json "type" and tsconfig.json "module"

3. rl.close() in the wrong place

What I Learned

TypeScript

Testing (Vitest)

Wrapping Up

game.ts — `determineResult` function

game.ts — `getComputerHand` function

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

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

3. `.js` extension required with `moduleResolution: nodenext`

Nullish Coalescing `??`

1. `npm` wouldn't run in PowerShell

2. Mismatch between `package.json` `"type"` and `tsconfig.json` `"module"`

3. `rl.close()` in the wrong place