{"id":13028,"library":"csv-simple-parser","title":"CSV Simple Parser","description":"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.","status":"active","version":"2.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/fabiospampinato/csv-simple-parser","tags":["javascript","csv","fast","parser","typescript"],"install":[{"cmd":"npm install csv-simple-parser","lang":"bash","label":"npm"},{"cmd":"yarn add csv-simple-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add csv-simple-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const parse = require('csv-simple-parser');","symbol":"parse","correct":"import parse from 'csv-simple-parser';"},{"note":"When using TypeScript, import the `Options` type to strongly type the configuration object for the parser.","symbol":"Options","correct":"import type { Options } from 'csv-simple-parser';"},{"note":"For advanced type inference scenarios, import the `CustomInferer` type to correctly type your custom infer function.","symbol":"CustomInferer","correct":"import type { CustomInferer } from 'csv-simple-parser';"}],"quickstart":{"code":"import parse from 'csv-simple-parser';\n\n// Example 1: Parse CSV with headers and automatic type inference\nconst csvDataWithTypes = 'Name,Age,Active,Balance\\n\"Alice\",30,true,100.50\\n\"Bob\",24,false,200.00\\n\"Charlie\",NULL,true,null';\nconst parsedObjects = parse(csvDataWithTypes, { header: true, infer: true });\nconsole.log('Parsed with inference:', parsedObjects);\n/*\nOutput:\n[\n  { Name: 'Alice', Age: 30, Active: true, Balance: 100.5 },\n  { Name: 'Bob', Age: 24, Active: false, Balance: 200 },\n  { Name: 'Charlie', Age: null, Active: true, Balance: null }\n]\n*/\n\n// Example 2: Parse CSV with custom delimiter and explicit type inference function\nconst customCsv = 'ID|Product|Price\\n101|\"Laptop\"|1200.00\\n102|\"Mouse\"|25.50';\nconst customInferFn = (value, x, y, isExplicitlyQuoted) => {\n  if (y === 2) return parseFloat(value);\n  return value;\n};\nconst parsedCustom = parse(customCsv, { header: true, delimiter: '|', infer: customInferFn });\nconsole.log('\\nParsed with custom delimiter & infer:', parsedCustom);\n/*\nOutput:\n[\n  { ID: '101', Product: 'Laptop', Price: 1200 },\n  { ID: '102', Product: 'Mouse', Price: 25.5 }\n]\n*/\n\n// Example 3: Parse CSV without headers, returning array of arrays\nconst simpleCsv = 'Header1,Header2\\nvalueA,valueB\\nvalueC,valueD';\nconst parsedArray = parse(simpleCsv);\nconsole.log('\\nParsed as array of arrays:', parsedArray);\n/*\nOutput:\n[\n  [ 'Header1', 'Header2' ],\n  [ 'valueA', 'valueB' ],\n  [ 'valueC', 'valueD' ]\n]\n*/","lang":"typescript","description":"Demonstrates parsing CSV strings into objects with header and type inference, using custom delimiters, and also parsing into arrays of arrays."},"warnings":[{"fix":"Pass `{ header: true }` in the options object to the `parse` function.","message":"By 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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"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; } }`.","message":"Values 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Configure `delimiter` and `quote` options if your CSV differs from the standard: `parse(csv, { delimiter: ';', quote: \"'\" })`. For strict newline parsing, consider `optimistic: false`.","message":"CSV 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"While 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.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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).","cause":"Attempting to use `require('csv-simple-parser')` and call `parse` directly in a CommonJS context, while the library primarily exposes a default ESM export.","error":"TypeError: csv_simple_parser_1.default is not a function"},{"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.","cause":"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).","error":"TS2339: Property 'MyColumn' does not exist on type 'string[]'."},{"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.","cause":"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.","error":"All my numbers and booleans are strings, even when `infer: true` is set!"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}