vlist 1.9.0 → 2.0.0

package/dist/plugins/async/sparse.js

@@ -0,0 +1,540 @@
+/**
+ * vlist - Sparse Storage
+ * Efficient storage for million+ item virtual lists
+ */
+// =============================================================================
+// Constants
+// =============================================================================
+const CHUNK_SIZE = 100;
+const MAX_CACHED_ITEMS = 5000;
+const EVICTION_BUFFER = 200;
+// =============================================================================
+// Sparse Storage Implementation
+// =============================================================================
+/**
+ * Create sparse storage for efficient large list handling
+ */
+export const createSparseStorage = (config = {}) => {
+    const { chunkSize = CHUNK_SIZE, maxCachedItems = MAX_CACHED_ITEMS, evictionBuffer = EVICTION_BUFFER, onEvict, } = config;
+    // Storage state
+    const chunks = new Map();
+    let totalItems = 0;
+    let cachedItemCount = 0;
+    // ==========================================================================
+    // Internal Helpers
+    // ==========================================================================
+    /**
+     * Get or create a chunk
+     */
+    const getOrCreateChunk = (chunkIndex) => {
+        let chunk = chunks.get(chunkIndex);
+        if (!chunk) {
+            chunk = {
+                items: new Array(chunkSize),
+                count: 0,
+                lastAccess: Date.now(),
+            };
+            chunks.set(chunkIndex, chunk);
+        }
+        else {
+            chunk.lastAccess = Date.now();
+        }
+        return chunk;
+    };
+    /**
+     * Get chunk index for item index
+     */
+    const getChunkIndex = (itemIndex) => {
+        return Math.floor(itemIndex / chunkSize);
+    };
+    /**
+     * Get index within chunk
+     */
+    const getIndexInChunk = (itemIndex) => {
+        return itemIndex % chunkSize;
+    };
+    // ==========================================================================
+    // Total Management
+    // ==========================================================================
+    const getTotal = () => totalItems;
+    const setTotal = (total) => {
+        totalItems = total;
+    };
+    // ==========================================================================
+    // Item Access
+    // ==========================================================================
+    const get = (index) => {
+        if (index < 0 || index >= totalItems) {
+            return undefined;
+        }
+        const chunkIndex = getChunkIndex(index);
+        const chunk = chunks.get(chunkIndex);
+        if (!chunk) {
+            // log(`get: index=${index}, chunkIndex=${chunkIndex} - chunk not found`);
+            return undefined;
+        }
+        return chunk.items[getIndexInChunk(index)];
+    };
+    const has = (index) => {
+        if (index < 0 || index >= totalItems) {
+            return false;
+        }
+        const chunkIndex = getChunkIndex(index);
+        const chunk = chunks.get(chunkIndex);
+        if (!chunk) {
+            return false;
+        }
+        return chunk.items[getIndexInChunk(index)] !== undefined;
+    };
+    const set = (index, item) => {
+        const chunkIndex = getChunkIndex(index);
+        const chunk = getOrCreateChunk(chunkIndex);
+        const indexInChunk = getIndexInChunk(index);
+        // Track if this is a new item
+        const isNew = chunk.items[indexInChunk] === undefined;
+        chunk.items[indexInChunk] = item;
+        if (isNew) {
+            chunk.count++;
+            cachedItemCount++;
+            // log(
+            //   `set: index=${index}, chunkIndex=${chunkIndex}, cachedItemCount=${cachedItemCount}`,
+            // );
+        }
+        // Update total if needed
+        if (index >= totalItems) {
+            totalItems = index + 1;
+        }
+    };
+    const setRange = (offset, items) => {
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            if (item !== undefined) {
+                set(offset + i, item);
+            }
+        }
+    };
+    const insertItem = (index, item) => {
+        if (index < 0 || index > totalItems)
+            return;
+        // Collect all loaded items at indices >= insertIndex, in order.
+        const insertChunkIdx = getChunkIndex(index);
+        const sortedChunkKeys = Array.from(chunks.keys())
+            .filter(k => k >= insertChunkIdx)
+            .sort((a, b) => a - b);
+        const shifted = [];
+        for (const ci of sortedChunkKeys) {
+            const c = chunks.get(ci);
+            const base = ci * chunkSize;
+            for (let s = 0; s < chunkSize; s++) {
+                if (c.items[s] === undefined)
+                    continue;
+                const itemIndex = base + s;
+                if (itemIndex < index)
+                    continue;
+                shifted.push({ oldIndex: itemIndex, item: c.items[s] });
+            }
+        }
+        // 1. Clear items that will shift up
+        for (const { oldIndex } of shifted) {
+            const ci = getChunkIndex(oldIndex);
+            const c = chunks.get(ci);
+            if (!c)
+                continue;
+            const slot = getIndexInChunk(oldIndex);
+            if (c.items[slot] !== undefined) {
+                c.items[slot] = undefined;
+                c.count--;
+                cachedItemCount--;
+                if (c.count === 0)
+                    chunks.delete(ci);
+            }
+        }
+        // 2. Increase total first (so getChunkIndex works for new positions)
+        totalItems++;
+        // 3. Re-insert each shifted item at (oldIndex + 1)
+        for (const { oldIndex, item: shiftedItem } of shifted) {
+            const newIndex = oldIndex + 1;
+            const ci = getChunkIndex(newIndex);
+            const dst = getOrCreateChunk(ci);
+            const slot = getIndexInChunk(newIndex);
+            dst.items[slot] = shiftedItem;
+            dst.count++;
+            cachedItemCount++;
+        }
+        // 4. Insert the new item
+        const ci = getChunkIndex(index);
+        const dst = getOrCreateChunk(ci);
+        const slot = getIndexInChunk(index);
+        dst.items[slot] = item;
+        dst.count++;
+        cachedItemCount++;
+    };
+    const deleteItem = (index) => {
+        if (index < 0 || index >= totalItems)
+            return false;
+        // Check if the item at this index is loaded
+        const chunkIdx = getChunkIndex(index);
+        const chunk = chunks.get(chunkIdx);
+        const slotInChunk = getIndexInChunk(index);
+        const wasLoaded = chunk !== undefined &&
+            chunk.items[slotInChunk] !== undefined;
+        if (!wasLoaded)
+            return false;
+        // Collect all loaded items at indices > deleted index, in order.
+        // This is O(cachedItems) instead of O(totalItems) — critical for
+        // lists with 300K+ items where only ~50 are in memory.
+        const deletedChunkIdx = chunkIdx;
+        const sortedChunkKeys = Array.from(chunks.keys())
+            .filter(k => k >= deletedChunkIdx)
+            .sort((a, b) => a - b);
+        const shifted = [];
+        for (const ci of sortedChunkKeys) {
+            const c = chunks.get(ci);
+            const base = ci * chunkSize;
+            for (let s = 0; s < chunkSize; s++) {
+                if (c.items[s] === undefined)
+                    continue;
+                const itemIndex = base + s;
+                if (itemIndex <= index)
+                    continue; // before or at deleted — skip
+                shifted.push({ oldIndex: itemIndex, item: c.items[s] });
+            }
+        }
+        // 1. Remove the deleted item and all items that will shift
+        //    Clear the deleted item
+        chunk.items[slotInChunk] = undefined;
+        chunk.count--;
+        cachedItemCount--;
+        if (chunk.count === 0)
+            chunks.delete(chunkIdx);
+        //    Clear each item that will be re-inserted at a lower index
+        for (const { oldIndex } of shifted) {
+            const ci = getChunkIndex(oldIndex);
+            const c = chunks.get(ci);
+            if (!c)
+                continue;
+            const slot = getIndexInChunk(oldIndex);
+            if (c.items[slot] !== undefined) {
+                c.items[slot] = undefined;
+                c.count--;
+                cachedItemCount--;
+                if (c.count === 0)
+                    chunks.delete(ci);
+            }
+        }
+        // 2. Re-insert each shifted item at (oldIndex - 1)
+        for (const { oldIndex, item } of shifted) {
+            const newIndex = oldIndex - 1;
+            const ci = getChunkIndex(newIndex);
+            const dst = getOrCreateChunk(ci);
+            const slot = getIndexInChunk(newIndex);
+            dst.items[slot] = item;
+            dst.count++;
+            cachedItemCount++;
+        }
+        // 3. Decrease total
+        totalItems--;
+        return true;
+    };
+    // ==========================================================================
+    // Range Operations
+    // ==========================================================================
+    const getRange = (start, end) => {
+        const result = [];
+        for (let i = start; i <= end && i < totalItems; i++) {
+            result.push(get(i));
+        }
+        return result;
+    };
+    const isRangeLoaded = (start, end) => {
+        for (let i = start; i <= end && i < totalItems; i++) {
+            if (!has(i)) {
+                return false;
+            }
+        }
+        return true;
+    };
+    const getLoadedRanges = () => {
+        const ranges = [];
+        let currentRange = null;
+        // Iterate through all chunks in order
+        const sortedChunkIndices = Array.from(chunks.keys()).sort((a, b) => a - b);
+        for (const chunkIndex of sortedChunkIndices) {
+            const chunk = chunks.get(chunkIndex);
+            if (!chunk)
+                continue;
+            const chunkStart = chunkIndex * chunkSize;
+            // Find loaded items in this chunk
+            for (let i = 0; i < chunkSize; i++) {
+                const itemIndex = chunkStart + i;
+                if (itemIndex >= totalItems)
+                    break;
+                if (chunk.items[i] !== undefined) {
+                    if (currentRange === null) {
+                        currentRange = { start: itemIndex, end: itemIndex };
+                    }
+                    else if (itemIndex === currentRange.end + 1) {
+                        currentRange.end = itemIndex;
+                    }
+                    else {
+                        ranges.push(currentRange);
+                        currentRange = { start: itemIndex, end: itemIndex };
+                    }
+                }
+                else if (currentRange !== null) {
+                    ranges.push(currentRange);
+                    currentRange = null;
+                }
+            }
+        }
+        if (currentRange !== null) {
+            ranges.push(currentRange);
+        }
+        return ranges;
+    };
+    const findUnloadedRanges = (start, end) => {
+        const unloaded = [];
+        let currentRange = null;
+        for (let i = start; i <= end && i < totalItems; i++) {
+            if (!has(i)) {
+                if (currentRange === null) {
+                    currentRange = { start: i, end: i };
+                }
+                else {
+                    currentRange.end = i;
+                }
+            }
+            else if (currentRange !== null) {
+                unloaded.push(currentRange);
+                currentRange = null;
+            }
+        }
+        if (currentRange !== null) {
+            unloaded.push(currentRange);
+        }
+        return unloaded;
+    };
+    // ==========================================================================
+    // Chunk Operations
+    // ==========================================================================
+    const isChunkLoaded = (chunkIndex) => {
+        return chunks.has(chunkIndex);
+    };
+    const isChunkFullyLoaded = (chunkIndex) => {
+        const chunk = chunks.get(chunkIndex);
+        if (!chunk)
+            return false;
+        const chunkStart = chunkIndex * chunkSize;
+        const expectedCount = Math.min(chunkSize, totalItems - chunkStart);
+        return chunk.count >= expectedCount;
+    };
+    const touchChunk = (chunkIndex) => {
+        const chunk = chunks.get(chunkIndex);
+        if (chunk) {
+            chunk.lastAccess = Date.now();
+        }
+    };
+    /**
+     * Mark all chunks covering a range as accessed with a single timestamp.
+     * Batches Date.now() to one call instead of per-item in get().
+     */
+    const touchChunksForRange = (start, end) => {
+        if (start > end || chunks.size === 0)
+            return;
+        const now = Date.now();
+        const startChunk = getChunkIndex(Math.max(0, start));
+        const endChunk = getChunkIndex(Math.min(totalItems - 1, end));
+        for (let ci = startChunk; ci <= endChunk; ci++) {
+            const chunk = chunks.get(ci);
+            if (chunk) {
+                chunk.lastAccess = now;
+            }
+        }
+    };
+    // ==========================================================================
+    // Eviction
+    // ==========================================================================
+    /**
+     * Evict chunks far from visible range
+     */
+    const evictDistant = (visibleStart, visibleEnd) => {
+        // Only evict if we exceed the limit
+        if (cachedItemCount <= maxCachedItems) {
+            return 0;
+        }
+        // Calculate keep zone with buffer
+        const keepStart = Math.max(0, visibleStart - evictionBuffer);
+        const keepEnd = Math.min(totalItems - 1, visibleEnd + evictionBuffer);
+        const keepChunkStart = getChunkIndex(keepStart);
+        const keepChunkEnd = getChunkIndex(keepEnd);
+        let evictedCount = 0;
+        const evictedRanges = [];
+        // Find chunks to evict
+        for (const [chunkIndex, chunk] of chunks) {
+            if (chunkIndex < keepChunkStart || chunkIndex > keepChunkEnd) {
+                evictedCount += chunk.count;
+                evictedRanges.push(chunkIndex);
+                cachedItemCount -= chunk.count;
+                chunks.delete(chunkIndex);
+            }
+        }
+        // Notify about eviction
+        if (evictedCount > 0 && onEvict) {
+            onEvict(evictedCount, evictedRanges);
+        }
+        return evictedCount;
+    };
+    /**
+     * Force eviction using LRU to meet memory limit
+     */
+    const evictToLimit = () => {
+        if (cachedItemCount <= maxCachedItems) {
+            return 0;
+        }
+        // Sort chunks by last access (oldest first)
+        const sortedChunks = Array.from(chunks.entries()).sort(([, a], [, b]) => a.lastAccess - b.lastAccess);
+        let evictedCount = 0;
+        const evictedRanges = [];
+        // Evict oldest chunks until under limit
+        for (const [chunkIndex, chunk] of sortedChunks) {
+            if (cachedItemCount <= maxCachedItems) {
+                break;
+            }
+            evictedCount += chunk.count;
+            cachedItemCount -= chunk.count;
+            evictedRanges.push(chunkIndex);
+            chunks.delete(chunkIndex);
+        }
+        // Notify about eviction
+        if (evictedCount > 0 && onEvict) {
+            onEvict(evictedCount, evictedRanges);
+        }
+        return evictedCount;
+    };
+    // ==========================================================================
+    // Statistics
+    // ==========================================================================
+    const getStats = () => {
+        return {
+            totalItems,
+            cachedItems: cachedItemCount,
+            cachedChunks: chunks.size,
+            chunkSize,
+            maxCachedItems,
+            memoryEfficiency: totalItems > 0 ? 1 - cachedItemCount / totalItems : 1,
+        };
+    };
+    const getCachedCount = () => cachedItemCount;
+    // ==========================================================================
+    // Lifecycle
+    // ==========================================================================
+    const clear = () => {
+        chunks.clear();
+        cachedItemCount = 0;
+    };
+    const reset = () => {
+        clear();
+        totalItems = 0;
+    };
+    // ==========================================================================
+    // Return Public API
+    // ==========================================================================
+    return {
+        chunkSize,
+        maxCachedItems,
+        getTotal,
+        setTotal,
+        get,
+        has,
+        set,
+        setRange,
+        insert: insertItem,
+        delete: deleteItem,
+        getRange,
+        isRangeLoaded,
+        getLoadedRanges,
+        findUnloadedRanges,
+        getChunkIndex,
+        isChunkLoaded,
+        isChunkFullyLoaded,
+        touchChunk,
+        touchChunksForRange,
+        evictDistant,
+        evictToLimit,
+        getStats,
+        getCachedCount,
+        clear,
+        reset,
+    };
+};
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Merge adjacent/overlapping ranges
+ */
+export const mergeRanges = (ranges) => {
+    if (ranges.length === 0)
+        return [];
+    // Sort by start
+    const sorted = [...ranges].sort((a, b) => a.start - b.start);
+    const merged = [{ ...sorted[0] }];
+    for (let i = 1; i < sorted.length; i++) {
+        const current = sorted[i];
+        const last = merged[merged.length - 1];
+        if (current.start <= last.end + 1) {
+            // Overlapping or adjacent - merge
+            last.end = Math.max(last.end, current.end);
+        }
+        else {
+            // Gap - new range
+            merged.push({ ...current });
+        }
+    }
+    return merged;
+};
+/**
+ * Calculate ranges that need to be loaded
+ */
+export const calculateMissingRanges = (needed, loaded, chunkSize) => {
+    // Align to chunk boundaries for efficient loading
+    const alignedStart = Math.floor(needed.start / chunkSize) * chunkSize;
+    const alignedEnd = Math.ceil((needed.end + 1) / chunkSize) * chunkSize - 1;
+    const alignedNeeded = { start: alignedStart, end: alignedEnd };
+    if (loaded.length === 0) {
+        return [alignedNeeded];
+    }
+    const missing = [];
+    const merged = mergeRanges(loaded);
+    let current = alignedNeeded.start;
+    for (const range of merged) {
+        // Skip ranges that end before our current position
+        if (range.end < current) {
+            continue;
+        }
+        // If this range starts after our aligned needed range, we're done
+        // (any remaining gap will be handled after the loop)
+        if (range.start > alignedNeeded.end) {
+            break;
+        }
+        // If there's a gap before this loaded range, record it
+        if (range.start > current) {
+            missing.push({
+                start: current,
+                end: Math.min(range.start - 1, alignedNeeded.end),
+            });
+        }
+        // Advance current past this loaded range
+        current = range.end + 1;
+        if (current > alignedNeeded.end)
+            break;
+    }
+    // Check for gap after all loaded ranges
+    if (current <= alignedNeeded.end) {
+        missing.push({
+            start: current,
+            end: alignedNeeded.end,
+        });
+    }
+    return missing;
+};

package/dist/plugins/autosize/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * vlist v2 — Autosize Plugin
+ */
+export { autosize, type AutosizePluginConfig } from "./plugin";
+//# sourceMappingURL=index.d.ts.map

package/dist/plugins/autosize/index.js

@@ -0,0 +1,4 @@
+/**
+ * vlist v2 — Autosize Plugin
+ */
+export { autosize } from "./plugin";

package/dist/plugins/autosize/plugin.d.ts

@@ -0,0 +1,19 @@
+/**
+ * vlist v2 — Autosize Plugin
+ *
+ * Enables dynamic item measurement via ResizeObserver for items with
+ * unknown sizes. Items are rendered without an explicit main-axis size,
+ * measured once by ResizeObserver, then pinned to their measured size.
+ *
+ * Priority 5 — runs before grid/masonry (10) so the measured cache
+ * is in place before layout plugins consume it.
+ *
+ * Requires: `item.estimatedHeight` or `item.estimatedWidth` in config
+ */
+import type { VListItem } from "../../types";
+import type { VListPlugin } from "../../core/types";
+export interface AutosizePluginConfig {
+    gap?: number;
+}
+export declare function autosize<T extends VListItem = VListItem>(config?: AutosizePluginConfig): VListPlugin<T>;
+//# sourceMappingURL=plugin.d.ts.map