@letsscrapedata/controller 0.1.0 → 0.5.0

package/dist/index.d.cts

@@ -159,6 +159,11 @@ interface BrowserOptions {
      * @default 900
      */
     maxPageFreeSeconds?: number;
+    /**
+     * maximum duration (in seconds) for which the idle page is reserved   for tasks with the same domainName.
+     * @default 0, that means no reservation
+     */
+    maxReservedSeconds?: number;
     /**
      * @default true
      */
@@ -284,6 +289,11 @@ type LsdBrowserContextOptions = {
      * * puppeteer: set when creating the new page in the browserContext
      */
     userAgent?: string;
+    /**
+     * maximum duration (in seconds) for which the idle page is reserved   for tasks with the same domainName.
+     * @default 0, that means no reservation
+     */
+    maxReservedSeconds?: number;
 };
 type PageStatus = "free" | "busy" | "closed";
 /**
@@ -332,7 +342,6 @@ interface PageInfo {
      * page's status: free or busy
      * @default current unix time
      */
-    lastStatusUpdateTime: number;
     /**
      * taskId that are using this page
      * @default 0
@@ -352,7 +361,6 @@ interface UpdatablePageInfo {
      * page's status: free or busy
      * @default current unix time
      */
-    lastStatusUpdateTime?: number;
     /**
      * taskId that are using this page
      * @default 0
@@ -1087,7 +1095,14 @@ interface LsdPage extends EventEmitter {
      */
     goto(url: string, options?: GotoOptions): Promise<boolean>;
     id(): string;
-    isFree(): boolean;
+    /**
+     * Is the current page free (available) for a new task for domainName?
+     * @param domainName default "":
+     ** If it is "" and the current page URL is not "" / "about:blank", the current page must have been idle for maxReservedSeconds; otherwise, return false.
+     ** If it is not "", the current page URL must contain domainName; otherwise, return false.
+     */
+    isAvailable(domainName?: string): boolean;
+    lastStatusUpdateTime(): number;
     /**
      * valid only in CheerioPage
      * @param html
@@ -1213,8 +1228,10 @@ interface LsdBrowserContext extends EventEmitter {
     free(clearStateData?: boolean): boolean;
     /**
      * get a free page from current pages or by creating a new page
+     * @param domainName default "", if it is not "", prioritize retrieving from a free page whose URL includes that value
+     * @param always default false, whether a (new) page is always allocated, ignoring maxPagesPerBrowserContext
      */
-    getPage(always?: boolean): Promise<LsdPage | null>;
+    getPage(domainName?: string, always?: boolean): Promise<LsdPage | null>;
     /**
      * whether can get a number of free page(s)
      * * refer to getPage()
@@ -1225,6 +1242,10 @@ interface LsdBrowserContext extends EventEmitter {
     isFree(): boolean;
     isIncognito(): boolean;
     creationMethod(): BrowserContextCreationMethod;
+    /**
+     * get maximum duration (in seconds) for which the idle page is reserved   for tasks with the same domainName.
+     */
+    maxReservedSeconds(): number;
     page(pageIdx: number): LsdPage | null;
     pages(): LsdPage[];
     proxy(): ProxyInController | null;
@@ -1347,19 +1368,20 @@ declare class PlaywrightBrowser extends EventEmitter implements LsdBrowser {
 
 declare class PlaywrightBrowserContext extends EventEmitter implements LsdBrowserContext {
     #private;
-    constructor(lsdBrowser: LsdBrowser, browserContext: BrowserContext, browserContextCreationMethod: BrowserContextCreationMethod, incognito?: boolean, proxy?: ProxyInController | null, browserIdx?: number, browserContextIdx?: number, maxPagesPerBrowserContext?: number, maxPageFreeSeconds?: number, userAgent?: string, maxViewportOfNewPage?: boolean);
+    constructor(lsdBrowser: LsdBrowser, browserContext: BrowserContext, browserContextCreationMethod: BrowserContextCreationMethod, incognito?: boolean, proxy?: ProxyInController | null, browserIdx?: number, browserContextIdx?: number, maxPagesPerBrowserContext?: number, maxPageFreeSeconds?: number, userAgent?: string, maxReservedSeconds?: number, maxViewportOfNewPage?: boolean);
     apiContext(): LsdApiContext;
     browser(): LsdBrowser;
     close(): Promise<boolean>;
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
     creationMethod(): BrowserContextCreationMethod;
     doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
-    getPage(always?: boolean): Promise<LsdPage | null>;
+    getPage(domainName?: string, always?: boolean): Promise<LsdPage | null>;
     free(clearStateData?: boolean): boolean;
     hasFreePage(pageNum?: number): boolean;
     id(): string;
     isFree(): boolean;
     isIncognito(): boolean;
+    maxReservedSeconds(): number;
     page(pageIdx: number): LsdPage | null;
     pages(): LsdPage[];
     proxy(): ProxyInController | null;
@@ -1395,7 +1417,8 @@ declare class PlaywrightPage extends EventEmitter implements LsdPage {
     free(): Promise<boolean>;
     goto(url: string, options?: GotoOptions | undefined): Promise<boolean>;
     id(): string;
-    isFree(): boolean;
+    isAvailable(domainName?: string): boolean;
+    lastStatusUpdateTime(): number;
     localStroage(): Promise<LocalStorageOrigin[]>;
     load(): boolean;
     mainFrame(): AllFrame;
@@ -1497,19 +1520,20 @@ declare class PuppeteerBrowser extends EventEmitter implements LsdBrowser {
 
 declare class PuppeteerBrowserContext extends EventEmitter implements LsdBrowserContext {
     #private;
-    constructor(lsdBrowser: LsdBrowser, browserContext: BrowserContext$1, browserContextCreationMethod: BrowserContextCreationMethod, incognito?: boolean, proxy?: ProxyInController | null, browserIdx?: number, browserContextIdx?: number, maxPagesPerBrowserContext?: number, maxPageFreeSeconds?: number, userAgent?: string, maxViewportOfNewPage?: boolean);
+    constructor(lsdBrowser: LsdBrowser, browserContext: BrowserContext$1, browserContextCreationMethod: BrowserContextCreationMethod, incognito?: boolean, proxy?: ProxyInController | null, browserIdx?: number, browserContextIdx?: number, maxPagesPerBrowserContext?: number, maxPageFreeSeconds?: number, userAgent?: string, maxReservedSeconds?: number, maxViewportOfNewPage?: boolean);
     apiContext(): LsdApiContext;
     browser(): LsdBrowser;
     close(): Promise<boolean>;
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
     creationMethod(): BrowserContextCreationMethod;
     doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
-    getPage(always?: boolean): Promise<LsdPage | null>;
+    getPage(domainName?: string, always?: boolean): Promise<LsdPage | null>;
     free(clearStateData?: boolean): boolean;
     hasFreePage(pageNum?: number): boolean;
     id(): string;
     isIncognito(): boolean;
     isFree(): boolean;
+    maxReservedSeconds(): number;
     page(pageIdx: number): LsdPage | null;
     pages(): LsdPage[];
     proxy(): ProxyInController | null;
@@ -1545,7 +1569,8 @@ declare class PuppeteerPage extends EventEmitter implements LsdPage {
     free(): Promise<boolean>;
     goto(url: string, options?: GotoOptions | undefined): Promise<boolean>;
     id(): string;
-    isFree(): boolean;
+    isAvailable(domainName?: string): boolean;
+    lastStatusUpdateTime(): number;
     localStroage(): Promise<LocalStorageOrigin[]>;
     load(): boolean;
     mainFrame(): AllFrame;
@@ -1651,7 +1676,8 @@ declare class CheerioPage extends EventEmitter implements LsdPage {
     free(): Promise<boolean>;
     goto(): Promise<boolean>;
     id(): string;
-    isFree(): boolean;
+    isAvailable(): boolean;
+    lastStatusUpdateTime(): number;
     load(html: string, isHtml?: boolean): boolean;
     localStroage(): Promise<LocalStorageOrigin[]>;
     mainFrame(): AllFrame;

package/dist/index.d.ts

@@ -159,6 +159,11 @@ interface BrowserOptions {
      * @default 900
      */
     maxPageFreeSeconds?: number;
+    /**
+     * maximum duration (in seconds) for which the idle page is reserved   for tasks with the same domainName.
+     * @default 0, that means no reservation
+     */
+    maxReservedSeconds?: number;
     /**
      * @default true
      */
@@ -284,6 +289,11 @@ type LsdBrowserContextOptions = {
      * * puppeteer: set when creating the new page in the browserContext
      */
     userAgent?: string;
+    /**
+     * maximum duration (in seconds) for which the idle page is reserved   for tasks with the same domainName.
+     * @default 0, that means no reservation
+     */
+    maxReservedSeconds?: number;
 };
 type PageStatus = "free" | "busy" | "closed";
 /**
@@ -332,7 +342,6 @@ interface PageInfo {
      * page's status: free or busy
      * @default current unix time
      */
-    lastStatusUpdateTime: number;
     /**
      * taskId that are using this page
      * @default 0
@@ -352,7 +361,6 @@ interface UpdatablePageInfo {
      * page's status: free or busy
      * @default current unix time
      */
-    lastStatusUpdateTime?: number;
     /**
      * taskId that are using this page
      * @default 0
@@ -1087,7 +1095,14 @@ interface LsdPage extends EventEmitter {
      */
     goto(url: string, options?: GotoOptions): Promise<boolean>;
     id(): string;
-    isFree(): boolean;
+    /**
+     * Is the current page free (available) for a new task for domainName?
+     * @param domainName default "":
+     ** If it is "" and the current page URL is not "" / "about:blank", the current page must have been idle for maxReservedSeconds; otherwise, return false.
+     ** If it is not "", the current page URL must contain domainName; otherwise, return false.
+     */
+    isAvailable(domainName?: string): boolean;
+    lastStatusUpdateTime(): number;
     /**
      * valid only in CheerioPage
      * @param html
@@ -1213,8 +1228,10 @@ interface LsdBrowserContext extends EventEmitter {
     free(clearStateData?: boolean): boolean;
     /**
      * get a free page from current pages or by creating a new page
+     * @param domainName default "", if it is not "", prioritize retrieving from a free page whose URL includes that value
+     * @param always default false, whether a (new) page is always allocated, ignoring maxPagesPerBrowserContext
      */
-    getPage(always?: boolean): Promise<LsdPage | null>;
+    getPage(domainName?: string, always?: boolean): Promise<LsdPage | null>;
     /**
      * whether can get a number of free page(s)
      * * refer to getPage()
@@ -1225,6 +1242,10 @@ interface LsdBrowserContext extends EventEmitter {
     isFree(): boolean;
     isIncognito(): boolean;
     creationMethod(): BrowserContextCreationMethod;
+    /**
+     * get maximum duration (in seconds) for which the idle page is reserved   for tasks with the same domainName.
+     */
+    maxReservedSeconds(): number;
     page(pageIdx: number): LsdPage | null;
     pages(): LsdPage[];
     proxy(): ProxyInController | null;
@@ -1347,19 +1368,20 @@ declare class PlaywrightBrowser extends EventEmitter implements LsdBrowser {
 
 declare class PlaywrightBrowserContext extends EventEmitter implements LsdBrowserContext {
     #private;
-    constructor(lsdBrowser: LsdBrowser, browserContext: BrowserContext, browserContextCreationMethod: BrowserContextCreationMethod, incognito?: boolean, proxy?: ProxyInController | null, browserIdx?: number, browserContextIdx?: number, maxPagesPerBrowserContext?: number, maxPageFreeSeconds?: number, userAgent?: string, maxViewportOfNewPage?: boolean);
+    constructor(lsdBrowser: LsdBrowser, browserContext: BrowserContext, browserContextCreationMethod: BrowserContextCreationMethod, incognito?: boolean, proxy?: ProxyInController | null, browserIdx?: number, browserContextIdx?: number, maxPagesPerBrowserContext?: number, maxPageFreeSeconds?: number, userAgent?: string, maxReservedSeconds?: number, maxViewportOfNewPage?: boolean);
     apiContext(): LsdApiContext;
     browser(): LsdBrowser;
     close(): Promise<boolean>;
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
     creationMethod(): BrowserContextCreationMethod;
     doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
-    getPage(always?: boolean): Promise<LsdPage | null>;
+    getPage(domainName?: string, always?: boolean): Promise<LsdPage | null>;
     free(clearStateData?: boolean): boolean;
     hasFreePage(pageNum?: number): boolean;
     id(): string;
     isFree(): boolean;
     isIncognito(): boolean;
+    maxReservedSeconds(): number;
     page(pageIdx: number): LsdPage | null;
     pages(): LsdPage[];
     proxy(): ProxyInController | null;
@@ -1395,7 +1417,8 @@ declare class PlaywrightPage extends EventEmitter implements LsdPage {
     free(): Promise<boolean>;
     goto(url: string, options?: GotoOptions | undefined): Promise<boolean>;
     id(): string;
-    isFree(): boolean;
+    isAvailable(domainName?: string): boolean;
+    lastStatusUpdateTime(): number;
     localStroage(): Promise<LocalStorageOrigin[]>;
     load(): boolean;
     mainFrame(): AllFrame;
@@ -1497,19 +1520,20 @@ declare class PuppeteerBrowser extends EventEmitter implements LsdBrowser {
 
 declare class PuppeteerBrowserContext extends EventEmitter implements LsdBrowserContext {
     #private;
-    constructor(lsdBrowser: LsdBrowser, browserContext: BrowserContext$1, browserContextCreationMethod: BrowserContextCreationMethod, incognito?: boolean, proxy?: ProxyInController | null, browserIdx?: number, browserContextIdx?: number, maxPagesPerBrowserContext?: number, maxPageFreeSeconds?: number, userAgent?: string, maxViewportOfNewPage?: boolean);
+    constructor(lsdBrowser: LsdBrowser, browserContext: BrowserContext$1, browserContextCreationMethod: BrowserContextCreationMethod, incognito?: boolean, proxy?: ProxyInController | null, browserIdx?: number, browserContextIdx?: number, maxPagesPerBrowserContext?: number, maxPageFreeSeconds?: number, userAgent?: string, maxReservedSeconds?: number, maxViewportOfNewPage?: boolean);
     apiContext(): LsdApiContext;
     browser(): LsdBrowser;
     close(): Promise<boolean>;
     closeFreePages(maxPageFreeSeconds?: number): Promise<boolean>;
     creationMethod(): BrowserContextCreationMethod;
     doesMeetBrowserContextRequirements(browserContextRequirements: BrowserContextRequirements): boolean;
-    getPage(always?: boolean): Promise<LsdPage | null>;
+    getPage(domainName?: string, always?: boolean): Promise<LsdPage | null>;
     free(clearStateData?: boolean): boolean;
     hasFreePage(pageNum?: number): boolean;
     id(): string;
     isIncognito(): boolean;
     isFree(): boolean;
+    maxReservedSeconds(): number;
     page(pageIdx: number): LsdPage | null;
     pages(): LsdPage[];
     proxy(): ProxyInController | null;
@@ -1545,7 +1569,8 @@ declare class PuppeteerPage extends EventEmitter implements LsdPage {
     free(): Promise<boolean>;
     goto(url: string, options?: GotoOptions | undefined): Promise<boolean>;
     id(): string;
-    isFree(): boolean;
+    isAvailable(domainName?: string): boolean;
+    lastStatusUpdateTime(): number;
     localStroage(): Promise<LocalStorageOrigin[]>;
     load(): boolean;
     mainFrame(): AllFrame;
@@ -1651,7 +1676,8 @@ declare class CheerioPage extends EventEmitter implements LsdPage {
     free(): Promise<boolean>;
     goto(): Promise<boolean>;
     id(): string;
-    isFree(): boolean;
+    isAvailable(): boolean;
+    lastStatusUpdateTime(): number;
     load(html: string, isHtml?: boolean): boolean;
     localStroage(): Promise<LocalStorageOrigin[]>;
     mainFrame(): AllFrame;