@aiquants/virtualscroll 3.10.0 → 3.11.1

package/src/logger.ts

@@ -47,7 +47,7 @@ export interface ILogger {
  */
 export class Logger implements ILogger {
     private level: LogLevel
-    private prefix: string
+    private readonly prefix: string
     private impl: ILogger
 
     /**
@@ -104,26 +104,6 @@ export class Logger implements ILogger {
         this.impl = impl
     }
 
-    /**
-     * @method setPrefix
-     * @description Updates the log prefix for the static instance.
-     * @description 静的インスタンスのログのプレフィックスを更新します。
-     * @param {string} prefix - The new prefix.
-     */
-    static setPrefix(prefix: string): void {
-        Logger.instance.setPrefix(prefix)
-    }
-
-    /**
-     * @method setPrefix
-     * @description Updates the log prefix.
-     * @description ログのプレフィックスを更新します。
-     * @param {string} prefix - The new prefix.
-     */
-    setPrefix(prefix: string): void {
-        this.prefix = prefix
-    }
-
     /**
      * @method isEnabled
      * @description Returns whether the given level would be emitted at the current level (static instance).
@@ -197,10 +177,6 @@ export class Logger implements ILogger {
         }
     }
 
-    static info(message?: unknown, ...optionalParams: unknown[]): void {
-        Logger.instance.info(message, ...optionalParams)
-    }
-
     info(message?: unknown, ...optionalParams: unknown[]): void {
         if (this.level <= LogLevel.INFO) {
             this.impl.info(...this.formatMessage(Logger.resolveLazy(message)), ...optionalParams.map(Logger.resolveLazy))

package/src/useFenwickMapTree.ts

@@ -11,7 +11,7 @@
  * それを管理するための React フック `useFenwickMapTree` の提供。
  * 動的なアイテムサイズを持つ仮想スクロールのシナリオに最適化されている。
  */
-import { useRef } from "react"
+import { useCallback, useReducer, useRef } from "react"
 import { Logger } from "./logger.ts"
 import { minmax } from "./utils.ts"
 
@@ -33,20 +33,15 @@ type DeltaUpdate = { index: number; change: number }
 type ValueUpdate = { index: number; value: number }
 
 /**
- * Converts a numeric size into a non-negative bigint, safeguarding against fractional input.
+ * The options of a tree read that only looks rows up and never materialises them (`prefixSum`, `get`, `getTotal`,
+ * `findIndexAtOrAfter`, `findIndexAtOrBefore`): the read leaves the stored values, the size and `revision` as they are. One
+ * frozen value that every lookup passes, so no caller spells the option out. Internal to the package (not in the barrel).
  *
- * 分数入力を安全に丸めてから非負の bigint へ変換。
+ * 行を引くだけで具現化しない木の読み取り (`prefixSum`・`get`・`getTotal`・`findIndexAtOrAfter`・`findIndexAtOrBefore`) の選択肢。
+ * 読み取りは保持する値・要素数・`revision` をそのまま残す。どの引き当ても渡す凍結した 1 つの値で、呼び出し側は選択肢を書き下さない。
+ * パッケージの内部用 (バレル非公開)。
  */
-const toSafeBigInt = (value: number): bigint => {
-    if (!Number.isFinite(value)) {
-        return 0n
-    }
-    const truncated = Math.trunc(value)
-    if (truncated <= 0) {
-        return 0n
-    }
-    return BigInt(truncated)
-}
+export const FENWICK_LOOKUP_ONLY = Object.freeze({ materializeOption: Object.freeze({ materialize: false }) })
 
 /**
  * Validates that `valueFn` returned a finite number, throwing otherwise. A single NaN/Infinity
@@ -75,14 +70,17 @@ const requireFiniteValue = (value: number, index: number): number => {
 const NEGATIVE_EFFECTIVE_VALUE_EPSILON = 1e-9
 
 /**
- * Derives the lowest set bit without relying on 32-bit bitwise operators.
+ * Derives the lowest set bit of a 1-based tree index (a positive integer) without relying on 32-bit bitwise operators. Every
+ * caller walks the tree from such an index, so the result is at least 1 and each walk ends: a walk up adds it until the index
+ * passes the size, a walk down subtracts it until the index reaches 0.
+ *
+ * 1 始まりの木の添字 (正の整数) の最下位ビットを、32 ビット演算に依存せずに求める処理。呼び出し元はどれもそのような添字から木を
+ * 辿るので、結果は 1 以上で、どの辿り方も終わる (上へ辿ると足して添字が要素数を越え、下へ辿ると引いて添字が 0 に着く)。
  *
- * 32 ビット演算に依存せずに最下位ビットを算出。
+ * @param value - A 1-based tree index (a positive integer) / 1 始まりの木の添字 (正の整数)
+ * @returns The lowest set bit (1 or more) / 最下位ビット (1 以上)
  */
 const getLowestSetBit = (value: number): number => {
-    if (value <= 0 || !Number.isFinite(value)) {
-        return 0
-    }
     const integer = Math.trunc(value)
     // 32 ビット符号付き整数の範囲内なら通常のビット演算で最下位ビットを求める (BigInt 割り当てを回避)。
     // ホットパス (prefixSum / _updateTree など) の GC 圧を大幅に削減する。
@@ -154,6 +152,13 @@ export class FenwickMapTree {
     private valueFn?: (index: number) => number
     private total?: number
 
+    /**
+     * @private
+     * @property {number} revisionCount - The counter behind `revision`: raised by every change of a stored value or of the size.
+     * @property {number} revisionCount - `revision` の元の数。保持する値か要素数が変わるたびに上がる。
+     */
+    private revisionCount = 0
+
     /**
      * @constructor
      * @description Initializes the Fenwick Tree.
@@ -193,6 +198,7 @@ export class FenwickMapTree {
             this.valueFn = undefined
             this.baseValue = valueOrFn
             this.total = this.baseValue * this.size
+            this.revisionCount += 1
             return
         }
 
@@ -276,11 +282,9 @@ export class FenwickMapTree {
         this.valueFn = valueOrFn
         this.baseValue = baseValue
         if (seed) {
+            // 種は [from, to] (to < size) の値なので、添字は要素数を越えない
             for (let i = 0; i < seed.values.length; i++) {
                 const index = seed.from + i
-                if (index >= this.size) {
-                    break
-                }
                 // _materialize を呼ぶ代わりに、計算フェーズの検証済みの値を使って更新する (二重評価を回避)
                 const change = seed.values[i] - this.baseValue
                 // baseValue と一致する行は delta を持たせない (Map の無駄な肥大を回避)
@@ -292,6 +296,7 @@ export class FenwickMapTree {
         }
         // 具現化が完了した後に total を計算する
         this.total = this.getTotal()
+        this.revisionCount += 1
     }
 
     /**
@@ -318,6 +323,7 @@ export class FenwickMapTree {
             // baseValue を差し替えたら total を再計算しないと prefixSum と乖離する。
             // (deltas は温存されるため sum(deltas) + baseValue * size に一致させる)
             this.total = this._computeTreeTotal()
+            this.revisionCount += 1
         }
     }
 
@@ -348,10 +354,6 @@ export class FenwickMapTree {
      * @returns {number} The representative base value.
      */
     private static _modeOrMedian(values: number[]): number {
-        if (values.length === 0) {
-            return 0
-        }
-
         // 中央値を計算してデフォルトの最頻値として設定
         values.sort((a, b) => a - b)
         const mid = Math.floor(values.length / 2)
@@ -402,10 +404,6 @@ export class FenwickMapTree {
      * @returns {number} The estimated base value.
      */
     private static _sampleBaseValueStrided(valueFn: (index: number) => number, size: number, sampleCount: number): number {
-        if (size <= 0) {
-            return 0
-        }
-
         // stride = max(1, ceil(size / sampleCount)) を基準に、偶数なら +1 して奇数化する。
         // ceil によりサンプル数を多少犠牲にしても必ずリスト全域を跨ぐ (_modeOrMedian の
         // 20% しきい値は割合ベースのためサンプル数減の影響は受けない)。
@@ -526,15 +524,12 @@ export class FenwickMapTree {
         if (change === 0) {
             return
         }
+        this.revisionCount += 1
         // tree Map を更新
         let treeIndex = index + 1 // Fenwick Tree のアルゴリズムは 1 始まりで設計される
         while (treeIndex <= this.size) {
             this.tree.set(treeIndex, (this.tree.get(treeIndex) ?? 0) + change)
-            const step = getLowestSetBit(treeIndex)
-            if (step === 0) {
-                break
-            }
-            treeIndex += step
+            treeIndex += getLowestSetBit(treeIndex)
         }
 
         // 合計値を更新 (totalが計算済みの場合のみ)
@@ -575,7 +570,8 @@ export class FenwickMapTree {
             }
 
             // 現在の delta はバッチ内で既に更新済みならその値を、なければ Map の値を使う
-            const currentDelta = pendingDeltas.has(index) ? (pendingDeltas.get(index) ?? 0) : (this.deltas.get(index) ?? 0)
+            const pendingDelta = pendingDeltas.get(index)
+            const currentDelta = pendingDelta === undefined ? (this.deltas.get(index) ?? 0) : pendingDelta
             const oldValue = currentDelta + this.baseValue
             const change = value - oldValue
             if (change !== 0) {
@@ -603,11 +599,7 @@ export class FenwickMapTree {
         let treeIndex = this.size
         while (treeIndex > 0) {
             sum += this.tree.get(treeIndex) ?? 0
-            const step = getLowestSetBit(treeIndex)
-            if (step === 0) {
-                break
-            }
-            treeIndex -= step
+            treeIndex -= getLowestSetBit(treeIndex)
         }
 
         return sum + this.baseValue * this.size
@@ -717,7 +709,7 @@ export class FenwickMapTree {
             return this._findIndexLarge(target, options, chooseLowerBound)
         }
         if (this.size === 0) {
-            return { index: -1, total: this.total ?? 0, cumulative: undefined, currentValue: undefined, safeIndex: undefined }
+            return { index: -1, total: this.getTotal(), cumulative: undefined, currentValue: undefined, safeIndex: undefined }
         }
 
         // 探索前に対象範囲を具現化しておく。具現化後のツリー状態で降下を行うことで、
@@ -737,7 +729,7 @@ export class FenwickMapTree {
             resultIdx = this._descend(target, chooseLowerBound)
 
             if (resultIdx < 0 || resultIdx >= this.size) {
-                return { index: -1, total: this.total ?? this.getTotal(), cumulative: undefined, currentValue: undefined, safeIndex: undefined }
+                return { index: -1, total: this.getTotal(), cumulative: undefined, currentValue: undefined, safeIndex: undefined }
             }
 
             if (!materialize) {
@@ -759,7 +751,7 @@ export class FenwickMapTree {
 
         return {
             index: resultIdx,
-            total: this.total ?? result.total,
+            total: this.getTotal(),
             cumulative: result.cumulative,
             currentValue: result.currentValue,
             safeIndex: result.safeIndex,
@@ -812,14 +804,8 @@ export class FenwickMapTree {
      * 非常に大きなサイズに対して bigint 演算を用いた二分探索を実施。
      */
     private _findIndexLarge(target: number, options: MaterializeConfig, chooseLowerBound: boolean): { index: number; total: number | undefined; cumulative: number | undefined; currentValue: number | undefined; safeIndex: number | undefined } {
-        if (this.size === 0) {
-            return { index: -1, total: this.total ?? 0, cumulative: undefined, currentValue: undefined, safeIndex: undefined }
-        }
-
-        const sizeBig = toSafeBigInt(this.size)
-        if (sizeBig === 0n) {
-            return { index: -1, total: this.total ?? 0, cumulative: undefined, currentValue: undefined, safeIndex: undefined }
-        }
+        // 呼び出し元 (_findIndex) は要素数 2^30 以上のときだけここへ来るので、要素数は正の整数
+        const sizeBig = BigInt(this.size)
 
         // 小サイズパス (_findIndex) と同一契約: 探索前に対象範囲を具現化し、探索中は木を
         // 変異させない (prefixSum に options を渡さない)。materialize:true の場合は
@@ -904,7 +890,7 @@ export class FenwickMapTree {
         // 空の木 (size=0) は正当な状態として中立値を返す (throw しない)。
         // minmax(index, 0, -1) が負値へ丸められ get(-1) が throw するのを回避する。
         if (this.size === 0) {
-            return { cumulative: 0, total: this.total ?? 0, currentValue: 0, safeIndex: 0 }
+            return { cumulative: 0, total: this.getTotal(), currentValue: 0, safeIndex: 0 }
         }
         // 小数 index は具現化時に非整数キーのノードを作り整数走査と乖離するため切り捨てる
         // (Infinity は trunc を素通りした後 minmax で size-1 にクランプされる)。
@@ -918,11 +904,7 @@ export class FenwickMapTree {
         while (treeIndex > 0) {
             const treeNodeValue = this.tree.get(treeIndex) ?? 0
             sum += treeNodeValue
-            const step = getLowestSetBit(treeIndex)
-            if (step === 0) {
-                break
-            }
-            treeIndex -= step
+            treeIndex -= getLowestSetBit(treeIndex)
         }
 
         const currentValue = materializeOption?.materialize ? this.get(safeIndex) : (this.deltas.get(safeIndex) || 0) + this.baseValue
@@ -972,10 +954,6 @@ export class FenwickMapTree {
                 this.total = 0
             } else {
                 this.total = this._computeTreeTotal()
-                const lastPrefix = this.prefixSum(this.getSize() - 1)
-                if (lastPrefix.cumulative !== lastPrefix.total) {
-                    Logger.error("Inconsistent Fenwick Tree state")
-                }
             }
         }
 
@@ -987,11 +965,11 @@ export class FenwickMapTree {
      * @description Rebuilds the Fenwick Tree from the existing `baseValue` and `deltas`. This corrects any discrepancies in the tree's internal state, such as those caused by floating-point errors, by recalculating the tree structure and the total sum from the source `deltas`. This method does not re-materialize values from `valueFn`.
      * @description 既存の `baseValue` と `deltas` から Fenwick Tree を再構築します。これにより、`deltas` からツリー構造と合計値を再計算することで、浮動小数点誤差などによって生じた内部状態の不一致を修正します。このメソッドは `valueFn` から値を再具現化しません。
      * @param {object} [options] - Optional settings for rebuilding.
-     * @param {boolean} [options.materialize=false] - If true and `valueFn` is provided, re-materializes all values, recalculating `deltas` and `baseValue`.
+     * @param {boolean} [options.materialize=false] - If true and `valueFn` is set, rebuilds from `valueFn` instead: a reset with materialization (`reset(size, valueFn, { materialize: true })`) that re-samples `baseValue`, materializes the initial window (rows 0 to `SAMPLE_COUNT - 1`) and discards every other measured delta. A tree with a uniform value (no `valueFn`) rebuilds from its deltas either way. / true かつ `valueFn` があれば、代わりに `valueFn` から作り直す。具現化付きのリセット (`reset(size, valueFn, { materialize: true })`) で、`baseValue` を標本で決め直し、初期の窓 (行 0〜`SAMPLE_COUNT - 1`) を具現化し、ほかの測った差分はすべて捨てる。一様な値の木 (`valueFn` 無し) はどちらでも差分から作り直す。
      */
     rebuildTree(options?: { materialize?: boolean }) {
         if (options?.materialize && this.valueFn) {
-            // すべての値を具現化する
+            // 全行の具現化は巨大な木で O(n) の valueFn 呼び出しになるので、リセットと同じく初期の窓だけを具現化する
             const valueFn = this.valueFn
             this.reset(this.size, (i) => valueFn(i), { materialize: true })
             return
@@ -1001,25 +979,21 @@ export class FenwickMapTree {
         // let newTotal = this.baseValue * this.size
 
         // 既存の deltas を使って新しいツリーを構築し、合計値も同時に再計算する
+        // 0 の delta は保持しない (zero-delta 枝刈り) ので、どの delta も木へ伝える
         for (const [index, delta] of this.deltas.entries()) {
-            if (delta === 0) {
-                continue
-            }
             // Fenwick Tree のアルゴリズムは 1 始まりで設計されるため、インデックスを 1 加算する
             let treeIndex = index + 1
             while (treeIndex <= this.size) {
                 newTree.set(treeIndex, (newTree.get(treeIndex) ?? 0) + delta)
-                const step = getLowestSetBit(treeIndex)
-                if (step === 0) {
-                    break
-                }
-                treeIndex += step
+                treeIndex += getLowestSetBit(treeIndex)
             }
         }
 
         // 最後に状態をアトミックに更新
         this.tree = newTree
         this.total = this._computeTreeTotal()
+        // 値は変えないが、浮動小数点の誤差を直した接頭辞和は変わり得る
+        this.revisionCount += 1
     }
 
     /**
@@ -1034,11 +1008,6 @@ export class FenwickMapTree {
      * @returns {number} The difference between the cached total and the theoretical total.
      */
     calculateAccumulatedError(): number {
-        if (this.total === undefined) {
-            // total がまだ計算されていない場合は、誤差は 0 とする
-            return 0
-        }
-
         // 理論上の合計値を計算する。範囲外へ退避している delta は木に載っていないので数えない
         let theoreticalTotal = this.baseValue * this.size
         for (const [index, delta] of this.deltas) {
@@ -1048,7 +1017,7 @@ export class FenwickMapTree {
         }
 
         // キャッシュされている合計値との差を返す
-        return this.total - theoreticalTotal
+        return this.getTotal() - theoreticalTotal
     }
 
     /**
@@ -1140,11 +1109,7 @@ export class FenwickMapTree {
             this.size = targetSize
             this.rebuildTree()
         }
-
-        const lastPrefix = this.prefixSum(this.getSize() - 1)
-        if (lastPrefix.cumulative !== lastPrefix.total) {
-            Logger.error("Inconsistent Fenwick Tree state")
-        }
+        this.revisionCount += 1
     }
 
     /**
@@ -1190,20 +1155,12 @@ export class FenwickMapTree {
         // 既存範囲 (<= oldSize) のノードは更新済みなので、
         // 親チェーンを辿って oldSize を超える最初のノードまで進める。
         while (treeIndex <= oldSize) {
-            const step = getLowestSetBit(treeIndex)
-            if (step === 0) {
-                break
-            }
-            treeIndex += step
+            treeIndex += getLowestSetBit(treeIndex)
         }
         // 新たに有効化されたノード (oldSize, newSize] にのみ差分を伝播する。
         while (treeIndex <= newSize) {
             this.tree.set(treeIndex, (this.tree.get(treeIndex) ?? 0) + delta)
-            const step = getLowestSetBit(treeIndex)
-            if (step === 0) {
-                break
-            }
-            treeIndex += step
+            treeIndex += getLowestSetBit(treeIndex)
         }
     }
 
@@ -1246,9 +1203,8 @@ export class FenwickMapTree {
 
         // total は増分 (+= baseValue * Δ) ではなく prefixSum と同一走査を再現する
         // _computeTreeTotal で確定する。増分加算は浮動小数点の分配則不成立により
-        // prefixSum の走査結果と厳密不一致になり、changeSize 末尾の整合検査が
-        // 偽の "Inconsistent Fenwick Tree state" を量産するため。O(log n) なので
-        // 増分更新の速度メリットは保たれる。
+        // prefixSum(size - 1) の走査結果と厳密には一致せず、末尾の位置で total と
+        // 最後の行の下端が食い違うため。O(log n) なので増分更新の速度メリットは保たれる。
         this.total = this._computeTreeTotal()
     }
 
@@ -1291,6 +1247,23 @@ export class FenwickMapTree {
         return this.baseValue
     }
 
+    /**
+     * @description Gets the tree's revision: a counter that rises whenever a value the tree stores or its size changes — an
+     * update, a materialization that changes a row, a reset, a resize, a new uniform value or a rebuild — and stays the same
+     * otherwise (reads, a materialization that finds the stored value, an update to the same value, a resize to the same size).
+     * The tree keeps its identity while its contents change, so a caller that derives anything from the prefix sums (row tops,
+     * a rendering range) compares two reads: equal reads mean nothing it derived became stale in between. The counter only
+     * rises; how far it rises per change is unspecified.
+     * @description 木の版を取得。木が保持する値か要素数が変わるたび (更新・行を変える具現化・リセット・要素数の変更・一様な値の
+     * 差し替え・再構築) に上がり、それ以外 (読み取り・保持する値と同じ値を見つけた具現化・同じ値への更新・同じ要素数への変更) では
+     * 変わらない数。木は中身が変わっても同一性を保つため、接頭辞和から何か (行の上端・描画範囲) を導く呼び出し側は 2 回の読み取りを
+     * 比べ、等しければその間に導いたものは古くなっていない。数は上がるだけで、1 回の変化でいくつ上がるかは決めない。
+     * @returns {number} The revision. 版。
+     */
+    get revision(): number {
+        return this.revisionCount
+    }
+
     /**
      * @method findIndexAtOrAfter
      * @description Finds the first index where the cumulative sum is greater than or equal to a target value.
@@ -1470,3 +1443,73 @@ export const useFenwickMapTree = (size: number, valueOrFn: number | ((index: num
 
     return tree
 }
+
+/**
+ * What `useFenwickTreeRevision` returns: the revision the memos that read one tree depend on, and the one way to change that
+ * tree outside render so that they see the change.
+ *
+ * `useFenwickTreeRevision` の戻り値。1 本の木を読む memo が依存する版数と、memo が変化に気付くように描画の外でその木を変える
+ * ただ 1 つの方法。
+ */
+export type FenwickTreeRevision = {
+    /** Advances by one per change made through `change` that moved the tree's revision / `change` を通した変更が木の版を動かすたびに 1 つ進む数 */
+    readonly revision: number
+    /** Runs one change of the tree made outside render and returns its result; advances `revision` only when the tree's revision moved / 描画の外で行う木の変更を 1 回実行してその結果を返し、木の版が動いたときだけ `revision` を進める処理 */
+    readonly change: <Result>(mutate: () => Result) => Result
+}
+
+/**
+ * Advances a component's tree revision by one (the reducer behind `FenwickTreeRevision["revision"]`).
+ *
+ * コンポーネントの木の版数を 1 つ進める処理 (`FenwickTreeRevision["revision"]` の reducer)。
+ *
+ * @param revision - The current revision / 今の版数
+ * @returns The next revision / 次の版数
+ */
+const nextTreeRevision = (revision: number): number => revision + 1
+
+/**
+ * Ties the memos of a component to the contents of a Fenwick tree. The tree keeps its identity while its contents change
+ * (`useFenwickMapTree`), so a memo that derives anything from its prefix sums (row tops, a rendering range, the placed
+ * columns) cannot see a change through the tree itself, and the total is no signal either: a batch of changes that cancel out
+ * leaves it as it was. Every change made outside render goes through `change`, which advances `revision` exactly when the
+ * tree's own revision (`FenwickMapTree.revision`) moved, so the next commit recomputes the memos that depend on `revision`,
+ * and a change that stores the same values (an update to the value a row already has, a materialisation that finds the stored
+ * value) adds no commit. Changes made during render (a reset or a resize by `useFenwickMapTree`) come with new props, which the
+ * memos depend on already. Internal to the package (not in the barrel).
+ *
+ * コンポーネントの memo を Fenwick 木の中身に結び付けるフック。木は中身が変わっても同一性を保つ (`useFenwickMapTree`) ので、
+ * 接頭辞和から何か (行の上端・描画範囲・配置した列) を導く memo は木そのものからは変化に気付けず、総和も合図にならない (打ち消し合う
+ * 変更の組は総和を変えない)。描画の外の変更はすべて `change` を通し、`change` は木自身の版 (`FenwickMapTree.revision`) が動いたとき
+ * ちょうどに `revision` を進める。だから次の確定は `revision` に依存する memo を計算し直し、同じ値を保つ変更 (行が既に持つ値への更新・
+ * 保持する値と同じ値を見つけた具現化) は確定を足さない。描画中の変更 (`useFenwickMapTree` のリセットと大きさの変更) は新しい props と
+ * 一緒に来るので、memo は既にそれに依存している。パッケージの内部用 (バレル非公開)。
+ *
+ * @param tree - The tree whose changes the memos must see / memo が変化に気付くべき木
+ * @returns The revision and the change runner / 版数と変更の実行関数
+ */
+export const useFenwickTreeRevision = (tree: FenwickMapTree): FenwickTreeRevision => {
+    const [revision, advanceRevision] = useReducer(nextTreeRevision, 0)
+
+    /**
+     * Runs one change of the tree and advances the revision when the tree's revision moved.
+     *
+     * 木の変更を 1 回実行し、木の版が動いたら版数を進める処理。
+     *
+     * @param mutate - The change of the tree / 木の変更
+     * @returns What `mutate` returned / `mutate` の戻り値
+     */
+    const change = useCallback(
+        <Result>(mutate: () => Result): Result => {
+            const revisionBefore = tree.revision
+            const result = mutate()
+            if (tree.revision !== revisionBefore) {
+                advanceRevision()
+            }
+            return result
+        },
+        [tree],
+    )
+
+    return { revision, change }
+}

package/src/useLruCache.ts

@@ -90,6 +90,16 @@ class DoublyLinkedList<K, V> {
         node.next = null
     }
 
+    /**
+     * Returns the head of the list (the least recently used item) without removing it.
+     * リストの先頭 (最も最近使用されていないアイテム) を外さずに返す処理。
+     *
+     * @returns {DoublyLinkedListNode<K, V> | null} The head node, or null if the list is empty / 先頭のノード (空なら null)
+     */
+    peekHead(): DoublyLinkedListNode<K, V> | null {
+        return this.head
+    }
+
     /**
      * @method removeHead
      * @description Removes and returns the head of the list, which is the least recently used item.
@@ -176,14 +186,10 @@ export function useLruCache<K, V>(capacity: number) {
         if (!Number.isFinite(normalizedCapacity)) {
             return
         }
-        while (cache.current.size > normalizedCapacity) {
-            const lruNode = list.current.removeHead()
-            if (lruNode) {
-                cache.current.delete(lruNode.key)
-            } else {
-                // This should not happen if cache.current.size > 0
-                break
-            }
+        // 使用順の一覧と Map は同じ項目を持つので、Map が容量を超えている間は一覧の先頭が必ずある
+        for (let lruNode = list.current.peekHead(); lruNode !== null && cache.current.size > normalizedCapacity; lruNode = list.current.peekHead()) {
+            list.current.remove(lruNode)
+            cache.current.delete(lruNode.key)
         }
     }, [capacity, normalizedCapacity])