@rickcedwhat/playwright-smart-table 2.3.1 → 3.1.0

package/README.md

@@ -21,14 +21,15 @@ For standard HTML tables (`<table>`, `<tr>`, `<td>`), the library works out of t
 <!-- embed: quick-start -->
 ```typescript
 // Example from: https://datatables.net/examples/data_sources/dom
-const table = useTable(page.locator('#example'), {
+const table = await useTable(page.locator('#example'), {
   headerSelector: 'thead th' // Override for this specific site
-});
+}).init();
 
 // Find the row with Name="Airi Satou", then get the Position cell
-const row = await table.getByRow({ Name: 'Airi Satou' });
+const row = table.getByRow({ Name: 'Airi Satou' });
 
-await expect(row.getCell('Position')).toHaveText('Accountant');
+const positionCell = row.getCell('Position');
+await expect(positionCell).toHaveText('Accountant');
 ```
 <!-- /embed: quick-start -->
 
@@ -46,10 +47,11 @@ The `SmartRow` is the core power of this library. Unlike a standard Playwright `
 // Example from: https://datatables.net/examples/data_sources/dom
 
 // Get SmartRow via getByRow
-const row = await table.getByRow({ Name: 'Airi Satou' });
+const row = table.getByRow({ Name: 'Airi Satou' });
 
 // Interact with cell using column name (resilient to column reordering)
-await row.getCell('Position').click();
+const positionCell = row.getCell('Position');
+await positionCell.click();
 
 // Extract row data as JSON
 const data = await row.toJSON();
@@ -84,11 +86,13 @@ const table = useTable(page.locator('#example'), {
   ),
   maxPages: 5 // Allow scanning up to 5 pages
 });
+await table.init();
 
 // ✅ Verify Colleen is NOT visible initially
 await expect(page.getByText("Colleen Hurst")).not.toBeVisible();
 
-await expect(await table.getByRow({ Name: "Colleen Hurst" })).toBeVisible();
+// Use searchForRow for pagination
+await expect(await table.searchForRow({ Name: "Colleen Hurst" })).toBeVisible();
 // NOTE: We're now on the page where Colleen Hurst exists (typically Page 2)
 ```
 <!-- /embed: pagination -->
@@ -104,8 +108,9 @@ const table = useTable(page.locator('#example'), {
   headerSelector: 'thead th',
   debug: true // Enables verbose logging of internal operations
 });
+await table.init();
 
-const row = await table.getByRow({ Name: 'Airi Satou' });
+const row = table.getByRow({ Name: 'Airi Satou' });
 await expect(row).toBeVisible();
 ```
 <!-- /embed: advanced-debug -->
@@ -121,15 +126,16 @@ If your tests navigate deep into a paginated table, use `.reset()` to return to
 // Example from: https://datatables.net/examples/data_sources/dom
 // Navigate deep into the table by searching for a row on a later page
 try {
-  await table.getByRow({ Name: 'Angelica Ramos' });
+  await table.searchForRow({ Name: 'Angelica Ramos' });
 } catch (e) {}
 
-// Reset internal state (and potentially UI) to Page 1
-await table.reset();
+// Reset internal state (and potentially UI) to initial page
+await table.reset(); 
+await table.init(); // Re-init after reset
 
 // Now subsequent searches start from the beginning
-const firstPageRow = await table.getByRow({ Name: 'Airi Satou' });
-await expect(firstPageRow).toBeVisible();
+const currentPageRow = table.getByRow({ Name: 'Airi Satou' });
+await expect(currentPageRow).toBeVisible();
 ```
 <!-- /embed: advanced-reset -->
 
@@ -149,14 +155,14 @@ expect(offices.length).toBeGreaterThan(0);
 
 ### Filling Row Data
 
-Use `fill()` to intelligently populate form fields in a table row. The method automatically detects input types (text inputs, selects, checkboxes, contenteditable divs) and fills them appropriately.
+Use `smartFill()` to intelligently populate form fields in a table row. The method automatically detects input types (text inputs, selects, checkboxes, contenteditable divs) and fills them appropriately. You can still use Locator's standard `fill()` method for single-input scenarios.
 
 <!-- embed: fill-basic -->
 ```typescript
 // Find a row and fill it with new data
-const row = await table.getByRow({ ID: '1' });
+const row = table.getByRow({ ID: '1' });
 
-await row.fill({
+await row.smartFill({
   Name: 'John Updated',
   Status: 'Inactive',
   Active: false,
@@ -164,10 +170,14 @@ await row.fill({
 });
 
 // Verify the values were filled correctly
-await expect(row.getCell('Name').locator('input')).toHaveValue('John Updated');
-await expect(row.getCell('Status').locator('select')).toHaveValue('Inactive');
-await expect(row.getCell('Active').locator('input[type="checkbox"]')).not.toBeChecked();
-await expect(row.getCell('Notes').locator('textarea')).toHaveValue('Updated notes here');
+const nameCell = row.getCell('Name');
+const statusCell = row.getCell('Status');
+const activeCell = row.getCell('Active');
+const notesCell = row.getCell('Notes');
+await expect(nameCell.locator('input')).toHaveValue('John Updated');
+await expect(statusCell.locator('select')).toHaveValue('Inactive');
+await expect(activeCell.locator('input[type="checkbox"]')).not.toBeChecked();
+await expect(notesCell.locator('textarea')).toHaveValue('Updated notes here');
 ```
 <!-- /embed: fill-basic -->
 
@@ -183,10 +193,10 @@ For edge cases where auto-detection doesn't work (e.g., custom components, multi
 
 <!-- embed: fill-custom-mappers -->
 ```typescript
-const row = await table.getByRow({ ID: '1' });
+const row = table.getByRow({ ID: '1' });
 
 // Use custom input mappers for specific columns
-await row.fill({
+await row.smartFill({
   Name: 'John Updated',
   Status: 'Inactive'
 }, {
@@ -199,8 +209,10 @@ await row.fill({
 });
 
 // Verify the values
-await expect(row.getCell('Name').locator('.primary-input')).toHaveValue('John Updated');
-await expect(row.getCell('Status').locator('select')).toHaveValue('Inactive');
+const nameCell = row.getCell('Name');
+const statusCell = row.getCell('Status');
+await expect(nameCell.locator('.primary-input')).toHaveValue('John Updated');
+await expect(statusCell.locator('select')).toHaveValue('Inactive');
 ```
 <!-- /embed: fill-custom-mappers -->
 
@@ -232,14 +244,21 @@ const table = useTable(page.locator('.MuiDataGrid-root').first(), {
     return text;
   }
 });
+await table.init();
 
 const headers = await table.getHeaders();
 // Now we can reference the "Actions" column even if it has no header text
 expect(headers).toContain('Actions');
 
 // Use the renamed column
-const row = await table.getByRow({ "Last name": "Melisandre" });
-await row.getCell('Actions').getByLabel("Select row").click();
+// First check it's not on the current page
+const currentPageRow = table.getByRow({ "Last name": "Melisandre" });
+await expect(currentPageRow).not.toBeVisible();
+
+// Then find it across pages
+const row = await table.searchForRow({ "Last name": "Melisandre" });
+const actionsCell = row.getCell('Actions');
+await actionsCell.getByLabel("Select row").click();
 ```
 <!-- /embed: header-transformer -->
 
@@ -258,10 +277,12 @@ const table = useTable(page.locator('#table1'), {
       .replace(/^\s*|\s*$/g, ''); // Remove leading/trailing spaces
   }
 });
+await table.init();
 
 // Now column names are consistent
-const row = await table.getByRow({ "Last Name": "Doe" });
-await expect(row.getCell("Email")).toHaveText("jdoe@hotmail.com");
+const row = table.getByRow({ "Last Name": "Doe" });
+const emailCell = row.getCell("Email");
+await expect(emailCell).toHaveText("jdoe@hotmail.com");
 ```
 <!-- /embed: header-transformer-normalize -->
 
@@ -292,20 +313,24 @@ getByRow: <T extends { asJSON?: boolean }>(
 <!-- embed: get-by-row -->
 ```typescript
 // Example from: https://datatables.net/examples/data_sources/dom
+const table = useTable(page.locator('#example'), { headerSelector: 'thead th' });
+await table.init();
+
 // Find a row where Name is "Airi Satou" AND Office is "Tokyo"
-const row = await table.getByRow({ Name: "Airi Satou", Office: "Tokyo" });
+const row = table.getByRow({ Name: "Airi Satou", Office: "Tokyo" });
 await expect(row).toBeVisible();
 
 // Assert it does NOT exist
-await expect(await table.getByRow({ Name: "Ghost User" })).not.toBeVisible();
+await expect(table.getByRow({ Name: "Ghost User" })).not.toBeVisible();
 ```
 <!-- /embed: get-by-row -->
 
 Get row data as JSON:
 <!-- embed: get-by-row-json -->
 ```typescript
-// Get row data directly as JSON object
-const data = await table.getByRow({ Name: 'Airi Satou' }, { asJSON: true });
+// Get row data as JSON object
+const row = table.getByRow({ Name: 'Airi Satou' });
+const data = await row.toJSON();
 // Returns: { Name: "Airi Satou", Position: "Accountant", Office: "Tokyo", ... }
 
 expect(data).toHaveProperty('Name', 'Airi Satou');
@@ -534,13 +559,13 @@ A `SmartRow` extends Playwright's `Locator` with table-aware methods.
 
 <!-- embed-type: SmartRow -->
 ```typescript
-export type SmartRow = Omit<Locator, 'fill'> & {
+export type SmartRow = Locator & {
   getCell(column: string): Locator;
   toJSON(): Promise<Record<string, string>>;
   /**
    * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
    */
-  fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
+  smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 ```
 <!-- /embed-type: SmartRow -->
@@ -548,7 +573,7 @@ export type SmartRow = Omit<Locator, 'fill'> & {
 **Methods:**
 - `getCell(column: string)`: Returns a `Locator` for the specified cell in this row
 - `toJSON()`: Extracts all cell data as a key-value object
-- `fill(data, options?)`: Intelligently fills form fields in the row. Automatically detects input types or use `inputMappers` for custom control
+- `smartFill(data, options?)`: Intelligently fills form fields in the row. Automatically detects input types or use `inputMappers` for custom control. Use Locator's standard `fill()` for single-input scenarios.
 
 All standard Playwright `Locator` methods (`.click()`, `.isVisible()`, `.textContent()`, etc.) are also available.
 
@@ -578,7 +603,7 @@ export interface TableConfig {
    */
   debug?: boolean;
   /**
-   * Strategy to reset the table to the first page.
+   * Strategy to reset the table to the initial page.
    * Called when table.reset() is invoked.
    */
   onReset?: (context: TableContext) => Promise<void>;

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 = "\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\nexport type SmartRow = Omit<Locator, 'fill'> & {\n  getCell(column: string): Locator;\n  toJSON(): Promise<Record<string, string>>;\n  /**\n   * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).\n   */\n  fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext;\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 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 interface TableConfig {\n  rowSelector?: Selector;\n  headerSelector?: Selector;\n  cellSelector?: Selector;\n  pagination?: PaginationStrategy;\n  sorting?: SortingStrategy;\n  maxPages?: number;\n  /**\n   * Hook to rename columns dynamically.\n   * * @param args.text - The default innerText of the header.\n   * @param args.index - The column index.\n   * @param args.locator - The specific header cell locator.\n   */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  autoScroll?: boolean;\n  /**\n   * Enable debug mode to log internal state to console.\n   */\n  debug?: boolean;\n  /**\n   * Strategy to reset the table to the first page.\n   * Called when table.reset() is invoked.\n   */\n  onReset?: (context: TableContext) => Promise<void>;\n}\n\n/**\n * Represents the final, resolved table configuration after default values have been applied.\n * All optional properties from TableConfig are now required, except for `sorting`.\n */\nexport type FinalTableConfig = Required<Omit<TableConfig, 'sorting'>> & {\n  sorting?: SortingStrategy;\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   * Columns not specified here will use auto-detection.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\nexport interface TableResult {\n  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  getByRow: <T extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>, \n    options?: { exact?: boolean, maxPages?: number } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string> : SmartRow>;\n\n  getAllRows: <T extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;\n  generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => 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";
+export declare const TYPE_CONTEXT = "\nexport type Selector = string | ((root: Locator | Page) => Locator);\n\nexport type SmartRow = Locator & {\n  getCell(column: string): Locator;\n  toJSON(): Promise<Record<string, string>>;\n  /**\n   * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).\n   */\n  smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;\n};\n\nexport type StrategyContext = TableContext;\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 interface TableConfig {\n  rowSelector?: Selector;\n  headerSelector?: Selector;\n  cellSelector?: Selector;\n  pagination?: PaginationStrategy;\n  sorting?: SortingStrategy;\n  maxPages?: number;\n  /**\n   * Hook to rename columns dynamically.\n   * * @param args.text - The default innerText of the header.\n   * @param args.index - The column index.\n   * @param args.locator - The specific header cell locator.\n   */\n  headerTransformer?: (args: { text: string, index: number, locator: Locator }) => string | Promise<string>;\n  autoScroll?: boolean;\n  /**\n   * Enable debug mode to log internal state to console.\n   */\n  debug?: boolean;\n  /**\n   * Strategy to reset the table to the initial page.\n   * Called when table.reset() is invoked.\n   */\n  onReset?: (context: TableContext) => Promise<void>;\n}\n\n/**\n * Represents the final, resolved table configuration after default values have been applied.\n * All optional properties from TableConfig are now required, except for `sorting`.\n */\nexport type FinalTableConfig = Required<Omit<TableConfig, 'sorting'>> & {\n  sorting?: SortingStrategy;\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   * Columns not specified here will use auto-detection.\n   */\n  inputMappers?: Record<string, (cell: Locator) => Locator>;\n}\n\nexport interface TableResult {\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  getHeaders: () => Promise<string[]>;\n  getHeaderCell: (columnName: string) => Promise<Locator>;\n\n  /**\n   * Finds a row on the current page only. Returns immediately (sync).\n   * Throws error if table is not initialized.\n   */\n  getByRow: (\n    filters: Record<string, string | RegExp | number>, \n    options?: { exact?: boolean }\n  ) => SmartRow;\n\n  /**\n   * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).\n   * Auto-initializes if needed.\n   */\n  searchForRow: (\n    filters: Record<string, string | RegExp | number>, \n    options?: { exact?: boolean, maxPages?: number }\n  ) => Promise<SmartRow>;\n\n  getAllRows: <T extends { asJSON?: boolean }>(\n    options?: { filter?: Record<string, any>, exact?: boolean } & T\n  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;\n\n  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;\n  generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;\n\n  /**\n   * Resets the table state (clears cache, flags) and invokes the onReset strategy.\n   */\n  reset: () => 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 = Omit<TableResult, 'searchForRow' | 'iterateThroughTable' | 'reset'>;\n";

package/dist/typeContext.js

@@ -9,13 +9,13 @@ exports.TYPE_CONTEXT = void 0;
 exports.TYPE_CONTEXT = `
 export type Selector = string | ((root: Locator | Page) => Locator);
 
-export type SmartRow = Omit<Locator, 'fill'> & {
+export type SmartRow = Locator & {
   getCell(column: string): Locator;
   toJSON(): Promise<Record<string, string>>;
   /**
    * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
    */
-  fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
+  smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 
 export type StrategyContext = TableContext;
@@ -51,6 +51,8 @@ export interface TableContext {
 
 export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
 
+export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
+
 export interface PromptOptions {
   /**
    * Output Strategy:
@@ -81,7 +83,7 @@ export interface TableConfig {
    */
   debug?: boolean;
   /**
-   * Strategy to reset the table to the first page.
+   * Strategy to reset the table to the initial page.
    * Called when table.reset() is invoked.
    */
   onReset?: (context: TableContext) => Promise<void>;
@@ -105,13 +107,32 @@ export interface FillOptions {
 }
 
 export interface TableResult {
+  /**
+   * Initializes the table by resolving headers. Must be called before using sync methods.
+   * @param options Optional timeout for header resolution (default: 3000ms)
+   */
+  init(options?: { timeout?: number }): Promise<TableResult>;
+
   getHeaders: () => Promise<string[]>;
   getHeaderCell: (columnName: string) => Promise<Locator>;
 
-  getByRow: <T extends { asJSON?: boolean }>(
+  /**
+   * Finds a row on the current page only. Returns immediately (sync).
+   * Throws error if table is not initialized.
+   */
+  getByRow: (
+    filters: Record<string, string | RegExp | number>, 
+    options?: { exact?: boolean }
+  ) => SmartRow;
+
+  /**
+   * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).
+   * Auto-initializes if needed.
+   */
+  searchForRow: (
     filters: Record<string, string | RegExp | number>, 
-    options?: { exact?: boolean, maxPages?: number } & T
-  ) => Promise<T['asJSON'] extends true ? Record<string, string> : SmartRow>;
+    options?: { exact?: boolean, maxPages?: number }
+  ) => Promise<SmartRow>;
 
   getAllRows: <T extends { asJSON?: boolean }>(
     options?: { filter?: Record<string, any>, exact?: boolean } & T
@@ -147,5 +168,34 @@ export interface TableResult {
      */
     getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;
   };
+
+  /**
+   * Iterates through paginated table data, calling the callback for each iteration.
+   * Callback return values are automatically appended to allData, which is returned.
+   */
+  iterateThroughTable: <T = any>(
+    callback: (context: {
+      index: number;
+      isFirst: boolean;
+      isLast: boolean;
+      rows: SmartRow[];
+      allData: T[];
+      table: RestrictedTableResult;
+    }) => T | Promise<T>,
+    options?: {
+      pagination?: PaginationStrategy;
+      dedupeStrategy?: DedupeStrategy;
+      maxIterations?: 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>;
+    }
+  ) => Promise<T[]>;
 }
+
+/**
+ * Restricted table result that excludes methods that shouldn't be called during iteration.
+ */
+export type RestrictedTableResult = Omit<TableResult, 'searchForRow' | 'iterateThroughTable' | 'reset'>;
 `;

package/dist/types.d.ts

@@ -1,12 +1,12 @@
 import type { Locator, Page } from '@playwright/test';
 export type Selector = string | ((root: Locator | Page) => Locator);
-export type SmartRow = Omit<Locator, 'fill'> & {
+export type SmartRow = Locator & {
     getCell(column: string): Locator;
     toJSON(): Promise<Record<string, string>>;
     /**
      * Fills the row with data. Automatically detects input types (text input, select, checkbox, etc.).
      */
-    fill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
+    smartFill: (data: Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 export type StrategyContext = TableContext;
 /**
@@ -36,6 +36,7 @@ export interface TableContext {
     resolve: (selector: Selector, parent: Locator | Page) => Locator;
 }
 export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
+export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 export interface PromptOptions {
     /**
      * Output Strategy:
@@ -69,7 +70,7 @@ export interface TableConfig {
      */
     debug?: boolean;
     /**
-     * Strategy to reset the table to the first page.
+     * Strategy to reset the table to the initial page.
      * Called when table.reset() is invoked.
      */
     onReset?: (context: TableContext) => Promise<void>;
@@ -90,14 +91,30 @@ export interface FillOptions {
     inputMappers?: Record<string, (cell: Locator) => Locator>;
 }
 export interface TableResult {
+    /**
+     * Initializes the table by resolving headers. Must be called before using sync methods.
+     * @param options Optional timeout for header resolution (default: 3000ms)
+     */
+    init(options?: {
+        timeout?: number;
+    }): Promise<TableResult>;
     getHeaders: () => Promise<string[]>;
     getHeaderCell: (columnName: string) => Promise<Locator>;
-    getByRow: <T extends {
-        asJSON?: boolean;
-    }>(filters: Record<string, string | RegExp | number>, options?: {
+    /**
+     * Finds a row on the current page only. Returns immediately (sync).
+     * Throws error if table is not initialized.
+     */
+    getByRow: (filters: Record<string, string | RegExp | number>, options?: {
+        exact?: boolean;
+    }) => SmartRow;
+    /**
+     * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).
+     * Auto-initializes if needed.
+     */
+    searchForRow: (filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
         maxPages?: number;
-    } & T) => Promise<T['asJSON'] extends true ? Record<string, string> : SmartRow>;
+    }) => Promise<SmartRow>;
     getAllRows: <T extends {
         asJSON?: boolean;
     }>(options?: {
@@ -134,4 +151,41 @@ export interface TableResult {
          */
         getState(columnName: string): Promise<'asc' | 'desc' | 'none'>;
     };
+    /**
+     * Iterates through paginated table data, calling the callback for each iteration.
+     * Callback return values are automatically appended to allData, which is returned.
+     */
+    iterateThroughTable: <T = any>(callback: (context: {
+        index: number;
+        isFirst: boolean;
+        isLast: boolean;
+        rows: SmartRow[];
+        allData: T[];
+        table: RestrictedTableResult;
+    }) => T | Promise<T>, options?: {
+        pagination?: PaginationStrategy;
+        dedupeStrategy?: DedupeStrategy;
+        maxIterations?: 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>;
+    }) => Promise<T[]>;
 }
+/**
+ * Restricted table result that excludes methods that shouldn't be called during iteration.
+ */
+export type RestrictedTableResult = Omit<TableResult, 'searchForRow' | 'iterateThroughTable' | 'reset'>;

package/dist/useTable.d.ts

@@ -1,20 +1,20 @@
 import type { Locator } from '@playwright/test';
-import { TableConfig, Selector, TableResult } from './types';
+import { TableConfig, Selector, TableResult, PaginationStrategy } from './types';
 /**
  * A collection of pre-built pagination strategies.
  */
 export declare const PaginationStrategies: {
-    clickNext: (nextButtonSelector: Selector, timeout?: number) => import("./types").PaginationStrategy;
-    clickLoadMore: (buttonSelector: Selector, timeout?: number) => import("./types").PaginationStrategy;
-    infiniteScroll: (timeout?: number) => import("./types").PaginationStrategy;
+    clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
+    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
+    infiniteScroll: (timeout?: number) => PaginationStrategy;
 };
 /**
  * @deprecated Use `PaginationStrategies` instead. This alias will be removed in a future major version.
  */
 export declare const TableStrategies: {
-    clickNext: (nextButtonSelector: Selector, timeout?: number) => import("./types").PaginationStrategy;
-    clickLoadMore: (buttonSelector: Selector, timeout?: number) => import("./types").PaginationStrategy;
-    infiniteScroll: (timeout?: number) => import("./types").PaginationStrategy;
+    clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
+    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
+    infiniteScroll: (timeout?: number) => PaginationStrategy;
 };
 /**
  * A collection of pre-built sorting strategies.

package/dist/useTable.js

@@ -26,6 +26,8 @@ exports.TableStrategies = pagination_1.TableStrategies;
  */
 exports.SortingStrategies = sorting_1.SortingStrategies;
 const useTable = (rootLocator, configOptions = {}) => {
+    // Store whether pagination was explicitly provided in config
+    const hasPaginationInConfig = configOptions.pagination !== undefined;
     const config = Object.assign({ rowSelector: "tbody tr", headerSelector: "th", cellSelector: "td", pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }), maxPages: 1, headerTransformer: ({ text, index, locator }) => text, autoScroll: true, debug: false, onReset: () => __awaiter(void 0, void 0, void 0, function* () { console.warn("⚠️ .reset() called but no 'onReset' strategy defined in config."); }) }, configOptions);
     const resolve = (item, parent) => {
         if (typeof item === 'string')
@@ -37,6 +39,7 @@ const useTable = (rootLocator, configOptions = {}) => {
     // Internal State
     let _headerMap = null;
     let _hasPaginated = false;
+    let _isInitialized = false;
     const logDebug = (msg) => {
         if (config.debug)
             console.log(`🔎 [SmartTable Debug] ${msg}`);
@@ -65,10 +68,11 @@ const useTable = (rootLocator, configOptions = {}) => {
         const contextMsg = context ? ` (${context})` : '';
         return new Error(`Column "${colName}" not found${contextMsg}${suggestion}`);
     };
-    const _getMap = () => __awaiter(void 0, void 0, void 0, function* () {
+    const _getMap = (timeout) => __awaiter(void 0, void 0, void 0, function* () {
         if (_headerMap)
             return _headerMap;
         logDebug('Mapping headers...');
+        const headerTimeout = timeout !== null && timeout !== void 0 ? timeout : 3000;
         if (config.autoScroll) {
             try {
                 yield rootLocator.scrollIntoViewIfNeeded({ timeout: 1000 });
@@ -77,7 +81,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         }
         const headerLoc = resolve(config.headerSelector, rootLocator);
         try {
-            yield headerLoc.first().waitFor({ state: 'visible', timeout: 3000 });
+            yield headerLoc.first().waitFor({ state: 'visible', timeout: headerTimeout });
         }
         catch (e) { /* Ignore hydration */ }
         // 1. Fetch data efficiently
@@ -126,7 +130,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return result;
         });
-        smart.fill = (data, fillOptions) => __awaiter(void 0, void 0, void 0, function* () {
+        smart.smartFill = (data, fillOptions) => __awaiter(void 0, void 0, void 0, function* () {
             var _a;
             logDebug(`Filling row with data: ${JSON.stringify(data)}`);
             // Fill each column
@@ -327,41 +331,35 @@ const useTable = (rootLocator, configOptions = {}) => {
             return clone.outerHTML;
         });
     });
-    const sortingNamespace = {
-        apply: (columnName, direction) => __awaiter(void 0, void 0, void 0, function* () {
-            if (!config.sorting) {
-                throw new Error('No sorting strategy has been configured. Please add a `sorting` strategy to your useTable config.');
+    // Helper to ensure initialization for async methods
+    const _ensureInitialized = () => __awaiter(void 0, void 0, void 0, function* () {
+        if (!_isInitialized) {
+            yield _getMap();
+            _isInitialized = true;
+        }
+    });
+    const result = {
+        init: (options) => __awaiter(void 0, void 0, void 0, function* () {
+            if (_isInitialized && _headerMap) {
+                return result;
             }
-            logDebug(`Applying sort for column "${columnName}" (${direction})`);
-            const context = {
-                root: rootLocator,
-                config: config,
-                page: rootLocator.page(),
-                resolve: resolve
-            };
-            yield config.sorting.doSort({ columnName, direction, context });
+            yield _getMap(options === null || options === void 0 ? void 0 : options.timeout);
+            _isInitialized = true;
+            return result;
         }),
-        getState: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
-            if (!config.sorting) {
-                throw new Error('No sorting strategy has been configured. Please add a `sorting` strategy to your useTable config.');
+        getHeaders: () => __awaiter(void 0, void 0, void 0, function* () {
+            if (!_isInitialized || !_headerMap) {
+                throw new Error('Table not initialized. Call await table.init() first.');
             }
-            logDebug(`Getting sort state for column "${columnName}"`);
-            const context = {
-                root: rootLocator,
-                config: config,
-                page: rootLocator.page(),
-                resolve: resolve
-            };
-            return config.sorting.getSortState({ columnName, context });
-        })
-    };
-    return {
-        getHeaders: () => __awaiter(void 0, void 0, void 0, function* () { return Array.from((yield _getMap()).keys()); }),
+            return Array.from(_headerMap.keys());
+        }),
         getHeaderCell: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
-            const map = yield _getMap();
-            const idx = map.get(columnName);
+            if (!_isInitialized || !_headerMap) {
+                throw new Error('Table not initialized. Call await table.init() first.');
+            }
+            const idx = _headerMap.get(columnName);
             if (idx === undefined)
-                throw _createColumnError(columnName, map, 'header cell');
+                throw _createColumnError(columnName, _headerMap, 'header cell');
             return resolve(config.headerSelector, rootLocator).nth(idx);
         }),
         reset: () => __awaiter(void 0, void 0, void 0, function* () {
@@ -375,14 +373,16 @@ const useTable = (rootLocator, configOptions = {}) => {
             yield config.onReset(context);
             _hasPaginated = false;
             _headerMap = null;
+            _isInitialized = false;
             logDebug("Table reset complete.");
         }),
         getColumnValues: (column, options) => __awaiter(void 0, void 0, void 0, function* () {
             var _a, _b;
-            const map = yield _getMap();
-            const colIdx = map.get(column);
+            // Auto-init if needed (async methods can auto-init)
+            yield _ensureInitialized();
+            const colIdx = _headerMap.get(column);
             if (colIdx === undefined)
-                throw _createColumnError(column, map);
+                throw _createColumnError(column, _headerMap);
             const mapper = (_a = options === null || options === void 0 ? void 0 : options.mapper) !== null && _a !== void 0 ? _a : ((c) => c.innerText());
             const effectiveMaxPages = (_b = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _b !== void 0 ? _b : config.maxPages;
             let currentPage = 1;
@@ -410,25 +410,37 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return results;
         }),
-        getByRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
+        getByRow: (filters, options) => {
+            // Throw error if not initialized (sync methods require explicit init)
+            if (!_isInitialized || !_headerMap) {
+                throw new Error('Table not initialized. Call await table.init() first.');
+            }
+            // Build locator chain (sync) - current page only
+            const allRows = resolve(config.rowSelector, rootLocator);
+            const matchedRows = _applyFilters(allRows, filters, _headerMap, (options === null || options === void 0 ? void 0 : options.exact) || false);
+            // Return first match (or sentinel) - lazy, doesn't check existence
+            const rowLocator = matchedRows.first();
+            return _makeSmart(rowLocator, _headerMap);
+        },
+        searchForRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
+            // Auto-init if needed (async methods can auto-init)
+            yield _ensureInitialized();
+            // Full pagination logic (existing _findRowLocator logic)
             let row = yield _findRowLocator(filters, options);
             if (!row) {
                 row = resolve(config.rowSelector, rootLocator).filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() });
             }
-            const smartRow = _makeSmart(row, yield _getMap());
-            if (options === null || options === void 0 ? void 0 : options.asJSON) {
-                return smartRow.toJSON();
-            }
-            return smartRow;
+            return _makeSmart(row, _headerMap);
         }),
         getAllRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            const map = yield _getMap();
+            // Auto-init if needed (async methods can auto-init)
+            yield _ensureInitialized();
             let rowLocators = resolve(config.rowSelector, rootLocator);
             if (options === null || options === void 0 ? void 0 : options.filter) {
-                rowLocators = _applyFilters(rowLocators, options.filter, map, options.exact || false);
+                rowLocators = _applyFilters(rowLocators, options.filter, _headerMap, options.exact || false);
             }
             const rows = yield rowLocators.all();
-            const smartRows = rows.map(loc => _makeSmart(loc, map));
+            const smartRows = rows.map(loc => _makeSmart(loc, _headerMap));
             if (options === null || options === void 0 ? void 0 : options.asJSON) {
                 return Promise.all(smartRows.map(r => r.toJSON()));
             }
@@ -446,7 +458,140 @@ const useTable = (rootLocator, configOptions = {}) => {
             const content = `\n==================================================\n🤖 COPY INTO GEMINI/ChatGPT TO WRITE A STRATEGY 🤖\n==================================================\nI need a custom Pagination Strategy for 'playwright-smart-table'.\nContainer HTML:\n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n`;
             yield _handlePrompt('Smart Table Strategy', content, options);
         }),
-        sorting: sortingNamespace,
+        sorting: {
+            apply: (columnName, direction) => __awaiter(void 0, void 0, void 0, function* () {
+                // Auto-init if needed (async methods can auto-init)
+                yield _ensureInitialized();
+                if (!config.sorting) {
+                    throw new Error('No sorting strategy has been configured. Please add a `sorting` strategy to your useTable config.');
+                }
+                logDebug(`Applying sort for column "${columnName}" (${direction})`);
+                const context = {
+                    root: rootLocator,
+                    config: config,
+                    page: rootLocator.page(),
+                    resolve: resolve
+                };
+                yield config.sorting.doSort({ columnName, direction, context });
+            }),
+            getState: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
+                // Auto-init if needed (async methods can auto-init)
+                yield _ensureInitialized();
+                if (!config.sorting) {
+                    throw new Error('No sorting strategy has been configured. Please add a `sorting` strategy to your useTable config.');
+                }
+                logDebug(`Getting sort state for column "${columnName}"`);
+                const context = {
+                    root: rootLocator,
+                    config: config,
+                    page: rootLocator.page(),
+                    resolve: resolve
+                };
+                return config.sorting.getSortState({ columnName, context });
+            })
+        },
+        iterateThroughTable: (callback, options) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            // Auto-init if needed (async methods can auto-init)
+            yield _ensureInitialized();
+            // Determine pagination strategy
+            const paginationStrategy = (_a = options === null || options === void 0 ? void 0 : options.pagination) !== null && _a !== void 0 ? _a : config.pagination;
+            // Check if pagination was explicitly provided in options or config
+            const hasPaginationInOptions = (options === null || options === void 0 ? void 0 : options.pagination) !== undefined;
+            if (!hasPaginationInOptions && !hasPaginationInConfig) {
+                throw new Error('No pagination strategy provided. Either set pagination in options or in table config.');
+            }
+            // Reset to initial page before starting
+            yield result.reset();
+            yield result.init();
+            // Create restricted table instance (excludes problematic methods)
+            const restrictedTable = {
+                init: result.init,
+                getHeaders: result.getHeaders,
+                getHeaderCell: result.getHeaderCell,
+                getByRow: result.getByRow,
+                getAllRows: result.getAllRows,
+                getColumnValues: result.getColumnValues,
+                generateConfigPrompt: result.generateConfigPrompt,
+                generateStrategyPrompt: result.generateStrategyPrompt,
+                sorting: result.sorting,
+            };
+            // Default functions
+            const getIsFirst = (_b = options === null || options === void 0 ? void 0 : options.getIsFirst) !== null && _b !== void 0 ? _b : (({ index }) => index === 0);
+            const getIsLast = (_c = options === null || options === void 0 ? void 0 : options.getIsLast) !== null && _c !== void 0 ? _c : (() => false);
+            // Create allData array (persists across iterations)
+            const allData = [];
+            const effectiveMaxIterations = (_d = options === null || options === void 0 ? void 0 : options.maxIterations) !== null && _d !== void 0 ? _d : config.maxPages;
+            let index = 0;
+            let paginationResult = true; // Will be set after first pagination attempt
+            let seenKeys = null; // Track seen keys across iterations for deduplication
+            logDebug(`Starting iterateThroughTable (maxIterations: ${effectiveMaxIterations})`);
+            while (index < effectiveMaxIterations) {
+                // Get current rows
+                const rowLocators = yield resolve(config.rowSelector, rootLocator).all();
+                let rows = rowLocators.map(loc => _makeSmart(loc, _headerMap));
+                // Deduplicate if dedupeStrategy provided (across all iterations)
+                if ((options === null || options === void 0 ? void 0 : options.dedupeStrategy) && rows.length > 0) {
+                    if (!seenKeys) {
+                        seenKeys = new Set();
+                    }
+                    const deduplicated = [];
+                    for (const row of rows) {
+                        const key = yield options.dedupeStrategy(row);
+                        if (!seenKeys.has(key)) {
+                            seenKeys.add(key);
+                            deduplicated.push(row);
+                        }
+                    }
+                    rows = deduplicated;
+                    logDebug(`Deduplicated ${rowLocators.length} rows to ${rows.length} unique rows (total seen: ${seenKeys.size})`);
+                }
+                // Determine flags (isLast will be checked after pagination attempt)
+                const isFirst = getIsFirst({ index });
+                let isLast = getIsLast({ index, paginationResult });
+                // Check if this is the last iteration due to maxIterations (before attempting pagination)
+                const isLastDueToMax = index === effectiveMaxIterations - 1;
+                // Call onFirst hook if applicable
+                if (isFirst && (options === null || options === void 0 ? void 0 : options.onFirst)) {
+                    yield options.onFirst({ index, rows, allData });
+                }
+                // Call main callback
+                const returnValue = yield callback({
+                    index,
+                    isFirst,
+                    isLast,
+                    rows,
+                    allData,
+                    table: restrictedTable,
+                });
+                // Append return value to allData
+                allData.push(returnValue);
+                // Attempt pagination (before checking if we should continue)
+                const context = {
+                    root: rootLocator,
+                    config: config,
+                    page: rootLocator.page(),
+                    resolve: resolve
+                };
+                paginationResult = yield paginationStrategy(context);
+                // Now check isLast with updated paginationResult
+                isLast = getIsLast({ index, paginationResult }) || isLastDueToMax;
+                // Call onLast hook if applicable (after we know pagination failed or we're at max iterations)
+                if (isLast && (options === null || options === void 0 ? void 0 : options.onLast)) {
+                    yield options.onLast({ index, rows, allData });
+                }
+                // Check if we should continue
+                if (isLast || !paginationResult) {
+                    logDebug(`Reached last iteration (index: ${index}, paginationResult: ${paginationResult}, isLastDueToMax: ${isLastDueToMax})`);
+                    break;
+                }
+                index++;
+                logDebug(`Iteration ${index} completed, continuing...`);
+            }
+            logDebug(`iterateThroughTable completed after ${index + 1} iterations, collected ${allData.length} items`);
+            return allData;
+        }),
     };
+    return result;
 };
 exports.useTable = useTable;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "2.3.1",
+  "version": "3.1.0",
   "description": "A smart table utility for Playwright with built-in pagination strategies that are fully extensible.",
   "repository": {
     "type": "git",