参照の安定性を型にする
Making Referential Stability a Type (jovidecroock.com)
要約
大規模な(P)Reactコードベースでは、useMemoやuseCallbackの使用にもかかわらず、コンポーネントに渡されるプロップの参照の安定性について暗黙的な保証しかなく、予期せぬ再レンダリングの原因となることがあります。この記事では、参照の安定性を型システムに組み込むための「Stable<T>」という型を提案しています。これにより、配列やコールバック関数などが安定した参照であることを型レベルで保証し、開発者が意図しない参照の不安定性によるバグを防ぐことを目指します。
全文翻訳
リファレンス安定性を型にする
2026年7月24日 執筆
ある程度の規模の(P)Reactコードベースに携わったことがあるなら、リファレンス安定性についての議論を嫌というほど経験したことがあるはずです。誰かがuseMemoを追加し、別の人useCallbackを追加し、exhaustive-depsの警告を無視し、そして私たちは次のコンポーネントに渡されるプロップが安定していることを願います。コードは通常正しく動作しますが、この暗黙的な安定性に対する保証は完全ではありません。
私は、新しい配列リテラルがメモ化された子コンポーネントに渡されたことが原因で発生する再レンダリングやエフェクト実行を追いかけるのに、言いたくないほど多くの時間を費やしてきました。宣言された型Item[]や、Item[]として型付けされたプロップは、その形状と形状の中身については教えてくれますが、次のレンダリングで安定した配列が得られるかどうかについては何も教えてくれません。
そこで、私は小さなアイデアを試していました。もしリファレンス安定性の意図が型の一部だったらどうなるだろうか、と。
型
このすべては、プライベートなファントムブランドにかかっています。
declare const stableBrand: unique symbol
type Stable<T> = T extends object ? T & { readonly [stableBrand]: true } : T
オブジェクト、配列、関数はブランド付けされます。プリミティブはそのまま通過します。なぜなら、ReactとPreactはそれらを値で比較するため、stringは常に「十分に安定している」からです。
ここで機能しているのはunique symbolです。もし_stable: trueのような文字列キーを使用していたら、その形状を持つ任意のオブジェクトが偶然ブランドを満たしてしまう可能性があり、誰かが最終的に{ _stable: true }と書くでしょう。パッケージから決して出ないunique symbolは、アプリケーションコードからの構造的な代入では再現できません。Stable<T>と名前を付けることはできますが、それを偽造することはできません。
これにより、プロップはデータ以上のものを記述できるようになります。
type ItemListProps = {
items: Stable<Item[]>
onSelect: Stable<(id: string) => void>
title: string
}
配列とコールバックは安定した意図で構築された参照であり、ブランドを運びます。そして今、インラインで構築された配列は間違った型になります。
<ItemList
items={items.filter(isVisible)}
onSelect={(id) => select(id)}
title="Visible items"
/>
コンポーネントの境界は、要求を呼び出し元に戻します。これはまさに、そうあるべき場所です。
これはまた、memo()やPureComponentの私たちが忘れがちな半分でもあります。コンポーネントをmemoでラップし、値の変更なしに再レンダリングされないと仮定しますが、複雑な型の安定性は保証されず、この最適化が無効になる可能性があります。
フックはそのままに、インポートを置き換える
これらの証明を生成するための私の最初の試みは、モジュール拡張を使用することでした。あなたは副作用のためにパッケージをインポートし、それはReactのフック型を拡張し、useMemoはすべての依存関係が安定しているときにその結果にブランド付けを開始します。
それは半分機能しますが、機能しない半分は理解する価値があります。なぜなら、それは私にとっても奇妙に聞こえた部分であり、その理由を掘り下げるまでそうでした。
モジュール拡張を使用すると、宣言にオーバーロードを追加できます。@types/reactが提供するものを削除したり置き換えたりすることはできません。拡張後、useMemoは2つのオーバーロードが並んで存在することになります。厳密な(factory, deps: StableDeps) => Stable<T>と、Reactの元の(factory, deps: DependencyList) => Tです。TypeScriptはまず厳密なものを試します。すべての依存関係が証明を持っている場合、素晴らしい、あなたはStable<T>を得ます。しかし、1つの依存関係がそうでない瞬間、厳密なオーバーロードは一致しなくなり、解決は静かにReactの元のものにフォールバックします。これは、任意のDependencyListを喜んで受け入れます。
const unstable = {}
const value = useMemo(() => ({ answer: 42 }), [unstable])
// エラーなし。valueは単なる { answer: number } で、ブランドなし
依存関係リストにエラーはありません。私がエラーを期待していた場所です。証明は単に生成されません。そこで私はそれに抵抗するのをやめました。厳密なパスは別のエントリポイントです。
import { useCallback, useEffect, useMemo } from 'stableref/react'
これらは実行時の実際のReactフックであり、より厳密な型宣言の下で公開されています。依存関係タプルは推論され、各未証明の要素は期待される型のアクション可能な文字列リテラルに置き換えられます。このパッケージにはReactの寛容なオーバーロードが含まれていないため、フォールバックするものは何もありません。生の参照は、それが記述された場所で失敗します。
const stableFilter = useCallback(filter, [query])
useMemo(() => source.filter(stableFilter), [source, stableFilter])
// Stable<Item[]> のまま
useMemo(() => source.filter(rawFilter), [source, rawFilter])
// ^ 型エラー
effect(syncSelection, [selection, page])
// ^ page が未証明のオブジェクトの場合に型エラー
パッケージは拡張モードを提供しません。静かに証明を失うことは、実際の強制と間違えるのが簡単すぎます。stableref/reactからインポートすると、悪い依存関係リストは、それが書かれた場所で失敗し、それ以降のどこかで失敗するのではなく、そこで失敗します。
Reactが既に保証しているソースに祝福を
すべての安定した参照がuseMemoから出てくるわけではありません。Reactはいくつか無料で提供しており、型はそのように言うことができます。
const [state, setState] = useState(initialState)
// state: Stable<State>
// setState: Stable<Dispatch<SetStateAction<State>>>
const element = useRef<HTMLElement | null>(null)
// element: Stable<RefObject<HTMLElement | null>>
Stable<State>は、最初に嘘のように読めるため、小さな説明に値します。それは状態が決して変わらないことを意味するのではなく、Reactが変更されなかった状態に新しいIDを製造しないことを意味します。実際の状態遷移は依然としてメモを無効にし、エフェクトを再実行する必要があります。それが状態のポイントです。ブランドは不変性ではなく、アイデンティティに関するものです。
初期化クロージャも証明を必要としません。それらは依存関係リストではありません。
const [state] = useState(() => buildInitialState(props))
const [reduced] = useReducer(reducer, props, createInitialState)
Reactはそれらを初期値の生成にのみ呼び出します。契約は結果の状態とディスパッチャーにブランドを付けますが、初期化クロージャ自体が安定していたかどうかは気にしないため、私はそれを要求しません。
構築によって安定しているモジュールスコープの値については、小さなアイデンティティヘルパーがあります。
export const EMPTY_ITEMS = stable([] as Item[])
実行時にはstable()は値をそのまま返します。x => xです。有用なのは証明であり、関数ではありません。主張が実際に真実であるモジュールスコープに保ってください。
コンテキストは、これがすぐに効果を発揮する場所
インラインコンテキスト値は、サブツリー全体に不要な作業をさせる静かな方法の1つです。
<ThemeContext.Provider value={{ theme, setTheme }}>
{children}
</ThemeContext.Provider>
createStableContextは、その要件をプロバイダーに移動させます。これはフレームワーク固有であるため、パッケージルートではなくReactエントリから取得します。
import { createStableContext } from 'stableref/react'
const ThemeContext = createStableContext<ThemeValue | null>(null)
これで、プロバイダーはStable<ThemeValue>のみを受け入れます。値の所有者はそれをメモ化するジョブも所有し、ツリーの奥深くにあるコンシューマーは、その値がどのように組み立てられたかを知る必要がありません。単に契約を得るだけです。これが私が型から欲しい境界であり、知識はその責任がある場所に留まります。
Preact
同じアイデア、別のエントリポイントです。なぜなら、Preactを置き去りにするわけにはいかなかったからです。
import { useEffect, useMemo, type Stable } from 'stableref/preact'
これらは元のpreact/hooks参照を保持し、同じ厳密な依存関係シグネチャを適用します。証明は値の契約に属しており、どのレンダリングライブラリを選択したかとは実際には関係ありませんでした。
これが解決しないこと
決意した開発者はいつでも次のように書くことができます。
value as Stable<typeof value>
ブランドはキャストに耐えません。これは、TypeScriptでモデル化するほぼすべての保証に当てはまります。私はそれのためのESLintプラグインを出荷しません。アサーションは、レビューと規約が注意を払う必要がある明示的なエスケープハッチのままです。stable()も同様の約束なので、コンパイラを黙らせるためにそれを散りばめないでください。
React Compilerは、人々が持ち出すもう1つのことです。手動メモ化は不要になりますか?多くのケースでは、そうです。しかし、このアイデアが無意味になるとは思いません。なぜなら、両者は異なる質問に答えるからです。コンパイラは「このアイデンティティを自動的に維持できますか?」と尋ねます。Stable<T>は「別のコンポーネントはこのアイデンティティを最適化契約として使用できます」と言います。1つはビルドに存在する実装の詳細であり、もう1つは呼び出し元が見ることができる型グラフに存在する契約です。
エージェントのためのガードレールとしての型エラー
今や多くのReactはコーディングエージェントによって書かれており、メモ化された子にインライン配列を渡すことは、彼らが一日中行うことのまさにそのようなことです。それはうまく読み取れ、うまく実行され、静かに必要以上の作業を行います。これは、目で見つけるのに最も悪い種類のバグです。エージェントはレンダリングしなかった再レンダリングを見ることはできませんが、型エラーには絶対に応答できます。それは既に実行しているフィードバックループです。
だからこそ、エラー自体がいくらかの労力に値するのです。依存関係が証明されていない場合、厳密なフックはそれを生のneverに対して失敗させるのではなく、修正を説明する文字列にマッピングします。
useMemo(() => source.filter(rawFilter), [source, rawFilter])
// 型 '(item: Item) => boolean' は型に割り当て可能ではありません
// 'This dependency is not Stable<T>: memoize it with useMemo/useCallback,
// source it from useState, depend on a useRef container rather than its mutable
// current value, or wrap a module-scope constant with stable().'
指示は診断と一緒に乗り、キャレットは正確な依存関係に配置されます。人間はエディタでそれを読み、エージェントはtscからそれを読み取ります。どちらも「neverに割り当て不可能」に立ち止まって型システムが何を望んでいたのか推測しようとはしません。チェックは「レビューで誰かが気づくことを願う」から「プロップが安定するまでビルドは赤のまま」に移行します。これは、コードが読める速度よりも速く生成されているときに、唯一持ちこたえることができるガードレールです。
より広いアイデア
私が実際に気にかけている部分は、メモ化よりも大きいです。
私たちは、型システムが運ぶことができるプロパティを常に運び回っていますが、それらをコメント、リンティングルール、部族の知識として残しています。リファレンス安定性はそれらの1つですが、唯一のものではありません。一度証明を運ぶようになれば、コンポーネントはそれを要求でき、フックはそれを引き渡すことができ、コンテキストはサブツリー全体でそれを維持できます。
実行時の作業は既に起こっていました。私たちは既にuseMemoを呼び出していました。欠けていた部分は、それが作成された行を過ぎても保証を生き残らせることでした。
私はこれをstablerefとしてパッケージ化しています。現時点ではライブラリというより実験なので、どこで壊れるかぜひ教えてください。