web-csv-toolbox 0.1.0 → 0.3.0

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,
 };