web-csv-toolbox 0.5.2 → 0.6.0

package/dist/types/common/types.d.ts

@@ -0,0 +1,163 @@
+import { Field, FieldDelimiter, RecordDelimiter } from "./constants.ts";
+/**
+ * Field token type.
+ * @category Types
+ */
+export interface FieldToken {
+    type: typeof Field;
+    value: string;
+}
+/**
+ * Token is a atomic unit of a CSV file.
+ * It can be a field, field delimiter, or record delimiter.
+ * @category Types
+ */
+export type Token = FieldToken | typeof FieldDelimiter | typeof RecordDelimiter;
+/**
+ * CSV Common Options.
+ * @category Types
+ */
+export interface CommonOptions {
+    /**
+     * CSV field delimiter.
+     *
+     * @remarks
+     * If you want to parse TSV, specify `'\t'`.
+     *
+     * This library supports multi-character delimiters.
+     * @default ','
+     */
+    delimiter?: string;
+    /**
+     * CSV field quotation.
+     *
+     * @remarks
+     * This library supports multi-character quotations.
+     *
+     * @default '"'
+     */
+    quotation?: string;
+}
+/**
+ * CSV Parsing Options for binary.
+ * @category Types
+ */
+export 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 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']`,
+ * 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.
+ */
+export 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.
+ * @category Types
+ */
+export interface ParseOptions<Header extends ReadonlyArray<string>> extends CommonOptions, RecordAssemblerOptions<Header> {
+}
+/**
+ * Parse options for CSV binary.
+ * @category Types
+ */
+export 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"]
+ * ```ts
+ * const record: CSVRecord<["foo", "bar"]> = {
+ *   foo: "1",
+ *   bar: "2",
+ * };
+ * ```
+ */
+export type CSVRecord<Header extends ReadonlyArray<string>> = Record<Header[number], string>;
+/**
+ * CSV String.
+ *
+ * @category Types
+ */
+export type CSVString = string | ReadableStream<string>;
+/**
+ * CSV Binary.
+ *
+ * @category Types
+ */
+export type CSVBinary = ReadableStream<Uint8Array> | Response | ArrayBuffer | Uint8Array;
+/**
+ * CSV.
+ *
+ * @category Types
+ */
+export type CSV = CSVString | CSVBinary;

package/dist/types/constants.d.ts

@@ -0,0 +1,11 @@
+export declare const CR = "\r";
+export declare const CRLF = "\r\n";
+export declare const LF = "\n";
+/**
+ * COMMA is a symbol for comma(,).
+ */
+export declare const COMMA = ",";
+/**
+ * DOUBLE_QUOTE is a symbol for double quote(").
+ */
+export declare const DOUBLE_QUOTE = "\"";

package/dist/types/convertBinaryToString.d.ts

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

package/dist/types/escapeField.d.ts

@@ -0,0 +1,13 @@
+import { CommonOptions } from "./common/types.ts";
+export interface EscapeFieldOptions extends CommonOptions {
+    quote?: true;
+}
+/**
+ * Escape the field.
+ *
+ * DO NOT USE THIS FUNCTION BEFORE ASSTPTED BY `{@link assertCommonOptions}`.
+ * @param value The field value to escape.
+ * @param options The options.
+ * @returns The escaped field.
+ */
+export declare function escapeField(value: string, { quotation, delimiter, quote, }?: EscapeFieldOptions): string;

package/dist/types/getOptionsFromResponse.d.ts

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

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