web-csv-toolbox 0.0.0-next-20240116142901 → 0.0.0-next-20240116163455

package/dist/types/parse.d.ts

@@ -0,0 +1,182 @@
+import { CSVBinary, CSVRecord, CSVString, ParseBinaryOptions, ParseOptions } from "./common/types.ts";
+/**
+ * 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 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...                        | 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
+ *
+ * ```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' }
+ * ```
+ */
+export declare function parse<Header extends ReadonlyArray<string>>(csv: CSVString, 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',
+ * })) {
+ *   // ...
+ * }
+ * ```
+ */
+export declare function parse<Header extends ReadonlyArray<string>>(csv: CSVBinary, options?: ParseBinaryOptions<Header>): AsyncIterableIterator<CSVRecord<Header>>;
+export 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: CSVString, 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: CSVBinary, options?: ParseBinaryOptions<Header>): Promise<CSVRecord<Header>[]>;
+}

package/dist/types/parseBinary.d.ts

@@ -0,0 +1,113 @@
+import { CSVRecord, ParseBinaryOptions } from "./common/types.ts";
+/**
+ * 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);
+ * }
+ * ```
+ */
+export declare function parseBinary<Header extends ReadonlyArray<string>>(bytes: Uint8Array | ArrayBuffer, options?: ParseBinaryOptions<Header>): AsyncIterableIterator<CSVRecord<Header>>;
+export 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>>;
+}

package/dist/types/parseBinaryToArraySync.d.ts

@@ -0,0 +1,2 @@
+import { CSVRecord, ParseBinaryOptions } from "./common/types.ts";
+export declare function parseBinaryToArraySync<Header extends ReadonlyArray<string>>(binary: Uint8Array | ArrayBuffer, options?: ParseBinaryOptions<Header>): CSVRecord<Header>[];

package/dist/types/parseBinaryToIterableIterator.d.ts

@@ -0,0 +1,2 @@
+import { CSVRecord, ParseBinaryOptions } from "./common/types.ts";
+export declare function parseBinaryToIterableIterator<Header extends ReadonlyArray<string>>(binary: Uint8Array | ArrayBuffer, options?: ParseBinaryOptions<Header>): IterableIterator<CSVRecord<Header>>;

package/dist/types/parseBinaryToStream.d.ts

@@ -0,0 +1,2 @@
+import { CSVRecord, ParseBinaryOptions } from "./common/types.ts";
+export declare function parseBinaryToStream<Header extends ReadonlyArray<string>>(binary: Uint8Array | ArrayBuffer, options?: ParseBinaryOptions<Header>): ReadableStream<CSVRecord<Header>>;

package/dist/types/parseResponse.d.ts

@@ -0,0 +1,80 @@
+import { CSVRecord, ParseOptions } from "./common/types.ts";
+/**
+ * Parse HTTP Response what contains CSV to records,
+ * ideal for smaller data sets.
+ *
+ * @remarks
+ * This function automatically treats response headers.
+ *
+ * - 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);
+ * }
+ * ```
+ */
+export declare function parseResponse<Header extends ReadonlyArray<string>>(response: Response, options?: ParseOptions<Header>): AsyncIterableIterator<CSVRecord<Header>>;
+export 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 Response to stream 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 toStream<Header extends ReadonlyArray<string>>(response: Response, options?: ParseOptions<Header>): ReadableStream<CSVRecord<Header>[]>;
+}

package/dist/types/parseResponseToStream.d.ts

@@ -0,0 +1,2 @@
+import { CSVRecord, ParseBinaryOptions } from "./common/types.ts";
+export declare function parseResponseToStream<Header extends ReadonlyArray<string>>(response: Response, options?: ParseBinaryOptions<Header>): ReadableStream<CSVRecord<Header>>;

package/dist/types/parseString.d.ts

@@ -0,0 +1,120 @@
+import { CSVRecord, ParseOptions } from "./common/types.ts";
+/**
+ * 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' }
+ * ```
+ */
+export declare function parseString<Header extends ReadonlyArray<string>>(csv: string, options?: ParseOptions<Header>): AsyncIterableIterator<CSVRecord<Header>>;
+export 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>>(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>>;
+}

package/dist/types/parseStringStream.d.ts

@@ -0,0 +1,98 @@
+import { CSVRecord, ParseOptions } from "./common/types.ts";
+/**
+ * Parse CSV string stream to records.
+ *
+ * @category Middle-level API
+ * @param stream CSV string stream to parse
+ * @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' }
+ * ```
+ */
+export declare function parseStringStream<Header extends ReadonlyArray<string>>(stream: ReadableStream<string>, options?: ParseOptions<Header>): AsyncIterableIterator<CSVRecord<Header>>;
+export 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<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>>;
+}

package/dist/types/parseStringStreamToStream.d.ts

@@ -0,0 +1,2 @@
+import { CSVRecord, ParseOptions } from "./common/types.ts";
+export declare function parseStringStreamToStream<Header extends ReadonlyArray<string>>(stream: ReadableStream<string>, options?: ParseOptions<Header>): ReadableStream<CSVRecord<Header>>;

package/dist/types/parseStringToArraySync.d.ts

@@ -0,0 +1,2 @@
+import { CSVRecord, ParseOptions } from "./common/types.ts";
+export declare function parseStringToArraySync<Header extends ReadonlyArray<string>>(csv: string, options?: ParseOptions<Header>): CSVRecord<Header>[];

package/dist/types/parseStringToIterableIterator.d.ts

@@ -0,0 +1,2 @@
+import { CSVRecord, ParseOptions } from "./common/types.ts";
+export declare function parseStringToIterableIterator<Header extends ReadonlyArray<string>>(csv: string, options?: ParseOptions<Header>): IterableIterator<CSVRecord<Header>>;

package/dist/types/parseStringToStream.d.ts

@@ -0,0 +1,2 @@
+import { CSVRecord, ParseOptions } from "./common/types.ts";
+export declare function parseStringToStream<Header extends ReadonlyArray<string>>(csv: string, options?: ParseOptions<Header>): ReadableStream<CSVRecord<Header>>;