path-binder
path-binder
Label your columns with paths.
path-binder builds the JSON.
A TypeScript library that parses flat data into nested JSON.
From Flat Data, To Nested JSON
| user.name | user.age | user.role |
|---|---|---|
| Taro | 25 | admin |
| Jiro | 30 | editor |
{
"user": [
{ "name": "Taro", "age": 25, "role": "admin" },
{ "name": "Jiro", "age": 30, "role": "editor" }
]
}
Write JSON paths as column headers. Fill in the data rows. Call generate(). That’s it.
Get Started in 3 Steps
1. Install
npm install path-binder
2. Prepare your data
Convert each spreadsheet column into { path, value } pairs.
import { generate } from 'path-binder'
const input = {
Sheet1: [
[{ path: 'user.name', value: 'Taro' }, { path: 'user.age', value: 25 }],
[{ path: 'user.name', value: 'Jiro' }, { path: 'user.age', value: 30 }],
],
}
3. Transform
const { result } = generate(input)
// → {
// user: [
// { name: 'Taro', age: 25 },
// { name: 'Jiro', age: 30 }
// ]
// }
Why path-binder?
Ever needed to transform flat data — from CSVs, spreadsheets, or databases — into structured JSON in a B2B SaaS product?
With path-binder, just add JSON path labels to your data columns. No complex transformation logic needed. Once paths are defined, the mapping works permanently — no matter how the data layout changes.
"Wouldn't Excel formulas be easier?"
For a one-off conversion, maybe. But maintaining complex formula chains across evolving business requirements creates ongoing support overhead. path-binder’s approach — simple labels that map directly to your data model — eliminates that cost entirely. Introduce it with your support team, and the reduction in maintenance effort speaks for itself.
Features
Zero Dependencies
No external dependencies. Keeps your node_modules clean — lightweight and fast.
Type Safe
Strict type inference based on your schema definition. Get the most out of TypeScript.
Schema Support
Declaratively define casting and filtering. Unwanted columns are automatically excluded.
Multi Sheet
Automatically join data across sheets using reference keys ($). Build relational structures in a single call.
Advanced Usage
Combine schemas for type casting with $ reference keys for multi-sheet joining.
import { generate, defineSchema, asNumber, asString, arrayOf } from 'path-binder'
const input = {
sheetA: [
[{ path: 'user.id', value: 1 }, { path: 'user.name', value: 'Taro' }],
[{ path: 'user.id', value: 2 }, { path: 'user.name', value: 'Jiro' }],
],
sheetB: [
[{ path: 'user.$id', value: 1 }, { path: 'user.info[].type', value: 'google' }],
],
}
const schema = defineSchema({
user: {
id: asNumber(),
name: asString(),
info: arrayOf({ type: asString() }),
},
})
const { result } = generate(input, { schema })
// → {
// user: [
// { id: 1, name: 'Taro', info: [{ type: 'google' }] },
// { id: 2, name: 'Jiro' },
// ]
// }
Next steps: Learn Path Syntax for nesting and arrays → Set up Schemas for type casting and filtering → Try the Playground