tpmjs/packages/tools/official/csv-parse/README.md

@tpmjs/tools-csv-parse

Parse CSV text into array of objects using papaparse.

Installation

npm install @tpmjs/tools-csv-parse
# or
pnpm add @tpmjs/tools-csv-parse
# or
yarn add @tpmjs/tools-csv-parse

Usage

With Vercel AI SDK

import { csvParseTool } from '@tpmjs/tools-csv-parse';
import { generateText } from 'ai';

const result = await generateText({
  model: yourModel,
  tools: {
    csvParse: csvParseTool,
  },
  prompt: 'Parse this CSV data and tell me the average age: name,age\nAlice,25\nBob,30\nCharlie,35',
});

Direct Usage

import { csvParseTool } from '@tpmjs/tools-csv-parse';

const result = await csvParseTool.execute({
  csv: `name,age,city
Alice,25,New York
Bob,30,San Francisco
Charlie,35,Boston`,
  hasHeaders: true,
});

console.log(result);
// {
//   rows: [
//     { name: 'Alice', age: 25, city: 'New York' },
//     { name: 'Bob', age: 30, city: 'San Francisco' },
//     { name: 'Charlie', age: 35, city: 'Boston' }
//   ],
//   headers: ['name', 'age', 'city'],
//   rowCount: 3,
//   metadata: {
//     parsedAt: '2025-01-15T12:00:00.000Z',
//     hasErrors: false,
//     errorCount: 0
//   }
// }

Features

• Automatic Type Inference - Numbers and booleans are automatically converted
• Header Detection - Automatically uses first row as headers or generates generic ones
• Error Handling - Reports parsing errors with row numbers
• Data Cleaning - Trims whitespace from headers and values
• Empty Line Handling - Automatically skips empty lines

Parameters

Parameter	Type	Required	Default	Description
csv	string	Yes	-	The CSV text to parse
hasHeaders	boolean	No	true	Whether the first row contains headers

Returns

{
  rows: Record<string, string | number | boolean | null>[];
  headers: string[];
  rowCount: number;
  metadata: {
    parsedAt: string;
    hasErrors: boolean;
    errorCount: number;
    errors?: Array<{
      row: number;
      message: string;
    }>;
  };
}

Examples

CSV with Headers

const result = await csvParseTool.execute({
  csv: 'product,price,inStock\nLaptop,999.99,true\nMouse,29.99,false',
});
// rows: [
//   { product: 'Laptop', price: 999.99, inStock: true },
//   { product: 'Mouse', price: 29.99, inStock: false }
// ]

CSV without Headers

const result = await csvParseTool.execute({
  csv: 'Alice,25,Engineer\nBob,30,Designer',
  hasHeaders: false,
});
// rows: [
//   { col_0: 'Alice', col_1: 25, col_2: 'Engineer' },
//   { col_0: 'Bob', col_1: 30, col_2: 'Designer' }
// ]

Handling Errors

const result = await csvParseTool.execute({
  csv: 'name,age\nAlice,25\nBob,invalid\nCharlie,35',
});
// metadata.hasErrors: true
// metadata.errors: [{ row: 1, message: '...' }]

License

MIT