signals-dart

Signals Core の高度なプリミティブ

このスキルでは、signals_core の高度な状態管理プリミティブ、リアクティブなコレクション、非同期機能、値オプションのセマンティクスについて説明します。

関連ドキュメントと項目

コアプリミティブ

関連ファイル	説明
signal.md	値アクセサー、変更の仕組み、基本的なカスタムオプションを備えた、標準的な書き込み可能リアクティブ状態プリミティブです。
computed.md	リアクティブな依存関係を動的に追跡する、遅延評価されるメモ化済みの読み取り専用派生状態シグナルです。
effect.md	アクティブなサブスクリプションループ、動的な依存関係の更新、ライフサイクルの解除を管理する同期オブザーバーです。
readonly.md	一方向のデータアクセスフローを保証する読み取り専用シグナルビューです。
batch.md	リアクティブな計算を最適化し、描画や再計算の過剰な発生を防ぐ、トランザクション形式の状態変更ブロックです。

非同期処理

関連ファイル	説明
future_signal.md	二重評価の問題を解決する、単一評価の非同期 Future 状態表現です。
stream_signal.md	非同期の読み込み／データ／エラー状態に対応付ける、動的でライフサイクルに安全な自動破棄型ストリームリスナーです。
async_signal.md	読み込み、成功データ、失敗エラーの各状態を明確に対応付ける、統合型の非同期状態コンテナーです。
computed_async.md	アクティブな競合状態の保護機能を備え、リアクティブシグナル上に構築された合成可能な非同期処理です。
computed_from.md	複数の非同期シグナルを単一の統合結果にまとめる状態集約シグナルです。

リアクティブなコレクション

関連ファイル	説明
list_signal.md	要素レベルのリアクティビティをサポートするため、標準的な操作をプロキシする最適化済みリストラッパーです。
set_signal.md	重複を無視し、一意な変更時に通知するカスタムセットラッパーです。
map_signal.md	辞書要素の個別検索をトリガーできる、細粒度のマップラッパーです。
iterable_signal.md	カスタムの遅延トラバーサルを動的なサブスクリプション層に対応付けるイテラブルラッパーです。
queue_signal.md	最適化されたリアクティブパイプライン構造をサポートする両端キューラッパーです。

ユーティリティプリミティブ

関連ファイル	説明
linked_signal.md	手動での上書きリセットとカスタムの同値性チェックをサポートする、書き込み可能な計算シグナルです。
tracked_signal.md	すぐに利用できる簡潔な元に戻す／やり直す機能を実現する状態履歴ラッパーです。
timer_signal.md	一時停止、再開、リセット機能を内蔵した、定期的に値を出力するストップウォッチシグナルです。
connect.md	複数の外部データパイプラインから単一のターゲットにデータを送る動的イベントコネクターです。

---

コアプリミティブ クイックスタートガイド

signals ライブラリは、あらゆるリアクティブなビジネスロジックをモデル化するための構成要素となる、5 つのコア関数を提供します。

1. signal(initialValue)

新しい変更可能なシグナルコンテナーを作成します。.value にアクセスすると、シグナルの値を読み取るか、更新を購読できます。

final counter = signal(0);
print(counter.value); // 0
counter.value = 1; // Mutates value and schedules dependent updates

.peek()

変更を購読せずに、シグナルの現在の値を読み取ります。

final counter = signal(0);
final logCount = signal(0);

effect(() {
  print(counter.value);
  // Read using peek to avoid subscribing/triggering loop
  logCount.value = logCount.peek() + 1;
});

2. untracked(fn)

シグナルを読み取っても、どのシグナルも購読しないコールバックを実行します。

final counter = signal(0);
final count = signal(0);

effect(() {
  print(counter.value);
  count.value = untracked(() => count.value + 1);
});

3. computed(fn)

複数のシグナルの値を組み合わせ、遅延評価されるメモ化済みの派生シグナルを作成します。

final first = signal('John');
final last = signal('Doe');
final fullName = computed(() => '${first.value} ${last.value}');
print(fullName.value); // John Doe

4. effect(fn)

コールバックを実行し、その中で読み取られたシグナルを購読することで、即時の同期的な副作用を調整します。

final name = signal('Jane');
final dispose = effect(() => print('Hello $name'));
dispose(); // Clean up subscription

5. batch(fn)

複数のシグナルへの書き込みを単一のトランザクションにまとめ、依存するすべての計算シグナルの評価とエフェクトを、最後にそれぞれ一度だけ実行します。

final a = signal(0);
final b = signal(0);

batch(() {
  a.value = 1;
  b.value = 2;
});

---

1. 書き込み可能な計算済みシグナル（linkedSignal）

書き込み可能な計算済みシグナル（LinkedSignal）は、派生したデフォルト値を提供します。この値は手動で上書きでき、上流の依存関係が変更されるたびに派生したデフォルト値にリセットされます。

使用方法

// Basic reset shorthand:
final size = signal('M');
final selection = linkedSignal(() => size.value);

// Advanced structural comparison:
final user = signal((id: 1, name: 'Alice'));
final name = linkedSignal<String, ({int id, String name})>(
  () => user.value,
  options: LinkedSignalOptions(
    computation: (u, prev) {
      if (prev != null && prev.source.id == u.id) {
        return prev.value; // Retain manual override
      }
      return u.name; // Reset on ID changes
    },
  ),
);

---

2. コレクションと非同期プリミティブ

A. コレクション

コレクションをラップするには、常に専用のコレクション（listSignal、setSignal、mapSignal など）を使用し、最適化された変更処理を実現してください（要素が実際に変更された場合にのみ更新がトリガーされます）。

final list = listSignal([1, 2], options: ListSignalOptions(autoDispose: true));
list.add(3); // Reacts to changes

B. 最適化された FutureSignal

FutureSignal は AsyncSignal を直接継承し、Stream のサブスクリプションによるオーバーヘッドを回避します。また、計算の実行を通じて依存関係を手動で追跡し、Future の計算を正確に1回だけ実行します（評価が二重に行われるループを回避します）。

final search = signal('');
final results = futureSignal(() => fetchResults(search.value));

---

3. オプションクラスの値セマンティクス

すべてのシグナルオプションオブジェクトは、柔軟なコピーと正確な比較を可能にする完全な値セマンティクス（copyWith、カスタム等価性、hashCode のオーバーライド）をサポートします。

• SignalOptions
• ComputedOptions
• AsyncSignalOptions
• LinkedSignalOptions
• ListSignalOptions / SetSignalOptions / MapSignalOptions