Pipe-separated comma-separated values — infinitely dimensional data in a 2D CSV.
npm install 3dcsvPipe-separated comma-separated values — represent complex, multi-valued data in a single 2D CSV. One table, one header row, list-valued cells via a dimension delimiter (default |).
_Yes, it’s still a 2D grid. The “3D” is aspirational._
``bash`
bun add 3dcsvor
npm install 3dcsv
For typed rows with runtime validation (recommended):
`bash`
bun add 3dcsv zod
`ts
import { parse, stringify } from "3dcsv";
const csv = name,age,tags
Alice,30,"js|ts|rust"
Bob,25,"hiking|photography";
const { headers, rows } = parse(csv);
// headers: ['name', 'age', 'tags']
// rows: [
// { name: 'Alice', age: '30', tags: ['js', 'ts', 'rust'] },
// { name: 'Bob', age: '25', tags: ['hiking', 'photography'] }
// ]
const back = stringify({ headers, rows });
// roundtrip: back === csv
`
Pass a Zod schema; return type is inferred. No type assertions.
`ts
import { parse } from "3dcsv";
import { z } from "zod";
const personSchema = z.object({
name: z.string(),
age: z.coerce.number(),
tags: z.array(z.string()),
});
const result = parse(csv, { schema: personSchema });
// result.rows is { name: string; age: number; tags: string[] }[]
// Optional runtime validation
const validated = parse(csv, { schema: personSchema, validate: true });
`
`ts`
type Person = { name: string; age: number; tags: string[] };
const result = parse
// result.rows is Person[]
`ts
const result = parse(csv);
result.rows; // default: array of row objects
result.toRows(); // always: Cell[][] (array of arrays)
result.toObjects(); // always: Record
`
Come back down to earth and expand list-valued cells into one row per element (join-table style). Then stringify to get plain CSV with no pipes.
`tsname,tags
const csv =
Alice,"js|ts|rust";`
const flat = parse(csv).flatten();
// flat.rows: [{ name: "Alice", tags: "js" }, { name: "Alice", tags: "ts" }, ...]
const regularCsv = stringify(flat); // no pipes
Optional: parse(csv).flatten({ columns: ["tags"] }) to expand only specific columns.
Run a local server and open a React table view in the browser:
`bash`
bunx 3dcsv visualizeor with a file (relative to cwd):
bunx 3dcsv visualize example.csv
Opens http://localhost:3847 (or PORT env). List-valued cells render as badges. The UI is built with React and bundled with Bun; run bun run dev:ui to watch for changes and bun run dev:server to run the server.
If you do nothing, you get { headers: string[]; rows: unknown[] }. Typed rows are opt-in via schema or generic.
- parse(input, options?) — Parse 3D CSV. Options: dimensionDelimiters, header, columns, asObjects, schema, validate.parse(csv).flatten(options?)
- — Expand array cells into one row per element (Cartesian product when multiple columns); returns Parsed3DCSV with all scalar rows. Options: columns?: string[].stringify(data, options?)
- — Stringify to 3D CSV. Accepts { headers, rows } or array of row objects (headers inferred).bunx 3dcsv visualize [file.csv]
- — Start a local server and open a table UI; optional file path (relative to cwd).
_It’s just CSV with pipes in the cells. Sometimes that’s all you need. Sometimes._
- Rows and columns as usual; cells can contain a dimension delimiter (default |)."a|b|c"
- A cell like is one cell whose value is the list ["a", "b", "c"].""
- Quoting and escaping follow standard CSV (e.g. inside quoted fields).
Changesets for versioning: run bun run changeset` when you change the package. Merge the “Version Packages” PR to publish. See .changeset/README.md.
MIT
---
_3D CSV: because one dimension was never enough. We’re not saying it’s a good idea — we’re just saying it works._