@rickcedwhat/playwright-smart-table 3.0.0 → 3.1.0

package/README.md

@@ -91,8 +91,8 @@ await table.init();
 // ✅ Verify Colleen is NOT visible initially
 await expect(page.getByText("Colleen Hurst")).not.toBeVisible();
 
-// Use getByRowAcrossPages for pagination
-await expect(await table.getByRowAcrossPages({ 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 -->
@@ -126,7 +126,7 @@ 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.getByRowAcrossPages({ Name: 'Angelica Ramos' });
+  await table.searchForRow({ Name: 'Angelica Ramos' });
 } catch (e) {}
 
 // Reset internal state (and potentially UI) to initial page
@@ -256,7 +256,7 @@ const currentPageRow = table.getByRow({ "Last name": "Melisandre" });
 await expect(currentPageRow).not.toBeVisible();
 
 // Then find it across pages
-const row = await table.getByRowAcrossPages({ "Last name": "Melisandre" });
+const row = await table.searchForRow({ "Last name": "Melisandre" });
 const actionsCell = row.getCell('Actions');
 await actionsCell.getByLabel("Select row").click();
 ```
@@ -328,8 +328,9 @@ await expect(table.getByRow({ Name: "Ghost User" })).not.toBeVisible();
 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');

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 = 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: <T extends { asJSON?: boolean }>(\n    filters: Record<string, string | RegExp | number>, \n    options?: { exact?: boolean } & T\n  ) => T['asJSON'] extends true ? Promise<Record<string, string>> : SmartRow;\n\n  /**\n   * Finds a row across multiple pages using pagination. Auto-initializes if needed.\n   */\n  getByRowAcrossPages: <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  /**\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, 'getByRowAcrossPages' | 'iterateThroughTable' | 'reset'>;\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

@@ -120,18 +120,19 @@ export interface TableResult {
    * Finds a row on the current page only. Returns immediately (sync).
    * Throws error if table is not initialized.
    */
-  getByRow: <T extends { asJSON?: boolean }>(
+  getByRow: (
     filters: Record<string, string | RegExp | number>, 
-    options?: { exact?: boolean } & T
-  ) => T['asJSON'] extends true ? Promise<Record<string, string>> : SmartRow;
+    options?: { exact?: boolean }
+  ) => SmartRow;
 
   /**
-   * Finds a row across multiple pages using pagination. Auto-initializes if needed.
+   * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).
+   * Auto-initializes if needed.
    */
-  getByRowAcrossPages: <T extends { asJSON?: boolean }>(
+  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
@@ -196,5 +197,5 @@ export interface TableResult {
 /**
  * Restricted table result that excludes methods that shouldn't be called during iteration.
  */
-export type RestrictedTableResult = Omit<TableResult, 'getByRowAcrossPages' | 'iterateThroughTable' | 'reset'>;
+export type RestrictedTableResult = Omit<TableResult, 'searchForRow' | 'iterateThroughTable' | 'reset'>;
 `;

package/dist/types.d.ts

@@ -104,20 +104,17 @@ export interface TableResult {
      * Finds a row on the current page only. Returns immediately (sync).
      * Throws error if table is not initialized.
      */
-    getByRow: <T extends {
-        asJSON?: boolean;
-    }>(filters: Record<string, string | RegExp | number>, options?: {
+    getByRow: (filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
-    } & T) => T['asJSON'] extends true ? Promise<Record<string, string>> : SmartRow;
+    }) => SmartRow;
     /**
-     * Finds a row across multiple pages using pagination. Auto-initializes if needed.
+     * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).
+     * Auto-initializes if needed.
      */
-    getByRowAcrossPages: <T extends {
-        asJSON?: boolean;
-    }>(filters: Record<string, string | RegExp | number>, options?: {
+    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?: {
@@ -191,4 +188,4 @@ export interface TableResult {
 /**
  * Restricted table result that excludes methods that shouldn't be called during iteration.
  */
-export type RestrictedTableResult = Omit<TableResult, 'getByRowAcrossPages' | 'iterateThroughTable' | 'reset'>;
+export type RestrictedTableResult = Omit<TableResult, 'searchForRow' | 'iterateThroughTable' | 'reset'>;

package/dist/useTable.js

@@ -420,13 +420,9 @@ const useTable = (rootLocator, configOptions = {}) => {
             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();
-            const smartRow = _makeSmart(rowLocator, _headerMap);
-            if (options === null || options === void 0 ? void 0 : options.asJSON) {
-                return smartRow.toJSON();
-            }
-            return smartRow;
+            return _makeSmart(rowLocator, _headerMap);
         },
-        getByRowAcrossPages: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
+        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)
@@ -434,11 +430,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             if (!row) {
                 row = resolve(config.rowSelector, rootLocator).filter({ hasText: "___SENTINEL_ROW_NOT_FOUND___" + Date.now() });
             }
-            const smartRow = _makeSmart(row, _headerMap);
-            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* () {
             // Auto-init if needed (async methods can auto-init)

package/package.json

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