CSV is the one format every AI already speaks. When an LLM needs structured data, it doesn't reach for Protocol Buffers. It writes a comma-separated table. When a tool returns rows to an agent, it's CSV, or something that wishes it were.
And yet most CSV libraries give you a pile of string arrays and wave goodbye. Here's your data, good luck.
@portel/csv is different. It's a stateful engine that actually understands what's inside the cells. Formulas evaluate. Columns know they hold currency. Queries work without loading pandas. You get a spreadsheet brain in a 30KB package, with zero dependencies and no I/O.
:---,:---#:,:---$:
Product,Quantity,Price
Widget,42,9.99
Gadget,17,24.50
That first row? It's a format row. Any CSV reader that doesn't understand it just sees dashes. But tools that do understand it know that Quantity is a number (right-aligned) and Price is currency. The schema lives inside the file. No sidecar JSON. No separate config. Just CSV that knows what it is.
If you're building agents, MCP servers, or tool-calling pipelines, this is your CSV layer.
The problem: An LLM asks your tool for sales data. You read a CSV, return string arrays, and the model has to guess that column 3 is currency. It formats 1234.5 as plain text. The user sees a wall of numbers with no structure. You end up writing formatting hints into system prompts.
With @portel/csv:
import{CsvEngine}from'@portel/csv';constengine=CsvEngine.fromCSV(csvText);constsnap=engine.snapshot('Sales data for Q1');// snap.data → evaluated values (formulas resolved)// snap.columnMeta → [{type:'text'}, {type:'number'}, {type:'currency'}]// snap.charts → any visual formulas, pre-resolved// snap.table → ASCII markdown table, ready to returnYour tool returns structured data and the metadata to render it. The client knows column 3 is currency and can format 1234.5 as $1,234.50 in whatever locale it wants. The AI doesn't have to guess. Neither does the UI.
Agents that mutate data get synchronous operations. No async, no file I/O, no "await the save." Just change the data and serialize when you're done.
engine.add({Product: 'Thingamajig',Quantity: '100',Price: '4.99'});engine.sort('Price','desc');engine.set('D1','=SUM(C1:C3)');constcsv=engine.toCSV();// ready to write, with formulas preservedSQL without the database. Need to answer "which products cost more than $10"? Your agent can query in plain SQL:
constresult=engine.sql('SELECT Product, Price FROM data WHERE Price > 10');// result.result → [{ Product: 'Gadget', Price: 24.50 }]// result.columnMeta → knows Price is currencyNo database. No connection string. Just a CSV file and a question. (SQL needs alasql as a peer dep. Everything else works with zero dependencies.)
npm install @portel/csvFor SQL queries:
npm install @portel/csv alasqlimport{CsvEngine}from'@portel/csv';constengine=CsvEngine.fromCSV(`Name,Age,ScoreAlice,30,95Bob,25,87Charlie,35,72`);engine.getHeaders();// ['Name', 'Age', 'Score']engine.rowCount;// 3engine.evaluate(0,1);// '30'engine.toTable();// ASCII markdown tableengine.toObjects();// [{ Name: 'Alice', Age: 30, Score: 95 }, ...]toObjects() auto-coerces numbers. Age comes back as 30, not "30". If you've set column metadata (or the CSV has a format row), currency columns strip $ and % before converting. The type information travels with the data.
Every mutation is synchronous. No promises, no callbacks, no waiting for disk. The engine is pure in-memory state. You persist it when and how you want.
engine.set('D1','=SUM(B1:B3)');// formulas just workengine.add({Name: 'Diana',Age: '28',Score: '91'});// add by column nameengine.push([['Eve','22','88'],['Frank','40','76']]);// batch appendengine.update(2,{Score: '90'});// update row 2engine.remove(3);// remove row 3engine.sort('Score','desc');// sort descendingengine.rename('A','FullName');// rename columnengine.fill('C1:C5','0');// fill a rangeengine.clear('B:B');// clear entire columnengine.resize(10,5);// grow or shrink the gridTwo ways to ask questions. Simple conditions for the common case, SQL for everything else.
// Simple: column, operator, valueconstresult=engine.query('Age > 25');result.matchCount;// 2result.data;// [['Alice','30','95'], ['Charlie','35','72']]result.columnMeta;// metadata for each column, so you can format the output// SQL: full power when you need itconstsql=engine.sql('SELECT Name, Score FROM data WHERE Score > 85 ORDER BY Score DESC');sql.result;// [{ Name: 'Alice', Score: 95 }, { Name: 'Bob', Score: 87 }]sql.columnMeta;// still there, still usefulBoth query() and sql() return columnMeta alongside the results. This is intentional. When your agent returns a table to the user, the rendering layer needs to know that Score is a number and Price is currency. The metadata is always available. You never have to ask for it separately.
engine.toCSV();// CSV text, format row included if presentengine.toCSV({formatRow: true});// force the format row inengine.toCSV({formatRow: false});// strip it outengine.toObjects();// typed objects with number coercionengine.toTable();// ASCII markdown tableengine.toTable('A1:B3');// just a rangeengine.snapshot('Quarterly report');// everything: data, formulas, charts, metadataengine.schema();// column types and fill statisticssnapshot() is the one you want for AI tool responses. It bundles evaluated data, raw formulas, chart descriptors, column metadata, and a message string into a single object. Hand it to your UI layer and it has everything it needs.
Cells starting with = evaluate when read. The formula engine handles A1 references, ranges, and these functions:
| Formula | What it does | Example |
|---|---|---|
=SUM(range) | Add up numbers | =SUM(A1:A10) |
=AVG(range) | Average (alias: AVERAGE) | =AVG(B1:B5) |
=MAX(range) | Largest value | =MAX(C1:C10) |
=MIN(range) | Smallest value | =MIN(C1:C10) |
=COUNT(range) | How many numbers | =COUNT(A:A) |
=IF(cond, t, f) | Pick one or the other | =IF(A1>10,"high","low") |
=LEN(value) | String length | =LEN(A1) |
=ABS(number) | Absolute value | =ABS(A1) |
=ROUND(n, digits) | Round to N places | =ROUND(A1, 2) |
=CONCAT(a, b, ...) | Stick strings together | =CONCAT(A1, " ", B1) |
Formulas are stored as-is in the CSV. toCSV() preserves them. evaluate() resolves them. Round-trip safe.
Some formulas don't produce numbers. They describe charts. The engine resolves the data ranges and gives you a ChartDescriptor. Your UI picks the charting library.
| Formula | Produces | Example |
|---|---|---|
=PIE(labels, values) | Pie chart descriptor | =PIE(A1:A5, B1:B5) |
=BAR(labels, values) | Bar chart descriptor | =BAR(A1:A5, B1:B5) |
=LINE(labels, values) | Line chart descriptor | =LINE(A1:A10, B1:B10) |
=SPARKLINE(range) | Sparkline descriptor | =SPARKLINE(B1:B10) |
=GAUGE(val, min, max) | Gauge descriptor | =GAUGE(B1, 0, 100) |
constsnap=engine.snapshot();snap.charts;// [{ cell: 'C1', type: 'pie', resolvedLabels: ['Q1','Q2'], resolvedValues: [40,60] }]The data is resolved. The labels are resolved. The UI just draws.
This is the interesting part. Here's a normal CSV:
Product,Quantity,PriceWidget,42,9.99And here's the same CSV with a format row:
:---,---#:,:---$:Product,Quantity,PriceWidget,42,9.99That first line tells any format-aware reader: column 1 is left-aligned text, column 2 is a right-aligned number, column 3 is right-aligned currency. Open this in Excel and you'll see a harmless row of dashes. Open it in @portel/csv and you get typed column metadata for free.
:---#w120+*:
│ │ ││ ││
│ │ ││ │└─ right/center align marker
│ │ ││ └── required field
│ │ ││ └──── text wrapping
│ │ │└────── width in pixels
│ │ └─────── type indicator
│ └────────── dashes (minimum 2)
└──────────── left/center align marker
The syntax is inspired by Markdown table separators. If you've written |:---|---:| in a Markdown table, you already know how this works.
| Alignment | Pattern | Types | Char | Modifiers | Syntax |
|---|---|---|---|---|---|
| Left | :--- | number | # | width | w120 |
| Right | ---: | currency | $ | wrap | + |
| Center | :---: | percent | % | required | * |
| date | D | sort asc | > prefix | ||
| bool | ? | sort desc | < prefix | ||
| markdown | M | ||||
| longtext | T |
Full specification with ABNF grammar: FORMAT.md
The format was designed around one principle: zero cost to ignore.
| Reader | What happens |
|---|---|
| Standard CSV parser | Sees a data row with dashes. Harmless. |
| Excel / Google Sheets | Shows dashes as text. Ignore or delete the row. |
| pandas | skiprows=[0] and carry on. |
@portel/csv | Full metadata extraction. Types, alignment, width, the works. |
Worth repeating: the library stores column metadata but never formats output. type: 'currency' is a hint that says "this column holds money." Your UI decides whether to show $9.99 or €9,99 or 9.99 USD. The engine stays locale-agnostic and opinion-free.
constengine=CsvEngine.fromCSV(csvWithFormatRow);constmeta=engine.getColumnMeta();// meta[2] = { align: 'right', type: 'currency' }// Every result carries this metadataconstquery=engine.query('Price > 5');query.columnMeta[2].type;// 'currency'// Your formatter does: new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })You don't have to use CsvEngine. Every module is exported individually:
import{escapeCSV,parseCSVLine,// CSV primitivesnumberToColumnName,columnNameToNumber,// A ↔ 0, Z ↔ 25, AA ↔ 26cellToIndex,rangeToIndices,// A1 → {row:0, col:0}isFormatRow,parseFormatCell,buildFormatCell,// format row handlingparseCondition,matchCondition,// query conditionsevaluateFormula,isVisualFormula,parseVisualFormula,// formula engine}from'@portel/csv';Building your own CSV viewer? Just pull parseCSVLine and isFormatRow. Writing a data pipeline? Use parseFormatCell to extract types and ignore the rest. The engine is convenient. The parts are flexible.
newCsvEngine()// 10 empty columnsnewCsvEngine({headers: ['Name','Age']})// custom headersnewCsvEngine({ headers, columnMeta,defaultCols: 5})// full controlCsvEngine.fromCSV(csvText: string): CsvEngine// parse CSV text| Property / Method | Returns | Description |
|---|---|---|
rowCount | number | Data rows |
colCount | number | Columns |
getHeaders() | string[] | Column headers (copy) |
getColumnMeta() | ColumnMeta[] | Column metadata (copy) |
evaluate(row, col) | string | Evaluated cell value |
evaluateAll() | string[][] | Full evaluated grid |
getRawCell(row, col) | string | Raw content (formula string if any) |
| Method | Signature | Returns |
|---|---|---|
set | (cell: string, value: string) | void |
add | (values: Record<string, string>) | number (1-indexed row) |
remove | (row: number) | void |
update | (row: number, values: Record<string, string>) | string[] (change descriptions) |
push | (rows: (string[] | Record<string, string>)[]) | number (rows added) |
fill | (range: string, pattern: string) | void |
clear | (range?: string) | void |
resize | (rows?: number, cols?: number) | void |
rename | (column: string, name: string) | string (old name) |
sort | (column: string, order?: 'asc' | 'desc') | void |
format | (column: string, opts) | void |
| Method | Returns | Notes |
|---|---|---|
query(where, limit?) | QueryResult | Conditions: >, <, =, !=, >=, <=, contains |
sql(query) | SqlResult | Full SQL. Requires alasql. |
| Method | Returns | Description |
|---|---|---|
toCSV(options?) | string | CSV text. { formatRow: true/false } controls format row. |
toObjects() | Record[] | Type-coerced objects |
toTable(range?) | string | ASCII markdown table |
snapshot(msg?) | EngineSnapshot | Full state for UIs |
schema() | SchemaColumn[] | Column types and stats |
| Method | Description |
|---|---|
loadCSV(csvText) | Replace state from CSV text |
appendCSVLines(lines) | Append lines, skipping headers/format rows |
Full TypeScript interfaces
interfaceColumnMeta{align: string;// 'left' | 'right' | 'center'type: string;// 'text' | 'number' | 'currency' | 'percent' | 'date'// | 'bool' | 'select' | 'formula' | 'markdown' | 'longtext'width?: number;// pixelsrequired?: boolean;sort?: string;// 'asc' | 'desc'wrap?: boolean;}interfaceEngineSnapshot{table: string;// ASCII tabledata: string[][];// evaluated values (non-empty rows)formulas: Record<string,string>;// cell ref → raw formulaheaders: string[];columnMeta: ColumnMeta[];charts: ChartDescriptor[];message: string;rows: number;cols: number;}interfaceQueryResult{table: string;data: string[][];headers: string[];columnMeta: ColumnMeta[];message: string;matchCount: number;}interfaceSqlResult{result: any;columnMeta: ColumnMeta[];count: number;message: string;}interfaceChartDescriptor{cell: string;type: 'pie'|'bar'|'line'|'sparkline'|'gauge';labelRange?: string;valueRange?: string;resolvedLabels: string[];resolvedValues: number[];min?: number;max?: number;}Pure library. No fs, no fetch, no async. Strings in, strings out. You bring the persistence layer. This means it works in browsers, workers, edge functions, Deno, Bun, wherever JavaScript runs.
Metadata, not opinions. Column types and alignment are stored and returned, never rendered. The engine is intentionally locale-agnostic. A currency column in Tokyo and Toronto should look different, and that's your formatter's job, not ours.
alasql is optional. Most people just need CSV parsing and formulas. SQL is powerful but heavy. It lives behind an optional peer dependency. If you call sql() without installing alasql, you get a clear error message telling you exactly what to do. Not a cryptic module resolution failure.
Format rows round-trip. Load a CSV with a format row, mutate the data, save it back. The format row survives. If you set column formatting programmatically, toCSV() auto-includes a format row even if the original didn't have one.
MIT