@rickcedwhat/playwright-smart-table 4.0.0 → 5.1.0

package/dist/useTable.js

@@ -9,7 +9,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Strategies = exports.ResolutionStrategies = exports.ColumnStrategies = exports.CellNavigationStrategies = exports.HeaderStrategies = exports.FillStrategies = exports.SortingStrategies = exports.DeprecatedTableStrategies = exports.PaginationStrategies = exports.useTable = void 0;
+exports.Strategies = exports.ResolutionStrategies = exports.CellNavigationStrategies = exports.HeaderStrategies = exports.FillStrategies = exports.SortingStrategies = exports.PaginationStrategies = exports.useTable = void 0;
 const typeContext_1 = require("./typeContext");
 const sorting_1 = require("./strategies/sorting");
 const pagination_1 = require("./strategies/pagination");
@@ -19,13 +19,14 @@ const headers_1 = require("./strategies/headers");
 Object.defineProperty(exports, "HeaderStrategies", { enumerable: true, get: function () { return headers_1.HeaderStrategies; } });
 const columns_1 = require("./strategies/columns");
 Object.defineProperty(exports, "CellNavigationStrategies", { enumerable: true, get: function () { return columns_1.CellNavigationStrategies; } });
-Object.defineProperty(exports, "ColumnStrategies", { enumerable: true, get: function () { return columns_1.ColumnStrategies; } });
 const smartRow_1 = require("./smartRow");
 const filterEngine_1 = require("./filterEngine");
 const resolution_1 = require("./strategies/resolution");
 Object.defineProperty(exports, "ResolutionStrategies", { enumerable: true, get: function () { return resolution_1.ResolutionStrategies; } });
 const strategies_1 = require("./strategies");
 Object.defineProperty(exports, "Strategies", { enumerable: true, get: function () { return strategies_1.Strategies; } });
+const validation_1 = require("./strategies/validation");
+const traceUtils_1 = require("./utils/traceUtils");
 /**
  * Main hook to interact with a table.
  */
@@ -40,7 +41,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         cellNavigation: columns_1.CellNavigationStrategies.default,
         pagination: () => __awaiter(void 0, void 0, void 0, function* () { return false; }),
     };
-    const config = Object.assign(Object.assign({ rowSelector: "tbody tr", headerSelector: "th", cellSelector: "td", maxPages: 1, headerTransformer: ({ text, index, locator }) => text, autoScroll: true, debug: false, onReset: () => __awaiter(void 0, void 0, void 0, function* () { }) }, configOptions), { strategies: Object.assign(Object.assign({}, defaultStrategies), configOptions.strategies) });
+    const config = Object.assign(Object.assign({ rowSelector: "tbody tr", headerSelector: "thead th", cellSelector: "td", maxPages: 1, headerTransformer: ({ text, index, locator }) => text, autoScroll: true, debug: false, onReset: () => __awaiter(void 0, void 0, void 0, function* () { }) }, configOptions), { strategies: Object.assign(Object.assign({}, defaultStrategies), configOptions.strategies) });
     const resolve = (item, parent) => {
         if (typeof item === 'string')
             return parent.locator(item);
@@ -162,7 +163,8 @@ const useTable = (rootLocator, configOptions = {}) => {
                     page: rootLocator.page(),
                     resolve: resolve
                 };
-                const didLoadMore = yield config.strategies.pagination(context);
+                const paginationResult = yield config.strategies.pagination(context);
+                const didLoadMore = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
                 if (didLoadMore) {
                     _hasPaginated = true;
                     currentPage++;
@@ -224,6 +226,9 @@ const useTable = (rootLocator, configOptions = {}) => {
                 return result;
             yield _getMap(options === null || options === void 0 ? void 0 : options.timeout);
             _isInitialized = true;
+            if (_headerMap) {
+                yield (0, traceUtils_1.addTraceEvent)(rootLocator.page(), 'init', { headers: Array.from(_headerMap.keys()), columnCount: _headerMap.size });
+            }
             return result;
         }),
         scrollToColumn: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
@@ -242,7 +247,7 @@ const useTable = (rootLocator, configOptions = {}) => {
         }),
         getHeaders: () => __awaiter(void 0, void 0, void 0, function* () {
             if (!_isInitialized || !_headerMap)
-                throw new Error('Table not initialized. Call await table.init() first.');
+                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.getRows() which auto-initialize.');
             return Array.from(_headerMap.keys());
         }),
         getHeaderCell: (columnName) => __awaiter(void 0, void 0, void 0, function* () {
@@ -299,22 +304,22 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return results;
         }),
-        getByRow: (filters, options = { exact: false }) => {
+        getRow: (filters, options = { exact: false }) => {
             if (!_isInitialized || !_headerMap)
-                throw new Error('Table not initialized. Call await table.init() first.');
+                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.getRows() which auto-initialize.');
             const allRows = resolve(config.rowSelector, rootLocator);
             const matchedRows = filterEngine.applyFilters(allRows, filters, _headerMap, options.exact || false, rootLocator.page());
             const rowLocator = matchedRows.first();
             return _makeSmart(rowLocator, _headerMap, 0); // fallback index 0
         },
-        getByRowIndex: (index, options = {}) => {
+        getRowByIndex: (index, options = {}) => {
             if (!_isInitialized || !_headerMap)
-                throw new Error('Table not initialized. Call await table.init() first.');
+                throw new Error('Table not initialized. Call await table.init() first, or use async methods like table.findRow() or table.getRows() which auto-initialize.');
             const rowIndex = index - 1; // Convert 1-based to 0-based
             const rowLocator = resolve(config.rowSelector, rootLocator).nth(rowIndex);
             return _makeSmart(rowLocator, _headerMap, rowIndex);
         },
-        searchForRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
+        findRow: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
             yield _ensureInitialized();
             let row = yield _findRowLocator(filters, options);
             if (!row) {
@@ -322,7 +327,7 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return _makeSmart(row, _headerMap, 0);
         }),
-        getAllCurrentRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
+        getRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
             yield _ensureInitialized();
             let rowLocators = resolve(config.rowSelector, rootLocator);
             if (options === null || options === void 0 ? void 0 : options.filter) {
@@ -335,22 +340,44 @@ const useTable = (rootLocator, configOptions = {}) => {
             }
             return smartRows;
         }),
-        getAllRows: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            console.warn("⚠️ [SmartTable] getAllRows is deprecated. Use getAllCurrentRows instead.");
-            return result.getAllCurrentRows(options);
-        }),
-        generateConfigPrompt: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            const html = yield _getCleanHtml(rootLocator);
-            const separator = "=".repeat(50);
-            const content = `\n${separator}\n🤖 COPY INTO GEMINI/ChatGPT 🤖\n${separator}\nI am using 'playwright-smart-table'.\nTarget Table Locator: ${rootLocator.toString()}\nGenerate config for:\n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n${separator}\n`;
-            yield _handlePrompt('Smart Table Config', content, options);
-        }),
-        generateStrategyPrompt: (options) => __awaiter(void 0, void 0, void 0, function* () {
-            const container = rootLocator.locator('xpath=..');
-            const html = yield _getCleanHtml(container);
-            const content = `\n==================================================\n🤖 COPY INTO GEMINI/ChatGPT TO WRITE A STRATEGY 🤖\n==================================================\nI need a custom Pagination Strategy for 'playwright-smart-table'.\nContainer HTML:\n\`\`\`html\n${html.substring(0, 10000)} ...\n\`\`\`\n`;
-            yield _handlePrompt('Smart Table Strategy', content, options);
+        findRows: (filters, options) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a, _b, _c, _d;
+            yield _ensureInitialized();
+            const allRows = [];
+            const effectiveMaxPages = (_b = (_a = options === null || options === void 0 ? void 0 : options.maxPages) !== null && _a !== void 0 ? _a : config.maxPages) !== null && _b !== void 0 ? _b : Infinity;
+            let pageCount = 0;
+            // Collect rows from current page
+            let rowLocators = resolve(config.rowSelector, rootLocator);
+            rowLocators = filterEngine.applyFilters(rowLocators, filters, _headerMap, (_c = options === null || options === void 0 ? void 0 : options.exact) !== null && _c !== void 0 ? _c : false, rootLocator.page());
+            let rows = yield rowLocators.all();
+            allRows.push(...rows.map((loc, i) => _makeSmart(loc, _headerMap, i)));
+            // Paginate and collect more rows
+            while (pageCount < effectiveMaxPages && config.strategies.pagination) {
+                const paginationResult = yield config.strategies.pagination({
+                    root: rootLocator,
+                    config,
+                    resolve,
+                    page: rootLocator.page()
+                });
+                const didPaginate = (0, validation_1.validatePaginationResult)(paginationResult, 'Pagination Strategy');
+                if (!didPaginate)
+                    break;
+                pageCount++;
+                _hasPaginated = true;
+                // Collect rows from new page
+                rowLocators = resolve(config.rowSelector, rootLocator);
+                rowLocators = filterEngine.applyFilters(rowLocators, filters, _headerMap, (_d = options === null || options === void 0 ? void 0 : options.exact) !== null && _d !== void 0 ? _d : false, rootLocator.page());
+                rows = yield rowLocators.all();
+                allRows.push(...rows.map((loc, i) => _makeSmart(loc, _headerMap, i)));
+            }
+            if (options === null || options === void 0 ? void 0 : options.asJSON) {
+                return Promise.all(allRows.map(r => r.toJSON()));
+            }
+            return allRows;
         }),
+        isInitialized: () => {
+            return _isInitialized;
+        },
         sorting: {
             apply: (columnName, direction) => __awaiter(void 0, void 0, void 0, function* () {
                 yield _ensureInitialized();
@@ -381,12 +408,13 @@ const useTable = (rootLocator, configOptions = {}) => {
                 init: result.init,
                 getHeaders: result.getHeaders,
                 getHeaderCell: result.getHeaderCell,
-                getByRow: result.getByRow,
-                getByRowIndex: result.getByRowIndex,
-                getAllCurrentRows: result.getAllCurrentRows,
+                getRow: result.getRow,
+                getRowByIndex: result.getRowByIndex,
+                findRow: result.findRow,
+                getRows: result.getRows,
+                findRows: result.findRows,
                 getColumnValues: result.getColumnValues,
-                generateConfigPrompt: result.generateConfigPrompt,
-                generateStrategyPrompt: result.generateStrategyPrompt,
+                isInitialized: result.isInitialized,
                 sorting: result.sorting,
                 scrollToColumn: result.scrollToColumn,
                 revalidate: result.revalidate,
@@ -395,10 +423,14 @@ const useTable = (rootLocator, configOptions = {}) => {
             const getIsLast = (_c = options === null || options === void 0 ? void 0 : options.getIsLast) !== null && _c !== void 0 ? _c : (() => false);
             const allData = [];
             const effectiveMaxIterations = (_d = options === null || options === void 0 ? void 0 : options.maxIterations) !== null && _d !== void 0 ? _d : config.maxPages;
+            const batchSize = options === null || options === void 0 ? void 0 : options.batchSize;
+            const isBatching = batchSize !== undefined && batchSize > 1;
             let index = 0;
             let paginationResult = true;
             let seenKeys = null;
-            logDebug(`Starting iterateThroughTable (maxIterations: ${effectiveMaxIterations})`);
+            let batchRows = [];
+            let batchStartIndex = 0;
+            logDebug(`Starting iterateThroughTable (maxIterations: ${effectiveMaxIterations}, batchSize: ${batchSize !== null && batchSize !== void 0 ? batchSize : 'none'})`);
             while (index < effectiveMaxIterations) {
                 const rowLocators = yield resolve(config.rowSelector, rootLocator).all();
                 let rows = rowLocators.map((loc, i) => _makeSmart(loc, _headerMap, i));
@@ -416,21 +448,91 @@ const useTable = (rootLocator, configOptions = {}) => {
                     rows = deduplicated;
                     logDebug(`Deduplicated ${rowLocators.length} rows to ${rows.length} unique rows (total seen: ${seenKeys.size})`);
                 }
-                const isFirst = getIsFirst({ index });
-                let isLast = getIsLast({ index, paginationResult });
-                const isLastDueToMax = index === effectiveMaxIterations - 1;
-                if (isFirst && (options === null || options === void 0 ? void 0 : options.onFirst))
-                    yield options.onFirst({ index, rows, allData });
-                const returnValue = yield callback({ index, isFirst, isLast, rows, allData, table: restrictedTable });
-                allData.push(returnValue);
-                const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
-                paginationResult = yield paginationStrategy(context);
-                isLast = getIsLast({ index, paginationResult }) || isLastDueToMax;
-                if (isLast && (options === null || options === void 0 ? void 0 : options.onLast))
-                    yield options.onLast({ index, rows, allData });
-                if (isLast || !paginationResult) {
-                    logDebug(`Reached last iteration (index: ${index}, paginationResult: ${paginationResult})`);
-                    break;
+                // Add rows to batch if batching is enabled
+                if (isBatching) {
+                    batchRows.push(...rows);
+                }
+                const isLastIteration = index === effectiveMaxIterations - 1;
+                // Determine if we should invoke the callback
+                const batchComplete = isBatching && (index - batchStartIndex + 1) >= batchSize;
+                const shouldInvokeCallback = !isBatching || batchComplete || isLastIteration;
+                if (shouldInvokeCallback) {
+                    const callbackRows = isBatching ? batchRows : rows;
+                    const callbackIndex = isBatching ? batchStartIndex : index;
+                    const isFirst = getIsFirst({ index: callbackIndex });
+                    let isLast = getIsLast({ index: callbackIndex, paginationResult });
+                    const isLastDueToMax = index === effectiveMaxIterations - 1;
+                    if (isFirst && (options === null || options === void 0 ? void 0 : options.beforeFirst)) {
+                        yield options.beforeFirst({ index: callbackIndex, rows: callbackRows, allData });
+                    }
+                    const batchInfo = isBatching ? {
+                        startIndex: batchStartIndex,
+                        endIndex: index,
+                        size: index - batchStartIndex + 1
+                    } : undefined;
+                    const returnValue = yield callback({
+                        index: callbackIndex,
+                        isFirst,
+                        isLast,
+                        rows: callbackRows,
+                        allData,
+                        table: restrictedTable,
+                        batchInfo
+                    });
+                    allData.push(returnValue);
+                    // Determine if this is truly the last iteration
+                    let finalIsLast = isLastDueToMax;
+                    if (!isLastIteration) {
+                        const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
+                        paginationResult = yield paginationStrategy(context);
+                        finalIsLast = getIsLast({ index: callbackIndex, paginationResult }) || !paginationResult;
+                    }
+                    if (finalIsLast && (options === null || options === void 0 ? void 0 : options.afterLast)) {
+                        yield options.afterLast({ index: callbackIndex, rows: callbackRows, allData });
+                    }
+                    if (finalIsLast || !paginationResult) {
+                        logDebug(`Reached last iteration (index: ${index}, paginationResult: ${paginationResult})`);
+                        break;
+                    }
+                    // Reset batch
+                    if (isBatching) {
+                        batchRows = [];
+                        batchStartIndex = index + 1;
+                    }
+                }
+                else {
+                    // Continue paginating even when batching
+                    const context = { root: rootLocator, config, page: rootLocator.page(), resolve };
+                    paginationResult = yield paginationStrategy(context);
+                    if (!paginationResult) {
+                        // Pagination failed, invoke callback with current batch
+                        const callbackIndex = batchStartIndex;
+                        const isFirst = getIsFirst({ index: callbackIndex });
+                        const isLast = true;
+                        if (isFirst && (options === null || options === void 0 ? void 0 : options.beforeFirst)) {
+                            yield options.beforeFirst({ index: callbackIndex, rows: batchRows, allData });
+                        }
+                        const batchInfo = {
+                            startIndex: batchStartIndex,
+                            endIndex: index,
+                            size: index - batchStartIndex + 1
+                        };
+                        const returnValue = yield callback({
+                            index: callbackIndex,
+                            isFirst,
+                            isLast,
+                            rows: batchRows,
+                            allData,
+                            table: restrictedTable,
+                            batchInfo
+                        });
+                        allData.push(returnValue);
+                        if (options === null || options === void 0 ? void 0 : options.afterLast) {
+                            yield options.afterLast({ index: callbackIndex, rows: batchRows, allData });
+                        }
+                        logDebug(`Pagination failed mid-batch (index: ${index})`);
+                        break;
+                    }
                 }
                 index++;
                 logDebug(`Iteration ${index} completed, continuing...`);
@@ -444,6 +546,4 @@ const useTable = (rootLocator, configOptions = {}) => {
 };
 exports.useTable = useTable;
 exports.PaginationStrategies = pagination_1.PaginationStrategies;
-/** @deprecated Use Strategies.Pagination instead */
-exports.DeprecatedTableStrategies = pagination_1.DeprecatedPaginationStrategies;
 exports.SortingStrategies = sorting_1.SortingStrategies;

package/dist/utils/stringUtils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Calculate Levenshtein distance between two strings
+ * Used for "did you mean?" suggestions
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Calculate similarity score between two strings (0-1)
+ * 1 = identical, 0 = completely different
+ */
+export declare function stringSimilarity(a: string, b: string): number;
+/**
+ * Find similar strings from a list
+ * Returns matches above threshold, sorted by similarity
+ */
+export declare function findSimilar(input: string, available: string[], threshold?: number): Array<{
+    value: string;
+    score: number;
+}>;
+/**
+ * Build a helpful error message for column not found
+ */
+export declare function buildColumnNotFoundError(columnName: string, availableColumns: string[]): string;

package/dist/utils/stringUtils.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshteinDistance = levenshteinDistance;
+exports.stringSimilarity = stringSimilarity;
+exports.findSimilar = findSimilar;
+exports.buildColumnNotFoundError = buildColumnNotFoundError;
+/**
+ * Calculate Levenshtein distance between two strings
+ * Used for "did you mean?" suggestions
+ */
+function levenshteinDistance(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                matrix[i][j - 1] + 1, // insertion
+                matrix[i - 1][j] + 1 // deletion
+                );
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+/**
+ * Calculate similarity score between two strings (0-1)
+ * 1 = identical, 0 = completely different
+ */
+function stringSimilarity(a, b) {
+    const distance = levenshteinDistance(a.toLowerCase(), b.toLowerCase());
+    const maxLen = Math.max(a.length, b.length);
+    return maxLen === 0 ? 1 : 1 - (distance / maxLen);
+}
+/**
+ * Find similar strings from a list
+ * Returns matches above threshold, sorted by similarity
+ */
+function findSimilar(input, available, threshold = 0.5) {
+    return available
+        .map(value => ({
+        value,
+        score: stringSimilarity(input, value)
+    }))
+        .filter(x => x.score >= threshold)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 3); // Top 3 suggestions
+}
+/**
+ * Build a helpful error message for column not found
+ */
+function buildColumnNotFoundError(columnName, availableColumns) {
+    const suggestions = findSimilar(columnName, availableColumns);
+    let message = `Column '${columnName}' not found`;
+    if (suggestions.length > 0) {
+        message += `\n\nDid you mean:`;
+        suggestions.forEach(({ value, score }) => {
+            const percentage = Math.round(score * 100);
+            message += `\n  • ${value} (${percentage}% match)`;
+        });
+    }
+    message += `\n\nAvailable columns: ${availableColumns.join(', ')}`;
+    message += `\n\nTip: Column names are case-sensitive`;
+    return message;
+}

package/dist/utils/traceUtils.d.ts

@@ -0,0 +1,11 @@
+import type { Page } from '@playwright/test';
+/**
+ * Add a custom trace event to Playwright's trace viewer
+ * Uses page.evaluate to log events that appear in the trace
+ */
+export declare function addTraceEvent(page: Page, type: string, data?: Record<string, any>): Promise<void>;
+/**
+ * Check if tracing is currently enabled
+ * Used for conditional trace logic
+ */
+export declare function isTracingEnabled(page: Page): Promise<boolean>;

package/dist/utils/traceUtils.js

@@ -0,0 +1,47 @@
+"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.addTraceEvent = addTraceEvent;
+exports.isTracingEnabled = isTracingEnabled;
+/**
+ * Add a custom trace event to Playwright's trace viewer
+ * Uses page.evaluate to log events that appear in the trace
+ */
+function addTraceEvent(page_1, type_1) {
+    return __awaiter(this, arguments, void 0, function* (page, type, data = {}) {
+        try {
+            // Add a console log that will appear in the trace viewer
+            // Prefix with [SmartTable] for easy filtering
+            const message = `[SmartTable:${type}] ${JSON.stringify(data)}`;
+            yield page.evaluate((msg) => console.log(msg), message);
+        }
+        catch (_a) {
+            // Silently ignore if page is not available
+            // This ensures zero overhead when tracing is off
+        }
+    });
+}
+/**
+ * Check if tracing is currently enabled
+ * Used for conditional trace logic
+ */
+function isTracingEnabled(page) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            // We can't directly check if tracing is enabled
+            // But we can safely call addTraceEvent - it will just be a no-op if not tracing
+            return true;
+        }
+        catch (_a) {
+            return false;
+        }
+    });
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rickcedwhat/playwright-smart-table",
-  "version": "4.0.0",
-  "description": "A smart table utility for Playwright with built-in pagination strategies that are fully extensible.",
+  "version": "5.1.0",
+  "description": "Production-ready table testing for Playwright with smart column-aware locators. Core library with plugin support for custom table implementations.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/rickcedwhat/playwright-smart-table.git"