Add note about adding await to download() (#12)

CHANGELOG.md

@@ -1,3 +1,8 @@
+# 3.1.1 (2024-07-31)
+
+- Added more debug logging
+- Added notes to `README.md` that `download()` *must* be called with `await` or weird things happen.
+
 # 3.1.0 (2024-07-22)
 
 - If you are using Electron >= `30.3.0`, you will get native reporting on

README.md

@@ -25,6 +25,8 @@ import { ElectronDownloadManager } from 'electron-dl-manager';
 const manager = new ElectronDownloadManager();
 
 // Start a download
+// You *must* call manager.download() with await or 
+// you may get unexpected behavior
 const id = await manager.download({
   window: browserWindowInstance,
   url: 'https://example.com/file.zip',
@@ -106,6 +108,8 @@ ipcMain.handle('download-file', async (event, args) => {
   let downloadId
   const browserWindow = BrowserWindow.fromId(event.sender.id)
 
+  // You *must* call manager.download() with await or 
+  // you may get unexpected behavior
   downloadId = await manager.download({
     window: browserWindow,
     url,
@@ -172,7 +176,9 @@ constructor(params: DownloadManagerConstructorParams)
 ```typescript
 interface DownloadManagerConstructorParams {
   /**
-   * If defined, will log out internal debug messages
+   * If defined, will log out internal debug messages. Useful for
+   * troubleshooting downloads. Does not log out progress due to
+   * how frequent it can be.
    */
   debugLogger?: (message: string) => void
 }
@@ -182,6 +188,8 @@ interface DownloadManagerConstructorParams {
 
 Starts a file download. Returns the `id` of the download.
 
+**You must call `download()` with `await` or you may get unexpected behavior.**
+
 ```typescript
 download(params: DownloadParams): Promise<string>
 ```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "electron-dl-manager",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "A library for implementing file downloads in Electron with 'save as' dialog and id support.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

src/DownloadInitiator.ts

@@ -288,13 +288,16 @@ export class DownloadInitiator {
     return async (_event: Event, state: "completed" | "cancelled" | "interrupted") => {
       switch (state) {
         case "completed": {
+          this.log(`Download completed. Total bytes: ${this.downloadData.item.getTotalBytes()}`);
           await this.callbackDispatcher.onDownloadCompleted(this.downloadData);
           break;
         }
         case "cancelled":
+          this.log(`Download cancelled. Total bytes: ${this.downloadData.item.getReceivedBytes()} / ${this.downloadData.item.getTotalBytes()}`);
           await this.callbackDispatcher.onDownloadCancelled(this.downloadData);
           break;
         case "interrupted":
+          this.log(`Download interrupted. Total bytes: ${this.downloadData.item.getReceivedBytes()} / ${this.downloadData.item.getTotalBytes()}`);
           this.downloadData.interruptedVia = "completed";
           await this.callbackDispatcher.onDownloadInterrupted(this.downloadData);
           break;
@@ -310,6 +313,7 @@ export class DownloadInitiator {
     const { item } = this.downloadData;
 
     if (item) {
+      this.log("Cleaning up download item event listeners");
       item.removeListener("updated", this.onItemUpdated);
       item.removeListener("done", this.onItemDone);
     }

src/types.ts

@@ -33,7 +33,9 @@ export type DebugLoggerFn = (message: string) => void;
 
 export interface DownloadManagerConstructorParams {
   /**
-   * If defined, will log out internal debug messages
+   * If defined, will log out internal debug messages. Useful for
+   * troubleshooting downloads. Does not log out progress due to
+   * how frequent it can be.
    */
   debugLogger?: DebugLoggerFn;
 }
@@ -125,6 +127,8 @@ export interface IElectronDownloadManager {
    * the saveAs dialog will show up first.
    *
    * Returns the id of the download.
+   *
+   * This *must* be called with `await` or unintended behavior may occur.
    */
   download(params: DownloadConfig): Promise<string>;
   /**