この記事で分かること
CSVをJSONへ移す人向けに、引用符内の区切り文字が単純分割でどう崩れるか、ToolShedの変換関数が境界入力をどう扱うかを、同じ入力の比較欄とNode.jsテストで説明します。
CSVをカンマで割るだけでは足りない
表データをJSONへ移すとき、各行を改行で分け、各セルをカンマで分けるだけでは、セルの中にあるカンマや改行を区切りと取り違えます。たとえば "music, video" は一つの値ですが、単純な split(',') では二つの値になります。引用符で囲まれた複数行の文章も、行の区切りで分割すると崩れます。
ToolShedのCSV→JSONは、先頭行を列名として読み、後続行をオブジェクト配列へ変換します。仕事の表を移すときは、変換後のJSONだけでなく、列名・列数・値の型も一緒に確認する必要があります。

操作の順序と出力の読み方はToolShedのCSV変換ガイドにまとめています。
パーサーの考え方を比べる
表は横にスクロールできます。
| 同じ入力を処理 | 単純な改行・カンマ分割 | 引用符を読む処理 |
|---|---|---|
| CSVの物理行 | 4行として読む(ヘッダー+データ断片3行) | ヘッダー+データ2件として読む |
| Sheer Clipのnote | "music と video" に分裂 | music, video の1値 |
| ToolShedのnote | "line one と次の行に分裂 | 改行を含む1値。二重引用符も復元 |
引用符を扱う処理では、文字を1つずつ見て「引用符の内側か」を記録します。内側のカンマと改行は値として残し、連続した二重引用符は値中の引用符1つとして読みます。外側にあるカンマと改行だけをセル・行の区切りにします。引用符内の文字を残す必要があるため、単純分割よりこの方式が要件に合います。今回のサンプルでは両方を同じ入力で比べ、2件のデータと値が保たれることをテストします。
次の入力は、引用符内の改行を含むため物理的には4行、ヘッダーを除く論理データは2件です。単純分割では1件目のnoteがカンマで2セルに分かれ、2件目は改行で別の断片になります。
name,count,note
Sheer Clip,2,"music, video"
ToolShed,3,"line one
line ""two"""
列名は最初の行から取得し、各データ行では列名の数だけ値を読みます。CSVはテキストなので、数値に見える 2 もJSONでは文字列の "2" になります。計算に使う場合は、受け取った後に列ごとの型変換を検討してください。
同じ入力をその場で比べる
例を選ぶかCSVを編集して、単純な改行・カンマ分割とToolShedの変換関数を比べられます。「単純分割の結果」は行ごとの配列、「変換関数の結果」はヘッダーを使ったJSONです。実際のCSV処理を別に書き直したものではなく、ビルド時に型注釈を外した同じ関数を読み込みます。
CSV比較欄
JavaScript有効時に比較を操作できます。初期例の結果を表示しています。
単純分割の結果(配列)
[
[
"name",
"count",
"note"
],
[
"Sheer Clip",
"2",
"\"music",
" video\""
],
[
"ToolShed",
"3",
"\"line one"
],
[
"line \"\"two\"\"\""
]
]変換関数の結果(JSON)
[
{
"name": "Sheer Clip",
"count": "2",
"note": "music, video"
},
{
"name": "ToolShed",
"count": "3",
"note": "line one\nline \"two\""
}
]入力を編集した後は、結果欄が前の入力に対するものだと分かる表示に切り替わります。「比較を実行」を押すと、その時点の入力で両方を更新します。入力は送信・保存しません。
独立テストで再現する
ToolShedの実装からコピーしたTypeScriptファイルとNode.js標準テストを使います。例の1件目にはカンマを含む値、2件目には改行と二重引用符を含む値を入れました。
- サンプルとテストを保存する
CSV変換のサンプルとテストファイルを同じフォルダへ保存します。
- Node.js 24でテストを実行する
そのフォルダで
node --experimental-strip-types --test --test-isolation=none toolshed-csv-json.test.mjsを実行します。TypeScriptの型注釈を除いてNode.jsから直接読み込む指定です。 - 比較と変換を確認する
8つのテストが引用符内のカンマ・改行・引用符、値の文字列化、往復、列の不足と余剰、単純分割との違い、閉じていない引用符、末尾空白、重複列名を検査します。
2件全体の出力は次のようになります。値は保たれますが、型情報はCSVに含まれないため、数値も文字列として表現されます。
[
{
"name": "Sheer Clip",
"count": "2",
"note": "music, video"
},
{
"name": "ToolShed",
"count": "3",
"note": "line one\nline \"two\""
}
]
このサンプルはアプリ本体から抽出した関数のコピーで、UIや本番サイトのデータ処理を呼び出すものではありません。手元で仕組みを試すための独立した例です。
テストで確かめた結果
Node.js v24.19.0で独立テスト8件が成功しました。引用符内のカンマは一つのセルに残り、引用符内の改行と二重引用符も復元されます。JSON→CSV→JSONでは、文字列として表せる値とヘッダーの並びを保てました。同じ入力を単純分割した比較では、ヘッダーを除くデータ断片が2件ではなく3件になり、最初のnoteも "music と video" に分かれました。
列数の違いも実際の関数に合わせて検査しています。列名より値が少ない行では不足セルが空文字になります。一方、値が多い行では余剰セルが出力JSONへ入りません。列数の不一致をエラーとして止める挙動ではないため、変換前に各データ行のセル数を列名の数と照合してください。
この結果を自分のCSVへ当てはめるなら、まず先頭行の列名、その後に数行の入力・出力を比較し、日付・数値・空欄が意図した形かを確かめます。元データを上書きする前に、変換後の値を使う側でも確認するのが安全です。
境界入力の結果
追加した3件のテストでは、閉じていない引用符をエラーにせず入力末尾までを値にし、入力全体の末尾にある空白を除き、重複ヘッダーの後の値を残しました。表の ␠ はテスト入力の末尾にある半角空白1つを示します。
表は横にスクロールできます。
| 入力 | 変換関数のJSON出力 | 読み方 |
|---|---|---|
name,note
ToolShed,"open | [{"name":"ToolShed","note":"open"}] | 閉じていない引用符をエラーとしていない |
name,note
ToolShed,tail␠ | [{"name":"ToolShed","note":"tail"}] | 全体の末尾空白をtrimで除く |
name,name
first,second | [{"name":"second"}] | 同じオブジェクトキーへの後の代入が前を上書き |
これらは入力を自動修復する保証ではありません。未閉じ引用符や末尾空白が意味を持つデータ、列名が重複する表は、変換前に元ファイルも確認してください。
Node.js 24の空の作業フォルダにtoolshed-csv-json.tsとtoolshed-csv-json.test.mjsを同じ場所へ保存し、node --experimental-strip-types --test --test-isolation=none toolshed-csv-json.test.mjsを実行します。8件が通れば既知の例を再現できています。moduleが見つからない場合は2ファイルの配置とNode.jsの版を確認します。自分のCSVへ移る前に、個人情報を含まない数行で行数・列名・不足/余剰セルを照合し、閉じていない引用符、末尾空白のtrim、重複ヘッダー上書きも処理要件と合うか確認してください。
使う前に確認したいこと
- 先頭行が列名として扱われるため、ヘッダーのないCSVはそのままでは同じ意味に変換できません。
- すべてのCSV値は文字列です。数値演算や日付比較が必要なら、用途に応じて型を決め直します。
- 同じ列名は後の値が上書きし、列名より値が多い余剰セルは結果から落ちます。行ごとの列数と列名の重複を確認してください。
- 閉じていない引用符や入力末尾の空白は今回の実装ではエラーにならず、末尾の空白は全体trimで除かれます。元CSVの意味と一致するか確認してください。
- このテストは代表例を扱いますが、あらゆる入力元のCSV方言を保証するものではありません。
ToolShedで使う場合は、対象ツールのCSV入力へ貼り付け、JSON出力を見てからコピーします。変換自体の説明はToolShedの使い方にまとめています。
参照した実装
コピー元はToolShedのソースリポジトリ webtool のHEAD 88a9ca686 にある packages/tools/src/text/csv-json.ts です。ブログのサンプルはこのファイルをそのまま配置し、変換関数の挙動をNode.jsテストで確かめる構成にしました。
テストは入力例を指定して実行できる確認範囲です。ToolShedの全機能や、本番環境でのファイル保存・通信までをテストするものではありません。