@svgrid/grid 2.6.21 → 2.6.22

package/src/core.filter.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Equivalence + work-budget tests for `createFilteredRowModel`.
+ *
+ * The filter path used to read a cell with
+ * `row.getAllCells().find((c) => c.column.id === id)?.getValue()`. That builds
+ * and caches the row's ENTIRE `Cell[]` just to read one field, which defeats
+ * the lazy-cell design the row factory goes out of its way to provide - a
+ * one-operator filter over 100k rows materialised 100,000 cell arrays
+ * (measured; `pnpm bench --case=filter-1op`).
+ *
+ * `getCellValueByColumnId` reads the same `cachedValues` array those cells read
+ * from, so the swap is a pure win - but "same array" is a claim about today's
+ * implementation, so the equivalence half of this file pins the observable
+ * behaviour rather than trusting it.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  createCoreRowModel,
+  createFilteredRowModel,
+  createSvGridCore,
+  filterFns,
+  tableFeatures,
+  type ColumnDef,
+  type ColumnFiltersState,
+} from './core'
+
+type Row = Record<string, unknown>
+
+const COLUMNS = [
+  { field: 'text' },
+  { field: 'num' },
+  { field: 'flag' },
+  // A computed column: `fieldFn` rather than `field`, to prove the value path
+  // is the same one the cell objects use.
+  { field: 'derived', fieldFn: (r: Row) => `${String(r.text).toUpperCase()}!` },
+]
+
+/** The original implementation, verbatim, as the oracle. */
+function referenceFilter(rows: Row[], columns: typeof COLUMNS, filters: ColumnFiltersState): Row[] {
+  const value = (row: Row, id: string) => {
+    const col = columns.find((c) => c.field === id)
+    if (!col) return undefined
+    return col.fieldFn ? col.fieldFn(row) : row[col.field]
+  }
+  return rows.filter((row) =>
+    filters.every((filter) => {
+      const fn = filter.fn ? filterFns[filter.fn] : filterFns.includesString
+      return fn(value(row, filter.id), filter.value as never)
+    }),
+  )
+}
+
+function actualFilter(rows: Row[], filters: ColumnFiltersState): Row[] {
+  const grid = createSvGridCore({
+    _features: tableFeatures({}),
+    _rowModels: {
+      coreRowModel: createCoreRowModel(),
+      filteredRowModel: createFilteredRowModel(),
+    },
+    columns: COLUMNS as unknown as Array<ColumnDef<ReturnType<typeof tableFeatures>, Row>>,
+    data: rows,
+    state: { columnFilters: filters },
+  })
+  return grid.getRowModel().rows.map((r) => r.original as Row)
+}
+
+const ROWS: Row[] = [
+  { text: 'banana', num: 2, flag: true },
+  { text: 'Apple', num: 10, flag: false },
+  { text: 'apple', num: -3, flag: true },
+  { text: null, num: null, flag: null },
+  { text: undefined, num: undefined, flag: undefined },
+  { text: '', num: 0, flag: '' },
+  { text: 'APPLE pie', num: NaN, flag: 'yes' },
+]
+
+describe('createFilteredRowModel - equivalence with the original', () => {
+  const cases: Array<[string, ColumnFiltersState]> = [
+    ['no filters', []],
+    ['substring, case-insensitive', [{ id: 'text', value: 'app' }]],
+    ['substring matching nothing', [{ id: 'text', value: 'zzz' }]],
+    ['empty needle matches everything', [{ id: 'text', value: '' }]],
+    ['equals operator', [{ id: 'num', value: 10, fn: 'equals' }]],
+    ['equals against null', [{ id: 'num', value: null, fn: 'equals' }]],
+    ['two filters ANDed', [{ id: 'text', value: 'a' }, { id: 'flag', value: 'true' }]],
+    ['unknown column id', [{ id: 'nope', value: 'x' }]],
+    ['computed column via fieldFn', [{ id: 'derived', value: 'APPLE' }]],
+    ['filter on undefined values', [{ id: 'flag', value: 'undefined' }]],
+  ]
+
+  for (const [name, filters] of cases) {
+    it(`matches: ${name}`, () => {
+      const actual = actualFilter(ROWS, filters)
+      const expected = referenceFilter(ROWS, COLUMNS, filters)
+      expect(actual.length).toBe(expected.length)
+      // Identity, so row order and object identity are both checked.
+      for (let i = 0; i < actual.length; i++) expect(actual[i]).toBe(expected[i])
+    })
+  }
+})
+
+describe('createFilteredRowModel - work budget', () => {
+  /**
+   * Count how many rows materialise their full `Cell[]` during filtering.
+   *
+   * Wrapping each row in a proxy that tallies `getAllCells` is the same
+   * technique tools/bench uses, kept in-process here so the invariant is
+   * enforced by the unit suite rather than only by the bench.
+   */
+  function countCellMaterialisations(rowCount: number, filters: ColumnFiltersState): number {
+    const rows: Row[] = Array.from({ length: rowCount }, (_, i) => ({
+      text: `row-${i % 7}`,
+      num: i,
+      flag: i % 2 === 0,
+    }))
+    let calls = 0
+    const grid = createSvGridCore({
+      _features: tableFeatures({}),
+      _rowModels: {
+        coreRowModel: createCoreRowModel(),
+        filteredRowModel: (args) =>
+          createFilteredRowModel<Row>()({
+            ...args,
+            rows: args.rows.map(
+              (row) =>
+                new Proxy(row, {
+                  get(obj, prop, recv) {
+                    if (prop === 'getAllCells') calls++
+                    return Reflect.get(obj, prop, recv)
+                  },
+                }) as typeof row,
+            ),
+          }),
+      },
+      columns: COLUMNS as unknown as Array<ColumnDef<ReturnType<typeof tableFeatures>, Row>>,
+      data: rows,
+      state: { columnFilters: filters },
+    })
+    grid.getRowModel()
+    return calls
+  }
+
+  it('never materialises a row\'s cell array to read one field', () => {
+    expect(countCellMaterialisations(2_000, [{ id: 'text', value: 'row-1' }])).toBe(0)
+  })
+
+  it('stays at zero with several filters', () => {
+    expect(
+      countCellMaterialisations(2_000, [
+        { id: 'text', value: 'row' },
+        { id: 'num', value: '1' },
+        { id: 'flag', value: 'true' },
+      ]),
+    ).toBe(0)
+  })
+})

package/src/core.grouping.test.ts

@@ -0,0 +1,146 @@
+/**
+ * Grouping: the ancestor short-circuit in `resolveColumnValue`.
+ *
+ * A group row shows, for each non-aggregated column, the value its children
+ * agree on - or `undefined` when they disagree. That used to be found by
+ * scanning every child, even for a column an ANCESTOR level had already grouped
+ * by, where the answer is fixed by construction. On a 100k x 9 two-level group
+ * that was ~100,000 reads for a value already in hand.
+ *
+ * The shortcut has one genuinely sharp edge, which is what most of this file is
+ * about: buckets are keyed by `String(value ?? '')`, so `null`, `undefined` and
+ * `''` all land in the SAME bucket. A scan of that bucket reports disagreement,
+ * so the shortcut has to report disagreement too rather than picking whichever
+ * raw value happened to arrive first.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  createCoreRowModel,
+  createGroupedRowModel,
+  createSvGridCore,
+  columnGroupingFeature,
+  tableFeatures,
+  type ColumnDef,
+  type Row,
+} from './core'
+
+type Data = Record<string, unknown>
+
+function grouped(data: Data[], fields: string[], grouping: string[]) {
+  const grid = createSvGridCore({
+    _features: tableFeatures({ columnGroupingFeature }),
+    _rowModels: { coreRowModel: createCoreRowModel(), groupedRowModel: createGroupedRowModel() },
+    columns: fields.map((f) => ({ field: f })) as unknown as Array<
+      ColumnDef<ReturnType<typeof tableFeatures>, Data>
+    >,
+    data,
+    state: { grouping },
+    onGroupingChange: () => {},
+  })
+  return grid.getRowModel().rows
+}
+
+/** Walk to the group rows at a given depth. */
+function atDepth(rows: Array<Row<Data>>, depth: number): Array<Row<Data>> {
+  const out: Array<Row<Data>> = []
+  const visit = (rs: Array<Row<Data>>) => {
+    for (const r of rs) {
+      if (r.depth === depth) out.push(r)
+      if (r.subRows?.length) visit(r.subRows as Array<Row<Data>>)
+    }
+  }
+  visit(rows)
+  return out
+}
+
+describe('createGroupedRowModel - ancestor value resolution', () => {
+  const FIELDS = ['region', 'status', 'owner', 'amount']
+
+  it('a second-level group still reports the first level value', () => {
+    const data: Data[] = [
+      { region: 'EMEA', status: 'open', owner: 'ada', amount: 1 },
+      { region: 'EMEA', status: 'open', owner: 'ada', amount: 2 },
+      { region: 'EMEA', status: 'shut', owner: 'bob', amount: 3 },
+      { region: 'APAC', status: 'open', owner: 'cy', amount: 4 },
+    ]
+    const inner = atDepth(grouped(data, FIELDS, ['region', 'status']), 1)
+    expect(inner.length).toBe(3)
+    for (const g of inner) {
+      // `region` is fixed by the ancestor bucket, so every inner group must
+      // report it rather than undefined.
+      expect(['EMEA', 'APAC']).toContain(g.getCellValueByColumnId('region'))
+    }
+    // And the columns that genuinely vary still resolve the old way.
+    const emeaOpen = inner.find((g) => g.getCellValueByColumnId('status') === 'open')!
+    expect(emeaOpen.getCellValueByColumnId('owner')).toBe('ada')
+  })
+
+  it('reports disagreement when a bucket mixed null, undefined and empty string', () => {
+    // All three key to '' and share one bucket. A scan would find they disagree,
+    // so the shortcut must not report whichever arrived first.
+    const data: Data[] = [
+      { region: null, status: 'x', owner: 'a', amount: 1 },
+      { region: undefined, status: 'y', owner: 'b', amount: 2 },
+      { region: '', status: 'z', owner: 'c', amount: 3 },
+    ]
+    const inner = atDepth(grouped(data, FIELDS, ['region', 'status']), 1)
+    expect(inner.length).toBe(3)
+    for (const g of inner) {
+      // Each inner bucket holds exactly one row, so `region` is whatever that
+      // row had - not a value borrowed from a sibling.
+      const status = g.getCellValueByColumnId('status')
+      const expected = data.find((d) => d.status === status)!.region
+      expect(g.getCellValueByColumnId('region')).toBe(expected)
+    }
+  })
+
+  it('a mixed ancestor bucket resolves to undefined at the deeper level', () => {
+    // One inner bucket spanning rows whose raw region values differ but key the
+    // same. `status` is identical so they stay together at level two.
+    const data: Data[] = [
+      { region: null, status: 'same', owner: 'a', amount: 1 },
+      { region: '', status: 'same', owner: 'a', amount: 2 },
+    ]
+    const inner = atDepth(grouped(data, FIELDS, ['region', 'status']), 1)
+    expect(inner.length).toBe(1)
+    // A scan of [null, ''] disagrees, so this must be undefined.
+    expect(inner[0]!.getCellValueByColumnId('region')).toBeUndefined()
+  })
+
+  it('preserves the raw type of an ancestor value rather than its bucket key', () => {
+    // Buckets are keyed by String(value), so a numeric grouping column would
+    // report '2024' instead of 2024 if the shortcut returned the key.
+    const data: Data[] = [
+      { region: 2024, status: 'a', owner: 'x', amount: 1 },
+      { region: 2024, status: 'b', owner: 'y', amount: 2 },
+    ]
+    const inner = atDepth(grouped(data, FIELDS, ['region', 'status']), 1)
+    expect(inner.length).toBe(2)
+    for (const g of inner) {
+      expect(g.getCellValueByColumnId('region')).toBe(2024)
+    }
+  })
+
+  it('handles three levels', () => {
+    const data: Data[] = [
+      { region: 'EMEA', status: 'open', owner: 'ada', amount: 1 },
+      { region: 'EMEA', status: 'open', owner: 'ada', amount: 2 },
+      { region: 'EMEA', status: 'open', owner: 'bob', amount: 3 },
+    ]
+    const deepest = atDepth(grouped(data, FIELDS, ['region', 'status', 'owner']), 2)
+    expect(deepest.length).toBe(2)
+    for (const g of deepest) {
+      expect(g.getCellValueByColumnId('region')).toBe('EMEA')
+      expect(g.getCellValueByColumnId('status')).toBe('open')
+    }
+  })
+
+  it('still returns undefined for a non-grouping column whose children disagree', () => {
+    const data: Data[] = [
+      { region: 'EMEA', status: 'open', owner: 'ada', amount: 1 },
+      { region: 'EMEA', status: 'open', owner: 'bob', amount: 2 },
+    ]
+    const inner = atDepth(grouped(data, FIELDS, ['region', 'status']), 1)
+    expect(inner[0]!.getCellValueByColumnId('owner')).toBeUndefined()
+  })
+})

package/src/core.row-shape.test.ts

@@ -0,0 +1,119 @@
+/**
+ * The public shape of a `Row`.
+ *
+ * Rows were rewritten from object literals with per-row closures to objects
+ * carrying shared `this`-based methods, which cut mount allocation from 56.5 MB
+ * to 14.5 MB. Those shared methods need a pointer back to the table, and the
+ * first version stored it as a plain `_ctx` property - which made every row
+ * serialise the whole grid, because `options.data` is reachable through it.
+ * `JSON.stringify(oneRow)` grew with the dataset: 981 characters at 3 rows,
+ * 67,719 at 3,000. Stringifying a row model was quadratic.
+ *
+ * The fix is to key the internals with symbols: invisible to `JSON.stringify`,
+ * `Object.keys` and `for...in`, but still copied by object spread, which
+ * several row models rely on when they do `{ ...row, depth }`.
+ *
+ * These tests pin all four of those properties. `Row` is public API and its
+ * observable shape is part of the contract.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  createCoreRowModel,
+  createGroupedRowModel,
+  createSvGridCore,
+  columnGroupingFeature,
+  tableFeatures,
+  type ColumnDef,
+} from './core'
+
+type Data = Record<string, unknown>
+
+function makeGrid(count: number, grouping: string[] = []) {
+  const data: Data[] = Array.from({ length: count }, (_, i) => ({
+    name: `row-${i}`,
+    score: i,
+    bucket: i % 2 === 0 ? 'even' : 'odd',
+  }))
+  return createSvGridCore({
+    _features: tableFeatures({ columnGroupingFeature }),
+    _rowModels: grouping.length
+      ? { coreRowModel: createCoreRowModel(), groupedRowModel: createGroupedRowModel() }
+      : { coreRowModel: createCoreRowModel() },
+    columns: [{ field: 'name' }, { field: 'score' }, { field: 'bucket' }] as unknown as Array<
+      ColumnDef<ReturnType<typeof tableFeatures>, Data>
+    >,
+    data,
+    state: { grouping },
+    onGroupingChange: () => {},
+  })
+}
+
+const PUBLIC_KEYS = [
+  'id',
+  'index',
+  'original',
+  'depth',
+  'getCanExpand',
+  'getIsExpanded',
+  'toggleExpanded',
+  'getIsSelected',
+  'toggleSelected',
+  'getAllCells',
+  'getCellValueByColumnId',
+]
+
+describe('Row public shape', () => {
+  it('exposes exactly the documented keys, with no internals', () => {
+    const row = makeGrid(10).getRowModel().rows[0]!
+    expect(Object.keys(row).sort()).toEqual([...PUBLIC_KEYS].sort())
+  })
+
+  it('does not leak internals through for...in', () => {
+    const row = makeGrid(10).getRowModel().rows[0]!
+    const seen: string[] = []
+    for (const k in row) seen.push(k)
+    expect(seen.sort()).toEqual([...PUBLIC_KEYS].sort())
+  })
+
+  it('serialises to a constant size regardless of dataset size', () => {
+    // The regression this guards: `_ctx` reached `options.data`, so a single
+    // row carried the entire grid into JSON. Sizes must not grow with count.
+    const sizes = [10, 100, 1000].map(
+      (n) => JSON.stringify(makeGrid(n).getRowModel().rows[0]).length,
+    )
+    expect(new Set(sizes).size).toBe(1)
+    // And it must stay small - this is 4 scalar fields, not a grid.
+    expect(sizes[0]!).toBeLessThan(200)
+  })
+
+  it('serialises a whole row model linearly, not quadratically', () => {
+    const small = JSON.stringify(makeGrid(50).getRowModel().rows).length
+    const large = JSON.stringify(makeGrid(500).getRowModel().rows).length
+    // Ten times the rows should cost about ten times the characters. Quadratic
+    // growth would put this well past 20x.
+    expect(large).toBeLessThan(small * 20)
+  })
+
+  it('survives an object spread with its methods intact', () => {
+    // `createGroupedRowModel` does `{ ...row, depth }` for leaf rows; the clone
+    // has to keep working, which is why the internals are symbol-keyed rather
+    // than non-enumerable.
+    const row = makeGrid(10).getRowModel().rows[0]!
+    const clone = { ...row, depth: 3 }
+    expect(clone.depth).toBe(3)
+    expect(typeof clone.getCellValueByColumnId).toBe('function')
+    expect(clone.getCellValueByColumnId('name')).toBe(row.getCellValueByColumnId('name'))
+    expect(clone.getIsSelected()).toBe(false)
+    // The clone must not have grown a public surface either.
+    expect(Object.keys(clone).sort()).toEqual([...PUBLIC_KEYS].sort())
+  })
+
+  it('keeps grouped leaf rows working after the model clones them', () => {
+    const rows = makeGrid(10, ['bucket']).getRowModel().rows
+    const group = rows[0]!
+    expect(group.subRows?.length).toBeGreaterThan(0)
+    const leaf = group.subRows![0]!
+    expect(leaf.getCellValueByColumnId('name')).toMatch(/^row-\d+$/)
+    expect(leaf.depth).toBe(1)
+  })
+})

package/src/core.rowmodel-cache.test.ts

@@ -0,0 +1,121 @@
+/**
+ * Row-model memo invalidation.
+ *
+ * `getRowModel()` caches on the identity of the data, the columns, and a set of
+ * state slices. `rowSelection` was one of those slices, so ticking a single
+ * checkbox on a 100k-row grid re-ran the whole pipeline - re-filtering and
+ * re-sorting the entire dataset - to produce a row array that was, by
+ * construction, identical. Measured at 5 full re-runs for 5 toggles
+ * (`pnpm bench --case=selection-toggle`).
+ *
+ * Nothing in the pipeline reads selection. The two consumers, `getIsSelected`
+ * on data rows (core.ts) and on group rows, are closures that read
+ * `store.state` when called, so they see a selection change without the model
+ * being rebuilt. That is what the last test here pins: dropping the slice must
+ * not make a selected row report the wrong thing.
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  createCoreRowModel,
+  createFilteredRowModel,
+  createSortedRowModel,
+  createSvGridCore,
+  rowSelectionFeature,
+  tableFeatures,
+  type ColumnDef,
+  type RowModelFactory,
+} from './core'
+
+type Row = { id: number; name: string; score: number }
+
+const COLUMNS = [
+  { field: 'id', editorType: 'number' },
+  { field: 'name' },
+  { field: 'score', editorType: 'number' },
+]
+
+function makeRows(n: number): Row[] {
+  return Array.from({ length: n }, (_, i) => ({
+    id: i,
+    name: `name-${(i * 7919) % n}`,
+    score: (i * 31) % 1000,
+  }))
+}
+
+/** Wrap a stage so we can count how many times the pipeline actually ran it. */
+function counted<T extends Row>(factory: RowModelFactory<T>, tally: { n: number }): RowModelFactory<T> {
+  return (args) => {
+    tally.n++
+    return factory(args)
+  }
+}
+
+function makeGrid(rows: Row[], tallies: { filter: { n: number }; sort: { n: number } }) {
+  return createSvGridCore({
+    _features: tableFeatures({ rowSelectionFeature }),
+    _rowModels: {
+      coreRowModel: createCoreRowModel(),
+      filteredRowModel: counted(createFilteredRowModel<Row>(), tallies.filter),
+      sortedRowModel: counted(createSortedRowModel<Row>(), tallies.sort),
+    },
+    columns: COLUMNS as unknown as Array<ColumnDef<ReturnType<typeof tableFeatures>, Row>>,
+    data: rows,
+    state: {
+      columnFilters: [{ id: 'name', value: 'name-' }],
+      sorting: [{ id: 'score', desc: false }],
+      rowSelection: {},
+    },
+  })
+}
+
+describe('row-model cache: selection', () => {
+  it('does not re-run the pipeline when only the selection changes', () => {
+    const tallies = { filter: { n: 0 }, sort: { n: 0 } }
+    const grid = makeGrid(makeRows(500), tallies)
+
+    grid.getRowModel() // first build - expected to run
+    const after = { filter: tallies.filter.n, sort: tallies.sort.n }
+    expect(after.filter).toBe(1)
+    expect(after.sort).toBe(1)
+
+    for (let i = 0; i < 5; i++) {
+      grid.setRowSelection((prev) => ({ ...prev, [String(i)]: true }))
+      grid.getRowModel()
+    }
+
+    expect(tallies.filter.n - after.filter).toBe(0)
+    expect(tallies.sort.n - after.sort).toBe(0)
+  })
+
+  it('still re-runs when a slice the pipeline DOES read changes', () => {
+    const tallies = { filter: { n: 0 }, sort: { n: 0 } }
+    const grid = makeGrid(makeRows(200), tallies)
+    grid.getRowModel()
+    const before = tallies.sort.n
+
+    // No `setSorting` on the core - sorting is driven through the store (or a
+    // column's `toggleSorting`), which is also how <SvGrid> does it.
+    grid.store.setState((prev) => ({ ...prev, sorting: [{ id: 'score', desc: true }] }))
+    grid.getRowModel()
+
+    expect(tallies.sort.n).toBeGreaterThan(before)
+  })
+
+  it('reports selection correctly even though the model was not rebuilt', () => {
+    const tallies = { filter: { n: 0 }, sort: { n: 0 } }
+    const grid = makeGrid(makeRows(50), tallies)
+
+    const rows = grid.getRowModel().rows
+    const target = rows[3]!
+    expect(target.getIsSelected()).toBe(false)
+
+    grid.setRowSelection((prev) => ({ ...prev, [target.id]: true }))
+
+    // Same row object, no rebuild - the closure must observe the new state.
+    expect(grid.getRowModel().rows[3]).toBe(target)
+    expect(target.getIsSelected()).toBe(true)
+
+    grid.setRowSelection(() => ({}))
+    expect(target.getIsSelected()).toBe(false)
+  })
+})