@rickcedwhat/playwright-smart-table 6.4.0 → 6.6.0

package/dist/typeContext.js

@@ -16,7 +16,7 @@ exports.TYPE_CONTEXT = `
  * // Function selector
  * rowSelector: (root) => root.locator('[role="row"]')
  */
-export type Selector = string | ((root: Locator | Page) => Locator);
+export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
 
 /**
  * Value used to filter rows.
@@ -71,6 +71,12 @@ export type SmartRow<T = any> = Locator & {
   /** Optional row index (0-based) if known */
   rowIndex?: number;
 
+  /** Optional page index this row was found on (0-based) */
+  tablePageIndex?: number;
+
+  /** Reference to the parent TableResult */
+  table: TableResult<T>;
+
   /**
    * Get a cell locator by column name.
    * @param column - Column name (case-sensitive)
@@ -178,7 +184,21 @@ export interface TableContext<T = any> {
   resolve: (selector: Selector, parent: Locator | Page) => Locator;
 }
 
-export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
+export interface PaginationPrimitives {
+  /** Classic "Next Page" or "Scroll Down" */
+  goNext?: (context: TableContext) => Promise<boolean>;
+
+  /** Classic "Previous Page" or "Scroll Up" */
+  goPrevious?: (context: TableContext) => Promise<boolean>;
+
+  /** Jump to first page / scroll to top */
+  goToFirst?: (context: TableContext) => Promise<boolean>;
+
+  /** Jump to specific page index (0-indexed) */
+  goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;
+}
+
+export type PaginationStrategy = ((context: TableContext) => Promise<boolean>) | PaginationPrimitives;
 
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 
@@ -191,10 +211,29 @@ export type FillStrategy = (options: {
   index: number;
   page: Page;
   rootLocator: Locator;
+  config: FinalTableConfig<any>;
   table: TableResult; // The parent table instance
   fillOptions?: FillOptions;
 }) => Promise<void>;
 
+export interface ColumnOverride<TValue = any> {
+  /** 
+   * How to extract the value from the cell. (Replaces dataMapper logic)
+   */
+  read?: (cell: Locator) => Promise<TValue> | TValue;
+
+  /** 
+   * How to fill the cell with a new value. (Replaces smartFill default logic)
+   * Provides the current value (via \`read\`) if a \`write\` wants to check state first.
+   */
+  write?: (params: {
+    cell: Locator;
+    targetValue: TValue;
+    currentValue?: TValue;
+    row: SmartRow<any>;
+  }) => Promise<void>;
+}
+
 export type { HeaderStrategy } from './strategies/headers';
 
 /**
@@ -275,10 +314,17 @@ export interface TableConfig<T = any> {
   /** All interaction strategies */
   strategies?: TableStrategies;
   /**
+   * @deprecated Use \`columnOverrides\` instead. \`dataMapper\` will be removed in v7.0.0.
    * Custom data mappers for specific columns.
    * Allows extracting complex data types (boolean, number) instead of just string.
    */
   dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;
+
+  /**
+   * Unified interface for reading and writing data to specific columns.
+   * Overrides both default extraction (toJSON) and filling (smartFill) logic.
+   */
+  columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;
 }
 
 export interface FinalTableConfig<T = any> extends TableConfig<T> {
@@ -319,7 +365,36 @@ export interface PromptOptions {
   includeTypes?: boolean;
 }
 
-export interface TableResult<T = any> {
+/** Callback context passed to forEach, map, and filter. */
+export type RowIterationContext<T = any> = {
+  row: SmartRow<T>;
+  rowIndex: number;
+  stop: () => void;
+};
+
+/** Shared options for forEach, map, and filter. */
+export type RowIterationOptions = {
+  /** Maximum number of pages to iterate. Defaults to config.maxPages. */
+  maxPages?: number;
+  /**
+   * Whether to process rows within a page concurrently.
+   * @default false for forEach/filter, true for map
+   */
+  parallel?: boolean;
+  /**
+   * Deduplication strategy. Use when rows may repeat across iterations
+   * (e.g. infinite scroll tables). Returns a unique key per row.
+   */
+  dedupe?: DedupeStrategy;
+};
+
+export interface TableResult<T = any> extends AsyncIterable<{ row: SmartRow<T>; rowIndex: number }> {
+  /**
+   * Represents the current page index of the table's DOM.
+   * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.
+   */
+  currentPageIndex: number;
+
   /**
    * Initializes the table by resolving headers. Must be called before using sync methods.
    * @param options Optional timeout for header resolution (default: 3000ms)
@@ -395,8 +470,54 @@ export interface TableResult<T = any> {
    */
   revalidate: () => Promise<void>;
 
+  /**
+   * Iterates every row across all pages, calling the callback for side effects.
+   * Execution is sequential by default (safe for interactions like clicking/filling).
+   * Call \`stop()\` in the callback to end iteration early.
+   *
+   * @example
+   * await table.forEach(async ({ row, stop }) => {
+   *   if (await row.getCell('Status').innerText() === 'Done') stop();
+   *   await row.getCell('Checkbox').click();
+   * });
+   */
+  forEach(
+    callback: (ctx: RowIterationContext<T>) => void | Promise<void>,
+    options?: RowIterationOptions
+  ): Promise<void>;
+
+  /**
+   * Transforms every row across all pages into a value. Returns a flat array.
+   * Execution is parallel within each page by default (safe for reads).
+   * Call \`stop()\` to halt after the current page finishes.
+   *
+   * @example
+   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
+   */
+  map<R>(
+    callback: (ctx: RowIterationContext<T>) => R | Promise<R>,
+    options?: RowIterationOptions
+  ): Promise<R[]>;
+
+  /**
+   * Filters rows across all pages by an async predicate. Returns a SmartRowArray.
+   * Rows are returned as-is — call \`bringIntoView()\` on each if needed.
+   * Execution is sequential by default.
+   *
+   * @example
+   * const active = await table.filter(async ({ row }) =>
+   *   await row.getCell('Status').innerText() === 'Active'
+   * );
+   */
+  filter(
+    predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>,
+    options?: RowIterationOptions
+  ): Promise<SmartRowArray<T>>;
+
   /**
    * Scans a specific column across all pages and returns the values.
+   * @deprecated Use \`table.map(({ row }) => row.getCell(column).innerText())\` instead.
+   *             Will be removed in v7.0.0.
    */
   getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;
 
@@ -421,6 +542,9 @@ export interface TableResult<T = any> {
   /**
    * Iterates through paginated table data, calling the callback for each iteration.
    * Callback return values are automatically appended to allData, which is returned.
+   * @deprecated Use \`forEach\`, \`map\`, or \`filter\` instead for cleaner cross-page iteration.
+   *             Only use this for advanced scenarios (batchSize, beforeFirst/afterLast hooks).
+   *             Will be removed in v7.0.0.
    */
   iterateThroughTable: <T = any>(
     callback: (context: {

package/dist/types.d.ts

@@ -9,7 +9,7 @@ import type { SmartRowArray } from './utils/smartRowArray';
  * // Function selector
  * rowSelector: (root) => root.locator('[role="row"]')
  */
-export type Selector = string | ((root: Locator | Page) => Locator);
+export type Selector = string | ((root: Locator | Page) => Locator) | ((root: Locator) => Locator);
 /**
  * Value used to filter rows.
  * - string/number/RegExp: filter by text content of the cell.
@@ -58,6 +58,10 @@ export type GetActiveCellFn = (args: TableContext) => Promise<{
 export type SmartRow<T = any> = Locator & {
     /** Optional row index (0-based) if known */
     rowIndex?: number;
+    /** Optional page index this row was found on (0-based) */
+    tablePageIndex?: number;
+    /** Reference to the parent TableResult */
+    table: TableResult<T>;
     /**
      * Get a cell locator by column name.
      * @param column - Column name (case-sensitive)
@@ -161,7 +165,17 @@ export interface TableContext<T = any> {
     page: Page;
     resolve: (selector: Selector, parent: Locator | Page) => Locator;
 }
-export type PaginationStrategy = (context: TableContext) => Promise<boolean>;
+export interface PaginationPrimitives {
+    /** Classic "Next Page" or "Scroll Down" */
+    goNext?: (context: TableContext) => Promise<boolean>;
+    /** Classic "Previous Page" or "Scroll Up" */
+    goPrevious?: (context: TableContext) => Promise<boolean>;
+    /** Jump to first page / scroll to top */
+    goToFirst?: (context: TableContext) => Promise<boolean>;
+    /** Jump to specific page index (0-indexed) */
+    goToPage?: (pageIndex: number, context: TableContext) => Promise<boolean>;
+}
+export type PaginationStrategy = ((context: TableContext) => Promise<boolean>) | PaginationPrimitives;
 export type DedupeStrategy = (row: SmartRow) => string | number | Promise<string | number>;
 export type FillStrategy = (options: {
     row: SmartRow;
@@ -170,9 +184,26 @@ export type FillStrategy = (options: {
     index: number;
     page: Page;
     rootLocator: Locator;
+    config: FinalTableConfig<any>;
     table: TableResult;
     fillOptions?: FillOptions;
 }) => Promise<void>;
+export interface ColumnOverride<TValue = any> {
+    /**
+     * How to extract the value from the cell. (Replaces dataMapper logic)
+     */
+    read?: (cell: Locator) => Promise<TValue> | TValue;
+    /**
+     * How to fill the cell with a new value. (Replaces smartFill default logic)
+     * Provides the current value (via `read`) if a `write` wants to check state first.
+     */
+    write?: (params: {
+        cell: Locator;
+        targetValue: TValue;
+        currentValue?: TValue;
+        row: SmartRow<any>;
+    }) => Promise<void>;
+}
 import { HeaderStrategy } from './strategies/headers';
 export type { HeaderStrategy } from './strategies/headers';
 import { NavigationPrimitives } from './strategies/columns';
@@ -263,10 +294,16 @@ export interface TableConfig<T = any> {
     /** All interaction strategies */
     strategies?: TableStrategies;
     /**
+     * @deprecated Use `columnOverrides` instead. `dataMapper` will be removed in v7.0.0.
      * Custom data mappers for specific columns.
      * Allows extracting complex data types (boolean, number) instead of just string.
      */
     dataMapper?: Partial<Record<keyof T, (cell: Locator) => Promise<T[keyof T]> | T[keyof T]>>;
+    /**
+     * Unified interface for reading and writing data to specific columns.
+     * Overrides both default extraction (toJSON) and filling (smartFill) logic.
+     */
+    columnOverrides?: Partial<Record<keyof T, ColumnOverride<T[keyof T]>>>;
 }
 export interface FinalTableConfig<T = any> extends TableConfig<T> {
     headerSelector: string | ((root: Locator) => Locator);
@@ -307,7 +344,36 @@ export interface PromptOptions {
      */
     includeTypes?: boolean;
 }
-export interface TableResult<T = any> {
+/** Callback context passed to forEach, map, and filter. */
+export type RowIterationContext<T = any> = {
+    row: SmartRow<T>;
+    rowIndex: number;
+    stop: () => void;
+};
+/** Shared options for forEach, map, and filter. */
+export type RowIterationOptions = {
+    /** Maximum number of pages to iterate. Defaults to config.maxPages. */
+    maxPages?: number;
+    /**
+     * Whether to process rows within a page concurrently.
+     * @default false for forEach/filter, true for map
+     */
+    parallel?: boolean;
+    /**
+     * Deduplication strategy. Use when rows may repeat across iterations
+     * (e.g. infinite scroll tables). Returns a unique key per row.
+     */
+    dedupe?: DedupeStrategy;
+};
+export interface TableResult<T = any> extends AsyncIterable<{
+    row: SmartRow<T>;
+    rowIndex: number;
+}> {
+    /**
+     * Represents the current page index of the table's DOM.
+     * Starts at 0. Automatically maintained by the library during pagination and bringIntoView.
+     */
+    currentPageIndex: number;
     /**
      * Initializes the table by resolving headers. Must be called before using sync methods.
      * @param options Optional timeout for header resolution (default: 3000ms)
@@ -371,8 +437,42 @@ export interface TableResult<T = any> {
      * Useful when columns change visibility or order dynamically.
      */
     revalidate: () => Promise<void>;
+    /**
+     * Iterates every row across all pages, calling the callback for side effects.
+     * Execution is sequential by default (safe for interactions like clicking/filling).
+     * Call `stop()` in the callback to end iteration early.
+     *
+     * @example
+     * await table.forEach(async ({ row, stop }) => {
+     *   if (await row.getCell('Status').innerText() === 'Done') stop();
+     *   await row.getCell('Checkbox').click();
+     * });
+     */
+    forEach(callback: (ctx: RowIterationContext<T>) => void | Promise<void>, options?: RowIterationOptions): Promise<void>;
+    /**
+     * Transforms every row across all pages into a value. Returns a flat array.
+     * Execution is parallel within each page by default (safe for reads).
+     * Call `stop()` to halt after the current page finishes.
+     *
+     * @example
+     * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
+     */
+    map<R>(callback: (ctx: RowIterationContext<T>) => R | Promise<R>, options?: RowIterationOptions): Promise<R[]>;
+    /**
+     * Filters rows across all pages by an async predicate. Returns a SmartRowArray.
+     * Rows are returned as-is — call `bringIntoView()` on each if needed.
+     * Execution is sequential by default.
+     *
+     * @example
+     * const active = await table.filter(async ({ row }) =>
+     *   await row.getCell('Status').innerText() === 'Active'
+     * );
+     */
+    filter(predicate: (ctx: RowIterationContext<T>) => boolean | Promise<boolean>, options?: RowIterationOptions): Promise<SmartRowArray<T>>;
     /**
      * Scans a specific column across all pages and returns the values.
+     * @deprecated Use `table.map(({ row }) => row.getCell(column).innerText())` instead.
+     *             Will be removed in v7.0.0.
      */
     getColumnValues: <V = string>(column: string, options?: {
         mapper?: (cell: Locator) => Promise<V> | V;
@@ -398,6 +498,9 @@ export interface TableResult<T = any> {
     /**
      * Iterates through paginated table data, calling the callback for each iteration.
      * Callback return values are automatically appended to allData, which is returned.
+     * @deprecated Use `forEach`, `map`, or `filter` instead for cleaner cross-page iteration.
+     *             Only use this for advanced scenarios (batchSize, beforeFirst/afterLast hooks).
+     *             Will be removed in v7.0.0.
      */
     iterateThroughTable: <T = any>(callback: (context: {
         index: number;