Registry / serialization / csv-simple-parser

csv-simple-parser

library2.0.2jsnpmunverified

csv-simple-parser is a lightweight, fast, and highly configurable CSV parsing library for JavaScript and TypeScript. It offers robust functionality for converting CSV string data into either arrays of string arrays or arrays of objects (when headers are present). A key differentiator is its built-in, configurable type inference system, which can automatically convert string values to numbers, booleans, or nulls, or be customized with a user-defined inference function. The library is currently at version 2.0.2 and appears to have a stable, though not rapid, release cadence, focusing on simplicity and performance. It's suitable for both Node.js and browser environments, providing a straightforward API for common CSV parsing tasks without the overhead of more complex streaming parsers.

serialization data

npm install csv-simple-parser

github ↗package ↗

INSTALL

IMPORT

SIG · CSV-SIMPLE-PARSER

csv-simple-parser

serializationjavascriptv2.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

✓ import parse from 'csv-simple-parser';

✗ const parse = require('csv-simple-parser');

The primary export is a default export, typically imported as 'parse'. CommonJS `require` might lead to `parse.default` or runtime errors in pure ESM environments.

Options

✓ import type { Options } from 'csv-simple-parser';

When using TypeScript, import the `Options` type to strongly type the configuration object for the parser.

CustomInferer

✓ import type { CustomInferer } from 'csv-simple-parser';

For advanced type inference scenarios, import the `CustomInferer` type to correctly type your custom infer function.

Demonstrates parsing CSV strings into objects with header and type inference, using custom delimiters, and also parsing into arrays of arrays.

import parse from 'csv-simple-parser'; // Example 1: Parse CSV with headers and automatic type inference const csvDataWithTypes = 'Name,Age,Active,Balance\n"Alice",30,true,100.50\n"Bob",24,false,200.00\n"Charlie",NULL,true,null'; const parsedObjects = parse(csvDataWithTypes, { header: true, infer: true }); console.log('Parsed with inference:', parsedObjects); /* Output: [ { Name: 'Alice', Age: 30, Active: true, Balance: 100.5 }, { Name: 'Bob', Age: 24, Active: false, Balance: 200 }, { Name: 'Charlie', Age: null, Active: true, Balance: null } ] */ // Example 2: Parse CSV with custom delimiter and explicit type inference function const customCsv = 'ID|Product|Price\n101|"Laptop"|1200.00\n102|"Mouse"|25.50'; const customInferFn = (value, x, y, isExplicitlyQuoted) => { if (y === 2) return parseFloat(value); return value; }; const parsedCustom = parse(customCsv, { header: true, delimiter: '|', infer: customInferFn }); console.log('\nParsed with custom delimiter & infer:', parsedCustom); /* Output: [ { ID: '101', Product: 'Laptop', Price: 1200 }, { ID: '102', Product: 'Mouse', Price: 25.5 } ] */ // Example 3: Parse CSV without headers, returning array of arrays const simpleCsv = 'Header1,Header2\nvalueA,valueB\nvalueC,valueD'; const parsedArray = parse(simpleCsv); console.log('\nParsed as array of arrays:', parsedArray); /* Output: [ [ 'Header1', 'Header2' ], [ 'valueA', 'valueB' ], [ 'valueC', 'valueD' ] ] */

Debug

Known issues

gotchaBy default, the parser returns an array of string arrays (string[][]). To parse the first row as headers and return an array of objects (Record<string, string>[] or similar), you must explicitly set the `header` option to `true`.

fix

Pass `{ header: true }` in the options object to the `parse` function.

affects: >=1.0.0

gotchaValues in the CSV are treated as strings by default, even if they appear to be numbers, booleans, or nulls. Automatic type inference (to `number`, `boolean`, `null`) only occurs if the `infer` option is explicitly set to `true` or a custom inference function is provided.

fix

To enable automatic type inference, use `{ infer: true }` in the options. For custom logic, provide an `infer` function: `{ infer: (value, x, y, isQuoted) => { /* custom logic */ return value; } }`.

affects: >=1.0.0

gotchaCSV files can use various line endings (CRLF `\r\n` or LF `\n`) and different delimiters (e.g., semicolon `;`) or quote characters (e.g., single quote `'`). The parser defaults to comma `,` and double quote `"` and is generally optimistic about newlines. If your CSV uses non-standard settings, it will misparse the data.

fix

Configure `delimiter` and `quote` options if your CSV differs from the standard: `parse(csv, { delimiter: ';', quote: "'" })`. For strict newline parsing, consider `optimistic: false`.

affects: >=1.0.0

breakingWhile not explicitly documented in the provided README, typical major version bumps (e.g., v1 to v2) in libraries often involve changes in import paths (e.g., switching from CommonJS to ESM only), API signature adjustments, or removal of deprecated options. Always review the full changelog when upgrading major versions.

fix

Consult the official changelog or migration guide on the project's GitHub repository for `csv-simple-parser` to identify any specific breaking changes when upgrading to version 2.x or later.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: csv_simple_parser_1.default is not a function

Attempting to use `require('csv-simple-parser')` and call `parse` directly in a CommonJS context, while the library primarily exposes a default ESM export.

fix

Switch to ESM `import parse from 'csv-simple-parser';` or, if strictly in CommonJS, try `const parse = require('csv-simple-parser').default;` (though direct ESM import is preferred).

TS2339: Property 'MyColumn' does not exist on type 'string[]'.

Trying to access parsed CSV data using object property syntax (e.g., `row.MyColumn`) without enabling header parsing, which means the output type is `string[][]` (array of arrays) instead of `Record<string, string | number | boolean | null>[]` (array of objects).

fix

Ensure the `header` option is set to `true`: `parse(csvString, { header: true })`. This instructs the parser to use the first row as keys for the resulting objects.

All my numbers and booleans are strings, even when `infer: true` is set!

The `infer` option only works on non-quoted values. If numbers or booleans are explicitly quoted in your CSV (e.g., `"123"`, `"true"`), they will still be parsed as strings, as per CSV standard interpretation.

fix

Ensure that numeric, boolean, or null values in your CSV are *not* explicitly quoted if you want the default `infer: true` to convert them. If they must be quoted, provide a custom `infer` function that handles parsing within quoted contexts.

Upgrade

Version history

2.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fabiospampinato/csv-simple-parser ↗

packagehttps://www.npmjs.com/package/csv-simple-parser ↗