🔍 「これは誰の仕事か」を4回間違えて気づいたTypeScript初日の教訓（#0009）

TypeScriptもElectronも初めて触るところから、個人でブラウザアプリ「Trueful」を作っています。今回はWorkspace管理機能の実装に着手した初日の記録です。設計自体は前回までに固めてあったのですが、いざコードを書き始めると「この情報は誰の責任範囲か」を4回も間違えて、その都度気づいては直す、という展開になりました。成功談よりも、この手の回り道のほうが誰かの役に立つ気がするので、そのまま書いておきます。

最初に考えていたこと

実装に入る前、services(単一責任の小さな操作)とflows(servicesを組み合わせたユースケース単位の処理)という役割分担を土台として置いていました。この軸があれば、「ある情報や処理をどこに置くべきか」を毎回判断できるはずだと思っていたのですが、実際に手を動かし始めると、この軸そのものへの理解がまず揺らぎました。

転換1: servicesとflowsの役割を逆に覚えていた

• 当初案: servicesが複数の処理をまとめる集大成で、flowsがこまごました個別操作
• 気づいたこと: 実装の相談を進める中で、この定義が以前自分で確定させたものと真逆であることに気づいた
• 直した内容: services=単一責任の小さな操作、flows=それらを組み合わせたユースケース単位の処理、という正しい定義に立ち返った

正直、自分で決めたはずの定義がここまで簡単にひっくり返るとは思っていませんでした。この後のすべての判断は、正しい定義に立ち返ってから進めています。今にして思うと、「services」「flows」という単語だけを覚えていて、それぞれが指す責任の重さの方を覚えていなかったのが原因だったように思います。

転換2: COM側jsonに情報を持たせすぎようとした

WorkspaceにはシステムだけがCOM側jsonというファイルとして管理する、システム管理用マニフェストがあります。この中身を決める場面で、status(active/dormant)・lastUsedTimeMs・保存先パス(fileSaveRoot)・ファイル自身のハッシュ値と、次々に「入れたほうがいいかもしれない」候補が浮かびました。

• 当初案: COM側jsonにstatus・lastUsedTimeMs・fileSaveRoot・ハッシュ値をすべて持たせる
• 気づいたこと: これらはすでに別の層が責務として持ちうる情報だった。status・lastUsedTimeMsはSQLite側がsource of truthとして持つべきで、二重に持たせると同期がズレたときにどちらが正しいか分からなくなる。保存先パスは書き込み処理を呼び出す側の関心事であり、データ自身が知っている必要はない。ハッシュ値に至っては、書き込み前の段階ではまだファイルが存在しないため、原理的に「自分自身のハッシュを自分の中に含める」ことができない
• 直した内容: 最終的にCOM側jsonは{ id: number }のみという、拍子抜けするほどシンプルな形に落ち着いた

services/workspaceFile.ts

// 最終的にCOM側jsonが持つのはこれだけ
type ComWorkspaceData = { id: number }

一瞬考えては踏みとどまる、を4回繰り返した結果がこれです。中身が薄い判断に見えますが、「DBが持つべき情報」「ユーザーが編集する情報(USER側json)」「システムだけが管理する情報(COM側json)」という3層の責務分離をはっきりさせられたのは大きな収穫でした。

転換3: number & nullとnumber | nullを混同した

型定義でも一箇所やらかしています。「numberまたはnull」を表現したかったのですが、書いたコードはこうでした。

services/workspaceCompute.ts

function isArchivable(
  dormantedTimeMs: number & null, // ← 本来は number | null
  nowMs: number,
  archiveThresholdMs: number
): boolean {
  // ...
}

• 当初案: number & nullで「numberまたはnull」を表現しようとした
• 気づいたこと: &はIntersection型(AかつB)であり、number & nullは「numberでありながらnullでもある値」という、そもそも存在しえない型を宣言していた
• 直した内容: Union型(AまたはB)を表す|に修正し、number | nullとした

- dormantedTimeMs: number & null,
+ dormantedTimeMs: number | null,

TypeScriptを触るのがこの日が初めてだったので、&と|という一文字違いの記号が全く別の意味を持つことを知らず、素直に間違えました。TypeScript公式ハンドブックのUnion Typesのページを後から読んで、ようやく腑に落ちました。

転換4: typeof nullの罠と、意味のないtry/catch

null判定と、ファイル書き込み処理のエラーハンドリングでも、それぞれ勘違いをしていました。

まずnull判定です。

services/workspaceCompute.ts

if (typeof dormantedTimeMs == null) { // ← 意図通りに動かない
  return false
}

• 当初案: typeof dormantedTimeMs == nullでnull判定をしようとした
• 気づいたこと: typeof nullはJavaScriptの有名な罠で、実は"object"という文字列を返す。つまりこの比較式は狙い通りには機能しない(MDNのtypeof演算子のページにもこの挙動が明記されている)
• 直した内容: dormantedTimeMs == nullのように、値そのものを直接比較する書き方に変更した

もう一つ、ファイル書き込み処理writeJsonFileにも、意味のないtry/catchを書いていました。

services/workspaceFile.ts

export function writeJsonFile(path: string, data: unknown): string {
  try {
    const json = JSON.stringify(data)
    fs.writeFileSync(path, json)
    return path
  } catch (e) {
    throw e // ← 何も加工していない、素通しのcatch
  }
}

• 当初案: try/catchで囲み、catchの中でそのままthrowし直す
• 気づいたこと: エディタのESLintから「Unnecessary try/catch wrapper」と指摘された。キャッチしても何も加工しておらず、書く意味がなかった
• 直した内容: try/catch自体を削除し、fs.writeFileSyncのエラーが自然に呼び出し元へ伝播する形にした

export function writeJsonFile(path: string, data: unknown): string {
-  try {
-    const json = JSON.stringify(data)
-    fs.writeFileSync(path, json)
-    return path
-  } catch (e) {
-    throw e
-  }
+  const json = JSON.stringify(data)
+  fs.writeFileSync(path, json)
+  return path
}

「将来のエラーハンドリングの受け皿として残しておきたい」という気持ちで書いたラッパーだったのですが、実際には処理を素通りさせているだけで、何の受け皿にもなっていませんでした。ツールに指摘されて初めて自覚した、という点では地味に効いた学びです。

振り返って何が共通していたか

4つの転換を並べてみると、実はどれも同じ形をしていました。

#	当初案	見直し後	共通する原因
1	services=まとめ役、flows=個別操作	services=個別操作、flows=まとめ役	用語だけ覚えて、責務の重さを覚えていなかった
2	COM側jsonに複数の情報を持たせる	{ id: number }のみに絞る	「あったら便利」で他の層の責務まで抱え込もうとした
3	number & null	number | null	記号の意味を確認せず、直感で書いた
4	typeof x == null / 素通しのtry/catch	直接比較 / try/catch削除	「動きそうに見える」書き方を検証せずに採用した

まとめると、今回のつまずきはほぼ全部「これは本当に自分(この関数・このファイル)の責務か」を確認しないまま書き進めた結果でした。COM側jsonの責務も、TypeScriptの型の意味も、null判定の書き方も、try/catchの要否も、結局は「これは誰の仕事か・何を意味する記号か」を一度立ち止まって確認すれば防げるミスばかりです。設計フェーズでさんざんやってきた「責務の分離」という考え方が、実装の一行一行にまでそのまま効いてくることを実感した初日でした。

次回

#0010 Workspace管理実装編(続き)
今回はCOM側jsonの設計とwriteJsonFileまで進みました。次回はreadJsonFileとworkspaceDb.ts(SQLite書き込み)に着手する予定です。

GitHub

AIの利用について

この記事は、Claudeに一次稿を作成してもらい、内容を確認・修正したものです。設計判断そのものは自分で行っており、実装コードも自分の手で書いています。Claudeの使い方については番外編1に詳しく書いています。