@svgrid/grid 3.0.7 → 3.0.9

package/src/virtualization/virtualizer.ts

@@ -11,6 +11,8 @@ function sameOptions(a: VirtualizerOptions, b: VirtualizerOptions) {
     a.count === b.count &&
     a.estimateSize === b.estimateSize &&
     (a.overscan ?? 6) === (b.overscan ?? 6) &&
+    a.overscanBehind === b.overscanBehind &&
+    a.overscanMin === b.overscanMin &&
     a.viewportHeight === b.viewportHeight &&
     (a.scrollOffset ?? 0) === (b.scrollOffset ?? 0)
   )
@@ -133,13 +135,14 @@ function buildVariableItems(
   return items
 }
 
-function createState(
+/** The items under the viewport at the current scroll offset, before any
+ *  overscan. */
+function visibleRange(
   options: VirtualizerOptions,
   /** Pre-built cumulative offsets for the variable-size path. */
   offsets: Array<number> | null,
-): VirtualizerState {
+) {
   const count = Math.max(options.count, 0)
-  const overscan = Math.max(options.overscan ?? 6, 0)
   const viewportHeight = Math.max(options.viewportHeight, 0)
 
   if (typeof options.estimateSize === 'function' && offsets) {
@@ -167,38 +170,59 @@ function createState(
       else hi = mid
     }
     const visibleEnd = Math.max(lo - 1, visibleStart)
-
-    const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1)
-    const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1)
-
-    return {
-      items: endIndex >= startIndex ? buildVariableItems(startIndex, endIndex, offsets) : [],
-      totalSize,
-      startIndex,
-      endIndex,
-      scrollOffset,
-      viewportHeight,
-    }
+    return { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize: 0 }
   }
 
   // Uniform-size fast path (original behavior).
-  const estimateSize = Math.max(
+  const uniformSize = Math.max(
     typeof options.estimateSize === 'number' ? options.estimateSize : 1,
     1,
   )
-  const totalSize = count * estimateSize
+  const totalSize = count * uniformSize
   const maxOffset = Math.max(totalSize - viewportHeight, 0)
   const scrollOffset = clamp(options.scrollOffset ?? 0, 0, maxOffset)
 
-  const visibleStart = Math.floor(scrollOffset / estimateSize)
-  const visibleCount = Math.ceil(viewportHeight / estimateSize)
+  const visibleStart = Math.floor(scrollOffset / uniformSize)
+  const visibleCount = Math.ceil(viewportHeight / uniformSize)
   const visibleEnd = Math.min(visibleStart + visibleCount, Math.max(count - 1, 0))
+  return { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize }
+}
 
-  const startIndex = count === 0 ? 0 : clamp(visibleStart - overscan, 0, count - 1)
-  const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscan, 0, count - 1)
+function createState(
+  options: VirtualizerOptions,
+  /** Pre-built cumulative offsets for the variable-size path. */
+  offsets: Array<number> | null,
+  /** The scroll moved on from the window already rendered. With
+   *  `overscanMin`, only then does the full `overscan` go ahead; a window
+   *  built at rest or after a jump carries `overscanMin`, so a thumb drag
+   *  that jumps every frame renders no more than it needs. */
+  scrolling = false,
+): VirtualizerState {
+  const full = Math.max(options.overscan ?? 6, 0)
+  const overscan =
+    options.overscanMin === undefined || scrolling ? full : clamp(options.overscanMin, 0, full)
+  // The overscan goes ahead of the scroll and `overscanBehind` behind it:
+  // items behind the movement were just scrolled past, and a horizontal
+  // scroll that kept three columns on each side drew ~40% more cells than it
+  // needed to (350 vs 275 in the wide benchmark).
+  const behind = Math.min(Math.max(options.overscanBehind ?? full, 0), overscan)
+  const direction = options.scrollDirection ?? 0
+  const overscanBefore = direction > 0 ? behind : overscan
+  const overscanAfter = direction < 0 ? behind : overscan
+  const { count, viewportHeight, totalSize, scrollOffset, visibleStart, visibleEnd, uniformSize } =
+    visibleRange(options, offsets)
+
+  const startIndex = count === 0 ? 0 : clamp(visibleStart - overscanBefore, 0, count - 1)
+  const endIndex = count === 0 ? -1 : clamp(visibleEnd + overscanAfter, 0, count - 1)
 
+  let items: Array<VirtualItem> = []
+  if (endIndex >= startIndex) {
+    items = uniformSize > 0
+      ? buildUniformItems(startIndex, endIndex, uniformSize)
+      : buildVariableItems(startIndex, endIndex, offsets!)
+  }
   return {
-    items: endIndex >= startIndex ? buildUniformItems(startIndex, endIndex, estimateSize) : [],
+    items,
     totalSize,
     startIndex,
     endIndex,
@@ -251,13 +275,52 @@ export function createVirtualizer(initial: VirtualizerOptions) {
     listeners.forEach((listener) => listener())
   }
 
-  function recalc() {
-    const next = createState(options, getOffsets())
+  function recalc(scrolling = false) {
+    const next = createState(options, getOffsets(), scrolling)
     if (sameState(state, next)) return
+    // Hand back the previous item object for a row whose index, offset, size
+    // and slot did not change. The grid's row {#each} is keyed by slot, so a
+    // row that stays in the window keeps its <tr>, but a new item object
+    // still invalidated everything that row and its cells derive from it:
+    // every scroll frame re-checked ~300 cells to render the two that came
+    // into view, and Svelte's dependency marking was most of the frame's
+    // script time (measured 4.8 of 8.3 ms on a 100k-row grid).
+    if (state.items.length > 0 && next.items.length > 0) {
+      const first = state.items[0]!.index
+      const items = next.items
+      for (let i = 0; i < items.length; i += 1) {
+        const item = items[i]!
+        const prev = state.items[item.index - first]
+        if (prev && prev.index === item.index && prev.start === item.start && prev.size === item.size && prev.key === item.key) {
+          items[i] = prev
+        }
+      }
+    }
     state = next
     emit()
   }
 
+  /**
+   * What a scroll does to the window already rendered, with `overscanMin`:
+   * 'hold' while that window still covers the visible items plus
+   * `overscanMin` ahead of the scroll, 'move' once the scroll runs past that
+   * (the window moves on with the full overscan ahead), and 'jump' when the
+   * visible items are nowhere in it. Without `overscanMin` every scroll moves
+   * the window.
+   */
+  function scrollStep(): 'hold' | 'move' | 'jump' {
+    const min = options.overscanMin
+    if (min === undefined || state.items.length === 0) return 'move'
+    const ahead = clamp(min, 0, Math.max(options.overscan ?? 6, 0))
+    const { count, viewportHeight, totalSize, visibleStart, visibleEnd } = visibleRange(options, getOffsets())
+    if (count === 0 || viewportHeight !== state.viewportHeight || totalSize !== state.totalSize) return 'jump'
+    if (visibleStart > state.endIndex || visibleEnd < state.startIndex) return 'jump'
+    const direction = options.scrollDirection ?? 0
+    const needStart = Math.max(visibleStart - (direction < 0 ? ahead : 0), 0)
+    const needEnd = Math.min(visibleEnd + (direction > 0 ? ahead : 0), count - 1)
+    return state.startIndex <= needStart && state.endIndex >= needEnd ? 'hold' : 'move'
+  }
+
   return {
     setOptions(next: Partial<VirtualizerOptions>) {
       const merged = { ...options, ...next }
@@ -278,9 +341,12 @@ export function createVirtualizer(initial: VirtualizerOptions) {
       recalc()
     },
     setScrollOffset(scrollOffset: number) {
-      if ((options.scrollOffset ?? 0) === scrollOffset) return
-      options = { ...options, scrollOffset }
-      recalc()
+      const previous = options.scrollOffset ?? 0
+      if (previous === scrollOffset) return
+      options = { ...options, scrollOffset, scrollDirection: scrollOffset > previous ? 1 : -1 }
+      const step = scrollStep()
+      if (step === 'hold') return
+      recalc(step === 'move')
     },
     setViewportHeight(viewportHeight: number) {
       if (options.viewportHeight === viewportHeight) return

package/src/windowed-brand.ts

@@ -0,0 +1,67 @@
+/**
+ * What marks an array as windowed data, and how to tell (windowed-data.ts has
+ * the full story). Kept apart from createWindowedData so code that only asks
+ * "is this windowed?" - the controller, the core's per-update paths - does not
+ * pull in the windowed row model that createWindowedData installs.
+ */
+
+const WINDOWED = Symbol.for('svgrid.windowedData')
+
+export type WindowedSource<T> = {
+  /** The number of rows, loaded or not. */
+  readonly length: number
+  /** The entry at `index`: a loaded row, a placeholder, or undefined. */
+  at(index: number): T | undefined
+}
+
+const isIndexKey = (key: string | symbol): key is string =>
+  typeof key === 'string' && key.length > 0 && key.length < 16 && /^(0|[1-9]\d*)$/.test(key)
+
+/**
+ * An array of `length` entries read through `at(i)`: a real `Array` (a Proxy
+ * over an empty one) carrying the windowed mark. Each call returns a new
+ * array identity, which is how a source tells the grid its rows changed.
+ */
+export function makeWindowedArray<T>(length: number, at: (index: number) => T | undefined): T[] {
+  const source: WindowedSource<T> = { length, at }
+  const target: T[] = []
+  return new Proxy(target, {
+    get(t, key, receiver) {
+      if (key === WINDOWED) return source
+      if (key === 'length') return length
+      if (isIndexKey(key)) {
+        const i = Number(key)
+        return i < length ? at(i) : undefined
+      }
+      return Reflect.get(t, key, receiver)
+    },
+    has(t, key) {
+      if (key === WINDOWED) return true
+      if (isIndexKey(key)) return Number(key) < length
+      return Reflect.has(t, key)
+    },
+    set() {
+      // Read-only: a write would land in the empty target and never be seen.
+      return false
+    },
+    getOwnPropertyDescriptor(t, key) {
+      if (isIndexKey(key) && Number(key) < length) {
+        return { value: at(Number(key)), writable: false, enumerable: true, configurable: true }
+      }
+      if (key === 'length') return { value: length, writable: true, enumerable: false, configurable: false }
+      return Reflect.getOwnPropertyDescriptor(t, key)
+    },
+  })
+}
+
+/** The source behind windowed data, or null for an ordinary array. */
+export function windowedSourceOf<T>(data: unknown): WindowedSource<T> | null {
+  if (data === null || typeof data !== 'object') return null
+  const source = (data as Record<symbol, unknown>)[WINDOWED]
+  return (source as WindowedSource<T> | undefined) ?? null
+}
+
+/** True for windowed data. */
+export function isWindowedData(data: unknown): boolean {
+  return windowedSourceOf(data) !== null
+}

package/src/windowed-data.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Windowed data: an array whose entries are read on demand, so a server row
+ * model can hand the grid 100M rows without building 100M of anything.
+ */
+import { describe, expect, it } from 'vitest'
+import { createWindowedData, isWindowedData, windowedSourceOf } from './windowed-data'
+import { createSvGridCore } from './core'
+import { createCoreRowModel, tableFeatures } from './index'
+import { createBlockCache } from './server-block-cache'
+
+describe('createWindowedData', () => {
+  it('reports the length and reads entries through at()', () => {
+    const reads: number[] = []
+    const data = createWindowedData(100_000_000, (i) => {
+      reads.push(i)
+      return { id: i }
+    })
+    expect(Array.isArray(data)).toBe(true)
+    expect(data.length).toBe(100_000_000)
+    expect(data[99_999_999]).toEqual({ id: 99_999_999 })
+    expect(data[100_000_000]).toBeUndefined()
+    expect(reads).toEqual([99_999_999])
+  })
+
+  it('is recognised, and ordinary arrays are not', () => {
+    const data = createWindowedData(3, (i) => i)
+    expect(isWindowedData(data)).toBe(true)
+    expect(windowedSourceOf(data)?.length).toBe(3)
+    expect(isWindowedData([1, 2, 3])).toBe(false)
+    expect(isWindowedData(null)).toBe(false)
+  })
+
+  it('still iterates like an array', () => {
+    const data = createWindowedData(4, (i) => i * 10)
+    expect([...data]).toEqual([0, 10, 20, 30])
+    expect(data.slice(1, 3)).toEqual([10, 20])
+    expect(2 in data).toBe(true)
+    expect(9 in data).toBe(false)
+  })
+
+  it('refuses writes', () => {
+    const data = createWindowedData(2, (i) => i) as number[]
+    expect(() => {
+      'use strict'
+      data[0] = 5
+    }).toThrow()
+  })
+})
+
+describe('core row model over windowed data', () => {
+  function grid(data: unknown) {
+    return createSvGridCore({
+      _features: tableFeatures({}),
+      _rowModels: { coreRowModel: createCoreRowModel() },
+      columns: [{ field: 'v', header: 'V' }],
+      data: data as any[],
+      getRowId: (r: any) => String(r.id),
+      state: {},
+    } as any)
+  }
+
+  it('builds a row only for the indices that are read', () => {
+    let reads = 0
+    const data = createWindowedData(50_000_000, (i) => {
+      reads += 1
+      return { id: i, v: i * 2 }
+    })
+    const rows = grid(data).getRowModel().rows
+    expect(rows.length).toBe(50_000_000)
+    expect(reads).toBe(0)
+    const row = rows[25_000_000]!
+    expect(row.id).toBe('25000000')
+    expect(row.index).toBe(25_000_000)
+    expect(row.getCellValueByColumnId('v')).toBe(50_000_000)
+    expect(reads).toBe(1)
+  })
+
+  it('keeps a row object while its data object is the same', () => {
+    const objects = [{ id: 0, v: 1 }, { id: 1, v: 2 }]
+    const g = grid(createWindowedData(2, (i) => objects[i]))
+    const first = g.getRowModel().rows[1]
+    expect(g.getRowModel().rows[1]).toBe(first)
+  })
+})
+
+describe('block cache windowedRows', () => {
+  it('spans the row count without materialising it', async () => {
+    const cache = createBlockCache<{ id: number }>({
+      blockSize: 100,
+      initialRowCount: 1,
+      fetch: async (start, end) => ({
+        rows: Array.from({ length: end - start }, (_, k) => ({ id: start + k })),
+        rowCount: 100_000_000,
+      }),
+      onChange: () => {},
+    })
+    cache.setViewport(0, 10)
+    for (let i = 0; i < 10; i += 1) await Promise.resolve()
+    const rows = cache.windowedRows()
+    expect(rows.length).toBe(100_000_000)
+    expect(rows[5]).toEqual({ id: 5 })
+    expect(cache.windowedRows()).toBe(rows) // memoised until the next change
+    cache.dispose()
+  })
+})

package/src/windowed-data.ts

@@ -0,0 +1,36 @@
+/**
+ * Windowed data: an array the grid can index without anyone having built it.
+ *
+ * A server row model knows how many rows there are and holds a few blocks of
+ * them. Handing the grid a dense array of `rowCount` entries (placeholders
+ * for everything not loaded) made every block landing cost O(rowCount): the
+ * array itself, a copy in the controller, and a row object per entry in the
+ * core. At 10M rows that was ~1 GB of heap and ~1 s per block; at 100M the
+ * grid never painted.
+ *
+ * `createWindowedData(length, at)` returns a real `Array` (a Proxy over one)
+ * whose `length` is the row count and whose entries are read through `at(i)`
+ * on demand. The grid recognises it (`windowedSourceOf`) and builds row
+ * objects only for the indices it actually reads - the rows on screen, plus
+ * whatever a user action touches. Iterating one still works (it is an array),
+ * but costs O(length), so the grid's per-update paths check for it first.
+ *
+ * Windowed data is final: the source has already sorted, filtered and grouped
+ * it, so the grid's own sort / filter / group stages do not run over it.
+ *
+ * The row model that reads it (windowed-row-model.ts) is installed by the
+ * first call here, so a grid never handed windowed data does not bundle it.
+ */
+import { makeWindowedArray } from './windowed-brand'
+import { enableWindowedRowModel } from './windowed-row-model'
+
+export { windowedSourceOf, isWindowedData, type WindowedSource } from './windowed-brand'
+
+/**
+ * An array of `length` entries read through `at(i)`. Each call returns a new
+ * array identity, which is how a source tells the grid its rows changed.
+ */
+export function createWindowedData<T>(length: number, at: (index: number) => T | undefined): T[] {
+  enableWindowedRowModel()
+  return makeWindowedArray(length, at)
+}

package/src/windowed-row-model.ts

@@ -0,0 +1,113 @@
+/**
+ * The row model for windowed data (see windowed-data.ts).
+ *
+ * No build loop and no pipeline stages: `rows` is itself windowed. A row
+ * object is made the first time an index is read and kept (up to
+ * WINDOWED_ROW_CAP) while its data object is the same one, so scrolling back
+ * does not rebuild what is still loaded, and scrolling a 100M-row source end
+ * to end keeps a few thousand rows, not 100M.
+ *
+ * Installed into the core by the first createWindowedData() call rather than
+ * imported by core.ts, so a grid that is never handed windowed data does not
+ * bundle any of this.
+ */
+import {
+  BASE_ROW_METHODS,
+  ROW_CELLS,
+  ROW_CTX,
+  ROW_FILTER_GEN,
+  ROW_FILTER_POS,
+  ROW_SORT_DROPPED,
+  ROW_SORT_KEY,
+  ROW_VALUES,
+  registerWindowedRowModel,
+  type BaseRowCtx,
+  type BaseRowState,
+  type Column,
+  type Row,
+  type RowData,
+  type RowModel,
+} from './core'
+import { makeWindowedArray, windowedSourceOf } from './windowed-brand'
+
+/** The windowed-data version a row's memoised values belong to. */
+const ROW_WINDOW_GEN = Symbol('svgrid.row.windowGen')
+const WINDOWED_ROW_CAP = 20_000
+
+let installed = false
+
+export function enableWindowedRowModel(): void {
+  if (installed) return
+  installed = true
+  registerWindowedRowModel(<TData extends RowData>(ctx: {
+    rowCtxFor: (columns: Array<Column<TData>>) => BaseRowCtx<TData>
+    getRowId: () => ((row: TData, index: number) => string) | undefined
+  }) => {
+    // Per grid: the model for the current input, and the row objects built
+    // so far, by index.
+    let current: { input: unknown; columns: Array<Column<TData>>; model: RowModel<TData> } | null = null
+    const rows = new Map<number, BaseRowState<TData>>()
+    let generation = 0
+
+    return (data: unknown, columns: Array<Column<TData>>): RowModel<TData> | null => {
+      const source = windowedSourceOf<TData>(data)
+      if (!source) return null
+      if (current && current.input === data && current.columns === columns) return current.model
+      if (!current || current.columns !== columns) rows.clear()
+      const rowCtx = ctx.rowCtxFor(columns)
+      const getRowId = ctx.getRowId()
+      const gen = ++generation
+      const m = BASE_ROW_METHODS as unknown as BaseRowState<TData>
+      const rowAt = (index: number): Row<TData> | undefined => {
+        if (index < 0 || index >= source.length) return undefined
+        const original = source.at(index)
+        if (original === undefined) return undefined
+        const kept = rows.get(index) as (BaseRowState<TData> & { [ROW_WINDOW_GEN]?: number }) | undefined
+        if (kept && kept.original === original) {
+          // A new data version may follow an in-place edit of the object, as
+          // in the dense path: drop the memoised values once per version.
+          if (kept[ROW_WINDOW_GEN] !== gen) {
+            kept[ROW_VALUES] = null
+            kept[ROW_CELLS] = null
+            kept[ROW_WINDOW_GEN] = gen
+          }
+          return kept
+        }
+        const row = {
+          id: getRowId ? getRowId(original, index) : String(index),
+          index,
+          original,
+          depth: 0,
+          [ROW_CTX]: rowCtx,
+          [ROW_VALUES]: null,
+          [ROW_CELLS]: null,
+          [ROW_FILTER_GEN]: 0,
+          [ROW_FILTER_POS]: -1,
+          [ROW_SORT_DROPPED]: 0,
+          [ROW_SORT_KEY]: undefined,
+          [ROW_WINDOW_GEN]: gen,
+          getCanExpand: m.getCanExpand,
+          getIsExpanded: m.getIsExpanded,
+          toggleExpanded: m.toggleExpanded,
+          getIsSelected: m.getIsSelected,
+          toggleSelected: m.toggleSelected,
+          getAllCells: m.getAllCells,
+          getCellValueByColumnId: m.getCellValueByColumnId,
+        } as unknown as BaseRowState<TData>
+        rows.set(index, row)
+        if (rows.size > WINDOWED_ROW_CAP) {
+          // Oldest first (Map keeps insertion order); a quarter at a time.
+          let drop = WINDOWED_ROW_CAP / 4
+          for (const key of rows.keys()) {
+            if (drop-- <= 0) break
+            rows.delete(key)
+          }
+        }
+        return row
+      }
+      const model: RowModel<TData> = { rows: makeWindowedArray(source.length, rowAt) as Array<Row<TData>> }
+      current = { input: data, columns, model }
+      return model
+    }
+  })
+}