How gabrielpetersson/fast-grid works
1. Repository shape
- This is a TypeScript-first library repo with two distinct parts:
- the core grid package at the repository root
- a Vite + React example app under example/ used to demo and benchmark the grid
- The root index.ts is the public entry point for consumers.
2. Primary product boundary
- The core system is a DOM-based, virtualized table/grid designed for very large row counts.
- The key architectural boundary is between:
- data/order computation off the main thread
- viewport rendering and interaction on the main thread
- The README explicitly describes multithreaded filtering/sorting using a SharedArrayBuffer and a web worker.
3. Grid rendering layer
- src/grid.ts appears to be the top-level composition layer for the visible table.
- src/cell.ts, src/row.ts, and src/scrollbar.ts indicate the UI is built from reusable primitives:
- cells render individual values
- rows group cells
- scrollbar provides custom scrolling behavior
- The design goal is heavy DOM reuse rather than recreating nodes during scroll.
4. Virtualization and viewport management
- The grid is not a full materialized table; it renders only the visible window plus whatever buffer it needs.
- The README’s references to “display millions rows at O(1)” and “custom virtualization” imply the grid maps scroll position to row index without relying on a giant native scroll container.
- This is also why a custom scrollbar exists: it avoids browser scroll-height limits.
5. Row ordering/filtering engine
- src/row-manager/row-manager.ts is the main data-organization subsystem.
- src/row-manager/timsort.ts shows that sorting is implemented with a dedicated algorithm module rather than delegating to built-in array sorting.
- src/row-manager/view-worker.ts indicates worker-based computation of row visibility/order, likely feeding the render layer with the current view state.
6. Concurrency model
- The architecture is intentionally split so expensive operations like sorting and filtering happen off-thread in a worker.
- A SharedArrayBuffer is used to share ordering/filtering state with minimal copying, matching the README’s “zero copy datatype” claim.
- The main thread remains focused on frame-critical work: scroll response, DOM updates, and painting.
7. Utility and data-shaping layer
- src/utils/filter.ts, generate-string.ts, is-empty-fast.ts, result.ts, wait.ts, and touch-scroll.ts provide supporting behavior around the core engine.
- These utilities suggest the library includes:
- fast predicate/filter helpers
- synthetic or benchmark data generation
- lightweight async coordination
- mobile/touch-specific scroll handling
- src/utils/result.ts likely standardizes success/failure communication across async or worker boundaries.
8. Input and scroll handling
- src/utils/touch-scroll.ts and src/scrollbar.ts point to custom handling for both desktop and mobile interaction.
- The README notes “non-passive scrolling” and custom scrolling on phones, so input handling is a first-class subsystem rather than a browser default.
- This is central to preserving frame rate while data changes concurrently.
9. Example application
- example/ is a standalone Vite app using React, TypeScript, and Tailwind/PostCSS for the demo UI.
- example/src/App.tsx and example/src/generateRows.ts suggest the demo creates synthetic datasets and wires the grid into a benchmark-style interface.
- example/vercel.json shows the demo is intended for easy web deployment.
10. Runtime and build tooling
- The core library is TypeScript and likely browser-only; no server runtime is evident in the root package.
- The example uses modern frontend tooling:
- Vite for bundling/dev server
- React for the demo shell
- Tailwind/PostCSS for styling
- This matters architecturally because the library itself is framework-agnostic, while the demo is framework-specific.
11. How data flows through the system
- Typical flow is:
1. consumer provides rows/data to the grid
2. row-manager computes order/filter state, often in the worker
3. shared state is updated with the current visible ordering
4. grid asks the viewport layer which rows are visible
5. row/cell primitives are reused to render only those rows
6. custom scrollbar/touch logic updates the view position
- The render path is designed to be stable even while ordering changes.
12. What an architecture diagram should emphasize
- Show a hard boundary between main-thread rendering/input and worker-based row computation.
- Show grid as the coordinator around row, cell, and scrollbar.
- Show row-manager plus timsort and view-worker as the data-processing subsystem.
- Show utils as shared support, and example/ as a separate demo consumer rather than part of the core library.
Main entry points: row-manager.ts Row manager · grid.ts Grid · view-worker.ts View worker · App.tsx App
Components 17
Core library
TypeScript grid package and its runtime subsystems.
- Entry · Root package entry point for consumers.
index.ts - Grid · Top-level composition layer for rendering and interaction.
src/grid.ts - Row · Reusable row-level rendering unit.
src/row.ts - Cell · Reusable cell-level rendering unit.
src/cell.ts - Scrollbar · Custom scrolling and position control.
src/scrollbar.ts - Row manager · Owns filtering, sorting, and visible row state.
src/row-manager/row-manager.ts - TimSort · Dedicated sorting implementation for row ordering.
src/row-manager/timsort.ts - View worker · Off-thread computation of visible order and view state.
src/row-manager/view-worker.ts - Filter · Fast filtering helpers used by row processing.
src/utils/filter.ts - Touch scroll · Mobile and touch-oriented scroll behavior.
src/utils/touch-scroll.ts - Result · Success/failure wrapper for coordination across boundaries.
src/utils/result.ts - Wait · Lightweight async timing or coordination helper.
src/utils/wait.ts - String gen · Synthetic string generation for data and benchmarks.
src/utils/generate-string.ts - Empty check · Fast emptiness test used in hot paths.
src/utils/is-empty-fast.ts
Example app
Vite + React demo and benchmark shell.
- App · React demo interface for the grid.
example/src/App.tsx - Main · Example app bootstrap and mounting entry.
example/src/main.tsx - Generate rows · Creates synthetic datasets for the demo.
example/src/generateRows.ts
Connections 19
- Entry → Grid: exports · Public entry point exposes the grid API.
- Grid → Row: renders · Grid composes visible rows from reusable row primitives.
- Row → Cell: contains · Rows are built from reusable cells.
- Grid → Scrollbar: uses · Custom scrolling drives viewport position.
- Grid → Row manager: queries · Grid asks for current ordering and visible window state.
- Grid → Touch scroll: handles · Touch and mobile scroll behavior feeds the viewport.
- Row manager → TimSort: sorts with · Ordering is delegated to a dedicated sort module.
- Row manager → View worker: delegates to · Heavy row computation runs off-thread.
- Row manager → Filter: filters with · Row filtering uses shared predicate helpers.
- Row manager → Result: reports · Worker and async outcomes are normalized as results.
- Row manager → Wait: coordinates · Async coordination supports worker-driven updates.
- Row manager → Empty check: checks · Hot-path emptiness checks support row processing.
- View worker → Result: returns · Worker work is surfaced through result-shaped messages.
- View worker → Filter: applies · Worker-side view computation uses filtering logic.
- View worker → TimSort: orders with · Worker-side ordering relies on the sort implementation.
- App → Grid: consumes · Demo shell embeds the core grid.
- App → Generate rows: generates · Demo creates benchmark-like synthetic rows.
- Main → App: mounts · Example entry bootstraps the React app.
- String gen → Generate rows: supports · Synthetic data generation is backed by string utilities.