Import CSV and TSV tables

The optional @graphora/adapter-csv package turns delimited text into validated Graphora input. Use explicit mappings to connect your business columns to node IDs, labels and edge endpoints.

Open the CSV import example.

import { parseCsvGraph } from '@graphora/adapter-csv'

const result = parseCsvGraph({
  nodes: {
    text: 'service,name\n001,API\n002,Worker',
    columns: { id: 'service', label: 'name' }
  },
  edges: {
    text: 'from,to\n001,002',
    columns: { source: 'from', target: 'to' }
  }
})

if (result.ok) {
  engine.loadGraph(result.graph)
  await engine.runLayout({ fitToView: { padding: 56 } })
} else {
  // Present issues with textContent, preserving their table/line/column context.
  console.log(result.issues, result.issuesTruncated)
}

Only call loadGraph after success. A parse or validation failure contains no partial graph, so your existing graph can remain untouched. Layout runs after publication; a later layout failure is a separate display error.

Preview and map columns

Call parseCsvTable(text) to inspect table.columns and frozen table.rows. Each row has values and a one-based physical starting line. A quoted cell may span several lines, so diagnostic lines can differ from spreadsheet row counts. Node id and edge source/target mappings are required; label and edge-ID mappings are optional. Omit the edge table for node-only input.

Column names are exact, including case and spaces. IDs remain strings: 001 and 1 differ. All input cells remain in each item's data; no numbers, dates or booleans are inferred. Blank optional edge IDs use normal core-generated IDs.

Delimiters and limits

Pass { delimiter: '\t' } for TSV or { delimiter: ';' } for semicolon exports. Quoted separators, quoted newlines and doubled quotes are supported. Headers must be unique and nonblank, every data row must match the header width, and quotes must close cleanly. Physically empty lines are skipped.

Default limits apply to each table: 10,000,000 UTF-16 code units, 100,000 data rows, 256 columns and 100 returned issues. Set maxCharacters, maxRows, maxColumns and maxIssues for your application. All are safe integers; maxRows may be zero, while the other limits must be positive. issuesTruncated means additional known diagnostics were omitted. Limits bound accepted input; parsing is synchronous, not a streaming or worker API.

Native XLSX workbooks are outside this adapter. Export spreadsheet sheets as CSV or TSV first. Fetching files, data coercion and incremental reconciliation belong to your application or their own adapters.

Generated adapter API.