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

@tpmjs/tools-csv-stringify

Convert array of objects to CSV string using papaparse.

Installation

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

Usage

With Vercel AI SDK

import { csvStringifyTool } from '@tpmjs/tools-csv-stringify';
import { generateText } from 'ai';

const result = await generateText({
  model: yourModel,
  tools: {
    csvStringify: csvStringifyTool,
  },
  prompt: 'Convert this data to CSV format: [{"name":"Alice","age":25},{"name":"Bob","age":30}]',
});

Direct Usage

import { csvStringifyTool } from '@tpmjs/tools-csv-stringify';

const result = await csvStringifyTool.execute({
  rows: [
    { name: 'Alice', age: 25, city: 'New York' },
    { name: 'Bob', age: 30, city: 'San Francisco' },
    { name: 'Charlie', age: 35, city: 'Boston' },
  ],
});

console.log(result.csv);
// name,age,city
// Alice,25,New York
// Bob,30,San Francisco
// Charlie,35,Boston

console.log(result);
// {
//   csv: '...',
//   rowCount: 3,
//   metadata: {
//     headers: ['name', 'age', 'city'],
//     stringifiedAt: '2025-01-15T12:00:00.000Z',
//     byteSize: 85
//   }
// }

Features

• Automatic Header Detection - Uses object keys from first row if headers not provided
• Custom Headers - Optionally specify custom header names and order
• Type Preservation - Properly handles strings, numbers, booleans, and null values
• Standards Compliant - Follows RFC 4180 CSV specification
• Byte Size Reporting - Returns UTF-8 byte size for file writing

Parameters

Parameter	Type	Required	Default	Description
rows	Record<string, unknown>[]	Yes	-	Array of objects to convert to CSV
headers	string[]	No	Object keys from first row	Custom header names

Returns

{
  csv: string;
  rowCount: number;
  metadata: {
    headers: string[];
    stringifiedAt: string;
    byteSize: number;
  };
}

Examples

Basic Usage

const result = await csvStringifyTool.execute({
  rows: [
    { product: 'Laptop', price: 999.99, inStock: true },
    { product: 'Mouse', price: 29.99, inStock: false },
  ],
});

console.log(result.csv);
// product,price,inStock
// Laptop,999.99,true
// Mouse,29.99,false

Custom Headers

const result = await csvStringifyTool.execute({
  rows: [
    { name: 'Alice', age: 25, city: 'NYC' },
    { name: 'Bob', age: 30, city: 'SF' },
  ],
  headers: ['name', 'city'], // Only include these columns
});

console.log(result.csv);
// name,city
// Alice,NYC
// Bob,SF

Custom Header Order

const result = await csvStringifyTool.execute({
  rows: [
    { age: 25, name: 'Alice', city: 'NYC' },
    { age: 30, name: 'Bob', city: 'SF' },
  ],
  headers: ['name', 'age', 'city'], // Specify order
});

console.log(result.csv);
// name,age,city
// Alice,25,NYC
// Bob,30,SF

Handling Special Characters

const result = await csvStringifyTool.execute({
  rows: [
    { name: 'Alice, Jr.', message: 'Hello "World"' },
    { name: 'Bob\nSmith', message: 'Line\nBreak' },
  ],
});

// Properly escapes commas, quotes, and newlines
console.log(result.csv);
// name,message
// "Alice, Jr.","Hello ""World"""
// "Bob\nSmith","Line\nBreak"

Writing to File

import { writeFile } from 'fs/promises';

const result = await csvStringifyTool.execute({
  rows: [...],
});

await writeFile('output.csv', result.csv, 'utf-8');
console.log(`Wrote ${result.metadata.byteSize} bytes to output.csv`);

Error Handling

try {
  const result = await csvStringifyTool.execute({
    rows: [],
  });
} catch (error) {
  console.error(error.message); // "Rows array cannot be empty"
}

try {
  const result = await csvStringifyTool.execute({
    rows: ['not', 'objects'], // Invalid
  });
} catch (error) {
  console.error(error.message); // "All rows must be objects"
}

License

MIT