tree-table-data-shaper

A small utility to transform flat datasets into a tree structure grouped for table/tree-table rendering.

Key features

• Lightweight, zero-dependency TypeScript helper
• Group flat arrays into nested TreeNode structures by one or more fields
• Configurable children key name

Installation

Install from npm:

npm install tree-table-data-shaper

Or with yarn:

yarn add tree-table-data-shaper

Usage

Import and call createTree with your data and a TreeConfig:

import { createTree } from "tree-table-data-shaper";

const data = [
  { country: "USA", state: "California", city: "Los Angeles" },
  { country: "USA", state: "California", city: "San Francisco" },
  { country: "USA", state: "New York", city: "New York City" },
  { country: "Canada", state: "Ontario", city: "Toronto" },
];

// Group by country then state
const tree = createTree(data, { groupBy: ["country", "state"] });

/*
Resulting structure:
[
  {
    key: "USA",
    children: [
      { key: "California", rows: [  *two rows*  ] },
      { key: "New York", rows: [  *one row*  ] }
    ]
  },
  {
    key: "Canada",
    children: [ { key: "Ontario", rows: [ * one row * ] } ]
  }
]
*/

API

• createTree<T>(data: T[], config: TreeConfig): TreeNode[]

TreeConfig (from src/types.ts):

• groupBy: string[] — Ordered list of object fields to group by (required).
• childrenKey?: string — Optional key name to use for child nodes (defaults to "children").

TreeNode shape:

• key: string — Group key value.
• children?: TreeNode[] — Child groups when grouping continues deeper.
• rows?: any[] — Original input rows when the last grouping level is reached.

Examples

• Group by a single field:

createTree(data, { groupBy: ["country"] });

• Use a custom children key:

createTree(data, { groupBy: ["country", "state"], childrenKey: "nodes" });

Adapters

createTree produces a small tree of TreeNode objects with key, children (or your childrenKey) and rows at the deepest level. Different UI libraries expect slightly different node shapes — use an adapter to convert the output into the shape your component needs.

This package includes a flexible generic adapter at src/adapters/genericAdapter.ts (exported as adaptTree) plus small presets for common libraries.

Usage examples

• PrimeReact TreeTable (each displayed row should be in node.data):

import {
  adaptTree,
  primeAdapter,
} from "tree-table-data-shaper/adapters/genericAdapter";

const tree = createTree(data, { groupBy: ["country", "state"] });
const primeNodes = primeAdapter(tree);
// `primeNodes` now contains nodes where group children are under `children` and row objects are in `data`.

• Generic adapter — control how leaf rows are represented (as child nodes or attached to group node):

import { adaptTree } from "tree-table-data-shaper/adapters/genericAdapter";

// Expand leaf rows into child nodes with `data`
const expanded = adaptTree(tree, { expandLeafRows: true });

// Keep leaf rows attached to group node under `data.rows`
const grouped = adaptTree(tree, {
  expandLeafRows: false,
  groupRowsKey: "items",
});

Adapters let you target other UI libraries by choosing targetChildrenKey, targetDataKey, and wrapGroupData for custom shapes.

Testing

This repo includes a simple vitest test at tests/createTree.test.ts that demonstrates expected behavior.

Run tests:

npm install
npm run test

Or with yarn:

yarn
yarn test

Contributing

Contributions welcome — open an issue or submit a PR. Keep changes small and add tests for new behaviors.

License

MIT