refactor: #69 Dynamic Type Inference and User-Defined Types from CSV Headers

src/Lexer.ts

@@ -1,14 +1,17 @@
 import { assertCommonOptions } from "./assertCommonOptions.ts";
 import { Field, FieldDelimiter, RecordDelimiter } from "./common/constants.ts";
 import { ParseError } from "./common/errors.ts";
+import type { Position, RecordDelimiterToken } from "./common/types.ts";
+
+
 import type {
   AbortSignalOptions,
   CommonOptions,
   Position,
   RecordDelimiterToken,
   Token,
 } from "./common/types.ts";
-import { COMMA, CRLF, DOUBLE_QUOTE, LF } from "./constants.ts";
+import { COMMA, CRLF, DEFAULT_DELIMITER, DEFAULT_QUOTATION, DOUBLE_QUOTE, LF } from "./constants.ts";
 import { escapeRegExp } from "./utils/escapeRegExp.ts";
 
 /**
@@ -38,8 +41,8 @@ export class Lexer {
    * @param options - The common options for the lexer.
    */
   constructor({
-    delimiter = COMMA,
-    quotation = DOUBLE_QUOTE,
+    delimiter = DEFAULT_DELIMITER,
+    quotation = DEFAULT_QUOTATION,
     signal,
   }: CommonOptions & AbortSignalOptions = {}) {
     assertCommonOptions({ delimiter, quotation });

src/common/types.ts

@@ -1,3 +1,5 @@
+import type { DEFAULT_DELIMITER, DEFAULT_QUOTATION } from "../constants.ts";
+import type { Join } from "../utils/types.ts";
 import type { Field, FieldDelimiter, RecordDelimiter } from "./constants.ts";
 
 /**
@@ -285,7 +287,15 @@ export type CSVRecord<Header extends ReadonlyArray<string>> = Record<
  *
  * @category Types
  */
-export type CSVString = string | ReadableStream<string>;
+export type CSVString<
+  Header extends ReadonlyArray<string> = [],
+  Delimiter extends string = DEFAULT_DELIMITER,
+  Quotation extends string = DEFAULT_QUOTATION,
+> = Header extends readonly [string, ...string[]]
+  ?
+      | Join<Header, Delimiter, Quotation>
+      | ReadableStream<Join<Header, Delimiter, Quotation>>
+  : string | ReadableStream<string>;
 
 /**
  * CSV Binary.
@@ -303,4 +313,10 @@ export type CSVBinary =
  *
  * @category Types
  */
-export type CSV = CSVString | CSVBinary;
+export type CSV<
+  Header extends ReadonlyArray<string> = [],
+  Delimiter extends string = DEFAULT_DELIMITER,
+  Quotation extends string = DEFAULT_QUOTATION,
+> = Header extends []
+  ? CSVString | CSVBinary
+  : CSVString<Header, Delimiter, Quotation>;

src/constants.ts

@@ -1,6 +1,13 @@
 export const CR = "\r";
+export type CR = typeof CR;
+
 export const CRLF = "\r\n";
+export type CRLF = typeof CRLF;
+
 export const LF = "\n";
+export type LF = typeof LF;
+
+export type Newline = CRLF | CR | LF;
 
 /**
  * COMMA is a symbol for comma(,).
@@ -11,3 +18,9 @@ export const COMMA = ",";
  * DOUBLE_QUOTE is a symbol for double quote(").
  */
 export const DOUBLE_QUOTE = '"';
+
+export const DEFAULT_DELIMITER = COMMA;
+export type DEFAULT_DELIMITER = typeof DEFAULT_DELIMITER;
+
+export const DEFAULT_QUOTATION = DOUBLE_QUOTE;
+export type DEFAULT_QUOTATION = typeof DEFAULT_QUOTATION;

src/escapeField.ts

@@ -1,6 +1,6 @@
 import type { assertCommonOptions } from "./assertCommonOptions.ts";
 import type { CommonOptions } from "./common/types.ts";
-import { COMMA, DOUBLE_QUOTE } from "./constants.ts";
+import { DEFAULT_DELIMITER, DEFAULT_QUOTATION } from "./constants.ts";
 import { occurrences } from "./utils/occurrences.ts";
 
 export interface EscapeFieldOptions extends CommonOptions {
@@ -20,8 +20,8 @@ const REPLACED_PATTERN_CACHE = new Map<string, string>();
 export function escapeField(
   value: string,
   {
-    quotation = DOUBLE_QUOTE,
-    delimiter = COMMA,
+    delimiter = DEFAULT_DELIMITER,
+    quotation = DEFAULT_QUOTATION,
     quote,
   }: EscapeFieldOptions = {},
 ): string {

src/parse.test-d.ts

@@ -0,0 +1,234 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { parse } from "./parse.ts";
+import type {
+  CSV,
+  CSVBinary,
+  CSVRecord,
+  CSVString,
+  ParseOptions,
+} from "./web-csv-toolbox.ts";
+
+describe("parse function", () => {
+  it("parse should be a function with expected parameter types", () => {
+    expectTypeOf(parse).toBeFunction();
+    expectTypeOf(parse).parameter(0).toMatchTypeOf<CSV>();
+    expectTypeOf(parse)
+      .parameter(1)
+      .toMatchTypeOf<ParseOptions<readonly string[]> | undefined>();
+  });
+});
+
+describe("binary parsing", () => {
+  it("should CSV header of the parsed result will be string array", () => {
+    expectTypeOf(parse({} as CSVBinary)).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly string[]>>
+    >();
+  });
+});
+
+describe("string parsing", () => {
+  it("should CSV header of the parsed result will be string array", () => {
+    expectTypeOf(parse("" as string)).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly string[]>>
+    >();
+
+    expectTypeOf(parse({} as ReadableStream)).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly string[]>>
+    >();
+
+    expectTypeOf(parse({} as ReadableStream<string>)).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly string[]>>
+    >();
+
+    expectTypeOf(parse("" as CSVString)).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly string[]>>
+    >();
+  });
+});
+
+describe("csv literal string parsing", () => {
+  const csv1 = `name,age,city,zip
+Alice,24,New York,10001
+Bob,36,Los Angeles,90001`;
+
+  it("should csv header of the parsed result will be header's tuple", () => {
+    expectTypeOf(parse(csv1)).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse("" as CSVString<readonly ["name", "age", "city", "zip"]>),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse("" as CSV<readonly ["name", "age", "city", "zip"]>),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(parse(new ReadableStream<typeof csv1>())).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+  });
+});
+
+describe("csv literal string parsing with line breaks, quotation, newline", () => {
+  const csv1 = `$name$*$*ag
+e
+$*$city$*$z*i
+p*$
+Alice*24*New York*$1000
+$1$
+Bob*$36$*$Los$
+Angeles$*90001`;
+
+  it("should csv header of the parsed result will be header's tuple", () => {
+    expectTypeOf(parse(csv1, { delimiter: "*", quotation: "$" })).toEqualTypeOf<
+      AsyncIterableIterator<
+        CSVRecord<readonly ["name", "*ag\ne\n", "city", "z*i\np*"]>
+      >
+    >();
+
+    expectTypeOf(
+      parse("" as CSVString<readonly ["name", "age\n", "city", "zi\np"]>),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<
+        CSVRecord<readonly ["name", "age\n", "city", "zi\np"]>
+      >
+    >();
+
+    expectTypeOf(
+      parse("" as CSV<readonly ["name", "age\n", "city", "zi\np"]>),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<
+        CSVRecord<readonly ["name", "age\n", "city", "zi\np"]>
+      >
+    >();
+
+    expectTypeOf(
+      parse(new ReadableStream<typeof csv1>(), {
+        delimiter: "*",
+        quotation: "$",
+      }),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<
+        CSVRecord<readonly ["name", "*ag\ne\n", "city", "z*i\np*"]>
+      >
+    >();
+  });
+});
+
+describe("generics", () => {
+  it("should CSV header of the parsed result should be the one specified in generics", () => {
+    expectTypeOf(
+      parse<readonly ["name", "age", "city", "zip"]>(""),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<readonly ["name", "age", "city", "zip"]>({} as CSVBinary),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<readonly ["name", "age", "city", "zip"]>({} as ReadableStream),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<readonly ["name", "age", "city", "zip"]>(
+        {} as ReadableStream<string>,
+      ),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<readonly ["name", "age", "city", "zip"]>("" as CSVString),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<string, readonly ["name", "age", "city", "zip"]>(""),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<ReadableStream, readonly ["name", "age", "city", "zip"]>(
+        {} as ReadableStream,
+      ),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<ReadableStream<string>, readonly ["name", "age", "city", "zip"]>(
+        {} as ReadableStream<string>,
+      ),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<CSVString, readonly ["name", "age", "city", "zip"]>(
+        "" as CSVString,
+      ),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<string, "#", "$", readonly ["name", "age", "city", "zip"]>("", {
+        delimiter: "#",
+        quotation: "$",
+      }),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<ReadableStream, "#", "$", readonly ["name", "age", "city", "zip"]>(
+        {} as ReadableStream,
+        {
+          delimiter: "#",
+          quotation: "$",
+        },
+      ),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<
+        ReadableStream<string>,
+        "#",
+        "$",
+        readonly ["name", "age", "city", "zip"]
+      >({} as ReadableStream<string>, {
+        delimiter: "#",
+        quotation: "$",
+      }),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+
+    expectTypeOf(
+      parse<CSVString, "#", "$", readonly ["name", "age", "city", "zip"]>(
+        "" as CSVString,
+        {
+          delimiter: "#",
+          quotation: "$",
+        },
+      ),
+    ).toEqualTypeOf<
+      AsyncIterableIterator<CSVRecord<readonly ["name", "age", "city", "zip"]>>
+    >();
+  });
+});

src/parse.ts

@@ -6,12 +6,14 @@ import type {
   ParseBinaryOptions,
   ParseOptions,
 } from "./common/types.ts";
+import type { DEFAULT_DELIMITER, DEFAULT_QUOTATION } from "./constants.ts";
 import { parseBinary } from "./parseBinary.ts";
 import { parseResponse } from "./parseResponse.ts";
 import { parseString } from "./parseString.ts";
 import { parseStringStream } from "./parseStringStream.ts";
 import { parseUint8ArrayStream } from "./parseUint8ArrayStream.ts";
 import * as internal from "./utils/convertThisAsyncIterableIteratorToArray.ts";
+import type { PickCSVHeader } from "./utils/types.ts";
 
 /**
  * Parse CSV to records.
@@ -118,6 +120,29 @@ import * as internal from "./utils/convertThisAsyncIterableIteratorToArray.ts";
  * // { name: 'Bob', age: '69' }
  * ```
  */
+export function parse<
+  CSVSource extends CSVString,
+  Delimiter extends string = DEFAULT_DELIMITER,
+  Quotation extends string = DEFAULT_QUOTATION,
+  Header extends ReadonlyArray<string> = PickCSVHeader<
+    CSVSource,
+    Delimiter,
+    Quotation
+  >,
+>(
+  csv: CSVSource,
+  options: ParseOptions<Header> & {
+    delimiter?: Delimiter;
+    quotation?: Quotation;
+  },
+): AsyncIterableIterator<CSVRecord<Header>>;
+export function parse<
+  CSVSource extends CSVString,
+  Header extends ReadonlyArray<string> = PickCSVHeader<CSVSource>,
+>(
+  csv: CSVSource,
+  options?: ParseOptions<Header>,
+): AsyncIterableIterator<CSVRecord<Header>>;
 export function parse<Header extends ReadonlyArray<string>>(
   csv: CSVString,
   options?: ParseOptions<Header>,

src/parseString.spec.ts

@@ -55,7 +55,7 @@ describe("parseString function", () => {
 
   it("should throw an error if options is invalid", () => {
     expect(async () => {
-      for await (const _ of parseString("", { delimiter: "" })) {
+      for await (const _ of parseString<"">("", { delimiter: "" })) {
         // Do nothing.
       }
     }).rejects.toThrowErrorMatchingInlineSnapshot(