@aiquants/virtualscroll 1.18.5 → 1.19.0

package/src/useHeightCache.ts

@@ -0,0 +1,32 @@
+/**
+ * @module useHeightCache
+ * @description This module provides a hook for caching item heights using an LRU (Least Recently Used) cache.
+ * It is designed to be used in virtual scrolling components to optimize performance by storing and retrieving the heights of rendered items.
+ *
+ * @description このモジュールは、LRU (Least Recently Used) キャッシュを使用してアイテムの高さをキャッシュするためのフックを提供します。
+ * 仮想スクロールコンポーネントで使用されることを想定しており、レンダリングされたアイテムの高さを保存および取得することでパフォーマンスを最適化します。
+ */
+import { useMemo } from "react"
+import { useLruCache } from "./useLruCache.ts"
+
+// LRU キャッシュに保存する高さの測定値の最大数
+const HEIGHT_CACHE_CAPACITY = 10000
+
+/**
+ * A custom hook that provides a cache for storing the heights of items, backed by an LRU cache.
+ * This helps in optimizing virtual scrolling by avoiding re-computation of item heights.
+ * The key is the item's index (number), and the value is its height (number).
+ *
+ * LRU キャッシュを利用して、アイテムの高さを保存するためのキャッシュを提供するカスタムフック。
+ * これにより、アイテムの高さの再計算を回避し、仮想スクロールを最適化します。
+ * キーはアイテムのインデックス (number)、値はその高さ (number) です。
+ */
+export const useHeightCache = () => {
+    // useLruCache フックを初期化し、指定された容量でキャッシュインスタンスを作成
+    const { get, set, has, clear } = useLruCache<number, number>(HEIGHT_CACHE_CAPACITY)
+
+    // キャッシュを操作するための関数 (get, set, has, clear) を安定参照のオブジェクトで返す。
+    // 毎レンダー新しいオブジェクトを返すと、戻り値を依存配列に入れた呼び出し側のメモ化が無効化されるため useMemo で安定化する。
+    // Return a memoized object so consumers depending on it in dep arrays are not invalidated every render.
+    return useMemo(() => ({ get, set, has, clear }), [get, set, has, clear])
+}

package/src/useLruCache.spec.ts

@@ -0,0 +1,382 @@
+/**
+ * @fileoverview Tests for useLruCache hook.
+ * useLruCache フックのテスト。
+ */
+
+import { act, renderHook } from "@testing-library/react"
+import { describe, expect, it, vi } from "vitest"
+import { useLruCache } from "./useLruCache"
+
+describe("useLruCache フック", () => {
+    it("値を追加して取得できる", () => {
+        const { result } = renderHook(() => useLruCache<string, number>(2))
+
+        act(() => {
+            result.current.set("alpha", 1)
+            result.current.set("beta", 2)
+        })
+
+        expect(result.current.get("alpha")).toBe(1)
+        expect(result.current.get("beta")).toBe(2)
+        expect(result.current.has("alpha")).toBe(true)
+        expect(result.current.has("beta")).toBe(true)
+    })
+
+    it("容量を超えると最も古い要素を削除する", () => {
+        const { result } = renderHook(() => useLruCache<string, number>(2))
+
+        act(() => {
+            result.current.set("first", 1)
+            result.current.set("second", 2)
+            result.current.set("third", 3)
+        })
+
+        expect(result.current.has("first")).toBe(false)
+        expect(result.current.has("second")).toBe(true)
+        expect(result.current.has("third")).toBe(true)
+    })
+
+    it("get の呼び出しで要素を最新扱いにする", () => {
+        const { result } = renderHook(() => useLruCache<string, number>(2))
+
+        act(() => {
+            result.current.set("first", 1)
+            result.current.set("second", 2)
+            result.current.get("first")
+            result.current.set("third", 3)
+        })
+
+        expect(result.current.has("first")).toBe(true)
+        expect(result.current.has("second")).toBe(false)
+        expect(result.current.has("third")).toBe(true)
+    })
+
+    it("remove で指定キーを削除する", () => {
+        const { result } = renderHook(() => useLruCache<string, number>(2))
+
+        act(() => {
+            result.current.set("alpha", 1)
+            result.current.set("beta", 2)
+            result.current.remove("alpha")
+        })
+
+        expect(result.current.has("alpha")).toBe(false)
+        expect(result.current.get("alpha")).toBeUndefined()
+        expect(result.current.has("beta")).toBe(true)
+    })
+
+    it("clear ですべての要素を削除する", () => {
+        const { result } = renderHook(() => useLruCache<string, number>(2))
+
+        act(() => {
+            result.current.set("first", 1)
+            result.current.set("second", 2)
+            result.current.clear()
+        })
+
+        expect(result.current.has("first")).toBe(false)
+        expect(result.current.has("second")).toBe(false)
+        expect(result.current.get("first")).toBeUndefined()
+        expect(result.current.get("second")).toBeUndefined()
+    })
+
+    it("capacity に NaN を渡しても無制限に成長しない (eviction 無効化を防ぐ)", () => {
+        const { result } = renderHook(() => useLruCache<number, number>(Number.NaN))
+
+        act(() => {
+            for (let key = 0; key < 100; key++) {
+                result.current.set(key, key)
+            }
+        })
+
+        // NaN は有効な容量ではないため、キャッシュには何も保持されない (無制限成長を防止)
+        for (let key = 0; key < 100; key++) {
+            expect(result.current.has(key)).toBe(false)
+        }
+    })
+
+    it("capacity = Infinity は無制限キャッシュとして格納でき evict されない", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+        try {
+            const { result } = renderHook(() => useLruCache<number, number>(Number.POSITIVE_INFINITY))
+
+            act(() => {
+                for (let key = 0; key < 500; key++) {
+                    result.current.set(key, key * 10)
+                }
+            })
+
+            // Infinity は「無制限」なので全エントリが evict されずに保持される
+            for (let key = 0; key < 500; key++) {
+                expect(result.current.has(key)).toBe(true)
+                expect(result.current.get(key)).toBe(key * 10)
+            }
+            // 有効な容量なので警告は出ない
+            expect(warnSpy).not.toHaveBeenCalled()
+        } finally {
+            warnSpy.mockRestore()
+        }
+    })
+
+    it("capacity に NaN を渡すと格納せず警告をログする", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+        try {
+            const { result } = renderHook(() => useLruCache<string, number>(Number.NaN))
+
+            act(() => {
+                result.current.set("alpha", 1)
+            })
+
+            // 無効容量なので格納されない
+            expect(result.current.has("alpha")).toBe(false)
+            expect(result.current.get("alpha")).toBeUndefined()
+            // capacity 変更 (マウント) につき 1 回だけ警告が出る
+            expect(warnSpy).toHaveBeenCalledTimes(1)
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("invalid capacity"))
+        } finally {
+            warnSpy.mockRestore()
+        }
+    })
+
+    it("capacity に負値を渡すと格納せず警告をログする", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+        try {
+            const { result } = renderHook(() => useLruCache<string, number>(-5))
+
+            act(() => {
+                result.current.set("alpha", 1)
+                result.current.set("beta", 2)
+            })
+
+            // 無効容量なので格納されない
+            expect(result.current.has("alpha")).toBe(false)
+            expect(result.current.has("beta")).toBe(false)
+            // set の回数によらず、capacity 変更 (マウント) につき 1 回だけ警告が出る
+            expect(warnSpy).toHaveBeenCalledTimes(1)
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("invalid capacity"))
+        } finally {
+            warnSpy.mockRestore()
+        }
+    })
+
+    it("小数 capacity は floor に正規化され set の eviction が実効容量を守る", () => {
+        const { result } = renderHook(() => useLruCache<string, number>(2.5))
+
+        act(() => {
+            result.current.set("a", 1)
+            result.current.set("b", 2)
+            result.current.set("c", 3)
+        })
+
+        // floor(2.5) = 2 が実効容量なので、3 件目の追加で最古の "a" が evict される
+        expect(result.current.has("a")).toBe(false)
+        expect(result.current.has("b")).toBe(true)
+        expect(result.current.has("c")).toBe(true)
+    })
+
+    it("小数 capacity への縮小でも刈り込み effect が floor 値まで刈り込む (set と同一の実効値)", () => {
+        const { result, rerender } = renderHook(({ capacity }) => useLruCache<number, number>(capacity), {
+            initialProps: { capacity: 5 },
+        })
+
+        act(() => {
+            for (let key = 0; key < 5; key++) {
+                result.current.set(key, key)
+            }
+        })
+
+        // capacity を 5 → 2.5 に縮小: floor(2.5) = 2 件まで刈り込まれる
+        rerender({ capacity: 2.5 })
+
+        let count = 0
+        for (let key = 0; key < 5; key++) {
+            if (result.current.has(key)) {
+                count++
+            }
+        }
+        expect(count).toBe(2)
+
+        // 以後の set も同じ実効容量 2 を守る
+        act(() => {
+            result.current.set(100, 100)
+        })
+        let countAfterSet = 0
+        for (let key = 0; key <= 100; key++) {
+            if (result.current.has(key)) {
+                countAfterSet++
+            }
+        }
+        expect(countAfterSet).toBe(2)
+    })
+
+    it("capacity が有効値から NaN に変わると既存エントリを全消去し警告をログする", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+        try {
+            const { result, rerender } = renderHook(({ capacity }) => useLruCache<string, number>(capacity), {
+                initialProps: { capacity: 10 },
+            })
+
+            act(() => {
+                result.current.set("alpha", 1)
+                result.current.set("beta", 2)
+            })
+            expect(result.current.has("alpha")).toBe(true)
+
+            // 有効値 → NaN への動的遷移
+            rerender({ capacity: Number.NaN })
+
+            // 警告文言「the cache will not store any entries」どおり、既存エントリも保持されない
+            expect(result.current.has("alpha")).toBe(false)
+            expect(result.current.has("beta")).toBe(false)
+            expect(result.current.get("alpha")).toBeUndefined()
+            expect(warnSpy).toHaveBeenCalledTimes(1)
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("invalid capacity"))
+        } finally {
+            warnSpy.mockRestore()
+        }
+    })
+
+    it("capacity が有効値から負値に変わると既存エントリを全消去する", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+        try {
+            const { result, rerender } = renderHook(({ capacity }) => useLruCache<string, number>(capacity), {
+                initialProps: { capacity: 10 },
+            })
+
+            act(() => {
+                result.current.set("alpha", 1)
+            })
+            expect(result.current.has("alpha")).toBe(true)
+
+            // 有効値 → 負値への動的遷移
+            rerender({ capacity: -1 })
+
+            expect(result.current.has("alpha")).toBe(false)
+            expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("invalid capacity"))
+
+            // 無効容量のままの set は no-op
+            act(() => {
+                result.current.set("beta", 2)
+            })
+            expect(result.current.has("beta")).toBe(false)
+        } finally {
+            warnSpy.mockRestore()
+        }
+    })
+
+    it("capacity を有限値から Infinity に変更すると以後は無制限に格納できる (仕様維持)", () => {
+        const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+        try {
+            const { result, rerender } = renderHook(({ capacity }) => useLruCache<number, number>(capacity), {
+                initialProps: { capacity: 2 },
+            })
+
+            act(() => {
+                result.current.set(0, 0)
+                result.current.set(1, 1)
+                result.current.set(2, 2)
+            })
+            // 有限容量 2 の間は evict される
+            expect(result.current.has(0)).toBe(false)
+
+            // Infinity へ動的変更: 無制限キャッシュとして格納・保持できる
+            rerender({ capacity: Number.POSITIVE_INFINITY })
+            act(() => {
+                for (let key = 10; key < 110; key++) {
+                    result.current.set(key, key)
+                }
+            })
+            for (let key = 10; key < 110; key++) {
+                expect(result.current.has(key)).toBe(true)
+            }
+            // Infinity は有効な容量なので警告は出ない
+            expect(warnSpy).not.toHaveBeenCalled()
+        } finally {
+            warnSpy.mockRestore()
+        }
+    })
+
+    it("handler の識別子がマウント後の再レンダーで安定している", () => {
+        const { result, rerender } = renderHook(() => useLruCache<string, number>(2))
+
+        const firstHandler = result.current
+        rerender()
+
+        // useMemo により余計な再生成が起きないので同一参照であること
+        expect(result.current).toBe(firstHandler)
+        expect(result.current.get).toBe(firstHandler.get)
+        expect(result.current.set).toBe(firstHandler.set)
+    })
+
+    it("capacity を縮小すると以後の set が新容量を守る (stale set 公開を防ぐ)", () => {
+        const { result, rerender } = renderHook(({ capacity }) => useLruCache<number, number>(capacity), {
+            initialProps: { capacity: 100 },
+        })
+
+        act(() => {
+            for (let key = 0; key < 11; key++) {
+                result.current.set(key, key)
+            }
+        })
+        expect(result.current.has(0)).toBe(true)
+
+        // capacity を 100 → 5 に縮小
+        rerender({ capacity: 5 })
+
+        act(() => {
+            result.current.set(100, 100)
+        })
+
+        // 刈り込み effect と最新 capacity を参照する set により、サイズは新容量 5 を超えない
+        let count = 0
+        for (let key = 0; key <= 100; key++) {
+            if (result.current.has(key)) {
+                count++
+            }
+        }
+        expect(count).toBe(5)
+    })
+
+    it("Number.MAX_SAFE_INTEGER 回の追加後でも値取得と全削除ができる", () => {
+        const capacity = 3
+        const { result } = renderHook(() => useLruCache<number, string>(capacity))
+
+        act(() => {
+            result.current.set(-1, "initial")
+            // LRU の性質上、末尾の capacity 件の追加で全体と同じ最終状態になる
+            for (let key = Number.MAX_SAFE_INTEGER - capacity + 1; key <= Number.MAX_SAFE_INTEGER; key++) {
+                result.current.set(key, `value-${key}`)
+            }
+        })
+
+        expect(result.current.has(-1)).toBe(false)
+        for (let key = Number.MAX_SAFE_INTEGER - capacity + 1; key <= Number.MAX_SAFE_INTEGER; key++) {
+            expect(result.current.has(key)).toBe(true)
+            expect(result.current.get(key)).toBe(`value-${key}`)
+        }
+
+        act(() => {
+            for (let key = Number.MAX_SAFE_INTEGER - capacity + 1; key <= Number.MAX_SAFE_INTEGER; key++) {
+                result.current.remove(key)
+            }
+        })
+
+        for (let key = Number.MAX_SAFE_INTEGER - capacity + 1; key <= Number.MAX_SAFE_INTEGER; key++) {
+            expect(result.current.has(key)).toBe(false)
+            expect(result.current.get(key)).toBeUndefined()
+        }
+
+        act(() => {
+            for (let key = Number.MAX_SAFE_INTEGER - capacity + 1; key <= Number.MAX_SAFE_INTEGER; key++) {
+                result.current.set(key, `value-${key}`)
+            }
+            result.current.clear()
+        })
+
+        expect(result.current.has(-1)).toBe(false)
+        for (let key = Number.MAX_SAFE_INTEGER - capacity + 1; key <= Number.MAX_SAFE_INTEGER; key++) {
+            expect(result.current.has(key)).toBe(false)
+            expect(result.current.get(key)).toBeUndefined()
+        }
+    })
+})