fix: remove explicit resource management from types (#10918)

docs/api/puppeteer.browser._symbol.asyncdispose_.md

@@ -1,17 +0,0 @@
----
-sidebar_label: Browser.[Symbol.asyncDispose]
----
-
-# Browser.\[Symbol.asyncDispose\]() method
-
-#### Signature:
-
-```typescript
-class Browser {
-  [Symbol.asyncDispose](): Promise<void>;
-}
-```
-
-**Returns:**
-
-Promise&lt;void&gt;

docs/api/puppeteer.browser._symbol.dispose_.md

@@ -1,17 +0,0 @@
----
-sidebar_label: Browser.[Symbol.dispose]
----
-
-# Browser.\[Symbol.dispose\]() method
-
-#### Signature:
-
-```typescript
-class Browser {
-  [Symbol.dispose](): void;
-}
-```
-
-**Returns:**
-
-void

docs/api/puppeteer.browser.md

@@ -9,13 +9,11 @@ A Browser is created when Puppeteer connects to a browser instance, either throu
 #### Signature:
 
 ```typescript
-export declare class Browser extends EventEmitter<BrowserEvents> implements AsyncDisposable, Disposable
+export declare class Browser extends EventEmitter<BrowserEvents>
 ```
 
 **Extends:** [EventEmitter](./puppeteer.eventemitter.md)&lt;[BrowserEvents](./puppeteer.browserevents.md)&gt;
 
-**Implements:** AsyncDisposable, Disposable
-
 ## Remarks
 
 The Browser class extends from Puppeteer's [EventEmitter](./puppeteer.eventemitter.md) class and will emit various events which are documented in the [BrowserEvent](./puppeteer.browserevent.md) enum.
@@ -62,8 +60,6 @@ import puppeteer from 'puppeteer';
 
 | Method                                                                                         | Modifiers | Description                                                                                                                                                                                                            |
 | ---------------------------------------------------------------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [\[Symbol.asyncDispose\]()](./puppeteer.browser._symbol.asyncdispose_.md)                      |           |                                                                                                                                                                                                                        |
-| [\[Symbol.dispose\]()](./puppeteer.browser._symbol.dispose_.md)                                |           |                                                                                                                                                                                                                        |
 | [browserContexts()](./puppeteer.browser.browsercontexts.md)                                    |           | Returns an array of all open browser contexts. In a newly created browser, this will return a single instance of [BrowserContext](./puppeteer.browsercontext.md).                                                      |
 | [close()](./puppeteer.browser.close.md)                                                        |           | Closes the browser and all of its pages (if any were opened). The [Browser](./puppeteer.browser.md) object itself is considered to be disposed and cannot be used anymore.                                             |
 | [createIncognitoBrowserContext(options)](./puppeteer.browser.createincognitobrowsercontext.md) |           | Creates a new incognito browser context. This won't share cookies/cache with other browser contexts.                                                                                                                   |

docs/api/puppeteer.jshandle._symbol.asyncdispose_.md

@@ -1,17 +0,0 @@
----
-sidebar_label: JSHandle.[Symbol.asyncDispose]
----
-
-# JSHandle.\[Symbol.asyncDispose\]() method
-
-#### Signature:
-
-```typescript
-class JSHandle {
-  [Symbol.asyncDispose](): Promise<void>;
-}
-```
-
-**Returns:**
-
-Promise&lt;void&gt;

docs/api/puppeteer.jshandle._symbol.dispose_.md

@@ -1,17 +0,0 @@
----
-sidebar_label: JSHandle.[Symbol.dispose]
----
-
-# JSHandle.\[Symbol.dispose\]() method
-
-#### Signature:
-
-```typescript
-class JSHandle {
-  [Symbol.dispose](): void;
-}
-```
-
-**Returns:**
-
-void

docs/api/puppeteer.jshandle.md

@@ -13,11 +13,9 @@ Handles can be used as arguments for any evaluation function such as [Page.$eval
 #### Signature:
 
 ```typescript
-export declare abstract class JSHandle<T = unknown> implements Disposable, AsyncDisposable, Moveable
+export declare abstract class JSHandle<T = unknown>
 ```
 
-**Implements:** Disposable, AsyncDisposable, [Moveable](./puppeteer.moveable.md)
-
 ## Remarks
 
 The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `JSHandle` class.
@@ -39,8 +37,6 @@ const windowHandle = await page.evaluateHandle(() => window);
 
 | Method                                                                       | Modifiers | Description                                                                                                                                                    |
 | ---------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [\[Symbol.asyncDispose\]()](./puppeteer.jshandle._symbol.asyncdispose_.md)   |           |                                                                                                                                                                |
-| [\[Symbol.dispose\]()](./puppeteer.jshandle._symbol.dispose_.md)             |           |                                                                                                                                                                |
 | [asElement()](./puppeteer.jshandle.aselement.md)                             |           | Either <code>null</code> or the handle itself if the handle is an instance of [ElementHandle](./puppeteer.elementhandle.md).                                   |
 | [dispose()](./puppeteer.jshandle.dispose.md)                                 |           | Releases the object referenced by the handle for garbage collection.                                                                                           |
 | [evaluate(pageFunction, args)](./puppeteer.jshandle.evaluate.md)             |           | Evaluates the given function with the current handle as its first argument.                                                                                    |

docs/api/puppeteer.page._symbol.asyncdispose_.md

@@ -1,17 +0,0 @@
----
-sidebar_label: Page.[Symbol.asyncDispose]
----
-
-# Page.\[Symbol.asyncDispose\]() method
-
-#### Signature:
-
-```typescript
-class Page {
-  [Symbol.asyncDispose](): Promise<void>;
-}
-```
-
-**Returns:**
-
-Promise&lt;void&gt;

docs/api/puppeteer.page._symbol.dispose_.md

@@ -1,17 +0,0 @@
----
-sidebar_label: Page.[Symbol.dispose]
----
-
-# Page.\[Symbol.dispose\]() method
-
-#### Signature:
-
-```typescript
-class Page {
-  [Symbol.dispose](): void;
-}
-```
-
-**Returns:**
-
-void

docs/api/puppeteer.page.md

@@ -15,13 +15,11 @@ One Browser instance might have multiple Page instances.
 #### Signature:
 
 ```typescript
-export declare abstract class Page extends EventEmitter<PageEvents> implements AsyncDisposable, Disposable
+export declare abstract class Page extends EventEmitter<PageEvents>
 ```
 
 **Extends:** [EventEmitter](./puppeteer.eventemitter.md)&lt;[PageEvents](./puppeteer.pageevents.md)&gt;
 
-**Implements:** AsyncDisposable, Disposable
-
 ## Remarks
 
 The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Page` class.
@@ -78,8 +76,6 @@ page.off('request', logRequest);
 
 | Method                                                                                                     | Modifiers | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | ---------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [\[Symbol.asyncDispose\]()](./puppeteer.page._symbol.asyncdispose_.md)                                     |           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| [\[Symbol.dispose\]()](./puppeteer.page._symbol.dispose_.md)                                               |           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | [$(selector)](./puppeteer.page._.md)                                                                       |           | Runs <code>document.querySelector</code> within the page. If no element matches the selector, the return value resolves to <code>null</code>.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | [$$(selector)](./puppeteer.page.__.md)                                                                     |           | The method runs <code>document.querySelectorAll</code> within the page. If no elements match the selector, the return value resolves to <code>[]</code>.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md)                                         |           | This method runs <code>Array.from(document.querySelectorAll(selector))</code> within the page and passes the result as the first argument to the <code>pageFunction</code>.                                                                                                                                                                                                                                                                                                                                                                                                                             |

package.json

@@ -175,6 +175,11 @@
     "wireit": "0.13.0",
     "zod": "3.22.2"
   },
+  "overrides": {
+    "@microsoft/api-extractor": {
+      "typescript": "$typescript"
+    }
+  },
   "workspaces": [
     "packages/*",
     "test",

packages/puppeteer-core/src/api/Browser.ts

@@ -241,10 +241,7 @@ export interface BrowserEvents extends Record<EventType, unknown> {
  *
  * @public
  */
-export class Browser
+export class Browser extends EventEmitter<BrowserEvents> {
-  extends EventEmitter<BrowserEvents>
-  implements AsyncDisposable, Disposable
-{
   /**
    * @internal
    */
@@ -506,10 +503,12 @@ export class Browser
     throw new Error('Not implemented');
   }
 
+  /** @internal */
   [Symbol.dispose](): void {
     return void this.close().catch(debugError);
   }
 
+  /** @internal */
   [Symbol.asyncDispose](): Promise<void> {
     return this.close();
   }

packages/puppeteer-core/src/api/JSHandle.ts

@@ -21,7 +21,6 @@ import {
   type EvaluateFuncWith,
   type HandleFor,
   type HandleOr,
-  type Moveable,
 } from '../common/types.js';
 import {debugError, withSourcePuppeteerURLIfNone} from '../common/util.js';
 import {moveable, throwIfDisposed} from '../util/decorators.js';
@@ -51,9 +50,7 @@ import {type Realm} from './Realm.js';
  * @public
  */
 @moveable
-export abstract class JSHandle<T = unknown>
+export abstract class JSHandle<T = unknown> {
-  implements Disposable, AsyncDisposable, Moveable
-{
   declare move: () => this;
 
   /**
@@ -219,10 +216,12 @@ export abstract class JSHandle<T = unknown>
    */
   abstract remoteObject(): Protocol.Runtime.RemoteObject;
 
+  /** @internal */
   [Symbol.dispose](): void {
     return void this.dispose().catch(debugError);
   }
 
+  /** @internal */
   [Symbol.asyncDispose](): Promise<void> {
     return this.dispose();
   }

packages/puppeteer-core/src/api/Page.ts

@@ -510,10 +510,7 @@ export interface NewDocumentScriptEvaluation {
  *
  * @public
  */
-export abstract class Page
+export abstract class Page extends EventEmitter<PageEvents> {
-  extends EventEmitter<PageEvents>
-  implements AsyncDisposable, Disposable
-{
   /**
    * @internal
    */
@@ -2882,10 +2879,12 @@ export abstract class Page
     throw new Error('Not implemented');
   }
 
+  /** @internal */
   [Symbol.dispose](): void {
     return void this.close().catch(debugError);
   }
 
+  /** @internal */
   [Symbol.asyncDispose](): Promise<void> {
     return this.close();
   }

packages/puppeteer-core/src/api/Realm.ts

@@ -101,6 +101,7 @@ export abstract class Realm implements Disposable {
   }
 
   #disposed = false;
+  /** @internal */
   [Symbol.dispose](): void {
     this.#disposed = true;
     this.taskManager.terminateAll(

packages/puppeteer-core/third_party/disposablestack/disposablestack.ts

@@ -1,3 +1,18 @@
+/*! *****************************************************************************
+Copyright (c) Microsoft Corporation. All rights reserved.
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE-2.0
+
+THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED
+WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE,
+MERCHANTABLITY OR NON-INFRINGEMENT.
+
+See the Apache Version 2.0 License for specific language governing permissions
+and limitations under the License.
+***************************************************************************** */
+
 import 'disposablestack/auto';
 
 declare global {
@@ -21,93 +36,156 @@ declare global {
     [Symbol.asyncDispose](): PromiseLike<void>;
   }
 
-  class DisposableStack implements Disposable {
+  interface SuppressedError extends Error {
-    constructor();
+    error: any;
+    suppressed: any;
+  }
 
+  interface SuppressedErrorConstructor extends ErrorConstructor {
+    new (error: any, suppressed: any, message?: string): SuppressedError;
+    (error: any, suppressed: any, message?: string): SuppressedError;
+    readonly prototype: SuppressedError;
+  }
+  var SuppressedError: SuppressedErrorConstructor;
+
+  interface DisposableStack {
     /**
-     * Gets a value indicating whether the stack has been disposed.
+     * Returns a value indicating whether this stack has been disposed.
      */
-    get disposed(): boolean;
+    readonly disposed: boolean;
-
     /**
-     * Alias for `[Symbol.dispose]()`.
+     * Disposes each resource in the stack in the reverse order that they were added.
      */
     dispose(): void;
-
     /**
-     * Adds a resource to the top of the stack. Has no effect if provided `null`
+     * Adds a disposable resource to the stack, returning the resource.
-     * or `undefined`.
+     * @param value The resource to add. `null` and `undefined` will not be added, but will be returned.
+     * @returns The provided {@link value}.
      */
-    use<T>(value: T): T;
+    use<T extends Disposable | null | undefined>(value: T): T;
-
     /**
-     * Adds a non-disposable resource and a disposal callback to the top of the
+     * Adds a value and associated disposal callback as a resource to the stack.
-     * stack.
+     * @param value The value to add.
+     * @param onDispose The callback to use in place of a `[Symbol.dispose]()` method. Will be invoked with `value`
+     * as the first parameter.
+     * @returns The provided {@link value}.
      */
     adopt<T>(value: T, onDispose: (value: T) => void): T;
-
     /**
-     * Adds a disposal callback to the top of the stack.
+     * Adds a callback to be invoked when the stack is disposed.
      */
     defer(onDispose: () => void): void;
-
     /**
-     * Moves all resources currently in this stack into a new `DisposableStack`.
+     * Move all resources out of this stack and into a new `DisposableStack`, and marks this stack as disposed.
+     * @example
+     * ```ts
+     * class C {
+     *   #res1: Disposable;
+     *   #res2: Disposable;
+     *   #disposables: DisposableStack;
+     *   constructor() {
+     *     // stack will be disposed when exiting constructor for any reason
+     *     using stack = new DisposableStack();
+     *
+     *     // get first resource
+     *     this.#res1 = stack.use(getResource1());
+     *
+     *     // get second resource. If this fails, both `stack` and `#res1` will be disposed.
+     *     this.#res2 = stack.use(getResource2());
+     *
+     *     // all operations succeeded, move resources out of `stack` so that they aren't disposed
+     *     // when constructor exits
+     *     this.#disposables = stack.move();
+     *   }
+     *
+     *   [Symbol.dispose]() {
+     *     this.#disposables.dispose();
+     *   }
+     * }
+     * ```
      */
     move(): DisposableStack;
-
-    /**
-     * Disposes of resources within this object.
-     */
     [Symbol.dispose](): void;
+    readonly [Symbol.toStringTag]: string;
   }
 
-  class AsyncDisposableStack implements AsyncDisposable {
+  interface DisposableStackConstructor {
-    constructor();
+    new (): DisposableStack;
+    readonly prototype: DisposableStack;
+  }
+  var DisposableStack: DisposableStackConstructor;
 
+  interface AsyncDisposableStack {
     /**
-     * Gets a value indicating whether the stack has been disposed.
+     * Returns a value indicating whether this stack has been disposed.
      */
-    get disposed(): boolean;
+    readonly disposed: boolean;
-
     /**
-     * Alias for `[Symbol.dispose]()`.
+     * Disposes each resource in the stack in the reverse order that they were added.
      */
-    dispose(): void;
+    disposeAsync(): Promise<void>;
-
     /**
-     * Adds a resource to the top of the stack. Has no effect if provided `null`
+     * Adds a disposable resource to the stack, returning the resource.
-     * or `undefined`.
+     * @param value The resource to add. `null` and `undefined` will not be added, but will be returned.
+     * @returns The provided {@link value}.
      */
-    use<T>(value: T): T;
+    use<T extends AsyncDisposable | Disposable | null | undefined>(value: T): T;
-
     /**
-     * Adds a non-disposable resource and a disposal callback to the top of the
+     * Adds a value and associated disposal callback as a resource to the stack.
-     * stack.
+     * @param value The value to add.
+     * @param onDisposeAsync The callback to use in place of a `[Symbol.asyncDispose]()` method. Will be invoked with `value`
+     * as the first parameter.
+     * @returns The provided {@link value}.
      */
-    adopt<T>(value: T, onDispose: (value: T) => Promise<void>): T;
+    adopt<T>(
-
+      value: T,
+      onDisposeAsync: (value: T) => PromiseLike<void> | void
+    ): T;
     /**
-     * Adds a disposal callback to the top of the stack.
+     * Adds a callback to be invoked when the stack is disposed.
      */
-    defer(onDispose: () => Promise<void>): void;
+    defer(onDisposeAsync: () => PromiseLike<void> | void): void;
-
     /**
-     * Moves all resources currently in this stack into a new `DisposableStack`.
+     * Move all resources out of this stack and into a new `DisposableStack`, and marks this stack as disposed.
+     * @example
+     * ```ts
+     * class C {
+     *   #res1: Disposable;
+     *   #res2: Disposable;
+     *   #disposables: DisposableStack;
+     *   constructor() {
+     *     // stack will be disposed when exiting constructor for any reason
+     *     using stack = new DisposableStack();
+     *
+     *     // get first resource
+     *     this.#res1 = stack.use(getResource1());
+     *
+     *     // get second resource. If this fails, both `stack` and `#res1` will be disposed.
+     *     this.#res2 = stack.use(getResource2());
+     *
+     *     // all operations succeeded, move resources out of `stack` so that they aren't disposed
+     *     // when constructor exits
+     *     this.#disposables = stack.move();
+     *   }
+     *
+     *   [Symbol.dispose]() {
+     *     this.#disposables.dispose();
+     *   }
+     * }
+     * ```
      */
     move(): AsyncDisposableStack;
-
-    /**
-     * Disposes of resources within this object.
-     */
     [Symbol.asyncDispose](): Promise<void>;
+    readonly [Symbol.toStringTag]: string;
   }
+
+  interface AsyncDisposableStackConstructor {
+    new (): AsyncDisposableStack;
+    readonly prototype: AsyncDisposableStack;
+  }
+  var AsyncDisposableStack: AsyncDisposableStackConstructor;
 }
 
 export const Symbol = globalThis.Symbol;
-export const DisposableStack = (
+export const DisposableStack = globalThis.DisposableStack;
-  globalThis as unknown as {DisposableStack: DisposableStack}
+export const AsyncDisposableStack = globalThis.AsyncDisposableStack;
-).DisposableStack;
-export const AsyncDisposableStack = (
-  globalThis as unknown as {AsyncDisposableStack: AsyncDisposableStack}
-).AsyncDisposableStack;