select-csv 1.1.21 → 1.1.22

package/README.md

@@ -4,7 +4,7 @@ The fastest, simplest, and most powerful CSV parser for Node.js. Optimized for h
 
 `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.
 
-## ✨ Key Features
+##  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.
@@ -14,21 +14,32 @@ The fastest, simplest, and most powerful CSV parser for Node.js. Optimized for h
 
 ---
 
-## 🚀 Installation
 
-```bash
-npm install select-csv
-🛠 Usage Examples
-Initialization
-JavaScript
+Install:
+-------
 
-const { parseCsv, parseText } = require("select-csv");
-let parse;
+select-csv is available on [npm](https://www.npmjs.com/package/select-csv). It
+can be installed with the following command:
 
-// 1. Create object from a local .csv file
+    npm install select-csv
+
+
+
+Usage:
+-------
+
+Here there are clearly different examples
+
+
+```js
+const {parseCsv,parseText} = require("select-csv");
+
+var parse;
+
+// First create object from .csv file
 parse = parseCsv('file_path.csv');
 
-// 2. Create object from raw text string
+// Or if you just want create object from text
 parse = parseText(
 `Index,User Id,First Name,Last Name,Sex
 1,5f10e9D33fC5f2b,Sara,Mcguire,Female
@@ -42,177 +53,398 @@ parse = parseText(
 9,F563CcbFBfEcf5a,Emma,Robinson,Female
 10,f2dceFc00F62542,Pedro,Cordova,Male`
 );
-Get All Rows
-JavaScript
 
-const result = parse.get(); 
+
+```
+
+* If you want to get all rows :
+```js
+const result = parse.get(); //Return all 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"],
-    ...
-  ],
-  row_count: 10
-}
+	{
+	time:1,
+	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
+	}
 */
-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
 
-// Get rows 0 and 1
-result = parse.chunk(2); 
+//Examples:
+result = parse.chunk(2) //Return row 0 and 1 
 /*
 {
-  "time": "0 ms",
-  "header": [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
-  "rows": [
+  "Time": 0,
+  "Header": [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
+  "Rows": [
     [ "1", "5f10e9D33fC5f2b", "Sara", "Mcguire", "Female" ],
     [ "2", "751cD1cbF77e005", "Alisha", "Hebert", "Male" ]
   ],
-  "row_count": 2
+  "row_count:": 2
 }
 */
 
-// Get rows 2, 3, and 4 (continues from last offset)
-result = parse.chunk(3); 
+result = parse.chunk(3) //Return row 2,3 and 4 (Get rows from last offset saved)
+/*
+{
+  "Time": 0,
+  "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,
+  "Header": [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
+  "Rows": [
+    [ "6", "BdDb6C8Af309202", "Calvin", "Ramsey", "Female" ]
+  ],
+  "row_count:": 1
+}
+*/
+
+
+```
+
+* If you want to get specific rows :
 
-// Get row 5
-result = parse.chunk(1); 
-Row Offsets (Specific Range)
-Use rowOffset(from, to) to fetch a specific range of rows.
+```js
+var result
+result = parse.rowOffset(from) 
+// The 'from' parameter must be an integer and greater than or equal to 0
 
-JavaScript
+// Or
+result = parse.rowOffset(from,to)
+// The 'to' parameter must be an integer and greater than or equal to 1
 
-// Get all rows from the 6th row to the last row
-let result = parse.rowOffset(6); 
+//Examples:
+result = parse.rowOffset(6) //Returns all rows from the sixth row to the last row
+/*
+{
+  "Time": 0,
+  "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
+}
+*/
 
-// Get rows from 5th to 8th row
-result = parse.rowOffset(5, 8); 
+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,
+  "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
+  "row_count:": 3
 }
 */
-Manual Offset Control
-You can manually set the row pointer using setRowOffset(offs).
 
-JavaScript
 
-// If offset exists, returns [byte_offset, row_number]
-let status = parse.setRowOffset(5); // [236, 5]
 
-// 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:
+* If you want to change the row offset :
 
-JavaScript
+```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
+/*
 {
-  '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)
+  "Time": 0,
+  "Header": [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
+  "Rows": [
+    [ "6", "BdDb6C8Af309202", "Calvin", "Ramsey", "Female" ]
+  ],
+  "row_count:": 1
 }
-Custom Options Example:
-JavaScript
+*/
 
-let option = {
-  'header': false,
-  'quote': true,
-  'linebreak': '\n',
-  'delimiter': ",",
-  'json': false,
-  'bufferSize': 2000
-};
+// 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,
+  "Header": [ "Index", "User Id", "First Name", "Last Name", "Sex" ],
+  "Rows": [
+    [ "7", "FCdfFf08196f633", "Collin", "Allison", "Male" ]
+  ],
+  "row_count:": 1
+}
+*/
+
+
+```
+
+* The default object option :
 
-parse = parseCsv('data.csv', option);
-Working with JSON Output:
-If you want the result as an array of objects based on the header:
+```js
+{
+	'header': true,
+	'quote': false,
+	'linebreak': '\r\n',
+	'delimiter': ",",
+  '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 */
+  'bufferSize':2000 /* It only works with a CSV file */
+}
 
-JavaScript
+var parse;
+// Create object from .csv file
+parse = parseCsv('file_path.csv',option);
 
-const parse = parseCsv('data.csv', { 'header': true, 'json': true });
-const result = parse.get();
+// 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);
+
+option = {
+	'header': false,
+}
+
+result = parse.rowOffset(2)
 /*
-rows: [
-  { "Index": "1", "User Id": "5f10e9D33fC5f2b", "First Name": "Sara", ... },
-  ...
-]
+{
+  "Time": 0,
+  "Header": false,
+  "Rows": [
+    [ "2", "751cD1cbF77e005", "Alisha", "Hebert", "Male" ]
+  ],
+  "row_count:": 1
+}
 */
-Raw Lines (No Delimiter):
-If delimiter is set to false, the parser returns full lines as strings.
 
-JavaScript
+option = { 
+	'header': true,
+	'delimiter': false 
+}
+	// delimiter: (String: get rows containing columns, false: get lines without columns)
+/*
+{
+  "Time": 0,
+  "Header": false,
+  "Rows": [
+    [ "2,751cD1cbF77e005,Alisha,Hebert,Male" ] // No columns, just string (all line)
+  ],
+  "row_count:": 1
+}
+*/
 
-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:
+```
 
-JavaScript
+* If you want to reset option after multiple uses of your code :
+```js
+const option = {       // Just an exapmle
+	'header': false,
+	'quote': true,
+	'linebreak': '\n'
+}
 
-const parse = parseCsv('huge-data.csv', {"header": false});
+parse.resetOption(option); // All saved values are erased and the object is restared again
 
-// Fetch 100,000 rows
-let result = parse.chunk(100000); // ~222ms
 
-// Jump to row 30,000,000
-result = parse.rowOffset(30000000, 30000005); // ~3743ms
+```
 
-// Jump to row 90,000,000
-result = parse.rowOffset(90000000, 90000004); // ~44126ms
+* If you want to get information of your object :
+```js
 
-// Current metadata
-console.log(parse.getInfo());
+const result = parse.getInfo();
 /*
 {
-  offset: 3599945660,
-  rowOffset: 90000008,
-  option: { ... }
+  "offset": 275,
+  "rowOffset": 7,
+  "option": {
+    "header": false,
+    "quote": false,
+    "linebreak": "\n",
+    "delimiter": false
+  }
 }
 */
-🧪 Advanced Methods
-getInfo()
-Returns current byte offset, row offset, and active options.
 
-JavaScript
+```
+
+* Examples of parsing a large CSV file:
+(https://www.kaggle.com/datasets/zanjibar/100-million-data-csv)
 
-const info = parse.getInfo();
-resetOption(newOptions)
-Clears internal state and re-initializes the parser with new settings.
 
-JavaScript
+```js
 
-parse.resetOption({ 'header': false, 'quote': true });
-header()
-Returns the detected CSV header array.
+const parse = parseCsv('100-million-data.csv',{"header": false});
+var result;
+result = parse.chunk(100000)
+/*
+{
+  time: 222,
+  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
+}
+*/
 
-JavaScript
+result = parse.chunk(3) // Return row 100001,100002 and 100003 (Get rows from last offset saved)
+/*
+{
+  time: 1,
+  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,
+  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
+}
+*/
+
+const from = 1000*1000*90;
+const to = from + 4;
+result = parse.rowOffset(from,to)
+/*
+{
+  time: 44126,
+  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
+}
+*/
+
+result = parse.chunk(3) // Get rows from last offset saved ( row to,to+1 and to+2 )
+/*
+{
+  time: 29,
+  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
+}
+*/
+
+result = parse.getInfo() // Get all the information
+/*
+{
+  offset: 3599945660,
+  rowOffset: 90000008,
+  option: {
+    header: false,
+    quote: false,
+    linebreak: '\r\n',
+    delimiter: ',',
+    bufferSize: 1048576
+  }
+}
+*/
+```
 
-const headers = parse.header();
-🤝 Contributing
-Found a bug or have a suggestion? Open an issue at GitHub Issues.
+## 📄 License
 
-📄 License
-This project is licensed under the MIT License.
+MIT License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "select-csv",
-  "version": "1.1.21",
+  "version": "1.1.22",
   "description": "A high-performance, memory-efficient CSV parser for Node.js. Supports streaming large files via chunks and row offsets with zero dependencies.",
   "keywords": [
     "csv",