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

parsing.mddocs/

CSV Parsing

Core CSV-to-JSON parsing functionality with automatic type conversion, delimiter detection, and comprehensive error handling. Supports multiple input formats and extensive configuration options.

Capabilities

Papa.parse()

Main parsing function that converts CSV data to JSON format with extensive configuration options.

/**
 * Parse CSV data into JSON format
 * @param input - CSV string, File object, or Node.js ReadableStream
 * @param config - Parsing configuration options
 * @returns Parsed result object or Node.js ReadableStream
 */
Papa.parse(input: string | File | NodeJS.ReadableStream | 1, config?: ParseConfig): ParseResult | NodeJS.ReadableStream;

Input Types:

  • String: Direct CSV text data
  • File: Browser File object from <input type="file">
  • ReadableStream: Node.js readable stream (Node.js only)
  • Papa.NODE_STREAM_INPUT: Special constant for Node.js duplex streaming

Usage Examples:

import Papa from 'papaparse';

// Parse CSV string
const csvString = "name,age,email\nJohn,25,john@example.com\nJane,30,jane@example.com";
const result = Papa.parse(csvString, {
  header: true,
  dynamicTyping: true
});
console.log(result.data);
// [{ name: "John", age: 25, email: "john@example.com" }, ...]

// Parse with custom delimiter
const tsvData = "name\tage\temail\nJohn\t25\tjohn@example.com";
const tsvResult = Papa.parse(tsvData, {
  delimiter: '\t',
  header: true
});

// Parse File object (browser)
const fileInput = document.getElementById('csvFile');
fileInput.addEventListener('change', function(e) {
  const file = e.target.files[0];
  Papa.parse(file, {
    header: true,
    complete: function(results) {
      console.log(results.data);
    }
  });
});

Header Processing

Parse CSV files with header rows and transform header names.

interface HeaderConfig {
  header?: boolean;                           // Treat first row as headers
  transformHeader?: (header: string) => string; // Transform header names
}

Usage Examples:

// Basic header parsing
const csvWithHeaders = "First Name,Last Name,Age\nJohn,Doe,25";
const result = Papa.parse(csvWithHeaders, { header: true });
console.log(result.data[0]);
// { "First Name": "John", "Last Name": "Doe", Age: "25" }

// Transform header names
const result2 = Papa.parse(csvWithHeaders, {
  header: true,
  transformHeader: function(header) {
    return header.toLowerCase().replace(' ', '_');
  }
});
console.log(result2.data[0]);
// { first_name: "John", last_name: "Doe", age: "25" }

Dynamic Typing

Automatically convert string values to appropriate JavaScript types.

interface DynamicTypingConfig {
  dynamicTyping?: boolean | object | ((field: string) => boolean);
}

Usage Examples:

const csvData = "name,age,active,score\nJohn,25,true,95.5\nJane,30,false,87.2";

// Enable for all fields
const result1 = Papa.parse(csvData, {
  header: true,
  dynamicTyping: true
});
console.log(result1.data[0]);
// { name: "John", age: 25, active: true, score: 95.5 }

// Enable for specific fields only
const result2 = Papa.parse(csvData, {
  header: true,
  dynamicTyping: {
    age: true,
    score: true
  }
});
console.log(result2.data[0]);
// { name: "John", age: 25, active: "true", score: 95.5 }

// Use function to determine dynamically
const result3 = Papa.parse(csvData, {
  header: true,
  dynamicTyping: function(field) {
    return field !== 'name'; // Convert all except name
  }
});

Data Transformation

Transform values during parsing with custom functions.

interface TransformConfig {
  transform?: (value: string, field: string | number) => any;
}

Usage Examples:

const csvData = "name,email,created_date\nJohn,JOHN@EXAMPLE.COM,2023-01-15";
const result = Papa.parse(csvData, {
  header: true,
  transform: function(value, field) {
    if (field === 'email') {
      return value.toLowerCase();
    }
    if (field === 'created_date') {
      return new Date(value);
    }
    return value;
  }
});
console.log(result.data[0]);
// { name: "John", email: "john@example.com", created_date: Date object }

Error Handling

Comprehensive error reporting with detailed information about parsing issues.

interface ParseError {
  type: string;                    // Error category
  code: string;                    // Specific error code
  message: string;                 // Human-readable error message
  row: number;                     // Row number where error occurred
}

interface ErrorHandlingConfig {
  error?: (error: ParseError) => void; // Error callback function
}

Usage Examples:

const malformedCsv = 'name,age\nJohn,25\nJane,"30,active';
const result = Papa.parse(malformedCsv, {
  header: true,
  error: function(error) {
    console.error('Parse error:', error.message, 'at row', error.row);
  }
});
console.log(result.errors);
// Array of error objects with details

Delimiter Detection

Automatic detection of field delimiters or manual specification.

interface DelimiterConfig {
  delimiter?: string;              // Specific delimiter character
  delimitersToGuess?: string[];    // Delimiters to try during auto-detection
}

Usage Examples:

// Automatic delimiter detection (default)
const csvData = "name;age;city\nJohn;25;NYC";
const result1 = Papa.parse(csvData, { header: true });
// Automatically detects semicolon delimiter

// Manual delimiter specification
const result2 = Papa.parse(csvData, {
  delimiter: ';',
  header: true
});

// Custom delimiter detection list
const result3 = Papa.parse(csvData, {
  delimitersToGuess: [';', '|', '\t'],
  header: true
});

Quote and Escape Handling

Handle quoted fields and escape characters properly.

interface QuoteConfig {
  quoteChar?: string;              // Quote character (default: ")
  escapeChar?: string;             // Escape character
}

Usage Examples:

// Handle quoted fields with commas
const csvData = 'name,description\n"John Doe","A person who likes to say, \\"Hello\\""';
const result = Papa.parse(csvData, {
  header: true,
  quoteChar: '"',
  escapeChar: '\\'
});
console.log(result.data[0]);
// { name: "John Doe", description: "A person who likes to say, \"Hello\"" }

// Custom quote character
const csvData2 = "name,description\n'John Doe','A simple description'";
const result2 = Papa.parse(csvData2, {
  header: true,
  quoteChar: "'"
});

Line Break Handling

Handle different line break formats across platforms.

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

Usage Examples:

// Handle Windows line breaks
const windowsCsv = "name,age\r\nJohn,25\r\nJane,30";
const result1 = Papa.parse(windowsCsv, {
  newline: '\r\n',
  header: true
});

// Handle Unix line breaks
const unixCsv = "name,age\nJohn,25\nJane,30";
const result2 = Papa.parse(unixCsv, {
  newline: '\n',
  header: true
});

// Automatic line break detection (default)
const result3 = Papa.parse(windowsCsv, { header: true });
// Automatically detects \r\n

Preview Mode

Parse only a limited number of rows for data sampling.

interface PreviewConfig {
  preview?: number;                // Maximum number of rows to parse
}

Usage Examples:

const largeCsv = "name,age\n" + Array.from({length: 1000}, (_, i) => `Person${i},${20+i}`).join('\n');

// Parse only first 10 rows
const preview = Papa.parse(largeCsv, {
  header: true,
  preview: 10
});
console.log(preview.data.length); // 10
console.log(preview.meta.truncated); // true

Comments

Skip lines that start with comment characters.

interface CommentConfig {
  comments?: string | boolean;     // Comment character or false to disable
}

Usage Examples:

const csvWithComments = `# This is a comment
name,age
# Another comment
John,25
Jane,30`;

const result = Papa.parse(csvWithComments, {
  header: true,
  comments: '#'
});
console.log(result.data);
// Only data rows, comments are ignored

Fast Mode

Optimized parsing for well-formed CSV data without extensive error checking.

interface FastModeConfig {
  fastMode?: boolean;              // Enable fast parsing mode
}

Usage Examples:

const cleanCsv = "name,age,city\nJohn,25,NYC\nJane,30,LA";
const result = Papa.parse(cleanCsv, {
  header: true,
  fastMode: true // Faster parsing, assumes data is well-formed
});

Empty Line Handling

Control how empty lines in CSV data are processed.

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

Usage Examples:

const csvWithEmptyLines = `name,age

John,25

Jane,30
`;

// Skip completely empty lines
const result1 = Papa.parse(csvWithEmptyLines, {
  header: true,
  skipEmptyLines: true
});

// Skip lines with only whitespace
const result2 = Papa.parse(csvWithEmptyLines, {
  header: true,
  skipEmptyLines: 'greedy'
});

Install with Tessl CLI

npx tessl i tessl/npm-papaparse

docs

index.md

parsing.md

streaming.md

unparsing.md

workers.md

tile.json