select-csv 1.1.20 → 1.1.21

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Housseyn Cheriet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,48 +1,34 @@
-Parse CSV with JavaScript
-========================================
+# select-csv
 
-It is the fastest, simplest and most powerful package of all existing libraries in npmjs. It converts .csv files into an array and even into lines. It contains two important functions parseCsv that handles a csv file, you only need a link to the file. And parseText deals with text, and they both have the same roles and and methods, and it comes with these features:
+The fastest, simplest, and most powerful CSV parser for Node.js. Optimized for high performance and extreme memory efficiency when handling massive datasets (100M+ rows).
 
-- Package with small content (< 30 KB)
-- Easy to use
-- Parse CSV files directly (local)
-- Fast mode
-- Stream large files
-- It is a synchronous package
-- Uses chunks
-- Uses row offset (get rows from line x to line x+n)
-- Returns rows (with columns) or lines (without columns)
-- No external dependencies
-- Flexible with lots of options (header, quote, line break, delimiter, bufferSize in CSV file, Rows in an array or json array)
-- One of the only parsers that correctly handles line-breaks and quotations
+`select-csv` converts `.csv` files into arrays, JSON objects, or raw lines. It provides two main functions, `parseCsv` (for local files) and `parseText` (for raw strings), both sharing the same methods and features.
 
-select-csv has **no dependencies** .
+## ✨ Key Features
+- **Ultra-Lightweight:** Package size is less than 30 KB.
+- **Fast Mode:** Synchronous execution for maximum speed and zero overhead.
+- **Memory Efficient:** Streams large files using chunks and row offsets instead of loading the entire file into RAM.
+- **Robust Parsing:** Correct handling of complex line-breaks (`\r\n`, `\n`) and nested quotations.
+- **No Dependencies:** Zero external dependencies for maximum security and stability.
+- **Flexible Options:** Highly customizable (headers, quotes, delimiters, buffers).
 
-Install:
--------
+---
 
-select-csv is available on [npm](https://www.npmjs.com/package/select-csv). It
-can be installed with the following command:
+## 🚀 Installation
 
-    npm install select-csv
+```bash
+npm install select-csv
+🛠 Usage Examples
+Initialization
+JavaScript
 
+const { parseCsv, parseText } = require("select-csv");
+let parse;
 
-
-Usage:
--------
-
-Here there are clearly different examples
-
-
-```js
-const {parseCsv,parseText} = require("select-csv");
-
-var parse;
-
-// First create object from .csv file
+// 1. Create object from a local .csv file
 parse = parseCsv('file_path.csv');
 
-// Or if you just want create object from text
+// 2. Create object from raw text string
 parse = parseText(
 `Index,User Id,First Name,Last Name,Sex
 1,5f10e9D33fC5f2b,Sara,Mcguire,Female
@@ -56,457 +42,177 @@ parse = parseText(
 9,F563CcbFBfEcf5a,Emma,Robinson,Female
 10,f2dceFc00F62542,Pedro,Cordova,Male`
 );
+Get All Rows
+JavaScript
 
-
-```
-
-* If you want to get just the header :
-```js
-const result = parse.header(); 
+const result = parse.get(); 
 /*
-  ["Index","User Id","First Name","Last Name","Sex"]
-*/
-
-```
-
-* If you want to get all rows :
-```js
-const result = parse.get(); //Return all rows
-/*
-  {
-  time:'1 ms',
-  header:["Index","User Id","First Name","Last Name","Sex"],
-  rows:[
+Returns:
+{
+  time: '1 ms',
+  header: ["Index","User Id","First Name","Last Name","Sex"],
+  rows: [
     ["1","5f10e9D33fC5f2b","Sara","Mcguire","Female"],
     ["2","751cD1cbF77e005","Alisha","Hebert","Male"],
-    ["3","DcEFDB2D2e62bF9","Gwendolyn","Sheppard","Male"],
-    ["4","C88661E02EEDA9e","Kristine","Mccann","Female"],
-    ["5","fafF1aBDebaB2a6","Bobby","Pittman","Female"],
-    ["6","BdDb6C8Af309202","Calvin","Ramsey","Female"],
-    ["7","FCdfFf08196f633","Collin","Allison","Male"],
-    ["8","356279dAa0F7CbD","Nicholas","Branch","Male"],
-    ["9","F563CcbFBfEcf5a","Emma","Robinson","Female"],
-    ["10","f2dceFc00F62542","Pedro","Cordova","Male"]
-    ],
-  row_count:10
-  }
+    ...
+  ],
+  row_count: 10
+}
 */
+Parsing in Chunks
+The chunk(c) method allows you to fetch a specific number of rows. The parser saves the current offset automatically.
 
-```
+JavaScript
 
-* If you want to get a chunks of rows :
+let result;
 
-```js
-var result;
-result = parse.chunk(c) 
-//The 'c' parameter must be an integer and greater than or equal to 1
-
-//Examples:
-result = parse.chunk(2) //Return row 0 and 1 
+// Get rows 0 and 1
+result = parse.chunk(2); 
 /*
 {
-  time: '0 ms',
-  header: [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
-  rows: [
+  "time": "0 ms",
+  "header": [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
+  "rows": [
     [ "1", "5f10e9D33fC5f2b", "Sara", "Mcguire", "Female" ],
     [ "2", "751cD1cbF77e005", "Alisha", "Hebert", "Male" ]
   ],
-  "row_count:": 2
-}
-*/
-
-result = parse.chunk(3) //Return row 2,3 and 4 (Get rows from last offset saved)
-/*
-{
-  time: '0 ms',
-  header: [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
-  rows: [
-    [ "3", "DcEFDB2D2e62bF9", "Gwendolyn", "Sheppard", "Male" ],
-    [ "4", "C88661E02EEDA9e", "Kristine", "Mccann", "Female" ],
-    [ "5", "fafF1aBDebaB2a6", "Bobby", "Pittman", "Female" ]
-  ],
-  "row_count:": 3
-}
-*/
-
-result = parse.chunk(1) //Return row 5 (Get rows from last offset saved)
-/*
-{
-  time: '0 ms',
-  header: [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
-  rows: [
-    [ "6", "BdDb6C8Af309202", "Calvin", "Ramsey", "Female" ]
-  ],
-  "row_count:": 1
+  "row_count": 2
 }
 */
 
+// Get rows 2, 3, and 4 (continues from last offset)
+result = parse.chunk(3); 
 
-```
+// Get row 5
+result = parse.chunk(1); 
+Row Offsets (Specific Range)
+Use rowOffset(from, to) to fetch a specific range of rows.
 
-* If you want to get specific rows :
+JavaScript
 
-```js
-var result
-result = parse.rowOffset(from) 
-// The 'from' parameter must be an integer and greater than or equal to 0
+// Get all rows from the 6th row to the last row
+let result = parse.rowOffset(6); 
 
-// Or
-result = parse.rowOffset(from,to)
-// The 'to' parameter must be an integer and greater than or equal to 1
-
-//Examples:
-result = parse.rowOffset(6) //Returns all rows from the sixth row to the last row
+// Get rows from 5th to 8th row
+result = parse.rowOffset(5, 8); 
 /*
 {
-  time: '0 ms',
-  header: [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
-  rows: [
-    [ "7", "FCdfFf08196f633", "Collin", "Allison", "Male" ],
-    [ "8", "356279dAa0F7CbD", "Nicholas", "Branch", "Male" ],
-    [ "9", "F563CcbFBfEcf5a", "Emma", "Robinson", "Female" ],
-    [ "10", "f2dceFc00F62542", "Pedro", "Cordova", "Male" ]
-  ],
-  "row_count:": 4
-}
-*/
-
-result = parse.rowOffset(5,8) //Returns all rows from 5th to 8th row
-/*
-{
-  time: '1 ms',
-  header: [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
-  rows: [
+  "time": "1 ms",
+  "header": [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
+  "rows": [
     [ "6", "BdDb6C8Af309202", "Calvin", "Ramsey", "Female" ],
     [ "7", "FCdfFf08196f633", "Collin", "Allison", "Male" ],
     [ "8", "356279dAa0F7CbD", "Nicholas", "Branch", "Male" ]
   ],
-  "row_count:": 3
-}
-*/
-
-
-
-```
-
-* If you want to change the row offset :
-
-```js
-parse.setRowOffset(offs) 
-
-// The 'offs' parameter must be an integer and greater than or equal to 0.
-
-// If the offset exists, return [offset,row_number].
-result = parse.setRowOffset(5) 
-/*
-[236,5]
-*/
-result = parse.chunk(1) // Get rows from last offset saved
-/*
-{
-  time: '0 ms',
-  header: [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
-  rows: [
-    [ "6", "BdDb6C8Af309202", "Calvin", "Ramsey", "Female" ]
-  ],
-  "row_count:": 1
-}
-*/
-
-// If not , returns false and the offset not changed.
-result = parse.setRowOffset(20) 
-/*
-false
-*/
-result = parse.chunk(1) // Get rows from last offset saved
-/*
-{
-  time: '0 ms',
-  header: [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
-  rows: [
-    [ "7", "FCdfFf08196f633", "Collin", "Allison", "Male" ]
-  ],
-  "row_count:": 1
+  "row_count": 3
 }
 */
+Manual Offset Control
+You can manually set the row pointer using setRowOffset(offs).
 
+JavaScript
 
-```
-
-* The default object option :
-
-```js
-{
-  'header': true,
-  'quote': false,
-  'linebreak': '\r\n',
-  'delimiter': ",",
-  'json': false,
-  'bufferSize':1024*1024 
-}
-  // delimiter: (String: get rows containing columns, false: get lines without columns)
-  //bufferSize: It only works with a CSV file, which is the maximum number of characters that can be read at a time, the minimum value is 1024
-```
-
-* If you want to use specific option :
-```js
-var option = {
-  'header': false,    /* or true */
-  'quote': true,      /* or false */
-  'linebreak': '\n',  /* '\n' or '\r' or any other string  */
-  'delimiter': ","    /* ';' or any other string or false */
-  'json': false       /* or true */
-  'bufferSize':2000   /* It only works with a CSV file */
-}
-
-var parse;
-// Create object from .csv file
-parse = parseCsv('file_path.csv',option);
+// If offset exists, returns [byte_offset, row_number]
+let status = parse.setRowOffset(5); // [236, 5]
 
-// Or if you just want create object from text
-parse = parseText(
-`Index,User Id,First Name,Last Name,Sex
-1,5f10e9D33fC5f2b,Sara,Mcguire,Female
-2,751cD1cbF77e005,Alisha,Hebert,Male
-3,DcEFDB2D2e62bF9,Gwendolyn,Sheppard,Male`
-, option);
+// Get row 6 after setting offset
+let nextRow = parse.chunk(1); 
 
+// Returns false if row number does not exist
+let fail = parse.setRowOffset(20); // false
+⚙️ Configuration Options
+The default configuration is:
 
-result = parse.rowOffset(2)
-/*
-{
-  time: '0 ms',
-  header: false,
-  rows: [
-    [ "2", "751cD1cbF77e005", "Alisha", "Hebert", "Male" ]
-  ],
-  "row_count:": 1
-}
-*/
+JavaScript
 
-option = { 
-  'header': true,
-  'delimiter': false 
-}
-  // delimiter: (String: get rows containing columns, false: get lines without columns)
-/*
 {
-  time: '0 ms',
-  header: false,
-  rows: [
-    [ "2,751cD1cbF77e005,Alisha,Hebert,Male" ] // No columns, just string (all line)
-  ],
-  "row_count:": 1
+  'header': true,     // Treat first row as header
+  'quote': false,      // Handle quoted values
+  'linebreak': '\r\n', // Custom line break
+  'delimiter': ",",    // Column separator (set to false for raw lines)
+  'json': false,       // Return rows as JSON objects (requires header: true)
+  'bufferSize': 1048576 // 1MB buffer (for parseCsv only)
 }
-*/
+Custom Options Example:
+JavaScript
 
-```
-
-* If you want to reset option after multiple uses of your code :
-```js
-const option = {       // Just an exapmle
+let option = {
   'header': false,
   'quote': true,
-  'linebreak': '\n'
-}
-
-parse.resetOption(option); // All saved values are erased and the object is restared again
-
-
-```
+  'linebreak': '\n',
+  'delimiter': ",",
+  'json': false,
+  'bufferSize': 2000
+};
 
-* If you want to rows as json array :
-```js
-// 'header' and 'json' must be true if you want to get rows as a json array
-const option = {       
-  'header': true, 
-  'json': true
-}
+parse = parseCsv('data.csv', option);
+Working with JSON Output:
+If you want the result as an array of objects based on the header:
 
+JavaScript
 
-const result = parse.chunk(3)
+const parse = parseCsv('data.csv', { 'header': true, 'json': true });
+const result = parse.get();
 /*
-{
-  time: '0 ms',
-  header: [ 'Index', 'User Id', 'First Name', 'Last Name', 'Sex' ],
-  rows: [
-    {
-      Index: '1',
-      'User Id': '5f10e9D33fC5f2b',
-      'First Name': 'Sara',
-      'Last Name': 'Mcguire',
-      Sex: 'Female'
-    },
-    {
-      Index: '2',
-      'User Id': '751cD1cbF77e005',
-      'First Name': 'Alisha',
-      'Last Name': 'Hebert',
-      Sex: 'Male'
-    },
-    {
-      Index: '3',
-      'User Id': 'DcEFDB2D2e62bF9',
-      'First Name': 'Gwendolyn',
-      'Last Name': 'Sheppard',
-      Sex: 'Male'
-    }
-  ],
-  row_count: 3
-}
+rows: [
+  { "Index": "1", "User Id": "5f10e9D33fC5f2b", "First Name": "Sara", ... },
+  ...
+]
 */
+Raw Lines (No Delimiter):
+If delimiter is set to false, the parser returns full lines as strings.
 
+JavaScript
 
-```
+parse.resetOption({ 'header': true, 'delimiter': false });
+let result = parse.rowOffset(2);
+// rows: [ ["2,751cD1cbF77e005,Alisha,Hebert,Male"] ]
+📊 Benchmarking Large Files
+Tested with a 100 Million Row Dataset:
 
-* If you want to get information of your object :
-```js
+JavaScript
 
-const result = parse.getInfo();
-/*
-{
-  "offset": 275,
-  "rowOffset": 7,
-  "option": {
-    "header": false,
-    "quote": false,
-    "linebreak": "\n",
-    "delimiter": false
-  }
-}
-*/
+const parse = parseCsv('huge-data.csv', {"header": false});
 
-```
+// Fetch 100,000 rows
+let result = parse.chunk(100000); // ~222ms
 
-* Examples of parsing a large CSV file:
-(https://www.kaggle.com/datasets/zanjibar/100-million-data-csv)
+// Jump to row 30,000,000
+result = parse.rowOffset(30000000, 30000005); // ~3743ms
 
+// Jump to row 90,000,000
+result = parse.rowOffset(90000000, 90000004); // ~44126ms
 
-```js
-
-const parse = parseCsv('100-million-data.csv',{"header": false});
-var result;
-result = parse.chunk(100000)
+// Current metadata
+console.log(parse.getInfo());
 /*
 {
-  time: '222 ms',
-  header: false,
-  rows: [
-    [ '198801', '1', '103', '100', '000000190', '0', '35843', '34353' ],
-    [ '198801', '1', '103', '100', '120991000', '0', '1590', '4154' ],
-    [ '198801', '1', '103', '100', '210390900', '0', '4500', '2565' ],
-    .
-    .
-    .
-    [ '198801', '1', '103', '100', '391590000', '0', '95000', '7850' ],
-    [ '198801', '1', '103', '100', '391620000', '0', '1000', '404' ],
-    [ '198801', '1', '103', '100', '391723000', '0', '545', '479' ],
-    [ '198801', '1', '103', '100', '391732100', '0', '24', '393' ],
-    [ '198801', '1', '103', '100', '391732900', '0', '60', '758' ],
-    [ '198801', '1', '103', '100', '391810100', '0', '1935', '1042' ],
-    [ '198801', '1', '103', '100', '391910200', '0', '510', '1303' ],
-    [ '198801', '1', '103', '100', '391910300', '0', '133', '379' ],
-    [ '198801', '1', '103', '100', '391990300', '0', '450', '1668' ],
-    [ '198801', '1', '103', '100', '391990500', '0', '942', '1721' ],
-    [ '198801', '1', '103', '100', '391990900', '0', '40', '235' ],
-    [ '198801', '1', '103', '100', '392030000', '0', '406', '652' ],
-    ... 99900 more items
-  ],
-  row_count: 100000
-}
-*/
-
-result = parse.chunk(3) // Return row 100001,100002 and 100003 (Get rows from last offset saved)
-/*
-{
-  time: '1 ms',
-  header: false,
-  rows: [
-    [ '198801', '1', '326', '500', '841330000', '90', '81', '246' ],
-    [ '198801', '1', '326', '500', '841510000', '0', '35', '1366' ],
-    [ '198801', '1', '326', '500', '841582100', '0', '6', '334' ]
-  ],
-  row_count: 3
-}
-*/
-
-const from = 1000*1000*30;
-const to = from + 5;
-result = parse.rowOffset(from,to)
-/*
-{
-  time: '3743 ms',
-  header: false,
-  rows: [
-    [
-      '199804',    '2',
-      '213',       '502',
-      '848130000', '16035',
-      '746',       '8380'
-    ],
-    [ '199804', '2', '213', '502', '848140000', '168', '152', '1891' ],
-    [ '199804', '2', '213', '502', '848180010', '77', '404', '1366' ],
-    [ '199804', '2', '213', '502', '848190000', '0', '131', '570' ],
-    [ '199804', '2', '213', '502', '848230000', '300', '4', '882' ]
-  ],
-  row_count: 5
+  offset: 3599945660,
+  rowOffset: 90000008,
+  option: { ... }
 }
 */
+🧪 Advanced Methods
+getInfo()
+Returns current byte offset, row offset, and active options.
 
-const from = 1000*1000*90;
-const to = from + 4;
-result = parse.rowOffset(from,to)
-/*
-{
-  time: '44126 ms',
-  header: false,
-  rows: [
-    [ '201412', '1', '125', '400', '283525000', '0', '160000', '6492' ],
-    [ '201412', '1', '125', '400', '390740100', '0', '17500', '5579' ],
-    [ '201412', '1', '125', '400', '390950000', '0', '36000', '21423' ],
-    [ '201412', '1', '125', '400', '392329000', '0', '520', '1413' ]
-  ],
-  row_count: 4
-}
-*/
+JavaScript
 
-result = parse.chunk(3) // Get rows from last offset saved ( row to,to+1 and to+2 )
-/*
-{
-  time: '29 ms',
-  header: false,
-  rows: [
-    [ '201412', '1', '125', '400', '400932000', '0', '18', '526' ],
-    [ '201412', '1', '125', '400', '401110000', '173', '1735', '1197' ],
-    [ '201412', '1', '125', '400', '401120000', '133', '1707', '1099' ]
-  ],
-  row_count: 3
-}
-*/
+const info = parse.getInfo();
+resetOption(newOptions)
+Clears internal state and re-initializes the parser with new settings.
 
-result = parse.getInfo() // Get all the information
-/*
-{
-  offset: 3599945660,
-  rowOffset: 90000008,
-  option: {
-    header: false,
-    quote: false,
-    linebreak: '\r\n',
-    delimiter: ',',
-    bufferSize: 1048576
-  }
-}
-*/
-```
+JavaScript
 
-## Request Features or Report Bugs
+parse.resetOption({ 'header': false, 'quote': true });
+header()
+Returns the detected CSV header array.
 
-Feature requests and bug reports are very welcome: https://github.com/housseynCheriet/select-csv/issues
+JavaScript
 
-A couple of requests from me when you raise an issue on GitHub.
+const headers = parse.header();
+🤝 Contributing
+Found a bug or have a suggestion? Open an issue at GitHub Issues.
 
-* **Requesting a feature:** Please try to provide the context of why you want the feature. Such as,
-  in what situation the feature could help you and how, or how the lack of the feature is causing an inconvenience to you.
-  I can't start thinking of introducing it until I understand how it helps you 🙂
-* **Reporting a bug:** If you could provide a runnable code snippet that reproduces the bug, it would be very helpful!
+📄 License
+This project is licensed under the MIT License.