@rickcedwhat/playwright-smart-table 5.0.0 → 5.1.0

package/README.md

@@ -355,11 +355,11 @@ const allData = await table.iterateThroughTable(
   },
   {
     getIsLast: ({ paginationResult }) => !paginationResult,
-    onFirst: async ({ allData }) => {
+    beforeFirst: async ({ allData }) => {
       console.log('Starting data collection...');
       // Could perform setup actions
     },
-    onLast: async ({ allData }) => {
+    afterLast: async ({ allData }) => {
       console.log(`Collected ${allData.length} total items`);
       // Could perform cleanup or final actions
     }
@@ -369,10 +369,43 @@ const allData = await table.iterateThroughTable(
 <!-- /embed: iterate-through-table-hooks -->
 
 **Hook Timing:**
-- `onFirst`: Runs **before** your callback processes the first page
-- `onLast`: Runs **after** your callback processes the last page
+- `beforeFirst`: Runs **before** your callback processes the first page
+- `afterLast`: Runs **after** your callback processes the last page
 - Both are optional and receive `{ index, rows, allData }`
 
+#### Batching (v5.1+)
+
+Process multiple pages at once for better performance:
+
+```typescript
+const results = await table.iterateThroughTable(
+  async ({ rows, batchInfo }) => {
+    // rows contains data from multiple pages
+    console.log(`Processing pages ${batchInfo.startIndex}-${batchInfo.endIndex}`);
+    console.log(`Batch has ${rows.length} total rows from ${batchInfo.size} pages`);
+    
+    // Bulk process (e.g., batch database insert)
+    await bulkInsert(rows);
+    return rows.length;
+  },
+  { 
+    batchSize: 3  // Process 3 pages at a time
+  }
+);
+
+// With 6 pages total:
+// - Batch 1: pages 0,1,2 (batchInfo.size = 3)
+// - Batch 2: pages 3,4,5 (batchInfo.size = 3)
+// results.length === 2 (fewer callbacks than pages)
+```
+
+**Key Points:**
+- `batchSize` = number of **pages**, not rows
+- `batchInfo` is undefined when not batching (`batchSize` undefined or `1`)
+- Works with deduplication, pagination strategies, and hooks
+- Reduces callback overhead for bulk operations
+- Default: no batching (one callback per page)
+
 ---
 
 ## 📖 API Reference

package/dist/smartRow.js

@@ -11,6 +11,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSmartRow = void 0;
 const fill_1 = require("./strategies/fill");
+const stringUtils_1 = require("./utils/stringUtils");
+const traceUtils_1 = require("./utils/traceUtils");
 /**
  * Factory to create a SmartRow by extending a Playwright Locator.
  * We avoid Class/Proxy to ensure full compatibility with Playwright's expect(locator) matchers.
@@ -23,8 +25,7 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
     smart.getCell = (colName) => {
         const idx = map.get(colName);
         if (idx === undefined) {
-            const availableColumns = Array.from(map.keys());
-            throw new Error(`Column "${colName}" not found. Available: ${availableColumns.join(', ')}`);
+            throw new Error((0, stringUtils_1.buildColumnNotFoundError)(colName, Array.from(map.keys())));
         }
         if (config.strategies.getCellLocator) {
             return config.strategies.getCellLocator({
@@ -35,6 +36,8 @@ const createSmartRow = (rowLocator, map, rowIndex, config, rootLocator, resolve,
                 page: rootLocator.page()
             });
         }
+        // Add trace event
+        (0, traceUtils_1.addTraceEvent)(rootLocator.page(), 'getCell', { column: colName, columnIndex: idx, rowIndex }).catch(() => { });
         return resolve(config.cellSelector, rowLocator).nth(idx);
     };
     smart.toJSON = (options) => __awaiter(void 0, void 0, void 0, function* () {

package/dist/typeContext.d.ts

@@ -3,4 +3,4 @@
  * This file is generated by scripts/embed-types.js
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
-export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\nexport interface TableContext {\n  root: Locator;\n  config: FinalTableConfig;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport type PaginationStrategy = (context: TableContext) => Promise<boolean>;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  includeTypes?: boolean;\n}\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport type { HeaderStrategy } from './strategies/headers';\nexport type { CellNavigationStrategy } from './strategies/columns';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: string | RegExp | number };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Strategy for navigating to specific cells (row + column) */\n  cellNavigation?: CellNavigationStrategy;\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n}\n\n/**\n * Configuration options for useTable.\n */\nexport interface TableConfig {\n  /** Selector for the table headers */\n  headerSelector?: string;\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string;\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Enable debug logs */\n  debug?: boolean;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n}\n\nexport interface FinalTableConfig extends TableConfig {\n  headerSelector: string;\n  rowSelector: string;\n  cellSelector: string;\n  maxPages: number;\n  autoScroll: boolean;\n  debug: boolean;\n  headerTransformer: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\nexport interface TableResult<T = any> {\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 1-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 1-based row index\n   * @param options Optional settings including bringIntoView\n   */\n  getRowByIndex: (\n    index: number,\n    options?: { bringIntoView?: boolean }\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match, max pages, and asJSON\n   */\n  findRows: <R extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * ASYNC: Gets all rows on the current page only (does not paginate).\n   * Auto-initializes the table if not already initialized.\n   * @param options - Filter and formatting options\n   */\n  getRows: <R extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Scans a specific column across all pages and returns the values.\n   */\n  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Iterates through paginated table data, calling the callback for each iteration.\n   * Callback return values are automatically appended to allData, which is returned.\n   */\n  iterateThroughTable: <T = any>(\n    callback: (context: {\n      index: number;\n      isFirst: boolean;\n      isLast: boolean;\n      rows: SmartRow[];\n      allData: T[];\n      table: RestrictedTableResult;\n    }) => T | Promise<T>,\n    options?: {\n      pagination?: PaginationStrategy;\n      dedupeStrategy?: DedupeStrategy;\n      maxIterations?: number;\n      getIsFirst?: (context: { index: number }) => boolean;\n      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;\n      onFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n      onLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n    }\n  ) => Promise<T[]>;\n}\n\n/**\n * Restricted table result that excludes methods that shouldn't be called during iteration.\n */\nexport type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;\n";
+export declare const TYPE_CONTEXT = "\n/**\n * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.\n * @example\n * // String selector\n * rowSelector: 'tbody tr'\n * \n * // Function selector\n * rowSelector: (root) => root.locator('[role=\"row\"]')\n */\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\n/**\n * Function to get a cell locator given row, column info.\n * Replaces the old cellResolver.\n */\nexport type GetCellLocatorFn = (args: {\n  row: Locator;\n  columnName: string;\n  columnIndex: number;\n  rowIndex?: number;\n  page: Page;\n}) => Locator;\n\n/**\n * Function to get the currently active/focused cell.\n * Returns null if no cell is active.\n */\nexport type GetActiveCellFn = (args: TableContext) => Promise<{\n  rowIndex: number;\n  columnIndex: number;\n  columnName?: string;\n  locator: Locator;\n} | null>;\n\n\n/**\n * SmartRow - A Playwright Locator with table-aware methods.\n * \n * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.\n * \n * @example\n * const row = table.getRow({ Name: 'John Doe' });\n * await row.click(); // Standard Locator method\n * const email = row.getCell('Email'); // Table-aware method\n * const data = await row.toJSON(); // Extract all row data\n * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields\n */\nexport type SmartRow<T = any> = Locator & {\n  /** Optional row index (0-based) if known */\n  rowIndex?: number;\n\n  /**\n   * Get a cell locator by column name.\n   * @param column - Column name (case-sensitive)\n   * @returns Locator for the cell\n   * @example\n   * const emailCell = row.getCell('Email');\n   * await expect(emailCell).toHaveText('john@example.com');\n   */\n  getCell(column: string): Locator;\n\n  /**\n   * Extract all cell data as a key-value object.\n   * @param options - Optional configuration\n   * @param options.columns - Specific columns to extract (extracts all if not specified)\n   * @returns Promise resolving to row data\n   * @example\n   * const data = await row.toJSON();\n   * // { Name: 'John', Email: 'john@example.com', ... }\n   * \n   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });\n   * // { Name: 'John', Email: 'john@example.com' }\n   */\n  toJSON(options?: { columns?: string[] }): Promise<T>;\n\n  /**\n   * Scrolls/paginates to bring this row into view.\n   * Only works if rowIndex is known (e.g., from getRowByIndex).\n   * @throws Error if rowIndex is unknown\n   */\n  bringIntoView(): Promise<void>;\n\n  /**\n   * Intelligently fills form fields in the row.\n   * Automatically detects input types (text, select, checkbox, contenteditable).\n   * \n   * @param data - Column-value pairs to fill\n   * @param options - Optional configuration\n   * @param options.inputMappers - Custom input selectors per column\n   * @example\n   * // Auto-detection\n   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });\n   * \n   * // Custom input mappers\n   * await row.smartFill(\n   *   { Name: 'John' },\n   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }\n   * );\n   */\n  smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };\n\n/**\n * Defines the contract for a sorting strategy.\n */\nexport interface SortingStrategy {\n  /**\n   * Performs the sort action on a column.\n   */\n  doSort(options: {\n    columnName: string;\n    direction: 'asc' | 'desc';\n    context: StrategyContext;\n  }): Promise<void>;\n\n  /**\n   * Retrieves the current sort state of a column.\n   */\n  getSortState(options: {\n    columnName: string;\n    context: StrategyContext;\n  }): Promise<'asc' | 'desc' | 'none'>;\n}\n\nexport interface TableContext {\n  root: Locator;\n  config: FinalTableConfig;\n  page: Page;\n  resolve: (selector: Selector, parent: Locator | Page) => Locator;\n}\n\nexport type PaginationStrategy = (context: TableContext) => Promise<boolean>;\n\nexport type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;\n\nexport interface PromptOptions {\n  /**\n   * Output Strategy:\n   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).\n   * - 'console': Standard console logs (Default).\n   */\n  output?: 'console' | 'error';\n  includeTypes?: boolean;\n}\n\nexport type FillStrategy = (options: {\n  row: SmartRow;\n  columnName: string;\n  value: any;\n  index: number;\n  page: Page;\n  rootLocator: Locator;\n  table: TableResult; // The parent table instance\n  fillOptions?: FillOptions;\n}) => Promise<void>;\n\nexport type { HeaderStrategy } from './strategies/headers';\nexport type { CellNavigationStrategy } from './strategies/columns';\n\n/**\n * Strategy to resolve column names (string or regex) to their index.\n */\nexport type { ColumnResolutionStrategy } from './strategies/resolution';\n\n/**\n * Strategy to filter rows based on criteria.\n */\nexport interface FilterStrategy {\n  apply(options: {\n    rows: Locator;\n    filter: { column: string, value: string | RegExp | number };\n    colIndex: number;\n    tableContext: TableContext;\n  }): Locator;\n}\n\n/**\n * Organized container for all table interaction strategies.\n */\nexport interface TableStrategies {\n  /** Strategy for discovering/scanning headers */\n  header?: HeaderStrategy;\n  /** Strategy for navigating to specific cells (row + column) */\n  cellNavigation?: CellNavigationStrategy;\n  /** Strategy for filling form inputs */\n  fill?: FillStrategy;\n  /** Strategy for paginating through data */\n  pagination?: PaginationStrategy;\n  /** Strategy for sorting columns */\n  sorting?: SortingStrategy;\n  /** Function to get a cell locator */\n  getCellLocator?: GetCellLocatorFn;\n  /** Function to get the currently active/focused cell */\n  getActiveCell?: GetActiveCellFn;\n}\n\n/**\n * Configuration options for useTable.\n */\nexport interface TableConfig {\n  /** Selector for the table headers */\n  headerSelector?: string;\n  /** Selector for the table rows */\n  rowSelector?: string;\n  /** Selector for the cells within a row */\n  cellSelector?: string;\n  /** Number of pages to scan for verification */\n  maxPages?: number;\n  /** Hook to rename columns dynamically */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  /** Automatically scroll to table on init */\n  autoScroll?: boolean;\n  /** Enable debug logs */\n  debug?: boolean;\n  /** Reset hook */\n  onReset?: (context: TableContext) => Promise<void>;\n  /** All interaction strategies */\n  strategies?: TableStrategies;\n}\n\nexport interface FinalTableConfig extends TableConfig {\n  headerSelector: string;\n  rowSelector: string;\n  cellSelector: string;\n  maxPages: number;\n  autoScroll: boolean;\n  debug: boolean;\n  headerTransformer: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  onReset: (context: TableContext) => Promise<void>;\n  strategies: TableStrategies;\n}\n\n\nexport interface FillOptions {\n  /**\n   * Custom input mappers for specific columns.\n   * Maps column names to functions that return the input locator for that cell.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\nexport interface TableResult<T = any> {\n  /**\n   * Initializes the table by resolving headers. Must be called before using sync methods.\n   * @param options Optional timeout for header resolution (default: 3000ms)\n   */\n  init(options?: { timeout?: number }): Promise<TableResult>;\n\n  /**\n   * SYNC: Checks if the table has been initialized.\n   * @returns true if init() has been called and completed, false otherwise\n   */\n  isInitialized(): boolean;\n\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row by filters on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Gets a row by 1-based index on the current page.\n   * Throws error if table is not initialized.\n   * @param index 1-based row index\n   * @param options Optional settings including bringIntoView\n   */\n  getRowByIndex: (\n    index: number,\n    options?: { bringIntoView?: boolean }\n  ) => SmartRow;\n\n  /**\n   * ASYNC: Searches for a single row across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match and max pages\n   */\n  findRow: (\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  /**\n   * ASYNC: Searches for all matching rows across pages using pagination.\n   * Auto-initializes the table if not already initialized.\n   * @param filters - The filter criteria to match\n   * @param options - Search options including exact match, max pages, and asJSON\n   */\n  findRows: <R extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>,\n    options?: { exact?: boolean, maxPages?: number } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  /**\n   * Navigates to a specific column using the configured CellNavigationStrategy.\n   */\n  scrollToColumn: (columnName: string) => Promise<void>;\n\n  /**\n   * ASYNC: Gets all rows on the current page only (does not paginate).\n   * Auto-initializes the table if not already initialized.\n   * @param options - Filter and formatting options\n   */\n  getRows: <R extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & R\n  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => Promise<void>;\n\n  /**\n   * Revalidates the table's structure (headers, columns) without resetting pagination or state.\n   * Useful when columns change visibility or order dynamically.\n   */\n  revalidate: () => Promise<void>;\n\n  /**\n   * Scans a specific column across all pages and returns the values.\n   */\n  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;\n\n  /**\n   * Provides access to sorting actions and assertions.\n   */\n  sorting: {\n    /**\n     * Applies the configured sorting strategy to the specified column.\n     * @param columnName The name of the column to sort.\n     * @param direction The direction to sort ('asc' or 'desc').\n     */\n    apply(columnName: string, direction: 'asc' | 'desc'): Promise<void>;\n    /**\n     * Gets the current sort state of a column using the configured sorting strategy.\n     * @param columnName The name of the column to check.\n     * @returns A promise that resolves to 'asc', 'desc', or 'none'.\n     */\n    getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;\n  };\n\n  /**\n   * Iterates through paginated table data, calling the callback for each iteration.\n   * Callback return values are automatically appended to allData, which is returned.\n   */\n  iterateThroughTable: <T = any>(\n    callback: (context: {\n      index: number;\n      isFirst: boolean;\n      isLast: boolean;\n      rows: SmartRow[];\n      allData: T[];\n      table: RestrictedTableResult;\n      batchInfo?: {\n        startIndex: number;\n        endIndex: number;\n        size: number;\n      };\n    }) => T | Promise<T>,\n    options?: {\n      pagination?: PaginationStrategy;\n      dedupeStrategy?: DedupeStrategy;\n      maxIterations?: number;\n      batchSize?: number;\n      getIsFirst?: (context: { index: number }) => boolean;\n      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;\n      beforeFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n      afterLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;\n    }\n  ) => Promise<T[]>;\n}\n\n/**\n * Restricted table result that excludes methods that shouldn't be called during iteration.\n */\nexport type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;\n";

package/dist/typeContext.js

@@ -368,15 +368,21 @@ export interface TableResult<T = any> {
       rows: SmartRow[];
       allData: T[];
       table: RestrictedTableResult;
+      batchInfo?: {
+        startIndex: number;
+        endIndex: number;
+        size: number;
+      };
     }) => T | Promise<T>,
     options?: {
       pagination?: PaginationStrategy;
       dedupeStrategy?: DedupeStrategy;
       maxIterations?: number;
+      batchSize?: number;
       getIsFirst?: (context: { index: number }) => boolean;
       getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;
-      onFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;
-      onLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;
+      beforeFirst?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;
+      afterLast?: (context: { index: number, rows: SmartRow[], allData: any[] }) => void | Promise<void>;
     }
   ) => Promise<T[]>;
 }

package/dist/types.d.ts

@@ -347,10 +347,16 @@ export interface TableResult<T = any> {
         rows: SmartRow[];
         allData: T[];
         table: RestrictedTableResult;
+        batchInfo?: {
+            startIndex: number;
+            endIndex: number;
+            size: number;
+        };
     }) => T | Promise<T>, options?: {
         pagination?: PaginationStrategy;
         dedupeStrategy?: DedupeStrategy;
         maxIterations?: number;
+        batchSize?: number;
         getIsFirst?: (context: {
             index: number;
         }) => boolean;
@@ -358,12 +364,12 @@ export interface TableResult<T = any> {
             index: number;
             paginationResult: boolean;
         }) => boolean;
-        onFirst?: (context: {
+        beforeFirst?: (context: {
             index: number;
             rows: SmartRow[];
             allData: any[];
         }) => void | Promise<void>;
-        onLast?: (context: {
+        afterLast?: (context: {
             index: number;
             rows: SmartRow[];
             allData: any[];

package/dist/useTable.js

@@ -26,6 +26,7 @@ Object.defineProperty(exports, "ResolutionStrategies", { enumerable: true, get:
 const strategies_1 = require("./strategies");
 Object.defineProperty(exports, "Strategies", { enumerable: true, get: function () { return strategies_1.Strategies; } });
 const validation_1 = require("./strategies/validation");
+const traceUtils_1 = require("./utils/traceUtils");
 /**
  * Main hook to interact with a table.
  */
@@ -40,7 +41,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         cellNavigation: columns_1.CellNavigationStrategies.default,
         pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }),
     };
-    const config = Object.assign(Object.assign({ rowSelector: "tbody tr", headerSelector: "th", cellSelector: "td", maxPages: 1, headerTransformer: ({ text, index, locator }) => text, autoScroll: true, debug: false, onReset: () => __awaiter(void 0, void 0, void 0, function* () { }) }, configOptions), { strategies: Object.assign(Object.assign({}, defaultStrategies), configOptions.strategies) });
+    const config = Object.assign(Object.assign({ rowSelector: "tbody tr", headerSelector: "thead th", cellSelector: "td", maxPages: 1, headerTransformer: ({ text, index, locator }) => text, autoScroll: true, debug: false, onReset: () => __awaiter(void 0, void 0, void 0, function* () { }) }, configOptions), { strategies: Object.assign(Object.assign({}, defaultStrategies), configOptions.strategies) });
     const resolve = (item, parent) => {
         if (typeof item === 'string')
             return parent.locator(item);
@@ -225,6 +226,9 @@ const useTable = (rootLocator, configOptions = {}) => {
                 return result;
             yield _getMap(options === null || options === void 0 ? void 0 : options.timeout);
             _isInitialized = true;
+            if (_headerMap) {
+                yield (0, traceUtils_1.addTraceEvent)(rootLocator.page(), 'init', { headers: Array.from(_headerMap.keys()), columnCount: _headerMap.size });
+            }
             return result;
         }),
         scrollToColumn: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
@@ -419,10 +423,14 @@ const useTable = (rootLocator, configOptions = {}) => {
             const getIsLast = (_c = options === null || options === void 0 ? void 0 : options.getIsLast) !== null && _c !== void 0 ? _c : (() => false);
             const allData = [];
             const effectiveMaxIterations = (_d = options === null || options === void 0 ? void 0 : options.maxIterations) !== null && _d !== void 0 ? _d : config.maxPages;
+            const batchSize = options === null || options === void 0 ? void 0 : options.batchSize;
+            const isBatching = batchSize !== undefined && batchSize > 1;
             let index = 0;
             let paginationResult = true;
             let seenKeys = null;
-            logDebug(`Starting iterateThroughTable (maxIterations: ${effectiveMaxIterations})`);
+            let batchRows = [];
+            let batchStartIndex = 0;
+            logDebug(`Starting iterateThroughTable (maxIterations: ${effectiveMaxIterations}, batchSize: ${batchSize !== null && batchSize !== void 0 ? batchSize : 'none'})`);
             while (index < effectiveMaxIterations) {
                 const rowLocators = yield resolve(config.rowSelector, rootLocator).all();
                 let rows = rowLocators.map((loc, i) => _makeSmart(loc, _headerMap, i));
@@ -440,21 +448,91 @@ const useTable = (rootLocator, configOptions = {}) => {
                     rows = deduplicated;
                     logDebug(`Deduplicated ${rowLocators.length} rows to ${rows.length} unique rows (total seen: ${seenKeys.size})`);
                 }
-                const isFirst = getIsFirst({ index });
-                let isLast = getIsLast({ index, paginationResult });
-                const isLastDueToMax = index === effectiveMaxIterations - 1;
-                if (isFirst && (options === null || options === void 0 ? void 0 : options.onFirst))
-                    yield options.onFirst({ index, rows, allData });
-                const returnValue = yield callback({ index, isFirst, isLast, rows, allData, table: restrictedTable });
-                allData.push(returnValue);
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                paginationResult = yield paginationStrategy(context);
-                isLast = getIsLast({ index, paginationResult }) || isLastDueToMax;
-                if (isLast && (options === null || options === void 0 ? void 0 : options.onLast))
-                    yield options.onLast({ index, rows, allData });
-                if (isLast || !paginationResult) {
-                    logDebug(`Reached last iteration (index: ${index}, paginationResult: ${paginationResult})`);
-                    break;
+                // Add rows to batch if batching is enabled
+                if (isBatching) {
+                    batchRows.push(...rows);
+                }
+                const isLastIteration = index === effectiveMaxIterations - 1;
+                // Determine if we should invoke the callback
+                const batchComplete = isBatching && (index - batchStartIndex + 1) >= batchSize;
+                const shouldInvokeCallback = !isBatching || batchComplete || isLastIteration;
+                if (shouldInvokeCallback) {
+                    const callbackRows = isBatching ? batchRows : rows;
+                    const callbackIndex = isBatching ? batchStartIndex : index;
+                    const isFirst = getIsFirst({ index: callbackIndex });
+                    let isLast = getIsLast({ index: callbackIndex, paginationResult });
+                    const isLastDueToMax = index === effectiveMaxIterations - 1;
+                    if (isFirst && (options === null || options === void 0 ? void 0 : options.beforeFirst)) {
+                        yield options.beforeFirst({ index: callbackIndex, rows: callbackRows, allData });
+                    }
+                    const batchInfo = isBatching ? {
+                        startIndex: batchStartIndex,
+                        endIndex: index,
+                        size: index - batchStartIndex + 1
+                    } : undefined;
+                    const returnValue = yield callback({
+                        index: callbackIndex,
+                        isFirst,
+                        isLast,
+                        rows: callbackRows,
+                        allData,
+                        table: restrictedTable,
+                        batchInfo
+                    });
+                    allData.push(returnValue);
+                    // Determine if this is truly the last iteration
+                    let finalIsLast = isLastDueToMax;
+                    if (!isLastIteration) {
+                        const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
+                        paginationResult = yield paginationStrategy(context);
+                        finalIsLast = getIsLast({ index: callbackIndex, paginationResult }) || !paginationResult;
+                    }
+                    if (finalIsLast && (options === null || options === void 0 ? void 0 : options.afterLast)) {
+                        yield options.afterLast({ index: callbackIndex, rows: callbackRows, allData });
+                    }
+                    if (finalIsLast || !paginationResult) {
+                        logDebug(`Reached last iteration (index: ${index}, paginationResult: ${paginationResult})`);
+                        break;
+                    }
+                    // Reset batch
+                    if (isBatching) {
+                        batchRows = [];
+                        batchStartIndex = index + 1;
+                    }
+                }
+                else {
+                    // Continue paginating even when batching
+                    const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
+                    paginationResult = yield paginationStrategy(context);
+                    if (!paginationResult) {
+                        // Pagination failed, invoke callback with current batch
+                        const callbackIndex = batchStartIndex;
+                        const isFirst = getIsFirst({ index: callbackIndex });
+                        const isLast = true;
+                        if (isFirst && (options === null || options === void 0 ? void 0 : options.beforeFirst)) {
+                            yield options.beforeFirst({ index: callbackIndex, rows: batchRows, allData });
+                        }
+                        const batchInfo = {
+                            startIndex: batchStartIndex,
+                            endIndex: index,
+                            size: index - batchStartIndex + 1
+                        };
+                        const returnValue = yield callback({
+                            index: callbackIndex,
+                            isFirst,
+                            isLast,
+                            rows: batchRows,
+                            allData,
+                            table: restrictedTable,
+                            batchInfo
+                        });
+                        allData.push(returnValue);
+                        if (options === null || options === void 0 ? void 0 : options.afterLast) {
+                            yield options.afterLast({ index: callbackIndex, rows: batchRows, allData });
+                        }
+                        logDebug(`Pagination failed mid-batch (index: ${index})`);
+                        break;
+                    }
                 }
                 index++;
                 logDebug(`Iteration ${index} completed, continuing...`);

package/dist/utils/stringUtils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Calculate Levenshtein distance between two strings
+ * Used for "did you mean?" suggestions
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Calculate similarity score between two strings (0-1)
+ * 1 = identical, 0 = completely different
+ */
+export declare function stringSimilarity(a: string, b: string): number;
+/**
+ * Find similar strings from a list
+ * Returns matches above threshold, sorted by similarity
+ */
+export declare function findSimilar(input: string, available: string[], threshold?: number): Array<{
+    value: string;
+    score: number;
+}>;
+/**
+ * Build a helpful error message for column not found
+ */
+export declare function buildColumnNotFoundError(columnName: string, availableColumns: string[]): string;

package/dist/utils/stringUtils.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshteinDistance = levenshteinDistance;
+exports.stringSimilarity = stringSimilarity;
+exports.findSimilar = findSimilar;
+exports.buildColumnNotFoundError = buildColumnNotFoundError;
+/**
+ * Calculate Levenshtein distance between two strings
+ * Used for "did you mean?" suggestions
+ */
+function levenshteinDistance(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                matrix[i][j - 1] + 1, // insertion
+                matrix[i - 1][j] + 1 // deletion
+                );
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+/**
+ * Calculate similarity score between two strings (0-1)
+ * 1 = identical, 0 = completely different
+ */
+function stringSimilarity(a, b) {
+    const distance = levenshteinDistance(a.toLowerCase(), b.toLowerCase());
+    const maxLen = Math.max(a.length, b.length);
+    return maxLen === 0 ? 1 : 1 - (distance / maxLen);
+}
+/**
+ * Find similar strings from a list
+ * Returns matches above threshold, sorted by similarity
+ */
+function findSimilar(input, available, threshold = 0.5) {
+    return available
+        .map(value => ({
+        value,
+        score: stringSimilarity(input, value)
+    }))
+        .filter(x => x.score >= threshold)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 3); // Top 3 suggestions
+}
+/**
+ * Build a helpful error message for column not found
+ */
+function buildColumnNotFoundError(columnName, availableColumns) {
+    const suggestions = findSimilar(columnName, availableColumns);
+    let message = `Column '${columnName}' not found`;
+    if (suggestions.length > 0) {
+        message += `\n\nDid you mean:`;
+        suggestions.forEach(({ value, score }) => {
+            const percentage = Math.round(score * 100);
+            message += `\n  • ${value} (${percentage}% match)`;
+        });
+    }
+    message += `\n\nAvailable columns: ${availableColumns.join(', ')}`;
+    message += `\n\nTip: Column names are case-sensitive`;
+    return message;
+}

package/dist/utils/traceUtils.d.ts

@@ -0,0 +1,11 @@
+import type { Page } from '@playwright/test';
+/**
+ * Add a custom trace event to Playwright's trace viewer
+ * Uses page.evaluate to log events that appear in the trace
+ */
+export declare function addTraceEvent(page: Page, type: string, data?: Record<string, any>): Promise<void>;
+/**
+ * Check if tracing is currently enabled
+ * Used for conditional trace logic
+ */
+export declare function isTracingEnabled(page: Page): Promise<boolean>;

package/dist/utils/traceUtils.js

@@ -0,0 +1,47 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addTraceEvent = addTraceEvent;
+exports.isTracingEnabled = isTracingEnabled;
+/**
+ * Add a custom trace event to Playwright's trace viewer
+ * Uses page.evaluate to log events that appear in the trace
+ */
+function addTraceEvent(page_1, type_1) {
+    return __awaiter(this, arguments, void 0, function* (page, type, data = {}) {
+        try {
+            // Add a console log that will appear in the trace viewer
+            // Prefix with [SmartTable] for easy filtering
+            const message = `[SmartTable:${type}] ${JSON.stringify(data)}`;
+            yield page.evaluate((msg) => console.log(msg), message);
+        }
+        catch (_a) {
+            // Silently ignore if page is not available
+            // This ensures zero overhead when tracing is off
+        }
+    });
+}
+/**
+ * Check if tracing is currently enabled
+ * Used for conditional trace logic
+ */
+function isTracingEnabled(page) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            // We can't directly check if tracing is enabled
+            // But we can safely call addTraceEvent - it will just be a no-op if not tracing
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Production-ready table testing for Playwright with smart column-aware locators. Core library with plugin support for custom table implementations.",
   "repository": {
     "type": "git",