convert-csv-to-json 4.2.0 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (60) hide show
  1. package/.eslintignore +3 -0
  2. package/.eslintrc.json +48 -0
  3. package/.github/workflows/ci-cd.yml +28 -2
  4. package/docs/api/BrowserApi.html +2435 -0
  5. package/docs/api/BrowserApiError.html +522 -0
  6. package/docs/api/ConfigurationError.html +594 -0
  7. package/docs/api/CsvFormatError.html +530 -0
  8. package/docs/api/CsvParsingError.html +384 -0
  9. package/docs/api/CsvToJson.html +3136 -0
  10. package/docs/api/CsvToJsonAsync.html +2672 -0
  11. package/docs/api/FileOperationError.html +270 -0
  12. package/docs/api/FileUtils.html +1012 -0
  13. package/docs/api/InputValidationError.html +293 -0
  14. package/docs/api/JsonUtil.html +340 -0
  15. package/docs/api/JsonValidationError.html +247 -0
  16. package/docs/api/fonts/OpenSans-Bold-webfont.eot +0 -0
  17. package/docs/api/fonts/OpenSans-Bold-webfont.svg +1830 -0
  18. package/docs/api/fonts/OpenSans-Bold-webfont.woff +0 -0
  19. package/docs/api/fonts/OpenSans-BoldItalic-webfont.eot +0 -0
  20. package/docs/api/fonts/OpenSans-BoldItalic-webfont.svg +1830 -0
  21. package/docs/api/fonts/OpenSans-BoldItalic-webfont.woff +0 -0
  22. package/docs/api/fonts/OpenSans-Italic-webfont.eot +0 -0
  23. package/docs/api/fonts/OpenSans-Italic-webfont.svg +1830 -0
  24. package/docs/api/fonts/OpenSans-Italic-webfont.woff +0 -0
  25. package/docs/api/fonts/OpenSans-Light-webfont.eot +0 -0
  26. package/docs/api/fonts/OpenSans-Light-webfont.svg +1831 -0
  27. package/docs/api/fonts/OpenSans-Light-webfont.woff +0 -0
  28. package/docs/api/fonts/OpenSans-LightItalic-webfont.eot +0 -0
  29. package/docs/api/fonts/OpenSans-LightItalic-webfont.svg +1835 -0
  30. package/docs/api/fonts/OpenSans-LightItalic-webfont.woff +0 -0
  31. package/docs/api/fonts/OpenSans-Regular-webfont.eot +0 -0
  32. package/docs/api/fonts/OpenSans-Regular-webfont.svg +1831 -0
  33. package/docs/api/fonts/OpenSans-Regular-webfont.woff +0 -0
  34. package/docs/api/global.html +3315 -0
  35. package/docs/api/index.html +326 -0
  36. package/docs/api/index.js.html +341 -0
  37. package/docs/api/scripts/linenumber.js +25 -0
  38. package/docs/api/scripts/prettify/Apache-License-2.0.txt +202 -0
  39. package/docs/api/scripts/prettify/lang-css.js +2 -0
  40. package/docs/api/scripts/prettify/prettify.js +28 -0
  41. package/docs/api/src_browserApi.js.html +271 -0
  42. package/docs/api/src_csvToJson.js.html +605 -0
  43. package/docs/api/src_csvToJsonAsync.js.html +244 -0
  44. package/docs/api/src_util_errors.js.html +374 -0
  45. package/docs/api/src_util_fileUtils.js.html +147 -0
  46. package/docs/api/src_util_jsonUtils.js.html +75 -0
  47. package/docs/api/src_util_stringUtils.js.html +212 -0
  48. package/docs/api/styles/jsdoc-default.css +358 -0
  49. package/docs/api/styles/prettify-jsdoc.css +111 -0
  50. package/docs/api/styles/prettify-tomorrow.css +132 -0
  51. package/index.js +109 -32
  52. package/jsdoc.json +17 -0
  53. package/package.json +10 -3
  54. package/src/browserApi.js +96 -4
  55. package/src/csvToJson.js +163 -2
  56. package/src/csvToJsonAsync.js +74 -14
  57. package/src/util/errors.js +96 -0
  58. package/src/util/fileUtils.js +34 -0
  59. package/src/util/jsonUtils.js +8 -0
  60. package/src/util/stringUtils.js +51 -0
package/docs/api/index.html ADDED
@@ -0,0 +1,326 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>JSDoc: Home</title>
6
+
7
+ <script src="scripts/prettify/prettify.js"> </script>
8
+ <script src="scripts/prettify/lang-css.js"> </script>
9
+ <!--[if lt IE 9]>
10
+ <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
11
+ <![endif]-->
12
+ <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
13
+ <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
14
+ </head>
15
+
16
+ <body>
17
+
18
+ <div id="main">
19
+
20
+ <h1 class="page-title">Home</h1>
21
+
22
+
23
+
24
+
25
+
26
+
27
+
28
+
29
+ <h3> </h3>
30
+
31
+
32
+
33
+
34
+
35
+
36
+
37
+
38
+
39
+
40
+
41
+
42
+
43
+
44
+
45
+ <section>
46
+ <article><h1>CSVtoJSON</h1>
47
+ <p><a href="https://github.com/iuccio/csvToJson/actions/workflows/ci-cd.yml"><img src="https://github.com/iuccio/csvToJson/actions/workflows/ci-cd.yml/badge.svg?branch=master" alt="Node CI"></a>
48
+ <img src="https://github.com/iuccio/csvToJson/actions/workflows/codeql-analysis.yml/badge.svg" alt="CodeQL">
49
+ <a href="https://snyk.io/test/github/iuccio/csvToJson"><img src="https://snyk.io/test/github/iuccio/csvToJson/badge.svg" alt="Known Vulnerabilities"></a>
50
+ <a href="https://codeclimate.com/github/iuccio/csvToJson"><img src="https://codeclimate.com/github/iuccio/csvToJson/badges/gpa.svg" alt="Code Climate"></a>
51
+ <a href="https://npmjs.org/package/convert-csv-to-json"><img src="https://img.shields.io/npm/v/convert-csv-to-json.svg" alt="NPM Version"></a>
52
+ <img src="https://img.shields.io/badge/nodeJS-%3E=18.x-brightgreen.svg" alt="NodeJS Version">
53
+ <a href="https://npmjs.org/package/convert-csv-to-json"><img src="https://img.shields.io/npm/dm/convert-csv-to-json.svg" alt="Downloads"></a>
54
+ <a href="https://npmjs.org/package/convert-csv-to-json"><img src="https://img.shields.io/npm/dt/convert-csv-to-json.svg?style=flat" alt="NPM total downloads"></a>
55
+ <a href="https://socket.dev/npm/package/convert-csv-to-json"><img src="https://badge.socket.dev/npm/package/convert-csv-to-json/3.20.0" alt="Socket Badge"></a></p>
56
+ <p><img src="https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&amp;logo=node.js&amp;logoColor=white" alt="NodeJS">
57
+ <img src="https://img.shields.io/badge/browser-supported-brightgreen.svg?style=for-the-badge&amp;logo=google-chrome&amp;logoColor=white" alt="Browser Support">
58
+ <img src="https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge&amp;logo=javascript&amp;logoColor=%23F7DF1E" alt="JavaScript">
59
+ <img src="https://img.shields.io/badge/typescript-%23007ACC.svg?style=for-the-badge&amp;logo=typescript&amp;logoColor=white" alt="TypeScript"></p>
60
+ <blockquote></blockquote>
61
+ <p>Convert CSV files to JSON with <strong>no dependencies</strong>. Supports Node.js (Sync &amp; Async), and Browser environments with full RFC 4180 compliance.</p>
62
+ <h2>Overview</h2>
63
+ <p>Transform CSV data into JSON with a simple, chainable API. Choose your implementation style:</p>
64
+ <ul>
65
+ <li><strong><a href="docs/SYNC.md">Synchronous API</a></strong> - Blocking operations for simple workflows</li>
66
+ <li><strong><a href="docs/ASYNC.md">Asynchronous API</a></strong> - Promise-based for modern async/await patterns</li>
67
+ <li><strong><a href="docs/BROWSER.md">Browser API</a></strong> - Client-side CSV parsing for web applications</li>
68
+ </ul>
69
+ <h2>Features</h2>
70
+ <p>✅ <strong>RFC 4180 Compliant</strong> - Proper handling of quoted fields, delimiters, newlines, and escape sequences<br>
71
+ ✅ <strong>Zero Dependencies</strong> - No external packages required<br>
72
+ ✅ <strong>Full TypeScript Support</strong> - Included type definitions for all APIs<br>
73
+ ✅ <strong>Flexible Configuration</strong> - Custom delimiters, encoding, trimming, and more<br>
74
+ ✅ <strong>Method Chaining</strong> - Fluent API for readable code<br>
75
+ ✅ <strong>Large File Support</strong> - Stream processing for memory-efficient handling<br>
76
+ ✅ <strong>Comprehensive Error Handling</strong> - Detailed, actionable error messages with solutions (see <a href="docs/ERROR_HANDLING.md">ERROR_HANDLING.md</a>)</p>
77
+ <h2>RFC 4180 Standard</h2>
78
+ <p><strong><a href="https://datatracker.ietf.org/doc/html/rfc4180">RFC 4180</a></strong> is the IETF standard specification for CSV (Comma-Separated Values) files. This library is fully compliant with RFC 4180, ensuring proper handling of:</p>
79
+ <table>
80
+ <thead>
81
+ <tr>
82
+ <th>Aspect</th>
83
+ <th>RFC 4180 Specification</th>
84
+ </tr>
85
+ </thead>
86
+ <tbody>
87
+ <tr>
88
+ <td><strong>Default Delimiter</strong></td>
89
+ <td>Comma (<code>,</code>)</td>
90
+ </tr>
91
+ <tr>
92
+ <td><strong>Record Delimiter</strong></td>
93
+ <td>CRLF (<code>\r\n</code>) or LF (<code>\n</code>)</td>
94
+ </tr>
95
+ <tr>
96
+ <td><strong>Quote Character</strong></td>
97
+ <td>Double-quote (<code>&quot;</code>)</td>
98
+ </tr>
99
+ <tr>
100
+ <td><strong>Quote Escaping</strong></td>
101
+ <td>Double quotes (<code>&quot;&quot;</code>)</td>
102
+ </tr>
103
+ </tbody>
104
+ </table>
105
+ <h3>RFC 4180 Example</h3>
106
+ <pre class="prettyprint source lang-csv"><code>firstName,lastName,email
107
+ &quot;Smith, John&quot;,Smith,john@example.com
108
+ Jane,Doe,jane@example.com
109
+ &quot;Cooper, Andy&quot;,Cooper,andy@company.com
110
+ </code></pre>
111
+ <p>Note the quoted fields containing commas are properly handled. See <a href="RFC4180_MIGRATION_GUIDE.md">RFC4180_MIGRATION_GUIDE.md</a> for breaking changes and migration details.</p>
112
+ <h2>Quick Start</h2>
113
+ <h3>Installation</h3>
114
+ <pre class="prettyprint source lang-bash"><code>npm install convert-csv-to-json
115
+ </code></pre>
116
+ <h3>Synchronous (Simple)</h3>
117
+ <pre class="prettyprint source lang-js"><code>const csvToJson = require('convert-csv-to-json');
118
+ const json = csvToJson.getJsonFromCsv('input.csv');
119
+ </code></pre>
120
+ <h3>Asynchronous (Modern)</h3>
121
+ <pre class="prettyprint source lang-js"><code>const csvToJson = require('convert-csv-to-json');
122
+ const json = await csvToJson.getJsonFromCsvAsync('input.csv');
123
+ </code></pre>
124
+ <h3>Browser</h3>
125
+ <pre class="prettyprint source lang-js"><code>const convert = require('convert-csv-to-json');
126
+ const json = await convert.browser.parseFile(file);
127
+ </code></pre>
128
+ <h2>Documentation</h2>
129
+ <table>
130
+ <thead>
131
+ <tr>
132
+ <th>Implementation</th>
133
+ <th>Use Case</th>
134
+ <th>Learn More</th>
135
+ </tr>
136
+ </thead>
137
+ <tbody>
138
+ <tr>
139
+ <td><strong>Sync API</strong></td>
140
+ <td>Simple, blocking operations</td>
141
+ <td><a href="docs/SYNC.md">Read SYNC.md</a></td>
142
+ </tr>
143
+ <tr>
144
+ <td><strong>Async API</strong></td>
145
+ <td>Concurrent operations, large files</td>
146
+ <td><a href="docs/ASYNC.md">Read ASYNC.md</a></td>
147
+ </tr>
148
+ <tr>
149
+ <td><strong>Browser API</strong></td>
150
+ <td>Client-side file parsing</td>
151
+ <td><a href="docs/BROWSER.md">Read BROWSER.md</a></td>
152
+ </tr>
153
+ </tbody>
154
+ </table>
155
+ <h2>Common Tasks</h2>
156
+ <h3>Parse CSV String</h3>
157
+ <pre class="prettyprint source lang-js"><code>const json = csvToJson.csvStringToJson('name,age\nAlice,30');
158
+ </code></pre>
159
+ <h3>Custom Delimiter</h3>
160
+ <pre class="prettyprint source lang-js"><code>const json = csvToJson
161
+ .fieldDelimiter(';')
162
+ .getJsonFromCsv('input.csv');
163
+ </code></pre>
164
+ <h3>Format Values</h3>
165
+ <pre class="prettyprint source lang-js"><code>const json = csvToJson
166
+ .formatValueByType()
167
+ .getJsonFromCsv('input.csv');
168
+ // Converts &quot;30&quot; → 30, &quot;true&quot; → true, etc.
169
+ </code></pre>
170
+ <h3>Handle Quoted Fields</h3>
171
+ <pre class="prettyprint source lang-js"><code>const json = csvToJson
172
+ .supportQuotedField(true)
173
+ .getJsonFromCsv('input.csv');
174
+ </code></pre>
175
+ <h3>Batch Process Files (Async)</h3>
176
+ <pre class="prettyprint source lang-js"><code>const files = ['file1.csv', 'file2.csv', 'file3.csv'];
177
+ const results = await Promise.all(
178
+ files.map(f => csvToJson.getJsonFromCsvAsync(f))
179
+ );
180
+ </code></pre>
181
+ <h2>Configuration Options</h2>
182
+ <p>All APIs (Sync, Async and Browser) support the same configuration methods:</p>
183
+ <ul>
184
+ <li><code>fieldDelimiter(char)</code> - Set field delimiter (default: <code>,</code>)</li>
185
+ <li><code>formatValueByType()</code> - Auto-convert numbers, booleans</li>
186
+ <li><code>supportQuotedField(bool)</code> - Handle quoted fields with embedded delimiters</li>
187
+ <li><code>indexHeader(num)</code> - Specify header row (default: 0)</li>
188
+ <li><code>trimHeaderFieldWhiteSpace(bool)</code> - Remove spaces from headers</li>
189
+ <li><code>parseSubArray(delim, sep)</code> - Parse delimited arrays</li>
190
+ <li><code>mapRows(fn)</code> - Transform, filter, or enrich each row</li>
191
+ <li><code>utf8Encoding()</code>, <code>latin1Encoding()</code>, etc. - Set file encoding</li>
192
+ </ul>
193
+ <h3>Examples</h3>
194
+ <h4><code>fieldDelimiter(char)</code> - Set field delimiter (default: <code>,</code>)</h4>
195
+ <pre class="prettyprint source lang-js"><code>// Semicolon-delimited
196
+ csvToJson.fieldDelimiter(';').getJsonFromCsv('data.csv');
197
+
198
+ // Tab-delimited
199
+ csvToJson.fieldDelimiter('\t').getJsonFromCsv('data.tsv');
200
+
201
+ // Pipe-delimited
202
+ csvToJson.fieldDelimiter('|').getJsonFromCsv('data.psv');
203
+ </code></pre>
204
+ <h4><code>formatValueByType()</code> - Auto-convert numbers, booleans</h4>
205
+ <pre class="prettyprint source lang-js"><code>// Input: name,age,active
206
+ // John,30,true
207
+ csvToJson.formatValueByType().getJsonFromCsv('data.csv');
208
+ // Output: { name: 'John', age: 30, active: true }
209
+ </code></pre>
210
+ <h4><code>supportQuotedField(bool)</code> - Handle quoted fields with embedded delimiters</h4>
211
+ <pre class="prettyprint source lang-js"><code>// Input: name,description
212
+ // &quot;Smith, John&quot;,&quot;He said &quot;&quot;Hello&quot;&quot;&quot;
213
+ csvToJson.supportQuotedField(true).getJsonFromCsv('data.csv');
214
+ // Output: { name: 'Smith, John', description: 'He said &quot;Hello&quot;' }
215
+ </code></pre>
216
+ <h4><code>indexHeader(num)</code> - Specify header row (default: 0)</h4>
217
+ <pre class="prettyprint source lang-js"><code>// If headers are in row 2 (3rd line):
218
+ csvToJson.indexHeader(2).getJsonFromCsv('data.csv');
219
+ </code></pre>
220
+ <h4><code>trimHeaderFieldWhiteSpace(bool)</code> - Remove spaces from headers</h4>
221
+ <pre class="prettyprint source lang-js"><code>// Input: &quot; First Name &quot;, &quot; Last Name &quot;
222
+ csvToJson.trimHeaderFieldWhiteSpace(true).getJsonFromCsv('data.csv');
223
+ // Output: { FirstName: 'John', LastName: 'Doe' }
224
+ </code></pre>
225
+ <h4><code>parseSubArray(delim, sep)</code> - Parse delimited arrays</h4>
226
+ <pre class="prettyprint source lang-js"><code>// Input: name,tags
227
+ // John,*javascript,nodejs,typescript*
228
+ csvToJson.parseSubArray('*', ',').getJsonFromCsv('data.csv');
229
+ // Output: { name: 'John', tags: ['javascript', 'nodejs', 'typescript'] }
230
+ </code></pre>
231
+ <h4><code>mapRows(fn)</code> - Transform, filter, or enrich each row</h4>
232
+ <pre class="prettyprint source lang-js"><code>// Filter out rows that don't match a condition
233
+ const result = csvToJson
234
+ .fieldDelimiter(',')
235
+ .mapRows((row) => {
236
+ // Only keep rows where age >= 30
237
+ if (parseInt(row.age) >= 30) {
238
+ return row;
239
+ }
240
+ return null; // Filters out this row
241
+ })
242
+ .getJsonFromCsv('input.csv');
243
+ </code></pre>
244
+ <p>See <a href="docs/MAPROWS.md">mapRows Feature - Usage Guide</a>.</p>
245
+ <h4><code>utf8Encoding()</code>, <code>latin1Encoding()</code>, etc. - Set file encoding</h4>
246
+ <pre class="prettyprint source lang-js"><code>// UTF-8 encoding
247
+ csvToJson.utf8Encoding().getJsonFromCsv('data.csv');
248
+
249
+ // Latin-1 encoding
250
+ csvToJson.latin1Encoding().getJsonFromCsv('data.csv');
251
+
252
+ // Custom encoding
253
+ csvToJson.customEncoding('ucs2').getJsonFromCsv('data.csv');
254
+ </code></pre>
255
+ <p>See <a href="docs/SYNC.md">SYNC.md</a>, <a href="docs/ASYNC.md">ASYNC.md</a> or <a href="docs/BROWSER.md">BROWSER.md</a> for complete configuration details.</p>
256
+ <h2>Example: Complete Workflow</h2>
257
+ <pre class="prettyprint source lang-js"><code>const csvToJson = require('convert-csv-to-json');
258
+
259
+ async function processCSV() {
260
+ const data = await csvToJson
261
+ .fieldDelimiter(',')
262
+ .formatValueByType()
263
+ .supportQuotedField(true)
264
+ .getJsonFromCsvAsync('data.csv');
265
+
266
+ console.log(`Parsed ${data.length} records`);
267
+ return data;
268
+ }
269
+ </code></pre>
270
+ <h2>Migration Guides</h2>
271
+ <ul>
272
+ <li><strong>RFC 4180 Breaking Changes</strong> - See <a href="migration/RFC4180_MIGRATION_GUIDE.md">RFC4180_MIGRATION_GUIDE.md</a></li>
273
+ <li><strong>Sync to Async Migration</strong> - See <a href="migration/MIGRATION_TO_ASYNC.md">MIGRATION.md</a></li>
274
+ <li><strong>Error Handling</strong> - See <a href="docs/ERROR_HANDLING.md">docs/ERROR_HANDLING.md</a> for comprehensive error documentation</li>
275
+ </ul>
276
+ <h2>Development</h2>
277
+ <p>Install dependencies:</p>
278
+ <pre class="prettyprint source lang-bash"><code>npm install
279
+ </code></pre>
280
+ <p>Run tests:</p>
281
+ <pre class="prettyprint source lang-bash"><code>npm test
282
+ </code></pre>
283
+ <p>Debug tests:</p>
284
+ <pre class="prettyprint source lang-bash"><code>npm run test-debug
285
+ </code></pre>
286
+ <h2>CI/CD GitHub Action</h2>
287
+ <p>See <a href=".github/workflows/ci-cd.yml">CI/CD GitHub Action</a>.</p>
288
+ <h3>Release</h3>
289
+ <p>When pushing to the <code>master</code> branch:</p>
290
+ <ul>
291
+ <li>Include <code>[MAJOR]</code> in commit message for major release (e.g., v1.0.0 → v2.0.0)</li>
292
+ <li>Include <code>[PATCH]</code> in commit message for patch release (e.g., v1.0.0 → v1.0.1)</li>
293
+ <li>Minor release is applied by default (e.g., v1.0.0 → v1.1.0)</li>
294
+ </ul>
295
+ <h2>License</h2>
296
+ <p>CSVtoJSON is licensed under the MIT <a href="LICENSE">License</a>.</p>
297
+ <hr>
298
+ <h2>Support</h2>
299
+ <p>Found a bug or need a feature? Open an issue on <a href="https://github.com/iuccio/csvToJson/issues">GitHub</a>.</p>
300
+ <p>Follow <a href="https://github.com/iuccio">me</a> and consider starring the project to show your support ⭐</p>
301
+ <h3>Buy Me a Coffee</h3>
302
+ <p>If you find this project helpful and would like to support its development:</p>
303
+ <p><strong>BTC</strong>: <code>37vdjQhbaR7k7XzhMKWzMcnqUxfw1njBNk</code></p></article>
304
+ </section>
305
+
306
+
307
+
308
+
309
+
310
+
311
+ </div>
312
+
313
+ <nav>
314
+ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="BrowserApi.html">BrowserApi</a></li><li><a href="BrowserApiError.html">BrowserApiError</a></li><li><a href="ConfigurationError.html">ConfigurationError</a></li><li><a href="CsvFormatError.html">CsvFormatError</a></li><li><a href="CsvParsingError.html">CsvParsingError</a></li><li><a href="CsvToJson.html">CsvToJson</a></li><li><a href="CsvToJsonAsync.html">CsvToJsonAsync</a></li><li><a href="FileOperationError.html">FileOperationError</a></li><li><a href="FileUtils.html">FileUtils</a></li><li><a href="InputValidationError.html">InputValidationError</a></li><li><a href="JsonUtil.html">JsonUtil</a></li><li><a href="JsonValidationError.html">JsonValidationError</a></li></ul><h3>Global</h3><ul><li><a href="global.html#asciiEncoding">asciiEncoding</a></li><li><a href="global.html#base64Encoding">base64Encoding</a></li><li><a href="global.html#browser">browser</a></li><li><a href="global.html#csvStringToJson">csvStringToJson</a></li><li><a href="global.html#csvStringToJsonStringified">csvStringToJsonStringified</a></li><li><a href="global.html#csvToJsonAsync">csvToJsonAsync</a></li><li><a href="global.html#customEncoding">customEncoding</a></li><li><a href="global.html#fieldDelimiter">fieldDelimiter</a></li><li><a href="global.html#formatValueByType">formatValueByType</a></li><li><a href="global.html#generateJsonFileFromCsv">generateJsonFileFromCsv</a></li><li><a href="global.html#getJsonFromCsv">getJsonFromCsv</a></li><li><a href="global.html#hexEncoding">hexEncoding</a></li><li><a href="global.html#indexHeader">indexHeader</a></li><li><a href="global.html#latin1Encoding">latin1Encoding</a></li><li><a href="global.html#mapRows">mapRows</a></li><li><a href="global.html#parseSubArray">parseSubArray</a></li><li><a href="global.html#supportQuotedField">supportQuotedField</a></li><li><a href="global.html#trimHeaderFieldWhiteSpace">trimHeaderFieldWhiteSpace</a></li><li><a href="global.html#ucs2Encoding">ucs2Encoding</a></li><li><a href="global.html#utf16leEncoding">utf16leEncoding</a></li><li><a href="global.html#utf8Encoding">utf8Encoding</a></li></ul>
315
+ </nav>
316
+
317
+ <br class="clear">
318
+
319
+ <footer>
320
+ Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.5</a> on Fri Mar 20 2026 14:48:29 GMT+0000 (Coordinated Universal Time)
321
+ </footer>
322
+
323
+ <script> prettyPrint(); </script>
324
+ <script src="scripts/linenumber.js"> </script>
325
+ </body>
326
+ </html>
package/docs/api/index.js.html ADDED
@@ -0,0 +1,341 @@
1
+ <!DOCTYPE html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="utf-8">
5
+ <title>JSDoc: Source: index.js</title>
6
+
7
+ <script src="scripts/prettify/prettify.js"> </script>
8
+ <script src="scripts/prettify/lang-css.js"> </script>
9
+ <!--[if lt IE 9]>
10
+ <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
11
+ <![endif]-->
12
+ <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
13
+ <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
14
+ </head>
15
+
16
+ <body>
17
+
18
+ <div id="main">
19
+
20
+ <h1 class="page-title">Source: index.js</h1>
21
+
22
+
23
+
24
+
25
+
26
+
27
+ <section>
28
+ <article>
29
+ <pre class="prettyprint source linenums"><code>/**
30
+ * CsvToJson - CSV to JSON converter library
31
+ * Main entry point providing chainable API for CSV parsing with multiple configuration options
32
+ */
33
+
34
+ /* globals FileOperationError, CsvFormatError, JsonValidationError, InputValidationError */
35
+
36
+ "use strict";
37
+
38
+ let csvToJson = require("./src/csvToJson.js");
39
+
40
+ const encodingOps = {
41
+ utf8: 'utf8',
42
+ ucs2: 'ucs2',
43
+ utf16le: 'utf16le',
44
+ latin1: 'latin1',
45
+ ascii: 'ascii',
46
+ base64: 'base64',
47
+ hex: 'hex'
48
+ };
49
+
50
+ /**
51
+ * Enable or disable automatic type formatting for values
52
+ * Converts numeric strings to numbers, 'true'/'false' to booleans
53
+ * @param {boolean} active - Whether to format values by type (default: true)
54
+ * @returns {object} Module context for method chaining
55
+ */
56
+ exports.formatValueByType = function (active = true) {
57
+ csvToJson.formatValueByType(active);
58
+ return this;
59
+ };
60
+
61
+ /**
62
+ * Enable or disable support for RFC 4180 quoted fields
63
+ * When enabled, fields wrapped in double quotes can contain delimiters and newlines
64
+ * @param {boolean} active - Whether to support quoted fields (default: false)
65
+ * @returns {object} Module context for method chaining
66
+ */
67
+ exports.supportQuotedField = function (active = false) {
68
+ csvToJson.supportQuotedField(active);
69
+ return this;
70
+ };
71
+ /**
72
+ * Set the field delimiter character used to separate CSV fields
73
+ * @param {string} delimiter - Character(s) to use as field separator (default: ',')
74
+ * @returns {object} Module context for method chaining
75
+ */
76
+ exports.fieldDelimiter = function (delimiter) {
77
+ csvToJson.fieldDelimiter(delimiter);
78
+ return this;
79
+ };
80
+
81
+ /**
82
+ * Configure whitespace handling in CSV header field names
83
+ * When active, removes all whitespace from header names (e.g., "My Name" → "MyName")
84
+ * When inactive, only trims leading and trailing whitespace
85
+ * @param {boolean} active - Whether to remove all whitespace from headers (default: false)
86
+ * @returns {object} Module context for method chaining
87
+ */
88
+ exports.trimHeaderFieldWhiteSpace = function (active = false) {
89
+ csvToJson.trimHeaderFieldWhiteSpace(active);
90
+ return this;
91
+ };
92
+
93
+ /**
94
+ * Set the row index where CSV headers are located
95
+ * Use this if headers are not on the first line (row 0)
96
+ * @param {number} index - Zero-based row index containing headers
97
+ * @returns {object} Module context for method chaining
98
+ */
99
+ exports.indexHeader = function (index) {
100
+ csvToJson.indexHeader(index);
101
+ return this;
102
+ };
103
+
104
+ /**
105
+ * Configure sub-array parsing for special field values
106
+ * Fields bracketed by delimiter and containing separator are parsed into arrays
107
+ * @param {string} delimiter - Bracket character (default: '*')
108
+ * @param {string} separator - Item separator within brackets (default: ',')
109
+ * @returns {object} Module context for method chaining
110
+ * @example
111
+ * // Input field: "*val1,val2,val3*"
112
+ * // Output array: ["val1", "val2", "val3"]
113
+ * csvToJson.parseSubArray('*', ',')
114
+ */
115
+ exports.parseSubArray = function (delimiter, separator) {
116
+ csvToJson.parseSubArray(delimiter, separator);
117
+ return this;
118
+ };
119
+
120
+ /**
121
+ * Set custom file encoding for reading CSV files
122
+ * Useful for non-UTF8 encoded files
123
+ * @param {string} encoding - Node.js supported encoding (e.g., 'utf8', 'latin1', 'ascii')
124
+ * @returns {object} Module context for method chaining
125
+ */
126
+ exports.customEncoding = function (encoding) {
127
+ csvToJson.encoding = encoding;
128
+ return this;
129
+ };
130
+
131
+ /**
132
+ * Set UTF-8 encoding (default encoding)
133
+ * @returns {object} Module context for method chaining
134
+ */
135
+ exports.utf8Encoding = function utf8Encoding() {
136
+ csvToJson.encoding = encodingOps.utf8;
137
+ return this;
138
+ };
139
+
140
+ /**
141
+ * Set UCS-2 encoding for reading files
142
+ * @returns {object} Module context for method chaining
143
+ */
144
+ exports.ucs2Encoding = function () {
145
+ csvToJson.encoding = encodingOps.ucs2;
146
+ return this;
147
+ };
148
+
149
+ /**
150
+ * Set UTF-16 LE encoding for reading files
151
+ * @returns {object} Module context for method chaining
152
+ */
153
+ exports.utf16leEncoding = function () {
154
+ csvToJson.encoding = encodingOps.utf16le;
155
+ return this;
156
+ };
157
+
158
+ /**
159
+ * Set Latin-1 (ISO-8859-1) encoding for reading files
160
+ * @returns {object} Module context for method chaining
161
+ */
162
+ exports.latin1Encoding = function () {
163
+ csvToJson.encoding = encodingOps.latin1;
164
+ return this;
165
+ };
166
+
167
+ /**
168
+ * Set ASCII encoding for reading files
169
+ * @returns {object} Module context for method chaining
170
+ */
171
+ exports.asciiEncoding = function () {
172
+ csvToJson.encoding = encodingOps.ascii;
173
+ return this;
174
+ };
175
+
176
+ /**
177
+ * Set Base64 encoding for reading files
178
+ * @returns {object} Module context for method chaining
179
+ */
180
+ exports.base64Encoding = function () {
181
+ this.csvToJson = encodingOps.base64;
182
+ return this;
183
+ };
184
+
185
+ /**
186
+ * Set Hex encoding for reading files
187
+ * @returns {object} Module context for method chaining
188
+ */
189
+ exports.hexEncoding = function () {
190
+ this.csvToJson = encodingOps.hex;
191
+ return this;
192
+ };
193
+
194
+ /**
195
+ * Set a mapper function to transform each row after conversion
196
+ * The mapper function receives (row, index) where row is the JSON object
197
+ * and index is the 0-based row number. Return null/undefined to filter out rows.
198
+ * @param {Function} mapperFn - Function to transform each row: `(row, index) => transformedRow | null`
199
+ * @returns {object} Module context for method chaining
200
+ * @example
201
+ * csvToJson
202
+ * .mapRows((row, idx) => idx % 2 === 0 ? row : null) // Keep every other row
203
+ * .getJsonFromCsv('input.csv')
204
+ */
205
+ exports.mapRows = function (mapperFn) {
206
+ csvToJson.mapRows(mapperFn);
207
+ return this;
208
+ };
209
+
210
+ /**
211
+ * Parse CSV file and write the parsed JSON to an output file (synchronous)
212
+ * @param {string} inputFileName - Path to input CSV file
213
+ * @param {string} outputFileName - Path to output JSON file
214
+ * @throws {Error} If inputFileName or outputFileName is not defined
215
+ * @throws {FileOperationError} If file operations fail
216
+ * @throws {CsvFormatError} If CSV is malformed
217
+ * @example
218
+ * const csvToJson = require('convert-csv-to-json');
219
+ * csvToJson.generateJsonFileFromCsv('input.csv', 'output.json');
220
+ */
221
+ exports.generateJsonFileFromCsv = function(inputFileName, outputFileName) {
222
+ if (!inputFileName) {
223
+ throw new Error("inputFileName is not defined!!!");
224
+ }
225
+ if (!outputFileName) {
226
+ throw new Error("outputFileName is not defined!!!");
227
+ }
228
+ csvToJson.generateJsonFileFromCsv(inputFileName, outputFileName);
229
+ };
230
+
231
+ /**
232
+ * Parse CSV file and return parsed data as JSON array of objects (synchronous)
233
+ * @param {string} inputFileName - Path to input CSV file
234
+ * @returns {Array&lt;object>} Array of objects representing CSV rows
235
+ * @throws {Error} If inputFileName is not defined
236
+ * @throws {FileOperationError} If file read fails
237
+ * @throws {CsvFormatError} If CSV is malformed
238
+ * @example
239
+ * const csvToJson = require('convert-csv-to-json');
240
+ * const rows = csvToJson.getJsonFromCsv('resource/input.csv');
241
+ * console.log(rows);
242
+ */
243
+ exports.getJsonFromCsv = function(inputFileName) {
244
+ if (!inputFileName) {
245
+ throw new Error("inputFileName is not defined!!!");
246
+ }
247
+ return csvToJson.getJsonFromCsv(inputFileName);
248
+ };
249
+
250
+ /**
251
+ * Parse CSV file asynchronously and return parsed data as JSON array
252
+ * @param {string} inputFileNameOrCsv - Path to file or CSV string
253
+ * @param {object} options - Configuration options
254
+ * @param {boolean} options.raw - If true, treats first param as CSV content; if false, reads from file
255
+ * @returns {Promise&lt;Array&lt;object>>} Promise resolving to array of objects
256
+ * @throws {InputValidationError} If input is invalid
257
+ * @throws {FileOperationError} If file read fails
258
+ * @throws {CsvFormatError} If CSV is malformed
259
+ * @example
260
+ * const csvToJson = require('convert-csv-to-json');
261
+ * const data = await csvToJson.getJsonFromCsvAsync('resource/input.csv');
262
+ * console.log(data);
263
+ */
264
+ const csvToJsonAsync = require('./src/csvToJsonAsync');
265
+
266
+ // Re-export all async API methods
267
+ Object.assign(exports, {
268
+ getJsonFromCsvAsync: function(input, options) {
269
+ return csvToJsonAsync.getJsonFromCsvAsync(input, options);
270
+ },
271
+ csvStringToJsonAsync: function(input, options) {
272
+ return csvToJsonAsync.csvStringToJsonAsync(input, options);
273
+ },
274
+ csvStringToJsonStringifiedAsync: function(input) {
275
+ return csvToJsonAsync.csvStringToJsonStringifiedAsync(input);
276
+ },
277
+ generateJsonFileFromCsvAsync: function(input, output) {
278
+ return csvToJsonAsync.generateJsonFileFromCsv(input, output);
279
+ }
280
+ });
281
+
282
+ /**
283
+ * Parse a CSV string and return as JSON array of objects (synchronous)
284
+ * @param {string} csvString - CSV content as string
285
+ * @returns {Array&lt;object>} Array of objects representing CSV rows
286
+ * @throws {InputValidationError} If csvString is invalid
287
+ * @throws {CsvFormatError} If CSV is malformed
288
+ * @example
289
+ * const csvToJson = require('convert-csv-to-json');
290
+ * const rows = csvToJson.csvStringToJson('name,age\nAlice,30');
291
+ * console.log(rows); // [{ name: 'Alice', age: '30' }]
292
+ */
293
+ exports.csvStringToJson = function(csvString) {
294
+ return csvToJson.csvStringToJson(csvString);
295
+ };
296
+
297
+ /**
298
+ * Parse CSV string and return as stringified JSON (synchronous)
299
+ * @param {string} csvString - CSV content as string
300
+ * @returns {string} JSON stringified array of objects
301
+ * @throws {InputValidationError} If csvString is invalid
302
+ * @throws {CsvFormatError} If CSV is malformed
303
+ * @throws {JsonValidationError} If JSON generation fails
304
+ */
305
+ exports.csvStringToJsonStringified = function(csvString) {
306
+ if (csvString === undefined || csvString === null) {
307
+ throw new Error("csvString is not defined!!!");
308
+ }
309
+ return csvToJson.csvStringToJsonStringified(csvString);
310
+ };
311
+
312
+
313
+
314
+ /**
315
+ * Browser API
316
+ * Provides parsing helpers suitable for browser environments (parsing strings and File/Blob objects)
317
+ */
318
+ exports.browser = require('./src/browserApi');
319
+ </code></pre>
320
+ </article>
321
+ </section>
322
+
323
+
324
+
325
+
326
+ </div>
327
+
328
+ <nav>
329
+ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="BrowserApi.html">BrowserApi</a></li><li><a href="BrowserApiError.html">BrowserApiError</a></li><li><a href="ConfigurationError.html">ConfigurationError</a></li><li><a href="CsvFormatError.html">CsvFormatError</a></li><li><a href="CsvParsingError.html">CsvParsingError</a></li><li><a href="CsvToJson.html">CsvToJson</a></li><li><a href="CsvToJsonAsync.html">CsvToJsonAsync</a></li><li><a href="FileOperationError.html">FileOperationError</a></li><li><a href="FileUtils.html">FileUtils</a></li><li><a href="InputValidationError.html">InputValidationError</a></li><li><a href="JsonUtil.html">JsonUtil</a></li><li><a href="JsonValidationError.html">JsonValidationError</a></li></ul><h3>Global</h3><ul><li><a href="global.html#asciiEncoding">asciiEncoding</a></li><li><a href="global.html#base64Encoding">base64Encoding</a></li><li><a href="global.html#browser">browser</a></li><li><a href="global.html#csvStringToJson">csvStringToJson</a></li><li><a href="global.html#csvStringToJsonStringified">csvStringToJsonStringified</a></li><li><a href="global.html#csvToJsonAsync">csvToJsonAsync</a></li><li><a href="global.html#customEncoding">customEncoding</a></li><li><a href="global.html#fieldDelimiter">fieldDelimiter</a></li><li><a href="global.html#formatValueByType">formatValueByType</a></li><li><a href="global.html#generateJsonFileFromCsv">generateJsonFileFromCsv</a></li><li><a href="global.html#getJsonFromCsv">getJsonFromCsv</a></li><li><a href="global.html#hexEncoding">hexEncoding</a></li><li><a href="global.html#indexHeader">indexHeader</a></li><li><a href="global.html#latin1Encoding">latin1Encoding</a></li><li><a href="global.html#mapRows">mapRows</a></li><li><a href="global.html#parseSubArray">parseSubArray</a></li><li><a href="global.html#supportQuotedField">supportQuotedField</a></li><li><a href="global.html#trimHeaderFieldWhiteSpace">trimHeaderFieldWhiteSpace</a></li><li><a href="global.html#ucs2Encoding">ucs2Encoding</a></li><li><a href="global.html#utf16leEncoding">utf16leEncoding</a></li><li><a href="global.html#utf8Encoding">utf8Encoding</a></li></ul>
330
+ </nav>
331
+
332
+ <br class="clear">
333
+
334
+ <footer>
335
+ Documentation generated by <a href="https://github.com/jsdoc/jsdoc">JSDoc 4.0.5</a> on Fri Mar 20 2026 14:48:29 GMT+0000 (Coordinated Universal Time)
336
+ </footer>
337
+
338
+ <script> prettyPrint(); </script>
339
+ <script src="scripts/linenumber.js"> </script>
340
+ </body>
341
+ </html>