DEV Community: Uya

Building a Weight Tracker CLI in Python — Type Hints, Pure Functions, and pytest

Uya — Fri, 12 Jun 2026 12:56:39 +0000

Introduction

This is my eighth article as a Java engineer learning TypeScript and Python from scratch.

My first seven articles were all small TypeScript CLIs. In the previous one, I built an HTTP client in TypeScript that calls a FastAPI (Python) server I wrote myself — that was my first contact with Python (FastAPI), but only as "the thing the client calls."

In other words, Python played a supporting role last time. From here, I start Python properly from "project 1." For this first one I go back to the basics: a weight tracker CLI.

What I focused on this time:

Python basics (# comments, def, snake_case, f-strings)
Type hints (list[float], tuple[float, float, float]) and how they differ from Java Generics
Input validation with try / except ValueError
Extracting the calculation logic as a "pure function" (separation of concerns, testability)
Unit testing with pytest (normal, boundary, and error cases)
The habits an ex-Java engineer slips into — and correcting them

As always, I write honestly about where I got stuck, what I thought through, and what I asked AI for.

📝 Where this sits in the series

This is the first article in my Python series. It's also a chance to check whether the mindset I picked up in the TypeScript series — "think in types," "separate logic from I/O," "write tests" — still works when the language changes.

My Learning Style (AI Transparency)

💡 Learning companions & how this article is written

I use Claude Pro (design discussions and Q&A) and Cursor Pro (coding support) as learning companions. Beyond the code, I also collaborate with AI on writing this article itself. Stating the facts plainly here.

Division of roles:

Tech selection, design, implementation, and code verification → me

Article structure, outline, draft prose, and translation → in collaboration with Claude

All content is checked and revised by me before publishing → me

My guiding principle is "the thinking is mine, the wording is AI-assisted, and I verify all of it." I write the code myself (I never ask AI to write code for me), I use AI for hints, spec clarification, and bug spotting, and I make sure I understand why before moving on — and I apply that same stance to the writing process.

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

What I Built

Enter a menu number, and the CLI records a weight, lists recorded weights, or computes statistics (average, max, min).

--------------------------------
1. Record weight
2. Display the recorded weights
3. Display the weight calculation result
4. Exit
--------------------------------
Enter your choice: 1
Enter your weight(kg): 70.5
--------------------------------
Enter your choice: 3
Weight calculation result:
Average weight: 70.5
Max weight: 70.5
Min weight: 70.5

Data is held in memory and resets when you exit (a deliberate simplification for local learning). I'm saving persistence for the next stage.

📦 Repository: https://github.com/uya0526-design/weight_tracker_py

File Structure and Tech Stack

The structure is very simple.

weight_tracker_py/
├── tests/
│   ├── __init__.py
│   └── test_main.py     # unit tests
├── main.py              # entry point
└── requirements.txt     # dependencies

Tech stack:

Python 3.12
pytest 9.0.3

The flow from creating a virtual environment (venv) to running tests:

python -m venv venv               # project-local isolated environment
.\venv\Scripts\Activate.ps1       # activate (Windows PowerShell)
pip install pytest                # install the test tool
pip freeze > requirements.txt     # record dependencies
python main.py                    # run the app
pytest                            # run the tests

I understood venv as "per-project isolation," close to a Maven local repository or Node's node_modules.

What I Implemented Myself

main.py — The menu loop and function split

I run the menu with while True + if / elif, dispatching to a function per choice, and break on 4 to exit.

def main() -> None:
    while True:
        choice = display_main_menu()
        if choice == "1":
            record_weight()
        elif choice == "2":
            display_recorded_weights()
        elif choice == "3":
            display_weight_calculation_result()
        elif choice == "4":
            break
        else:
            print("Invalid choice")

if __name__ == "__main__":
    main()

I understood if __name__ == "__main__": as a declaration of "this is the program's entry point," close to Java's public static void main(String[] args). It doesn't run when imported — only when the file is run directly.

Input validation — try / except ValueError

The weight is read as a string, so I check whether it can be converted to a number.

def record_weight() -> None:
    weight = input("Enter your weight(kg): ")
    # Check if the weight is a number
    try:
        weight = float(weight)
    except ValueError:
        print("Invalid weight")
        return
    recorded_weights.append(weight)

At first I tried to judge "is this a number?" with isdigit() and got stuck (more below). Structurally this is almost the same as Java's try-catch: a string that can't be converted by float() raises ValueError (close to Java's NumberFormatException).

Listing — enumerate and an empty-list check

I used enumerate to list items with numbers.

def display_recorded_weights() -> None:
    print("Recorded weights: ")
    if len(recorded_weights) == 0:
        print("No weights recorded")
        return
    for index, weight in enumerate(recorded_weights):
        print(f"{index + 1}. {weight}")

enumerate is a loop that gives you the index and the element at once, letting me write what I used to write as for (int i = 0; i < list.size(); i++) in Java much more cleanly. I wanted the display to start at 1, so I print index + 1.

Statistics — extracting a pure function (my biggest lesson this time)

This was the design highlight of the project. At first I bundled display and calculation into one function, but I extracted just the calculation logic as a "pure function that takes arguments and only returns values."

# display side (reads the global list → hard to test)
def display_weight_calculation_result() -> None:
    print("Weight calculation result: ")
    if len(recorded_weights) == 0:
        print("No weights recorded")
        return
    average_weight, max_weight, min_weight = calculate_weight_calculation_result(recorded_weights)
    print(f"Average weight: {average_weight}")
    print(f"Max weight: {max_weight}")
    print(f"Min weight: {min_weight}")

# calculation side (takes arguments, only returns values → easy to test)
def calculate_weight_calculation_result(weights: list[float]) -> tuple[float, float, float]:
    average_weight = round(sum(weights) / len(weights), 2)
    max_weight = max(weights)
    min_weight = min(weights)
    return average_weight, max_weight, min_weight

Two points here.

1. Don't read the global variable directly — take it as an argument

The display_... side reads the module-level recorded_weights. That depends on the result of input(), which makes it hard to test. The calculate_... side takes weights as an argument, so a test can pass any list it likes. This is separation of concerns — the same idea I kept coming back to in the TypeScript series, and it worked just as well in Python.

2. Return multiple values as a tuple

return average_weight, max_weight, min_weight returns three values at once. The caller can unpack them with a, b, c = .... In Java, "multiple return values" meant a dedicated class or an array, so writing it with plain syntax felt fresh.

The return type hint -> tuple[float, float, float] feels close to Generics like List<Float> in Java. The big difference is that it's not enforced at runtime (returning a value that doesn't match the type isn't an error), so I understood it as information for the reader and the IDE.

tests/test_main.py — normal, boundary, and error cases

Because I'd extracted a pure function, the tests were very straightforward to write.

import pytest
from main import calculate_weight_calculation_result

# normal: multiple items
def test_calculate_weight_calculation_result():
    weights = [70.12345, 75, 80, 85, 90]
    average_weight, max_weight, min_weight = calculate_weight_calculation_result(weights)
    assert average_weight == 80.02
    assert max_weight == 90.0
    assert min_weight == 70.12345

# error: empty list → division by zero
def test_calculate_weight_calculation_result_empty_list():
    with pytest.raises(ZeroDivisionError):
        calculate_weight_calculation_result([])

# boundary: a single item
def test_calculate_weight_calculation_result_one_weight():
    weights = [70.12345]
    average_weight, max_weight, min_weight = calculate_weight_calculation_result(weights)
    assert average_weight == 70.12
    assert max_weight == 70.12345
    assert min_weight == 70.12345

pytest.raises(ZeroDivisionError) corresponds to Java's assertThrows(ArithmeticException.class, ...). It's interesting that "this should throw an exception" can be written as a test too.

What I Asked AI For

Topic	What AI helped with
Spec clarification	Surfacing unclear points: input validation, display format, how to exit, menu design
Comment syntax	Pointing out that Python uses `#`, not `//`
Validation	Pointing out that `isdigit()` can't handle decimals
Conversion handling	Pointing out I was appending the raw string, and that double-converting with `float()` was unnecessary
Design suggestion	Suggesting I pass the global variable as an argument, for testability
Type hints	Pointing out a mismatch between `-> None` and `-> list[float]`
Testing	The `pytest.raises` syntax, and the ideal folder structure
Dependencies	Explaining `requirements.txt` (direct deps only vs. pinning everything)
README	Tidying it up in both Japanese and English

Note: I found and fixed the wrong test expectation (below) myself.

Where I Got Stuck

1. I wrote comments with `//`

Situation: I wrote a comment with // and it wouldn't run.

Root cause: A Java / TypeScript habit. Python comments use #.

Fix: Changed them all to #.

Takeaway: When the language changes, the first differences show up in the tiniest syntax. A small thing, but it reliably reminds me "you're writing a different language now."

2. `isdigit()` can't reject decimals

Situation: I used "70.5".isdigit() for input validation, and a valid weight got rejected.

Root cause: isdigit() returns True only when every character is a digit. A decimal point . makes it False, so a value like 70.5 doesn't pass.

Fix: I dropped the character-type check and switched to trying a float() conversion, catching failures with try / except ValueError.

# NG: a decimal point makes it False → rejects a valid weight
if weight.isdigit():
    ...

# OK: try to convert, reject on failure
try:
    weight = float(weight)
except ValueError:
    print("Invalid weight")
    return

Takeaway: If you want to know "can this be used as a number?", actually trying to convert it is more reliable than inspecting character types. I learned to pick the check that fits the goal.

3. ZeroDivisionError on an empty list

Situation: Computing the average with zero recorded weights crashed the program.

Root cause: In sum(weights) / len(weights), len became 0, causing a division by zero (ZeroDivisionError).

Fix and design decision: I added an early return if len(recorded_weights) == 0 on the display side, returning "No weights recorded" to the user. On the other hand, I deliberately left the calculation function (calculate_...) to raise ZeroDivisionError as-is, and verified that with a test.

Takeaway: "Where to prevent an error" and "where to let an exception through" are separate decisions. I block early near the UI, while letting the pure function raise naturally and pinning that behavior with a test.

4. Can't import main.py from tests/

Situation: from main import ... in tests/test_main.py raised ModuleNotFoundError.

Root cause: tests/ wasn't recognized as a package, so the import couldn't be resolved.

Fix: Adding tests/__init__.py (an empty file) resolved it.

Takeaway: Folder structure is part of "the spec for making things run." Tracking down the cause myself was a small confidence boost.

5. My test expectation was wrong

Situation: A test failed. The assert for average_weight didn't match.

Root cause: It wasn't the implementation — my own expected value was wrong. I'd written the round() result from my head without actually computing it.

Fix: The average of [70.12345, 75, 80, 85, 90] is 400.12345 / 5 = 80.02469, and round(..., 2) makes it 80.02. I recomputed it by hand and corrected the expectation.

Takeaway: "A failing test" doesn't always mean "the implementation is wrong." Catching a wrong expectation is also part of a test's value. Experiencing the real-world cycle in miniature — a test fails, then you separate whether the cause is the implementation or the expectation — was my biggest gain this time.

What I Learned

Python basics (mapped to Java)

Topic	Key takeaway
Comments	Use `#` (`//` is Java / JavaScript)
Function definition	`def name():` (corresponds to Java's `static void`)
Naming	snake_case `record_weight` (vs. Java's camelCase)
Multiple return values	`return a, b, c` returns a tuple (Java needs a dedicated class or array)
String formatting	f-strings (`f"{variable}"`)

Type hints

You can annotate arguments and return values (list[float], tuple[float, float, float])
Feels close to Java Generics (List<Float>)
But it's not enforced at runtime — it's information for readability and IDE support

Exception handling

try / except has the same structure as Java's try-catch
A string that float() can't convert raises ValueError (close to Java's NumberFormatException)

Testability (separation of concerns)

Functions containing input() or print() are hard to test
Extracting the calculation logic as a pure function that takes arguments and returns values makes it testable
This is exactly the "separation of concerns" that matters in real work

Unit testing (pytest)

Topic	Key takeaway
Position	`pytest` corresponds to Java's `JUnit`
Exception tests	`with pytest.raises(...)` corresponds to `assertThrows(...)`
Coverage	Covering normal, boundary, and error cases is the baseline
Value	When a test fails, it can also reveal a wrong expectation

Project structure

Putting __init__.py in tests/ resolves pytest's import
requirements.txt can list "direct deps only" or "pin everything." When reproducibility matters, list everything

Reflection

I built this the same way as before: write the code myself and have AI review it. As my first Python project, three things stood out.

The habit of thinking in types carried straight over: The "think in types first" I repeated in the TypeScript series came naturally with Python's type hints. There's the difference that they're not enforced at runtime, but understanding the goal — "write them for the reader and the IDE" — was a real gain.

Separation of concerns transcends the language: Extracting the calculation logic as a pure function made the tests surprisingly easy to write. "Separate I/O from logic" works the same way in TypeScript and in Python.

The experience of a test failing is itself a lesson: Recomputing and fixing my own expectation taught me that "a test isn't just a tool for doubting the implementation." Separating whether a failure comes from the implementation or the expectation was the most satisfying part.

The ex-Java habits (// comments, isdigit()) did surface, but I corrected them along with the reasons, so I should be able to leave them behind for the next Python project.

Wrapping Up

This was my record of building a weight tracker CLI in Python, centered on type hints, pure functions, and pytest — my first article in the Python series.

Continuous progress from the TypeScript series:

Picked up Python basics while staying aware of the differences from Java (#, def, snake_case, tuple multiple returns)
Wrote type hints while understanding that they're not enforced at runtime
Extracted the calculation logic as a pure function, practicing separation of concerns in Python too
Covered normal, boundary, and error cases with pytest
Found and fixed a wrong test expectation myself, experiencing the same cycle as real work

Next, I want to move into persistence with file saving and JSON, and graduate from this project's "data disappears when you exit" simplification.

The full learning log is in the repository:

weight_tracker_py / LEARNING_LOG.md

This article is part of my public learning journey using AI tools (Claude Pro / Cursor Pro). The thinking and all code are mine; I collaborate with AI on the writing (structure, drafting, translation) and verify every line before publishing.

Building an HTTP Client CLI for Your Own API with TypeScript — FastAPI, POST, and Error Handling

Uya — Sun, 07 Jun 2026 13:32:28 +0000

Introduction

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

In my previous article, I built a CLI that calls an external weather API (Open-Meteo) with fetch, and learned about async/await, response type definitions, and error handling with response.ok. But that was "read-only (GET)" against "someone else's API." This time I go a step further: I build the API server myself and then build an HTTP client that calls it.

Backend: a REST API server built with FastAPI (Python)
Client: a TypeScript CLI that calls that API

What I focused on this time:

Implementing GET and POST with fetch (previously GET only)
The Content-Type: application/json header on POST (a 422 error I fixed myself)
How where you place try-catch changes behavior (continue vs. exit)
The difference between return and throw error (close to Java's throws)
Narrowing the unknown type with error instanceof Error
FastAPI basics (Spring-like decorators, BaseModel, HTTPException)

Same as always — I write honestly about where I got stuck, what I thought through, and what I asked AI for.

📝 Scope of this article

This article centers on the TypeScript client. The Python (FastAPI) side is introduced compactly, as "the thing the client calls."

My Learning Style (AI Transparency)

💡 Learning companions

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

My rules:

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

Pick a menu option in the CLI, and it gets a list of items, gets an item by ID, or adds an item — all against my own API server.

Custom API Call CLI tool
================================
1. Get all items
2. Get item by ID
3. Add an item
4. Exit
================================
Choose: 1
[
  { id: 1, name: 'apple', price: 100 },
  { id: 2, name: 'banana', price: 200 },
  { id: 3, name: 'cherry', price: 300 }
]

Data is held in memory on the server, so it resets when the server restarts (a deliberate simplification for local learning).

📦 Repositories

Client (TypeScript): https://github.com/uya0526-design/simple_api_ts
Server (Python / FastAPI): https://github.com/uya0526-design/simple_api_py

System Overview

This project is split across two repositories. The roles are simply "server and client."

[ TypeScript CLI ]  --- HTTP (fetch) --->  [ FastAPI server ]
  simple_api_ts                              simple_api_py
  - GET  /items                              - holds items in memory
  - GET  /items/{id}                         - accepts GET / POST
  - POST /items                              - returns 404 via HTTPException

The endpoint spec:

Method	Path	Description
GET	`/items`	Returns all items
GET	`/items/{id}`	Returns one item (404 if not found)
POST	`/items`	Adds an item (id auto-assigned by the server)

Backend: FastAPI Server (Python)

First I need something to call. This was my first time touching FastAPI, but to an ex-Java engineer's eyes it looked remarkably close to a Spring Boot controller.

Setup

python -m venv venv               # project-local isolated environment
.\venv\Scripts\Activate.ps1       # activate (Windows PowerShell)
pip install fastapi uvicorn       # install packages
pip freeze > requirements.txt     # record dependencies
uvicorn main:app --reload         # start the dev server

I understood venv as "per-project isolation," close to a Maven local repository or Node's node_modules, and uvicorn main:app --reload as the dev server equivalent of TypeScript's ts-node.

Implementing the endpoints

Routes are defined in main.py. The decorator feel is just like Spring.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

# internal / response use (has id)
class Item(BaseModel):
    id: int
    name: str
    price: int

# request-receiving use (no id — auto-assigned by server)
class ItemCreate(BaseModel):
    name: str
    price: int

items = [
    Item(id=1, name="apple", price=100),
    Item(id=2, name="banana", price=200),
    Item(id=3, name="cherry", price=300),
]

@app.get("/items")
def get_items():
    return items

@app.get("/items/{item_id}")
def get_item(item_id: int):
    for item in items:
        if item.id == item_id:
            return item
    raise HTTPException(status_code=404, detail="Item not found")

@app.post("/items")
def create_item(item: ItemCreate):
    new_id = len(items) + 1
    new_item = Item(id=new_id, name=item.name, price=item.price)
    items.append(new_item)
    return new_item

Splitting RequestDTO and ResponseDTO

The main design decision was separating the receiving type (ItemCreate) from the internal/return type (Item).

ItemCreate: only name and price. No id (the client shouldn't send it)
Item: includes id. The server assigns it

Avoiding "id can go in either one" and making each type's responsibility clear — I realized this is the same idea as separating RequestDTO and ResponseDTO in Java.

Java mapping (FastAPI to Spring)

FastAPI / Python	Equivalent Java concept
`@app.get("/items")`	`@GetMapping("/items")`
`@app.post("/items")`	`@PostMapping("/items")`
`{item_id}` path parameter	`@PathVariable`
`BaseModel`	DTO class
`item: ItemCreate` (typed argument)	`@RequestBody`
`HTTPException`	`ResponseStatusException`
`raise`	`throw`
`len(items)`	`.size()`
`uvicorn main:app --reload`	`ts-node`
`/docs` (auto Swagger UI)	manual setup like SpringFox

The biggest surprise was that just visiting /docs auto-generates a Swagger UI — coming from setting that up by hand, that felt like magic.

That's the server done. Now for the main event: the TypeScript client.

Client: TypeScript CLI

types.ts — Mirror the server's types

The client types mirror the server's DTOs. Dropping id from ItemCreate follows the same reasoning.

export interface Item {
  id: number;
  name: string;
  price: number;
}

export interface ItemCreate {
  // no id — the server auto-assigns it
  name: string;
  price: number;
}

📝 An interface closes with }, not };

At first I wrote the end of the interface as };. The correct form is } (watch the difference from a class or a function expression). The trailing ; on properties works with or without it, but by TypeScript convention it's common to include it.

api.ts — GET and POST with fetch

Previously I only did GET; this time I add POST too.

import { Item, ItemCreate } from "./types";

const API_ENDPOINT = "http://localhost:8000";

export async function getItems(): Promise<Item[]> {
  const response = await fetch(`${API_ENDPOINT}/items`);
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  return await response.json();
}

export async function getItemById(id: number): Promise<Item> {
  const response = await fetch(`${API_ENDPOINT}/items/${id}`);
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  return await response.json();
}

export async function createItem(inputItem: ItemCreate): Promise<Item> {
  const response = await fetch(`${API_ENDPOINT}/items`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(inputItem),
  });
  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }
  return await response.json();
}

Two things I improved from AI feedback.

1. Collect the base URL into a constant

At first I hardcoded "http://localhost:8000" in all three functions. I pulled it into a single const API_ENDPOINT to make changes easier.

2. The POST body is fine as JSON.stringify(inputItem)

At first I expanded the fields: JSON.stringify({ name: inputItem.name, price: inputItem.price }). But since inputItem is the ItemCreate type and is guaranteed to hold only name and price, JSON.stringify(inputItem) is enough. The type makes the code shorter — a nice example.

index.ts — Interactive menu and input validation

I wrap readline in a Promise and run a menu loop with while (true) + switch (an application of what I built up in previous projects).

const id = await askQuestion("Enter ID: ");
if (isNaN(parseInt(id))) {
  console.log("Please enter a number");
  continue;
}

The important part here is where to place try-catch (more below). In "get item by ID" (case "2"), the CLI was exiting entirely when the server returned 404, so I added try-catch inside the case to keep the loop going.

case "2": {
  const id = await askQuestion("Enter ID: ");
  if (isNaN(parseInt(id))) {
    console.log("Please enter a number");
    break;
  }
  try {
    const item = await getItemById(parseInt(id));
    console.log(item);
  } catch (error) {
    if (error instanceof Error && error.message.includes("404")) {
      console.log("Item not found");
    } else {
      console.error(error);
      throw error; // delegate unexpected errors to main().catch()
    }
  }
  break;
}

api.test.ts — Mocking fetch (success and failure)

Seven tests total. I reuse jest.spyOn(global, "fetch") from last time. This time, for the failure case, I used mockRejectedValue to reproduce fetch itself failing.

test("throws when the API returns an error", async () => {
  jest.spyOn(global, "fetch").mockRejectedValue(new Error("network error"));
  await expect(getItems()).rejects.toThrow();
});

afterEach(() => {
  jest.restoreAllMocks();
});

For the add (POST) test, I compared the count (length) before and after to confirm exactly one item was added.

 PASS  src/__tests__/api.test.ts

Test Suites: 1 passed, 1 total
Tests:       7 passed, 7 total
Time:        0.248 s

💡 Unit vs. integration tests

Tests that complete with mocks are "unit tests"; tests that need the actual FastAPI server running are "integration tests." Right now they share a single describe block, but as things grow, splitting them into unit/ and integration/ folders makes them easier to manage.

What I Asked AI For

Topic	What AI helped with
Spec clarification	Surfacing missing and unclear requirements
Design suggestion (Python)	Explaining why to split `ItemCreate` and `Item`
Concept explanation (Python)	Explaining `venv`, `pip`, `uvicorn`, `HTTPException` vs Java/TS
404 exit bug	Caught that `case "2"` had no try-catch, so errors reached `main().catch()` and exited
Error message branching	Suggested `error.message.includes("404")` to show "not found"
return vs throw	Suggested re-throwing with `throw error` instead of `return` on unexpected errors
Base URL collection	Suggested pulling the three hardcoded URLs into an `API_ENDPOINT` constant
Body simplification	Suggested simplifying to `JSON.stringify(inputItem)`
interface syntax	Caught the trailing `};` that should be `}`

Note: I found and fixed the 422 error (below) myself.

Where I Got Stuck

1. A 422 error on POST (the Content-Type header)

Situation: When adding an item (POST), the server returned 422 (Unprocessable Entity).

Root cause: My fetch POST didn't set the Content-Type: application/json header. Without it, FastAPI can't interpret the request body as JSON and returns 422.

// ❌ no header — the body can't be read as JSON → 422
await fetch(`${API_ENDPOINT}/items`, {
  method: "POST",
  body: JSON.stringify(inputItem),
});

// ✅ declare the Content-Type
await fetch(`${API_ENDPOINT}/items`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(inputItem),
});

Takeaway: I reached the cause on my own. A server and a client only agree to "exchange JSON" once that's declared via the header. I never thought about this while writing GET-only code.

2. The CLI exits entirely on a 404

Situation: Entering a non-existent ID exited the CLI with no error message at all.

Root cause: The exception thrown by getItemById wasn't caught inside the switch and propagated all the way to main().catch(). Since main().catch() is the last line of defense that ends the program, the loop couldn't resume and the CLI fell over.

// ❌ no catch in the case → the exception reaches main().catch() and exits
case "2": {
  const item = await getItemById(parseInt(id)); // 404 throws → loop breaks → exit
  console.log(item);
  break;
}

I added try-catch inside case "2", showing "Item not found" for 404 and continuing the loop (code shown earlier).

Takeaway: Where you catch a thrown error decides whether the program continues or exits. The same exception leads to a different user experience depending on where you place the catch.

3. The difference between `return` and `throw error`

Situation: On unexpected errors, I first exited main with return. That quietly ended the program normally, and I couldn't tell what had happened.

Root cause and fix: return just ends main normally. Logging with console.error(error) and then re-throwing with throw error lets it reach main().catch() and end with process.exit(1) (abnormal exit).

// normal exit. no error detail remains
return;

// abnormal exit. delegate to main().catch() → process.exit(1)
console.error(error);
throw error;

Takeaway: This felt close to delegating an exception upward with Java's throws. Choosing deliberately between "swallow it" and "throw it up" matters.

What I Learned

async/await and fetch (GET / POST)

POST specifies method, headers, and body. The body is stringified with JSON.stringify(...)
Sending JSON to FastAPI requires Content-Type: application/json (without it, 422)
For both GET and POST, you detect errors yourself with !response.ok and throw

Error handling

Topic	Key Takeaway
try-catch placement	Where you catch decides whether the program continues or exits
`error instanceof Error`	A caught `error` is `unknown`. Narrow the type before using `.message`
`return` vs `throw error`	`return` exits normally. `throw error` delegates to `main().catch()` for an abnormal exit. Close to Java's `throws`

Letting types simplify code

Since the ItemCreate type is guaranteed to hold only name and price, JSON.stringify(inputItem) sends it as-is. No need to expand the fields by hand

FastAPI / Python (first contact)

Topic	Key Takeaway
Decorators	`@app.get` / `@app.post` correspond to Spring's `@GetMapping` / `@PostMapping`
`BaseModel`	Defines request/response data structures. Equivalent to a Java DTO
`HTTPException`	An exception with a status code. Equivalent to `ResponseStatusException`
RequestDTO/ResponseDTO split	`ItemCreate` (no id) and `Item` (with id) separate the responsibilities
`/docs`	Just visiting it auto-generates a Swagger UI

Test design

Tests that complete with mocks are unit tests; those needing a running server are integration tests
A POST test can confirm the add by comparing the count (length) before and after

Reflection

I built this the same way as before: write the code myself and have AI review it. The big difference from last time was that I built the "other side" of the API myself.

Three things stood out:

A server and a client are connected by a "contract": The 422 error came down to declaring "this is JSON" via the Content-Type header before FastAPI would understand it. Building both sides myself made that boundary agreement tangible.

Exceptions are a design choice about "where to catch": The 404-exit incident showed me that try-catch placement directly shapes the user experience. The return vs throw error distinction also clicked, connecting back to my memory of Java's throws.

FastAPI looked like Spring: Decorators, DTOs, exception classes, auto-docs. It was rewarding to feel my past Java experience working as a foundation even in a new language.

Wrapping Up

This was my record of building a self-made FastAPI server and a TypeScript HTTP client CLI that calls it.

Progress since the previous projects:

Implemented not just GET but POST with fetch (Content-Type, body)
Found and fixed the cause of a 422 error myself
Understood that try-catch placement changes behavior, and made a CLI that doesn't fall over on 404
Used return and throw error deliberately
Built the server side with FastAPI too, understanding both ends of the API

Building both ends of an API once gave me both perspectives — "the server as seen from the client" and "the client as seen from the server." Next, I want to build on this setup and move toward more practical data operations and persistence.

Full learning logs are in each repository:

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 Weather API CLI with TypeScript — async/await, fetch, and Response Types

Uya — Sat, 06 Jun 2026 01:32:45 +0000

Introduction

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

In my previous article, I built a Quiz CLI and learned about enum, tuple types, and mocking an entire module with jest.mock(). This time, I built a Weather API CLI and focused on:

Calling an external API asynchronously with async/await and fetch
Describing an API response with type definitions (type to model the JSON shape)
HTTP error handling with response.ok
Extracting object key types with keyof typeof
Swapping out fetch with jest.spyOn(global, "fetch")
Verifying structure and type at once with toMatchObject + expect.any()

Same as always — I write honestly about where I got stuck, what I thought through, and what I asked AI for.

My Learning Style (AI Transparency)

💡 Learning companions

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

My rules:

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 weather tool. Pick a city, or enter a latitude and longitude, and it shows the current weather, temperature, humidity, and wind speed.

Weather API Call CLI
================================================
1. Select a city and run
2. Enter latitude and longitude and run
3. Exit
Choose: 1
1. Sapporo
2. Sendai
3. Tokyo
4. Nagoya
5. Osaka
6. Fukuoka
7. Kagoshima
8. Naha
Choose a city: 3
Tokyo weather: Partly cloudy
Tokyo temperature: 20.4°C
Tokyo humidity: 80%
Tokyo wind speed: 3.1km/h
================================================

Weather data comes from the free Open-Meteo API (no API key required).

📦 Repository: https://github.com/uya0526-design/weather_api

Project Structure

weather_api/
├── src/
│   ├── index.ts             # Entry point / CLI menu
│   ├── api.ts               # API call logic
│   ├── types.ts             # Type definitions
│   └── __tests__/
│       └── api.test.ts      # Unit tests
├── jest.config.js
├── tsconfig.json
└── package.json

Same three-layer structure as the previous projects: types.ts (types) / api.ts (logic) / index.ts (UI). New this time: communicating with an external API is the main event.

Tech Stack

TypeScript
Node.js (readline and fetch)
Jest + ts-jest (unit testing)
Open-Meteo API (weather data)

What I Implemented Myself

types.ts — API Response Types

The heart of the type design this time was how to express an API response as a type.

First, define the "city data"

I defined the list of selectable cities and their latitude, longitude, and timezone.

// List of selectable cities
export const cityList = [
  "Sapporo", "Sendai", "Tokyo", "Nagoya",
  "Osaka", "Fukuoka", "Kagoshima", "Naha",
];

// Latitude / longitude / timezone per city
export const cityCoordinates = {
  "Tokyo": {
    latitude: 35.68123,
    longitude: 139.76712,
    timezone: "Asia/Tokyo",
  },
  // ...
};

The quietly useful tool here is keyof typeof. It lets me pull out just the keys of cityCoordinates (the city names) as a type.

type CityName = keyof typeof cityCoordinates;
// becomes a union type: "Sapporo" | "Sendai" | "Tokyo" | ...

In Java I'd define the cities as an enum. In TypeScript I can reuse the keys of an object that already exists directly as a type — that felt fresh.

Define the API response type

This was the main challenge. I called the API first, checked the actual response JSON, and modeled that shape directly with type.

export type WeatherResponse = {
  latitude: number;
  longitude: number;
  timezone: string;
  timezone_abbreviation: string;
  current_units: {
    temperature_2m: string;
    relative_humidity_2m: string;
    weather_code: string;
    wind_speed_10m: string;
  };
  current: {
    time: string;
    interval: number;
    temperature_2m: number;
    relative_humidity_2m: number;
    weather_code: number;
    wind_speed_10m: number;
  };
};

⚠️ A type that didn't match reality

At first I defined temperature_2m and the other fields inside current as string. Looking at the actual API response, they're numbers, so number is correct — and AI caught this for me (more below). A wrong type definition leads to runtime errors, so I felt firsthand how important it is to check the type against the real response.

Convert weather codes to text

Open-Meteo returns WMO (World Meteorological Organization) weather codes as numbers. I defined a mapping to convert them to readable text.

export const WeatherCode = {
  0: { name: "Clear" },
  1: { name: "Mainly clear" },
  2: { name: "Partly cloudy" },
  3: { name: "Cloudy" },
  45: { name: "Fog" },
  // ...
  95: { name: "Thunderstorm" },
};

📝 I first tried writing this as an enum

I originally went for enum, but I decided on my own that a "code → text" mapping reads more naturally as a const object than as an enum. An enum is "a named set of constants," while an object is "a key-to-value mapping" — the difference in purpose started to feel intuitive.

At this point I had written the keys as the string "0", which didn't line up with the numeric weather_code from the API, so I fixed them to the numeric key 0 (also an AI catch).

api.ts — Async API Calls with fetch

The getWeather function takes a latitude, longitude, and timezone, and calls the API.

export async function getWeather(
  latitude: number,
  longitude: number,
  timezone: string | undefined,
): Promise<WeatherResponse> {
  const params = new URLSearchParams({
    latitude: String(latitude),
    longitude: String(longitude),
    current: "temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m",
  });
  if (timezone) {
    params.append("timezone", timezone);
  }

  const url = `https://api.open-meteo.com/v1/forecast?${params.toString()}`;
  const response = await fetch(url);

  if (!response.ok) {
    throw new Error(`API error: ${response.status}`);
  }

  return await response.json();
}

Two key points.

1. Detect HTTP errors with response.ok

fetch does not throw on HTTP errors like 404 or 500 — response.ok just becomes false (this differs from how some Java HTTP clients behave). So I have to check if (!response.ok) myself and throw.

2. Branch when timezone is undefined

In the flow where you enter latitude/longitude directly, there may be no timezone, so I branch to leave it out of the query in that case.

index.ts — Wrapping readline in a Promise

I adopted the async/await wrapping I learned in the previous Quiz project, from the start this time.

function askQuestion(prompt: string): Promise<string> {
  return new Promise((resolve) => {
    rl.question(prompt, (answer) => {
      resolve(answer);
    });
  });
}

This lets me write await askQuestion(...) top-to-bottom inside the while (true) menu loop.

In the latitude/longitude input flow, I added validation with isNaN and a range check.

const lat = Number(await askQuestion("Enter latitude: "));
if (isNaN(lat) || lat < -90 || lat > 90) {
  console.log("Latitude must be a number between -90 and 90");
  continue;
}

The weather code is converted to text by looking it up in WeatherCode.

const code = weather.current.weather_code;
const weatherName = WeatherCode[code as keyof typeof WeatherCode]?.name ?? "Unknown";

And rather than hardcoding the units, I pull them from the API response's current_units (another point improved from an AI catch).

console.log(`${city} temperature: ${weather.current.temperature_2m}${weather.current_units.temperature_2m}`);
console.log(`${city} wind speed: ${weather.current.wind_speed_10m}${weather.current_units.wind_speed_10m}`);

Finally, main().catch() catches any unexpected errors in one place.

api.test.ts — Mocking fetch

The highlight of testing this project was mocking fetch.

Success case: hit the real API and check

test("can fetch the weather for Tokyo", async () => {
  const result = await getWeather(35.68, 139.76, "Asia/Tokyo");
  expect(result).toMatchObject({
    latitude: expect.any(Number),
    longitude: expect.any(Number),
    current: {
      temperature_2m: expect.any(Number),
      weather_code: expect.any(Number),
    },
  });
});

Using toMatchObject + expect.any(Number) verifies not just that a field exists, but that its type matches — all at once. I first wrote this with toBeDefined() only, but that would pass even if the type was off, so I improved it.

Failure case: swap fetch for a mock

I can't conveniently produce a broken API for the error path, so I swap fetch for a mock.

test("throws when the API returns an error", async () => {
  jest.spyOn(global, "fetch").mockResolvedValue({
    ok: false,
    status: 500,
  } as Response);

  await expect(getWeather(35.68, 139.76, "Asia/Tokyo")).rejects.toThrow("API error");
});

afterEach(() => {
  jest.restoreAllMocks();
});

Last time, fs couldn't be patched with jest.spyOn and needed jest.mock(), but global.fetch can be swapped with jest.spyOn(global, "fetch"). The lesson from last time — that which approach works depends on the target's property descriptor (configurable) — carried over directly.

💡 Cleanup belongs in afterEach

I first wrote jest.restoreAllMocks() inside the test body, but if the test fails it never reaches that line and the mock stays in place. I moved it into afterEach so cleanup runs whether the test passes or fails.

Test results:

 PASS  src/__tests__/api.test.ts

Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Time:        1.216 s

What I Asked AI For

Topic	What AI helped with
Spec clarification	Identified unclear and missing requirements up front
Type fix	Caught numeric fields inside `current` typed as `string`
Hardcoded units	Suggested reading units from `current_units` instead of fixing them to m/s
Weather code key mismatch	Caught string key "0" not matching the numeric `weather_code`
Unused import removal	Removed `WeatherResponse` that wasn't used in `index.ts`
Test type verification	Improved from `toBeDefined()` to `toMatchObject` + `expect.any()`
Mock cleanup	Suggested moving `restoreAllMocks()` into `afterEach`
Peer dependency check	Showed how to use `npm info` with `peerDependencies` to check a package

Where I Got Stuck

1. I typed numeric response fields as string

Situation: Inside current on WeatherResponse, I defined temperature_2m and others as string.

Root cause: Looking at the actual API response, temperature, humidity, weather code, and wind speed are all numbers. The units (°C, %, etc.) live separately in current_units as strings — I was conflating the two.

// ❌ a number, but defined as string
current: {
  temperature_2m: string;
};

// ✅ numbers are number
current: {
  temperature_2m: number;
};

Takeaway: Check type definitions against the real API response. Deciding "this feels string-ish" leads to a runtime mismatch — an obvious lesson I learned the hard way.

2. I hardcoded the units

Situation: I wrote the wind speed unit as "m/s" directly in the code.

Root cause: Open-Meteo actually returns wind speed in km/h. Hardcoding it would make the display a lie. And since the API returns the units in a current_units field, using that is the right answer.

// ❌ unit fixed in code
console.log(`wind speed: ${weather.current.wind_speed_10m}m/s`);

// ✅ use the unit the API returns
console.log(`wind speed: ${weather.current.wind_speed_10m}${weather.current_units.wind_speed_10m}`);

Takeaway: Don't hardcode units or config values — pulling them from the data source is more resilient to spec changes. I aligned temperature and humidity to the same approach.

3. The weather code keys didn't match because they were strings

Situation: I wrote the WeatherCode keys as the strings "0" and "1".

Root cause: The API's weather_code comes back as a number. When looking it up with WeatherCode[weather_code], the keys need to be defined as numbers or the lookup won't work as intended.

// ❌ string keys
export const WeatherCode = {
  "0": { name: "Clear" },
};

// ✅ numeric keys (match the numeric weather_code from the API)
export const WeatherCode = {
  0: { name: "Clear" },
};

Takeaway: Match "the key type" to "the type you look it up with." Object keys can look similar but are different things as numbers vs. strings — a good reminder.

4. AI's suggestions aren't always correct

This was less a sticking point and more a turning point in how I learn.

During development, AI flagged that "the combination of jest ^30 and ts-jest ^29 may have a version mismatch." Rather than taking it at face value, I checked it myself with npm info.

npm info ts-jest peerDependencies
# result: jest: '^29.0.0 || ^30.0.0'

ts-jest supports both jest 29 and 30, so in reality there was no problem.

Takeaway: AI suggestions are just hints. When I can confirm a fact with a command, I confirm it myself. I want to build the habit of "verify and then decide" rather than "fix it because AI said so."

(Side note: npm install brings each package to its latest version independently, so combined versions can drift. But npm installs them anyway without erroring, which makes it easy to miss — learning that I can check ahead of time by running npm info against a package's peerDependencies was a real gain.)

What I Learned

async/await and fetch

Writing await fetch(url) inside an async function lets you write async code top-to-bottom, sequentially
fetch does not throw on HTTP errors — you check response.ok yourself
response.json() extracts the response body as JSON
Some Java HTTP clients throw depending on the status code, so this needed a mental shift

TypeScript Types

Topic	Key Takeaway
Response type definition	You can model each JSON field with `type`. Choosing `number` vs `string` matters
`keyof typeof`	Extracts an existing object's keys as a type. I auto-generated a union of city names
Numeric vs string keys	Object keys differ as numbers vs strings. Match them to the lookup type

Jest Mocking

Topic	Key Takeaway
`jest.spyOn(global, "fetch")`	Swaps the global `fetch` for a mock
`mockResolvedValue`	Creates a mock that returns a Promise (for mocking async functions)
`rejects.toThrow()`	Verifies that an async operation throws
`toMatchObject` + `expect.any()`	Verifies structure and type at once — stricter than `toBeDefined()`
Cleanup in `afterEach`	Mocks reliably reset even when a test fails. Equivalent to Java's `@AfterEach`

Design

Don't hardcode units and config values — pulling them from the data source is more resilient to spec changes
Remove unused imports (readability and maintainability)
Tests should be written with "what am I verifying" in mind, not just "does it run"
Verify AI's suggestions with commands — don't take them at face value

Reflection

I built this with the same style as before: write the code myself and have AI review it.

Three things stood out:

Check type definitions against the real response: Mixing up string and number was a mistake the actual JSON would have prevented. "Look at the real thing, then write the type" is more reliable than "imagine the type first."

A sense for avoiding hardcoding: Pulling units from the API made me pause the next time I felt the urge to hardcode a value.

Use AI, but confirm it yourself in the end: Verifying the version-mismatch flag with npm info myself was my biggest gain this time. AI is convenient, but I want to keep the initiative on fact-checking.

Wrapping Up

This was my record of building an external API tool (a weather CLI) as a TypeScript beginner.

Progress since the previous projects:

Called an external API asynchronously with async/await and fetch
Modeled the API response structure accurately with type (choosing number/string)
Used keyof typeof to leverage object keys as a type
Mocked fetch with jest.spyOn(global, "fetch")
Built the habit of verifying AI's suggestions myself with npm info

Next up: a simple HTTP client that calls my own API (FastAPI), going deeper on async/await and type definitions.

Full learning log: 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.

Self-Host Your GitHub Stats Badge on Vercel — Fixing the 'Broken Image' on Your Profile README

Uya — Thu, 04 Jun 2026 12:42:49 +0000

🌐 This is the English version of an article I originally wrote in Japanese on Zenn. The original is linked as the canonical source.

Introduction

You've probably seen that "GitHub Stats" card (github-readme-stats) on a lot of profile READMEs. Ever pasted it in, only to get a broken image? I have.

I touched on this problem in my previous article, but the fix — self-hosting — has enough steps that I split it into its own post.

💡 The background (why it breaks in the first place) is covered in the previous article. Worth reading alongside this one.
👉 I Built a GitHub Profile README — the 'It Won't Show Up' Traps and Tips to Stand Out

In this article, I'll walk through how to self-host github-readme-stats on your own Vercel account so it renders reliably, along with the points that are easy to trip over.

Why self-hosting is needed

The official instance of github-readme-stats (github-readme-stats.vercel.app) is shared by many users. Because of that, it easily hits the free-tier API limits, and during busy periods the image won't render (it returns 503 SERVICE_UNAVAILABLE / DEPLOYMENT_PAUSED).

This isn't a problem on your side — it's a known issue that happens intermittently due to the shared service. If you self-host, you get your own dedicated instance, so you no longer depend on someone else's quota and it renders reliably.

💡 Assume that badges depending on external services will go down someday. For the important ones, self-hosting is the most reassuring option in the end.

Background terms

Before the steps, here's a quick rundown of the terms that come up.

Term	Description
Vercel	A cloud deploy / hosting platform for frontend apps
Hobby plan	The free plan for personal, non-commercial use. Fine for portfolio purposes
Serverless function	A function that runs only on request instead of a server running constantly. Vercel uses this to generate the image dynamically
Environment variable	A config value passed in safely from outside instead of hard-coded. Here it holds the GitHub API token
Fork	Copying someone else's GitHub repository into your own account

Steps

The overall flow is six steps: register on Vercel → fork the repo → get a token → deploy → check the URL → embed in your README.

1. Create a Vercel account

Go to https://vercel.com/signup
Choose "Continue with GitHub" to link your GitHub account
For the plan, choose "Hobby"
If asked for phone verification, enter it in international format (for Japan, choose +81 and drop the leading 0)

Gotcha: the "The user could not be found" error

Even with a correctly entered phone number, you may get this error. It seems to be a known issue on Vercel's side.

Fix: Submit the form at https://vercel.com/accountrecovery to contact support. Example for the "Additional Details" field:

I tried to sign up via GitHub and was asked to verify my phone number. I entered my mobile number but received the error message "The user could not be found." I have tried re-entering the number multiple times but the issue persists. This is a new account and the phone number has not been used with any other Vercel account.

2. Fork the repository

Go to https://github.com/anuraghazra/github-readme-stats
Click the "Fork" button at the top right
Confirm it's been forked into your own GitHub account

3. Get a GitHub Personal Access Token

This is needed so github-readme-stats can call the GitHub API.

Go to https://github.com/settings/tokens
Click "Generate new token" → "Generate new token (classic)"
Settings:
- Note: anything (e.g. vercel-readme-stats)
- Expiration: No expiration (or any period you like)
- Select scopes: check public_repo (use repo if you also want to count private repositories)
Click "Generate token"
Copy and save the token shown (the string starting with ghp_)

⚠️ Security note: The token is only shown once — once you close this screen it's gone, so be sure to save it. Also, never write the token directly in your code or README; pass it only as a Vercel environment variable in the next step, and don't leak it.

4. Deploy to Vercel

Go to https://vercel.com/new
From the Import Git Repository list, select github-readme-stats and click "Import"
Open the "Environment Variables" section and add the following:

| Key | Value |
| :--- | :--- |
| PAT_1 | The token from step 3 (the string starting with ghp_) |

Leave the other settings at their defaults and click "Deploy"
When the "Congratulations!" screen appears, the deployment is done

5. Check the deploy URL

Back on the dashboard, two kinds of URL are shown. The one you use is the fixed URL, so be careful not to mix them up.

URL	Use
The URL in the Domains field (e.g. `github-readme-stats-xxx-yyy.vercel.app`)	The fixed production URL. Use this one
The long URL in the Deployment field (e.g. `github-readme-stats-aabbccddee-xxx.vercel.app`)	A temporary URL that changes per deploy. Don't use it

To verify, open the following in a browser; if the Stats card appears, you're good.

https://[your Domains URL]/api?username=[your GitHub username]

6. Embed it in your README

Add the following to your profile README.md, using your own Domains URL.

![GitHub Stats](https://[your Domains URL]/api?username=[username]&show_icons=true&hide_border=true&count_private=true)
![Top Languages](https://[your Domains URL]/api/top-langs/?username=[username]&layout=compact&hide_border=true)

Now the Stats card renders from your own dedicated instance, unaffected by the congestion on the official one.

Common customization options

You can tweak the look and what's counted via URL query parameters. Here are the ones I use most.

Option	What it does	Example
`&theme=`	Theme color	`radical`, `dark`, `tokyonight`, `merko`
`&show_icons=true`	Show icons	—
`&hide_border=true`	Hide the border	—
`&count_private=true`	Also count private repositories	—
`&hide=`	Hide specific items	`&hide=issues,contribs`
`&layout=compact`	Compact layout for the language card	for top-langs

Hobby plan limits and caveats

For this use case (just showing it on your own README), traffic is extremely low, so the Hobby plan is plenty. Still, keep these in mind:

Serverless function execution limit: 10 seconds (it could rarely time out if the GitHub API is slow to respond, but in practice it's almost never an issue)
Bandwidth: 100 GB/month (nowhere near reachable for personal use)
No commercial use (ads, paid services, etc. require the Pro plan)

Wrap-up

The broken-image problem with github-readme-stats is usually caused by "the official instance being paused" — not a mistake on your side. Even so, putting something that might go down at any time on the face of your profile is unsettling, so I recommend self-hosting to get your own dedicated instance.

To recap the steps:

Register on Vercel (Hobby plan is enough)
Fork github-readme-stats
Get a GitHub Personal Access Token (public_repo)
Put the token in the PAT_1 environment variable and Deploy
Note the fixed Domains URL
Swap your README's image URL for your own Domains URL

Six steps in total. Once you've done it, it just keeps working reliably.

You can see my card in action on my profile 👉 github.com/uya0526-design

Thanks for reading.

References

I Built a GitHub Profile README — the 'It Won't Show Up' Traps and Tips to Stand Out

Uya — Thu, 04 Jun 2026 12:21:49 +0000

🌐 This is the English version of an article I originally wrote in Japanese on Zenn. The original is linked as the canonical source.

Introduction

I usually write "I built a small CLI tool in TypeScript / Python" style posts. This time it's a bit different: a write-up about building my GitHub profile README.

I'm an engineer who spent 15+ years mostly on legacy Java, and I'm now learning TypeScript and Python on my own, publishing what I learn on Zenn and dev.to. Once I had a decent number of learning projects piling up, I decided it was time to build "the face of my GitHub."

Here's the conclusion up front:

Writing the README itself is not hard. You just line up Markdown and badges.
But I kept getting stuck on "it doesn't show up on my profile."
And there was a second trap: the GitHub Stats badge was broken and wouldn't render.

This post focuses on the points that are surprisingly easy to miss if you only read the official docs, using my own profile as a concrete example.

Here's the finished result 👉 github.com/uya0526-design

💡 I'm writing this for people building a profile README for the first time. If you've written repository READMEs before but never the profile one, this should be about the right level.

What is a profile README, anyway?

GitHub has two kinds of README, and it's easy to confuse them at first. Let me separate them clearly.

Type	Where it lives	Where it shows up	Role
Repository README	`README.md` inside each repo	Top of that repository	Explaining the project and how to use it
Profile README	`README.md` inside a repo named exactly like your username	Top of your profile page (`github.com/username`)	Self-introduction and the "face" of your portfolio

The key point: the profile README differs from the repository README you normally write, both in where it lives and what it's for.

The essentials of making one

The mechanism is simple. You create a repository whose name exactly matches your username, and put a README.md at its root.

Username uya0526-design → repository uya0526-design/uya0526-design
GitHub treats this repo as a "special repository"
Put README.md at the root
Make the repository Public

In theory it should now show up... and this is where I fell into the swamp.

Trap 1: the README doesn't show up

I wrote the README, pushed it, and nothing appeared on my profile. I burned a fair amount of time in this state. Let me share the final cause and a checklist for narrowing it down.

The real cause: I hadn't pressed the "Share to profile" button

This was the actual culprit in my case.

Just creating the special repository does not always auto-publish it to your profile
There's a "Share to profile" button on the repository page, and only after pressing it does the README appear on your profile
The button is subtle, and I completely missed it

✅ Takeaway: When your README won't show up even after you wrote and pushed it, first look for the "Share to profile" button on the repository page. In my case, this one action got me out of the swamp.

Checklist for when it won't show up

That said, this isn't the only possible cause. There are several easy-to-miss points. Checking them top to bottom is efficient.

Does the repository name match your username exactly?
- Watch out for mixing up hyphen - and underscore _
- Match case as well
Is the repository Public? (Private repos won't show up)
Is README.md at the root? (It won't be picked up from a subfolder)
Does the README have content? (An empty file won't show)
Is the README at the root of the default branch?
- The profile README only references the README on the "default branch"
- If you created it locally on master, pushed, and added main afterward, the default branch and the branch holding the README can end up out of sync
- Check under Settings → General → Default branch
Did you press "Share to profile"? ← my actual cause
Propagation delay / cache
- There can be a lag right after pushing. Wait a bit, or hard reload (Ctrl + Shift + R)

Number 5 is an especially easy trap for people who used master by local habit. Maybe a classic "ex-SE" mistake.

A tip for checking: view it while logged out

This one helped in a quiet but real way.

Open github.com/username in incognito / InPrivate mode
When you're logged in, the editing UI takes priority and the appearance can differ, so checking "how others see it" while logged out is the reliable way
When it's correctly reflected, the README appears large, above your Pinned repositories
- In other words, if Pinned is at the very top, the README hasn't been reflected yet

Trap 2: the GitHub Stats badge is broken

You know that "GitHub Stats" card (github-readme-stats) you often see on profile READMEs? When I pasted it in, the image turned into a broken-image icon.

The cause: the official instance was paused

When I opened the image URL directly in a browser, it returned 503 SERVICE_UNAVAILABLE / DEPLOYMENT_PAUSED.

This means the official deployment (on a free Vercel tier) is temporarily paused due to congestion or limits
Since it's a service shared by many users, this is a known issue that happens intermittently
It's not a problem on your side

In other words, my README was fine — the shared service I was riding on happened to be down.

The fix: self-host on your own Vercel

If it's a temporary outage you can just wait, but I wasn't comfortable putting something that might go down again on the "face" of my profile. So I decided to self-host on my own Vercel account. That removes the dependency on someone else's quota.

Here are just the key steps (the official repository README has the details).

Create a Vercel account (the free Hobby plan is enough for personal use)
Fork github-readme-stats to your own account
Get a GitHub Personal Access Token (classic, with the public_repo scope)
Import it into Vercel, set the token as the environment variable PAT_1, and Deploy
Note the fixed Domains URL that gets issued (not the temporary URL that changes per deploy)
Replace the image URL in your README, swapping the official instance for your own Domains URL

After swapping, the embed looks like this (replace the URL part with your own):

![GitHub Stats](https://[your Domains URL]/api?username=[username]&show_icons=true&hide_border=true&count_private=true)
![Top Languages](https://[your Domains URL]/api/top-langs/?username=[username]&layout=compact&hide_border=true)

⚠️ Security note: A Personal Access Token is shown only once — copy it before you close the screen. Never write the token directly in your code or README; pass it only as a Vercel environment variable, and don't leak it.

If you get stuck signing up for Vercel (phone verification error): When signing up via GitHub, phone verification can fail with "The user could not be found" (this seems to be a known Vercel issue). If that happens, use the form at Vercel Account Recovery to explain the situation and contact support.

You can see my self-hosted card working in the "GitHub Stats" section near the bottom of my profile.

📝 This self-hosting procedure turned out to be enough material for its own article. I plan to split out the detailed steps (with screenshots) into a separate post.

💡 Lesson: Assume that badges depending on external services will go down someday. Self-host the important ones, or place them where it isn't fatal if they break.

What to highlight: from a reskilling ex-engineer's view

Beyond just "making a working README," the real question is what you communicate to the reader (recruiters, collaborators, peers). My position is "15+ years of real experience, but modern tech is still ahead of me," so I focused on showing that honestly and attractively.

What I included

In my actual profile, I structured it roughly in this order:

Header (one-line catch + badges): years of experience, key certifications, and what I'm learning, at a glance
About Me: which domains I've worked in and for how long, plus where I am now (reskilling)
How I Learn: less abstract self-PR, more "how I actually move my hands"
Certifications: a table with dates (high credibility, easy to read)
Tech Stack: badges split into "professional experience" and "currently learning"
Featured Projects: link + tech used + what I practiced, as a set
Writing: links to Zenn / dev.to
GitHub Stats: the self-hosted version above

Ways of thinking that work for self-promotion

Four things I paid special attention to:

Concrete > abstract. "Lots of Java experience" is weaker than "15 years of enterprise Java in telecom, logistics, and finance." Specific industry names add credibility.
Separate real experience from what you're learning, honestly. Categorizing accurately without exaggeration actually builds trust. That's why I split my Tech Stack into "Professional experience" and "Currently learning & building."
Show how you learn. In my case I wrote about the process itself: "I don't let AI write my code — I implement first, then have AI review," "I design my own tests," "I don't take AI's suggestions at face value — I verify them with actual commands." Showing the process is itself a statement about your attitude as an engineer.
Stack up "finished and published" wins, however small. A pile of small projects with tests, a README, and a learning log is plain but strong.

A small trick for going bilingual

Assuming some global readers, I wrote mainly in English while folding a Japanese version into a collapsible block. That keeps an English-first layout while still being readable for Japanese speakers.

<details>
<summary>Japanese profile (click to expand)</summary>

(Japanese body goes here)

</details>

📝 GitHub READMEs support some HTML (like collapsible blocks and centered text), but behavior can vary by environment. Always check the actual rendering after publishing.

Wrap-up: a checklist for next time

Finally, a checklist for my future self (and for you, if you read this far).

[ ] Created a repository with the same name as your username (exact match)
[ ] Made it Public
[ ] Put README.md at the root of the default branch
[ ] Pressed the "Share to profile" button
[ ] Opened github.com/username in incognito mode to verify
[ ] Checked that external badges (Stats, etc.) render (self-host if not)
[ ] Wrote "real experience" and "currently learning" separately and accurately
[ ] Made the content convey your learning process and consistency

A profile README isn't something you make once and forget — it's a place to keep showing your growth. I'll keep updating Featured Projects and "Next up" as projects accumulate.

Here's the finished profile 👉 github.com/uya0526-design

Thanks for reading. I hope it helps anyone else stuck in the "it won't show up" swamp.

Building a Quiz CLI with TypeScript — enum, Tuple Types, and Jest Mocks

Uya — Tue, 02 Jun 2026 15:34:49 +0000

Introduction

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

In my previous article, I built a Household Budget CLI and learned about class, generics <T>, interface extends, and array methods like reduce, some, and find. This time, I built a Quiz CLI and focused on:

Managing choice IDs safely with enum
Constraining array length at the type level with tuple types
Replacing callback hell with async/await
Swapping out the fs module entirely with jest.mock()
Understanding when to use jest.spyOn vs jest.mock()

Same as always — I write honestly about where I got stuck, what I thought through, and what I asked AI for.

My Learning Style (AI Transparency)

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

My rules:

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 to create, edit, delete, and randomly play quiz questions stored in a JSON file.

==============================
1. Add a quiz
2. Edit a quiz
3. Delete a quiz
4. Play quizzes (3 random questions)
5. Show all quizzes
6. Exit
> 1
Enter the question: What keyword defines a type alias in TypeScript?
Enter option 1: type
Enter option 2: interface
Enter the correct answer (1 or 2): 1
Quiz added.

> 4
--- Question 1 ---
What keyword defines a type alias in TypeScript?
1: type
2: interface
Your answer (1 or 2): 1
✅ Correct!

Result: 1 / 1 correct
==============================

Quiz data is saved to a JSON file and persists between sessions.

📦 Repository: https://github.com/uya0526-design/simple_quiz

Project Structure

simple_quiz/
├── src/
│   ├── index.ts             # Entry point / CLI menu
│   ├── quiz.ts              # Business logic (QuizManager class)
│   ├── types.ts             # Type definitions
│   └── __tests__/
│       └── quiz.test.ts     # Unit tests (10 cases)
├── quizzes.json             # Persistent quiz data
├── jest.config.js
├── tsconfig.json
└── package.json

Same three-layer structure as the previous projects: types.ts (types) / quiz.ts (logic) / index.ts (UI).
New this time: JSON file persistence.

Tech Stack

TypeScript
Node.js (readline and fs modules)
Jest + ts-jest (unit testing)

What I Implemented Myself

types.ts — Type Definitions

Two key ideas drove the type design this time: enum and tuple types.

enum to name choice IDs

The quiz is always two choices. My first instinct was to use plain number, but 1 and 2 on their own carry no meaning. enum lets me give those numbers names:

export enum OptionId {
  One = 1,
  Two = 2,
}

OptionId.One is immediately readable — you know it means "the first option." Same concept as a Java enum paired with an integer value.

Tuple types to fix array length

I first typed the options array as option[]. The problem: that accepts zero items, three items, or any count — but a quiz always has exactly two choices. A tuple locks that down:

export type option = {
  id: OptionId;
  text: string;
};

export interface Quiz {
  id: number;
  question: string;
  options: [option, option]; // exactly 2 — enforced at compile time
  answer: OptionId;
}

With [option, option], TypeScript rejects anything that isn't exactly two elements. option[] couldn't prevent that — tuple types can.

quiz.ts — The QuizManager Class

I decided to separate logic into a QuizManager class and keep index.ts as pure I/O. The previous household budget project taught me that this separation makes testing much easier — same principle as a Java Service layer vs. Controller layer.

export class QuizManager {
  private quizzes: Quiz[] = [];

  constructor() {}

  loadQuizzes(): void {
    if (!fs.existsSync(FILE_PATH)) {
      fs.writeFileSync(FILE_PATH, JSON.stringify([], null, 2));
    }
    const data = fs.readFileSync(FILE_PATH, 'utf-8');
    this.quizzes = JSON.parse(data);
  }

  saveQuizzes(): void {
    fs.writeFileSync(FILE_PATH, JSON.stringify(this.quizzes, null, 2));
  }
  // ...
}

ID generation with reduce

Rather than keeping a nextId field in the stored data (which would pollute the JSON), I compute it from existing records:

private getNextQuizId(): number {
  if (this.quizzes.length === 0) return 1;
  return this.quizzes.reduce((maxId, quiz) => Math.max(maxId, quiz.id), 0) + 1;
}

Start at 0, walk through all IDs, take the max, add one. If a quiz is deleted and a new one is added, there are no ID collisions.

isQuizExists with some

isQuizExists(id: number): boolean {
  return this.quizzes.some((quiz) => quiz.id === id);
}

Guard method used before editing or deleting. some returns true if at least one element matches — Java's Stream.anyMatch(). I'd used this pattern in the budget project too, so it came naturally.

index.ts — CLI Menu

async/await to escape callback nesting

The budget project's readline callbacks were readable, but I could already see how deeper nesting would make them hard to follow. This time I wrapped readline in a Promise from the start:

function askQuestion(prompt: string): Promise<string> {
  return new Promise((resolve) => {
    rl.question(prompt, (answer) => {
      resolve(answer);
    });
  });
}

Then the main flow reads top-to-bottom:

// Callback style (nesting grows with each input)
rl.question('Question: ', (q) => {
    rl.question('Option 1: ', (o1) => {
        rl.question('Option 2: ', (o2) => {
            // ...
        });
    });
});

// async/await (reads like sequential code)
const question = await askQuestion('Enter the question: ');
const option1  = await askQuestion('Enter option 1: ');
const option2  = await askQuestion('Enter option 2: ');

It feels similar to waiting on a Java Future with .get(), but without blocking a thread.

Random question selection

const randomQuizzes = quizManager.getQuizzes()
  .sort(() => Math.random() - 0.5)
  .slice(0, 3);

sort(() => Math.random() - 0.5) is a standard shuffle idiom — the comparator returns a random positive or negative value, randomizing the sort order. .slice(0, 3) then takes the first three.

quiz.test.ts — Unit Tests with Jest

The toughest part of testing this project was mocking the fs module.

jest.spyOn vs jest.mock()

I started with jest.spyOn(fs, 'readFileSync'). Immediate error:

Cannot redefine property: readFileSync

AI explained why: Node's fs module methods have configurable: false in their property descriptors. jest.spyOn works by redefining the property — which is forbidden when configurable is false.

The fix is to replace the entire module instead of patching individual methods:

// ❌ fs methods are configurable: false — spyOn can't redefine them
jest.spyOn(fs, 'readFileSync').mockReturnValue('...');

// ✅ jest.mock() replaces the whole module — no configurable restriction
jest.mock('fs');
const mockedFs = jest.mocked(fs);

Comparison:

	`jest.spyOn`	`jest.mock()`
Scope	One method	Entire module
Requirement	`configurable: true`	No restriction
Reset	`restoreAllMocks()`	`resetAllMocks()`
Java equivalent	`Mockito.spy(realObject)`	`Mockito.mock(ClassName.class)`

Note: console.error does work with jest.spyOn because console methods are configurable: true. Whether spyOn is usable depends entirely on how the object's properties are defined — not on which module it is.

The "accidentally passing test" trap

While writing the loadQuizzes test, I used JSON.stringify([]) in my assertion. It passed. AI flagged it:

// ❌ Accidentally passes — empty arrays produce "[]" either way
expect(mockedFs.writeFileSync).toHaveBeenCalledWith(
  expect.stringContaining('quizzes.json'),
  JSON.stringify([])
);

// ✅ Matches the actual call exactly
expect(mockedFs.writeFileSync).toHaveBeenCalledWith(
  expect.stringContaining('quizzes.json'),
  JSON.stringify([], null, 2)
);

JSON.stringify([]) and JSON.stringify([], null, 2) both return "[]" for an empty array. Once data is present, the second form adds newlines and indentation — and the test would fail. "Test passes" does not mean "test is correct."

expect.stringContaining() for cross-platform paths

File paths look different on Windows (\) vs Mac/Linux (/). Rather than hardcoding a full path, I match on the filename only:

expect(mockedFs.writeFileSync).toHaveBeenCalledWith(
  expect.stringContaining('quizzes.json'),
  // ...
);

Test results:

 PASS  src/__tests__/quiz.test.ts
  loadQuizzes
    ✓ creates a new file if none exists
    ✓ loads data from an existing file
  saveQuizzes
    ✓ can save quizzes
  addQuiz
    ✓ can add a quiz
    ✓ second quiz gets ID 2
  editQuiz
    ✓ can edit a quiz
  deleteQuiz
    ✓ can delete a quiz
  isQuizExists
    ✓ returns true when the quiz exists
    ✓ returns false when the quiz does not exist
  getNextQuizId (tested indirectly via addQuiz)
    ✓ no ID collision after delete then add

Tests: 10 passed, 10 total

What I Asked AI For

Topic	What AI helped with
Spec clarification	Identified unclear and missing requirements up front
async/await explanation	Compared it to callback style and to Java's Future
Tuple type hint	Suggested changing `option[]` to `[option, option]`
Constructor issue	Caught that `private constructor` prevents external instantiation
editQuiz bug	Pointed out `map(q => q.id === id ? q : q)` does nothing
Jest error fix	Explained `Cannot redefine property` and suggested `jest.mock()`
console.error mock	Showed how to use `jest.spyOn(console, 'error')`
Path comparison	Suggested `expect.stringContaining()`
README corrections	Fixed title and tech stack description

Where I Got Stuck

1. `private constructor` prevented instantiation

Situation: Wrote private constructor() on QuizManager. Then new QuizManager() threw an error.

Root cause: private constructor is intentional — it's the pattern for preventing external instantiation (e.g., singletons). A regular class should just use constructor() (public by default).

// ❌ Can't be instantiated from outside the class
export class QuizManager {
  private constructor() {}
}

// ✅ Public constructor — the normal case
export class QuizManager {
  constructor() {}
}

Same rule applies in Java. A slip of habit.

2. editQuiz had a no-op map

Situation: After calling editQuiz, nothing changed. AI asked me to re-read the map callback.

Root cause: Both branches of the ternary returned the same value:

// ❌ Both branches return `quiz` — nothing is updated
this.quizzes = this.quizzes.map((quiz) =>
  quiz.id === id ? quiz : quiz
);

// ✅ Return the updated object when IDs match
this.quizzes = this.quizzes.map((quiz) =>
  quiz.id === id ? updatedQuiz : quiz
);

The intent was clear — the execution was wrong. The kind of bug that's invisible until you slow down and re-read the line.

3. let inside a switch case caused a scope error

Situation: let score = 0 inside case '6' caused a TypeScript error.

Root cause: switch cases share a single scope. let and const declarations in one case can conflict with those in others.

// ❌ All cases share one scope — let can conflict across cases
case '6':
  let score = 0;
  break;

// ✅ Wrap in braces to create a block scope
case '6': {
  let score = 0;
  break;
}

Wrapping in {} gives each case its own block scope. Simple fix once you know the cause.

4. console.error needed spyOn, not jest.mock()

Unlike fs, console.error works fine with jest.spyOn:

jest.spyOn(console, 'error').mockImplementation(() => {});

Because console properties are configurable: true. The lesson isn't "use jest.mock() for everything" — it's "know your target's property descriptor before choosing your approach."

What I Learned

async/await

Wrapping readline in new Promise((resolve) => { ... }) makes it await-able
async/await turns nested callbacks into sequential, top-to-bottom code
Feels like Java's CompletableFuture.get(), but non-blocking

TypeScript Types

Topic	Key Takeaway
`enum`	Gives numeric values meaningful names. `OptionId.One` beats a raw `1`
Tuple `[A, B]`	Enforces exact array length and element types at compile time
Missing `export`	Any type or class used across files needs `export` — easy to forget

Jest Mocking

Topic	Key Takeaway
`jest.spyOn()`	Works when `configurable: true` — patches a single method
`jest.mock()`	Replaces the entire module — no `configurable` restriction
`jest.mocked(fn)`	Utility that tells TypeScript a function is already mocked
`jest.resetAllMocks()`	Clears mock implementations and call history

Test Quality

A test that passes is not necessarily a correct test
JSON.stringify([]) and JSON.stringify([], null, 2) look different but both return "[]" for empty arrays
expect.stringContaining() handles OS path differences without hardcoding separators
Write tests for error paths (catch blocks), not just happy paths

Design

Separating logic (quiz.ts) from I/O (index.ts) makes the logic independently testable
Code that touches the filesystem during tests should be mocked out
Same principle as Java's Service / Controller separation

Reflection

async/await built on last project's frustration: The budget project's readline callbacks were fine, but I could see the wall coming. Starting this project with async/await from day one felt like applying a lesson before being forced to — that's a good sign.

Tuple types clicked because I had a concrete need: "This quiz must always have exactly two options" is a real constraint. Expressing that constraint as [option, option] instead of option[] felt like TypeScript doing what it's supposed to do — enforcing things so I don't have to remember them.

Understanding configurable made jest.mock() make sense: If I'd just followed "use jest.mock() for fs" as a rule, I wouldn't have known why — or when to use spyOn instead. Now I know the underlying reason, and I can apply the right tool in future situations.

"Accidentally passing" tests are dangerous: A test that passes for the wrong reason gives false confidence. After this experience, I now double-check: does this test actually verify the behavior I care about, or did I get lucky?

Wrapping Up

This was my fifth TypeScript project — a Quiz CLI with CRUD and random playback.

Progress since the Household Budget:

Used async/await to eliminate callback nesting in readline
Constrained array length with tuple types — [option, option] instead of option[]
Gave numeric IDs meaningful names with enum
Understood the configurable property descriptor and chose jest.mock() over jest.spyOn for fs
Discovered the "accidentally passing test" trap and learned to verify test correctness, not just test passage

Next up: an external API tool (weather API) to go deeper on fetch, async/await, and response type definitions.

Full learning log: 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 Household Budget CLI with TypeScript — class, Generics, and Jest

Uya — Sat, 30 May 2026 13:50:35 +0000

Introduction

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

In my previous article, I built a Todo List CLI and learned about interface, array methods, immutable patterns, and Jest's beforeEach. This time, I built a Household Budget CLI and focused on:

Organizing logic with a class (closer to how I'd write Java)
Designing a shared interface with generics <T>
Reducing duplication with interface inheritance (extends)
Using reduce / filter / some / find in real logic
Writing date and category validation from scratch
Testing class methods with Jest (13 test cases)

Same as always — I write honestly about where I got stuck, what I thought through, and what I asked AI for.

My Learning Style (AI Transparency)

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

My rules:

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 to record, edit, delete, and summarize household income and expenses.

================================================
1. Add income
2. Add expense
3. Show all records
4. Show balance summary
5. Edit income
6. Edit expense
7. Delete a record
8. Exit
> 1
Enter amount: 250000
Enter date: 2026/05/23
Choose a category from the following:
給与, 賞与, 副業, その他
Enter category: 給与
Enter description: May salary
Income added.
================================================
Household Budget
================================================
Income:
1: 250000 2026/05/23 給与 May salary
Expenses:
================================================

⚠️ Data is lost when you exit — no persistence. This is purely a learning project.

📦 Repository: https://github.com/uya0526-design/household_account

Project Structure

household_account/
├── src/
│   ├── index.ts             # Entry point / CLI menu
│   ├── account.ts           # Business logic (AccountBook class)
│   ├── types.ts             # Type definitions
│   └── __tests__/
│       └── account.test.ts  # Unit tests (13 cases)
├── jest.config.js
├── tsconfig.json
└── package.json

Same three-layer structure as before: types.ts (types) / account.ts (logic) / index.ts (UI).
The key change from the Todo project: logic moved from functions to a class.

Tech Stack

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

What I Implemented Myself

types.ts — Type Definitions

The centerpiece of this project's type design was a shared interface using generics.

My first draft defined Income and Expense as completely separate interfaces:

// First version — lots of duplication
export interface Income {
  id: number;
  amount: number;
  date: string;
  category: IncomeCategory;
  description: string;
}

export interface Expense {
  id: number;
  amount: number;
  date: string;
  category: ExpenseCategory;
  description: string;
}

Four fields — id, amount, date, description — are identical. AI suggested that generics could consolidate these, and I refactored it myself:

// Refactored with generics
interface EntityDetail<T> {
  id: number;
  amount: number;
  date: string;       // format: YYYY/MM/DD
  category: T;
  description: string;
}

export interface Income  extends EntityDetail<IncomeCategory>  {}
export interface Expense extends EntityDetail<ExpenseCategory> {}

By passing IncomeCategory or ExpenseCategory as the type parameter T, only the category field differs between the two. This is the same idea as Java's List<T> — a common structure with a pluggable type.

I also defined the category types and constant lists myself:

export type IncomeCategory  = "給与" | "賞与" | "副業" | "その他";
export type ExpenseCategory = "食費" | "交通費" | "光熱費" | "娯楽" | "その他";

export const IncomeCategoryList:  IncomeCategory[]  = ["給与", "賞与", "副業", "その他"];
export const ExpenseCategoryList: ExpenseCategory[] = ["食費", "交通費", "光熱費", "娯楽", "その他"];

export type Account = {
  nextId: number;
  incomes:  Income[];
  expenses: Expense[];
};

The constant lists serve double duty: they're used for both validation and displaying choices to the user.

account.ts — The AccountBook Class

My Todo project used pure functions (each returning a new array). This time I switched to a class-based approach, storing state inside the class itself.

export class AccountBook {
  private account: Account;

  constructor() {
    this.account = { nextId: 1, incomes: [], expenses: [] };
  }

  addIncome(amount: number, date: string, category: IncomeCategory, description: string): void {
    const newIncome: Income = { id: this.account.nextId, amount, date, category, description };
    this.account.incomes.push(newIncome);
    this.account.nextId++;
  }

  // ...
}

ID generation — learning from last time

In the Todo project, I used todoItems.length + 1 for IDs, which caused duplicates after deletion. This time I introduced nextId as a dedicated field. It only increments — never resets — so IDs stay unique no matter how many deletions happen.

`delete` — filter to keep everything else

delete(id: number): void {
  this.account.incomes  = this.account.incomes.filter((income)  => income.id !== id);
  this.account.expenses = this.account.expenses.filter((expense) => expense.id !== id);
}

Both income and expenses are checked — the user just provides an ID without specifying which type. The logic is "keep everything that isn't this ID."

`editIncome` / `editExpense` — delete then re-add

editIncome(id: number, amount: number, date: string, category: IncomeCategory, description: string): void {
  this.account.incomes = this.account.incomes.filter((i) => i.id !== id);
  const editedIncome: Income = { id, amount, date, category, description };
  this.account.incomes.push(editedIncome);
}

Remove the old record, insert a new one with the same ID. Simple and explicit.

`displayTotal` — `reduce` for aggregation

displayTotal(): void {
  const totalIncome  = this.account.incomes.reduce((sum, income) => sum + income.amount, 0);
  const totalExpense = this.account.expenses.reduce((sum, expense) => sum + expense.amount, 0);
  const balance = totalIncome - totalExpense;
  console.log(`Total income:   ${totalIncome}`);
  console.log(`Total expenses: ${totalExpense}`);
  console.log(`Balance:        ${balance}`);
}

reduce — "collapse an array into a single value" — is a natural fit for summing amounts. Same mental model as Java's Stream.reduce().

`displayIncomeAndExpense` — non-destructive sort with spread

displayIncomeAndExpense(): void {
  const sortedIncomes  = [...this.account.incomes].sort((a, b) => a.id - b.id);
  const sortedExpenses = [...this.account.expenses].sort((a, b) => a.id - b.id);
  // ...
}

Array.prototype.sort() mutates the original array. Spreading first ([...array]) creates a copy, keeping the stored data intact. AI pointed this out — more on that in the "where I got stuck" section.

`isIncomeId` / `isExpenseId` — existence check with `some`

isIncomeId(id: number): boolean {
  return this.account.incomes.some((income) => income.id === id);
}

some returns true if at least one element matches — Java's Stream.anyMatch() equivalent. Used to validate that an ID actually exists before editing or deleting.

`getIncome` / `getExpense` — added for testing

getIncome(id: number): Income | undefined {
  return this.account.incomes.find((income) => income.id === id);
}

I added these methods myself to make test assertions easier. find returns the first matching element, or undefined if none is found.

index.ts — CLI Menu

Date validation — catching impossible dates

// Format check (YYYY/MM/DD)
const dateRegex = /^\d{4}\/\d{2}\/\d{2}$/;
if (!dateRegex.test(date)) { /* ... */ }

// Existence check — catch things like "2026/02/30"
const dateObj = new Date(date.replace(/\//g, '-'));
if (isNaN(dateObj.getTime())) {
  console.log("That date does not exist.");
}

A regex can verify the format, but it can't tell you whether February 30th is real. new Date('2026-02-30') produces an Invalid Date, and isNaN(dateObj.getTime()) detects that. I added this check myself after noticing the gap.

Displaying category options before input

console.log(`Choose a category from the following:`);
console.log(IncomeCategoryList.join(", "));

My first version just asked for a category without showing options. After running it myself and thinking "wait, what are the valid values?", I added the display. Small UX improvement, self-initiated.

Bug fix — `||` should be `&&` in the delete validation

// ❌ Passes if the ID exists in either list (always true)
if (!accountBook.isIncomeId(id) || !accountBook.isExpenseId(id)) {

// ✅ Only errors when the ID exists in neither list
if (!accountBook.isIncomeId(id) && !accountBook.isExpenseId(id)) {

AI caught this one. "Not in income OR not in expense" is always true for any valid ID — the correct logic is AND.

account.test.ts — Unit Tests with Jest

Class-based testing requires a fresh instance before each test:

import { AccountBook } from '../account';

describe('addIncome', () => {
  let accountBook: AccountBook;

  beforeEach(() => {
    accountBook = new AccountBook();
  });

  test('can add income', () => {
    accountBook.addIncome(1000, '2026/05/23', '給与', 'test');
    expect(accountBook.getIncome(1)?.amount).toBe(1000);
  });

  test('ID increments after adding income', () => {
    accountBook.addIncome(1000, '2026/05/23', '給与', 'test');
    accountBook.addIncome(2000, '2026/05/24', '賞与', 'test2');
    expect(accountBook.getIncome(2)?.id).toBe(2);
  });
});

I used describe.skip to exclude display methods (console.log-only) from the test suite.

Test results:

 PASS  src/__tests__/account.test.ts
  addIncome
    ✓ can add income
    ✓ ID increments after adding income
  addExpense
    ✓ can add expense
    ✓ ID increments after adding expense
  delete
    ✓ can delete a record
  editIncome
    ✓ can edit income
  editExpense
    ✓ can edit expense
  isIncomeId
    ✓ returns true for a matching income ID
    ✓ returns false for a non-matching income ID
  isExpenseId
    ✓ returns true for a matching expense ID
    ✓ returns false for a non-matching expense ID
  getIncome
    ✓ can retrieve income by ID
  getExpense
    ✓ can retrieve expense by ID

Tests: 13 passed, 13 total

What I Asked AI For

Topic	What AI helped with
Spec decisions	Date format, ID strategy, display format, validation approach — confirmed one by one
Design suggestion	Proposed `EntityDetail` generics (`<T>`) as a way to consolidate the two interfaces
Bug catch	Variable shadowing in `editIncome` — callback arg `income` was hiding the outer variable
Bug catch	Missing `main()` calls in certain `case` branches
Bug catch	Logical operator fix in delete validation — changed OR to AND
Clarification	Explained that `Array.sort()` mutates the original — suggested the spread-copy pattern

Where I Got Stuck

1. `sort()` without spread mutated the stored array

Situation: The display order of records kept changing unexpectedly between views.

Root cause: Array.prototype.sort() is destructive — it modifies the array in place. I was sorting this.account.incomes directly.

// ❌ Mutates the stored array
this.account.incomes.sort((a, b) => a.id - b.id);

// ✅ Sort a copy, leave the original alone
const sortedIncomes = [...this.account.incomes].sort((a, b) => a.id - b.id);

I had applied the spread pattern in the Todo project for push, but hadn't thought to apply it to sort. AI's reminder made it click for me.

2. Variable shadowing caused `undefined` IDs in `editIncome`

Situation: After editing an income record, its ID became undefined.

Root cause: The callback argument and an outer variable shared the same name — the callback's income parameter was shadowing the outer scope.

// ❌ The filter callback's `income` hides the outer `income` variable
const editedIncome: Income = { id: income.id, ... }; // which `income`?
this.account.incomes = this.account.incomes.filter((income) => income.id !== id);

// ✅ Rename the callback argument to avoid the collision
this.account.incomes = this.account.incomes.filter((i) => i.id !== id);
const editedIncome: Income = { id, amount, date, category, description };

This can happen in Java too, but it's especially easy to hit in JavaScript where callbacks are everywhere. Good one to internalize.

3. Regex alone can't catch impossible dates

Situation: "2026/02/30" passed format validation and entered the system.

Root cause: A regex can verify structure, not validity.

// Catches wrong format — but not wrong dates
const dateRegex = /^\d{4}\/\d{2}\/\d{2}$/;

// Catches impossible dates too
const dateObj = new Date(date.replace(/\//g, '-'));
if (isNaN(dateObj.getTime())) {
  console.log("That date does not exist.");
}

new Date('2026-02-30') becomes Invalid Date, and isNaN(getTime()) catches it. I noticed this gap on my own and added the check.

4. Forgetting `rl.close()`

Situation: Selecting "Exit" printed the message but the process didn't end.

Root cause: rl.close() was missing. Without it, the readline interface stays open and the process hangs.

case "8":
  rl.close(); // required — otherwise the process never exits
  break;

I hit this same bug in the Todo project. Writing it down again so it sticks.

What I Learned

Functions vs. Classes

My Todo project used pure functions (return new arrays, no side effects). This project switched to a class.

Aspect	Function-based	Class-based
State management	Caller holds the variable	Class holds it internally
Testability	Clear input → output, easy to assert	Need a fresh instance per test
Familiarity from Java	More functional-style	Closer to Java OOP

Neither is strictly better — it depends on the design goals.

TypeScript

Topic	Key Takeaway
Generics `<T>`	Reuse structure with a pluggable type. `EntityDetail<IncomeCategory>` — same idea as `List<T>` in Java
`interface extends`	Inherit shared fields from a base interface
Optional chaining `?.`	`getIncome(1)?.amount` — safe access when the value might be `undefined`
`private` / `public`	Same as Java — controls access from outside the class

JavaScript / Node.js

Topic	Key Takeaway
`sort()` is destructive	`Array.sort()` modifies in place — spread first to stay safe
`find`	Returns the first matching element, or `undefined`
Variable shadowing	Callback args with the same name as outer vars hide the outer scope
Date validation	`new Date()` + `isNaN(getTime())` catches dates that are formatted correctly but don't exist

Array Methods vs Java Streams

TypeScript	Java	Purpose
`filter`	`stream().filter()`	Keep elements matching a condition
`reduce`	`stream().reduce()`	Collapse an array into a single value
`some`	`stream().anyMatch()`	Return true if any element matches
`find`	`stream().findFirst()`	Return the first matching element

Jest Testing

Topic	Key Takeaway
`beforeEach` with class	Create `new AccountBook()` before each test to keep tests independent
`expect().toBe()`	Strict equality check
`expect().toBeUndefined()`	Assert that a value is `undefined`
`describe.skip`	Explicitly skip test groups that aren't meaningful to automate

Reflection

Generics made sense once I had a reason to use them: I didn't design with EntityDetail<T> from the start. I wrote out both interfaces in full, felt the redundancy, and then asked AI if there was a better way. Refactoring after experiencing the pain made the concept stick much better than if I'd been told about it upfront.

Validation comes from running the code: Both the impossible-date gap and the missing category hints came from actually using the CLI and thinking "that's wrong." The feedback loop of building → using → improving is what I'm finding most valuable in these projects.

Starting with types pays off: Locking down types.ts before touching account.ts meant TypeScript caught mismatches early. This mirrors the interface-first approach I'd use in Java, and it works just as well here.

readline + async/await is next: The callback nesting in index.ts was readable this time, but I can see how it'll get messy as complexity grows. Rewriting with async/await is on my list for the next project.

Wrapping Up

This was my fourth TypeScript project — a Household Budget CLI.

Progress since the Todo List:

Designed a shared generic interface (EntityDetail<T>) from scratch
Moved from function-based to class-based design and understood the trade-offs
Used reduce, some, and find in real logic — not just exercises
Wrote date validation that catches impossible dates, not just malformed ones
Hit and diagnosed variable shadowing — a subtle bug category worth knowing

Next up: an external API tool (weather API) to learn async/await, fetch, and response type definitions.

Full learning log: 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 Todo List CLI with TypeScript — interface, Array Methods, and Jest

Uya — Sat, 30 May 2026 05:44:45 +0000

Introduction

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

In my previous article, I built a Rock-Paper-Scissors CLI and learned about union types, conditional logic, and Jest. This time, I built a Todo List CLI and focused on:

Defining data structures with interface (the TypeScript equivalent of a Java POJO class)
Using array methods (filter / map / reduce / some) and comparing them with Java Streams
Writing immutable operations with the spread operator instead of push
Understanding async flow in readline — callbacks and recursive calls
Managing test setup with beforeEach in Jest

Same as before — I write honestly about where I got stuck, 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 Todo list that manages title, priority, and completion status.

$ npm start

Select a menu option:
1. Add Todo
2. Delete Todo
3. Toggle completion
4. Show list
0. Exit
1
Enter a title:
Learn TypeScript
Select priority:
1. High
2. Medium
3. Low
1
Todo added!
[ { id: 1, title: 'Learn TypeScript', priority: 'high', completed: false } ]

⚠️ The list resets when you exit — no persistence. This is purely a learning project.

📦 Repository: https://github.com/uya0526-design/todo_list

Project Structure

todo_list/
├── src/
│   ├── index.ts          # Entry point / CLI menu
│   ├── todo.ts           # Todo operation logic
│   ├── types.ts          # Type definitions
│   └── __tests__/
│       └── todo.test.ts  # Unit tests (12 cases)
├── jest.config.js
├── package.json
└── tsconfig.json

Same as my previous projects — responsibilities 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 Priority = 'high' | 'medium' | 'low';

export interface TodoItem {
  id: number;
  title: string;
  priority: Priority;
  completed: boolean;
}

How I used interface vs type:

Initially, I embedded the priority options as an inline union type inside the interface:

// First version (inline)
export interface TodoItem {
  id: number;
  title: string;
  priority: 'high' | 'medium' | 'low'; // embedded directly
  completed: boolean;
}

As I built out index.ts, I realized I needed to reference the priority values there too. So I refactored Priority into its own named type alias — a decision I made myself, without being prompted.

Naming the type makes the intent clearer: this value represents a priority level, not just a random string.

todo.ts — Todo Operation Logic

`addTodoItem` function

import type { TodoItem, Priority } from './types.js';

export function addTodoItem(
  todoItems: TodoItem[],
  title: string,
  priority: Priority
): TodoItem[] {
  const maxId = todoItems.reduce((max, item) => Math.max(max, item.id), 0);
  const newItem: TodoItem = { id: maxId + 1, title, priority, completed: false };
  return [...todoItems, newItem];
}

Design decisions:

Spread instead of push: push mutates the original array. Returning a new array with [...todoItems, newItem] keeps the function pure and the data immutable.
reduce for ID generation: Using todoItems.length + 1 caused duplicate IDs after deletion. Using reduce to find the current max ID solves that.

This was the first time I used reduce in real logic. The mental model — "collapse an array into a single value" — maps directly to Java's Stream.reduce().

`deleteTodoItem` function

export function deleteTodoItem(todoItems: TodoItem[], id: number): TodoItem[] {
  return todoItems.filter((item) => item.id !== id);
}

"Keep everything except the one to remove" — clean and immutable. The original array is never touched.

`toggleTodoItem` function

export function toggleTodoItem(todoItems: TodoItem[], id: number): TodoItem[] {
  return todoItems.map((item) =>
    item.id === id ? { ...item, completed: !item.completed } : item
  );
}

What { ...item, completed: !item.completed } does:

Instead of doing item.completed = !item.completed (which mutates), this creates a new object: spread all properties from item, then override only completed. The original object is untouched.

This style felt unfamiliar coming from Java, but once I saw it as "copy and override," it clicked.

index.ts — CLI Menu

The main loop uses readline + switch, with recursion to keep the menu running.

import * as readline from 'readline';
import { addTodoItem, deleteTodoItem, toggleTodoItem } from './todo.js';
import type { TodoItem, Priority } from './types.js';

let todoItems: TodoItem[] = [];

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

function main(): void {
  console.log('Select a menu option:');
  console.log('1. Add Todo');
  console.log('2. Delete Todo');
  console.log('3. Toggle completion');
  console.log('4. Show list');
  console.log('0. Exit');

  rl.question('', (input) => {
    const choice = parseInt(input, 10);
    if (isNaN(choice)) {
      console.log('Please enter a number.');
      return main();
    }

    switch (choice) {
      case 1:
        addTodo();
        break;
      case 2:
        deleteTodo();
        break;
      case 3:
        toggleTodo();
        break;
      case 4:
        console.log(todoItems);
        main();
        break;
      case 0:
        rl.close();
        break;
      default:
        console.log('Invalid input.');
        main();
        break;
    }
  });
}

main();

Why let instead of const for todoItems:

Since my Todo functions return new arrays (immutable pattern), I need to reassign the variable with the returned value. const doesn't allow reassignment, so let is needed here.

// ❌ const doesn't allow reassignment
const todoItems: TodoItem[] = [];
todoItems = addTodoItem(todoItems, title, priority); // Error

// ✅ let allows reassignment
let todoItems: TodoItem[] = [];
todoItems = addTodoItem(todoItems, title, priority);

todo.test.ts — Unit Tests with Jest

Using beforeEach to reset state before each test:

import { addTodoItem, deleteTodoItem, toggleTodoItem } from '../todo';

describe('addTodoItem', () => {
  let todoItems = addTodoItem([], 'test', 'high');

  beforeEach(() => {
    todoItems = addTodoItem([], 'test', 'high');
  });

  test('adding a Todo increases the count by 1', () => {
    expect(todoItems).toHaveLength(1);
  });

  test('added Todo has id 1', () => {
    expect(todoItems[0].id).toBe(1);
  });

  test('added Todo has the correct title', () => {
    expect(todoItems[0].title).toBe('test');
  });

  test('added Todo has the correct priority', () => {
    expect(todoItems[0].priority).toBe('high');
  });

  test('added Todo has completed = false', () => {
    expect(todoItems[0].completed).toBe(false);
  });

  test('adding after delete does not produce a duplicate ID', () => {
    const after = addTodoItem(deleteTodoItem(todoItems, 1), 'test2', 'low');
    expect(after[0].id).toBe(1);
  });
});

describe('deleteTodoItem', () => {
  let todoItems: ReturnType<typeof addTodoItem>;

  beforeEach(() => {
    todoItems = addTodoItem(addTodoItem([], 'test1', 'high'), 'test2', 'low');
  });

  test('deleting a Todo decreases the count by 1', () => {
    expect(deleteTodoItem(todoItems, 1)).toHaveLength(1);
  });

  test('deleted Todo no longer exists in the list', () => {
    const result = deleteTodoItem(todoItems, 1);
    expect(result.find((item) => item.id === 1)).toBeUndefined();
  });

  test('original array is unchanged after delete (immutability)', () => {
    deleteTodoItem(todoItems, 1);
    expect(todoItems).toHaveLength(2);
  });
});

describe('toggleTodoItem', () => {
  let todoItems: ReturnType<typeof addTodoItem>;

  beforeEach(() => {
    todoItems = addTodoItem([], 'test', 'high');
  });

  test('toggling changes completed from false to true', () => {
    expect(toggleTodoItem(todoItems, 1)[0].completed).toBe(true);
  });

  test('toggling twice returns completed to false', () => {
    const toggled = toggleTodoItem(todoItems, 1);
    expect(toggleTodoItem(toggled, 1)[0].completed).toBe(false);
  });

  test('toggling one item does not affect others', () => {
    const items = addTodoItem(todoItems, 'test2', 'low');
    expect(toggleTodoItem(items, 1)[1].completed).toBe(false);
  });
});

Test results:

 PASS  src/__tests__/todo.test.ts
  addTodoItem
    ✓ adding a Todo increases the count by 1
    ✓ added Todo has id 1
    ✓ added Todo has the correct title
    ✓ added Todo has the correct priority
    ✓ added Todo has completed = false
    ✓ adding after delete does not produce a duplicate ID
    ✓ deleting a Todo decreases the count by 1
    ✓ deleted Todo no longer exists in the list
    ✓ original array is unchanged after delete (immutability)
    ✓ toggling changes completed from false to true
    ✓ toggling twice returns completed to false
    ✓ toggling one item does not affect others

Tests: 12 passed, 12 total

What I Asked AI For

Topic	What AI helped with
interface syntax	The basic `export interface Name { ... }` form and PascalCase convention
push → spread	The concept of immutability and the `[...arr, newItem]` approach
Recursive `main()` issue	Explained that `rl.question` is async — calling `main()` outside the callback runs immediately
`switch` fallthrough	Pointed out that missing `break` / `return` causes the next `case` to run
Processing after `isNaN`	Noted that without `return`, code after the check still executes
Jest setup	Explained `npm install --save-dev jest ts-jest @types/jest` and what each package does
`beforeEach` usage	Explained the syntax, compared to JUnit's `@BeforeEach`
Test coverage ideas	Suggested what edge cases to verify for `deleteTodoItem` and `toggleTodoItem`

Where I Got Stuck

1. Adding after deletion caused duplicate IDs

Situation: After deleting the item with id: 1, adding a new item also got id: 1.

Root cause: My original ID logic was todoItems.length + 1. After a deletion, the array length decreases — so the new ID could collide with one that already exists elsewhere.

// ❌ Length-based (breaks after deletion)
const newId = todoItems.length + 1;

// ✅ Max ID-based (always safe)
const maxId = todoItems.reduce((max, item) => Math.max(max, item.id), 0);
const newId = maxId + 1;

Insight: I only caught this because I wrote a test for it. Without that test case, I might not have noticed until it caused a real bug.

2. Calling `main()` outside the `rl.question` callback

Situation: I wanted to show the menu again after each selection, so I initially wrote:

// ❌ Runs immediately, doesn't wait for input
rl.question('', (input) => {
  // ... handle input
});
main(); // called outside the callback

Root cause: rl.question() is asynchronous — it registers a callback and moves on immediately. Calling main() outside the callback means it executes right away, before the user even answers.

Fix: Move every main() call inside the callback, at the end of each case branch.

3. Missing `break` in the `default` case

Situation: When a user entered an invalid option, main() was called (to show the menu again), but then execution fell through into case 0 and closed the program.

Root cause: No break after the default block. JavaScript's switch falls through to the next case just like Java — you need break or return to stop it.

// ❌ Falls through to case 0
default:
  console.log('Invalid input.');
  main();
  // execution continues into case 0...

// ✅ Stops here
default:
  console.log('Invalid input.');
  main();
  break;

I know this rule from Java, but it's easy to forget in the heat of writing logic.

4. No error when specifying a non-existent ID

Situation: Trying to delete or toggle an ID that didn't exist produced no error and no feedback — the operation just silently did nothing.

Fix: Added an existence check using some():

if (!todoItems.some((item) => item.id === id)) {
  console.log('No Todo found with that ID.');
  return main();
}

some() returns true if at least one element matches the condition — equivalent to Java's Stream.anyMatch().

What I Learned

TypeScript Type System

Topic	Key Takeaway
`interface`	Defines the shape of data — similar to a Java POJO class
`type` alias	Gives a name to a union type for reuse across files
Shorthand properties	`{ title: title }` can be written as `{ title }`

Array Methods vs Java Streams

TypeScript	Java	Purpose
`filter`	`stream().filter()`	Keep elements that match a condition
`map`	`stream().map()`	Transform every element
`reduce`	`stream().reduce()`	Collapse an array into a single value
`some`	`stream().anyMatch()`	Return true if any element matches

Immutable Operations

push mutates the original array → use [...arr, newItem] to return a new one
Partial object updates → use { ...obj, field: newValue } to return a new object
Functions that return new values instead of mutating are easier to test

Async Flow with readline

rl.question() registers a callback and returns immediately
To loop the menu, call main() recursively inside the callback — not outside

Jest Testing

Topic	Key Takeaway
`beforeEach`	Runs before each test — equivalent to JUnit's `@BeforeEach`
`toHaveLength(n)`	Asserts array length
`toBeUndefined()`	Asserts a value is `undefined`
Immutability testing	After an operation, verify the original array hasn't changed

Reflection

Where my Java background helped: The Java Stream API background made filter, map, reduce, and some immediately intuitive — I could connect each one to its Java counterpart. My quality-first instincts also kicked in: I wrote tests for "does deletion preserve IDs?" and "does the operation stay immutable?" without being asked.

Biggest new concept: Async readline. Coming from Java's synchronous execution model, the idea that code after rl.question() runs before the callback was genuinely surprising. Hitting the bug and debugging it was the best way to understand it.

Self-initiated refactor: Extracting Priority into its own type alias was my own call. I noticed the need when building index.ts, and made the change without prompting — that kind of design awareness feels like real progress.

Wrapping Up

This was my third TypeScript project — a Todo List CLI.

Progress since the Rock-Paper-Scissors game:

Designed a multi-field data structure with interface on my own
Used filter, map, reduce, and some in real logic
Applied immutable patterns consistently throughout
Understood async callback flow by hitting (and fixing) a real bug
Managed test state properly with beforeEach

Next up: persistent storage (writing to a file) and deeper async patterns.

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 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.

DEV Community: Uya

Building a Weight Tracker CLI in Python — Type Hints, Pure Functions, and pytest

Introduction

My Learning Style (AI Transparency)

What I Built

File Structure and Tech Stack

What I Implemented Myself

main.py — The menu loop and function split

Input validation — try / except ValueError

Listing — enumerate and an empty-list check

Statistics — extracting a pure function (my biggest lesson this time)

tests/test_main.py — normal, boundary, and error cases

What I Asked AI For

Where I Got Stuck

1. I wrote comments with //

2. isdigit() can't reject decimals

3. ZeroDivisionError on an empty list

4. Can't import main.py from tests/

5. My test expectation was wrong

What I Learned

Python basics (mapped to Java)

Type hints

Exception handling

Testability (separation of concerns)

Unit testing (pytest)

Project structure

Reflection

Wrapping Up

Building an HTTP Client CLI for Your Own API with TypeScript — FastAPI, POST, and Error Handling

Introduction

My Learning Style (AI Transparency)

What I Built

System Overview

Backend: FastAPI Server (Python)

Setup

Implementing the endpoints

Splitting RequestDTO and ResponseDTO

Client: TypeScript CLI

types.ts — Mirror the server's types

api.ts — GET and POST with fetch

index.ts — Interactive menu and input validation

api.test.ts — Mocking fetch (success and failure)

What I Asked AI For

Where I Got Stuck

1. A 422 error on POST (the Content-Type header)

2. The CLI exits entirely on a 404

3. The difference between return and throw error

What I Learned

async/await and fetch (GET / POST)

Error handling

Letting types simplify code

FastAPI / Python (first contact)

Test design

Reflection

Wrapping Up

Building a Weather API CLI with TypeScript — async/await, fetch, and Response Types

Introduction

My Learning Style (AI Transparency)

What I Built

Project Structure

Tech Stack

What I Implemented Myself

types.ts — API Response Types

First, define the "city data"

Define the API response type

Convert weather codes to text

api.ts — Async API Calls with fetch

index.ts — Wrapping readline in a Promise

api.test.ts — Mocking fetch

Success case: hit the real API and check

Failure case: swap fetch for a mock

What I Asked AI For

Where I Got Stuck

1. I typed numeric response fields as string

2. I hardcoded the units

3. The weather code keys didn't match because they were strings

4. AI's suggestions aren't always correct

What I Learned

async/await and fetch

TypeScript Types

1. I wrote comments with `//`

2. `isdigit()` can't reject decimals

3. The difference between `return` and `throw error`

1. `private constructor` prevented instantiation