tessl/npm-d3-hierarchy

Layout algorithms for visualizing hierarchical data.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Hierarchy Construction

Name: tessl/npm-d3-hierarchy
Author: tessl

Core functions for creating hierarchical data structures from nested objects or flat tabular data. These are the foundation for all layout algorithms in d3-hierarchy.

Capabilities

Hierarchy Function

Creates a root node from hierarchical data with optional custom children accessor.

/**
 * Constructs a root node from hierarchical data
 * @param data - The root data object
 * @param children - Optional accessor function to get children array
 * @returns Root node of the hierarchy
 */
function hierarchy(data, children);

Usage Examples:

import { hierarchy } from "d3-hierarchy";

// Basic usage with standard 'children' property
const data = {
  name: "root",
  children: [
    { name: "child1" },
    { name: "child2", children: [{ name: "grandchild" }] }
  ]
};

const root = hierarchy(data);
console.log(root.children.length); // 2

// Custom children accessor
const customData = {
  name: "root",
  items: [{ name: "child1" }, { name: "child2" }]
};

const root2 = hierarchy(customData, d => d.items);

// Working with Map data
const mapData = new Map([
  ["root", new Map([
    ["child1", null],
    ["child2", new Map([["grandchild", null]])]
  ])]
]);

const root3 = hierarchy(mapData);

Stratify Function Factory

Creates a stratify function for converting flat tabular data into hierarchical structure using id and parentId relationships.

/**
 * Creates a stratify function for tabular data conversion  
 * @returns Stratify function with configuration methods
 */
function stratify();

interface StratifyFunction {
  /** Convert flat data array to hierarchy */
  (data: any[]): Node;
  /** Get/set the id accessor function */
  id(accessor?: (d: any, i: number, data: any[]) => string): StratifyFunction | Function;
  /** Get/set the parentId accessor function */  
  parentId(accessor?: (d: any, i: number, data: any[]) => string): StratifyFunction | Function;
  /** Get/set the path accessor function for path-based hierarchies */
  path(accessor?: (d: any, i: number, data: any[]) => string): StratifyFunction | Function;
}

Usage Examples:

import { stratify } from "d3-hierarchy";

// Basic stratify with id/parentId
const flatData = [
  { id: "root", parentId: null, name: "Root" },
  { id: "child1", parentId: "root", name: "Child 1" },
  { id: "child2", parentId: "root", name: "Child 2" },
  { id: "grandchild", parentId: "child2", name: "Grandchild" }
];

const stratifyFunc = stratify()
  .id(d => d.id)
  .parentId(d => d.parentId);

const root = stratifyFunc(flatData);
console.log(root.children.length); // 2

// Path-based stratification
const pathData = [
  { path: "/", name: "Root" },
  { path: "/docs", name: "Documentation" },
  { path: "/docs/api", name: "API Reference" },
  { path: "/src", name: "Source Code" }
];

const pathStratify = stratify()
  .path(d => d.path);

const pathRoot = pathStratify(pathData);

// Custom accessor functions
const customData = [
  { uid: 1, manager: null, employee: "CEO" },
  { uid: 2, manager: 1, employee: "CTO" }, 
  { uid: 3, manager: 1, employee: "CFO" },
  { uid: 4, manager: 2, employee: "Engineer" }
];

const customStratify = stratify()
  .id(d => d.uid)
  .parentId(d => d.manager);

const orgChart = customStratify(customData);

Error Handling

Stratify validates the hierarchy structure and throws descriptive errors:

// Throws "missing: parentId" if parent reference doesn't exist
// Throws "ambiguous: id" if multiple nodes have same id  
// Throws "multiple roots" if more than one root node found
// Throws "no root" if no root node found
// Throws "cycle" if circular references detected

try {
  const root = stratifyFunc(invalidData);
} catch (error) {
  console.error("Hierarchy creation failed:", error.message);
}

Children Accessor Function

Default children accessor for hierarchy function:

/**
 * Default children accessor - returns d.children
 * @param d - Data object
 * @returns Array of children or null/undefined
 */
function defaultChildren(d) {
  return d.children;
}

Custom children accessor examples:

// For nested arrays
const arrayData = [
  "root", 
  [
    ["child1"],
    ["child2", [["grandchild"]]]
  ]
];

const root = hierarchy(arrayData, d => Array.isArray(d) ? d.slice(1) : null);

// For object with custom property names
const customData = {
  title: "root",
  subitems: [
    { title: "child1" },
    { title: "child2", subitems: [{ title: "grandchild" }] }
  ]
};

const root2 = hierarchy(customData, d => d.subitems);

Install with Tessl CLI