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

PapaParse

PapaParse is a fast and powerful CSV parsing library for JavaScript that works in browsers and Node.js environments. It provides comprehensive CSV-to-JSON and JSON-to-CSV conversion capabilities with support for RFC 4180 compliance, automatic delimiter detection, streaming of large files, web worker integration for non-blocking parsing, and advanced features like pause/resume/abort functionality.

Package Information

  • Package Name: papaparse
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install papaparse

Core Imports

import Papa from 'papaparse';

For CommonJS:

const Papa = require('papaparse');

For browsers:

<script src="https://unpkg.com/papaparse@latest/papaparse.min.js"></script>

For AMD:

define(['papaparse'], function(Papa) {
  // Use Papa here
});

For jQuery:

$('#fileInput').parse({
  config: {
    header: true,
    complete: function(results, file) {
      console.log('Parsed:', results.data);
    }
  }
});

Basic Usage

import Papa from 'papaparse';

// Parse CSV string to JSON
const csvData = "name,age,city\nJohn,25,NYC\nJane,30,LA";
const results = Papa.parse(csvData, {
  header: true,
  dynamicTyping: true
});
console.log(results.data);
// [{ name: "John", age: 25, city: "NYC" }, { name: "Jane", age: 30, city: "LA" }]

// Convert JSON to CSV
const jsonData = [
  { name: "John", age: 25, city: "NYC" },
  { name: "Jane", age: 30, city: "LA" }
];
const csv = Papa.unparse(jsonData);
console.log(csv);
// "name,age,city\nJohn,25,NYC\nJane,30,LA"

Architecture

PapaParse is built around several key components:

  • Core Parser: Main Papa.parse() and Papa.unparse() methods for CSV/JSON conversion
  • Streaming Engine: Multiple streamer classes for handling different input types (files, strings, network, Node.js streams)
  • Web Worker Support: Background processing for large datasets without blocking the UI
  • Configuration System: Extensive options for customizing parsing and unparsing behavior
  • Parser Classes: Low-level Parser and ParserHandle classes for direct parsing control

Capabilities

CSV Parsing

Core CSV-to-JSON parsing functionality with automatic type conversion, delimiter detection, and error handling. Supports strings, files, and URLs as input sources.

Papa.parse(input: string | File | NodeJS.ReadableStream | 1, config?: ParseConfig): ParseResult | NodeJS.ReadableStream;

CSV Parsing

CSV Generation

JSON-to-CSV conversion with customizable formatting, quote handling, and column ordering. Supports arrays of objects, arrays of arrays, and structured data objects.

Papa.unparse(input: object[] | string[][] | UnparseObject, config?: UnparseConfig): string;

CSV Generation

File Streaming

High-performance streaming for large CSV files with chunk-based processing, progress callbacks, and memory-efficient parsing. Supports local files, remote URLs, and Node.js streams.

Papa.parse(file: File | string, config: { download?: boolean; chunk?: Function; step?: Function }): void;

File Streaming

Web Worker Support

Background parsing using web workers to prevent UI blocking during large file processing. Automatically creates and manages worker threads with message passing.

Papa.parse(input: string | File, config: { worker: true }): void;

Web Workers

jQuery Integration

Optional jQuery plugin for easy file input processing when jQuery is available.

$('#fileInput').parse(options: {
  config?: ParseConfig;
  before?: (file: File, inputElement: Element) => void | object;
  error?: (error: ParseError, file: File, inputElement: Element, reason?: string) => void;
  complete?: (results: ParseResult, file: File, inputElement: Element) => void;
}): jQuery;

Usage Examples:

// Basic jQuery file processing
$('#csvFileInput').parse({
  config: {
    header: true,
    dynamicTyping: true,
    worker: true
  },
  complete: function(results, file) {
    console.log('File:', file.name, 'Rows:', results.data.length);
  }
});

// Multiple files with preprocessing
$('#multipleFiles').parse({
  before: function(file, inputElem) {
    if (file.size > 10 * 1024 * 1024) { // > 10MB
      return { config: { worker: true, chunkSize: Papa.LocalChunkSize } };
    }
  },
  config: { header: true },
  complete: function(results, file) {
    addFileResults(file.name, results.data);
  },
  error: function(error, file) {
    console.error('Error parsing', file.name, ':', error);
  }
});

Constants and Configuration

Built-in Constants

Papa.RECORD_SEP: string;           // ASCII record separator (char 30)
Papa.UNIT_SEP: string;             // ASCII unit separator (char 31)
Papa.BYTE_ORDER_MARK: string;      // UTF-8 BOM ('\ufeff')
Papa.BAD_DELIMITERS: string[];     // Invalid delimiter characters
Papa.WORKERS_SUPPORTED: boolean;   // Web Worker availability
Papa.NODE_STREAM_INPUT: 1;         // Node.js stream input constant
Papa.LocalChunkSize: number;       // Default local file chunk size (10MB)
Papa.RemoteChunkSize: number;      // Default remote file chunk size (5MB)
Papa.DefaultDelimiter: string;     // Default delimiter (',')

Internal APIs (Development/Testing)

These classes are exposed for development and testing purposes but are not recommended for typical usage:

Papa.Parser: class;                // Core parser class
Papa.ParserHandle: class;          // Parser with configuration handling
Papa.NetworkStreamer: class;       // Network streaming implementation
Papa.FileStreamer: class;          // File streaming implementation  
Papa.StringStreamer: class;        // String streaming implementation
Papa.ReadableStreamStreamer: class; // Node.js ReadableStream streaming
Papa.DuplexStreamStreamer: class;  // Node.js duplex streaming (Node.js only)

Note: These internal APIs may change without notice. Use the main Papa.parse() and Papa.unparse() methods for production applications.

Types

ParseResult

interface ParseResult {
  data: any[][];                   // Parsed data rows
  errors: ParseError[];            // Parse errors encountered
  meta: {
    delimiter: string;             // Detected or used delimiter
    linebreak: string;             // Detected or used line break
    aborted: boolean;              // Whether parsing was aborted
    truncated: boolean;            // Whether data was truncated
    cursor: number;                // Final parsing position
    fields?: string[];             // Field names when header: true
  };
}

ParseError

interface ParseError {
  type: string;                    // Error type
  code: string;                    // Error code
  message: string;                 // Error description
  row: number;                     // Row number where error occurred
}

ParseConfig

interface ParseConfig {
  delimiter?: string;              // Field delimiter
  newline?: string;               // Line terminator
  quoteChar?: string;             // Quote character
  escapeChar?: string;            // Escape character
  header?: boolean;               // First row contains headers
  transformHeader?: (header: string) => string; // Transform header names
  dynamicTyping?: boolean | object | ((field: string) => boolean); // Auto-convert types
  preview?: number;               // Parse only first N rows
  encoding?: string;              // Character encoding (Node.js)
  worker?: boolean;               // Use web worker
  comments?: string | boolean;    // Comment character
  step?: (result: ParseResult, parser: any) => void; // Row callback
  complete?: (result: ParseResult) => void; // Completion callback
  error?: (error: ParseError) => void; // Error callback
  download?: boolean;             // Download from URL
  downloadRequestHeaders?: object; // Request headers
  downloadRequestBody?: string | FormData; // Request body
  skipEmptyLines?: boolean | 'greedy'; // Skip empty lines behavior
  chunk?: (result: ParseResult, parser: any) => void; // Chunk callback
  chunkSize?: number;             // Chunk size in bytes
  fastMode?: boolean;             // Fast parsing mode
  beforeFirstChunk?: (chunk: string) => string; // Pre-process chunk
  withCredentials?: boolean;      // Include credentials
  transform?: (value: string, field: string | number) => any; // Transform values
  delimitersToGuess?: string[];   // Delimiters for auto-detection
}

UnparseConfig

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

UnparseObject

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

Install with Tessl CLI

npx tessl i tessl/npm-papaparse
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/papaparse@5.5.x
Publish Source
CLI
Badge
tessl/npm-papaparse badge