@rickcedwhat/playwright-smart-table 6.7.8 → 6.8.0

package/dist/types.d.ts

@@ -329,6 +329,11 @@ export interface TableConfig<T = any> {
     cellSelector?: string | ((row: Locator) => Locator);
     /** Number of pages to scan for verification */
     maxPages?: number;
+    /**
+     * Default concurrency strategy for iteration methods.
+     * Can be overridden by the options passed to forEach, map, or filter.
+     */
+    concurrency?: RowIterationMode;
     /** Hook to rename columns dynamically */
     headerTransformer?: (args: {
         text: string;
@@ -356,6 +361,7 @@ export interface FinalTableConfig<T = any> extends TableConfig<T> {
     cellSelector: string | ((row: Locator) => Locator);
     maxPages: number;
     autoScroll: boolean;
+    concurrency?: RowIterationMode;
     debug?: TableConfig['debug'];
     headerTransformer: (args: {
         text: string;
@@ -379,15 +385,26 @@ export type RowIterationContext<T = any> = {
     rowIndex: number;
     stop: () => void;
 };
+/** Concurrency modes for row iteration. */
+export type RowIterationMode = 'parallel' | 'sequential' | 'synchronized';
 /** 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
+     * @deprecated Use 'concurrency' mode instead.
+     * - parallel: true -> concurrency: 'parallel'
+     * - parallel: false -> concurrency: 'sequential'
      */
     parallel?: boolean;
+    /**
+     * Concurrency strategy for iteration.
+     * - 'parallel': Full parallel execution of both navigation and actions.
+     * - 'synchronized': Parallel navigation (lock-step) with serial actions.
+     * - 'sequential': Strictly serial one-at-a-time execution. No parallel navigation.
+     * @default 'parallel' (for map), 'sequential' (for forEach/filter)
+     */
+    concurrency?: RowIterationMode;
     /**
      * Deduplication strategy. Use when rows may repeat across iterations
      * (e.g. infinite scroll tables). Returns a unique key per row.
@@ -475,6 +492,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * Execution is sequential by default (safe for interactions like clicking/filling).
      * Call `stop()` in the callback to end iteration early.
      *
+     * @param callback - Function receiving { row, rowIndex, stop }
+     * @param options - maxPages, concurrency, dedupe, useBulkPagination (`parallel` is deprecated; use `concurrency`)
+     *
      * @example
      * await table.forEach(async ({ row, stop }) => {
      *   if (await row.getCell('Status').innerText() === 'Done') stop();
@@ -487,22 +507,25 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * 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.
+     * > **⚠️ UI Interactions:** `map` defaults to `concurrency: 'parallel'`. If your callback opens popovers,
+     * > fills inputs, or otherwise mutates UI state, pass `concurrency: 'sequential'` (or `'synchronized'`
+     * > when navigation must stay lock-step) to avoid overlapping interactions.
+     *
+     * @param callback - Function receiving { row, rowIndex, stop }
+     * @param options - maxPages, concurrency, dedupe, useBulkPagination (`parallel` is deprecated; use `concurrency`)
      *
      * @example
      * // Data extraction — parallel is safe
      * const emails = await table.map(({ row }) => row.getCell('Email').innerText());
      *
      * @example
-     * // UI interactions — must use parallel: false
+     * // UI interactions — use sequential (or synchronized) concurrency
      * 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 });
+     * }, { concurrency: 'sequential' });
      */
     map<R>(callback: (ctx: RowIterationContext<T>) => R | Promise<R>, options?: RowIterationOptions): Promise<R[]>;
     /**
@@ -510,6 +533,9 @@ export interface TableResult<T = any> extends AsyncIterable<{
      * Rows are returned as-is — call `bringIntoView()` on each if needed.
      * Execution is sequential by default.
      *
+     * @param predicate - Function receiving { row, rowIndex, stop }
+     * @param options - maxPages, concurrency, dedupe, useBulkPagination (`parallel` is deprecated; use `concurrency`)
+     *
      * @example
      * const active = await table.filter(async ({ row }) =>
      *   await row.getCell('Status').innerText() === 'Active'

package/dist/useTable.js

@@ -39,6 +39,7 @@ const tableIteration_1 = require("./engine/tableIteration");
 const debugUtils_1 = require("./utils/debugUtils");
 const smartRowArray_1 = require("./utils/smartRowArray");
 const elementTracker_1 = require("./utils/elementTracker");
+const navigationBarrier_1 = require("./utils/navigationBarrier");
 /**
  * Main hook to interact with a table.
  */
@@ -94,8 +95,8 @@ const useTable = (rootLocator, configOptions = {}) => {
     // Placeholder for the final table object
     let finalTable = null;
     // Helper factory
-    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex) => {
-        return (0, smartRow_1.default)(rowLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex);
+    const _makeSmart = (rowLocator, map, rowIndex, tablePageIndex, barrier) => {
+        return (0, smartRow_1.default)(rowLocator, map, rowIndex, config, rootLocator, resolve, finalTable, tablePageIndex, barrier);
     };
     const tableState = { currentPageIndex: 0 };
     const rowFinder = new rowFinder_1.RowFinder(rootLocator, config, resolve, filterEngine, tableMapper, _makeSmart, tableState);
@@ -299,8 +300,9 @@ const useTable = (rootLocator, configOptions = {}) => {
                         const rowLocators = resolve(config.rowSelector, rootLocator);
                         const newIndices = yield __await(tracker.getUnseenIndices(rowLocators));
                         const pageRows = yield __await(rowLocators.all());
+                        const barrier = new navigationBarrier_1.NavigationBarrier(newIndices.length);
                         for (const idx of newIndices) {
-                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex), rowIndex });
+                            yield yield __await({ row: _makeSmart(pageRows[idx], map, rowIndex, pagesScanned - 1, barrier), rowIndex });
                             rowIndex++;
                         }
                         if (pagesScanned >= effectiveMaxPages)
@@ -322,7 +324,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 getRowLocators: () => resolve(config.rowSelector, rootLocator),
                 getMap: () => tableMapper.getMapSync(),
                 advancePage: _advancePage,
-                makeSmartRow: (loc, map, idx, pageIdx) => _makeSmart(loc, map, idx, pageIdx),
+                makeSmartRow: (loc, map, idx, pageIdx, barrier) => _makeSmart(loc, map, idx, pageIdx, barrier),
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
@@ -334,7 +336,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 getRowLocators: () => resolve(config.rowSelector, rootLocator),
                 getMap: () => tableMapper.getMapSync(),
                 advancePage: _advancePage,
-                makeSmartRow: (loc, map, idx, pageIdx) => _makeSmart(loc, map, idx, pageIdx),
+                makeSmartRow: (loc, map, idx, pageIdx, barrier) => _makeSmart(loc, map, idx, pageIdx, barrier),
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),
@@ -346,7 +348,7 @@ const useTable = (rootLocator, configOptions = {}) => {
                 getRowLocators: () => resolve(config.rowSelector, rootLocator),
                 getMap: () => tableMapper.getMapSync(),
                 advancePage: _advancePage,
-                makeSmartRow: (loc, map, idx, pageIdx) => _makeSmart(loc, map, idx, pageIdx),
+                makeSmartRow: (loc, map, idx, pageIdx, barrier) => _makeSmart(loc, map, idx, pageIdx, barrier),
                 createSmartRowArray: smartRowArray_1.createSmartRowArray,
                 config,
                 getPage: () => rootLocator.page(),

package/dist/utils/mutex.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A simple async mutex to handle sequential execution within
+ * a parallel batch.
+ */
+export declare class Mutex {
+    private queue;
+    run<T>(action: () => T | Promise<T>): Promise<T>;
+}

package/dist/utils/mutex.js

@@ -0,0 +1,31 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Mutex = void 0;
+/**
+ * A simple async mutex to handle sequential execution within
+ * a parallel batch.
+ */
+class Mutex {
+    constructor() {
+        this.queue = Promise.resolve();
+    }
+    run(action) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const next = this.queue.then(() => __awaiter(this, void 0, void 0, function* () {
+                return yield action();
+            }));
+            this.queue = next.catch(() => { }); // prevent chain breakage
+            return yield next;
+        });
+    }
+}
+exports.Mutex = Mutex;

package/dist/utils/navigationBarrier.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A synchronization barrier that allows multiple parallel row processors
+ * to coordinate their navigation actions.
+ */
+export declare class NavigationBarrier {
+    private total;
+    private finishedCount;
+    private buckets;
+    constructor(total: number);
+    /**
+     * Synchronize all active rows at a specific column index.
+     * The last row to arrive will trigger the `moveAction`.
+     */
+    sync<T = void>(colIndex: number, moveAction?: () => Promise<T>): Promise<T | void>;
+    /**
+     * Mark a row as finished (no more cells to process).
+     * This ensures the barrier doesn't wait for rows that have exited the loop.
+     */
+    markFinished(): void;
+    private broadcast;
+}

package/dist/utils/navigationBarrier.js

@@ -0,0 +1,82 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NavigationBarrier = void 0;
+/**
+ * A synchronization barrier that allows multiple parallel row processors
+ * to coordinate their navigation actions.
+ */
+class NavigationBarrier {
+    constructor(total) {
+        this.finishedCount = 0;
+        // Map of colIndex -> Set of waiting resolvers
+        this.buckets = new Map();
+        this.total = total;
+    }
+    /**
+     * Synchronize all active rows at a specific column index.
+     * The last row to arrive will trigger the `moveAction`.
+     */
+    sync(colIndex, moveAction) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (this.total <= 1) {
+                if (moveAction)
+                    return yield moveAction();
+                return;
+            }
+            return new Promise((resolve) => {
+                let bucket = this.buckets.get(colIndex);
+                if (!bucket) {
+                    bucket = new Set();
+                    this.buckets.set(colIndex, bucket);
+                }
+                bucket.add(resolve);
+                if (bucket.size + this.finishedCount >= this.total) {
+                    // Use a self-executing async function to handle the moveAction synchronously in this context
+                    (() => __awaiter(this, void 0, void 0, function* () {
+                        let result;
+                        try {
+                            if (moveAction)
+                                result = yield moveAction();
+                        }
+                        finally {
+                            this.broadcast(colIndex, result);
+                        }
+                    }))();
+                }
+            });
+        });
+    }
+    /**
+     * Mark a row as finished (no more cells to process).
+     * This ensures the barrier doesn't wait for rows that have exited the loop.
+     */
+    markFinished() {
+        this.finishedCount++;
+        // Check all buckets - any bucket that was waiting for this row might now be ready
+        for (const colIndex of Array.from(this.buckets.keys())) {
+            const bucket = this.buckets.get(colIndex);
+            if (bucket.size + this.finishedCount >= this.total) {
+                this.broadcast(colIndex);
+            }
+        }
+    }
+    broadcast(colIndex, result) {
+        const bucket = this.buckets.get(colIndex);
+        if (bucket) {
+            for (const resolve of bucket) {
+                resolve(result);
+            }
+            this.buckets.delete(colIndex);
+        }
+    }
+}
+exports.NavigationBarrier = NavigationBarrier;

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "6.7.8",
+  "version": "6.8.0",
   "description": "Smart, column-aware table interactions for Playwright",
   "author": "Cedrick Catalan",
   "license": "MIT",
+  "homepage": "https://rickcedwhat.github.io/playwright-smart-table/",
   "repository": {
     "type": "git",
     "url": "https://github.com/rickcedwhat/playwright-smart-table.git"
   },
+  "bugs": {
+    "url": "https://github.com/rickcedwhat/playwright-smart-table/issues"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -55,7 +59,15 @@
     "playwright",
     "testing",
     "table",
-    "automation"
+    "automation",
+    "locators",
+    "e2e",
+    "qa",
+    "typescript",
+    "datagrid",
+    "smart-table",
+    "ag-grid",
+    "mui"
   ],
   "peerDependencies": {
     "@playwright/test": "^1.40.0"