@rickcedwhat/playwright-smart-table 6.5.0 → 6.7.0

package/dist/typeContext.js

@@ -128,7 +128,12 @@ export type SmartRow<T = any> = Locator & {
   smartFill: (data: Partial<T> | Record<string, any>, options?: FillOptions) => Promise<void>;
 };
 
-export type StrategyContext = TableContext & { rowLocator?: Locator; rowIndex?: number };
+export type StrategyContext = TableContext & {
+  rowLocator?: Locator;
+  rowIndex?: number;
+  /** Helper to reliably get a header cell locator by name */
+  getHeaderCell?: (headerName: string) => Promise<Locator>;
+};
 
 /**
  * Defines the contract for a sorting strategy.
@@ -191,6 +196,12 @@ export interface PaginationPrimitives {
   /** Classic "Previous Page" or "Scroll Up" */
   goPrevious?: (context: TableContext) => Promise<boolean>;
 
+  /** Bulk skip forward multiple pages at once */
+  goNextBulk?: (context: TableContext) => Promise<boolean>;
+
+  /** Bulk skip backward multiple pages at once */
+  goPreviousBulk?: (context: TableContext) => Promise<boolean>;
+
   /** Jump to first page / scroll to top */
   goToFirst?: (context: TableContext) => Promise<boolean>;
 
@@ -313,12 +324,6 @@ export interface TableConfig<T = any> {
   onReset?: (context: TableContext) => Promise<void>;
   /** 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.
@@ -348,24 +353,32 @@ export interface FillOptions {
   inputMappers?: Record<string, (cell: Locator) => Locator>;
 }
 
-/**
- * Options for generateConfigPrompt
- */
-export interface PromptOptions {
+
+
+/** 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;
   /**
-   * Output Strategy:
-   * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).
-   * - 'console': Standard console logs (Default).
+   * Whether to process rows within a page concurrently.
+   * @default false for forEach/filter, true for map
    */
-  output?: 'console' | 'error';
+  parallel?: boolean;
   /**
-   * Include TypeScript type definitions in the prompt
-   * @default true
+   * Deduplication strategy. Use when rows may repeat across iterations
+   * (e.g. infinite scroll tables). Returns a unique key per row.
    */
-  includeTypes?: boolean;
-}
+  dedupe?: DedupeStrategy;
+};
 
-export interface TableResult<T = any> {
+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.
@@ -448,9 +461,62 @@ export interface TableResult<T = any> {
   revalidate: () => Promise<void>;
 
   /**
-   * Scans a specific column across all pages and returns the values.
+   * 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();
+   * });
    */
-  getColumnValues: <V = string>(column: string, options?: { mapper?: (cell: Locator) => Promise<V> | V, maxPages?: number }) => Promise<V[]>;
+  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.
+   *
+   * > **⚠️ UI Interactions:** \`map\` defaults to \`parallel: true\`. If your callback opens popovers,
+   * > fills inputs, or otherwise mutates UI state, pass \`{ parallel: false }\` to avoid concurrent
+   * > interactions interfering with each other.
+   *
+   * @example
+   * // Data extraction — parallel is safe
+   * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
+   *
+   * @example
+   * // UI interactions — must use parallel: false
+   * const assignees = await table.map(async ({ row }) => {
+   *   await row.getCell('Assignee').locator('button').click();
+   *   const name = await page.locator('.popover .name').innerText();
+   *   await page.keyboard.press('Escape');
+   *   return name;
+   * }, { parallel: false });
+   */
+  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>>;
 
   /**
    * Provides access to sorting actions and assertions.
@@ -470,51 +536,11 @@ export interface TableResult<T = any> {
     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: SmartRowArray;
-      allData: T[];
-      table: RestrictedTableResult;
-      batchInfo?: {
-        startIndex: number;
-        endIndex: number;
-        size: number;
-      };
-
-    }) => T | T[] | Promise<T | T[]>,
-    options?: {
-      pagination?: PaginationStrategy;
-      dedupeStrategy?: DedupeStrategy;
-      maxIterations?: number;
-      batchSize?: number;
-      getIsFirst?: (context: { index: number }) => boolean;
-      getIsLast?: (context: { index: number, paginationResult: boolean }) => boolean;
-      beforeFirst?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;
-      afterLast?: (context: { index: number, rows: SmartRowArray, allData: any[] }) => void | Promise<void>;
-      /**
-       * If true, flattens array results from callback into the main data array.
-       * If false (default), pushes the return value as-is (preserves batching/arrays).
-       */
-      autoFlatten?: boolean;
-    }
-  ) => Promise<T[]>;
-
   /**
    * Generate an AI-friendly configuration prompt for debugging.
    * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
+   * Automatically throws an Error containing the prompt.
    */
-  generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
+  generateConfigPrompt: () => Promise<void>;
 }
-
-/**
- * Restricted table result that excludes methods that shouldn't be called during iteration.
- */
-export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;
 `;

package/dist/types.d.ts

@@ -114,6 +114,8 @@ export type SmartRow<T = any> = Locator & {
 export type StrategyContext = TableContext & {
     rowLocator?: Locator;
     rowIndex?: number;
+    /** Helper to reliably get a header cell locator by name */
+    getHeaderCell?: (headerName: string) => Promise<Locator>;
 };
 /**
  * Defines the contract for a sorting strategy.
@@ -170,6 +172,10 @@ export interface PaginationPrimitives {
     goNext?: (context: TableContext) => Promise<boolean>;
     /** Classic "Previous Page" or "Scroll Up" */
     goPrevious?: (context: TableContext) => Promise<boolean>;
+    /** Bulk skip forward multiple pages at once */
+    goNextBulk?: (context: TableContext) => Promise<boolean>;
+    /** Bulk skip backward multiple pages at once */
+    goPreviousBulk?: (context: TableContext) => Promise<boolean>;
     /** Jump to first page / scroll to top */
     goToFirst?: (context: TableContext) => Promise<boolean>;
     /** Jump to specific page index (0-indexed) */
@@ -293,12 +299,6 @@ export interface TableConfig<T = any> {
     onReset?: (context: TableContext) => Promise<void>;
     /** 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.
@@ -328,23 +328,31 @@ export interface FillOptions {
      */
     inputMappers?: Record<string, (cell: Locator) => Locator>;
 }
-/**
- * Options for generateConfigPrompt
- */
-export interface PromptOptions {
+/** 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;
     /**
-     * Output Strategy:
-     * - 'error': Throws an error with the prompt (useful for platforms that capture error output cleanly).
-     * - 'console': Standard console logs (Default).
+     * Whether to process rows within a page concurrently.
+     * @default false for forEach/filter, true for map
      */
-    output?: 'console' | 'error';
+    parallel?: boolean;
     /**
-     * Include TypeScript type definitions in the prompt
-     * @default true
+     * Deduplication strategy. Use when rows may repeat across iterations
+     * (e.g. infinite scroll tables). Returns a unique key per row.
      */
-    includeTypes?: boolean;
-}
-export interface TableResult<T = any> {
+    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.
@@ -414,12 +422,51 @@ export interface TableResult<T = any> {
      */
     revalidate: () => Promise<void>;
     /**
-     * Scans a specific column across all pages and returns the values.
+     * 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();
+     * });
      */
-    getColumnValues: <V = string>(column: string, options?: {
-        mapper?: (cell: Locator) => Promise<V> | V;
-        maxPages?: number;
-    }) => Promise<V[]>;
+    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.
+     *
+     * > **⚠️ UI Interactions:** `map` defaults to `parallel: true`. If your callback opens popovers,
+     * > fills inputs, or otherwise mutates UI state, pass `{ parallel: false }` to avoid concurrent
+     * > interactions interfering with each other.
+     *
+     * @example
+     * // Data extraction — parallel is safe
+     * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
+     *
+     * @example
+     * // UI interactions — must use parallel: false
+     * const assignees = await table.map(async ({ row }) => {
+     *   await row.getCell('Assignee').locator('button').click();
+     *   const name = await page.locator('.popover .name').innerText();
+     *   await page.keyboard.press('Escape');
+     *   return name;
+     * }, { parallel: false });
+     */
+    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>>;
     /**
      * Provides access to sorting actions and assertions.
      */
@@ -437,57 +484,10 @@ export interface TableResult<T = any> {
          */
         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: SmartRowArray;
-        allData: T[];
-        table: RestrictedTableResult;
-        batchInfo?: {
-            startIndex: number;
-            endIndex: number;
-            size: number;
-        };
-    }) => T | T[] | Promise<T | T[]>, options?: {
-        pagination?: PaginationStrategy;
-        dedupeStrategy?: DedupeStrategy;
-        maxIterations?: number;
-        batchSize?: number;
-        getIsFirst?: (context: {
-            index: number;
-        }) => boolean;
-        getIsLast?: (context: {
-            index: number;
-            paginationResult: boolean;
-        }) => boolean;
-        beforeFirst?: (context: {
-            index: number;
-            rows: SmartRowArray;
-            allData: any[];
-        }) => void | Promise<void>;
-        afterLast?: (context: {
-            index: number;
-            rows: SmartRowArray;
-            allData: any[];
-        }) => void | Promise<void>;
-        /**
-         * If true, flattens array results from callback into the main data array.
-         * If false (default), pushes the return value as-is (preserves batching/arrays).
-         */
-        autoFlatten?: boolean;
-    }) => Promise<T[]>;
     /**
      * Generate an AI-friendly configuration prompt for debugging.
      * Outputs table HTML and TypeScript definitions to help AI assistants generate config.
+     * Automatically throws an Error containing the prompt.
      */
-    generateConfigPrompt: (options?: PromptOptions) => Promise<void>;
+    generateConfigPrompt: () => Promise<void>;
 }
-/**
- * Restricted table result that excludes methods that shouldn't be called during iteration.
- */
-export type RestrictedTableResult<T = any> = Omit<TableResult<T>, 'searchForRow' | 'iterateThroughTable' | 'reset'>;