---

Key Concepts ✨

• 🌐 Web Standards first.
  • Utilizing the Web Standards APIs, such as the Web Streams API.
• ❤️ TypeScript friendly & User friendly.
  • Fully typed and documented.
• 0️⃣ Zero dependencies.
  • Using only Web Standards APIs.
• 💪 Property-based testing.
  • Using fast-check and vitest.
• ✅ Cross-platform.
  • Works on browsers, Node.js, and Deno.

Key Features 📗

• 🌊 Efficient CSV Parsing with Streams
  • 💻 Leveraging the WHATWG Streams API and other Web APIs for seamless and efficient data processing.
• 🛑 AbortSignal and Timeout Support: Ensure your CSV processing is cancellable, including support for automatic timeouts.
  • ✋ Integrate with AbortController to manually cancel operations as needed.
  • ⏳ Use AbortSignal.timeout to automatically cancel operations that exceed a specified time limit.
• 🎨 Flexible Source Support
  • 🧩 Parse CSVs directly from strings, ReadableStreams, or Response objects.
• ⚙️ Advanced Parsing Options: Customize your experience with various delimiters and quotation marks.
  • 🔄 Defaults to , and " respectively.
• 💾 Specialized Binary CSV Parsing: Leverage Stream-based processing for versatility and strength.
  • 🔄 Flexible BOM handling.
  • 🗜️ Supports various compression formats.
  • 🔤 Charset specification for diverse encoding.
• 🚀 Using WebAssembly for High Performance: WebAssembly is used for high performance parsing. (Experimental)
  • 📦 WebAssembly is used for high performance parsing.
• 📦 Lightweight and Zero Dependencies: No external dependencies, only Web Standards APIs.
• 📚 Fully Typed and Documented: Fully typed and documented with TypeDoc.

Installation 📥

With Package manager 📦

This package can then be installed using a package manager.

1# Install with npm
2$ npm install web-csv-toolbox
3# Or Yarn
4$ yarn add web-csv-toolbox
5# Or pnpm
6$ pnpm add web-csv-toolbox

From CDN (unpkg.com) 🌐

UMD Style 🔄

1<script src="https://unpkg.com/web-csv-toolbox"></script>
2<script>
3const csv = `name,age
4Alice,42
5Bob,69`;
6
7(async function () {
8  for await (const record of CSV.parse(csv)) {
9    console.log(record);
10  }
11})();
12</script>

ESModule Style 📦

1<script type="module">
2import { parse } from 'https://unpkg.com/web-csv-toolbox?module';
3
4const csv = `name,age
5Alice,42
6Bob,69`;
7
8for await (const record of parse(csv)) {
9  console.log(record);
10}
11</script>

Deno 🦕

You can install and use the package by specifying the following:

1import { parse } from "npm:web-csv-toolbox";

Usage 📘

Parsing CSV files from strings

1import { parse } from 'web-csv-toolbox';
2
3const csv = `name,age
4Alice,42
5Bob,69`;
6
7for await (const record of parse(csv)) {
8  console.log(record);
9}
10// Prints:
11// { name: 'Alice', age: '42' }
12// { name: 'Bob', age: '69' }

Parsing CSV files from ReadableStreams

1import { parse } from 'web-csv-toolbox';
2
3const csv = `name,age
4Alice,42
5Bob,69`;
6
7const stream = new ReadableStream({
8  start(controller) {
9    controller.enqueue(csv);
10    controller.close();
11  },
12});
13
14for await (const record of parse(stream)) {
15  console.log(record);
16}
17// Prints:
18// { name: 'Alice', age: '42' }
19// { name: 'Bob', age: '69' }

Parsing CSV files from Response objects

1import { parse } from 'web-csv-toolbox';
2
3const response = await fetch('https://example.com/data.csv');
4
5for await (const record of parse(response)) {
6  console.log(record);
7}
8// Prints:
9// { name: 'Alice', age: '42' }
10// { name: 'Bob', age: '69' }

Parsing CSV files with different delimiters and quotation characters

1import { parse } from 'web-csv-toolbox';
2
3const csv = `name\tage
4Alice\t42
5Bob\t69`;
6
7for await (const record of parse(csv, { delimiter: '\t' })) {
8  console.log(record);
9}
10// Prints:
11// { name: 'Alice', age: '42' }
12// { name: 'Bob', age: '69' }

Parsing CSV files with headers

1import { parse } from 'web-csv-toolbox';
2
3const csv = `Alice,42
4Bob,69`;
5
6for await (const record of parse(csv, { headers: ['name', 'age'] })) {
7  console.log(record);
8}
9// Prints:
10// { name: 'Alice', age: '42' }
11// { name: 'Bob', age: '69' }

AbortSignal / AbortController Support

Support for AbortSignal / AbortController, enabling you to cancel ongoing asynchronous CSV processing tasks.

This feature is useful for scenarios where processing needs to be halted, such as when a user navigates away from the page or other conditions that require stopping the task early.

Example Use Case: Abort with user action

1import { parse } from 'web-csv-toolbox';
2
3const controller = new AbortController();
4const csv = "name,age\nAlice,30\nBob,25";
5
6try {
7  // Parse the CSV data then pass the AbortSignal to the parse function
8  for await (const record of parse(csv, { signal: controller.signal })) {
9    console.log(record);
10  }
11} catch (error) {
12  if (error instanceof DOMException && error.name === 'AbortError') {
13     // The CSV processing was aborted by the user
14    console.log('CSV processing was aborted by the user.');
15  } else {
16    // An error occurred during CSV processing
17    console.error('An error occurred:', error);
18  }
19}
20
21// Some abort logic, like a cancel button
22document.getElementById('cancel-button')
23  .addEventListener('click', () => {
24    controller.abort();
25  });

Example Use Case: Abort with timeout

1import { parse } from 'web-csv-toolbox';
2
3// Set up a timeout of 5 seconds (5000 milliseconds)
4const signal = AbortSignal.timeout(5000);
5
6const csv = "name,age\nAlice,30\nBob,25";
7
8try {
9  // Pass the AbortSignal to the parse function
10  const result = await parse.toArray(csv, { signal });
11  console.log(result);
12} catch (error) {
13  if (error instanceof DOMException && error.name === 'TimeoutError') {
14    // Handle the case where the processing was aborted due to timeout
15    console.log('CSV processing was aborted due to timeout.');
16  } else {
17    // Handle other errors
18    console.error('An error occurred during CSV processing:', error);
19  }
20}

Supported Runtimes 💻

Works on Node.js

Versions	Status
20.x	✅
18.x	✅

Works on Browser

OS	Chrome	FireFox	Default
Windows	✅	✅	✅ (Edge)
macos	✅	✅	⬜ (Safari *)
Linux	✅	✅	-

* To Be Tested: I couldn't launch Safari in headless mode on GitHub Actions, so I couldn't verify it, but it probably works.

Others

• Verify that JavaScript is executable on the Deno.

APIs 🧑‍💻

High-level APIs 🚀

These APIs are designed for Simplicity and Ease of Use, providing an intuitive and straightforward experience for users.

• function parse(input[, options]): AsyncIterableIterator<CSVRecord>: 📑
  • Parses various CSV input formats into an asynchronous iterable of records.
• function parse.toArray(input[, options]): Promise<CSVRecord[]>: 📑
  • Parses CSV input into an array of records, ideal for smaller data sets.

The input paramater can be a string, a ReadableStream of strings or Uint8Arrays, or a Uint8Array object, or a ArrayBuffer object, or a Response object.

Middle-level APIs 🧱

These APIs are optimized for Enhanced Performance and Control, catering to users who need more detailed and fine-tuned functionality.

• function parseString(string[, options]): 📑
  • Efficient parsing of CSV strings.
• function parseBinary(buffer[, options]): 📑
  • Parse CSV Binary of ArrayBuffer or Uint8Array.
• function parseResponse(response[, options]): 📑
  • Customized parsing directly from Response objects.
• function parseStream(stream[, options]): 📑
  • Stream-based parsing for larger or continuous data.
• function parseStringStream(stream[, options]): 📑
  • Combines string-based parsing with stream processing.
• function parseUint8ArrayStream(stream[, options]): 📑
  • Parses binary streams with precise control over data types.

Low-level APIs ⚙️

These APIs are built for Advanced Customization and Pipeline Design, ideal for developers looking for in-depth control and flexibility.

• class LexerTransformer: 📑
  • A TransformStream class for lexical analysis of CSV data.
• class RecordAssemblerTransformer: 📑
  • Handles the assembly of parsed data into records.

Experimental APIs 🧪

These APIs are experimental and may change in the future.

Parsing using WebAssembly for high performance.

You can use WebAssembly to parse CSV data for high performance.

• Parsing with WebAssembly is faster than parsing with JavaScript, but it takes time to load the WebAssembly module.
• Supports only UTF-8 encoding csv data.
• Quotation characters are only ". (Double quotation mark)
  • If you pass a different character, it will throw an error.

1import { loadWASM, parseStringWASM } from "web-csv-toolbox";
2
3// load WebAssembly module
4await loadWASM();
5
6const csv = "a,b,c\n1,2,3";
7
8// parse CSV string
9const result = parseStringToArraySyncWASM(csv);
10console.log(result);
11// Prints:
12// [{ a: "1", b: "2", c: "3" }]

• function loadWASM(): Promise<void>: 📑
  • Loads the WebAssembly module.
• function parseStringToArraySyncWASM(string[, options]): CSVRecord[]: 📑
  • Parses CSV strings into an array of records.

Options Configuration 🛠️

Common Options ⚙️

Option	Description	Default	Notes
delimiter	Character to separate fields	,
quotation	Character used for quoting fields	"
headers	Custom headers for the parsed records	First row	If not provided, the first row is used as headers
signal	AbortSignal to cancel processing	undefined	Allows aborting of long-running operations

Advanced Options (Binary-Specific) 🧬

Option	Description	Default	Notes
charset	Character encoding for binary CSV inputs	utf-8	See Encoding API Compatibility for the encoding formats that can be specified.
decompression	Decompression algorithm for compressed CSV inputs		See DecompressionStream Compatibility.
ignoreBOM	Whether to ignore Byte Order Mark (BOM)	false	See TextDecoderOptions.ignoreBOM for more information about the BOM.
fatal	Throw an error on invalid characters	false	See TextDecoderOptions.fatal for more information.

How to Contribute 💪

Star ⭐

The easiest way to contribute is to use the library and star repository.

Questions 💭

Feel free to ask questions on GitHub Discussions.

Report bugs / request additional features 💡

Please register at GitHub Issues.

Financial Support 💸

Please support kamiazya.

Even just a dollar is enough motivation to develop 😊

License ⚖️

This software is released under the MIT License, see LICENSE.