vku-sdk 1.0.0

package/src/modules/shared/parsers/html-table.parser.ts

@@ -0,0 +1,320 @@
+import * as cheerio from "cheerio";
+import { IParser } from "../../../core";
+import type { Element } from "domhandler";
+
+export interface TableCell {
+  [key: string]: string;
+}
+
+export interface TableCellWithRawHTML extends TableCell {
+  rawHTML: string;
+}
+
+export interface ParserOptions {
+  headerRowIndex?: number;
+  skipRows?: number[];
+  useFirstColumnAsKey?: boolean;
+  trimWhitespace?: boolean;
+  includeRawHTML?: boolean;
+}
+
+interface CellData {
+  value: string;
+  rowspan: number;
+  colspan: number;
+}
+
+type CellMatrix = (CellData | null)[][];
+
+export class HtmlTableParser implements IParser<
+  TableCell[] | TableCellWithRawHTML[]
+> {
+  private options: Required<ParserOptions>;
+  private rowElements: Map<number, Element>;
+
+  constructor(options: ParserOptions = {}) {
+    this.options = {
+      headerRowIndex: options.headerRowIndex ?? 0,
+      skipRows: options.skipRows ?? [],
+      useFirstColumnAsKey: options.useFirstColumnAsKey ?? false,
+      trimWhitespace: options.trimWhitespace ?? true,
+      includeRawHTML: options.includeRawHTML ?? true,
+    };
+    this.rowElements = new Map();
+  }
+
+  public parse(html: string): TableCell[] | TableCellWithRawHTML[] {
+    const $ = cheerio.load(html);
+    const table = this.findTable($);
+
+    if (!table || table.length === 0) {
+      throw new Error("No table found in HTML");
+    }
+    const rows = table.find("tr").toArray();
+    if (rows.length === 0) {
+      return [];
+    }
+
+    const cellMatrix = this.buildCellMatrix($, rows);
+    const headers = this.extractHeaders(cellMatrix);
+    const data = this.convertToObjects($, cellMatrix, headers);
+
+    return data;
+  }
+
+  private findTable($: cheerio.CheerioAPI): cheerio.Cheerio<Element> {
+    return $("table").first();
+  }
+
+  private buildCellMatrix($: cheerio.CheerioAPI, rows: Element[]): CellMatrix {
+    const matrix: CellMatrix = [];
+
+    rows.forEach((row, rowIndex) => {
+      if (this.shouldSkipRow(rowIndex)) {
+        return;
+      }
+
+      // Store row element for later HTML extraction
+      this.rowElements.set(rowIndex, row);
+
+      this.initializeMatrixRow(matrix, rowIndex);
+
+      const cells = $(row).find("td, th").toArray();
+      this.processCells($, cells, matrix, rowIndex);
+    });
+
+    return matrix;
+  }
+
+  /**
+   * Check if row should be skipped
+   */
+  private shouldSkipRow(rowIndex: number): boolean {
+    return this.options.skipRows.includes(rowIndex);
+  }
+
+  /**
+   * Initialize matrix row if not exists
+   */
+  private initializeMatrixRow(matrix: CellMatrix, rowIndex: number): void {
+    if (!matrix[rowIndex]) {
+      matrix[rowIndex] = [];
+    }
+  }
+
+  /**
+   * Process all cells in a row
+   */
+  private processCells(
+    $: cheerio.CheerioAPI,
+    cells: Element[],
+    matrix: CellMatrix,
+    rowIndex: number,
+  ): void {
+    let colIndex = 0;
+
+    cells.forEach((cell) => {
+      colIndex = this.findNextAvailableColumn(matrix, rowIndex, colIndex);
+      const cellData = this.extractCellData($, cell);
+      this.fillMatrixWithCell(matrix, cellData, rowIndex, colIndex);
+      colIndex += cellData.colspan;
+    });
+  }
+
+  /**
+   * Find next available column (skip cells occupied by rowspan/colspan)
+   */
+  private findNextAvailableColumn(
+    matrix: CellMatrix,
+    rowIndex: number,
+    startCol: number,
+  ): number {
+    let colIndex = startCol;
+    while (matrix[rowIndex][colIndex] !== undefined) {
+      colIndex++;
+    }
+    return colIndex;
+  }
+
+  /**
+   * Extract cell data including rowspan and colspan
+   */
+  private extractCellData($: cheerio.CheerioAPI, cell: Element): CellData {
+    const $cell = $(cell);
+    const rowspan = parseInt($cell.attr("rowspan") || "1", 10);
+    const colspan = parseInt($cell.attr("colspan") || "1", 10);
+    let value = $cell.text();
+
+    if (this.options.trimWhitespace) {
+      value = value.trim();
+    }
+
+    return { value, rowspan, colspan };
+  }
+
+  /**
+   * Fill matrix cells affected by rowspan and colspan
+   */
+  private fillMatrixWithCell(
+    matrix: CellMatrix,
+    cellData: CellData,
+    startRow: number,
+    startCol: number,
+  ): void {
+    for (let r = 0; r < cellData.rowspan; r++) {
+      for (let c = 0; c < cellData.colspan; c++) {
+        const targetRow = startRow + r;
+        const targetCol = startCol + c;
+
+        this.initializeMatrixRow(matrix, targetRow);
+        matrix[targetRow][targetCol] = cellData;
+      }
+    }
+  }
+
+  /**
+   * Extract headers from specified row
+   */
+  private extractHeaders(matrix: CellMatrix): string[] {
+    const headerRow = matrix[this.options.headerRowIndex] || [];
+    const headers: string[] = [];
+
+    headerRow.forEach((cell, index) => {
+      if (cell) {
+        const uniqueHeader = this.generateUniqueHeader(
+          cell.value || `column_${index}`,
+          headers,
+        );
+        headers[index] = uniqueHeader;
+      }
+    });
+
+    return headers;
+  }
+
+  /**
+   * Generate unique header name to avoid duplicates
+   */
+  private generateUniqueHeader(
+    baseName: string,
+    existingHeaders: string[],
+  ): string {
+    let uniqueName = baseName;
+    let counter = 1;
+
+    while (existingHeaders.includes(uniqueName)) {
+      uniqueName = `${baseName}_${counter}`;
+      counter++;
+    }
+
+    return uniqueName;
+  }
+
+  /**
+   * Convert cell matrix to array of objects
+   */
+  private convertToObjects(
+    $: cheerio.CheerioAPI,
+    matrix: CellMatrix,
+    headers: string[],
+  ): TableCell[] | TableCellWithRawHTML[] {
+    const result: (TableCell | TableCellWithRawHTML)[] = [];
+
+    for (let rowIndex = 0; rowIndex < matrix.length; rowIndex++) {
+      if (this.shouldSkipDataRow(rowIndex)) {
+        continue;
+      }
+
+      const rowData = this.buildRowObject(matrix[rowIndex], headers);
+
+      if (this.isValidRow(rowData)) {
+        // Add raw HTML if option is enabled
+        if (this.options.includeRawHTML && this.rowElements.has(rowIndex)) {
+          const rowElement = this.rowElements.get(rowIndex)!;
+          const rowWithHTML: TableCellWithRawHTML = {
+            ...rowData,
+            rawHTML: $.html(rowElement),
+          };
+          result.push(rowWithHTML);
+        } else {
+          result.push(rowData);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Check if data row should be skipped
+   */
+  private shouldSkipDataRow(rowIndex: number): boolean {
+    return (
+      rowIndex === this.options.headerRowIndex ||
+      this.options.skipRows.includes(rowIndex)
+    );
+  }
+
+  /**
+   * Build single row object from cells
+   */
+  private buildRowObject(
+    row: (CellData | null)[],
+    headers: string[],
+  ): TableCell {
+    const rowData: TableCell = {};
+
+    row.forEach((cell, colIndex) => {
+      if (cell && headers[colIndex]) {
+        rowData[headers[colIndex]] = cell.value;
+      }
+    });
+
+    return rowData;
+  }
+
+  /**
+   * Check if row has valid data
+   */
+  private isValidRow(rowData: TableCell): boolean {
+    return Object.keys(rowData).length > 0;
+  }
+}
+
+export class HtmlTableKeyValueParser implements IParser<
+  Record<string, TableCell>
+> {
+  private baseParser: HtmlTableParser;
+  private keyColumn: string | number;
+
+  constructor(options: ParserOptions & { keyColumn?: string | number } = {}) {
+    this.baseParser = new HtmlTableParser(options);
+    this.keyColumn = options.keyColumn ?? 0;
+  }
+
+  public parse(html: string): Record<string, TableCell> {
+    const data = this.baseParser.parse(html);
+    return this.convertToKeyValue(data);
+  }
+
+  private convertToKeyValue(data: TableCell[]): Record<string, TableCell> {
+    const result: Record<string, TableCell> = {};
+
+    data.forEach((row) => {
+      const key = this.extractKey(row);
+      if (key) {
+        result[key] = row;
+      }
+    });
+
+    return result;
+  }
+
+  private extractKey(row: TableCell): string | null {
+    if (typeof this.keyColumn === "number") {
+      const keys = Object.keys(row).filter((k) => k !== "rawHTML");
+      return keys[this.keyColumn] ? row[keys[this.keyColumn]] : null;
+    }
+    return row[this.keyColumn] || null;
+  }
+}

package/src/modules/shared/parsers/index.ts

@@ -0,0 +1 @@
+export * from "./html-table.parser";

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2020", // Mã JavaScript đầu ra (ES2020 hoặc cao hơn)
+    "module": "NodeNext", // Module system cho Node.js
+    "outDir": "./dist", // Thư mục chứa file đã biên dịch
+    "rootDir": "./src", // Thư mục chứa mã nguồn TypeScript
+    "strict": true, // Bật tất cả các kiểm tra nghiêm ngặt
+    "esModuleInterop": true, // Hỗ trợ import các module CommonJS
+    "forceConsistentCasingInFileNames": true, // Kiểm tra phân biệt hoa thường tên file
+    "skipLibCheck": true, // Bỏ qua kiểm tra type của các thư viện
+    "resolveJsonModule": true, // Cho phép import file JSON
+    "moduleResolution": "nodenext", // Cách TypeScript tìm module
+    "allowJs": true, // Cho phép biên dịch file .js
+    "noImplicitAny": true, // Không cho phép kiểu any ngầm định
+    "types": ["node"], // Bao gồm type của Node.js
+    "sourceMap": false, // Tạo file .map để debug,
+    "declaration": true
+  },
+  "include": ["src"], // Chỉ biên dịch các file trong src/
+  "exclude": ["node_modules", "dist", "*.spec.ts"], // Loại trừ các thư mục này
+}