@tidyjs/tidy 2.5.2 → 2.6.1

package/genai-docs/api-other.md

@@ -0,0 +1,238 @@
+# Other Functions
+
+Miscellaneous tidyjs functions for completing, filling, replacing, adding rows, and math utilities.
+
+```js
+import { tidy, complete, expand, fill, replaceNully, addRows, rate, TMath } from '@tidyjs/tidy';
+```
+
+---
+
+<!-- keywords: complete, fill missing combinations, add missing rows -->
+## complete
+
+Fill in missing combinations of data. Adds rows for any combination of specified keys that does not already exist.
+
+**Signature:** `complete<T>(expandKeys: string | string[] | KeyMap<T>, replaceNullySpec?: Partial<T>)`
+**Goes inside:** `tidy(data, complete(...))`
+
+### Parameters
+- **expandKeys** `string | string[] | KeyMap<T>` -- defines which columns to expand. As a `KeyMap`, each key maps to an array of values or a sequence function (e.g., `fullSeq`).
+- **replaceNullySpec** `Partial<T>` (optional) -- replace null/undefined in newly created rows. E.g., `{ value: 0 }`.
+
+### Example
+```js
+const data = [
+  { group: 'a', year: 2020, value: 10 },
+  { group: 'a', year: 2021, value: 20 },
+  { group: 'b', year: 2020, value: 30 },
+];
+
+tidy(data, complete({ group: ['a', 'b'], year: [2020, 2021] }, { value: 0 }));
+// output:
+// [
+//   { group: 'a', year: 2020, value: 10 },
+//   { group: 'a', year: 2021, value: 20 },
+//   { group: 'b', year: 2020, value: 30 },
+//   { group: 'b', year: 2021, value: 0 },  // added, value filled with 0
+// ]
+```
+
+---
+
+<!-- keywords: expand, all combinations, cartesian product, cross join -->
+## expand
+
+Generate all combinations of the specified keys. Unlike `complete`, returns only the expanded combination rows (does not merge with original data).
+
+**Signature:** `expand<T>(expandKeys: string | string[] | KeyMap<T>)`
+**Goes inside:** `tidy(data, expand(...))`
+
+### Parameters
+- **expandKeys** `string | string[] | KeyMap<T>` -- columns to expand. As a string or array, uses distinct values from the data. As a `KeyMap`, values can be explicit arrays or sequence functions.
+
+### Example
+```js
+const data = [
+  { group: 'a', year: 2020 },
+  { group: 'b', year: 2021 },
+];
+
+tidy(data, expand(['group', 'year']));
+// output: all combinations of distinct group and year values
+// [
+//   { group: 'a', year: 2020 },
+//   { group: 'a', year: 2021 },
+//   { group: 'b', year: 2020 },
+//   { group: 'b', year: 2021 },
+// ]
+```
+
+---
+
+<!-- keywords: fill, fill down, forward fill, last observation carried forward -->
+## fill
+
+Fill null/undefined values forward (downward) using the last non-null value.
+
+**Signature:** `fill<T>(keys: string | string[])`
+**Goes inside:** `tidy(data, fill(...))`
+
+### Parameters
+- **keys** `string | string[]` -- column name(s) to fill.
+
+### Example
+```js
+const data = [
+  { name: 'Alice', value: 10 },
+  { name: undefined, value: 20 },
+  { name: undefined, value: 30 },
+  { name: 'Bob', value: 40 },
+];
+
+tidy(data, fill('name'));
+// output:
+// [
+//   { name: 'Alice', value: 10 },
+//   { name: 'Alice', value: 20 },  // filled from above
+//   { name: 'Alice', value: 30 },  // filled from above
+//   { name: 'Bob', value: 40 },
+// ]
+```
+
+---
+
+<!-- keywords: replace nully, replace null, replace undefined, default values, coalesce -->
+## replaceNully
+
+Replace null or undefined values with specified defaults.
+
+**Signature:** `replaceNully<T>(replaceSpec: Partial<T>)`
+**Goes inside:** `tidy(data, replaceNully(...))`
+
+### Parameters
+- **replaceSpec** `Partial<T>` -- object mapping column names to replacement values. Only null/undefined values are replaced.
+
+### Example
+```js
+const data = [
+  { name: 'Alice', score: null, grade: undefined },
+  { name: 'Bob', score: 85, grade: 'B' },
+];
+
+tidy(data, replaceNully({ score: 0, grade: 'N/A' }));
+// output:
+// [
+//   { name: 'Alice', score: 0, grade: 'N/A' },
+//   { name: 'Bob', score: 85, grade: 'B' },
+// ]
+```
+
+---
+
+<!-- keywords: add rows, add items, append, insert rows -->
+## addRows
+
+Append rows to the data. Alias: `addItems`.
+
+**Signature:** `addRows<T>(itemsToAdd: T | T[] | ((items: T[]) => T | T[]))`
+**Goes inside:** `tidy(data, addRows(...))`
+
+### Parameters
+- **itemsToAdd** `T | T[] | ((items: T[]) => T | T[])` -- rows to append. Can be a single item, an array, or a function that receives the current items and returns new rows.
+
+### Example
+```js
+const data = [{ name: 'Alice', value: 10 }];
+
+tidy(data, addRows([{ name: 'Bob', value: 20 }]));
+// output: [{ name: 'Alice', value: 10 }, { name: 'Bob', value: 20 }]
+
+// dynamic: add a total row
+tidy(data, addRows((items) => ({
+  name: 'Total',
+  value: items.reduce((s, d) => s + d.value, 0),
+})));
+```
+
+---
+
+<!-- keywords: rate, ratio, divide, item accessor, mutate rate -->
+## rate (item accessor)
+
+Create a per-item rate accessor for use inside `mutate()`. Computes `numerator / denominator` for each row.
+
+**Signature:** `rate<T>(numerator: keyof T | Accessor, denominator: keyof T | Accessor, options?: { predicate?, allowDivideByZero? })`
+**Goes inside:** `mutate({ col: rate('num', 'denom') })`
+
+### Parameters
+- **numerator** `keyof T | ((d, i, arr) => number)` -- column name or accessor for the numerator.
+- **denominator** `keyof T | ((d, i, arr) => number)` -- column name or accessor for the denominator.
+- **options.predicate** `(d, i, arr) => boolean` -- if provided, returns `undefined` when predicate is false.
+- **options.allowDivideByZero** `boolean` -- if `true`, allows division by zero (returns `Infinity`). Default: `false` (returns `undefined` when denominator is 0, except 0/0 which returns 0).
+
+### Example
+```js
+const data = [
+  { hits: 30, attempts: 100 },
+  { hits: 0, attempts: 0 },
+  { hits: 5, attempts: 0 },
+];
+
+tidy(data, mutate({ pct: rate('hits', 'attempts') }));
+// output:
+// [
+//   { hits: 30, attempts: 100, pct: 0.3 },
+//   { hits: 0, attempts: 0, pct: 0 },       // 0/0 = 0
+//   { hits: 5, attempts: 0, pct: undefined }, // div by zero = undefined
+// ]
+```
+
+**Do not confuse with `TMath.rate`** (see below), which is a plain math function, not an item accessor.
+
+---
+
+<!-- keywords: TMath, math rate, math add, math subtract, null safe math -->
+## TMath
+
+Plain math utility functions with null/undefined safety. These are standalone functions, not tidy pipeline operators.
+
+```js
+import { TMath } from '@tidyjs/tidy';
+```
+
+### TMath.rate(numerator, denominator, allowDivideByZero?)
+
+Compute `numerator / denominator` with null safety.
+
+- Returns `undefined` if either argument is null/undefined.
+- Returns `0` if both numerator and denominator are 0.
+- Returns `undefined` if denominator is 0 (unless `allowDivideByZero` is `true`).
+
+```js
+TMath.rate(30, 100);       // 0.3
+TMath.rate(0, 0);          // 0
+TMath.rate(5, 0);          // undefined
+TMath.rate(null, 100);     // undefined
+TMath.rate(5, 0, true);    // Infinity
+```
+
+### TMath.add(a, b, nullyZero?)
+
+Null-safe addition. Returns `undefined` if either value is null/undefined, unless `nullyZero` is `true` (treats null/undefined as 0).
+
+```js
+TMath.add(1, 2);           // 3
+TMath.add(1, null);        // undefined
+TMath.add(1, null, true);  // 1
+```
+
+### TMath.subtract(a, b, nullyZero?)
+
+Null-safe subtraction. Returns `undefined` if either value is null/undefined, unless `nullyZero` is `true`.
+
+```js
+TMath.subtract(5, 3);           // 2
+TMath.subtract(5, null);        // undefined
+TMath.subtract(5, null, true);  // 5
+```

package/genai-docs/api-pivot.md

@@ -0,0 +1,112 @@
+# Pivot (Reshape)
+
+Reshape data between long and wide formats.
+
+```js
+import { tidy, pivotWider, pivotLonger } from '@tidyjs/tidy';
+```
+
+---
+
+<!-- keywords: pivot wider, spread, long to wide, reshape, widen -->
+## pivotWider
+
+Reshape from long format to wide format by spreading values into new columns.
+
+**Signature:** `pivotWider<T>(options: { namesFrom, valuesFrom, valuesFill?, valuesFillMap?, namesSep? })`
+**Goes inside:** `tidy(data, pivotWider(...))`
+
+### Parameters
+- **namesFrom** `keyof T | (keyof T)[]` -- column(s) whose values become new column names.
+- **valuesFrom** `keyof T | (keyof T)[]` -- column(s) whose values fill the new columns.
+- **valuesFill** `any` -- value to use when a combination has no data. Default: `undefined`.
+- **valuesFillMap** `Record<string, any>` -- per-valuesFrom fill values (e.g., `{ count: 0, total: 0 }`).
+- **namesSep** `string` -- separator when combining multiple namesFrom or valuesFrom keys. Default: `'_'`.
+
+### Example
+```js
+const data = [
+  { name: 'Alice', subject: 'math', score: 90 },
+  { name: 'Alice', subject: 'reading', score: 85 },
+  { name: 'Bob', subject: 'math', score: 70 },
+  { name: 'Bob', subject: 'reading', score: 95 },
+];
+
+tidy(data, pivotWider({
+  namesFrom: 'subject',
+  valuesFrom: 'score',
+  valuesFill: 0,
+}));
+// output:
+// [
+//   { name: 'Alice', math: 90, reading: 85 },
+//   { name: 'Bob', math: 70, reading: 95 },
+// ]
+```
+
+### Multiple valuesFrom
+```js
+tidy(data, pivotWider({
+  namesFrom: 'subject',
+  valuesFrom: ['score', 'grade'],
+  namesSep: '_',
+}));
+// columns become: name, score_math, score_reading, grade_math, grade_reading
+```
+
+---
+
+<!-- keywords: pivot longer, melt, gather, wide to long, unpivot, reshape -->
+## pivotLonger
+
+Reshape from wide format to long format by collapsing columns into rows.
+
+**Signature:** `pivotLonger<T>(options: { cols?, namesTo, valuesTo, namesSep? })`
+**Goes inside:** `tidy(data, pivotLonger(...))`
+
+### Parameters
+- **cols** `(keyof T)[] | SelectorFn` -- columns to pivot into longer format. Accepts an array of column names or selector functions like `startsWith()`, `contains()`, etc.
+- **namesTo** `string | string[]` -- name for the new column(s) that will hold the former column names.
+- **valuesTo** `string | string[]` -- name for the new column(s) that will hold the values.
+- **namesSep** `string` -- separator to split column names when `namesTo` is an array. Default: `'_'`.
+
+### Example
+```js
+const data = [
+  { name: 'Alice', math: 90, reading: 85 },
+  { name: 'Bob', math: 70, reading: 95 },
+];
+
+tidy(data, pivotLonger({
+  cols: ['math', 'reading'],
+  namesTo: 'subject',
+  valuesTo: 'score',
+}));
+// output:
+// [
+//   { name: 'Alice', subject: 'math', score: 90 },
+//   { name: 'Alice', subject: 'reading', score: 85 },
+//   { name: 'Bob', subject: 'math', score: 70 },
+//   { name: 'Bob', subject: 'reading', score: 95 },
+// ]
+```
+
+### Using selectors for cols
+```js
+import { startsWith } from '@tidyjs/tidy';
+
+const data = [
+  { id: 1, rev_q1: 100, rev_q2: 200, cost_q1: 50 },
+];
+
+tidy(data, pivotLonger({
+  cols: [startsWith('rev_')],
+  namesTo: 'quarter',
+  valuesTo: 'revenue',
+}));
+// output:
+// [
+//   { id: 1, cost_q1: 50, quarter: 'rev_q1', revenue: 100 },
+//   { id: 1, cost_q1: 50, quarter: 'rev_q2', revenue: 200 },
+// ]
+```

package/genai-docs/api-selectors.md

@@ -0,0 +1,159 @@
+# Selectors
+
+Functions that dynamically select column names based on patterns. Selectors return `(items: T[]) => string[]`.
+
+Use selectors inside `select()`, `summarizeAt()`, `totalAt()`, and `pivotLonger({ cols: ... })`.
+
+```js
+import { tidy, select,
+  everything, startsWith, endsWith, contains, matches, numRange, negate
+} from '@tidyjs/tidy';
+```
+
+---
+
+<!-- keywords: everything, all columns, select all -->
+## everything
+
+Select all columns.
+
+**Signature:** `everything<T>()`
+**Returns:** `(items: T[]) => string[]`
+
+### Example
+```js
+tidy(data, select([everything(), '-secret']));
+// selects all columns except 'secret'
+```
+
+---
+
+<!-- keywords: starts with, prefix, column prefix -->
+## startsWith
+
+Select columns whose names start with a prefix.
+
+**Signature:** `startsWith<T>(prefix: string, ignoreCase?: boolean)`
+**Returns:** `(items: T[]) => string[]`
+
+### Parameters
+- **prefix** `string` -- the prefix to match.
+- **ignoreCase** `boolean` -- case-insensitive matching. Default: `true`.
+
+### Example
+```js
+// data has columns: rev_q1, rev_q2, cost_q1
+tidy(data, select([startsWith('rev_')]));
+// keeps: rev_q1, rev_q2
+```
+
+---
+
+<!-- keywords: ends with, suffix, column suffix -->
+## endsWith
+
+Select columns whose names end with a suffix.
+
+**Signature:** `endsWith<T>(suffix: string, ignoreCase?: boolean)`
+**Returns:** `(items: T[]) => string[]`
+
+### Parameters
+- **suffix** `string` -- the suffix to match.
+- **ignoreCase** `boolean` -- case-insensitive matching. Default: `true`.
+
+### Example
+```js
+// data has columns: name_en, name_fr, age
+tidy(data, select([endsWith('_en')]));
+// keeps: name_en
+```
+
+---
+
+<!-- keywords: contains, substring, column search -->
+## contains
+
+Select columns whose names contain a substring.
+
+**Signature:** `contains<T>(substring: string, ignoreCase?: boolean)`
+**Returns:** `(items: T[]) => string[]`
+
+### Parameters
+- **substring** `string` -- the substring to search for.
+- **ignoreCase** `boolean` -- case-insensitive matching. Default: `true`.
+
+### Example
+```js
+// data has columns: total_revenue, net_revenue, cost
+tidy(data, select([contains('revenue')]));
+// keeps: total_revenue, net_revenue
+```
+
+---
+
+<!-- keywords: matches, regex, pattern, column regex -->
+## matches
+
+Select columns whose names match a regular expression.
+
+**Signature:** `matches<T>(regex: RegExp)`
+**Returns:** `(items: T[]) => string[]`
+
+### Parameters
+- **regex** `RegExp` -- the regular expression to test against.
+
+### Example
+```js
+// data has columns: q1_sales, q2_sales, q1_cost, notes
+tidy(data, select([matches(/^q\d+_sales$/)]));
+// keeps: q1_sales, q2_sales
+```
+
+---
+
+<!-- keywords: num range, numbered columns, prefix with numbers -->
+## numRange
+
+Select columns matching a prefix followed by numbers in a range.
+
+**Signature:** `numRange<T>(prefix: string, range: [number, number], width?: number)`
+**Returns:** `(items: T[]) => string[]`
+
+### Parameters
+- **prefix** `string` -- the column name prefix.
+- **range** `[number, number]` -- inclusive `[start, end]` range of numbers.
+- **width** `number` (optional) -- zero-pad numbers to this width. E.g., `width=3` turns `1` into `001`.
+
+### Example
+```js
+// data has columns: wk1, wk2, wk3, ..., wk52, name
+tidy(data, select([numRange('wk', [1, 4])]));
+// keeps: wk1, wk2, wk3, wk4
+
+// with zero-padded columns: wk001, wk002, ...
+tidy(data, select([numRange('wk', [1, 4], 3)]));
+// keeps: wk001, wk002, wk003, wk004
+```
+
+---
+
+<!-- keywords: negate, invert, exclude, drop columns -->
+## negate
+
+Invert a selector to exclude the matched columns. Prefixes matched keys with `-`.
+
+**Signature:** `negate<T>(selectors: Selector | Selector[])`
+**Returns:** `(items: T[]) => string[]`
+
+### Parameters
+- **selectors** -- one or more selectors (or key names) to invert.
+
+### Example
+```js
+// data has columns: id, rev_q1, rev_q2, cost_q1
+tidy(data, select([negate(startsWith('rev_'))]));
+// drops rev_q1, rev_q2 -- keeps id, cost_q1
+
+// equivalent to:
+tidy(data, select(['-rev_q1', '-rev_q2']));
+```

package/genai-docs/api-sequences.md

@@ -0,0 +1,127 @@
+# Sequences
+
+Generate full sequences of values. Typically used inside `complete()` or `expand()` to define the full range of a variable.
+
+```js
+import { tidy, complete, expand,
+  fullSeq, fullSeqDate, fullSeqDateISOString,
+  vectorSeq, vectorSeqDate
+} from '@tidyjs/tidy';
+```
+
+---
+
+<!-- keywords: full sequence, numeric sequence, fill range, step -->
+## fullSeq
+
+Generate a full numeric sequence from min to max of a column's values.
+
+**Signature:** `fullSeq<T>(key: keyof T | ((d: T) => number), period?: number)`
+**Returns:** `(items: T[]) => number[]`
+
+### Parameters
+- **key** `keyof T | ((d: T) => number)` -- column name or accessor to read numeric values from.
+- **period** `number` -- step size between values. Default: `1`.
+
+### Example
+```js
+const data = [
+  { year: 2020, value: 10 },
+  { year: 2023, value: 30 },
+];
+
+tidy(data, complete({ year: fullSeq('year') }));
+// fills in missing years: 2020, 2021, 2022, 2023
+// rows for 2021 and 2022 are added with value: undefined
+```
+
+---
+
+<!-- keywords: full date sequence, date range, granularity, day week month -->
+## fullSeqDate
+
+Generate a full date sequence from min to max of a column's Date values.
+
+**Signature:** `fullSeqDate<T>(key: keyof T | ((d: T) => Date), granularity?: Granularity, period?: number)`
+**Returns:** `(items: T[]) => Date[]`
+
+### Parameters
+- **key** `keyof T | ((d: T) => Date)` -- column name or accessor to read Date values from.
+- **granularity** `Granularity` -- step unit. One of: `'second'` / `'s'`, `'minute'` / `'min'`, `'day'` / `'d'`, `'week'` / `'w'`, `'month'` / `'m'`, `'year'` / `'y'` (and plural forms). Default: `'day'`.
+- **period** `number` -- number of granularity units per step. Default: `1`.
+
+### Example
+```js
+const data = [
+  { date: new Date('2023-01-01'), value: 1 },
+  { date: new Date('2023-01-04'), value: 4 },
+];
+
+tidy(data, complete({ date: fullSeqDate('date', 'day') }));
+// fills in Jan 1, 2, 3, 4 -- adds rows for Jan 2 and Jan 3
+```
+
+---
+
+<!-- keywords: full date sequence ISO, date string, ISO 8601 -->
+## fullSeqDateISOString
+
+Same as `fullSeqDate` but returns ISO 8601 strings instead of Date objects.
+
+**Signature:** `fullSeqDateISOString<T>(key: keyof T | ((d: T) => string), granularity?: Granularity, period?: number)`
+**Returns:** `(items: T[]) => string[]`
+
+### Parameters
+Same as `fullSeqDate`. The key accessor should return a string parseable by `new Date(...)`.
+
+### Example
+```js
+const data = [
+  { date: '2023-01-01', value: 1 },
+  { date: '2023-01-03', value: 3 },
+];
+
+tidy(data, complete({ date: fullSeqDateISOString('date', 'day') }));
+// fills dates as ISO strings: '2023-01-01T00:00:00.000Z', '2023-01-02T00:00:00.000Z', ...
+```
+
+---
+
+<!-- keywords: vector sequence, explicit values, numeric -->
+## vectorSeq
+
+Generate a numeric sequence from an explicit array of values (min to max with a step).
+
+**Signature:** `vectorSeq(values: number[], period?: number): number[]`
+**Returns:** `number[]` (not a factory function -- returns the sequence directly)
+
+### Parameters
+- **values** `number[]` -- array of numbers. The sequence spans from `min(values)` to `max(values)`.
+- **period** `number` -- step size. Default: `1`.
+
+### Example
+```js
+vectorSeq([2, 8], 2);
+// output: [2, 4, 6, 8]
+```
+
+---
+
+<!-- keywords: vector date sequence, explicit date values -->
+## vectorSeqDate
+
+Generate a date sequence from an explicit array of Date values (min to max).
+
+**Signature:** `vectorSeqDate(values: Date[], granularity?: Granularity, period?: number): Date[]`
+**Returns:** `Date[]` (not a factory function -- returns the sequence directly)
+
+### Parameters
+- **values** `Date[]` -- array of Dates. The sequence spans from earliest to latest.
+- **granularity** `Granularity` -- step unit. Default: `'day'`.
+- **period** `number` -- number of granularity units per step. Default: `1`.
+
+### Example
+```js
+vectorSeqDate([new Date('2023-01-01'), new Date('2023-01-03')], 'day');
+// output: [Date(Jan 1), Date(Jan 2), Date(Jan 3)]
+```