web-csv-toolbox 0.0.0-next-20231225182210 → 0.0.0-next-20231227082102

package/README.md

@@ -1,38 +1,73 @@
-# web-csv-toolbox
+<div align="center">
+
+[![Node.js CI](https://github.com/kamiazya/web-csv-toolbox/actions/workflows/node.js.yaml/badge.svg)](https://github.com/kamiazya/web-csv-toolbox/actions/workflows/node.js.yaml)
+[![npm version](https://badge.fury.io/js/web-csv-toolbox.svg)](https://badge.fury.io/js/web-csv-toolbox)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
+![node version](https://img.shields.io/node/v/web-csv-toolbox)
+![npm](https://img.shields.io/npm/dm/web-csv-toolbox)
+
+# `🌐 web-csv-toolbox 💽`
 
 A CSV Toolbox utilizing Web Standard APIs.
 
-## Key Concepts
+🔗
 
-- Web Standards first.
-  - Using the [Web Streams API](https://streams.spec.whatwg.org/).
-- TypeScript friendly & User friendly.
-  - Fully typed and documented.
-- Zero dependencies.
-  - Using only Web Standards APIs.
-- Property-based testing.
-  - Using [fast-check](https://fast-check.dev/) and [vitest](https://vitest.dev).
-- **To Be Tested** Cross platform.
-  - Works on browsers and Node.js, Deno
-    - Only web standard APIs are used, so it should work with these Runtimes.
+[![GitHub](https://img.shields.io/badge/-GitHub-181717?logo=GitHub&style=flat)](https://github.com/kamiazya/web-csv-toolbox)
+[![npm](https://img.shields.io/badge/-npm-CB3837?logo=npm&style=flat)](https://www.npmjs.com/package/web-csv-toolbox)
+[![yarn](https://img.shields.io/badge/-yarn-ffffff?logo=Yarn&style=flat)](https://yarnpkg.com/package/web-csv-toolbox)
+[![API Reference](https://img.shields.io/badge/-API%20Refarence-3178C6?logo=TypeScript&style=flat&logoColor=fff)](https://kamiazya.github.io/web-csv-toolbox/)
+[![Sponsor](https://img.shields.io/badge/-GitHub%20Sponsor-fff?logo=GitHub%20Sponsors&style=flat)](https://github.com/sponsors/kamiazya)
+
+
+[![format: Biome](https://img.shields.io/badge/format%20with-Biome-F7B911?logo=biome&style=flat)](https://biomejs.dev/)
+[![test: Vitest](https://img.shields.io/badge/tested%20with-Vitest-6E9F18?logo=vitest&style=flat)](https://vitest.dev/)
+[![build: Rollup](https://img.shields.io/badge/build%20with-Rollup-EC4A3F?logo=rollup.js&style=flat)](https://rollupjs.org/)
 
-## Key Features
+</div>
 
-- Parses CSV files using the [WHATWG Streams API](https://streams.spec.whatwg.org/).
-- Supports parsing CSV files from strings, `ReadableStream`s, and `Response` objects.
-- Supports parsing CSV files with different delimiters and quotation characters.
-  - Defaults to `,` and `"` respectively.
-  - Supports parsing TSV files by setting `delimiter` to `\t`.
-  - Supports parsing with multi-character/multi-byte delimiters and quotation characters.
-- Supports parsing binary CSV files.
+---
 
-## Installation
+## Key Concepts ✨
+
+- 🌐 **Web Standards first.**
+  - Utilizing the Web Standards APIs, such as the [Web Streams API](https://developer.mozilla.org/en/docs/Web/API/Streams_API).
+- ❤️ **TypeScript friendly & User friendly.**
+  - Fully typed and documented.
+- 0️⃣ **Zero dependencies.**
+  - Using only Web Standards APIs.
+- 💪 **Property-based testing.**
+  - Using [fast-check](https://fast-check.dev/) and [vitest](https://vitest.dev).
+- ✅ **_To Be Tested_** **Cross-platform.**
+  - Works on browsers, Node.js, and Deno.
+    - Only web standard APIs are used, so it should work with these runtimes.
+
+## Key Features 📗
+
+- 🌊 **Efficient CSV Parsing with Streams**
+  - 💻 Leveraging the [WHATWG Streams API](https://streams.spec.whatwg.org/) and other Web APIs for seamless and efficient data processing.
+- 🎨 **Flexible Source Support**
+  - 🧩 Parse CSVs directly from `string`s, `ReadableStream`s, or `Response` objects.
+- ⚙️ **Advanced Parsing Options**: Customize your experience with various delimiters and quotation marks.
+  - 🔄 Defaults to `,` and `"` respectively.
+  - 🛠️ Use multi-character/multi-byte delimiters and quotations.
+- 💾 **Specialized Binary CSV Parsing**: Leverage Stream-based processing for versatility and strength.
+  - 🔄 Flexible BOM handling.
+  - 🗜️ Supports various compression formats.
+  - 🔤 Charset specification for diverse encoding.
+
+## Installation 📥
 
 ```sh
-npm install web-csv-toolbox
+# Install with npm
+$ npm install web-csv-toolbox
+# Or Yarn
+$ yarn add web-csv-toolbox
+# Or pnpm
+$ pnpm add web-csv-toolbox
 ```
 
-## Usage
+## Usage 📘
 
 ### Parsing CSV files from strings
 
@@ -107,7 +142,7 @@ for await (const record of parse(csv, { delimiter: '\t' })) {
 // { name: 'Bob', age: '69' }
 ```
 
-### Parsing CSV files with different headers
+### Parsing CSV files with headers
 
 ```js
 import { parse } from 'web-csv-toolbox';
@@ -123,69 +158,87 @@ for await (const record of parse(csv, { headers: ['name', 'age'] })) {
 // { name: 'Bob', age: '69' }
 ```
 
-## APIs
-
-### High-level APIs
-
-#### `parse(input[, options]): AsyncIterableIterator<Record>` function
-
-Returns an asynchronous iterable of records.
+## APIs 🧑‍💻
 
-##### `input` parameter
+### High-level APIs 🚀
 
-The input to parse. This can be a `string`, a `ReadableStream` of `string`s or `Uint8Array`s, or a `Response` object.
+These APIs are designed for **Simplicity and Ease of Use**,
+providing an intuitive and straightforward experience for users.
 
-##### `options` parameter
+- **`function parse(input[, options]): AsyncIterableIterator<CSVRecord>`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parse-1.html)
+  - Parses various CSV input formats into an asynchronous iterable of records.
+- **`function parse.toArray(input[, options]): Promise<CSVRecord[]>`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parse.toArray.html)
+  - Parses CSV input into an array of records, ideal for smaller data sets.
 
-An optional object with the following properties:
+The `input` paramater can be a `string`, a [ReadableStream](https://developer.mozilla.org/docs/Web/API/ReadableStream)
+of `string`s or [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)s,
+or a [Response](https://developer.mozilla.org/docs/Web/API/Response) object.
 
-###### `options.delimiter`
+### Middle-level APIs 🧱
 
-The character used to separate fields in the CSV input. Defaults to `,`.
+These APIs are optimized for **Enhanced Performance and Control**,
+catering to users who need more detailed and fine-tuned functionality.
 
-###### `options.quotation`
+- **`function parseBinaryStream(stream[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseBinaryStream-1.html)
+  - Parses binary streams with precise control over data types.
+- **`function parseResponse(response[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseResponse-1.html)
+  - Customized parsing directly from `Response` objects.
+- **`function parseStream(stream[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseStream-1.html)
+  - Stream-based parsing for larger or continuous data.
+- **`function parseString(string[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseString-1.html)
+  - Efficient parsing of CSV strings.
+- **`function parseStringStream(stream[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseStringStream-1.html)
+  - Combines string-based parsing with stream processing.
 
-The character used to quote fields in the CSV input. Defaults to `"`.
+### Low-level APIs ⚙️
 
-###### `options.headers`
+These APIs are built for **Advanced Customization and Pipeline Design**,
+ideal for developers looking for in-depth control and flexibility.
 
-An optional array of strings to use as the headers for the parsed records.
+- **`class LexerTransformer`**: [📑](https://kamiazya.github.io/web-csv-toolbox/classes/LexerTransformer.html)
+  - A TransformStream class for lexical analysis of CSV data.
+- **`class RecordAssemblerTransformer`**: [📑](https://kamiazya.github.io/web-csv-toolbox/classes/RecordAssemblerTransformar.html)
+  - Handles the assembly of parsed data into records.
 
-If not provided, the first record will be used as the headers.
+## Options Configuration 🛠️
 
-###### `options.decompression`
+### Common Options ⚙️
 
-The decompression format to use when parsing the binary CSV input.
+| 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 |
 
-If not provided, the input will be treated as text.
+### Advanced Options (Binary-Specific) 🧬
 
-Possible values are:
+| Option          | Description                                       | Default   | Notes |
+| --------------- | ------------------------------------------------- | --------- | ---------------------- |
+| `charset`       | Character encoding for binary CSV inputs          | `utf-8`   | See [Encoding API Compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings) for the encoding formats that can be specified. |
+| `decompression` | Decompression algorithm for compressed CSV inputs |           | See [DecompressionStream Compatibility](https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream#browser_compatibilit). |
+| `ignoreBOM`     | Whether to ignore Byte Order Mark (BOM)           | `false`   | See [TextDecoderOptions.ignoreBOM](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream/ignoreBOM) for more information about the BOM. |
+| `fatal`         | Throw an error on invalid characters              | `false`   | See [TextDecoderOptions.fatal](https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream/fatal) for more information. |
 
-- `gzip`
-- `deflate`
-- `deflate-raw`
-  - Note: This format is supported in Node.js v21.2.0 and above.
+## How to Contribute 💪
 
-###### `options.charset`
+## Star ⭐
 
-The character set to use when parsing the binary CSV input.
+The easiest way to contribute is to use the library and star [repository](https://github.com/kamiazya/web-csv-toolbox/).
 
-Defaults to `utf-8`.
+### Questions 💭
 
-###### `options.ignoreBOM`
+Feel free to ask questions on [GitHub Discussions](https://github.com/kamiazya/web-csv-toolbox/discussions).
 
-Whether to ignore a leading BOM in the CSV input.
-Defaults to `false`.
+### Report bugs / request additional features 💡
 
-###### `options.fatal`
+Please register at [GitHub Issues](https://github.com/kamiazya/web-csv-toolbox/issues/new/choose).
 
-Whether to throw an error if the CSV input is invalid.
-Defaults to `false`.
+### Financial Support 💸
 
-### Low-level APIs
+Please support [kamiazya](https://github.com/sponsors/kamiazya).
 
-For low-level API details, please refer to [source code](https://github.com/kamiazya/web-csv-toolbox).
+> Even just a dollar is enough motivation to develop 😊
 
-## License
+## License ⚖️
 
-[MIT](./LICENSE)
+This software is released under the MIT License, see [LICENSE](https://github.com/kamiazya/web-csv-toolbox?tab=MIT-1-ov-file).

package/lib/index.d.ts

@@ -1,19 +1,23 @@
 /**
  * FiledDelimiter is a symbol for field delimiter of CSV.
+ * @category Constants
  */
 declare const FieldDelimiter: unique symbol;
 /**
  * RecordDelimiter is a symbol for record delimiter of CSV.
+ * @category Constants
  */
 declare const RecordDelimiter: unique symbol;
 /**
  * Field is a symbol for field of CSV.
+ * @category Constants
  */
 declare const Field: unique symbol;
 
 /**
  * Token is a atomic unit of a CSV file.
  * It can be a field, field delimiter, or record delimiter.
+ * @category Types
  *
  * @example
  * ```ts
@@ -28,10 +32,12 @@ interface Token<T extends TokenType = TokenType> {
 }
 /**
  * Type of a token for CSV.
+ * @category Types
  */
 type TokenType = typeof FieldDelimiter | typeof RecordDelimiter | typeof Field;
 /**
  * CSV Common Options.
+ * @category Types
  */
 interface CommonOptions {
   /**
@@ -56,6 +62,7 @@ interface CommonOptions {
 }
 /**
  * CSV Parsing Options for binary.
+ * @category Types
  */
 interface BinaryOptions {
   /**
@@ -64,6 +71,7 @@ interface BinaryOptions {
    *
    * @remarks
    * Make sure the runtime you are running supports stream decompression.
+   *
    * See {@link https://developer.mozilla.org/en-US/docs/Web/API/DecompressionStream#browser_compatibility | DecompressionStream Compatibility}.
    */
   decomposition?: CompressionFormat;
@@ -71,7 +79,8 @@ interface BinaryOptions {
    * You can specify the character encoding of the binary.
    *
    * @remarks
-   * {@link TextDecoderStream} is used internally.
+   * {@link !TextDecoderStream} is used internally.
+   *
    * See {@link https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API/Encodings | Encoding API Compatibility}
    * for the encoding formats that can be specified.
    *
@@ -92,14 +101,21 @@ interface BinaryOptions {
    * If the binary has a invalid character, you can specify whether to throw an error.
    *
    * @remarks
-   * If you specify true, an error will be thrown.
-   * If you specify false or not specify it, the invalid character will be replaced with `U+FFFD`.
-   * See {@link https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream/fatal | TextDecoderOptions.fatal} for more information about the invalid character.
+   * If the property is `true` then a decoder will throw a {@link !TypeError}
+   * if it encounters malformed data while decoding.
+   *
+   * If `false` the decoder will substitute the invalid data
+   * with the replacement character `U+FFFD` (�).
+   *
+   * See {@link https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream/fatal | TextDecoderOptions.fatal} for more information.
+   *
+   * @default false
    */
   fatal?: boolean;
 }
 /**
  * Record Assembler Options for CSV.
+ * @category Types
  *
  * @remarks
  * If you specify `header: ['foo', 'bar']`,
@@ -125,18 +141,21 @@ interface RecordAssemblerOptions<Header extends ReadonlyArray<string>> {
 }
 /**
  * Parse options for CSV string.
+ * @category Types
  */
 interface ParseOptions<Header extends ReadonlyArray<string>>
   extends CommonOptions,
     RecordAssemblerOptions<Header> {}
 /**
  * Parse options for CSV binary.
+ * @category Types
  */
 interface ParseBinaryOptions<Header extends ReadonlyArray<string>>
   extends ParseOptions<Header>,
     BinaryOptions {}
 /**
  * CSV Record.
+ * @category Types
  * @template Header Header of the CSV.
  *
  * @example Header is ["foo", "bar"]
@@ -155,6 +174,8 @@ type CSVRecord<Header extends ReadonlyArray<string>> = Record<
 /**
  * A transform stream that converts a stream of tokens into a stream of rows.
  *
+ * @category Low-level API
+ *
  * @example Parse a CSV with headers by data
  * ```ts
  * new ReadableStream({
@@ -189,6 +210,8 @@ declare class LexerTransformer extends TransformStream<string, Token> {
  * @template Header The type of the header row.
  * @param options The options for the parser.
  *
+ * @category Low-level API
+ *
  * @example Parse a CSV with headers by data
  *  ```ts
  * new ReadableStream({
@@ -235,16 +258,55 @@ declare class RecordAssemblerTransformar<
 /**
  * Parse CSV string to records.
  *
+ * @category Middle-level API
  * @param csv CSV string to parse
  * @param options Parsing options. See {@link ParseOptions}.
+ * @returns Async iterable iterator of records.
+ *
+ * If you want array of records, use {@link parseString.toArray} function.
+ * @example Parsing CSV files from strings
+ *
+ * ```ts
+ * import { parseString } from 'web-csv-toolbox';
+ *
+ * const csv = `name,age
+ * Alice,42
+ * Bob,69`;
+ *
+ * for await (const record of parseString(csv)) {
+ *   console.log(record);
+ * }
+ * // Prints:
+ * // { name: 'Alice', age: '42' }
+ * // { name: 'Bob', age: '69' }
+ * ```
  */
-declare function streamingParse<Header extends ReadonlyArray<string>>(
+declare function parseString<Header extends ReadonlyArray<string>>(
   csv: string,
   options?: ParseOptions<Header>,
 ): AsyncIterableIterator<CSVRecord<Header>>;
-declare namespace streamingParse {
+declare namespace parseString {
+  /**
+   * Parse CSV string to records.
+   *
+   * @returns Array of records
+   *
+   * @example
+   * ```ts
+   * import { parseString } from 'web-csv-toolbox';
+   *
+   * const csv = `name,age
+   * Alice,42
+   * Bob,69`;
+   *
+   * const records = await parseString.toArray(csv);
+   * console.log(records);
+   * // Prints:
+   * // [ { name: 'Alice', age: '42' }, { name: 'Bob', age: '69' } ]
+   * ```
+   */
   function toArray<Header extends ReadonlyArray<string>>(
-    stream: ReadableStream<Uint8Array>,
+    csv: string,
     options?: ParseOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
 }
@@ -253,16 +315,66 @@ declare namespace streamingParse {
  * Parse CSV to records.
  * This function is for parsing a binary stream.
  *
+ * @category Middle-level API
  * @remarks
- * If you want to parse a string, use {@link streamingParse}.
+ * If you want to parse a string, use {@link parseStringStream}.
  * @param stream CSV string to parse
  * @param options Parsing options. See {@link ParseBinaryOptions}.
+ * @returns Async iterable iterator of records.
+ *
+ * If you want array of records, use {@link parseBinaryStream.toArray} function.
+ *
+ * @example Parsing CSV binary
+ *
+ * ```ts
+ * import { parseBinaryStream } from 'web-csv-toolbox';
+ *
+ * const csv = Uint8Array.from([
+ *  // ...
+ * ]);
+ *
+ * const stream = new ReadableStream({
+ *   start(controller) {
+ *     controller.enqueue(csv);
+ *     controller.close();
+ *   },
+ * });
+ *
+ * for await (const record of parseBinaryStream(csv)) {
+ * console.log(record);
+ * }
+ * ```
  */
 declare function parseBinaryStream<Header extends ReadonlyArray<string>>(
   stream: ReadableStream<Uint8Array>,
   options?: ParseBinaryOptions<Header>,
 ): AsyncIterableIterator<CSVRecord<Header>>;
 declare namespace parseBinaryStream {
+  /**
+   * Parse CSV binary to array of records,
+   * ideal for smaller data sets.
+   *
+   * @returns Array of records
+   *
+   * @example Parsing CSV binary
+   * ```ts
+   * import { parseBinaryStream } from 'web-csv-toolbox';
+   *
+   * const csv = Uint8Array.from([
+   *   // ...
+   * ]);
+   *
+   * const stream = new ReadableStream({
+   *   start(controller) {
+   *     controller.enqueue(csv);
+   *     controller.close();
+   *   },
+   * });
+   *
+   * const records = await parseBinaryStream.toArray(stream);
+   * console.log(records);
+   * ```
+   */
   function toArray<Header extends ReadonlyArray<string>>(
     stream: ReadableStream<Uint8Array>,
     options?: ParseBinaryOptions<Header>,
@@ -270,48 +382,407 @@ declare namespace parseBinaryStream {
 }
 
 /**
- * Parse CSV string to records.
+ * Parse CSV string stream to records.
  *
+ * @category Middle-level API
  * @param stream CSV string stream to parse
- * @param options Parsing options. See {@link ParseOptions}.
+ * @param options Parsing options.
+ * @returns Async iterable iterator of records.
+ *
+ * If you want array of records, use {@link parseStringStream.toArray} function.
+ *
+ * @example Parsing CSV files from strings
+ *
+ * ```ts
+ * import { parseStringStream } from 'web-csv-toolbox';
+ *
+ * const csv = `name,age
+ * Alice,42
+ * Bob,69`;
+ *
+ * const stream = new ReadableStream({
+ *  start(controller) {
+ *     controller.enqueue(csv);
+ *     controller.close();
+ *   },
+ * });
+ *
+ * for await (const record of parseStringStream(csv)) {
+ *  console.log(record);
+ * }
+ * // Prints:
+ * // { name: 'Alice', age: '42' }
+ * // { name: 'Bob', age: '69' }
+ * ```
  */
 declare function parseStringStream<Header extends ReadonlyArray<string>>(
   stream: ReadableStream<string>,
   options?: ParseOptions<Header>,
 ): AsyncIterableIterator<CSVRecord<Header>>;
 declare namespace parseStringStream {
+  /**
+   * Parse CSV string stream to records.
+   *
+   * @returns Array of records
+   *
+   * @example
+   *
+   * ```ts
+   * import { parseStringStream } from 'web-csv-toolbox';
+   *
+   * const csv = `name,age
+   * Alice,42
+   * Bob,69`;
+   *
+   * const stream = new ReadableStream({
+   *   start(controller) {
+   *     controller.enqueue(csv);
+   *     controller.close();
+   *   },
+   * });
+   *
+   * const records = await parseStringStream.toArray(stream);
+   * console.log(records);
+   * // Prints:
+   * // [ { name: 'Alice', age: '42' }, { name: 'Bob', age: '69' } ]
+   * ```
+   */
   function toArray<Header extends ReadonlyArray<string>>(
-    stream: ReadableStream<Uint8Array>,
+    stream: ReadableStream<string>,
     options?: ParseOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
 }
 
 /**
- * Parse CSV to records.
+ * Parse HTTP Response what contains CSV to records,
+ * ideal for smaller data sets.
+ *
+ * @remarks
+ * This function automatically treats response headers.
  *
- * {@link String}, {@link Uint8Array}, ReadableStream<string | Uint8Array> and Response are supported.
+ * - If `Content-Type` header is not set, it assumes `text/csv`.
+ * - If `Content-Type` header is not `text/csv`, it throws an error.
+ * - If `Content-Type` header has charset parameter, it uses it for decoding.
+ * - If `Content-Encoding` header is set, it decompresses the response.
+ * - Should there be any conflicting information between the header and the options, the option's value will take precedence.
+ *
+ * @category Middle-level API
+ * @param response
+ * @param options
+ * @returns Async iterable iterator of records.
+ *
+ * If you want array of records, use {@link parseResponse.toArray} function.
+ *
+ * @example Parsing CSV Response
+ *
+ * ```ts
+ * import { parseResponse } from 'web-csv-toolbox';
+ *
+ * const response = await fetch('https://example.com/data.csv');
+ *
+ * for await (const record of parseResponse(response)) {
+ *   console.log(record);
+ * }
+ * ```
+ */
+declare function parseResponse<Header extends ReadonlyArray<string>>(
+  response: Response,
+  options?: ParseOptions<Header>,
+): AsyncIterableIterator<CSVRecord<Header>>;
+declare namespace parseResponse {
+  /**
+   * Parse CSV Response to array of records.
+   *
+   * @returns Array of records
+   *
+   * @example Parsing CSV Response
+   *
+   * ```ts
+   * import { parseResponse } from 'web-csv-toolbox';
+   *
+   * const response = await fetch('https://example.com/data.csv');
+   *
+   * const records = await parseResponse.toArray(response);
+   * console.log(records);
+   * ```
+   */
+  function toArray<Header extends ReadonlyArray<string>>(
+    response: Response,
+    options?: ParseOptions<Header>,
+  ): Promise<CSVRecord<Header>[]>;
+}
+
+/**
+ * Parse CSV Stream to records,
+ * ideal for smaller data sets.
+ *
+ * {@link !ReadableStream} of {@link !String} and {@link !Uint8Array} are supported.
  *
  * @remarks
- * {@link streamingParse}, {@link parseBinaryStream},
- * {@link parseStringStream} and {@link parseResponse} are used internally.
+ * {@link parseStringStream} and {@link parseBinaryStream} are used internally.
  * If you known the type of the stream, it performs better to use them directly.
  *
- * If you want to parse a string, use {@link streamingParse}.
- * If you want to parse a Uint8Array, use {@link parseStream}.
- * If you want to parse a ReadableStream<string>, use {@link parseStringStream}.
- * If you want to parse a ReadableStream<Uint8Array>, use {@link parseBinaryStream}.
- * If you want to parse a Response, use {@link parseResponse}.
+ * If you want to parse a string, use {@link parseStringStream}.
+ * If you want to parse a Uint8Array, use {@link parseBinaryStream}.
  *
+ * @category Middle-level API
  * @param csv CSV string to parse
  * @param options Parsing options. See {@link ParseOptions}.
+ * @returns Async iterable iterator of records.
+ *
+ * If you want array of records, use {@link parseStream.toArray} function.
+ *
+ * @example Parsing CSV string stream
+ *
+ * ```ts
+ *
+ * import { parseStream } from 'web-csv-toolbox';
+ *
+ * const csv = `name,age
+ * Alice,42
+ * Bob,69`;
+ *
+ * const stream = new ReadableStream({
+ *  start(controller) {
+ *    controller.enqueue(csv);
+ *   controller.close();
+ * },
+ * });
+ *
+ * for await (const record of parseStream(stream)) {
+ *  console.log(record);
+ * }
+ * // Prints:
+ * // { name: 'Alice', age: '42' }
+ * // { name: 'Bob', age: '69' }
+ * ```
+ *
+ * @example Parsing CSV binary stream
+ *
+ * ```ts
+ * import { parseStream } from 'web-csv-toolbox';
+ *
+ * const csv = Uint8Array.from([
+ *   // ...
+ * ]);
+ *
+ * const stream = new ReadableStream({
+ *   start(controller) {
+ *     controller.enqueue(csv);
+ *     controller.close();
+ *   },
+ * });
+ *
+ * for await (const record of parseStream(stream)) {
+ *   console.log(record);
+ * }
+ * ```
+ */
+declare function parseStream<Header extends ReadonlyArray<string>>(
+  stream: ReadableStream<Uint8Array | string>,
+  options?: ParseBinaryOptions<Header>,
+): AsyncIterableIterator<CSVRecord<Header>>;
+declare namespace parseStream {
+  /**
+   * Parse CSV Stream to array of records.
+   *
+   * @returns Array of records
+   */
+  function toArray<Header extends ReadonlyArray<string>>(
+    stream: ReadableStream<Uint8Array>,
+    options?: ParseBinaryOptions<Header>,
+  ): Promise<CSVRecord<Header>[]>;
+}
+
+/**
+ * Parse CSV to records.
+ *
+ * {@link !String}, {@link !ReadableStream}<string | {@link !Uint8Array}> and {@link !Response} are supported.
+ *
+ *
+ * @typeParam Header Header type like `['name', 'age']`.
+ *
+ * @param csv CSV string to parse.
+ * @param options Parsing options for CSV string parsing.
+ * @returns Async iterable iterator of records.
+ *
+ * If you want array of records, use {@link parse.toArray} function.
+ * @category High-level API
+ *
+ * @remarks
+ * {@link parseString}, {@link parseBinaryStream},
+ * {@link parseStringStream} and {@link parseResponse} are used internally.
+ *
+ * If you known the type of the CSV, it performs better to use them directly.
+ *
+ * | If you want to parse a...           | Use...                    | Data are treated as... |
+ * | ----------------------------------- | ------------------------- | ---------------------- |
+ * | {@link !String}                     | {@link parseString}    | String                 |
+ * | {@link !ReadableStream}<string>     | {@link parseStringStream} | String                 |
+ * | {@link !ReadableStream}<Uint8Array> | {@link parseBinaryStream} | Binary                 |
+ * | {@link !Response}                   | {@link parseResponse}     | Binary                 |
+ *
+ * @example Parsing CSV files from strings
+ *
+ * ```ts
+ * import { parse } from 'web-csv-toolbox';
+ *
+ * const csv = `name,age
+ * Alice,42
+ * Bob,69`;
+ *
+ * for await (const record of parse(csv)) {
+ *   console.log(record);
+ * }
+ * // Prints:
+ * // { name: 'Alice', age: '42' }
+ * // { name: 'Bob', age: '69' }
+ * ```
+ *
+ * @example Parsing CSV files from streams
+ *
+ * ```ts
+ * import { parse } from 'web-csv-toolbox';
+ *
+ * const csv = `name,age
+ * Alice,42
+ * Bob,69`;
+ *
+ * const stream = new ReadableStream({
+ *   start(controller) {
+ *     controller.enqueue(csv);
+ *     controller.close();
+ *   }
+ * });
+ *
+ * for await (const record of parse(stream)) {
+ *  console.log(record);
+ * }
+ * // Prints:
+ * // { name: 'Alice', age: '42' }
+ * // { name: 'Bob', age: '69' }
+ * ```
+ *
+ *
+ * @example Parsing CSV files with headers
+ *
+ * ```ts
+ * import { parse } from 'web-csv-toolbox';
+ *
+ * // This CSV has no header.
+ * const csv = `Alice,42
+ * Bob,69`;
+ *
+ * for await (const record of parse(csv, { header: ['name', 'age'] })) {
+ *  console.log(record);
+ * }
+ * // Prints:
+ * // { name: 'Alice', age: '42' }
+ * // { name: 'Bob', age: '69' }
+ * ```
+ *
+ * @example Parsing CSV files with different delimiters characters
+ *
+ * ```ts
+ * import { parse } from 'web-csv-toolbox';
+ *
+ * const csv = `name\tage
+ * Alice\t42
+ * Bob\t69`;
+ *
+ * for await (const record of parse(csv, { delimiter: '\t' })) {
+ * console.log(record);
+ * }
+ * // Prints:
+ * // { name: 'Alice', age: '42' }
+ * // { name: 'Bob', age: '69' }
+ * ```
  */
 declare function parse<Header extends ReadonlyArray<string>>(
-  csv: string | ReadableStream<Uint8Array | string> | Response,
+  csv: string | ReadableStream<string>,
   options?: ParseOptions<Header>,
 ): AsyncIterableIterator<CSVRecord<Header>>;
+/**
+ * Parse CSV binary to records.
+ *
+ * @param csv CSV binary to parse.
+ * @param options Parsing options for CSV binary parsing.
+ *
+ * @example Parsing CSV files from responses
+ *
+ * ```ts
+ * import { parse } from 'web-csv-toolbox';
+ *
+ * // This CSV data is not gzipped and encoded in utf-8.
+ * const response = await fetch('https://example.com/data.csv');
+ *
+ * for await (const record of parse(response)) {
+ *   // ...
+ * }
+ * ```
+ *
+ * @example Parsing CSV files with options spcialized for binary
+ *
+ * ```ts
+ * import { parse } from 'web-csv-toolbox';
+ *
+ * // This CSV data is gzipped and encoded in shift-jis and has BOM.
+ * const response = await fetch('https://example.com/data.csv.gz');
+ *
+ * for await (const record of parse(response, {
+ *   charset: 'shift-jis',
+ *   ignoreBOM: true,
+ *   decomposition: 'gzip',
+ * })) {
+ *   // ...
+ * }
+ * ```
+ */
+declare function parse<Header extends ReadonlyArray<string>>(
+  csv: ReadableStream<Uint8Array> | Response,
+  options?: ParseBinaryOptions<Header>,
+): AsyncIterableIterator<CSVRecord<Header>>;
 declare namespace parse {
+  /**
+   * Parse CSV string to array of records,
+   * ideal for smaller data sets.
+   *
+   * @example Parse a CSV as array of records
+   *
+   * ```ts
+   * import { parse } from 'web-csv-toolbox';
+   *
+   * const csv = `name,age
+   * Alice,42
+   * Bob,69`;
+   *
+   * const records = await parse.toArray(csv);
+   * console.log(records);
+   * // Prints:
+   * // [ { name: 'Alice', age: '42' }, { name: 'Bob', age: '69' } ]
+   * ```
+   */
+  function toArray<Header extends ReadonlyArray<string>>(
+    csv: string | ReadableStream<string>,
+    options?: ParseOptions<Header>,
+  ): Promise<CSVRecord<Header>[]>;
+  /**
+   * Parse CSV string to array of records,
+   * ideal for smaller data sets.
+   *
+   * @example Parse a CSV as array of records
+   *
+   * ```ts
+   * import { parse } from 'web-csv-toolbox';
+   *
+   * const response = await fetch('https://example.com/data.csv');
+   *
+   * const records = await parse.toArray(response);
+   * console.log(records);
+   * ```
+   */
   function toArray<Header extends ReadonlyArray<string>>(
-    csv: string | ReadableStream<string | Uint8Array> | Response,
+    csv: ReadableStream<Uint8Array> | Response,
     options?: ParseOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
 }
@@ -332,6 +803,8 @@ export {
   type TokenType,
   parse,
   parseBinaryStream,
+  parseResponse,
+  parseStream,
+  parseString,
   parseStringStream,
-  streamingParse,
 };

package/lib/index.js

@@ -1,33 +1,13 @@
-/**
- * FiledDelimiter is a symbol for field delimiter of CSV.
- */
 const FieldDelimiter = Symbol.for("web-streams-csv.FieldDelimiter");
-/**
- * RecordDelimiter is a symbol for record delimiter of CSV.
- */
 const RecordDelimiter = Symbol.for("web-streams-csv.RecordDelimiter");
-/**
- * Field is a symbol for field of CSV.
- */
 const Field = Symbol.for("web-streams-csv.Field");
 
 const CR = "\r";
 const CRLF = "\r\n";
 const LF = "\n";
-/**
- * COMMA is a symbol for comma(,).
- */
 const COMMA = ",";
-/**
- * DOUBLE_QUATE is a symbol for double quate(").
- */
 const DOUBLE_QUATE = '"';
 
-/**
- * Assert that the options are valid.
- *
- * @param options The options to assert.
- */
 function assertCommonOptions(options) {
   if (typeof options.quotation === "string" && options.quotation.length === 0) {
     throw new Error("quotation must not be empty");
@@ -51,41 +31,10 @@ function assertCommonOptions(options) {
   }
 }
 
-/**
- * Escape a string for use in a regular expression.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions#escaping Regular expressions#Escaping | MDN}
- * @param v string to escape
- * @returns escaped string
- */
 function escapeRegExp(v) {
   return v.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-/**
- * A transform stream that converts a stream of tokens into a stream of rows.
- *
- * @example Parse a CSV with headers by data
- * ```ts
- * new ReadableStream({
- *  start(controller) {
- *   controller.enqueue("name,age\r\n");
- *  controller.enqueue("Alice,20\r\n");
- * controller.close();
- * }
- * })
- * .pipeThrough(new LexerTransformer())
- * .pipeTo(new WritableStream({ write(token) { console.log(token); }}));
- * // { type: Field, value: "name" }
- * // { type: FieldDelimiter, value: "," }
- * // { type: Field, value: "age" }
- * // { type: RecordDelimiter, value: "\r\n" }
- * // { type: Field, value: "Alice" }
- * // { type: FieldDelimiter, value: "," }
- * // { type: Field, value: "20" }
- * // { type: RecordDelimiter, value: "\r\n" }
- * ```
- */
 class LexerTransformer extends TransformStream {
   #demiliter;
   #demiliterLength;
@@ -161,49 +110,38 @@ class LexerTransformer extends TransformStream {
     if (this.#buffer.length === 0) {
       return null;
     }
-    // Check for CRLF
     if (this.#buffer.startsWith(CRLF)) {
       this.#buffer = this.#buffer.slice(2);
       return { type: RecordDelimiter, value: CRLF };
     }
-    // Check for LF
     if (this.#buffer.startsWith(LF)) {
       this.#buffer = this.#buffer.slice(1);
       return { type: RecordDelimiter, value: LF };
     }
-    // Check for Delimiter
     if (this.#buffer.startsWith(this.#demiliter)) {
       this.#buffer = this.#buffer.slice(this.#demiliterLength);
       return { type: FieldDelimiter, value: this.#demiliter };
     }
-    // Check for Quoted String
     if (this.#buffer.startsWith(this.#quotation)) {
-      // If we're flushing and the buffer doesn't end with a quote, then return null
-      // because we're not done with the quoted string
       if (flush === false && this.#buffer.endsWith(this.#quotation)) {
         return null;
       }
       return this.extractQuotedString();
     }
-    // Check for Unquoted String
     const match = this.#matcher.exec(this.#buffer);
     if (match) {
-      // If we're flushing and the match doesn't consume the entire buffer,
-      // then return null
       if (flush === false && match[0].length === this.#buffer.length) {
         return null;
       }
       this.#buffer = this.#buffer.slice(match[0].length);
       return { type: Field, value: match[0] };
     }
-    // Otherwise, return null
     return null;
   }
   extractQuotedString() {
-    let end = this.#quotationLength; // Skip the opening quote
+    let end = this.#quotationLength;
     let value = "";
     while (end < this.#buffer.length) {
-      // Escaped quote
       if (
         this.#buffer.slice(end, end + this.#quotationLength) ===
           this.quotation &&
@@ -216,7 +154,6 @@ class LexerTransformer extends TransformStream {
         end += this.#quotationLength * 2;
         continue;
       }
-      // Closing quote
       if (
         this.#buffer.slice(end, end + this.#quotationLength) === this.quotation
       ) {
@@ -226,52 +163,10 @@ class LexerTransformer extends TransformStream {
       value += this.#buffer[end];
       end++;
     }
-    // If we get here, we've reached the end of the buffer
     return null;
   }
 }
 
-/**
- * A transform stream that converts a stream of tokens into a stream of rows.
- * @template Header The type of the header row.
- * @param options The options for the parser.
- *
- * @example Parse a CSV with headers by data
- *  ```ts
- * new ReadableStream({
- *   start(controller) {
- *     controller.enqueue("name,age\r\n");
- *     controller.enqueue("Alice,20\r\n");
- *     controller.enqueue("Bob,25\r\n");
- *     controller.enqueue("Charlie,30\r\n");
- *     controller.close();
- *   })
- *   .pipeThrough(new LexerTransformer())
- *   .pipeThrough(new RecordAssemblerTransformar())
- *   .pipeTo(new WritableStream({ write(row) { console.log(row); }}));
- * // { name: "Alice", age: "20" }
- * // { name: "Bob", age: "25" }
- * // { name: "Charlie", age: "30" }
- * ```
- *
- * @example Parse a CSV with headers by options
- * ```ts
- * new ReadableStream({
- *   start(controller) {
- *     controller.enqueue("Alice,20\r\n");
- *     controller.enqueue("Bob,25\r\n");
- *     controller.enqueue("Charlie,30\r\n");
- *     controller.close();
- *   }
- * })
- * .pipeThrough(new LexerTransformer())
- * .pipeThrough(new RecordAssemblerTransformar({ header: ["name", "age"] }))
- * .pipeTo(new WritableStream({ write(row) { console.log(row); }}));
- * // { name: "Alice", age: "20" }
- * // { name: "Bob", age: "25" }
- * // { name: "Charlie", age: "30" }
- * ```
- */
 class RecordAssemblerTransformar extends TransformStream {
   #fieldIndex = 0;
   #row = [];
@@ -301,7 +196,6 @@ class RecordAssemblerTransformar extends TransformStream {
                 controller.enqueue(record);
               }
             }
-            // Reset the row fields buffer.
             this.#fieldIndex = 0;
             this.#row = new Array(this.#header?.length);
             this.#darty = false;
@@ -310,7 +204,6 @@ class RecordAssemblerTransformar extends TransformStream {
       },
       flush: (controller) => {
         if (this.#fieldIndex !== 0 && this.#header !== undefined) {
-          // console.log('B', this.#row)
           if (this.#darty) {
             const record = Object.fromEntries(
               this.#header
@@ -356,12 +249,6 @@ async function toArray(...args) {
   return rows;
 }
 
-/**
- * Parse CSV string to records.
- *
- * @param stream CSV string stream to parse
- * @param options Parsing options. See {@link ParseOptions}.
- */
 async function* parseStringStream(stream, options) {
   let controller;
   const readable = new ReadableStream({
@@ -387,48 +274,30 @@ async function* parseStringStream(stream, options) {
     reader.releaseLock();
   }
 }
-(function (parseStringStream) {})(
-  parseStringStream || (parseStringStream = {}),
-);
-parseStringStream.toArray = toArray;
+((parseStringStream) => {
+  parseStringStream.toArray = toArray;
+})(parseStringStream || (parseStringStream = {}));
 
-/**
- * Parse CSV string to records.
- *
- * @param csv CSV string to parse
- * @param options Parsing options. See {@link ParseOptions}.
- */
-async function* streamingParse(csv, options) {
+async function* parseString(csv, options) {
   yield* parseStringStream(new SingleValueReadableStream(csv), options);
 }
-(function (streamingParse) {})(streamingParse || (streamingParse = {}));
-streamingParse.toArray = toArray;
+((parseString) => {
+  parseString.toArray = toArray;
+})(parseString || (parseString = {}));
 
-/**
- * Parse CSV to records.
- * This function is for parsing a binary stream.
- *
- * @remarks
- * If you want to parse a string, use {@link streamingParse}.
- * @param stream CSV string to parse
- * @param options Parsing options. See {@link ParseBinaryOptions}.
- */
 async function* parseBinaryStream(stream, options) {
   const { charset, fatal, ignoreBOM, decomposition } = options ?? {};
   yield* parseStringStream(
     [
-      // NOTE: if decompression is undefined, it will be ignored.
       ...(decomposition ? [new DecompressionStream(decomposition)] : []),
-      // NOTE: if charset is undefined, it will be decoded as utf-8.
       new TextDecoderStream(charset, { fatal, ignoreBOM }),
     ].reduce((stream, transformer) => stream.pipeThrough(transformer), stream),
     options,
   );
 }
-(function (parseBinaryStream) {})(
-  parseBinaryStream || (parseBinaryStream = {}),
-);
-parseBinaryStream.toArray = toArray;
+((parseBinaryStream) => {
+  parseBinaryStream.toArray = toArray;
+})(parseBinaryStream || (parseBinaryStream = {}));
 
 function parseMime(contentType) {
   const [type, ...parameters] = contentType.split(";");
@@ -452,8 +321,6 @@ function parseResponse(response, options) {
   }
   const decomposition = headers.get("content-encoding") ?? undefined;
   const charset = mime.parameters.charset ?? "utf-8";
-  // TODO: Support header=present and header=absent
-  // const header = mime.parameters.header ?? "present";
   if (response.body === null) {
     throw new Error("Response body is null");
   }
@@ -463,74 +330,37 @@ function parseResponse(response, options) {
     ...options,
   });
 }
-(function (parseResponse) {})(parseResponse || (parseResponse = {}));
-parseResponse.toArray = toArray;
+((parseResponse) => {
+  parseResponse.toArray = toArray;
+})(parseResponse || (parseResponse = {}));
 
-/**
- * Parse CSV Stream to records.
- * string and Uint8Array are supported.
- *
- * @remarks
- * {@link parseStringStream} and {@link parseBinaryStream} are used internally.
- * If you known the type of the stream, it performs better to use them directly.
- *
- * If you want to parse a string, use {@link parseStringStream}.
- * If you want to parse a Uint8Array, use {@link parseBinaryStream}.
- *
- * @param csv CSV string to parse
- * @param options Parsing options. See {@link ParserOptions}.
- */
 async function* parseStream(stream, options) {
   const [branch1, branch2] = stream.tee();
   const reader1 = branch1.getReader();
   const { value: firstChunk } = await reader1.read();
   reader1.releaseLock();
-  switch (true) {
-    case typeof firstChunk === "string":
-      yield* parseStringStream(branch2, options);
-      break;
-    case firstChunk instanceof Uint8Array:
-      yield* parseBinaryStream(branch2, options);
-      break;
+  if (typeof firstChunk === "string") {
+    yield* parseStringStream(branch2, options);
+  } else if (firstChunk instanceof Uint8Array) {
+    yield* parseBinaryStream(branch2, options);
   }
 }
-(function (parseStream) {})(parseStream || (parseStream = {}));
-parseStream.toArray = toArray;
+((parseStream) => {
+  parseStream.toArray = toArray;
+})(parseStream || (parseStream = {}));
 
-/**
- * Parse CSV to records.
- *
- * {@link String}, {@link Uint8Array}, ReadableStream<string | Uint8Array> and Response are supported.
- *
- * @remarks
- * {@link streamingParse}, {@link parseBinaryStream},
- * {@link parseStringStream} and {@link parseResponse} are used internally.
- * If you known the type of the stream, it performs better to use them directly.
- *
- * If you want to parse a string, use {@link streamingParse}.
- * If you want to parse a Uint8Array, use {@link parseStream}.
- * If you want to parse a ReadableStream<string>, use {@link parseStringStream}.
- * If you want to parse a ReadableStream<Uint8Array>, use {@link parseBinaryStream}.
- * If you want to parse a Response, use {@link parseResponse}.
- *
- * @param csv CSV string to parse
- * @param options Parsing options. See {@link ParseOptions}.
- */
 async function* parse(csv, options) {
-  switch (true) {
-    case typeof csv === "string":
-      yield* streamingParse(csv, options);
-      break;
-    case csv instanceof ReadableStream:
-      yield* parseStream(csv, options);
-      break;
-    case csv instanceof Response:
-      yield* parseResponse(csv, options);
-      break;
+  if (typeof csv === "string") {
+    yield* parseString(csv, options);
+  } else if (csv instanceof ReadableStream) {
+    yield* parseStream(csv, options);
+  } else if (csv instanceof Response) {
+    yield* parseResponse(csv, options);
   }
 }
-(function (parse) {})(parse || (parse = {}));
-parse.toArray = toArray;
+((parse) => {
+  parse.toArray = toArray;
+})(parse || (parse = {}));
 
 export {
   Field,
@@ -540,6 +370,8 @@ export {
   RecordDelimiter,
   parse,
   parseBinaryStream,
+  parseResponse,
+  parseStream,
+  parseString,
   parseStringStream,
-  streamingParse,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-csv-toolbox",
-  "version": "0.0.0-next-20231225182210",
+  "version": "0.0.0-next-20231227082102",
   "description": "A CSV Toolbox utilizing Web Standard APIs.",
   "type": "module",
   "main": "lib/index.js",
@@ -27,7 +27,7 @@
     "lint": "biome lint .",
     "check": "biome check src --apply",
     "check:no-apply": "biome check src",
-    "build": "rollup -c rollup.config.ts --configPlugin rollup-plugin-typescript2 && biome format lib --write",
+    "build": "rollup -c rollup.config.ts --configPlugin rollup-plugin-typescript2 && biome check lib --apply",
     "prepare": "husky install"
   },
   "repository": {
@@ -45,7 +45,7 @@
   "bugs": {
     "url": "https://github.com/kamiazya/web-csv-toolbox/issues"
   },
-  "homepage": "https://github.com/kamiazya/web-csv-toolbox#readme",
+  "homepage": "https://kamiazya.github.io/web-csv-toolbox/",
   "devDependencies": {
     "@biomejs/biome": "1.4.1",
     "@changesets/changelog-github": "^0.5.0",
@@ -60,7 +60,8 @@
     "rollup-plugin-dts": "^6.1.0",
     "rollup-plugin-typescript2": "^0.36.0",
     "typedoc": "^0.25.4",
+    "typedoc-plugin-mdn-links": "^3.1.9",
     "typescript": "^5.3.2",
     "vitest": "^1.1.0"
   }
-}
+}