🚀 Data Alchemy ✨

Stop writing CSV/XLSX parsers. Convert Base64, CSV, or Excel files → clean JSON in 1 line.

Transform Your Data with Ease. Effortlessly convert Base64-encoded CSV or XLSX files directly into rich JSON formats.

Data Alchemy is no longer just a utility wrapper—it's a high-performance powerful data transformation utility. Now powered by industrial-strength parsing (papaparse), dynamic typing, and automated data cleaning, it even comes with a handy command-line interface!

⚡ Why DataAlchemy?

Working with CSV or Excel in Node.js is painful:

• ❌ Manual parsing logic
• ❌ Broken rows & messy data
• ❌ Base64 decoding headaches
• ❌ Type conversion issues

👉 Data Alchemy fixes all of this instantly.

🚀 Features

• Reverse Alchemy 🔁 (JSON to Base64): Export JSON data back to Base64 CSV or XLSX instantly!
• Header Mapping 🗺️: Safely map messy CSV headers ("Client First Na.me") directly to clean keys ("firstName").
• Blazing Fast Parsing: Built on top of PapaParse for rock-solid, incredibly fast CSV operations. Supports commas inside values and multi-line cells.
• Auto-Detect File Types: Forget explicitly defining type="csv". Just pass the base64 string, and let Data Alchemy determine if it's an XLSX or CSV.
• Data Cleaning Built-In: Automatically trims whitespace, lowercases headers, and removes empty rows out of the box.
• Type Inference (Dynamic Typing): Automatically parses numbers and booleans correctly ("25" turns into 25, "true" turns into true).
• CLI Tool Included: Convert files right from your terminal without writing a single line of code.
• Full TypeScript Support: Generics support for dynamic return types base64ToJSON<T>().
• Multi-Sheet XLSX Support: Need a specific page? Pass sheet: "Sheet2". Need every page? Pass sheet: "all" to get a dictionary of all sheets mapped to their exact names!

📦 Installation

To use Data Alchemy in your project or as a local CLI:

npm i dataalchemy

If you want to use the CLI globally:

npm install -g dataalchemy

💻 CLI Usage (New!)

Data Alchemy now includes a powerful CLI to convert files right from your terminal.

# Basic usage. It reads the file, converts via base64 automatically under the hood!
dataalchemy convert path/to/file.csv

# Output to a file
dataalchemy convert path/to/file.xlsx -o output.json

# Extract a specific sheet from XLSX
dataalchemy convert finances.xlsx --sheet "Q3" -o output.json

# Extract ALL sheets from XLSX securely mapped to their sheet names
dataalchemy convert finances.xlsx --sheet all -o output.json

🛠️ Library Usage

🔁 Reverse Alchemy (JSON to Base64 CSV/XLSX)

Data Alchemy isn't just about reading files—you can instantly convert your database JSON into explicit Base64 CSV or XLSX files for users to download.

import { jsonToBase64 } from 'dataalchemy';

const exportArray = [
  { username: "Alice", age: 28 },
  { username: "Bob", age: 32 }
];

const base64Output = jsonToBase64({
    data: exportArray,
    type: "csv" // or "xlsx"
});

console.log(base64Output); 
// Outputs ready-to-download Base64 encoded string!

Basic Example (Auto-Detect!)

import { base64ToJSON } from 'dataalchemy';

// Pass base64 data. Data Alchemy will figure out if it's CSV or XLSX automatically.
const jsonData = base64ToJSON({ base64Data: "UEsDBBQ..." });

console.log(jsonData);
// Output with Type Inference: [{ name: "John Doe", age: 30 }] 

Power Features & Header Mapping

Data Alchemy allows you to structure and clean your output using the new props:

import { base64ToJSON } from 'dataalchemy';

interface UserRow {
  firstName: string;
  age: number;
}

const jsonData = base64ToJSON<UserRow>({ 
  base64Data: myBase64String,
  headerMap: { "Client First Na.me": "firstName" }, // Maps messy headers to clean keys 🔥
  trim: true,                // Trims whitespace from cells (default: true)
  lowercaseHeaders: true,    // Converts headers like "NaMe" to "name" (default: false)
  removeEmptyRows: true,     // Removes blank lines (default: true)
  dynamicTyping: true        // "25" -> 25 (default: true)
});

📗 Multi-Page XLSX Support

Extract exactly what you need out of workbooks.

// 1. Extract a specific page
const q3Data = base64ToJSON({ 
    base64Data: myXlsxBase64,
    sheet: "Q3_Earnings" 
});

// 2. Extract ALL pages mapped to their actual sheet names!
const masterWorkbookMap = base64ToJSON({ 
    base64Data: myXlsxBase64,
    sheet: "all" 
});

console.log(masterWorkbookMap);
/* Output:
{
   "Q1_Earnings": [ { "revenue": 5000 } ],
   "Q2_Earnings": [ { "revenue": 8500 } ],
   "Q3_Earnings": [ { "revenue": 10000 } ]
}
*/

Async Version

For standard node operations parity:

import { base64ToJSONAsync } from 'dataalchemy';

const transformData = async () => {
    const data = await base64ToJSONAsync({ base64Data });
};

🧠 Comparison

| Feature | DataAlchemy | Manual Parsing | | ------------------- | ----------- | -------------- | | Base64 Support | ✅ | ❌ | | Auto Type Detection | ✅ | ❌ | | Handles Messy Data | ✅ | ❌ | | Excel Support | ✅ | ⚠️ | | Developer Friendly | ✅ | ❌ |

📈 Performance

• ⚡ Optimized for speed
• 🧠 Optimized for typical datasets (streaming support coming soon)
• 🔧 Built on top of robust parsing libraries (papaparse, xlsx)

🛠️ Roadmap

• [ ] Streaming support for large files
• [ ] Data validation schemas
• [ ] Web playground
• [ ] VS Code extension
• [ ] API service

🌍 Keywords for Discoverability (SEO)

CSV to JSON, Node.js Excel parser, Base64 to JSON converter, Parse CSV in JavaScript, XLSX to JSON npm package, Data transformation utility, Data manipulation TypeScript, fast node CSV parser, reverse conversion.

🤝 Contributing & Support

Contributions are welcome! Feel free to open issues or submit PRs on our GitHub repository. If this package helped you: 👉 Star the repo 👉 Share with other developers

📜 License & Vision

MIT License

DataAlchemy aims to become the easiest way to transform messy data into usable JSON.

Made by @palacharlanarendra and community.