graceful-playwright 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) [2024], [Beeno Tung (Tung Cheung Leong)]
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,58 @@
+# graceful-playwright
+
+Gracefully handle timeout and network error with auto retry.
+
+[![npm Package Version](https://img.shields.io/npm/v/graceful-playwright)](https://www.npmjs.com/package/graceful-playwright)
+
+## Features
+
+- auto retry when `page.goto()` timeout or encountered `/ERR_NETWORK_CHANGED/i`
+
+- auto restart page when `page.goto()` crashed with `/page crashed/i` error
+
+- support restarting page from `Browser` or `BrowserContext` instance
+
+- support wrapping existing `Page` instance
+
+- proxy frequently used methods
+
+- create `Page` instance lazily (on-demand)
+
+## Installation
+
+```bash
+npm install graceful-playwright
+```
+
+You can install the package with yarn, pnpm or slnpm as well.
+
+## Usage Example
+
+More usage examples see: [example.ts](./example.ts) and [core.spec.ts](./core.spec.ts)
+
+```typescript
+import { GracefulPage } from 'graceful-playwright'
+
+let browser = await chromium.launch()
+let page = new GracefulPage({ from: browser })
+
+await page.goto('http://example.net')
+let lines: string[] = await page.evaluate(() =>
+  Array.from(document.querySelectorAll('a'), a => a.href),
+)
+console.log('lines:', lines)
+
+await page.close()
+await browser.close()
+```
+
+## License
+
+This project is licensed with [BSD-2-Clause](./LICENSE)
+
+This is free, libre, and open-source software. It comes down to four essential freedoms [[ref]](https://seirdy.one/2021/01/27/whatsapp-and-the-domestication-of-users.html#fnref:2):
+
+- The freedom to run the program as you wish, for any purpose
+- The freedom to study how the program works, and change it so it does your computing as you wish
+- The freedom to redistribute copies so you can help others
+- The freedom to distribute copies of your modified versions to others

package/core.d.ts

@@ -0,0 +1,53 @@
+import { Browser, BrowserContext, Page } from 'playwright';
+export declare class GracefulPage {
+    options: {
+        from: Browser | BrowserContext;
+        page?: Page | Promise<Page>;
+        /**
+         * @default 5000 ms
+         */
+        retryInterval?: number;
+        /**
+         * @default error => console.error(error)
+         */
+        onError?: (error: unknown) => void;
+    };
+    constructor(options: {
+        from: Browser | BrowserContext;
+        page?: Page | Promise<Page>;
+        /**
+         * @default 5000 ms
+         */
+        retryInterval?: number;
+        /**
+         * @default error => console.error(error)
+         */
+        onError?: (error: unknown) => void;
+    });
+    fork(): GracefulPage;
+    getRetryInterval(): number;
+    getOnError(): (error: unknown) => void;
+    getPage(): Page | Promise<Page>;
+    restart(options?: Parameters<Page['close']>[0]): Promise<Page>;
+    goto(url: string, 
+    /**
+     * @default { waitUtil: "domcontentloaded" }
+     */
+    options?: Parameters<Page['goto']>[1]): Promise<import("playwright").Response | null>;
+    /** @description proxy method to (await this.getPage()).evaluate */
+    evaluate: Page['evaluate'];
+    /** @description proxy method to (await this.getPage()).fill */
+    fill: Page['fill'];
+    /** @description proxy method to (await this.getPage()).click */
+    click: Page['click'];
+    /** @description proxy method to (await this.getPage()).content */
+    content: Page['content'];
+    /** @description proxy method to (await this.getPage()).title */
+    title: Page['title'];
+    /** @description proxy method to (await this.getPage()).innerHTML */
+    innerHTML: Page['innerHTML'];
+    /** @description proxy method to (await this.getPage()).innerText */
+    innerText: Page['innerText'];
+    /** @description proxy method to (await this.getPage()).click */
+    close: Page['close'];
+}

package/core.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GracefulPage = void 0;
+class GracefulPage {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    fork() {
+        let { page, ...options } = this.options;
+        return new GracefulPage(options);
+    }
+    getRetryInterval() {
+        return this.options.retryInterval || 5000;
+    }
+    getOnError() {
+        return this.options.onError || ((error) => console.error(error));
+    }
+    getPage() {
+        this.options.page ||= this.options.from.newPage();
+        return this.options.page;
+    }
+    async restart(options) {
+        await this.close(options);
+        return this.getPage();
+    }
+    async goto(url, 
+    /**
+     * @default { waitUtil: "domcontentloaded" }
+     */
+    options) {
+        for (;;) {
+            let page = await this.getPage();
+            try {
+                let response = await page.goto(url, {
+                    waitUntil: 'domcontentloaded',
+                    ...options,
+                });
+                return response;
+            }
+            catch (error) {
+                let message = String(error);
+                let flags = {
+                    retry: message.match(/timeout/i) || message.match(/ERR_NETWORK_CHANGED/i),
+                    restart: message.match(/page crashed/i),
+                };
+                if (flags.retry || flags.restart) {
+                    if (flags.restart) {
+                        await this.restart();
+                    }
+                    await sleep(this.getRetryInterval());
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    /** @description proxy method to (await this.getPage()).evaluate */
+    evaluate = async (pageFunction, arg) => {
+        let page = await this.getPage();
+        return await page.evaluate(pageFunction, arg);
+    };
+    /** @description proxy method to (await this.getPage()).fill */
+    fill = async (selector, value, options) => {
+        let page = await this.getPage();
+        return await page.fill(selector, value, options);
+    };
+    /** @description proxy method to (await this.getPage()).click */
+    click = async (selector, options) => {
+        let page = await this.getPage();
+        return await page.click(selector, options);
+    };
+    /** @description proxy method to (await this.getPage()).content */
+    content = async () => {
+        let page = await this.getPage();
+        return await page.content();
+    };
+    /** @description proxy method to (await this.getPage()).title */
+    title = async () => {
+        let page = await this.getPage();
+        return await page.title();
+    };
+    /** @description proxy method to (await this.getPage()).innerHTML */
+    innerHTML = async (selector, options) => {
+        let page = await this.getPage();
+        return await page.innerHTML(selector, options);
+    };
+    /** @description proxy method to (await this.getPage()).innerText */
+    innerText = async (selector, options) => {
+        let page = await this.getPage();
+        return await page.innerText(selector, options);
+    };
+    /** @description proxy method to (await this.getPage()).click */
+    close = async (options) => {
+        let promise = Promise.resolve(this.options.page)
+            .then(page => page?.close(options))
+            .catch(this.getOnError());
+        this.options.page = undefined;
+        return promise;
+    };
+}
+exports.GracefulPage = GracefulPage;
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}

package/package.json

@@ -1,17 +1,65 @@
 {
   "name": "graceful-playwright",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
+  "version": "1.0.0",
+  "description": "Gracefully handle timeout and network error with auto retry.",
+  "keywords": [
+    "graceful",
+    "retry",
+    "retries",
+    "error",
+    "errors",
+    "handling",
+    "timeout",
+    "ERR_NETWORK_CHANGED",
+    "page",
+    "crashed",
+    "goto",
+    "playwright",
+    "browser",
+    "automation",
+    "scrapping",
+    "crawling",
+    "crawler",
+    "typescript"
+  ],
+  "author": "Beeno Tung <aabbcc1241@yahoo.com.hk> (https://beeno-tung.surge.sh)",
+  "license": "BSD-2-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beenotung/graceful-playwright.git"
+  },
+  "homepage": "https://github.com/beenotung/graceful-playwright#readme",
+  "bugs": {
+    "url": "https://github.com/beenotung/graceful-playwright/issues"
+  },
+  "main": "core.js",
+  "types": "core.d.ts",
+  "files": [
+    "core.js",
+    "core.d.ts"
+  ],
   "scripts": {
-    "test": "tsc --noEmit",
-    "build": "tsc -p ."
+    "clean": "rimraf *.js *.d.ts",
+    "test": "run-p build mocha",
+    "build": "run-s clean tsc",
+    "tsc": "tsc -p .",
+    "mocha": "ts-mocha core.spec.ts"
+  },
+  "peerDependencies": {
+    "playwright": "^1.41.2"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
   "devDependencies": {
+    "@types/chai": "4",
+    "@types/express": "^4.17.21",
+    "@types/mocha": "^10.0.6",
     "@types/node": "^20.11.17",
+    "chai": "4",
+    "express": "^4.18.2",
+    "mocha": "^10.3.0",
+    "npm-run-all": "^4.1.5",
+    "playwright": "^1.41.2",
+    "rimraf": "^5.0.5",
+    "ts-mocha": "^10.0.0",
     "ts-node": "^10.9.2",
     "ts-node-dev": "^2.0.0",
     "typescript": "^5.3.3"

package/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "es2022",
-    "module": "commonjs",
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "skipLibCheck": true,
-    "incremental": true,
-    "outDir": "dist"
-  },
-  "exclude": [
-    "dist"
-  ]
-}