Skip to content

Data Mapping

Transform any JSON structure into graph data using a mapping config. No manual data transformation needed.

Basic Usage

TypeScript 
import { Graph } from '@topokit/core';

const apiResponse = {
  users: [
    { userId: 1, fullName: 'Alice Chen', role: 'engineer' },
    { userId: 2, fullName: 'Bob Smith', role: 'designer' },
  ],
  connections: [
    { from: 1, to: 2, type: 'collaborates' },
  ],
};

const graph = Graph.fromData(apiResponse, {
  nodes: {
    path: 'users',
    id: 'userId',
    label: 'fullName',
    group: 'role',
  },
  edges: {
    path: 'connections',
    source: 'from',
    target: 'to',
    label: 'type',
  },
});

Node Mapping

PropertyTypeDescription
pathstringDot-path to node array (e.g., 'data.users').
idstring | (item) => stringNode ID field or extractor.
labelstring | (item) => stringDisplay label field or extractor.
groupstring | (item) => stringGrouping field (for autoStyle).
sizestring | (item) => numberNode radius field or extractor.
data(item) => RecordCustom data payload (defaults to whole item).
style(item) => Partial<NodeStyle>Per-node style overrides.

Edge Mapping

PropertyTypeDescription
pathstringDot-path to edge array.
idstring | (item) => stringEdge ID (auto-generated if omitted).
sourcestring | (item) => stringSource node ID field.
targetstring | (item) => stringTarget node ID field.
labelstring | (item) => stringEdge label field.
style(item) => Partial<EdgeStyle>Per-edge style overrides.

Dot-Path Strings

Field resolvers accept dot-paths for nested properties: 'user.profile.name' accesses item.user.profile.name.

TypeScript 
const graph = Graph.fromData(data, {
  nodes: {
    path: 'response.data.entities',
    id: 'meta.uuid',
    label: 'attributes.displayName',
    group: 'attributes.category',
  },
  edges: {
    path: 'response.data.relationships',
    source: 'meta.sourceId',
    target: 'meta.targetId',
  },
});

Auto Styling

Enable autoStyle: true to assign distinct fill colors per group automatically.

TypeScript 
const graph = Graph.fromData(data, {
  nodes: { path: 'nodes', id: 'id', label: 'name', group: 'type' },
  edges: { path: 'links', source: 'source', target: 'target' },
  autoStyle: true,
  autoEdgeStyle: true, // color edges by label value
});

Function Resolvers

Use functions for complex transformations.

TypeScript 
const graph = Graph.fromData(rawData, {
  nodes: {
    path: 'items',
    id: (item) => `node-${item.pk}`,
    label: (item) => `${item.firstName} ${item.lastName}`,
    group: (item) => item.score > 80 ? 'high' : 'low',
    size: (item) => Math.max(15, Math.min(50, item.importance * 5)),
    style: (item) => ({
      shape: item.type === 'org' ? 'rect' : 'circle',
      icon: item.emoji,
    }),
  },
  edges: {
    path: 'relationships',
    source: (item) => `node-${item.subject}`,
    target: (item) => `node-${item.object}`,
    label: 'predicate',
    style: (item) => ({
      dashed: item.confidence < 0.5,
      width: item.weight * 2,
    }),
  },
  autoStyle: true,
});

Using with create()

TypeScript 
import { Graph } from '@topokit/core';
import { create } from '@topokit/renderer-canvas';

const graph = Graph.fromData(apiResponse, mapping);

const app = create(container, {
  graph,           // pass the pre-built graph
  layout: 'force',
  theme: 'dark',
});

Next Steps