# gabrielpetersson/fast-grid architecture

> Architecture diagram of the GitHub repository gabrielpetersson/fast-grid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gabrielpetersson/fast-grid
- Repository: https://github.com/gabrielpetersson/fast-grid

## Overview

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: [`src/row-manager/row-manager.ts`](https://github.com/gabrielpetersson/fast-grid/blob/master/src/row-manager/row-manager.ts) (Row manager), [`src/grid.ts`](https://github.com/gabrielpetersson/fast-grid/blob/master/src/grid.ts) (Grid), [`src/row-manager/view-worker.ts`](https://github.com/gabrielpetersson/fast-grid/blob/master/src/row-manager/view-worker.ts) (View worker), [`example/src/App.tsx`](https://github.com/gabrielpetersson/fast-grid/blob/master/example/src/App.tsx) (App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_index["Entry<br/>public API<br/>[index.ts]"]
  node_grid["Grid<br/>viewport coordinator<br/>[grid.ts]"]
  node_row["Row<br/>[row.ts]"]
  node_cell["Cell<br/>[cell.ts]"]
  node_scrollbar["Scrollbar<br/>scroll control<br/>[scrollbar.ts]"]
  node_row_manager["Row manager<br/>ordering engine<br/>[row-manager.ts]"]
  node_timsort["TimSort<br/>sort algorithm<br/>[timsort.ts]"]
  node_view_worker["View worker<br/>worker bridge<br/>[view-worker.ts]"]
  node_filter_util["Filter<br/>predicate helpers<br/>[filter.ts]"]
  node_touch_scroll["Touch scroll<br/>input handling<br/>[touch-scroll.ts]"]
  node_result_util["Result<br/>[result.ts]"]
  node_wait_util["Wait<br/>async helper<br/>[wait.ts]"]
  node_string_gen["String gen<br/>data generator<br/>[generate-string.ts]"]
  node_empty_fast["Empty check<br/>predicate helper<br/>[is-empty-fast.ts]"]
end

subgraph group_example["Example app"]
  node_app["App<br/>demo shell<br/>[App.tsx]"]
  node_main["Main<br/>app entry<br/>[main.tsx]"]
  node_generate_rows["Generate rows<br/>fixture data<br/>[generateRows.ts]"]
end

node_index -->|"exports"| node_grid
node_grid -->|"renders"| node_row
node_row -->|"contains"| node_cell
node_grid -->|"uses"| node_scrollbar
node_grid -->|"queries"| node_row_manager
node_grid -->|"handles"| node_touch_scroll
node_row_manager -->|"sorts with"| node_timsort
node_row_manager -->|"delegates to"| node_view_worker
node_row_manager -->|"filters with"| node_filter_util
node_row_manager -->|"reports"| node_result_util
node_row_manager -->|"coordinates"| node_wait_util
node_row_manager -->|"checks"| node_empty_fast
node_view_worker -->|"returns"| node_result_util
node_view_worker -->|"applies"| node_filter_util
node_view_worker -->|"orders with"| node_timsort
node_app -->|"consumes"| node_grid
node_app -->|"generates"| node_generate_rows
node_main -->|"mounts"| node_app
node_string_gen -->|"supports"| node_generate_rows

click node_index "https://github.com/gabrielpetersson/fast-grid/blob/master/index.ts"
click node_grid "https://github.com/gabrielpetersson/fast-grid/blob/master/src/grid.ts"
click node_row "https://github.com/gabrielpetersson/fast-grid/blob/master/src/row.ts"
click node_cell "https://github.com/gabrielpetersson/fast-grid/blob/master/src/cell.ts"
click node_scrollbar "https://github.com/gabrielpetersson/fast-grid/blob/master/src/scrollbar.ts"
click node_row_manager "https://github.com/gabrielpetersson/fast-grid/blob/master/src/row-manager/row-manager.ts"
click node_timsort "https://github.com/gabrielpetersson/fast-grid/blob/master/src/row-manager/timsort.ts"
click node_view_worker "https://github.com/gabrielpetersson/fast-grid/blob/master/src/row-manager/view-worker.ts"
click node_filter_util "https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/filter.ts"
click node_touch_scroll "https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/touch-scroll.ts"
click node_result_util "https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/result.ts"
click node_wait_util "https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/wait.ts"
click node_string_gen "https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/generate-string.ts"
click node_empty_fast "https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/is-empty-fast.ts"
click node_app "https://github.com/gabrielpetersson/fast-grid/blob/master/example/src/App.tsx"
click node_main "https://github.com/gabrielpetersson/fast-grid/blob/master/example/src/main.tsx"
click node_generate_rows "https://github.com/gabrielpetersson/fast-grid/blob/master/example/src/generateRows.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_grid,node_row,node_cell,node_scrollbar,node_row_manager,node_timsort,node_view_worker,node_filter_util,node_touch_scroll,node_result_util,node_wait_util,node_string_gen,node_empty_fast toneBlue
class node_app,node_main,node_generate_rows toneAmber
```

## Components

### Core library

TypeScript grid package and its runtime subsystems.

- [Entry](https://github.com/gabrielpetersson/fast-grid/blob/master/index.ts): public API · Root package entry point for consumers. · `index.ts`
- [Grid](https://github.com/gabrielpetersson/fast-grid/blob/master/src/grid.ts): viewport coordinator · Top-level composition layer for rendering and interaction. · `src/grid.ts`
- [Row](https://github.com/gabrielpetersson/fast-grid/blob/master/src/row.ts): row primitive · Reusable row-level rendering unit. · `src/row.ts`
- [Cell](https://github.com/gabrielpetersson/fast-grid/blob/master/src/cell.ts): cell primitive · Reusable cell-level rendering unit. · `src/cell.ts`
- [Scrollbar](https://github.com/gabrielpetersson/fast-grid/blob/master/src/scrollbar.ts): scroll control · Custom scrolling and position control. · `src/scrollbar.ts`
- [Row manager](https://github.com/gabrielpetersson/fast-grid/blob/master/src/row-manager/row-manager.ts): ordering engine · Owns filtering, sorting, and visible row state. · `src/row-manager/row-manager.ts`
- [TimSort](https://github.com/gabrielpetersson/fast-grid/blob/master/src/row-manager/timsort.ts): sort algorithm · Dedicated sorting implementation for row ordering. · `src/row-manager/timsort.ts`
- [View worker](https://github.com/gabrielpetersson/fast-grid/blob/master/src/row-manager/view-worker.ts): worker bridge · Off-thread computation of visible order and view state. · `src/row-manager/view-worker.ts`
- [Filter](https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/filter.ts): predicate helpers · Fast filtering helpers used by row processing. · `src/utils/filter.ts`
- [Touch scroll](https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/touch-scroll.ts): input handling · Mobile and touch-oriented scroll behavior. · `src/utils/touch-scroll.ts`
- [Result](https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/result.ts): async result · Success/failure wrapper for coordination across boundaries. · `src/utils/result.ts`
- [Wait](https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/wait.ts): async helper · Lightweight async timing or coordination helper. · `src/utils/wait.ts`
- [String gen](https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/generate-string.ts): data generator · Synthetic string generation for data and benchmarks. · `src/utils/generate-string.ts`
- [Empty check](https://github.com/gabrielpetersson/fast-grid/blob/master/src/utils/is-empty-fast.ts): predicate helper · Fast emptiness test used in hot paths. · `src/utils/is-empty-fast.ts`

### Example app

Vite + React demo and benchmark shell.

- [App](https://github.com/gabrielpetersson/fast-grid/blob/master/example/src/App.tsx): demo shell · React demo interface for the grid. · `example/src/App.tsx`
- [Main](https://github.com/gabrielpetersson/fast-grid/blob/master/example/src/main.tsx): app entry · Example app bootstrap and mounting entry. · `example/src/main.tsx`
- [Generate rows](https://github.com/gabrielpetersson/fast-grid/blob/master/example/src/generateRows.ts): fixture data · Creates synthetic datasets for the demo. · `example/src/generateRows.ts`

## Connections

- 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.
