web-csv-toolbox 0.7.5 → 0.9.0

package/dist/types/Lexer.d.ts

@@ -1,7 +1,26 @@
 import type { CommonOptions, Token } from "./common/types.ts";
+/**
+ * CSV Lexer.
+ *
+ * Lexter tokenizes CSV data into fields and records.
+ */
 export declare class Lexer {
     #private;
+    /**
+     * Constructs a new Lexer instance.
+     * @param options - The common options for the lexer.
+     */
     constructor({ delimiter, quotation, }?: CommonOptions);
+    /**
+     * Lexes the given chunk of CSV data.
+     * @param chunk - The chunk of CSV data to be lexed.
+     * @param buffering - Indicates whether the lexer is buffering or not.
+     * @returns An iterable iterator of tokens.
+     */
     lex(chunk: string | null, buffering?: boolean): IterableIterator<Token>;
+    /**
+     * Flushes the lexer and returns any remaining tokens.
+     * @returns An array of tokens.
+     */
     flush(): Token[];
 }

package/dist/types/Lexer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/assertCommonOptions.d.ts

@@ -1,7 +1,20 @@
 import type { CommonOptions } from "./common/types.ts";
 /**
- * Assert that the options are valid.
+ * Asserts that the provided options object contains all the required properties.
+ * Throws an error if any required property is missing
+ * or if the delimiter and quotation length is not 1 byte character,
+ * or if the delimiter is the same as the quotation.
  *
- * @param options The options to assert.
+ * @example
+ *
+ * ```ts
+ * assertCommonOptions({
+ *   quotation: '"',
+ *   delimiter: ',',
+ * });
+ * ```
+ *
+ * @param options - The options object to be validated.
+ * @throws {Error} If any required property is missing or if the delimiter is the same as the quotation.
  */
-export declare function assertCommonOptions(options: Required<CommonOptions>): void;
+export declare function assertCommonOptions(options: Required<CommonOptions>): asserts options is Required<CommonOptions>;

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

@@ -1,4 +1,46 @@
 import type { Field, FieldDelimiter, RecordDelimiter } from "./constants.ts";
+/**
+ * Position object.
+ */
+export interface Position {
+    /**
+     * Line number.
+     * Starts from 1.
+     */
+    line: number;
+    /**
+     * Column number.
+     * Starts from 1.
+     */
+    column: number;
+    /**
+     * Character offset.
+     * Starts from 0.
+     */
+    offset: number;
+}
+/**
+ * Token location object.
+ */
+export interface TokenLocation {
+    /**
+     * Start location.
+     */
+    start: Position;
+    /**
+     * End location.
+     */
+    end: Position;
+    /**
+     * Row number.
+     * Starts from 1.
+     *
+     * @remarks
+     * This represents the logical row number in the CSV,
+     * counting from 1 for the first row, whether it is a header or not.
+     */
+    rowNumber: number;
+}
 /**
  * Field token type.
  * @category Types
@@ -6,13 +48,32 @@ import type { Field, FieldDelimiter, RecordDelimiter } from "./constants.ts";
 export interface FieldToken {
     type: typeof Field;
     value: string;
+    location: TokenLocation;
+}
+/**
+ * Field delimiter token type.
+ * @category Types
+ */
+export interface FieldDelimiterToken {
+    type: typeof FieldDelimiter;
+    value: string;
+    location: TokenLocation;
+}
+/**
+ * Record delimiter token type.
+ * @category Types
+ */
+export interface RecordDelimiterToken {
+    type: typeof RecordDelimiter;
+    value: string;
+    location: TokenLocation;
 }
 /**
  * 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;
+export type Token = FieldToken | FieldDelimiterToken | RecordDelimiterToken;
 /**
  * CSV Common Options.
  * @category Types
@@ -20,20 +81,23 @@ export type Token = FieldToken | typeof FieldDelimiter | typeof RecordDelimiter;
 export interface CommonOptions {
     /**
      * CSV field delimiter.
+     * If you want to parse TSV, specify `'\t'`.
      *
      * @remarks
-     * If you want to parse TSV, specify `'\t'`.
+     * Detail restrictions are as follows:
+     *
+     * - Must not be empty
+     * - Must be a single character
+     *    - Multi-byte characters are not supported
+     * - Must not include CR or LF
+     * - Must not be the same as the quotation
      *
-     * This library supports multi-character delimiters.
      * @default ','
      */
     delimiter?: string;
     /**
      * CSV field quotation.
      *
-     * @remarks
-     * This library supports multi-character quotations.
-     *
      * @default '"'
      */
     quotation?: string;