web-csv-toolbox 0.3.2 → 0.5.0

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.
    *
@@ -170,6 +176,28 @@ type CSVRecord<Header extends ReadonlyArray<string>> = Record<
   Header[number],
   string
 >;
+/**
+ * CSV String.
+ *
+ * @category Types
+ */
+type CSVString = string | ReadableStream<string>;
+/**
+ * CSV Binary.
+ *
+ * @category Types
+ */
+type CSVBinary =
+  | ReadableStream<Uint8Array>
+  | Response
+  | ArrayBuffer
+  | Uint8Array;
+/**
+ * CSV.
+ *
+ * @category Types
+ */
+type CSV = CSVString | CSVBinary;
 
 /**
  * A transform stream that converts a stream of tokens into a stream of rows.
@@ -179,30 +207,30 @@ type CSVRecord<Header extends ReadonlyArray<string>> = Record<
  * @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);
 }
 
 /**
@@ -223,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" }
@@ -241,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>);
 }
 
@@ -309,6 +336,213 @@ 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>>;
+}
+
+/**
+ * Parse a binary from an {@link !Uint8Array}.
+ *
+ * @category Middle-level API
+ *
+ * @param bytes CSV bytes to parse.
+ * @param options Parsing options
+ * @returns Async iterable iterator of records.
+ *
+ * @example Parsing CSV binary
+ *
+ * ```ts
+ * import { parseUint8Array } from 'web-csv-toolbox';
+ *
+ * const csv = Uint8Array.from([
+ *   // ...
+ * ]);
+ *
+ * for await (const record of parseUint8Array(csv)) {
+ *   console.log(record);
+ * }
+ * ```
+ */
+declare function parseBinary<Header extends ReadonlyArray<string>>(
+  bytes: Uint8Array | ArrayBuffer,
+  options?: ParseBinaryOptions<Header>,
+): AsyncIterableIterator<CSVRecord<Header>>;
+declare namespace parseBinary {
+  /**
+   * 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 = await parseUint8Array.toArray(csv);
+   * ```
+   */
+  function toArray<Header extends ReadonlyArray<string>>(
+    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>>;
 }
 
 /**
@@ -319,15 +553,15 @@ declare namespace parseString {
  * @remarks
  * If you want to parse a string, use {@link parseStringStream}.
  * @param stream CSV string to parse
- * @param options Parsing options. See {@link ParseBinaryOptions}.
+ * @param options Parsing options.
  * @returns Async iterable iterator of records.
  *
- * If you want array of records, use {@link parseBinaryStream.toArray} function.
+ * If you want array of records, use {@link parseUint8ArrayStream.toArray} function.
  *
  * @example Parsing CSV binary
  *
  * ```ts
- * import { parseBinaryStream } from 'web-csv-toolbox';
+ * import { parseUint8ArrayStream } from 'web-csv-toolbox';
  *
  * const csv = Uint8Array.from([
  *  // ...
@@ -340,16 +574,16 @@ declare namespace parseString {
  *   },
  * });
  *
- * for await (const record of parseBinaryStream(csv)) {
- * console.log(record);
+ * for await (const record of parseUint8ArrayStream(csv)) {
+ *   console.log(record);
  * }
  * ```
  */
-declare function parseBinaryStream<Header extends ReadonlyArray<string>>(
+declare function parseUint8ArrayStream<Header extends ReadonlyArray<string>>(
   stream: ReadableStream<Uint8Array>,
   options?: ParseBinaryOptions<Header>,
 ): AsyncIterableIterator<CSVRecord<Header>>;
-declare namespace parseBinaryStream {
+declare namespace parseUint8ArrayStream {
   /**
    * Parse CSV binary to array of records,
    * ideal for smaller data sets.
@@ -358,7 +592,7 @@ declare namespace parseBinaryStream {
    *
    * @example Parsing CSV binary
    * ```ts
-   * import { parseBinaryStream } from 'web-csv-toolbox';
+   * import { parseUint8ArrayStream } from 'web-csv-toolbox';
    *
    * const csv = Uint8Array.from([
    *   // ...
@@ -371,7 +605,7 @@ declare namespace parseBinaryStream {
    *   },
    * });
    *
-   * const records = await parseBinaryStream.toArray(stream);
+   * const records = await parseUint8ArrayStream.toArray(stream);
    * console.log(records);
    * ```
    */
@@ -379,6 +613,39 @@ declare namespace parseBinaryStream {
     stream: ReadableStream<Uint8Array>,
     options?: ParseBinaryOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
+  /**
+   * Parse CSV binary to array of records.
+   *
+   * @returns Stream of records
+   *
+   * @example Parsing CSV binary
+   * ```ts
+   * import { parseUint8ArrayStream } from 'web-csv-toolbox';
+   *
+   * const csv = Uint8Array.from([
+   *  // ...
+   * ]);
+   *
+   * const stream = new ReadableStream({
+   *  start(controller) {
+   *   controller.enqueue(csv);
+   *  controller.close();
+   * },
+   * });
+   *
+   * await parseUint8ArrayStream.toStream(stream)
+   *   .pipeTo(new WritableStream({
+   *     write(record) {
+   *       console.log(record);
+   *     },
+   *   }),
+   * );
+   * ```
+   */
+  function toStream<Header extends ReadonlyArray<string>>(
+    stream: ReadableStream<Uint8Array>,
+    options?: ParseBinaryOptions<Header>,
+  ): ReadableStream<CSVRecord<Header>[]>;
 }
 
 /**
@@ -408,7 +675,7 @@ declare namespace parseBinaryStream {
  * });
  *
  * for await (const record of parseStringStream(csv)) {
- *  console.log(record);
+ *   console.log(record);
  * }
  * // Prints:
  * // { name: 'Alice', age: '42' }
@@ -451,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>>;
 }
 
 /**
@@ -510,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 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}.
- *
- * @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>[]>;
 }
 
 /**
@@ -610,17 +860,18 @@ declare namespace parseStream {
  * @category High-level API
  *
  * @remarks
- * {@link parseString}, {@link parseBinaryStream},
+ * {@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 parseBinaryStream} | Binary                 |
- * | {@link !Response}                   | {@link parseResponse}     | 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
  *
@@ -699,7 +950,7 @@ declare namespace parseStream {
  * ```
  */
 declare function parse<Header extends ReadonlyArray<string>>(
-  csv: string | ReadableStream<string>,
+  csv: CSVString,
   options?: ParseOptions<Header>,
 ): AsyncIterableIterator<CSVRecord<Header>>;
 /**
@@ -739,7 +990,7 @@ declare function parse<Header extends ReadonlyArray<string>>(
  * ```
  */
 declare function parse<Header extends ReadonlyArray<string>>(
-  csv: ReadableStream<Uint8Array> | Response,
+  csv: CSVBinary,
   options?: ParseBinaryOptions<Header>,
 ): AsyncIterableIterator<CSVRecord<Header>>;
 declare namespace parse {
@@ -763,7 +1014,7 @@ declare namespace parse {
    * ```
    */
   function toArray<Header extends ReadonlyArray<string>>(
-    csv: string | ReadableStream<string>,
+    csv: CSVString,
     options?: ParseOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
   /**
@@ -782,29 +1033,34 @@ declare namespace parse {
    * ```
    */
   function toArray<Header extends ReadonlyArray<string>>(
-    csv: ReadableStream<Uint8Array> | Response,
-    options?: ParseOptions<Header>,
+    csv: CSVBinary,
+    options?: ParseBinaryOptions<Header>,
   ): Promise<CSVRecord<Header>[]>;
 }
 
 export {
   type BinaryOptions,
+  type CSV,
+  type CSVBinary,
   type CSVRecord,
+  type CSVString,
   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,
-  parseBinaryStream,
+  parseBinary,
   parseResponse,
-  parseStream,
   parseString,
   parseStringStream,
+  parseUint8ArrayStream,
 };