web-csv-toolbox 0.0.1 → 0.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 A CSV Toolbox utilizing Web Standard APIs.
 
-## Key concepts
+## Key Concepts
 
 - Web Standards first.
   - Using the [Web Streams API](https://streams.spec.whatwg.org/).
@@ -16,7 +16,7 @@ A CSV Toolbox utilizing Web Standard APIs.
   - Works on browsers and Node.js, Deno
     - Only web standard APIs are used, so it should work with these Runtimes.
 
-## Key features
+## Key Features
 
 - Parses CSV files using the [WHATWG Streams API](https://streams.spec.whatwg.org/).
 - Supports parsing CSV files from strings, `ReadableStream`s, and `Response` objects.
@@ -51,7 +51,7 @@ for await (const record of parse(csv)) {
 // { name: 'Bob', age: '69' }
 ```
 
-## Parsing CSV files from `ReadableStream`s
+### Parsing CSV files from `ReadableStream`s
 
 ```js
 import { parse } from 'web-csv-toolbox';
@@ -123,7 +123,7 @@ for await (const record of parse(csv, { headers: ['name', 'age'] })) {
 // { name: 'Bob', age: '69' }
 ```
 
-## API
+## APIs
 
 ### High-level APIs
 

package/lib/index.d.ts

@@ -0,0 +1,337 @@
+/**
+ * FiledDelimiter is a symbol for field delimiter of CSV.
+ */
+declare const FieldDelimiter: unique symbol;
+/**
+ * RecordDelimiter is a symbol for record delimiter of CSV.
+ */
+declare const RecordDelimiter: unique symbol;
+/**
+ * Field is a symbol for field of CSV.
+ */
+declare const Field: unique symbol;
+
+/**
+ * Token is a atomic unit of a CSV file.
+ * It can be a field, field delimiter, or record delimiter.
+ *
+ * @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;
+  value: string;
+}
+/**
+ * Type of a token for CSV.
+ */
+type TokenType = typeof FieldDelimiter | typeof RecordDelimiter | typeof Field;
+/**
+ * CSV Common Options.
+ */
+interface CommonOptions {
+  /**
+   * CSV field delimiter.
+   *
+   * @remarks
+   * If you want to parse TSV, specify `'\t'`.
+   *
+   * This library supports multi-character delimiters.
+   * @default ','
+   */
+  demiliter?: string;
+  /**
+   * CSV field quotation.
+   *
+   * @remarks
+   * This library supports multi-character quotations.
+   *
+   * @default '"'
+   */
+  quotation?: string;
+}
+/**
+ * CSV Parsing Options for binary.
+ */
+interface BinaryOptions {
+  /**
+   * If the binary is compressed by a compression algorithm,
+   * the decompressed CSV can be parsed by specifying the algorithm.
+   *
+   * @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;
+  /**
+   * You can specify the character encoding of the binary.
+   *
+   * @remarks
+   * {@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.
+   *
+   * @default 'utf-8'
+   */
+  charset?: string;
+  /**
+   * If the binary has a BOM, you can specify whether to ignore it.
+   *
+   * @remarks
+   * If you specify true, the BOM will be ignored.
+   * If you specify false or not specify it, the BOM will be treated as a normal character.
+   * See {@link https://developer.mozilla.org/en-US/docs/Web/API/TextDecoderStream/ignoreBOM | TextDecoderOptions.ignoreBOM} for more information about the BOM.
+   * @default false
+   */
+  ignoreBOM?: boolean;
+  /**
+   * 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.
+   */
+  fatal?: boolean;
+}
+/**
+ * Record Assembler Options for CSV.
+ *
+ * @remarks
+ * If you specify `header: ['foo', 'bar']`,
+ * the first record will be treated as a normal record.
+ *
+ * If you don't specify `header`,
+ * the first record will be treated as a header.
+ */
+interface RecordAssemblerOptions<Header extends ReadonlyArray<string>> {
+  /**
+   * CSV header.
+   *
+   * @remarks
+   * If you specify this option,
+   * the first record will be treated as a normal record.
+   *
+   * If you don't specify this option,
+   * the first record will be treated as a header.
+   *
+   * @default undefined
+   */
+  header?: Header;
+}
+/**
+ * Parse options for CSV string.
+ */
+interface ParseOptions<Header extends ReadonlyArray<string>>
+  extends CommonOptions,
+    RecordAssemblerOptions<Header> {}
+/**
+ * Parse options for CSV binary.
+ */
+interface ParseBinaryOptions<Header extends ReadonlyArray<string>>
+  extends ParseOptions<Header>,
+    BinaryOptions {}
+/**
+ * CSV Record.
+ * @template Header Header of the CSV.
+ *
+ * @example Header is ["foo", "bar"]
+ * ```ts
+ * const record: CSVRecord<["foo", "bar"]> = {
+ *   foo: "1",
+ *   bar: "2",
+ * };
+ * ```
+ */
+type CSVRecord<Header extends ReadonlyArray<string>> = Record<
+  Header[number],
+  string
+>;
+
+/**
+ * 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" }
+ * ```
+ */
+declare class LexerTransformer extends TransformStream<string, Token> {
+  #private;
+  get demiliter(): string;
+  get quotation(): string;
+  constructor({ demiliter, quotation }?: CommonOptions);
+  private extractQuotedString;
+}
+
+/**
+ * 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" }
+ * ```
+ */
+declare class RecordAssemblerTransformar<
+  Header extends ReadonlyArray<string>,
+> extends TransformStream<Token, Record<Header[number], string | undefined>> {
+  #private;
+  constructor(options?: RecordAssemblerOptions<Header>);
+}
+
+/**
+ * Parse CSV string to records.
+ *
+ * @param csv CSV string to parse
+ * @param options Parsing options. See {@link ParseOptions}.
+ */
+declare function streamingParse<Header extends ReadonlyArray<string>>(
+  csv: string,
+  options?: ParseOptions<Header>,
+): AsyncIterableIterator<CSVRecord<Header>>;
+declare namespace streamingParse {
+  function toArray<Header extends ReadonlyArray<string>>(
+    stream: ReadableStream<Uint8Array>,
+    options?: ParseOptions<Header>,
+  ): Promise<CSVRecord<Header>[]>;
+}
+
+/**
+ * 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}.
+ */
+declare function parseBinaryStream<Header extends ReadonlyArray<string>>(
+  stream: ReadableStream<Uint8Array>,
+  options?: ParseBinaryOptions<Header>,
+): AsyncIterableIterator<CSVRecord<Header>>;
+declare namespace parseBinaryStream {
+  function toArray<Header extends ReadonlyArray<string>>(
+    stream: ReadableStream<Uint8Array>,
+    options?: ParseBinaryOptions<Header>,
+  ): Promise<CSVRecord<Header>[]>;
+}
+
+/**
+ * Parse CSV string to records.
+ *
+ * @param stream CSV string stream to parse
+ * @param options Parsing options. See {@link ParseOptions}.
+ */
+declare function parseStringStream<Header extends ReadonlyArray<string>>(
+  stream: ReadableStream<string>,
+  options?: ParseOptions<Header>,
+): AsyncIterableIterator<CSVRecord<Header>>;
+declare namespace parseStringStream {
+  function toArray<Header extends ReadonlyArray<string>>(
+    stream: ReadableStream<Uint8Array>,
+    options?: ParseOptions<Header>,
+  ): Promise<CSVRecord<Header>[]>;
+}
+
+/**
+ * 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}.
+ */
+declare function parse<Header extends ReadonlyArray<string>>(
+  csv: string | ReadableStream<Uint8Array | string> | Response,
+  options?: ParseOptions<Header>,
+): AsyncIterableIterator<CSVRecord<Header>>;
+declare namespace parse {
+  function toArray<Header extends ReadonlyArray<string>>(
+    csv: string | ReadableStream<string | Uint8Array> | Response,
+    options?: ParseOptions<Header>,
+  ): Promise<CSVRecord<Header>[]>;
+}
+
+export {
+  type BinaryOptions,
+  type CSVRecord,
+  type CommonOptions,
+  Field,
+  FieldDelimiter,
+  LexerTransformer,
+  type ParseBinaryOptions,
+  type ParseOptions,
+  type RecordAssemblerOptions,
+  RecordAssemblerTransformar,
+  RecordDelimiter,
+  type Token,
+  type TokenType,
+  parse,
+  parseBinaryStream,
+  parseStringStream,
+  streamingParse,
+};

package/lib/index.js

@@ -0,0 +1,545 @@
+/**
+ * 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");
+  }
+  if (typeof options.demiliter === "string" && options.demiliter.length === 0) {
+    throw new Error("demiliter must not be empty");
+  }
+  if (options.quotation.includes(LF) || options.quotation.includes(CR)) {
+    throw new Error("quotation must not include CR or LF");
+  }
+  if (options.demiliter.includes(LF) || options.demiliter.includes(CR)) {
+    throw new Error("demiliter must not include CR or LF");
+  }
+  if (
+    options.demiliter.includes(options.quotation) ||
+    options.quotation.includes(options.demiliter)
+  ) {
+    throw new Error(
+      "demiliter and quotation must not include each other as a substring",
+    );
+  }
+}
+
+/**
+ * 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;
+  #quotation;
+  #quotationLength;
+  #matcher;
+  #buffer = "";
+  get demiliter() {
+    return this.#demiliter;
+  }
+  get quotation() {
+    return this.#quotation;
+  }
+  constructor({ demiliter = COMMA, quotation = DOUBLE_QUATE } = {}) {
+    assertCommonOptions({ demiliter, quotation });
+    super({
+      transform: (chunk, controller) => {
+        if (chunk.length !== 0) {
+          this.#buffer += chunk;
+          for (const token of this.#tokens({ flush: false })) {
+            controller.enqueue(token);
+          }
+        }
+      },
+      flush: (controller) => {
+        for (const token of this.#tokens({ flush: true })) {
+          controller.enqueue(token);
+        }
+      },
+    });
+    this.#demiliter = demiliter;
+    this.#demiliterLength = demiliter.length;
+    this.#quotation = quotation;
+    this.#quotationLength = quotation.length;
+    const d = escapeRegExp(demiliter);
+    const q = escapeRegExp(quotation);
+    this.#matcher = new RegExp(
+      `^(?:(?!${q})(?!${d})(?![\\r\\n]))([\\S\\s\\uFEFF\\xA0]+?)(?=${q}|${d}|\\r|\\n|$)`,
+    );
+  }
+  *#tokens({ flush }) {
+    let currentField = null;
+    for (let token; (token = this.#nextToken({ flush })); ) {
+      switch (token.type) {
+        case Field:
+          if (currentField) {
+            currentField.value += token.value;
+          } else {
+            currentField = token;
+          }
+          break;
+        case FieldDelimiter:
+          if (currentField) {
+            yield currentField;
+            currentField = null;
+          }
+          yield token;
+          break;
+        case RecordDelimiter:
+          if (currentField) {
+            yield currentField;
+            currentField = null;
+          }
+          yield token;
+          break;
+      }
+    }
+    if (currentField) {
+      yield currentField;
+    }
+  }
+  #nextToken({ flush = false } = {}) {
+    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 value = "";
+    while (end < this.#buffer.length) {
+      // Escaped quote
+      if (
+        this.#buffer.slice(end, end + this.#quotationLength) ===
+          this.quotation &&
+        this.#buffer.slice(
+          end + this.#quotationLength,
+          end + this.#quotationLength * 2,
+        ) === this.quotation
+      ) {
+        value += this.quotation;
+        end += this.#quotationLength * 2;
+        continue;
+      }
+      // Closing quote
+      if (
+        this.#buffer.slice(end, end + this.#quotationLength) === this.quotation
+      ) {
+        this.#buffer = this.#buffer.slice(end + this.#quotationLength);
+        return { type: Field, value };
+      }
+      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 = [];
+  #header;
+  #darty = false;
+  constructor(options = {}) {
+    super({
+      transform: (token, controller) => {
+        switch (token.type) {
+          case Field:
+            this.#darty = true;
+            this.#row[this.#fieldIndex] = token.value;
+            break;
+          case FieldDelimiter:
+            this.#fieldIndex++;
+            break;
+          case RecordDelimiter:
+            if (this.#header === undefined) {
+              this.#setHeader(this.#row);
+            } else {
+              if (this.#darty) {
+                const record = Object.fromEntries(
+                  this.#header
+                    .filter((v) => v)
+                    .map((header, index) => [header, this.#row.at(index)]),
+                );
+                controller.enqueue(record);
+              }
+            }
+            // Reset the row fields buffer.
+            this.#fieldIndex = 0;
+            this.#row = new Array(this.#header?.length);
+            this.#darty = false;
+            break;
+        }
+      },
+      flush: (controller) => {
+        if (this.#fieldIndex !== 0 && this.#header !== undefined) {
+          // console.log('B', this.#row)
+          if (this.#darty) {
+            const record = Object.fromEntries(
+              this.#header
+                .filter((v) => v)
+                .map((header, index) => [header, this.#row.at(index)]),
+            );
+            controller.enqueue(record);
+          }
+        }
+      },
+    });
+    if (options.header !== undefined && Array.isArray(options.header)) {
+      this.#setHeader(options.header);
+    }
+  }
+  #setHeader(header) {
+    this.#header = header;
+    if (this.#header.length === 0) {
+      throw new Error("The header must not be empty.");
+    }
+    if (new Set(this.#header).size !== this.#header.length) {
+      throw new Error("The header must not contain duplicate fields.");
+    }
+  }
+}
+
+class SingleValueReadableStream extends ReadableStream {
+  constructor(value) {
+    super({
+      start(controller) {
+        controller.enqueue(value);
+        controller.close();
+      },
+    });
+  }
+}
+
+async function toArray(...args) {
+  const rows = [];
+  for await (const row of this(...args)) {
+    rows.push(row);
+  }
+  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({
+    start: (controller_) => (controller = controller_),
+  });
+  await stream
+    .pipeThrough(new LexerTransformer(options))
+    .pipeThrough(new RecordAssemblerTransformar(options))
+    .pipeTo(
+      new WritableStream({
+        write: (row) => controller.enqueue(row),
+        close: () => controller.close(),
+      }),
+    );
+  const reader = readable.getReader();
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+(function (parseStringStream) {})(
+  parseStringStream || (parseStringStream = {}),
+);
+parseStringStream.toArray = toArray;
+
+/**
+ * Parse CSV string to records.
+ *
+ * @param csv CSV string to parse
+ * @param options Parsing options. See {@link ParseOptions}.
+ */
+async function* streamingParse(csv, options) {
+  yield* parseStringStream(new SingleValueReadableStream(csv), options);
+}
+(function (streamingParse) {})(streamingParse || (streamingParse = {}));
+streamingParse.toArray = toArray;
+
+/**
+ * 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;
+
+function parseMime(contentType) {
+  const [type, ...parameters] = contentType.split(";");
+  const result = {
+    type: type.trim(),
+    parameters: {},
+  };
+  for (const paramator of parameters) {
+    const [key, value] = paramator.split("=");
+    result.parameters[key.trim()] = value.trim();
+  }
+  return result;
+}
+
+function parseResponse(response, options) {
+  const { headers } = response;
+  const contentType = headers.get("content-type") ?? "text/csv";
+  const mime = parseMime(contentType);
+  if (mime.type !== "text/csv") {
+    throw new Error(`Invalid mime type: ${contentType}`);
+  }
+  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");
+  }
+  return parseBinaryStream(response.body, {
+    decomposition,
+    charset,
+    ...options,
+  });
+}
+(function (parseResponse) {})(parseResponse || (parseResponse = {}));
+parseResponse.toArray = toArray;
+
+/**
+ * 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;
+  }
+}
+(function (parseStream) {})(parseStream || (parseStream = {}));
+parseStream.toArray = toArray;
+
+/**
+ * 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;
+  }
+}
+(function (parse) {})(parse || (parse = {}));
+parse.toArray = toArray;
+
+export {
+  Field,
+  FieldDelimiter,
+  LexerTransformer,
+  RecordAssemblerTransformar,
+  RecordDelimiter,
+  parse,
+  parseBinaryStream,
+  parseStringStream,
+  streamingParse,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-csv-toolbox",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "A CSV Toolbox utilizing Web Standard APIs.",
   "type": "module",
   "main": "lib/index.js",
@@ -21,6 +21,7 @@
     "README.md"
   ],
   "scripts": {
+    "doc": "typedoc",
     "test": "vitest",
     "format": "biome format . --write",
     "lint": "biome lint .",
@@ -47,8 +48,10 @@
   "homepage": "https://github.com/kamiazya/web-csv-toolbox#readme",
   "devDependencies": {
     "@biomejs/biome": "1.4.1",
+    "@changesets/changelog-github": "^0.5.0",
     "@changesets/cli": "^2.27.1",
-    "@fast-check/vitest": "^0.0.8",
+    "@fast-check/vitest": "^0.0.9",
+    "changesets-github-release": "^0.1.0",
     "husky": "^8.0.0",
     "jsdom": "^23.0.1",
     "lint-staged": "^15.2.0",
@@ -56,7 +59,8 @@
     "rollup-plugin-delete": "^2.0.0",
     "rollup-plugin-dts": "^6.1.0",
     "rollup-plugin-typescript2": "^0.36.0",
+    "typedoc": "^0.25.4",
     "typescript": "^5.3.2",
-    "vitest": "^0.34.6"
+    "vitest": "^1.1.0"
   }
-}
+}