Before writing any tidyjs code, you MUST read the relevant docs. tidyjs has a distinctive pipeline pattern and function taxonomy that differs from pandas, SQL, and lodash. Pre-training knowledge is often wrong for this library — always prefer the docs.
Locating the docs
The genai-docs should be found at one of these locations. Check in order:
- npm package:
node_modules/@tidyjs/tidy/genai-docs/
If found, use that path as DOCS_ROOT below and proceed to How to navigate.
If docs are not found locally
Fetch them from the public docs site. The AI-optimized docs are available at:
https://pbeshai.github.io/tidy/genai-docs/
The site also has llms.txt at https://pbeshai.github.io/tidy/llms.txt with a full index.
Key files to fetch:
https://pbeshai.github.io/tidy/genai-docs/mental-model.md — start here
https://pbeshai.github.io/tidy/genai-docs/quick-reference.md — task-to-function lookup
https://pbeshai.github.io/tidy/genai-docs/gotchas.md — common mistakes
- Then fetch specific
api-*.md files as needed
How to navigate
- Start: Read
DOCS_ROOT/mental-model.md for the pipeline pattern, accessor conventions, and function taxonomy. This is essential before writing any code.
- Quick lookup: Read
DOCS_ROOT/quick-reference.md to find which function to use for a given task.
- API details: Read the relevant
api-*.md file for function signatures, parameters, and examples:
- Core verbs (tidy, filter, mutate, arrange, select, etc.):
api-core.md
- Grouping:
api-grouping.md
- Summarize + aggregation functions:
api-summarize.md
- Vector/cross-item operations:
api-vector.md
- Joins:
api-joins.md
- Pivoting:
api-pivot.md
- Slicing:
api-slice.md
- Column selectors:
api-selectors.md
- Sequences:
api-sequences.md
- Other (complete, expand, fill, TMath, etc.):
api-other.md
- Recipes: Read
DOCS_ROOT/patterns.md for multi-verb composition patterns.
- Avoid mistakes: Read
DOCS_ROOT/gotchas.md before finalizing code.
Key principles
- Always read before writing: Read the relevant api doc for every function you use.
- Pipeline pattern: All transformations flow through
tidy(data, verb1(), verb2()). Verbs are curried functions.
- Accessor functions, not strings: Use
(d) => d.column for field access, not string column names (except in summary functions like sum('key') and sort helpers like desc('key')).
- mutate vs mutateWithSummary:
mutate is per-item (item, index, array) => value. mutateWithSummary receives the full array (items[]) => value[] | value. Using summary/vector functions inside mutate() is a silent bug. Always check gotchas.md if unsure.
- groupBy export modes: Without an export option,
groupBy returns a flat array. With groupBy.object(), .entries(), .map(), etc., the output shape changes. Export modes must be the last pipeline step.
- Check the function taxonomy: Summary functions go inside
summarize(). Vector functions go inside mutateWithSummary(). Item functions go inside mutate(). Selectors go inside select(). Getting this wrong produces incorrect results.
1---2name: using-tidyjs3description: Write correct, idiomatic tidyjs code. Activates when the user works with @tidyjs/tidy imports, mentions tidyjs, or asks about JavaScript data wrangling in a project that uses tidyjs.4metadata:5 source: https://skillmd.com/skills/pbeshai/using-tidyjs6---78**Before writing any tidyjs code, you MUST read the relevant docs.** tidyjs has a distinctive pipeline pattern and function taxonomy that differs from pandas, SQL, and lodash. Pre-training knowledge is often wrong for this library — always prefer the docs.910## Locating the docs1112The genai-docs should be found at one of these locations. Check in order:13141. **npm package**: `node_modules/@tidyjs/tidy/genai-docs/`1516If found, use that path as `DOCS_ROOT` below and proceed to **How to navigate**.1718### If docs are not found locally1920Fetch them from the public docs site. The AI-optimized docs are available at:2122`https://pbeshai.github.io/tidy/genai-docs/`2324The site also has `llms.txt` at `https://pbeshai.github.io/tidy/llms.txt` with a full index.2526Key files to fetch:27- `https://pbeshai.github.io/tidy/genai-docs/mental-model.md` — start here28- `https://pbeshai.github.io/tidy/genai-docs/quick-reference.md` — task-to-function lookup29- `https://pbeshai.github.io/tidy/genai-docs/gotchas.md` — common mistakes30- Then fetch specific `api-*.md` files as needed3132## How to navigate33341. **Start**: Read `DOCS_ROOT/mental-model.md` for the pipeline pattern, accessor conventions, and function taxonomy. This is essential before writing any code.352. **Quick lookup**: Read `DOCS_ROOT/quick-reference.md` to find which function to use for a given task.363. **API details**: Read the relevant `api-*.md` file for function signatures, parameters, and examples:37 - Core verbs (tidy, filter, mutate, arrange, select, etc.): `api-core.md`38 - Grouping: `api-grouping.md`39 - Summarize + aggregation functions: `api-summarize.md`40 - Vector/cross-item operations: `api-vector.md`41 - Joins: `api-joins.md`42 - Pivoting: `api-pivot.md`43 - Slicing: `api-slice.md`44 - Column selectors: `api-selectors.md`45 - Sequences: `api-sequences.md`46 - Other (complete, expand, fill, TMath, etc.): `api-other.md`474. **Recipes**: Read `DOCS_ROOT/patterns.md` for multi-verb composition patterns.485. **Avoid mistakes**: Read `DOCS_ROOT/gotchas.md` before finalizing code.4950## Key principles5152- **Always read before writing**: Read the relevant api doc for every function you use.53- **Pipeline pattern**: All transformations flow through `tidy(data, verb1(), verb2())`. Verbs are curried functions.54- **Accessor functions, not strings**: Use `(d) => d.column` for field access, not string column names (except in summary functions like `sum('key')` and sort helpers like `desc('key')`).55- **mutate vs mutateWithSummary**: `mutate` is per-item `(item, index, array) => value`. `mutateWithSummary` receives the full array `(items[]) => value[] | value`. Using summary/vector functions inside `mutate()` is a silent bug. Always check `gotchas.md` if unsure.56- **groupBy export modes**: Without an export option, `groupBy` returns a flat array. With `groupBy.object()`, `.entries()`, `.map()`, etc., the output shape changes. Export modes must be the last pipeline step.57- **Check the function taxonomy**: Summary functions go inside `summarize()`. Vector functions go inside `mutateWithSummary()`. Item functions go inside `mutate()`. Selectors go inside `select()`. Getting this wrong produces incorrect results.