@aiquants/virtualscroll 1.18.5 → 1.19.1

package/src/useLruCache.ts

@@ -0,0 +1,301 @@
+/**
+ * @module useLruCache
+ * @description This module provides a `useLruCache` hook, which implements a Least Recently Used (LRU) cache.
+ * It uses a Map for O(1) key-based lookups and a doubly linked list to maintain the order of usage, ensuring that get, set, and eviction operations are all efficient.
+ *
+ * @description このモジュールは、Least Recently Used (LRU) キャッシュを実装した `useLruCache` フックを提供します。
+ * Map を使用した O(1) のキー検索と、使用順序を維持するための双方向連結リストを組み合わせることで、get, set, および削除操作のすべてを効率的に行います。
+ */
+import { useCallback, useEffect, useMemo, useRef } from "react"
+import { Logger } from "./logger"
+
+/**
+ * @class DoublyLinkedListNode
+ * @description Represents a node in the doubly linked list. It holds a key-value pair and references to the previous and next nodes.
+ * @description 双方向連結リスト内のノードを表します。キーと値のペア、および前後のノードへの参照を保持します。
+ */
+class DoublyLinkedListNode<K, V> {
+    key: K
+    value: V
+    prev: DoublyLinkedListNode<K, V> | null = null
+    next: DoublyLinkedListNode<K, V> | null = null
+
+    constructor(key: K, value: V) {
+        // キーを初期化
+        this.key = key
+        // 値を初期化
+        this.value = value
+    }
+}
+
+/**
+ * @class DoublyLinkedList
+ * @description Implements a doubly linked list to maintain the usage order of cache items.
+ * The tail of the list represents the most recently used item, and the head represents the least recently used item.
+ * @description キャッシュアイテムの使用順序を維持するための双方向連結リストを実装します。
+ * リストの末尾が最も最近使用されたアイテムを、先頭が最も最近使用されていないアイテムを示します。
+ */
+class DoublyLinkedList<K, V> {
+    private head: DoublyLinkedListNode<K, V> | null = null
+    private tail: DoublyLinkedListNode<K, V> | null = null
+
+    /**
+     * @method addToTail
+     * @description Adds a node to the tail of the list, marking it as the most recently used.
+     * @description ノードをリストの末尾に追加し、最も最近使用されたものとしてマークします。
+     * @param {DoublyLinkedListNode<K, V>} node - The node to add.
+     */
+    addToTail(node: DoublyLinkedListNode<K, V>) {
+        // リストが既に末尾ノードを持っているかチェック
+        if (this.tail) {
+            // 既存の末尾ノードの次に新しいノードをリンク
+            this.tail.next = node
+            // 新しいノードの前に既存の末尾ノードをリンク
+            node.prev = this.tail
+            // リストの末尾を新しいノードに更新
+            this.tail = node
+        } else {
+            // リストが空の場合、新しいノードが先頭かつ末尾となる
+            this.head = this.tail = node
+        }
+    }
+
+    /**
+     * @method remove
+     * @description Removes a given node from the list.
+     * @description 指定されたノードをリストから削除します。
+     * @param {DoublyLinkedListNode<K, V>} node - The node to remove.
+     */
+    remove(node: DoublyLinkedListNode<K, V>) {
+        // ノードに前のノードが存在する場合
+        if (node.prev) {
+            // 前のノードの `next` を、現在のノードの `next` につなぎ直す
+            node.prev.next = node.next
+        } else {
+            // ノードが先頭の場合、リストの先頭を次のノードに更新
+            this.head = node.next
+        }
+
+        // ノードに次のノードが存在する場合
+        if (node.next) {
+            // 次のノードの `prev` を、現在のノードの `prev` につなぎ直す
+            node.next.prev = node.prev
+        } else {
+            // ノードが末尾の場合、リストの末尾を前のノードに更新
+            this.tail = node.prev
+        }
+
+        // 削除されたノードの参照をクリア
+        node.prev = null
+        node.next = null
+    }
+
+    /**
+     * @method removeHead
+     * @description Removes and returns the head of the list, which is the least recently used item.
+     * @description リストの先頭（最も最近使用されていないアイテム）を削除して返します。
+     * @returns {DoublyLinkedListNode<K, V> | null} The removed head node, or null if the list is empty.
+     */
+    removeHead(): DoublyLinkedListNode<K, V> | null {
+        // 現在の先頭ノードを保持
+        const head = this.head
+        // 先頭ノードが存在する場合のみ処理
+        if (head) {
+            // 先頭ノードをリストから削除
+            this.remove(head)
+        }
+        // 削除したノード（または null）を返す
+        return head
+    }
+
+    /**
+     * @method moveToTail
+     * @description Moves an existing node to the tail of the list to mark it as most recently used.
+     * @description 既存のノードをリストの末尾に移動し、最も最近使用されたものとしてマークします。
+     * @param {DoublyLinkedListNode<K, V>} node - The node to move.
+     */
+    moveToTail(node: DoublyLinkedListNode<K, V>) {
+        // ノードを現在の位置から一旦削除
+        this.remove(node)
+        // ノードをリストの末尾に再追加
+        this.addToTail(node)
+    }
+}
+
+/**
+ * @hook useLruCache
+ * @description A custom hook that provides a Least Recently Used (LRU) cache of a specified capacity.
+ * It returns an object with methods to interact with the cache (`get`, `set`, `has`, `remove`, `clear`).
+ * `Infinity` is treated as an unbounded cache (entries are stored and never evicted),
+ * while `NaN` or a negative capacity is invalid (nothing is stored, existing entries are cleared, and a warning is logged).
+ * A fractional capacity is normalized with `Math.floor` so that both the set path and the pruning
+ * effect share the same effective capacity.
+ * @description 指定された容量の LRU (Least Recently Used) キャッシュを提供するカスタムフック。
+ * キャッシュを操作するためのメソッド (`get`, `set`, `has`, `remove`, `clear`) を持つオブジェクトを返します。
+ * `Infinity` は無制限キャッシュ (格納し、evict しない)、`NaN` / 負値は無効容量
+ * (格納せず、既存エントリも全消去し、警告をログ) として扱う仕様。
+ * 小数の capacity は `Math.floor` で正規化し、set 経路と刈り込み effect が同じ実効容量を共有する。
+ * @param {number} capacity - The maximum capacity of the cache. `Infinity` means unbounded; `NaN` / negative values are invalid; fractional values are floored.
+ * @returns {{ get: (key: K) => V | undefined, set: (key: K, value: V) => void, has: (key: K) => boolean, remove: (key: K) => void, clear: () => void }} An object with methods to interact with the cache.
+ */
+export function useLruCache<K, V>(capacity: number) {
+    // キャッシュストレージ。キーと双方向連結リストのノードをマッピングする (O(1) アクセス用)
+    const cache = useRef(new Map<K, DoublyLinkedListNode<K, V>>())
+    // 使用順序を管理する双方向連結リスト (先頭が最も古く、末尾が最も新しい)
+    const list = useRef(new DoublyLinkedList<K, V>())
+
+    // 小数の capacity は floor で正規化し、set の eviction 判定と刈り込み effect が同じ実効容量を使う。
+    // Math.floor は NaN → NaN、Infinity → Infinity、負値 → 負値のまま保つため、無効容量/無制限の判定は影響を受けない。
+    // Fractional capacities are floored so the set path and the pruning effect share one effective capacity.
+    const normalizedCapacity = Math.floor(capacity)
+
+    // 最新の capacity を保持する ref。
+    // set などのコールバックがこの ref を参照することで、識別子を安定 (空 deps) に保ちつつ
+    // 常に現在の capacity で eviction 判定でき、capacity 変更時に stale なクロージャが公開される問題を防ぐ。
+    // レンダーフェーズでは書き込まず、下の useEffect でコミット後に同期する (concurrent rendering で
+    // 破棄されたレンダーの値が ref に残留する tearing を避けるため)。
+    // The ref keeps callbacks stable while always reading the latest capacity, avoiding stale closures on
+    // capacity change. It is synchronized in the effect below (not during render) so a discarded render
+    // can never leave an uncommitted capacity behind.
+    const capacityRef = useRef(normalizedCapacity)
+
+    useEffect(() => {
+        // コミット済みの capacity を ref に同期する (set はこの値で eviction 判定する)
+        capacityRef.current = normalizedCapacity
+        // NaN / 負の capacity は無効容量。既存エントリも全消去し、capacity 変更ごとに 1 回だけ警告する
+        // Invalid capacity (NaN or negative): clear existing entries and warn once per capacity change.
+        if (Number.isNaN(normalizedCapacity) || normalizedCapacity < 0) {
+            Logger.warn(`useLruCache: invalid capacity ${capacity}; the cache will not store any entries.`)
+            // 警告文言「何も保持しない」と挙動を一致させるため、既存エントリを消去する
+            cache.current.clear()
+            list.current = new DoublyLinkedList<K, V>()
+            return
+        }
+        // capacity が Infinity の場合は「無制限キャッシュ」として刈り込みを行わない
+        // Infinity means an unbounded cache: never prune.
+        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
+            }
+        }
+    }, [capacity, normalizedCapacity])
+
+    /**
+     * @function get
+     * @description Retrieves a value from the cache for a given key. If found, the item is marked as most recently used.
+     * @description 指定されたキーの値を取得します。アイテムが見つかった場合、それは最も最近使用されたものとしてマークされます。
+     * @param {K} key - The key of the item to retrieve.
+     * @returns {V | undefined} The cached value, or undefined if the key does not exist.
+     */
+    const get = useCallback((key: K): V | undefined => {
+        // Map からノードを効率的に検索
+        const node = cache.current.get(key)
+        // ノードが存在する場合
+        if (node) {
+            // アクセスされたノードを使用順序リストの末尾に移動
+            list.current.moveToTail(node)
+            // ノードの値を返す
+            return node.value
+        }
+        // ノードが存在しない場合は undefined を返す
+        return undefined
+    }, [])
+
+    /**
+     * @function set
+     * @description Adds or updates a key-value pair in the cache. If the cache is full, it evicts the least recently used item.
+     * @description キーと値のペアをキャッシュに追加または更新します。キャッシュが満杯の場合、最も最近使用されていないアイテムが削除されます。
+     * @param {K} key - The key of the item to set.
+     * @param {V} value - The value of the item to set.
+     */
+    const set = useCallback((key: K, value: V) => {
+        // 現在の実効 capacity (floor 正規化済み) を ref から読み取る (識別子安定化のため deps に含めない)
+        const capacity = capacityRef.current
+        // NaN / 0 以下は無効容量として格納しない (警告は capacity 変更時の effect が発行する)。
+        // capacity = Infinity は「無制限 (evict しない)」として格納を許可する。
+        // NaN / <=0 are invalid capacities: skip caching (the effect above logs the warning).
+        // capacity = Infinity means an unbounded cache: storing is allowed and eviction never triggers.
+        if (Number.isNaN(capacity) || capacity <= 0) {
+            return
+        }
+        // キャッシュ内にキーが既に存在するかチェック
+        let node = cache.current.get(key)
+
+        if (node) {
+            // キーが存在する場合、値を更新
+            node.value = value
+            // アクセスされたので、使用順序リストの末尾に移動
+            list.current.moveToTail(node)
+        } else {
+            // 新しいノードを追加する場合
+            // キャッシュが容量上限に達しているかチェック
+            if (cache.current.size >= capacity) {
+                // 容量オーバーの場合、最も最近使用されていないノード (リストの先頭) を取得して削除
+                const lruNode = list.current.removeHead()
+                if (lruNode) {
+                    // Map からも対応するエントリを削除
+                    cache.current.delete(lruNode.key)
+                }
+            }
+            // 新しいノードを作成
+            node = new DoublyLinkedListNode(key, value)
+            // 新しいノードを Map に登録
+            cache.current.set(key, node)
+            // 新しいノードを使用順序リストの末尾に追加
+            list.current.addToTail(node)
+        }
+    }, [])
+
+    /**
+     * @function has
+     * @description Checks if a key exists in the cache.
+     * @description 指定されたキーがキャッシュ内に存在するかどうかを確認します。
+     * @param {K} key - The key to check.
+     * @returns {boolean} True if the key exists, false otherwise.
+     */
+    const has = useCallback((key: K): boolean => {
+        // Map にキーが存在するかどうかを O(1) でチェック
+        return cache.current.has(key)
+    }, [])
+
+    /**
+     * @function remove
+     * @description Deletes a specific entry from the cache and updates the usage order list.
+     * @description キャッシュから特定のエントリを削除し、使用順リストを更新します。
+     * @param {K} key - The key to delete.
+     */
+    const remove = useCallback((key: K) => {
+        const node = cache.current.get(key)
+        if (!node) {
+            return
+        }
+        list.current.remove(node)
+        cache.current.delete(key)
+    }, [])
+
+    /**
+     * @function clear
+     * @description Clears the entire cache, removing all entries.
+     * @description キャッシュを完全にクリアし、すべてのエントリを削除します。
+     */
+    const clear = useCallback(() => {
+        // Map をクリア
+        cache.current.clear()
+        // 双方向連結リストを新しく作成してリセット
+        list.current = new DoublyLinkedList<K, V>()
+    }, [])
+
+    // キャッシュ操作用の API を安定参照で返す。
+    // get/set/has/remove/clear はすべて安定 (空 deps) なので、この handler もマウント後に再生成されず、
+    // useState + useEffect による余計な再レンダーを回避する。
+    // Returns a stable API object; since all callbacks are stable, this handler is created once and
+    // never triggers the extra re-render the previous useState/useEffect pattern caused.
+    return useMemo(() => ({ get, set, has, remove, clear }), [get, set, has, remove, clear])
+}

package/src/utils.spec.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Tests for utils.
+ * utils のテスト。
+ */
+
+import { describe, expect, it } from "vitest"
+import { minmax } from "./utils"
+
+describe("minmax", () => {
+    it("値を [min, max] にクランプする", () => {
+        expect(minmax(5, 0, 10)).toBe(5)
+        expect(minmax(-3, 0, 10)).toBe(0)
+        expect(minmax(42, 0, 10)).toBe(10)
+    })
+
+    it("通常の min <= max では従来と同一結果を返す(境界含む)", () => {
+        // 従来実装 Math.min(max, Math.max(min, value)) と一致することを保証。
+        for (const [value, min, max] of [
+            [5, 0, 10],
+            [0, 0, 10],
+            [10, 0, 10],
+            [-1, 0, 10],
+            [11, 0, 10],
+            [-100, -50, 50],
+            [7, 7, 7],
+        ] as const) {
+            expect(minmax(value, min, max)).toBe(Math.min(max, Math.max(min, value)))
+        }
+    })
+
+    it("退化入力 min > max でも下限 (min) を下回らない", () => {
+        // 回帰: 旧実装 Math.min(max, Math.max(min, value)) は max を返し
+        // min を割り込んでいた (例: 空リストで safeIndex=-1 が漏れる)。
+        expect(minmax(5, 0, -1)).toBe(0)
+        expect(minmax(0, 0, -1)).toBe(0)
+        expect(minmax(-5, 0, -1)).toBe(0)
+        expect(minmax(100, 3, 1)).toBe(3)
+    })
+})

package/src/utils.ts

@@ -0,0 +1,16 @@
+/**
+ * Clamps a value between a minimum and maximum value.
+ *
+ * 指定された値が最小値と最大値の範囲内に収まるように調整。
+ *
+ * min > max のような退化した入力でも、下限 (min) を下回る値を返さない。
+ * (Math.min を内側に置くことで、min > max のときは常に min を返す。)
+ *
+ * @param value The value to clamp. / クランプする値。
+ * @param min The minimum value. / 最小値。
+ * @param max The maximum value. / 最大値。
+ * @returns The clamped value. / クランプされた値。
+ */
+export const minmax = (value: number, min: number, max: number): number => {
+    return Math.max(min, Math.min(max, value))
+}