@rickcedwhat/playwright-smart-table 4.0.0 → 5.1.0

package/dist/typeContext.js

@@ -7,6 +7,15 @@ exports.TYPE_CONTEXT = void 0;
  * It contains the raw text of types.ts to provide context for LLM prompts.
  */
 exports.TYPE_CONTEXT = `
+/**
+ * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.
+ * @example
+ * // String selector
+ * rowSelector: 'tbody tr'
+ * 
+ * // Function selector
+ * rowSelector: (root) => root.locator('[role="row"]')
+ */
 export type Selector = string | ((root: Locator | Page) => Locator);
 
 /**
@@ -33,22 +42,69 @@ export type GetActiveCellFn = (args: TableContext) => Promise<{
 } | null>;
 
 
+/**
+ * SmartRow - A Playwright Locator with table-aware methods.
+ * 
+ * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.
+ * 
+ * @example
+ * const row = table.getRow({ Name: 'John Doe' });
+ * await row.click(); // Standard Locator method
+ * const email = row.getCell('Email'); // Table-aware method
+ * const data = await row.toJSON(); // Extract all row data
+ * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields
+ */
 export type SmartRow<T = any> = Locator & {
-  getRequestIndex(): number | undefined;
+  /** Optional row index (0-based) if known */
   rowIndex?: number;
+
+  /**
+   * Get a cell locator by column name.
+   * @param column - Column name (case-sensitive)
+   * @returns Locator for the cell
+   * @example
+   * const emailCell = row.getCell('Email');
+   * await expect(emailCell).toHaveText('john@example.com');
+   */
   getCell(column: string): Locator;
+
+  /**
+   * Extract all cell data as a key-value object.
+   * @param options - Optional configuration
+   * @param options.columns - Specific columns to extract (extracts all if not specified)
+   * @returns Promise resolving to row data
+   * @example
+   * const data = await row.toJSON();
+   * // { Name: 'John', Email: 'john@example.com', ... }
+   * 
+   * const partial = await row.toJSON({ columns: ['Name', 'Email'] });
+   * // { Name: 'John', Email: 'john@example.com' }
+   */
   toJSON(options?: { columns?: string[] }): Promise<T>;
+
   /**
    * Scrolls/paginates to bring this row into view.
-   * Only works if rowIndex is known.
+   * Only works if rowIndex is known (e.g., from getRowByIndex).
+   * @throws Error if rowIndex is unknown
    */
   bringIntoView(): Promise<void>;
+
   /**
-   * Fills the row with data. Automatically detects input types.
-   */
-  fill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
-  /**
-   * Alias for fill() to avoid conflict with Locator.fill()
+   * Intelligently fills form fields in the row.
+   * Automatically detects input types (text, select, checkbox, contenteditable).
+   * 
+   * @param data - Column-value pairs to fill
+   * @param options - Optional configuration
+   * @param options.inputMappers - Custom input selectors per column
+   * @example
+   * // Auto-detection
+   * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });
+   * 
+   * // Custom input mappers
+   * await row.smartFill(
+   *   { Name: 'John' },
+   *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }
+   * );
    */
   smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
 };
@@ -201,6 +257,12 @@ export interface TableResult<T = any> {
    */
   init(options?: { timeout?: number }): Promise<TableResult>;
 
+  /**
+   * SYNC: Checks if the table has been initialized.
+   * @returns true if init() has been called and completed, false otherwise
+   */
+  isInitialized(): boolean;
+
   getHeaders: () => Promise<string[]>;
   getHeaderCell: (columnName: string) => Promise<Locator>;
 
@@ -208,7 +270,7 @@ export interface TableResult<T = any> {
    * Finds a row by filters on the current page only. Returns immediately (sync).
    * Throws error if table is not initialized.
    */
-  getByRow: (
+  getRow: (
     filters: Record<string, string | RegExp | number>,
     options?: { exact?: boolean }
   ) => SmartRow;
@@ -219,38 +281,46 @@ export interface TableResult<T = any> {
    * @param index 1-based row index
    * @param options Optional settings including bringIntoView
    */
-  getByRowIndex: (
+  getRowByIndex: (
     index: number,
     options?: { bringIntoView?: boolean }
   ) => SmartRow;
 
   /**
-   * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).
-   * Auto-initializes if needed.
+   * ASYNC: Searches for a single row across pages using pagination.
+   * Auto-initializes the table if not already initialized.
+   * @param filters - The filter criteria to match
+   * @param options - Search options including exact match and max pages
    */
-  searchForRow: (
+  findRow: (
     filters: Record<string, string | RegExp | number>,
     options?: { exact?: boolean, maxPages?: number }
   ) => Promise<SmartRow>;
 
+  /**
+   * ASYNC: Searches for all matching rows across pages using pagination.
+   * Auto-initializes the table if not already initialized.
+   * @param filters - The filter criteria to match
+   * @param options - Search options including exact match, max pages, and asJSON
+   */
+  findRows: <R extends { asJSON?: boolean }>(
+    filters: Record<string, string | RegExp | number>,
+    options?: { exact?: boolean, maxPages?: number } & R
+  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+
   /**
    * Navigates to a specific column using the configured CellNavigationStrategy.
    */
   scrollToColumn: (columnName: string) => Promise<void>;
 
-  getAllCurrentRows: <T extends { asJSON?: boolean }>(
-    options?: { filter?: Record<string, any>, exact?: boolean } & T
-  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
-
   /**
-   * @deprecated Use getAllCurrentRows instead. This method will be removed in a future major version.
+   * ASYNC: Gets all rows on the current page only (does not paginate).
+   * Auto-initializes the table if not already initialized.
+   * @param options - Filter and formatting options
    */
-  getAllRows: <T extends { asJSON?: boolean }>(
-    options?: { filter?: Record<string, any>, exact?: boolean } & T
-  ) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
-
-  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
-  generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;
+  getRows: <R extends { asJSON?: boolean }>(
+    options?: { filter?: Record<string, any>, exact?: boolean } & R
+  ) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
 
   /**
    * Resets the table state (clears cache, flags) and invokes the onReset strategy.
@@ -298,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[]>;
 }
@@ -314,5 +390,5 @@ export interface TableResult<T = any> {
 /**
  * Restricted table result that excludes methods that shouldn't be called during iteration.
  */
-export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset' | 'getAllRows'>;
+export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;
 `;

package/dist/types.d.ts

@@ -1,4 +1,13 @@
 import type { Locator, Page } from '@playwright/test';
+/**
+ * Flexible selector type - can be a CSS string, function returning a Locator, or Locator itself.
+ * @example
+ * // String selector
+ * rowSelector: 'tbody tr'
+ *
+ * // Function selector
+ * rowSelector: (root) => root.locator('[role="row"]')
+ */
 export type Selector = string | ((root: Locator | Page) => Locator);
 /**
  * Function to get a cell locator given row, column info.
@@ -21,24 +30,67 @@ export type GetActiveCellFn = (args: TableContext) => Promise<{
     columnName?: string;
     locator: Locator;
 } | null>;
+/**
+ * SmartRow - A Playwright Locator with table-aware methods.
+ *
+ * Extends all standard Locator methods (click, isVisible, etc.) with table-specific functionality.
+ *
+ * @example
+ * const row = table.getRow({ Name: 'John Doe' });
+ * await row.click(); // Standard Locator method
+ * const email = row.getCell('Email'); // Table-aware method
+ * const data = await row.toJSON(); // Extract all row data
+ * await row.smartFill({ Name: 'Jane', Status: 'Active' }); // Fill form fields
+ */
 export type SmartRow<T = any> = Locator & {
-    getRequestIndex(): number | undefined;
+    /** Optional row index (0-based) if known */
     rowIndex?: number;
+    /**
+     * Get a cell locator by column name.
+     * @param column - Column name (case-sensitive)
+     * @returns Locator for the cell
+     * @example
+     * const emailCell = row.getCell('Email');
+     * await expect(emailCell).toHaveText('john@example.com');
+     */
     getCell(column: string): Locator;
+    /**
+     * Extract all cell data as a key-value object.
+     * @param options - Optional configuration
+     * @param options.columns - Specific columns to extract (extracts all if not specified)
+     * @returns Promise resolving to row data
+     * @example
+     * const data = await row.toJSON();
+     * // { Name: 'John', Email: 'john@example.com', ... }
+     *
+     * const partial = await row.toJSON({ columns: ['Name', 'Email'] });
+     * // { Name: 'John', Email: 'john@example.com' }
+     */
     toJSON(options?: {
         columns?: string[];
     }): Promise<T>;
     /**
      * Scrolls/paginates to bring this row into view.
-     * Only works if rowIndex is known.
+     * Only works if rowIndex is known (e.g., from getRowByIndex).
+     * @throws Error if rowIndex is unknown
      */
     bringIntoView(): Promise<void>;
     /**
-     * Fills the row with data. Automatically detects input types.
-     */
-    fill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
-    /**
-     * Alias for fill() to avoid conflict with Locator.fill()
+     * Intelligently fills form fields in the row.
+     * Automatically detects input types (text, select, checkbox, contenteditable).
+     *
+     * @param data - Column-value pairs to fill
+     * @param options - Optional configuration
+     * @param options.inputMappers - Custom input selectors per column
+     * @example
+     * // Auto-detection
+     * await row.smartFill({ Name: 'John', Status: 'Active', Subscribe: true });
+     *
+     * // Custom input mappers
+     * await row.smartFill(
+     *   { Name: 'John' },
+     *   { inputMappers: { Name: (cell) => cell.locator('.custom-input') } }
+     * );
      */
     smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
 };
@@ -191,13 +243,18 @@ export interface TableResult<T = any> {
     init(options?: {
         timeout?: number;
     }): Promise<TableResult>;
+    /**
+     * SYNC: Checks if the table has been initialized.
+     * @returns true if init() has been called and completed, false otherwise
+     */
+    isInitialized(): boolean;
     getHeaders: () => Promise<string[]>;
     getHeaderCell: (columnName: string) => Promise<Locator>;
     /**
      * Finds a row by filters on the current page only. Returns immediately (sync).
      * Throws error if table is not initialized.
      */
-    getByRow: (filters: Record<string, string | RegExp | number>, options?: {
+    getRow: (filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
     }) => SmartRow;
     /**
@@ -206,38 +263,46 @@ export interface TableResult<T = any> {
      * @param index 1-based row index
      * @param options Optional settings including bringIntoView
      */
-    getByRowIndex: (index: number, options?: {
+    getRowByIndex: (index: number, options?: {
         bringIntoView?: boolean;
     }) => SmartRow;
     /**
-     * Searches for a row across all available data using the configured strategy (pagination, scroll, etc.).
-     * Auto-initializes if needed.
+     * ASYNC: Searches for a single row across pages using pagination.
+     * Auto-initializes the table if not already initialized.
+     * @param filters - The filter criteria to match
+     * @param options - Search options including exact match and max pages
      */
-    searchForRow: (filters: Record<string, string | RegExp | number>, options?: {
+    findRow: (filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
         maxPages?: number;
     }) => Promise<SmartRow>;
     /**
-     * Navigates to a specific column using the configured CellNavigationStrategy.
+     * ASYNC: Searches for all matching rows across pages using pagination.
+     * Auto-initializes the table if not already initialized.
+     * @param filters - The filter criteria to match
+     * @param options - Search options including exact match, max pages, and asJSON
      */
-    scrollToColumn: (columnName: string) => Promise<void>;
-    getAllCurrentRows: <T extends {
+    findRows: <R extends {
         asJSON?: boolean;
-    }>(options?: {
-        filter?: Record<string, any>;
+    }>(filters: Record<string, string | RegExp | number>, options?: {
         exact?: boolean;
-    } & T) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
+        maxPages?: number;
+    } & R) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
     /**
-     * @deprecated Use getAllCurrentRows instead. This method will be removed in a future major version.
+     * Navigates to a specific column using the configured CellNavigationStrategy.
      */
-    getAllRows: <T extends {
+    scrollToColumn: (columnName: string) => Promise<void>;
+    /**
+     * ASYNC: Gets all rows on the current page only (does not paginate).
+     * Auto-initializes the table if not already initialized.
+     * @param options - Filter and formatting options
+     */
+    getRows: <R extends {
         asJSON?: boolean;
     }>(options?: {
         filter?: Record<string, any>;
         exact?: boolean;
-    } & T) => Promise<T['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
-    generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
-    generateStrategyPrompt: (options?: PromptOptions) => Promise<void>;
+    } & R) => Promise<R['asJSON'] extends true ? Record<string, string>[] : SmartRow[]>;
     /**
      * Resets the table state (clears cache, flags) and invokes the onReset strategy.
      */
@@ -282,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;
@@ -293,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[];
@@ -308,4 +379,4 @@ export interface TableResult<T = any> {
 /**
  * Restricted table result that excludes methods that shouldn't be called during iteration.
  */
-export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset' | 'getAllRows'>;
+export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;

package/dist/useTable.d.ts

@@ -2,7 +2,7 @@ import type { Locator } from '@playwright/test';
 import { TableConfig, Selector, TableResult, PaginationStrategy } from './types';
 import { FillStrategies } from './strategies/fill';
 import { HeaderStrategies } from './strategies/headers';
-import { CellNavigationStrategies, ColumnStrategies } from './strategies/columns';
+import { CellNavigationStrategies } from './strategies/columns';
 import { ResolutionStrategies } from './strategies/resolution';
 import { Strategies } from './strategies';
 /**
@@ -11,16 +11,9 @@ import { Strategies } from './strategies';
 export declare const useTable: <T = any>(rootLocator: Locator, configOptions?: TableConfig) => TableResult<T>;
 export declare const PaginationStrategies: {
     clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
-    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
-    infiniteScroll: (timeout?: number) => PaginationStrategy;
-};
-/** @deprecated Use Strategies.Pagination instead */
-export declare const DeprecatedTableStrategies: {
-    clickNext: (nextButtonSelector: Selector, timeout?: number) => PaginationStrategy;
-    clickLoadMore: (buttonSelector: Selector, timeout?: number) => PaginationStrategy;
     infiniteScroll: (timeout?: number) => PaginationStrategy;
 };
 export declare const SortingStrategies: {
     AriaSort: () => import("./types").SortingStrategy;
 };
-export { FillStrategies, HeaderStrategies, CellNavigationStrategies, ColumnStrategies, ResolutionStrategies, Strategies };
+export { FillStrategies, HeaderStrategies, CellNavigationStrategies, ResolutionStrategies, Strategies };