@letsscrapedata/controller 0.0.2 → 0.0.3

package/dist/index.cjs

@@ -667,12 +667,19 @@ var PlaywrightPage = class extends import_node_events.default {
     await this.clearResponseInterceptions();
     return true;
   }
+  #getWaitUntil(origWaitUntil) {
+    if (origWaitUntil === "networkidle0" || origWaitUntil === "networkidle2") {
+      return "networkidle";
+    } else {
+      return origWaitUntil;
+    }
+  }
   async goto(url, options) {
     if (!this.#page) {
       throw new Error("No valid page");
     }
     if (options) {
-      const { referer, timeout, waitUntil } = options;
+      const { referer, timeout, waitUntil = "load" } = options;
       const newOptions = {};
       if (referer) {
         newOptions.referer = referer;
@@ -680,9 +687,7 @@ var PlaywrightPage = class extends import_node_events.default {
       if (timeout) {
         newOptions.timeout = timeout;
       }
-      if (waitUntil && waitUntil !== "commit") {
-        newOptions.waitUntil = waitUntil === "networkidle" ? "networkidle0" : waitUntil;
-      }
+      newOptions.waitUntil = this.#getWaitUntil(waitUntil);
       await this.#page.goto(url, newOptions);
     } else {
       await this.#page.goto(url);
@@ -1015,6 +1020,30 @@ var PlaywrightPage = class extends import_node_events.default {
     this.#status = "busy";
     return true;
   }
+  async waitForElement(selector, options = {}) {
+    if (!this.#page) {
+      throw new Error("No valid page");
+    }
+    const locator = this.#page.locator(selector);
+    const { timeout = 3e4, state = "visible" } = options;
+    await locator.waitFor({ state, timeout });
+    return true;
+  }
+  async waitForNavigation(options) {
+    if (!this.#page) {
+      throw new Error("No valid page");
+    }
+    const { url = "", timeout = 3e4, waitUntil = "load" } = options;
+    const newWaitUntil = this.#getWaitUntil(waitUntil);
+    if (url) {
+      await this.#page.waitForURL(url, { timeout, waitUntil: newWaitUntil });
+    } else if (newWaitUntil === "commit") {
+      throw new Error("commit is not supported in PlaywrightPage.waitForNavigation");
+    } else {
+      await this.#page.waitForLoadState(newWaitUntil, { timeout });
+    }
+    return true;
+  }
   async windowMember(keys) {
     if (!this.#page) {
       throw new Error("No valid page");
@@ -2042,12 +2071,21 @@ var PuppeteerPage = class extends import_node_events4.default {
     await this.clearResponseInterceptions();
     return true;
   }
+  #getWaitUntil(origWaitUntil) {
+    if (origWaitUntil === "networkidle") {
+      return "networkidle0";
+    } else if (origWaitUntil === "commit") {
+      throw new Error("commit is not supported in PuppeteerPage");
+    } else {
+      return origWaitUntil;
+    }
+  }
   async goto(url, options) {
     if (!this.#page) {
       throw new Error("No valid page");
     }
     if (options) {
-      const { referer, timeout, waitUntil } = options;
+      const { referer, timeout, waitUntil = "load" } = options;
       const newOptions = {};
       if (referer) {
         newOptions.referer = referer;
@@ -2056,7 +2094,7 @@ var PuppeteerPage = class extends import_node_events4.default {
         newOptions.timeout = timeout;
       }
       if (waitUntil && waitUntil !== "commit") {
-        newOptions.waitUntil = waitUntil === "networkidle" ? "networkidle0" : waitUntil;
+        newOptions.waitUntil = this.#getWaitUntil(waitUntil);
       }
       await this.#page.goto(url, newOptions);
     } else {
@@ -2370,6 +2408,33 @@ var PuppeteerPage = class extends import_node_events4.default {
     this.#status = "busy";
     return true;
   }
+  async waitForElement(selector, options = {}) {
+    if (!this.#page) {
+      throw new Error("No valid page");
+    }
+    const { timeout = 3e4, state = "visible" } = options;
+    if (state === "visible") {
+      await this.#page.waitForSelector(selector, { timeout, visible: true });
+    } else if (state === "hidden") {
+      await this.#page.waitForSelector(selector, { timeout, hidden: true });
+    } else {
+      throw new Error(`${state} is not supported in PuppeteerPage.waitForElement`);
+    }
+    return true;
+  }
+  async waitForNavigation(options) {
+    if (!this.#page) {
+      throw new Error("No valid page");
+    }
+    const { url = "", timeout = 3e4, waitUntil = "load" } = options;
+    const newWaitUntil = this.#getWaitUntil(waitUntil);
+    if (url) {
+      throw new Error("url is not supported in PuppeteerPage.waitForNavigation");
+    } else {
+      await this.#page.waitForNavigation({ timeout, waitUntil: newWaitUntil });
+    }
+    return true;
+  }
   async windowMember(keys) {
     if (!this.#page) {
       throw new Error("No valid page");
@@ -16946,6 +17011,12 @@ var CheerioPage = class extends import_node_events7.default {
   use() {
     throw new Error("Not supported in CheerioPage.");
   }
+  waitForElement() {
+    throw new Error("Not supported in CheerioPage.");
+  }
+  waitForNavigation() {
+    throw new Error("Not supported in CheerioPage.");
+  }
   async windowMember() {
     throw new Error("Not supported in CheerioPage.");
   }

package/dist/index.d.cts

@@ -243,14 +243,15 @@ interface SelectOptions {
      */
     labels?: string[];
 }
+/**
+ * * playwright: "load" | "domcontentloaded" | "networkidle" | "commit", "networkidle0" | "networkidle2" => "networkidle";
+ * * puppeteer: "load" | "domcontentloaded" | "networkidle0" | "networkidle2", "networkidle" => "networkidle0", "commit" ignored;
+ */
+type NavigationWaitUntil = "load" | "domcontentloaded" | "networkidle" | "commit" | "networkidle0" | "networkidle2";
 interface GotoOptions {
     referer?: string;
     timeout?: number;
-    /**
-     * playwright: "load" | "domcontentloaded" | "networkidle" | "commit", "networkidle0" | "networkidle2" => "networkidle";
-     * puppeteer: "load" | "domcontentloaded" | "networkidle0" | "networkidle2", "networkidle" => "networkidle0", "commit" ignored;
-     */
-    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit" | "networkidle0" | "networkidle2";
+    waitUntil?: NavigationWaitUntil;
 }
 /**
  * * src takes precedence over selector, at least one of them must be defined
@@ -684,6 +685,31 @@ interface ScreenshotOptions {
      */
     type?: 'png' | 'jpeg';
 }
+interface WaitElementOptions {
+    /**
+     * @default 30_000 ms
+     */
+    timeout?: number;
+    /**
+     * @default "visible"
+     */
+    state?: "attached" | "detached" | "hidden" | "visible";
+}
+interface WaitNavigationOptions {
+    /**
+     * only supported in playwright by now
+     * @default ""
+     */
+    url?: string | RegExp;
+    /**
+     * @default 30_000 ms
+     */
+    timeout?: number;
+    /**
+     * @default "visible"
+     */
+    waitUntil?: NavigationWaitUntil;
+}
 interface LsdPage extends EventEmitter {
     bringToFront(): Promise<boolean>;
     browserContext(): LsdBrowserContext;
@@ -778,6 +804,17 @@ interface LsdPage extends EventEmitter {
      * 开始使用该page(当前状态必须为free)
      */
     use(): boolean;
+    /**
+     *
+     * @param selector CSS selector, not XPath
+     * @param options
+     */
+    waitForElement(selector: string, options?: WaitElementOptions): Promise<boolean>;
+    /**
+     *
+     * @param options
+     */
+    waitForNavigation(options: WaitNavigationOptions): Promise<boolean>;
     /**
      * obj=window?.[key1]...?.[keyn]
      * @return obj ? JSON.stringify(obj) : ""
@@ -937,6 +974,8 @@ declare class PlaywrightPage extends EventEmitter implements LsdPage {
     title(): Promise<string>;
     url(): string;
     use(): boolean;
+    waitForElement(selector: string, options?: WaitElementOptions): Promise<boolean>;
+    waitForNavigation(options: WaitNavigationOptions): Promise<boolean>;
     windowMember(keys: string[]): Promise<string>;
 }
 
@@ -1041,6 +1080,8 @@ declare class PuppeteerPage extends EventEmitter implements LsdPage {
     title(): Promise<string>;
     url(): string;
     use(): boolean;
+    waitForElement(selector: string, options?: WaitElementOptions): Promise<boolean>;
+    waitForNavigation(options: WaitNavigationOptions): Promise<boolean>;
     windowMember(keys: string[]): Promise<string>;
 }
 
@@ -1110,6 +1151,8 @@ declare class CheerioPage extends EventEmitter implements LsdPage {
     title(): Promise<string>;
     url(): string;
     use(): boolean;
+    waitForElement(): Promise<boolean>;
+    waitForNavigation(): Promise<boolean>;
     windowMember(): Promise<string>;
 }
 
@@ -1135,4 +1178,4 @@ declare class CheerioElement implements LsdElement {
     scrollIntoView(): Promise<boolean>;
 }
 
-export { type AllBrowser, type AllBrowserContext, type AllFrame, type AllPage, type AllResponse, type BrowserControllerOptions, type BrowserControllerType, type BrowserCreationMethod, type BrowserManager, CheerioElement, type CheerioNode, CheerioPage, type CookieItem, type GotoOptions, type IframeOption, type InputOptions, type KeyInput, type KeyPressOptions, type LocalStorageItem, type LocalStorageOrigin, type LowerCasePaperFormat, type LsdBrowser, type LsdBrowserContext, type LsdBrowserContextOptions, type LsdBrowserController, type LsdBrowserType, type LsdConnectOptions, type LsdElement, type LsdLaunchOptions, type LsdPage, type MouseClickOptions, type PDFMargin, type PDFOptions, type PageExtInPlaywright, type PageExtInPuppeteer, type PageInfo, type PageOpenType, type PageStatus, type PaperFormat, PlaywrightBrowser, PlaywrightBrowserContext, PlaywrightElement, PlaywrightPage, type Proxy, PuppeteerBrowser, PuppeteerBrowserContext, PuppeteerElement, PuppeteerPage, type RequestInterceptionAction, type RequestInterceptionOption, type RequestMatch, type RequestMethod, type RequestResourceType, type ResponseHandler, type ResponseHandlerOptions, type ResponseInterceptionItem, type ResponseInterceptionOption, type ResponseMatch, type ScreenshotOptions, type SelectOptions, type StateData, type ViewportSize, defaultProxy };
+export { type AllBrowser, type AllBrowserContext, type AllFrame, type AllPage, type AllResponse, type BrowserControllerOptions, type BrowserControllerType, type BrowserCreationMethod, type BrowserManager, CheerioElement, type CheerioNode, CheerioPage, type CookieItem, type GotoOptions, type IframeOption, type InputOptions, type KeyInput, type KeyPressOptions, type LocalStorageItem, type LocalStorageOrigin, type LowerCasePaperFormat, type LsdBrowser, type LsdBrowserContext, type LsdBrowserContextOptions, type LsdBrowserController, type LsdBrowserType, type LsdConnectOptions, type LsdElement, type LsdLaunchOptions, type LsdPage, type MouseClickOptions, type NavigationWaitUntil, type PDFMargin, type PDFOptions, type PageExtInPlaywright, type PageExtInPuppeteer, type PageInfo, type PageOpenType, type PageStatus, type PaperFormat, PlaywrightBrowser, PlaywrightBrowserContext, PlaywrightElement, PlaywrightPage, type Proxy, PuppeteerBrowser, PuppeteerBrowserContext, PuppeteerElement, PuppeteerPage, type RequestInterceptionAction, type RequestInterceptionOption, type RequestMatch, type RequestMethod, type RequestResourceType, type ResponseHandler, type ResponseHandlerOptions, type ResponseInterceptionItem, type ResponseInterceptionOption, type ResponseMatch, type ScreenshotOptions, type SelectOptions, type StateData, type ViewportSize, type WaitElementOptions, type WaitNavigationOptions, defaultProxy };

package/dist/index.d.ts

@@ -243,14 +243,15 @@ interface SelectOptions {
      */
     labels?: string[];
 }
+/**
+ * * playwright: "load" | "domcontentloaded" | "networkidle" | "commit", "networkidle0" | "networkidle2" => "networkidle";
+ * * puppeteer: "load" | "domcontentloaded" | "networkidle0" | "networkidle2", "networkidle" => "networkidle0", "commit" ignored;
+ */
+type NavigationWaitUntil = "load" | "domcontentloaded" | "networkidle" | "commit" | "networkidle0" | "networkidle2";
 interface GotoOptions {
     referer?: string;
     timeout?: number;
-    /**
-     * playwright: "load" | "domcontentloaded" | "networkidle" | "commit", "networkidle0" | "networkidle2" => "networkidle";
-     * puppeteer: "load" | "domcontentloaded" | "networkidle0" | "networkidle2", "networkidle" => "networkidle0", "commit" ignored;
-     */
-    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit" | "networkidle0" | "networkidle2";
+    waitUntil?: NavigationWaitUntil;
 }
 /**
  * * src takes precedence over selector, at least one of them must be defined
@@ -684,6 +685,31 @@ interface ScreenshotOptions {
      */
     type?: 'png' | 'jpeg';
 }
+interface WaitElementOptions {
+    /**
+     * @default 30_000 ms
+     */
+    timeout?: number;
+    /**
+     * @default "visible"
+     */
+    state?: "attached" | "detached" | "hidden" | "visible";
+}
+interface WaitNavigationOptions {
+    /**
+     * only supported in playwright by now
+     * @default ""
+     */
+    url?: string | RegExp;
+    /**
+     * @default 30_000 ms
+     */
+    timeout?: number;
+    /**
+     * @default "visible"
+     */
+    waitUntil?: NavigationWaitUntil;
+}
 interface LsdPage extends EventEmitter {
     bringToFront(): Promise<boolean>;
     browserContext(): LsdBrowserContext;
@@ -778,6 +804,17 @@ interface LsdPage extends EventEmitter {
      * 开始使用该page(当前状态必须为free)
      */
     use(): boolean;
+    /**
+     *
+     * @param selector CSS selector, not XPath
+     * @param options
+     */
+    waitForElement(selector: string, options?: WaitElementOptions): Promise<boolean>;
+    /**
+     *
+     * @param options
+     */
+    waitForNavigation(options: WaitNavigationOptions): Promise<boolean>;
     /**
      * obj=window?.[key1]...?.[keyn]
      * @return obj ? JSON.stringify(obj) : ""
@@ -937,6 +974,8 @@ declare class PlaywrightPage extends EventEmitter implements LsdPage {
     title(): Promise<string>;
     url(): string;
     use(): boolean;
+    waitForElement(selector: string, options?: WaitElementOptions): Promise<boolean>;
+    waitForNavigation(options: WaitNavigationOptions): Promise<boolean>;
     windowMember(keys: string[]): Promise<string>;
 }
 
@@ -1041,6 +1080,8 @@ declare class PuppeteerPage extends EventEmitter implements LsdPage {
     title(): Promise<string>;
     url(): string;
     use(): boolean;
+    waitForElement(selector: string, options?: WaitElementOptions): Promise<boolean>;
+    waitForNavigation(options: WaitNavigationOptions): Promise<boolean>;
     windowMember(keys: string[]): Promise<string>;
 }
 
@@ -1110,6 +1151,8 @@ declare class CheerioPage extends EventEmitter implements LsdPage {
     title(): Promise<string>;
     url(): string;
     use(): boolean;
+    waitForElement(): Promise<boolean>;
+    waitForNavigation(): Promise<boolean>;
     windowMember(): Promise<string>;
 }
 
@@ -1135,4 +1178,4 @@ declare class CheerioElement implements LsdElement {
     scrollIntoView(): Promise<boolean>;
 }
 
-export { type AllBrowser, type AllBrowserContext, type AllFrame, type AllPage, type AllResponse, type BrowserControllerOptions, type BrowserControllerType, type BrowserCreationMethod, type BrowserManager, CheerioElement, type CheerioNode, CheerioPage, type CookieItem, type GotoOptions, type IframeOption, type InputOptions, type KeyInput, type KeyPressOptions, type LocalStorageItem, type LocalStorageOrigin, type LowerCasePaperFormat, type LsdBrowser, type LsdBrowserContext, type LsdBrowserContextOptions, type LsdBrowserController, type LsdBrowserType, type LsdConnectOptions, type LsdElement, type LsdLaunchOptions, type LsdPage, type MouseClickOptions, type PDFMargin, type PDFOptions, type PageExtInPlaywright, type PageExtInPuppeteer, type PageInfo, type PageOpenType, type PageStatus, type PaperFormat, PlaywrightBrowser, PlaywrightBrowserContext, PlaywrightElement, PlaywrightPage, type Proxy, PuppeteerBrowser, PuppeteerBrowserContext, PuppeteerElement, PuppeteerPage, type RequestInterceptionAction, type RequestInterceptionOption, type RequestMatch, type RequestMethod, type RequestResourceType, type ResponseHandler, type ResponseHandlerOptions, type ResponseInterceptionItem, type ResponseInterceptionOption, type ResponseMatch, type ScreenshotOptions, type SelectOptions, type StateData, type ViewportSize, defaultProxy };
+export { type AllBrowser, type AllBrowserContext, type AllFrame, type AllPage, type AllResponse, type BrowserControllerOptions, type BrowserControllerType, type BrowserCreationMethod, type BrowserManager, CheerioElement, type CheerioNode, CheerioPage, type CookieItem, type GotoOptions, type IframeOption, type InputOptions, type KeyInput, type KeyPressOptions, type LocalStorageItem, type LocalStorageOrigin, type LowerCasePaperFormat, type LsdBrowser, type LsdBrowserContext, type LsdBrowserContextOptions, type LsdBrowserController, type LsdBrowserType, type LsdConnectOptions, type LsdElement, type LsdLaunchOptions, type LsdPage, type MouseClickOptions, type NavigationWaitUntil, type PDFMargin, type PDFOptions, type PageExtInPlaywright, type PageExtInPuppeteer, type PageInfo, type PageOpenType, type PageStatus, type PaperFormat, PlaywrightBrowser, PlaywrightBrowserContext, PlaywrightElement, PlaywrightPage, type Proxy, PuppeteerBrowser, PuppeteerBrowserContext, PuppeteerElement, PuppeteerPage, type RequestInterceptionAction, type RequestInterceptionOption, type RequestMatch, type RequestMethod, type RequestResourceType, type ResponseHandler, type ResponseHandlerOptions, type ResponseInterceptionItem, type ResponseInterceptionOption, type ResponseMatch, type ScreenshotOptions, type SelectOptions, type StateData, type ViewportSize, type WaitElementOptions, type WaitNavigationOptions, defaultProxy };

package/dist/index.js

@@ -648,12 +648,19 @@ var PlaywrightPage = class extends EventEmitter {
     await this.clearResponseInterceptions();
     return true;
   }
+  #getWaitUntil(origWaitUntil) {
+    if (origWaitUntil === "networkidle0" || origWaitUntil === "networkidle2") {
+      return "networkidle";
+    } else {
+      return origWaitUntil;
+    }
+  }
   async goto(url, options) {
     if (!this.#page) {
       throw new Error("No valid page");
     }
     if (options) {
-      const { referer, timeout, waitUntil } = options;
+      const { referer, timeout, waitUntil = "load" } = options;
       const newOptions = {};
       if (referer) {
         newOptions.referer = referer;
@@ -661,9 +668,7 @@ var PlaywrightPage = class extends EventEmitter {
       if (timeout) {
         newOptions.timeout = timeout;
       }
-      if (waitUntil && waitUntil !== "commit") {
-        newOptions.waitUntil = waitUntil === "networkidle" ? "networkidle0" : waitUntil;
-      }
+      newOptions.waitUntil = this.#getWaitUntil(waitUntil);
       await this.#page.goto(url, newOptions);
     } else {
       await this.#page.goto(url);
@@ -996,6 +1001,30 @@ var PlaywrightPage = class extends EventEmitter {
     this.#status = "busy";
     return true;
   }
+  async waitForElement(selector, options = {}) {
+    if (!this.#page) {
+      throw new Error("No valid page");
+    }
+    const locator = this.#page.locator(selector);
+    const { timeout = 3e4, state = "visible" } = options;
+    await locator.waitFor({ state, timeout });
+    return true;
+  }
+  async waitForNavigation(options) {
+    if (!this.#page) {
+      throw new Error("No valid page");
+    }
+    const { url = "", timeout = 3e4, waitUntil = "load" } = options;
+    const newWaitUntil = this.#getWaitUntil(waitUntil);
+    if (url) {
+      await this.#page.waitForURL(url, { timeout, waitUntil: newWaitUntil });
+    } else if (newWaitUntil === "commit") {
+      throw new Error("commit is not supported in PlaywrightPage.waitForNavigation");
+    } else {
+      await this.#page.waitForLoadState(newWaitUntil, { timeout });
+    }
+    return true;
+  }
   async windowMember(keys) {
     if (!this.#page) {
       throw new Error("No valid page");
@@ -2023,12 +2052,21 @@ var PuppeteerPage = class extends EventEmitter4 {
     await this.clearResponseInterceptions();
     return true;
   }
+  #getWaitUntil(origWaitUntil) {
+    if (origWaitUntil === "networkidle") {
+      return "networkidle0";
+    } else if (origWaitUntil === "commit") {
+      throw new Error("commit is not supported in PuppeteerPage");
+    } else {
+      return origWaitUntil;
+    }
+  }
   async goto(url, options) {
     if (!this.#page) {
       throw new Error("No valid page");
     }
     if (options) {
-      const { referer, timeout, waitUntil } = options;
+      const { referer, timeout, waitUntil = "load" } = options;
       const newOptions = {};
       if (referer) {
         newOptions.referer = referer;
@@ -2037,7 +2075,7 @@ var PuppeteerPage = class extends EventEmitter4 {
         newOptions.timeout = timeout;
       }
       if (waitUntil && waitUntil !== "commit") {
-        newOptions.waitUntil = waitUntil === "networkidle" ? "networkidle0" : waitUntil;
+        newOptions.waitUntil = this.#getWaitUntil(waitUntil);
       }
       await this.#page.goto(url, newOptions);
     } else {
@@ -2351,6 +2389,33 @@ var PuppeteerPage = class extends EventEmitter4 {
     this.#status = "busy";
     return true;
   }
+  async waitForElement(selector, options = {}) {
+    if (!this.#page) {
+      throw new Error("No valid page");
+    }
+    const { timeout = 3e4, state = "visible" } = options;
+    if (state === "visible") {
+      await this.#page.waitForSelector(selector, { timeout, visible: true });
+    } else if (state === "hidden") {
+      await this.#page.waitForSelector(selector, { timeout, hidden: true });
+    } else {
+      throw new Error(`${state} is not supported in PuppeteerPage.waitForElement`);
+    }
+    return true;
+  }
+  async waitForNavigation(options) {
+    if (!this.#page) {
+      throw new Error("No valid page");
+    }
+    const { url = "", timeout = 3e4, waitUntil = "load" } = options;
+    const newWaitUntil = this.#getWaitUntil(waitUntil);
+    if (url) {
+      throw new Error("url is not supported in PuppeteerPage.waitForNavigation");
+    } else {
+      await this.#page.waitForNavigation({ timeout, waitUntil: newWaitUntil });
+    }
+    return true;
+  }
   async windowMember(keys) {
     if (!this.#page) {
       throw new Error("No valid page");
@@ -16927,6 +16992,12 @@ var CheerioPage = class extends EventEmitter7 {
   use() {
     throw new Error("Not supported in CheerioPage.");
   }
+  waitForElement() {
+    throw new Error("Not supported in CheerioPage.");
+  }
+  waitForNavigation() {
+    throw new Error("Not supported in CheerioPage.");
+  }
   async windowMember() {
     throw new Error("Not supported in CheerioPage.");
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letsscrapedata/controller",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Unified browser / HTML controller interfaces that support playwright, puppeteer and cheerio",
   "type": "module",
   "main": "./dist/index.mjs",