refactor: Extract per-run crawler state into a CrawlerRun class

docs/public-api/crawlee-basic.api.md

@@ -47,6 +47,8 @@ import type { TypedRequestsLike } from '@crawlee/core';
 
 // @public (undocumented)
 export class BasicCrawler<Context extends CrawlingContext = CrawlingContext, ContextExtension = Dictionary<never>, ExtendedContext extends Context = Context & ContextExtension, Routes extends Record<keyof Routes, Dictionary> = Record<string, GetUserDataFromRequest<Context['request']>>, StatisticStateExtension extends object = {}> {
+    // (undocumented)
+    [Symbol.asyncDispose](): Promise<void>;
     constructor(options?: BasicCrawlerOptions<Context, ContextExtension, ExtendedContext, Routes, StatisticStateExtension> & RequireContextPipeline<CrawlingContext, Context>);
     // (undocumented)
     protected readonly additionalHttpErrorStatusCodes: Set<number>;
@@ -61,6 +63,7 @@ export class BasicCrawler<Context extends CrawlingContext = CrawlingContext, Con
     // (undocumented)
     get contextPipeline(): ContextPipeline<CrawlingContext, ExtendedContext>;
     protected createDefaultConcurrencySystem(options: ConcurrencySystemOptions): ConcurrencySystem;
+    destroy(): Promise<void>;
     exportData<Data>(path: string, format?: 'json' | 'csv', options?: DatasetExportOptions): Promise<Data[]>;
     // (undocumented)
     protected getCookieHeaderFromRequest(request: Request_2): string;
@@ -95,8 +98,7 @@ export class BasicCrawler<Context extends CrawlingContext = CrawlingContext, Con
     protected readonly retryOnBlocked: boolean;
     readonly router: RouterHandler<Context, Routes>;
     run(requests?: TypedRequestsLike<Routes>, options?: CrawlerRunOptions): Promise<FinalStatistics>;
-    // (undocumented)
-    running: boolean;
+    get running(): boolean;
     // (undocumented)
     protected runRequestHandler(crawlingContext: ExtendedContext): Promise<void>;
     get sessionPool(): ISessionPool;

docs/public-api/crawlee-browser-pool.api.md

@@ -229,6 +229,7 @@ export class BrowserPool<Options extends BrowserPoolOptions = BrowserPoolOptions
     prePageCloseHooks: PrePageCloseHook<BrowserControllerReturn, PageReturn>[];
     // (undocumented)
     prePageCreateHooks: PrePageCreateHook<BrowserControllerReturn, PageOptions>[];
+    releaseAllBrowsers(): Promise<void>;
     retireAllBrowsers(): void;
     // (undocumented)
     retireBrowserAfterPageCount: number;
@@ -587,6 +588,7 @@ export class RemoteBrowserPool<Page = unknown> implements IBrowserPool<Page> {
     get maxOpenBrowsers(): number;
     set maxOpenBrowsers(value: number);
     newPage(options?: NewPageOptions): Promise<Page>;
+    releaseAllBrowsers(): Promise<void>;
 }
 
 // @public (undocumented)

docs/public-api/crawlee-browser.api.md

@@ -48,6 +48,8 @@ export abstract class BrowserCrawler<Page extends CommonPage = CommonPage, Respo
     // (undocumented)
     protected buildContextPipeline(): ContextPipeline<CrawlingContext, BrowserCrawlingContext<Page, Response, Dictionary>>;
     // (undocumented)
+    destroy(): Promise<void>;
+    // (undocumented)
     protected getNavigationTimeoutMillis(): number;
     // (undocumented)
     protected readonly ignoreIframes: boolean;
@@ -58,6 +60,7 @@ export abstract class BrowserCrawler<Page extends CommonPage = CommonPage, Respo
     // (undocumented)
     protected abstract navigationHandler(crawlingContext: BrowserCrawlingContext<Page, Response>, gotoOptions: GoToOptions): Promise<Context['response'] | null | undefined>;
     protected runRequestHandler(crawlingContext: ExtendedContext): Promise<void>;
+    teardown(): Promise<void>;
 }
 
 // @public (undocumented)
@@ -113,6 +116,7 @@ export type LauncherRemoteBrowserPoolOptions = Omit<RemoteBrowserPoolOptions, 'b
 
 // @public
 export type OwnedBrowserPool<Page> = IBrowserPool<Page> & {
+    releaseAllBrowsers: () => Promise<void>;
     destroy: () => Promise<void>;
 };
 

docs/public-api/crawlee-core.api.md

@@ -32,6 +32,7 @@ import { LoggerJson } from '@apify/log';
 import type { LoggerOptions } from '@apify/log';
 import { LoggerText } from '@apify/log';
 import { LogLevel } from '@apify/log';
+import type { LogOptions } from '@crawlee/types';
 import { ParseSitemapOptions } from '@crawlee/utils';
 import type { ProcessedRequest } from '@crawlee/types';
 import type { ProxyInfo } from '@crawlee/types';
@@ -90,26 +91,26 @@ export abstract class BaseCrawleeLogger implements CrawleeLogger {
     child(options: Partial<CrawleeLoggerOptions>): CrawleeLogger;
     protected abstract createChild(options: Partial<CrawleeLoggerOptions>): CrawleeLogger;
     // (undocumented)
-    debug(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     // (undocumented)
     deprecated(message: string): void;
     // (undocumented)
-    error(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     // (undocumented)
     exception(exception: Error, message: string, data?: Record<string, unknown>): void;
     // (undocumented)
     getOptions(): CrawleeLoggerOptions;
     // (undocumented)
-    info(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     abstract logWithLevel(level: number, message: string, data?: Record<string, unknown>): void;
     // (undocumented)
-    perf(message: string, data?: Record<string, unknown>): void;
+    perf(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     // (undocumented)
     setOptions(options: Partial<CrawleeLoggerOptions>): void;
     // (undocumented)
-    softFail(message: string, data?: Record<string, unknown>): void;
+    softFail(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     // (undocumented)
-    warning(message: string, data?: Record<string, unknown>): void;
+    warning(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     // (undocumented)
     warningOnce(message: string): void;
 }
@@ -966,6 +967,8 @@ export { LoggerText }
 
 export { LogLevel }
 
+export { LogOptions }
+
 // @public (undocumented)
 export const MAX_POOL_SIZE = 1000;
 

docs/public-api/crawlee-playwright.api.md

@@ -75,6 +75,8 @@ export class AdaptivePlaywrightCrawler<ContextExtension = Dictionary<never>, Ext
     // (undocumented)
     protected buildContextPipeline(): ContextPipeline_2<CrawlingContext_2, AdaptivePlaywrightCrawlerContext>;
     // (undocumented)
+    destroy(): Promise<void>;
+    // (undocumented)
     protected init(): Promise<void>;
     // (undocumented)
     protected runRequestHandler(crawlingContext: CrawlingContext_2): Promise<void>;

docs/public-api/crawlee-types.api.md

@@ -96,17 +96,17 @@ export interface CookieJarSetCookieOptions {
 // @public
 export interface CrawleeLogger {
     child(options: Partial<CrawleeLoggerOptions>): CrawleeLogger;
-    debug(message: string, data?: Record<string, unknown>): void;
+    debug(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     deprecated(message: string): void;
-    error(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     exception(exception: Error, message: string, data?: Record<string, unknown>): void;
     getOptions(): CrawleeLoggerOptions;
-    info(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     logWithLevel(level: number, message: string, data?: Record<string, unknown>): void;
-    perf(message: string, data?: Record<string, unknown>): void;
+    perf(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     setOptions(options: Partial<CrawleeLoggerOptions>): void;
-    softFail(message: string, data?: Record<string, unknown>): void;
-    warning(message: string, data?: Record<string, unknown>): void;
+    softFail(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
+    warning(message: string, data?: Record<string, unknown>, options?: LogOptions): void;
     warningOnce(message: string): void;
 }
 
@@ -309,6 +309,11 @@ export interface KeyValueStoreRecord {
 // @public
 export type KeyValueStoreRecordInputValue = Buffer | ArrayBuffer | ArrayBufferView | string | NodeJS.ReadableStream | ReadableStream;
 
+// @public
+export interface LogOptions {
+    once?: boolean;
+}
+
 // @public
 export interface NewPageOptions {
     id?: string;

docs/upgrading/upgrading_v4.md

@@ -652,6 +652,29 @@ for (const [index, urls] of batches.entries()) {
 
 An alias identifies a run-scoped queue. It has no persistent name, and is emptied on start along with the default storages. Reuse an alias and you get that same queue back, handled requests included. The next crawl then finds nothing to do. Give each crawl its own alias. `purge()` is for when one crawler and one queue must be reused.
 
+### `teardown()` is per-run, disposing of the crawler is not
+
+`crawler.teardown()` ends the run in progress and releases only what that run owns — it is what `run()` calls on its way out. In v3 it also destroyed the browser pool a browser crawler had built for itself, and a destroyed `BrowserPool` cannot be used again: with its timers cleared and its listeners dropped, a second `run()` had nothing retiring idle browsers or reaping the retired ones. It now releases that run's browsers and leaves the pool usable.
+
+What outlives a run is released by `crawler.destroy()`, or by disposing of the crawler:
+
+```typescript
+await using crawler = new PlaywrightCrawler({ requestHandler: async ({ page }) => { /* ... */ } });
+
+await crawler.run(['https://example.com/a']);
+await crawler.run(['https://example.com/b']);
+```
+
+Disposing is optional — a finished run leaves no browsers open and no timer holding the process alive.
+
+:::info
+
+The `await using` syntax needs Node.js 24 or later. On Node.js 22 call <ApiLink to="basic-crawler/class/BasicCrawler#destroy">`destroy()`</ApiLink> yourself instead — it is what the disposal hook calls anyway, as with the [collaborators you own](#collaborators-you-own-are-disposable).
+
+:::
+
+`crawler.running` is now a read-only getter; in v3 it was an assignable field.
+
 ### Storage `.open()` now also accepts `{ id?, name? }`
 
 `Dataset.open()`, `KeyValueStore.open()`, and `RequestQueue.open()` previously accepted a single `idOrName?: string` parameter. This was ambiguous — callers couldn't express whether they were opening a storage by its ID or by name.