@svgrid/grid 3.0.3 → 3.0.5

package/dist/server-block-cache.js

@@ -0,0 +1,531 @@
+/**
+ * Block cache for server-backed rows - the engine behind infinite scrolling.
+ *
+ * Paging asks for "page 3". Infinite scrolling asks a different question: the
+ * user is looking at rows 4,000 to 4,020 of a table with a million rows, so
+ * fetch the block that covers them, keep a bounded number of recently-seen
+ * blocks, and render something sensible for every row nobody has fetched yet.
+ * That is all this module does, in plain TypeScript with no Svelte and no DOM.
+ *
+ * The shape of the problem (and most of the vocabulary) is the same one every
+ * grid with a server row model solves, so the options here are deliberately
+ * recognisable: `blockSize`, `maxBlocksInCache`, `maxConcurrentRequests`,
+ * `blockLoadDebounceMs`, `initialRowCount`, `overflowRows`.
+ *
+ * Three things it takes seriously:
+ *
+ *   - **Unloaded rows still have to render.** `rows()` always returns a dense
+ *     array, with a shared sentinel object in every slot that has no data. The
+ *     grid recognises those (see {@link rowPlaceholderState}) and draws a
+ *     skeleton or a retry affordance instead of an empty row, so the scrollbar
+ *     never lies and scrolling never leaves a hole.
+ *   - **The row count may be unknown.** A backend that cannot cheaply count
+ *     says so (omit `rowCount`, or send `-1`) and the list grows by a block at
+ *     a time until a short block proves where the end is.
+ *   - **Requests are not free.** In-flight blocks are deduplicated, at most
+ *     `maxConcurrentRequests` are open at once, a fast scroll debounces rather
+ *     than firing a request per frame, and blocks abandoned by eviction or
+ *     purge are aborted.
+ *
+ * Enterprise's server row model runs one of these per group level; the free
+ * flat controller runs exactly one.
+ */
+/**
+ * The mark that says "this row is not data yet".
+ *
+ * A symbol, for two reasons. It cannot collide with a field in anyone's row
+ * data, which a string key like `__svPlaceholder` eventually would. And
+ * `Symbol.for` puts it in the global registry, so a placeholder still reads as
+ * one after it has crossed a module boundary - two copies of this file loaded
+ * through different specifiers would otherwise mint different symbols.
+ */
+const PLACEHOLDER = Symbol.for('svgrid.rowPlaceholder');
+/** Rows the cache has not loaded. One shared object per state, not per row. */
+const LOADING_ROW = Object.freeze({ [PLACEHOLDER]: 'loading' });
+const FAILED_ROW = Object.freeze({ [PLACEHOLDER]: 'failed' });
+/**
+ * Why a row is not real data, or `null` when it is.
+ *
+ * Deliberately NOT an identity check. The sentinels are shared objects, so
+ * `row === LOADING_ROW` looks like the obvious test - but rows routinely
+ * arrive here through something that wrapped them. Svelte is the everyday
+ * case: assigning the controller state into `$state` makes the row array
+ * deeply reactive, and every row read back out is a proxy of the original.
+ * Identity fails, every placeholder reads as real data, and the grid renders
+ * a screen of blank rows instead of skeletons. Reading the mark works through
+ * any wrapper that forwards property access, which is all of them.
+ */
+export function rowPlaceholderState(row) {
+    if (row == null || typeof row !== 'object')
+        return null;
+    const mark = row[PLACEHOLDER];
+    return mark === 'loading' || mark === 'failed' ? mark : null;
+}
+/**
+ * Mint a frozen placeholder the grid will recognise, carrying whatever
+ * other fields the caller wants on it. The row model uses this to give its
+ * placeholders a `kind`, so code reading display rows and code reading grid
+ * rows agree on what they are looking at.
+ */
+export function createRowPlaceholder(state, fields) {
+    return Object.freeze({ ...fields, [PLACEHOLDER]: state });
+}
+const defaultSchedule = (flush) => {
+    void Promise.resolve().then(flush);
+};
+/**
+ * Build a block cache over a `fetch(startRow, endRow, signal)`. The free
+ * infinite row model and the Enterprise server-side row model both run on
+ * it, one per level.
+ */
+export function createBlockCache(options) {
+    const blockSize = Math.max(1, options.blockSize ?? 100);
+    const maxBlocks = options.maxBlocksInCache ?? Infinity;
+    const maxConcurrent = Math.max(1, options.maxConcurrentRequests ?? 2);
+    const debounceMs = Math.max(0, options.blockLoadDebounceMs ?? 0);
+    const initialRowCount = Math.max(0, options.initialRowCount ?? 1);
+    const overflowRows = Math.max(0, options.overflowRows ?? 1);
+    const schedule = options.schedule ?? defaultSchedule;
+    const blocks = new Map();
+    /** Block indices waiting for a slot, in the order the viewport asked for them. */
+    const queue = [];
+    let inFlight = 0;
+    let touchClock = 0;
+    let count = null;
+    let countKnown = false;
+    let disposed = false;
+    let viewStart = 0;
+    let viewEnd = 0;
+    let debounceTimer = null;
+    let emitScheduled = false;
+    let rowsCache = null;
+    const blockOf = (rowIndex) => Math.floor(rowIndex / blockSize);
+    const startOf = (blockIndex) => blockIndex * blockSize;
+    /**
+     * How many rows to claim we have.
+     *
+     * With a known count that is simply the count. Without one it is the last row
+     * we have touched plus `overflowRows`, so there is always somewhere to scroll
+     * that will ask for the next block - this is what makes the list grow as you
+     * go rather than ending at the first unloaded row.
+     */
+    function currentLength() {
+        if (countKnown && count != null)
+            return count;
+        let highestEnd = 0;
+        let anySettled = false;
+        for (const b of blocks.values())
+            if (b.status !== 'loading')
+                anySettled = true;
+        for (const [index, block] of blocks) {
+            // A block in flight extends the list only once some block has settled.
+            // Before that the list is `initialRowCount` long: the few skeleton
+            // rows a level shows while it waits, not a hundred of them. The first
+            // block failing says nothing about how long the list is either, so it
+            // keeps those few rows (its Retry sits on them); a failed block further
+            // in was scrolled to, so its slots stay and the scrollbar holds still.
+            const end = block.status === 'loaded'
+                ? startOf(index) + block.rows.length
+                : block.status === 'failed'
+                    ? index === 0 ? 0 : startOf(index) + blockSize
+                    : anySettled
+                        ? startOf(index) + blockSize
+                        : 0;
+            if (end > highestEnd)
+                highestEnd = end;
+        }
+        if (!anySettled)
+            return initialRowCount;
+        return Math.max(initialRowCount, highestEnd + overflowRows);
+    }
+    function state() {
+        const failed = [];
+        for (const [index, block] of blocks)
+            if (block.status === 'failed')
+                failed.push(index);
+        return {
+            rowCount: countKnown ? count : null,
+            lastRowKnown: countKnown,
+            loading: inFlight > 0,
+            failedBlocks: failed.sort((a, b) => a - b),
+        };
+    }
+    /**
+     * Something changed: forget the row array NOW, so a synchronous read after
+     * a mutation sees the new state, and notify on the next tick, so a burst of
+     * mutations notifies once. Every mutating path ends here.
+     */
+    function emit() {
+        rowsCache = null; // rebuilt lazily, on the next read
+        if (disposed || emitScheduled)
+            return;
+        emitScheduled = true;
+        schedule(() => {
+            emitScheduled = false;
+            if (disposed)
+                return;
+            options.onChange(state());
+        });
+    }
+    function ensureBlock(blockIndex) {
+        if (disposed)
+            return;
+        const existing = blocks.get(blockIndex);
+        // Loading or loaded blocks are left alone; a failed one only retries when
+        // asked, so a broken backend is not hammered once per scroll frame.
+        if (existing)
+            return;
+        if (queue.includes(blockIndex))
+            return;
+        queue.push(blockIndex);
+        pump();
+    }
+    function pump() {
+        while (!disposed && inFlight < maxConcurrent && queue.length > 0) {
+            const blockIndex = queue.shift();
+            if (blocks.has(blockIndex))
+                continue;
+            void load(blockIndex);
+        }
+    }
+    async function load(blockIndex) {
+        const controller = new AbortController();
+        const block = {
+            status: 'loading',
+            rows: [],
+            lastTouched: (touchClock += 1),
+            controller,
+        };
+        blocks.set(blockIndex, block);
+        inFlight += 1;
+        emit();
+        const startRow = startOf(blockIndex);
+        const endRow = startRow + blockSize;
+        try {
+            const result = await options.fetch(startRow, endRow, controller.signal);
+            if (disposed || controller.signal.aborted || blocks.get(blockIndex) !== block)
+                return;
+            block.rows = [...result.rows];
+            block.status = 'loaded';
+            block.controller = null;
+            applyCountFrom(blockIndex, block.rows.length, result.rowCount);
+            evictIfNeeded();
+        }
+        catch {
+            if (disposed || controller.signal.aborted || blocks.get(blockIndex) !== block)
+                return;
+            block.status = 'failed';
+            block.rows = [];
+            block.controller = null;
+        }
+        finally {
+            if (!disposed && !controller.signal.aborted) {
+                inFlight -= 1;
+                emit();
+                pump();
+            }
+        }
+    }
+    /**
+     * Learn the total from a block that just landed.
+     *
+     * An explicit non-negative `rowCount` settles it. Otherwise a SHORT block is
+     * the proof that we hit the end: fewer rows came back than were asked for, so
+     * the data stops where they stop.
+     */
+    function applyCountFrom(blockIndex, received, reported) {
+        if (typeof reported === 'number' && reported >= 0) {
+            count = reported;
+            countKnown = true;
+            return;
+        }
+        if (received < blockSize) {
+            count = startOf(blockIndex) + received;
+            countKnown = true;
+        }
+    }
+    /**
+     * Evict loaded blocks over the limit, least-recently-seen first, never one
+     * the viewport is currently on - dropping a visible block would swap real
+     * rows for skeletons under the user's eyes and immediately re-fetch them.
+     */
+    function evictIfNeeded() {
+        if (!Number.isFinite(maxBlocks))
+            return;
+        const firstVisible = blockOf(viewStart);
+        const lastVisible = blockOf(Math.max(viewStart, viewEnd));
+        const evictable = [...blocks.entries()]
+            .filter(([index, b]) => b.status === 'loaded' && (index < firstVisible || index > lastVisible))
+            .sort((a, b) => a[1].lastTouched - b[1].lastTouched);
+        let loaded = 0;
+        for (const b of blocks.values())
+            if (b.status === 'loaded')
+                loaded += 1;
+        for (const [index] of evictable) {
+            if (loaded <= maxBlocks)
+                break;
+            blocks.delete(index);
+            loaded -= 1;
+        }
+    }
+    function fetchViewport() {
+        if (disposed)
+            return;
+        const first = blockOf(viewStart);
+        const last = blockOf(Math.max(viewStart, viewEnd));
+        for (let i = first; i <= last; i += 1) {
+            const block = blocks.get(i);
+            if (block)
+                block.lastTouched = touchClock += 1;
+            else
+                ensureBlock(i);
+        }
+    }
+    function abortAll() {
+        for (const block of blocks.values())
+            block.controller?.abort();
+        inFlight = 0;
+        queue.length = 0;
+    }
+    return {
+        setViewport(startIndex, endIndex) {
+            if (disposed)
+                return;
+            viewStart = Math.max(0, startIndex);
+            viewEnd = Math.max(viewStart, endIndex);
+            if (debounceMs === 0) {
+                fetchViewport();
+                return;
+            }
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => {
+                debounceTimer = null;
+                fetchViewport();
+            }, debounceMs);
+        },
+        rows() {
+            if (rowsCache)
+                return rowsCache;
+            const length = currentLength();
+            const out = new Array(length);
+            // Fill from the blocks we have, then pad the rest with placeholders. One
+            // pass per block beats one lookup per row: at a million rows the
+            // difference is the frame budget.
+            out.fill(LOADING_ROW);
+            for (const [index, block] of blocks) {
+                const start = startOf(index);
+                if (start >= length)
+                    continue;
+                if (block.status === 'failed') {
+                    const end = Math.min(start + blockSize, length);
+                    for (let i = start; i < end; i += 1)
+                        out[i] = FAILED_ROW;
+                    continue;
+                }
+                for (let i = 0; i < block.rows.length && start + i < length; i += 1) {
+                    out[start + i] = block.rows[i];
+                }
+            }
+            rowsCache = out;
+            return out;
+        },
+        getRow(index) {
+            const block = blocks.get(blockOf(index));
+            if (!block)
+                return LOADING_ROW;
+            if (block.status === 'failed')
+                return FAILED_ROW;
+            const row = block.rows[index - startOf(blockOf(index))];
+            return row ?? LOADING_ROW;
+        },
+        rowCount: () => (countKnown ? count : null),
+        lastRowKnown: () => countKnown,
+        retryFailed() {
+            let any = false;
+            for (const [index, block] of [...blocks]) {
+                if (block.status !== 'failed')
+                    continue;
+                blocks.delete(index);
+                ensureBlock(index);
+                any = true;
+            }
+            if (any)
+                emit();
+        },
+        refresh() {
+            // Keep the count and the scroll position: drop the DATA, re-request the
+            // same blocks. The user sees skeletons where they were, not a jump home.
+            for (const [index, block] of [...blocks]) {
+                block.controller?.abort();
+                blocks.delete(index);
+                ensureBlock(index);
+            }
+            emit();
+        },
+        purge() {
+            abortAll();
+            blocks.clear();
+            count = null;
+            countKnown = false;
+            rowsCache = null;
+            fetchViewport();
+            emit();
+        },
+        setRowCount(next, known = next != null) {
+            count = next;
+            countKnown = known && next != null;
+            emit();
+        },
+        applyRows(startRow, rows, rowCount) {
+            if (startRow % blockSize !== 0) {
+                throw new Error(`createBlockCache.applyRows: startRow ${startRow} is not a multiple of blockSize ${blockSize}`);
+            }
+            const firstBlock = blockOf(startRow);
+            const blockCount = Math.ceil(rows.length / blockSize);
+            for (let i = 0; i < blockCount; i += 1) {
+                const index = firstBlock + i;
+                blocks.get(index)?.controller?.abort(); // ours now, whatever was in flight
+                blocks.set(index, {
+                    status: 'loaded',
+                    rows: rows.slice(i * blockSize, (i + 1) * blockSize),
+                    lastTouched: (touchClock += 1),
+                    controller: null,
+                });
+            }
+            const lastBlock = blocks.get(firstBlock + blockCount - 1);
+            if (lastBlock)
+                applyCountFrom(firstBlock + blockCount - 1, lastBlock.rows.length, rowCount);
+            else if (typeof rowCount === 'number' && rowCount >= 0) {
+                count = rowCount;
+                countKnown = true;
+            }
+            emit();
+        },
+        patch(index, row) {
+            const block = blocks.get(blockOf(index));
+            if (!block || block.status !== 'loaded')
+                return false;
+            const offset = index - startOf(blockOf(index));
+            if (offset < 0 || offset >= block.rows.length)
+                return false;
+            block.rows[offset] = row;
+            emit();
+            return true;
+        },
+        findIndex(predicate) {
+            for (const [blockIndex, block] of blocks) {
+                if (block.status !== 'loaded')
+                    continue;
+                const start = startOf(blockIndex);
+                for (let i = 0; i < block.rows.length; i += 1) {
+                    if (predicate(block.rows[i], start + i))
+                        return start + i;
+                }
+            }
+            return -1;
+        },
+        insert(index, rows) {
+            if (rows.length === 0)
+                return false;
+            const clamped = Math.max(0, Math.min(index, currentLength()));
+            const run = loadedRunAt(clamped);
+            if (run) {
+                // Rows shift across block boundaries, so re-slice the run from its
+                // first block; everything loaded past it is dropped (offsets moved).
+                run.flat.splice(clamped - startOf(run.startBlock), 0, ...rows);
+                reseat(run.startBlock, run.flat);
+            }
+            else {
+                dropLoadedFrom(blockOf(clamped));
+            }
+            if (countKnown && count != null)
+                count += rows.length;
+            emit();
+            return run != null;
+        },
+        remove(index, removeCount = 1) {
+            if (removeCount <= 0)
+                return 0;
+            const run = loadedRunAt(index);
+            if (!run)
+                return 0;
+            const removed = run.flat.splice(index - startOf(run.startBlock), removeCount).length;
+            reseat(run.startBlock, run.flat);
+            if (countKnown && count != null)
+                count = Math.max(0, count - removed);
+            emit();
+            return removed;
+        },
+        getCacheState() {
+            return [...blocks.entries()]
+                .map(([blockIndex, block]) => ({
+                blockIndex,
+                startRow: startOf(blockIndex),
+                endRow: startOf(blockIndex) + blockSize,
+                status: block.status,
+                lastTouched: block.lastTouched,
+            }))
+                .sort((a, b) => a.blockIndex - b.blockIndex);
+        },
+        dispose() {
+            disposed = true;
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = null;
+            abortAll();
+            blocks.clear();
+        },
+    };
+    /**
+     * The run of consecutive loaded blocks containing `index`, flattened, with
+     * the block it starts at. Null when the block at `index` is not loaded -
+     * an index-shifting edit there would have nothing to shift.
+     */
+    function loadedRunAt(index) {
+        const at = blockOf(index);
+        if (blocks.get(at)?.status !== 'loaded')
+            return null;
+        let startBlock = at;
+        while (blocks.get(startBlock - 1)?.status === 'loaded')
+            startBlock -= 1;
+        const flat = [];
+        for (let i = startBlock;; i += 1) {
+            const block = blocks.get(i);
+            if (!block || block.status !== 'loaded')
+                break;
+            flat.push(...block.rows);
+            if (block.rows.length < blockSize)
+                break; // the last block, by definition
+        }
+        return { startBlock, flat };
+    }
+    /**
+     * Lay a flat run back out into blocks from `startBlock`, and drop every
+     * block after the run: their rows have shifted, and re-fetching them at
+     * the new offsets is the honest outcome. Blocks before it are untouched.
+     */
+    function reseat(startBlock, flat) {
+        const blockCount = Math.ceil(flat.length / blockSize);
+        dropLoadedFrom(startBlock);
+        for (let i = 0; i < blockCount; i += 1) {
+            blocks.set(startBlock + i, {
+                status: 'loaded',
+                rows: flat.slice(i * blockSize, (i + 1) * blockSize),
+                lastTouched: (touchClock += 1),
+                controller: null,
+            });
+        }
+        rowsCache = null;
+    }
+    /** Forget every block from `fromBlock` on, aborting any in flight. */
+    function dropLoadedFrom(fromBlock) {
+        for (const [index, block] of [...blocks]) {
+            if (index < fromBlock)
+                continue;
+            block.controller?.abort();
+            blocks.delete(index);
+        }
+        rowsCache = null;
+    }
+}