refactor: MixerDataを論理グループにネスト化するか検討する

[9c5s]

背景

PR #86 (issue #75) で MixerData 型を TCNet 仕様上の全 47 フィールドに拡張した。フラット構造のままでは可読性・保守性に懸念があり、下流クライアント (tcnet-viewer) 側のレビューでも「論理グループにネスト化するか、コメントでグループ化するか」の選択が議論された。

下流プロジェクト tcnet-viewer では暫定対応としてセクションコメントでのグループ化を採用したが、より良い構造化の案としてネスト化が挙がっている。ただしネスト化は破壊的変更になるため、プロトコル提供元 (本リポジトリ) で先に方針を決定し、下流が追従する方が整合性が保てる。

• 関連: MixerDataの47フィールドを論理グループにネスト化するか検討する tcnet-viewer#41 (下流側の追従検討 issue)

現状

// src/types.ts
export type MixerData = {
    mixerId: number;
    mixerType: number;
    mixerName: string;
    masterAudioLevel: number;
    masterFaderLevel: number;
    masterFilter: number;
    micEqHi: number;
    micEqLow: number;
    linkCueA: number;
    linkCueB: number;
    masterCueA: number;
    masterCueB: number;
    // ... 合計 47 フィールド (channels 除く)
    channels: MixerChannel[];
};

ネスト化案

export type MixerData = {
    id: { mixerId: number; mixerType: number; mixerName: string };
    master: { audioLevel: number; faderLevel: number; filter: number; cueA: number; cueB: number };
    mic: { eqHi: number; eqLow: number };
    link: { cueA: number; cueB: number };
    isolator: { on: boolean; hi: number; mid: number; low: number };
    filter: { hpf: number; lpf: number; resonance: number };
    sendFx: { effect: number; ext1: number; ext2: number; masterMix: number; sizeFeedback: number; time: number; hpf: number; level: number };
    sendReturn3: { source: number; type: number; on: number; level: number };
    crossFader: { curve: number; value: number; channelCurve: number };
    beatFx: { on: boolean; levelDepth: number; channelSelect: number; select: number; freqHi: number; freqMid: number; freqLow: number };
    headphones: { preEq: number; aLevel: number; aMix: number; bLevel: number; bMix: number };
    booth: { level: number; eqHi: number; eqLow: number };
    channels: MixerChannel[];
};

検討事項

1. ネスト化するメリット

• 47 フィールドの型定義がグループ単位で俯瞰しやすくなる
• ドメインモデル (Mic / Master / Send FX / Booth 等) が型で直接表現される
• 将来フィールドが増えた場合もグループ内で追加可能で拡張性が高い
• 下流クライアントで mixer.sendFx.level のように階層アクセスできる

2. ネスト化するデメリット

• 破壊的変更: 全フィールドアクセスパスが変わる (tcnet-viewer で約 9 箇所の修正)
• プロトコル仕様 (TCNet 公式 spec) はフラットなバイトレイアウトで定義されており、ネスト化は SDK レイヤー独自の構造化
• parse 処理のネストオブジェクト生成が若干のオーバーヘッド (無視できる程度)
• 既に下流に 47 フィールドフラット構造でリリース済み (v0.9.x)

3. フラット維持の正当性

• TCNet プロトコル仕様と 1:1 対応のままで、バイトオフセットとフィールド名の対応が追跡しやすい
• 破壊的変更を避けられる
• 下流側で必要ならラッパー層でネスト化できる

判断ポイント

• プロトコル SDK としての立ち位置: 「プロトコル仕様の忠実な移植」(フラット維持) vs 「TypeScript エコシステムで使いやすい形」(ネスト化)
• ユーザー数/ユースケース: 現状 tcnet-viewer 以外の利用者は?
• v1.0 リリース前後: v1.0 前なら破壊的変更のコストが低い

やること

• フラット維持かネスト化かの方針決定
• ネスト化する場合:
  • src/types.ts の MixerData 型を再設計
  • src/network.ts の TCNetDataPacketMixer.read() を対応
  • tests/ のアサーション更新
  • CHANGELOG に破壊的変更を明記
  • MixerDataの47フィールドを論理グループにネスト化するか検討する tcnet-viewer#41 へリンクして下流に追従依頼
• フラット維持の場合:
  • MixerDataの47フィールドを論理グループにネスト化するか検討する tcnet-viewer#41 を close し「フラット維持を正式解とする」旨伝える

参考

• PR feat: パケットフィールド拡充・バグ修正・テスト強化 #86 (MixerData 26 フィールド拡張): 4b902ee
• 下流側の関連 issue: MixerDataの47フィールドを論理グループにネスト化するか検討する tcnet-viewer#41

[coderabbitai]

Coding Plan

Summary

• v1.0前の適切なタイミングでMixerData型を論理グループにネスト化し、47フィールドの可読性・保守性問題を解決する
• 12個のサブタイプ（MixerIdentity, MixerMaster等）を定義し、ドメインモデルを型で直接表現する
• バイナリパーサーのオフセット読み取りロジックは維持し、オブジェクト構築部分のみ修正する
• 破壊的変更としてChangesetに記録し、下流プロジェクト（tcnet-viewer）への追従を促す

Design Choices

Design Choice 1: フラット維持 vs ネスト化の方針選択

Options Considered:

1. フラット維持: TCNetプロトコル仕様と1:1対応を維持し、破壊的変更を回避する。下流が必要ならラッパー層でネスト化可能。
2. ネスト化: 47フィールドを論理グループ（master, sendFx, beatFx, booth等）に再構成し、TypeScript開発者にとって使いやすい型を提供する。

Chosen Option: 2

Rationale: v1.0前であり破壊的変更のコストが低い。プロトコルSDKとしてもTypeScriptエコシステムでの使いやすさを優先すべきであり、47フィールドのフラット構造は可読性・保守性に問題がある。下流（tcnet-viewer）の修正箇所も約9箇所と限定的で対応可能。

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: 型定義の再設計

MixerData型を論理グループごとのサブタイプに分割し、ネスト構造として再定義する。既存のMixerChannel型はそのまま維持する。

Task 1: サブタイプの定義

各論理グループに対応するサブタイプをsrc/types.tsに追加する。

• src/types.tsに以下のサブタイプを新規定義:
  • MixerIdentity: mixerId, mixerType, mixerName
  • MixerMaster: audioLevel, faderLevel, filter, cueA, cueB
  • MixerMic: eqHi, eqLow
  • MixerLink: cueA, cueB
  • MixerIsolator: on, hi, mid, low
  • MixerFilter: hpf, lpf, resonance
  • MixerSendFx: effect, ext1, ext2, masterMix, sizeFeedback, time, hpf, level
  • MixerSendReturn3: source, type, on, level
  • MixerCrossFader: curve, value, channelCurve
  • MixerBeatFx: on, levelDepth, channelSelect, select, freqHi, freqMid, freqLow
  • MixerHeadphones: preEq, aLevel, aMix, bLevel, bMix
  • MixerBooth: level, eqHi, eqLow
• フィールド名はプレフィックスを除去してグループ内で自明な命名にする（例: masterAudioLevel → master.audioLevel）
• 各サブタイプをexportし、下流での部分的な型利用を可能にする

Task 2: MixerData型のネスト構造化

サブタイプを使用してMixerDataを再定義する。

• src/types.tsの既存MixerData型をネスト構造に置き換え
• 構造: { id: MixerIdentity, master: MixerMaster, mic: MixerMic, link: MixerLink, isolator: MixerIsolator, filter: MixerFilter, sendFx: MixerSendFx, sendReturn3: MixerSendReturn3, crossFader: MixerCrossFader, beatFx: MixerBeatFx, headphones: MixerHeadphones, booth: MixerBooth, channels: MixerChannel[] }
• MixerChannel型は14フィールドで適切なサイズのため変更しない

🤖 Prompt for AI agents

`src/types.ts`を更新し、MixerData型をフラット構造からネスト構造へ再設計する。

- 以下の12個のサブタイプを新規定義し、それぞれexportする:
  - `MixerIdentity`: mixerId, mixerType, mixerName
  - `MixerMaster`: audioLevel, faderLevel, filter, cueA, cueB
  - `MixerMic`: eqHi, eqLow
  - `MixerLink`: cueA, cueB
  - `MixerIsolator`: on, hi, mid, low
  - `MixerFilter`: hpf, lpf, resonance
  - `MixerSendFx`: effect, ext1, ext2, masterMix, sizeFeedback, time, hpf, level
  - `MixerSendReturn3`: source, type, on, level
  - `MixerCrossFader`: curve, value, channelCurve
- `MixerBeatFx`: on, levelDepth, channelSelect, select, freqHi, freqMid, freqLow
  - `MixerHeadphones`: preEq, aLevel, aMix, bLevel, bMix
  - `MixerBooth`: level, eqHi, eqLow
- フィールド名はプレフィックスを除去し、グループ内で自明な命名にする（例: `masterAudioLevel` → `master.audioLevel`）
- 既存の`MixerData`型をネスト構造に置き換える: `{ id: MixerIdentity, master: MixerMaster, mic:
MixerMic, link: MixerLink, isolator: MixerIsolator, filter: MixerFilter, sendFx:
MixerSendFx, sendReturn3: MixerSendReturn3, crossFader: MixerCrossFader, beatFx:
MixerBeatFx, headphones: MixerHeadphones, booth: MixerBooth, channels:
MixerChannel[] }`
- `MixerChannel`型は14フィールドで適切なサイズのため変更しない

Phase 2: パーサーの更新

TCNetDataPacketMixer.read()メソッドをネスト構造のオブジェクトを生成するよう更新する。バイトオフセットの読み取りロジックは変更せず、オブジェクト構築部分のみ修正する。

read()メソッドのオブジェクト構築部更新

ネスト構造のMixerDataオブジェクトを生成するようread()を修正する。

• src/network.tsのTCNetDataPacketMixer.read()メソッドを更新
• バイトオフセットからの値読み取りロジック（readUInt8等）は変更しない
• this.data = { ... }のオブジェクトリテラル構造を、サブオブジェクトを含むネスト形式に変更
• 各グループのフィールドを対応するサブオブジェクトにまとめる
• 例: masterAudioLevel: buffer.readUInt8(61) → master: { audioLevel: buffer.readUInt8(61), ... }

🤖 Prompt for AI agents

`src/network.ts`の`TCNetDataPacketMixer.read()`メソッドのオブジェクト構築部分を、Phase
1で定義したネスト構造に合わせて更新する。

- バイトオフセットからの値読み取りロジック（`readUInt8`等）は一切変更しない
- `this.data = { ... }`のオブジェクトリテラルを、サブオブジェクトを含むネスト形式に変更する
- 各フィールドを対応するサブオブジェクトにグループ化する
- 例: `masterAudioLevel: buffer.readUInt8(61)` → `master: { audioLevel:
buffer.readUInt8(61), ... }`
- Phase 1で定義した全サブタイプ（id, master, mic, link, isolator, filter, sendFx,
sendReturn3, crossFader, beatFx, headphones, booth, channels）に対応するサブオブジェクトを構築する

Phase 3: テストの更新

テストアサーションをネスト構造のアクセスパスに更新する。テストカバレッジは維持し、バイトオフセット検証の正確性を保つ。

beatgrid-mixer.test.tsのアサーション更新

フラットなフィールドアクセスをネスト形式に変更する。

• tests/beatgrid-mixer.test.tsの全MixerDataフィールドアサーションを更新
• フラットアクセス（例: d.masterAudioLevel）をネストアクセス（例: d.master.audioLevel）に変更
• 変更対象のアサーションパターン:
  • d.mixerId → d.id.mixerId
  • d.masterAudioLevel → d.master.audioLevel
  • d.sendFxLevel → d.sendFx.level
  • 他全てのフィールドアクセス（約40箇所）
• d.channels[n].sourceSelect等のチャンネルアクセスは変更なし
• テスト値とバイトオフセット対応は維持

🤖 Prompt for AI agents

`tests/beatgrid-mixer.test.ts`の全MixerDataフィールドアサーションをネスト構造のアクセスパスに更新する。

- フラットアクセスをネストアクセスに変更する（約40箇所）:
  - `d.mixerId` → `d.id.mixerId`
  - `d.masterAudioLevel` → `d.master.audioLevel`
  - `d.sendFxLevel` → `d.sendFx.level`
  - その他全てのフィールドアクセスも同様に変更
- `d.channels[n].sourceSelect`等のチャンネルアクセスは変更しない
- テスト値とバイトオフセット対応は維持する（テストカバレッジを落とさない）

Phase 4: ドキュメントと変更管理

破壊的変更をChangesetに記録し、下流プロジェクトへの影響を明示する。

Task 1: Changesetの作成

破壊的変更を記録するchangesetファイルを追加する。

• .changeset/ディレクトリに新規changesetファイルを作成
• バンプレベルはminor（既存パターンに従う。BREAKING CHANGEは本文で明記）
• 本文にBREAKING CHANGE:を含め、MixerData型の構造変更と移行方法を記載
• 下流issue（MixerDataの47フィールドを論理グループにネスト化するか検討する tcnet-viewer#41）へのリンクを含める
• 変更内容: 全フィールドアクセスパスの変更（例: mixer.masterAudioLevel → mixer.master.audioLevel）

Task 2: 型エクスポートの確認

新規サブタイプが公開APIから利用可能であることを確認する。

• src/index.tsのexport * from "./types"により自動的にエクスポートされることを確認
• 追加のエクスポート設定は不要（ワイルドカードエクスポートで対応済み）

🤖 Prompt for AI agents

破壊的変更をChangesetに記録し、新規サブタイプの公開API公開を確認する。

- `.changeset/`ディレクトリに新規changesetファイルを作成する:
  - バンプレベルは`minor`（既存パターンに従う。BREAKING CHANGEは本文で明記）
  - 本文に`BREAKING CHANGE:`を含め、MixerData型の構造変更と移行方法を記載
  - 下流issue（9c5s/tcnet-viewer#41）へのリンクを含める
- 変更内容として全フィールドアクセスパスの変更を例示（例: `mixer.masterAudioLevel` →
`mixer.master.audioLevel`）
- `src/index.ts`の`export * from
"./types"`により新規サブタイプが自動的にエクスポートされることを確認する（追加のエクスポート設定は不要）

Research

本プロジェクトはTCNetプロトコルのTypeScript SDKである。型定義はsrc/types.tsに集約され、バイナリパーサーはsrc/network.tsの各パケットクラスに実装されている。MixerData型は現在50フィールド（49フィールド + channels配列）を持ち、TCNetDataPacketMixer.read()がバイトオフセットからフィールドを読み取りオブジェクトを構築する。テストはtests/beatgrid-mixer.test.tsに集約されており、全フィールドのオフセット検証と値アサーションを行っている。公開APIはsrc/index.tsのワイルドカードエクスポートで提供される。

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

`src/types.ts`を更新し、MixerData型をフラット構造からネスト構造へ再設計する。

- 以下の12個のサブタイプを新規定義し、それぞれexportする:
  - `MixerIdentity`: mixerId, mixerType, mixerName
  - `MixerMaster`: audioLevel, faderLevel, filter, cueA, cueB
  - `MixerMic`: eqHi, eqLow
  - `MixerLink`: cueA, cueB
  - `MixerIsolator`: on, hi, mid, low
  - `MixerFilter`: hpf, lpf, resonance
  - `MixerSendFx`: effect, ext1, ext2, masterMix, sizeFeedback, time, hpf, level
  - `MixerSendReturn3`: source, type, on, level
  - `MixerCrossFader`: curve, value, channelCurve
- `MixerBeatFx`: on, levelDepth, channelSelect, select, freqHi, freqMid, freqLow
  - `MixerHeadphones`: preEq, aLevel, aMix, bLevel, bMix
  - `MixerBooth`: level, eqHi, eqLow
- フィールド名はプレフィックスを除去し、グループ内で自明な命名にする（例: `masterAudioLevel` → `master.audioLevel`）
- 既存の`MixerData`型をネスト構造に置き換える: `{ id: MixerIdentity, master: MixerMaster, mic:
MixerMic, link: MixerLink, isolator: MixerIsolator, filter: MixerFilter, sendFx:
MixerSendFx, sendReturn3: MixerSendReturn3, crossFader: MixerCrossFader, beatFx:
MixerBeatFx, headphones: MixerHeadphones, booth: MixerBooth, channels:
MixerChannel[] }`
- `MixerChannel`型は14フィールドで適切なサイズのため変更しない
===============================================================================

Task: 2

`src/network.ts`の`TCNetDataPacketMixer.read()`メソッドのオブジェクト構築部分を、Phase
1で定義したネスト構造に合わせて更新する。

- バイトオフセットからの値読み取りロジック（`readUInt8`等）は一切変更しない
- `this.data = { ... }`のオブジェクトリテラルを、サブオブジェクトを含むネスト形式に変更する
- 各フィールドを対応するサブオブジェクトにグループ化する
- 例: `masterAudioLevel: buffer.readUInt8(61)` → `master: { audioLevel:
buffer.readUInt8(61), ... }`
- Phase 1で定義した全サブタイプ（id, master, mic, link, isolator, filter, sendFx,
sendReturn3, crossFader, beatFx, headphones, booth, channels）に対応するサブオブジェクトを構築する
===============================================================================

Task: 3

`tests/beatgrid-mixer.test.ts`の全MixerDataフィールドアサーションをネスト構造のアクセスパスに更新する。

- フラットアクセスをネストアクセスに変更する（約40箇所）:
  - `d.mixerId` → `d.id.mixerId`
  - `d.masterAudioLevel` → `d.master.audioLevel`
  - `d.sendFxLevel` → `d.sendFx.level`
  - その他全てのフィールドアクセスも同様に変更
- `d.channels[n].sourceSelect`等のチャンネルアクセスは変更しない
- テスト値とバイトオフセット対応は維持する（テストカバレッジを落とさない）
===============================================================================

Task: 4

破壊的変更をChangesetに記録し、新規サブタイプの公開API公開を確認する。

- `.changeset/`ディレクトリに新規changesetファイルを作成する:
  - バンプレベルは`minor`（既存パターンに従う。BREAKING CHANGEは本文で明記）
  - 本文に`BREAKING CHANGE:`を含め、MixerData型の構造変更と移行方法を記載
  - 下流issue（9c5s/tcnet-viewer#41）へのリンクを含める
- 変更内容として全フィールドアクセスパスの変更を例示（例: `mixer.masterAudioLevel` →
`mixer.master.audioLevel`）
- `src/index.ts`の`export * from
"./types"`により新規サブタイプが自動的にエクスポートされることを確認する（追加のエクスポート設定は不要）

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

🔗 Related PRs

#2 - fix: TCNet仕様準拠のプロトコル実装バグ修正 [merged]
#19 - feat: 全DataPacketタイプの専用パケットクラスを実装 [merged]
#22 - docs: Wiki更新 - 実装済みDataPacketクラスのAPI追加と実装状況修正 [merged]
#41 - refactor: TypeScript 5.xモダナイゼーション (#35) [merged]
#69 - fix: PitchBendの型と波形バイト順を仕様に準拠させる [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!