web-csv-toolbox 0.4.0 → 0.5.0

package/README.md

@@ -253,10 +253,8 @@ catering to users who need more detailed and fine-tuned functionality.
 
 - **`function parseString(string[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseString-1.html)
   - Efficient parsing of CSV strings.
-- **`function parseArrayBuffer(buffer[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseArrayBuffer-1.html)
-  - Parse CSV Binary of ArrayBuffer.
-- **`function parseUint8Array(buffer[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseUint8Array-1.html)
-  - Parse CSV Binary of Uint8Array.
+- **`function parseBinary(buffer[, options])`**: [📑](https://kamiazya.github.io/web-csv-toolbox/functions/parseBinary-1.html)
+  - Parse CSV Binary of ArrayBuffer or Uint8Array.
 - **`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)
@@ -273,7 +271,7 @@ ideal for developers looking for in-depth control and flexibility.
 
 - **`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)
+- **`class RecordAssemblerTransformer`**: [📑](https://kamiazya.github.io/web-csv-toolbox/classes/RecordAssemblerTransformer.html)
   - Handles the assembly of parsed data into records.
 
 ## Options Configuration 🛠️

package/lib/index.d.ts

@@ -15,26 +15,32 @@ declare const RecordDelimiter: unique symbol;
 declare const Field: unique symbol;
 
 /**
- * Token is a atomic unit of a CSV file.
- * It can be a field, field delimiter, or record delimiter.
+ * Field token type.
  * @category Types
- *
- * @example
- * ```ts
- * const fieldToken: Token = { type: Field, value: "foo" };
- * const fieldDelimiterToken: Token = { type: FieldDelimiter, value: "," };
- * const recordDelimiterToken: Token = { type: RecordDelimiter, value: "\n" };
- * ```
  */
-interface Token<T extends TokenType = TokenType> {
-  type: T;
+interface FieldToken {
+  type: typeof Field;
   value: string;
 }
 /**
- * Type of a token for CSV.
+ * Field delimiter token type.
+ * @category Types
+ */
+interface FieldDelimiterToken {
+  type: typeof FieldDelimiter;
+}
+/**
+ * Record delimiter token type.
+ */
+interface RecordDelimiterToken {
+  type: typeof RecordDelimiter;
+}
+/**
+ * Token is a atomic unit of a CSV file.
+ * It can be a field, field delimiter, or record delimiter.
  * @category Types
  */
-type TokenType = typeof FieldDelimiter | typeof RecordDelimiter | typeof Field;
+type Token = FieldToken | typeof FieldDelimiter | typeof RecordDelimiter;
 /**
  * CSV Common Options.
  * @category Types
@@ -49,7 +55,7 @@ interface CommonOptions {
    * This library supports multi-character delimiters.
    * @default ','
    */
-  demiliter?: string;
+  delimiter?: string;
   /**
    * CSV field quotation.
    *
@@ -201,30 +207,30 @@ type CSV = CSVString | CSVBinary;
  * @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();
- * }
+ *   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); }}));
+ *   .pipeThrough(new LexerTransformer())
+ *   .pipeTo(new WritableStream({ write(tokens) {
+ *     for (const token of tokens) {
+ *       console.log(token);
+ *     }
+ *   }}));
  * // { type: Field, value: "name" }
- * // { type: FieldDelimiter, value: "," }
+ * // FieldDelimiter
  * // { type: Field, value: "age" }
- * // { type: RecordDelimiter, value: "\r\n" }
+ * // RecordDelimiter
  * // { type: Field, value: "Alice" }
- * // { type: FieldDelimiter, value: "," }
+ * // FieldDelimiter
  * // { type: Field, value: "20" }
- * // { type: RecordDelimiter, value: "\r\n" }
+ * // RecordDelimiter
  * ```
  */
-declare class LexerTransformer extends TransformStream<string, Token> {
-  #private;
-  get demiliter(): string;
-  get quotation(): string;
-  constructor({ demiliter, quotation }?: CommonOptions);
-  private extractQuotedString;
+declare class LexerTransformer extends TransformStream<string, Token[]> {
+  constructor(options?: CommonOptions);
 }
 
 /**
@@ -245,7 +251,7 @@ declare class LexerTransformer extends TransformStream<string, Token> {
  *     controller.close();
  *   })
  *   .pipeThrough(new LexerTransformer())
- *   .pipeThrough(new RecordAssemblerTransformar())
+ *   .pipeThrough(new RecordAssemblerTransformer())
  *   .pipeTo(new WritableStream({ write(row) { console.log(row); }}));
  * // { name: "Alice", age: "20" }
  * // { name: "Bob", age: "25" }
@@ -263,17 +269,16 @@ declare class LexerTransformer extends TransformStream<string, Token> {
  *   }
  * })
  * .pipeThrough(new LexerTransformer())
- * .pipeThrough(new RecordAssemblerTransformar({ header: ["name", "age"] }))
+ * .pipeThrough(new RecordAssemblerTransformer({ header: ["name", "age"] }))
  * .pipeTo(new WritableStream({ write(row) { console.log(row); }}));
  * // { name: "Alice", age: "20" }
  * // { name: "Bob", age: "25" }
  * // { name: "Charlie", age: "30" }
  * ```
  */
-declare class RecordAssemblerTransformar<
+declare class RecordAssemblerTransformer<
   Header extends ReadonlyArray<string>,
-> extends TransformStream<Token, Record<Header[number], string | undefined>> {
-  #private;
+> extends TransformStream<Token[], CSVRecord<Header>> {
   constructor(options?: RecordAssemblerOptions<Header>);
 }
 
@@ -331,6 +336,85 @@ declare namespace parseString {
     csv: string,
     options?: ParseOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
+  /**
+   * 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 = parseString.toArraySync(csv);
+   * console.log(records);
+   * // Prints:
+   * // [ { name: 'Alice', age: '42' }, { name: 'Bob', age: '69' } ]
+   * ```
+   */
+  function toArraySync<Header extends ReadonlyArray<string>>(
+    csv: string,
+    options?: ParseOptions<Header>,
+  ): CSVRecord<Header>[];
+  /**
+   * Parse CSV string to records.
+   *
+   * @returns Async iterable iterator of records
+   *
+   * @example
+   * ```ts
+   * import { parseString } from 'web-csv-toolbox';
+   *
+   * const csv = `name,age
+   * Alice,42
+   * Bob,69`;
+   *
+   * for (const record of parseString.toIterableIterator(csv)) {
+   *   console.log(record);
+   * }
+   * // Prints:
+   * // { name: 'Alice', age: '42' }
+   * // { name: 'Bob', age: '69' }
+   * ```
+   */
+  function toIterableIterator<Header extends ReadonlyArray<string>>(
+    csv: string,
+    options?: ParseOptions<Header>,
+  ): IterableIterator<CSVRecord<Header>>;
+  /**
+   * Parse CSV string to records.
+   *
+   * @returns Readable stream of records
+   *
+   * @example
+   * ```ts
+   * import { parseString } from 'web-csv-toolbox';
+   *
+   * const csv = `name,age
+   * Alice,42
+   * Bob,69`;
+   *
+   * await parseString.toStream(csv)
+   *   .pipeTo(
+   *      new WritableStream({
+   *        write(record) {
+   *          console.log(record);
+   *        },
+   *      }),
+   *   );
+   * // Prints:
+   * // { name: 'Alice', age: '42' }
+   * // { name: 'Bob', age: '69' }
+   * ```
+   */
+  function toStream<Header extends ReadonlyArray<string>>(
+    csv: string,
+    options?: ParseOptions<Header>,
+  ): ReadableStream<CSVRecord<Header>>;
 }
 
 /**
@@ -356,11 +440,11 @@ declare namespace parseString {
  * }
  * ```
  */
-declare function parseUint8Array<Header extends ReadonlyArray<string>>(
-  bytes: Uint8Array,
+declare function parseBinary<Header extends ReadonlyArray<string>>(
+  bytes: Uint8Array | ArrayBuffer,
   options?: ParseBinaryOptions<Header>,
 ): AsyncIterableIterator<CSVRecord<Header>>;
-declare namespace parseUint8Array {
+declare namespace parseBinary {
   /**
    * Parse a binary from an {@link !Uint8Array} to an array of records.
    *
@@ -380,9 +464,85 @@ declare namespace parseUint8Array {
    * ```
    */
   function toArray<Header extends ReadonlyArray<string>>(
-    bytes: Uint8Array,
+    bytes: Uint8Array | ArrayBuffer,
     options?: ParseBinaryOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
+  /**
+   * Parse a binary from an {@link !Uint8Array} to an array of records.
+   *
+   * @param bytes CSV bytes to parse.
+   * @param options Parsing options
+   * @returns Array of records
+   * @example
+   *
+   * ```ts
+   * import { parseUint8Array } from 'web-csv-toolbox';
+   *
+   * const csv = Uint8Array.from([
+   *  // ...
+   * ]);
+   *
+   * const records = parseUint8Array.toArraySync(csv);
+   * ```
+   */
+  function toArraySync<Header extends ReadonlyArray<string>>(
+    bytes: Uint8Array | ArrayBuffer,
+    options?: ParseBinaryOptions<Header>,
+  ): CSVRecord<Header>[];
+  /**
+   * Parse a binary from an {@link !Uint8Array} to an iterable iterator of records.
+   *
+   * @param bytes CSV bytes to parse.
+   * @param options Parsing options
+   * @returns Async iterable iterator of records.
+   * @example
+   * ```ts
+   * import { parseUint8Array } from 'web-csv-toolbox';
+   *
+   * const csv = Uint8Array.from([
+   *  // ...
+   * ]);
+   *
+   * for (const record of parseUint8Array.toIterableIterator(csv)) {
+   *   console.log(record);
+   * }
+   * ```
+   */
+  function toIterableIterator<Header extends ReadonlyArray<string>>(
+    bytes: Uint8Array,
+    options?: ParseBinaryOptions<Header>,
+  ): IterableIterator<CSVRecord<Header>>;
+  /**
+   * Parse a binary from an {@link !Uint8Array} to a stream of records.
+   *
+   * @param bytes CSV bytes to parse.
+   * @param options Parsing options
+   * @returns Stream of records.
+   *
+   * @example
+   *
+   * ```ts
+   * import { parseUint8Array } from 'web-csv-toolbox';
+   *
+   * const csv = Uint8Array.from([
+   *  // ...
+   * ]);
+   *
+   * const stream = parseUint8Array.toStream(csv);
+   *
+   * await stream.pipeTo(
+   *   new WritableStream({
+   *     write(record) {
+   *       console.log(record);
+   *     },
+   *   }),
+   * );
+   * ```
+   */
+  function toStream<Header extends ReadonlyArray<string>>(
+    bytes: Uint8Array,
+    options?: ParseBinaryOptions<Header>,
+  ): ReadableStream<CSVRecord<Header>>;
 }
 
 /**
@@ -453,66 +613,39 @@ declare namespace parseUint8ArrayStream {
     stream: ReadableStream<Uint8Array>,
     options?: ParseBinaryOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
-}
-
-/**
- * Parse a binary from an {@link !ArrayBuffer}.
- *
- * @category Middle-level API
-
- * @param buffer CSV ArrayBuffer to parse.
- * @param options Parsing options
- * @returns Async iterable iterator of records.
- *
- * @example Parsing CSV files from ArrayBuffers
- *
- * ```ts
- * import { parseArrayBuffer } from 'web-csv-toolbox';
- *
- * const csv = `name,age
- * Alice,42
- * Bob,69`;
- *
- * const buffer = new TextEncoder().encode(csv).buffer;
- *
- * for await (const record of parseArrayBuffer(buffer)) {
- *   console.log(record);
- * }
- * // Prints:
- * // { name: 'Alice', age: '42' }
- * // { name: 'Bob', age: '69' }
- * ```
- */
-declare function parseArrayBuffer<Header extends ReadonlyArray<string>>(
-  buffer: ArrayBuffer,
-  options?: ParseBinaryOptions<Header>,
-): AsyncIterableIterator<CSVRecord<Header>>;
-declare namespace parseArrayBuffer {
   /**
-   * Parse a binary from an {@link !ArrayBuffer} to an array of records.
-   * @param buffer CSV ArrayBuffer to parse.
-   * @param options Parsing options
-   * @returns Array of records
-   * @example
+   * Parse CSV binary to array of records.
+   *
+   * @returns Stream of records
+   *
+   * @example Parsing CSV binary
    * ```ts
-   * import { parseArrayBuffer } from 'web-csv-toolbox';
+   * import { parseUint8ArrayStream } from 'web-csv-toolbox';
    *
-   * const csv = `name,age
-   * Alice,42
-   * Bob,69`;
+   * const csv = Uint8Array.from([
+   *  // ...
+   * ]);
    *
-   * const buffer = new TextEncoder().encode(csv).buffer;
+   * const stream = new ReadableStream({
+   *  start(controller) {
+   *   controller.enqueue(csv);
+   *  controller.close();
+   * },
+   * });
    *
-   * const records = await parseArrayBuffer.toArray(buffer);
-   * console.log(records);
-   * // Prints:
-   * // [ { name: 'Alice', age: '42' }, { name: 'Bob', age: '69' } ]
+   * await parseUint8ArrayStream.toStream(stream)
+   *   .pipeTo(new WritableStream({
+   *     write(record) {
+   *       console.log(record);
+   *     },
+   *   }),
+   * );
    * ```
    */
-  function toArray<Header extends ReadonlyArray<string>>(
-    buffer: ArrayBuffer,
+  function toStream<Header extends ReadonlyArray<string>>(
+    stream: ReadableStream<Uint8Array>,
     options?: ParseBinaryOptions<Header>,
-  ): Promise<CSVRecord<Header>[]>;
+  ): ReadableStream<CSVRecord<Header>[]>;
 }
 
 /**
@@ -542,7 +675,7 @@ declare namespace parseArrayBuffer {
  * });
  *
  * for await (const record of parseStringStream(csv)) {
- *  console.log(record);
+ *   console.log(record);
  * }
  * // Prints:
  * // { name: 'Alice', age: '42' }
@@ -585,6 +718,41 @@ declare namespace parseStringStream {
     stream: ReadableStream<string>,
     options?: ParseOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
+  /**
+   * 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();
+   *   },
+   * });
+   *
+   * await parseStringStream.toStream(stream)
+   *   .pipeTo(
+   *     new WritableStream({
+   *       write(record) {
+   *       console.log(record);
+   *     },
+   *   }),
+   * );
+   * ```
+   */
+  function toStream<Header extends ReadonlyArray<string>>(
+    stream: ReadableStream<string>,
+    options?: ParseOptions<Header>,
+  ): ReadableStream<CSVRecord<Header>>;
 }
 
 /**
@@ -644,88 +812,36 @@ declare namespace parseResponse {
     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 parseStringStream} and {@link parseUint8ArrayStream} 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 parseUint8ArrayStream}.
- *
- * @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.
+   * Parse CSV Response to stream of records.
    *
-   * @returns Array of records
+   * @param response Response to parse
+   * @returns Stream of records
+   *
+   * @example Parsing CSV Response
+   *
+   * ```ts
+   * import { parseResponse } from 'web-csv-toolbox';
+   *
+   * const response = await fetch('https://example.com/data.csv');
+   *
+   * await parseResponse.toStream(response)
+   *   .pipeTo(
+   *     new WritableStream({
+   *       write(record) {
+   *         console.log(record);
+   *       },
+   *    }),
+   * );
+   * // Prints:
+   * // { name: 'Alice', age: '42' }
+   * // { name: 'Bob', age: '69' }
+   * ```
    */
-  function toArray<Header extends ReadonlyArray<string>>(
-    stream: ReadableStream<Uint8Array>,
-    options?: ParseBinaryOptions<Header>,
-  ): Promise<CSVRecord<Header>[]>;
+  function toStream<Header extends ReadonlyArray<string>>(
+    response: Response,
+    options?: ParseOptions<Header>,
+  ): ReadableStream<CSVRecord<Header>[]>;
 }
 
 /**
@@ -744,20 +860,18 @@ declare namespace parseStream {
  * @category High-level API
  *
  * @remarks
- * {@link parseString}, {@link parseUint8ArrayStream},
- * {@link parseArrayBuffer}, {@link parseUint8Array},
+ * {@link parseString}, {@link parseBinary}, {@link parseUint8ArrayStream},
  * {@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 parseUint8ArrayStream} | Binary                 |
- * | {@link !Response}                   | {@link parseResponse}         | Binary                 |
- * | {@link !ArrayBuffer}                | {@link parseArrayBuffer}      | Binary                 |
- * | {@link !Uint8Array}                 | {@link parseUint8Array}       | Binary                 |
+ * | If you want to parse a...                    | Use...                        | Options...                 |
+ * | -------------------------------------------- | ----------------------------- | -------------------------- |
+ * | {@link !String}                              | {@link parseString}           | {@link ParseOptions}       |
+ * | {@link !ReadableStream}<{@link !String}>     | {@link parseStringStream}     | {@link ParseOptions}       |
+ * | {@link !Uint8Array} \| {@link !ArrayBuffer}  | {@link parseBinary}           | {@link ParseBinaryOptions} |
+ * | {@link !ReadableStream}<{@link !Uint8Array}> | {@link parseUint8ArrayStream} | {@link ParseBinaryOptions} |
+ * | {@link !Response}                            | {@link parseResponse}         | {@link ParseBinaryOptions} |
  *
  * @example Parsing CSV files from strings
  *
@@ -933,20 +1047,20 @@ export {
   type CommonOptions,
   Field,
   FieldDelimiter,
+  type FieldDelimiterToken,
+  type FieldToken,
   LexerTransformer,
   type ParseBinaryOptions,
   type ParseOptions,
   type RecordAssemblerOptions,
-  RecordAssemblerTransformar,
+  RecordAssemblerTransformer,
   RecordDelimiter,
+  type RecordDelimiterToken,
   type Token,
-  type TokenType,
   parse,
-  parseArrayBuffer,
+  parseBinary,
   parseResponse,
-  parseStream,
   parseString,
   parseStringStream,
-  parseUint8Array,
   parseUint8ArrayStream,
 };