Skip to content

README.md

Latest commit

 

History

History
106 lines (76 loc) · 3.83 KB

README.md

File metadata and controls

106 lines (76 loc) · 3.83 KB
Raw

JoinScope

See what your join will actually do.
A visual, local-first CSV join explorer for matches, duplicate keys, orphan rows, and row multiplication.

Live demo · Run locally · Privacy

JoinScope desktop workspace

Why JoinScope exists

A join can look harmless in a query and still multiply rows, hide records, or silently discard unmatched data. JoinScope makes those consequences visible before you run the operation in SQL, Python, R, or a BI tool.

Load two CSV files, select one key on each side, and switch between INNER, LEFT, RIGHT, and FULL OUTER. The relationship map and diagnostics update immediately.

Features

  • Four relational joins: inner, left, right, and full outer.
  • Correct duplicate behavior: repeated keys expand into the Cartesian combinations a real join produces.
  • Cardinality diagnosis: identifies 1:1, 1:N, N:1, and N:N relationships.
  • Orphan detection: counts rows that have no partner on either side.
  • Visual row map: traces sampled rows while full-data metrics remain exact.
  • CSV export: downloads the complete result with left. and right. column prefixes.
  • Local-first privacy: files are parsed and joined inside the browser tab.
  • Zero runtime dependencies: plain JavaScript modules, semantic HTML, CSS, and SVG.

Join behavior

Mode Rows kept
INNER Only rows with a matching key on both sides
LEFT Every left row, plus matching right rows
RIGHT Every right row, plus matching left rows
FULL OUTER Matching rows and unmatched rows from both sides

Blank or whitespace-only keys are treated as missing and never match one another.

Use it

  1. Open the live site. Sample files are already loaded.
  2. Drop a CSV into Table A and Table B.
  3. Select the join-key column for each table.
  4. Choose a join type.
  5. Inspect the relationship map, row counts, duplicate warnings, and result preview.
  6. Download the complete joined CSV.

The interface accepts CSV files up to 25 MB. The visual map samples a bounded set of rows for readability; diagnostics and export use the complete in-memory dataset.

Privacy

JoinScope has no backend, account system, upload endpoint, analytics pipeline, or database. CSV contents stay in the current browser tab and disappear when the tab is closed or refreshed.

Run locally

No package installation or build step is required.

git clone https://github.com/DarkMatterNet/joinscope.git
cd joinscope
python3 -m http.server 4173

Open http://localhost:4173.

Tests

Node.js 22 or newer is recommended.

npm test

The test suite covers join semantics, duplicate expansion, blank keys, CSV quoting, export escaping, visualization modeling, and the initial UI workspace.

Project structure

.
├── index.html
├── styles.css
├── src/
│   ├── app.js                 # Browser state and interactions
│   ├── core/
│   │   ├── csv.js             # CSV parser and serializer
│   │   ├── join.js            # Join engine and diagnostics
│   │   ├── source.js          # CSV source creation
│   │   ├── visualization.js   # Bounded graph model
│   │   └── workspace.js       # Derived UI model
│   ├── data/demo.js
│   └── ui/templates.js
└── tests/

Design goals

JoinScope is intentionally closer to an interactive explainer than a generic data utility. The interface exposes row-level consequences directly, keeps the first experience useful with sample data, and avoids hiding important behavior behind documentation.

License

MIT © 2026 DarkMatterNet