CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-papaparse

Fast and powerful CSV parser for the browser that supports web workers and streaming large files.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

unparsing.mddocs/

CSV Generation (Unparsing)

JSON-to-CSV conversion functionality with customizable formatting, quote handling, and column ordering. Converts JavaScript objects and arrays into properly formatted CSV strings.

Capabilities

Papa.unparse()

Main function for converting JSON data to CSV format with extensive formatting options.

/**
 * Convert JSON data to CSV format
 * @param input - Data to convert: array of objects, array of arrays, or structured object
 * @param config - Unparsing configuration options
 * @returns CSV string
 */
Papa.unparse(input: object[] | string[][] | UnparseObject, config?: UnparseConfig): string;

Input Types:

  • Array of Objects: [{name: "John", age: 25}, {name: "Jane", age: 30}]
  • Array of Arrays: [["name", "age"], ["John", 25], ["Jane", 30]]
  • UnparseObject: {fields: ["name", "age"], data: [["John", 25], ["Jane", 30]]}

Usage Examples:

import Papa from 'papaparse';

// Convert array of objects
const users = [
  { name: "John", age: 25, city: "NYC" },
  { name: "Jane", age: 30, city: "LA" }
];
const csv1 = Papa.unparse(users);
console.log(csv1);
// "name,age,city\nJohn,25,NYC\nJane,30,LA"

// Convert array of arrays
const data = [
  ["name", "age", "city"],
  ["John", 25, "NYC"],
  ["Jane", 30, "LA"]
];
const csv2 = Papa.unparse(data);
console.log(csv2);
// "name,age,city\nJohn,25,NYC\nJane,30,LA"

// Convert structured object
const structured = {
  fields: ["name", "age", "city"],
  data: [
    ["John", 25, "NYC"],
    ["Jane", 30, "LA"]
  ]
};
const csv3 = Papa.unparse(structured);
console.log(csv3);
// "name,age,city\nJohn,25,NYC\nJane,30,LA"

Quote Handling

Control when fields are quoted in the output CSV.

interface QuoteConfig {
  quotes?: boolean | boolean[] | ((value: any, columnIndex: number) => boolean); // Quote behavior
  quoteChar?: string;             // Quote character (default: ")
  escapeChar?: string;            // Escape character for quotes
}

Usage Examples:

const data = [
  { name: "John Doe", description: "A person who likes to say, \"Hello\"", age: 25 }
];

// Quote all fields
const csv1 = Papa.unparse(data, { quotes: true });
console.log(csv1);
// "\"name\",\"description\",\"age\"\n\"John Doe\",\"A person who likes to say, \"\"Hello\"\"\",\"25\""

// Quote specific columns only
const csv2 = Papa.unparse(data, { 
  quotes: [true, true, false] // Quote name and description, not age
});

// Dynamic quoting based on content
const csv3 = Papa.unparse(data, {
  quotes: function(value, columnIndex) {
    // Quote if value contains comma or quotes
    return typeof value === 'string' && (value.includes(',') || value.includes('"'));
  }
});

// Custom quote character
const csv4 = Papa.unparse(data, {
  quotes: true,
  quoteChar: "'"
});
console.log(csv4);
// "'name','description','age'\n'John Doe','A person who likes to say, \"Hello\"','25'"

Delimiter Configuration

Customize the field separator character.

interface DelimiterConfig {
  delimiter?: string;             // Field delimiter character
}

Usage Examples:

const data = [
  { name: "John", age: 25, city: "NYC" },
  { name: "Jane", age: 30, city: "LA" }
];

// Use semicolon delimiter
const csv1 = Papa.unparse(data, { delimiter: ';' });
console.log(csv1);
// "name;age;city\nJohn;25;NYC\nJane;30;LA"

// Use tab delimiter
const csv2 = Papa.unparse(data, { delimiter: '\t' });
console.log(csv2);
// "name\tage\tcity\nJohn\t25\tNYC\nJane\t30\tLA"

// Use pipe delimiter
const csv3 = Papa.unparse(data, { delimiter: '|' });
console.log(csv3);
// "name|age|city\nJohn|25|NYC\nJane|30|LA"

Line Break Configuration

Control the line terminator characters.

interface LineBreakConfig {
  newline?: string;               // Line terminator character(s)
}

Usage Examples:

const data = [
  { name: "John", age: 25 },
  { name: "Jane", age: 30 }
];

// Windows line breaks
const csv1 = Papa.unparse(data, { newline: '\r\n' });
console.log(csv1);
// "name,age\r\nJohn,25\r\nJane,30"

// Unix line breaks (default)
const csv2 = Papa.unparse(data, { newline: '\n' });
console.log(csv2);
// "name,age\nJohn,25\nJane,30"

// Custom line separator
const csv3 = Papa.unparse(data, { newline: '||\n' });
console.log(csv3);
// "name,age||\nJohn,25||\nJane,30"

Header Control

Control whether to include header row in output.

interface HeaderConfig {
  header?: boolean;               // Include header row
}

Usage Examples:

const data = [
  { name: "John", age: 25 },
  { name: "Jane", age: 30 }
];

// Include headers (default)
const csv1 = Papa.unparse(data, { header: true });
console.log(csv1);
// "name,age\nJohn,25\nJane,30"

// Exclude headers
const csv2 = Papa.unparse(data, { header: false });
console.log(csv2);
// "John,25\nJane,30"

// For array of arrays, first row is treated as header
const arrayData = [
  ["name", "age"],
  ["John", 25],
  ["Jane", 30]
];
const csv3 = Papa.unparse(arrayData, { header: false });
console.log(csv3);
// "name,age\nJohn,25\nJane,30" (first row still included)

Column Ordering

Specify the order of columns in the output CSV.

interface ColumnConfig {
  columns?: string[];             // Column order for object unparsing
}

Usage Examples:

const users = [
  { age: 25, name: "John", city: "NYC", country: "USA" },
  { age: 30, name: "Jane", city: "LA", country: "USA" }
];

// Specify column order
const csv1 = Papa.unparse(users, {
  columns: ["name", "city", "age"] // Exclude country, reorder columns
});
console.log(csv1);
// "name,city,age\nJohn,NYC,25\nJane,LA,30"

// Include all columns in specific order
const csv2 = Papa.unparse(users, {
  columns: ["country", "city", "name", "age"]
});
console.log(csv2);
// "country,city,name,age\nUSA,NYC,John,25\nUSA,LA,Jane,30"

Empty Line Handling

Control how empty rows are handled in the output.

interface EmptyLineConfig {
  skipEmptyLines?: boolean | 'greedy'; // Skip empty lines behavior
}

Usage Examples:

const data = [
  { name: "John", age: 25 },
  { name: "", age: null },  // Empty name, null age
  { name: "Jane", age: 30 }
];

// Include empty lines (default)
const csv1 = Papa.unparse(data);
console.log(csv1);
// "name,age\nJohn,25\n,\nJane,30"

// Skip completely empty lines
const csv2 = Papa.unparse(data, { skipEmptyLines: true });
console.log(csv2);
// "name,age\nJohn,25\n,\nJane,30" (line with empty values still included)

// Skip lines with only whitespace/empty values
const csv3 = Papa.unparse(data, { skipEmptyLines: 'greedy' });
console.log(csv3);
// "name,age\nJohn,25\nJane,30" (empty value line skipped)

Formula Escaping

Prevent CSV fields from being interpreted as spreadsheet formulas.

interface FormulaConfig {
  escapeFormulae?: boolean;       // Escape potential spreadsheet formulas
}

Usage Examples:

const data = [
  { name: "John", formula: "=SUM(A1:A10)" },
  { name: "Jane", formula: "+1+1" },
  { name: "Bob", formula: "-1+2" },
  { name: "Alice", formula: "@SUM(1,2)" }
];

// Escape formulas for safety
const csv = Papa.unparse(data, { escapeFormulae: true });
console.log(csv);
// "name,formula\nJohn,'=SUM(A1:A10)\nJane,'+1+1\nBob,'-1+2\nAlice,'@SUM(1,2)"
// Formulas are prefixed with single quote to prevent execution

JSON String Input

Parse JSON strings before converting to CSV.

/**
 * Convert JSON string to CSV
 * @param input - JSON string representation of data
 * @param config - Unparsing configuration
 */
Papa.unparse(input: string, config?: UnparseConfig): string;

Usage Examples:

// JSON string input
const jsonString = '[{"name":"John","age":25},{"name":"Jane","age":30}]';
const csv = Papa.unparse(jsonString);
console.log(csv);
// "name,age\nJohn,25\nJane,30"

// JSON string with nested data property
const nestedJsonString = '{"data":[["name","age"],["John",25],["Jane",30]]}';
const csv2 = Papa.unparse(nestedJsonString);
console.log(csv2);
// "name,age\nJohn,25\nJane,30"

Advanced Configuration

Complete configuration interface for fine-tuned control.

interface UnparseConfig {
  quotes?: boolean | boolean[] | ((value: any, columnIndex: number) => boolean); // Quote behavior
  quoteChar?: string;             // Quote character (default: ")
  escapeChar?: string;            // Escape character for quotes within quotes
  delimiter?: string;             // Field delimiter (default: ,)
  header?: boolean;               // Include header row (default: true)
  newline?: string;               // Line terminator (default: \r\n)
  skipEmptyLines?: boolean | 'greedy'; // Skip empty lines behavior
  columns?: string[];             // Column order for object unparsing
  escapeFormulae?: boolean;       // Escape spreadsheet formulas (default: false)
}

interface UnparseObject {
  fields: string[];               // Column headers
  data: any[][];                  // Data rows as arrays
}

Complete Example:

const complexData = [
  { 
    id: 1,
    name: "John, Jr.", 
    email: "john@example.com",
    notes: "Likes to say \"Hello!\"",
    formula: "=A1+B1",
    active: true
  },
  { 
    id: 2,
    name: "Jane Smith", 
    email: "jane@example.com",
    notes: "",
    formula: "+10*2",
    active: false
  }
];

const csv = Papa.unparse(complexData, {
  quotes: function(value, columnIndex) {
    // Quote strings that contain special characters
    return typeof value === 'string' && 
           (value.includes(',') || value.includes('"') || value.includes('\n'));
  },
  quoteChar: '"',
  escapeChar: '"',
  delimiter: ',',
  header: true,
  newline: '\n',
  skipEmptyLines: 'greedy',
  columns: ['id', 'name', 'email', 'active', 'notes'], // Exclude formula
  escapeFormulae: true
});

console.log(csv);
// Properly formatted CSV with escaped quotes and controlled quoting

Install with Tessl CLI

npx tessl i tessl/npm-papaparse

docs

index.md

parsing.md

streaming.md

unparsing.md

workers.md

tile.json