docs: discourage Download.createReadStream (#37831)

Author: Skn0tt

docs/src/api/class-download.md

@@ -74,6 +74,10 @@ Upon successful cancellations, `download.failure()` would resolve to `'canceled'
 
 Returns a readable stream for a successful download, or throws for a failed/canceled download.
 
+:::note
+If you don't need a readable stream, it's usually simpler to read the file from disk after the download completed. See [`method: Download.path`].
+:::
+
 ## async method: Download.delete
 * since: v1.8
 

packages/playwright-client/types/types.d.ts

@@ -19106,6 +19106,10 @@ export interface Download {
 
   /**
    * Returns a readable stream for a successful download, or throws for a failed/canceled download.
+   *
+   * **NOTE** If you don't need a readable stream, it's usually simpler to read the file from disk after the download
+   * completed. See [download.path()](https://playwright.dev/docs/api/class-download#download-path).
+   *
    */
   createReadStream(): Promise<Readable>;
 

packages/playwright-core/types/types.d.ts

@@ -19106,6 +19106,10 @@ export interface Download {
 
   /**
    * Returns a readable stream for a successful download, or throws for a failed/canceled download.
+   *
+   * **NOTE** If you don't need a readable stream, it's usually simpler to read the file from disk after the download
+   * completed. See [download.path()](https://playwright.dev/docs/api/class-download#download-path).
+   *
    */
   createReadStream(): Promise<Readable>;