Add note about handling invalid URLs

.npmignore

@@ -5,3 +5,4 @@ test
 config
 __mocks__
 .github
+test-app

CHANGELOG.md

@@ -1,3 +1,7 @@
+# 3.2.1 (2024-10-21)
+
+- Add an FAQ section to `README.md` on how to handle invalid URLs
+
 # 3.2.0 (2024-08-04)
 
 - Fix issues around starting multiple downloads at the same time.

README.md

@@ -74,6 +74,7 @@ manager.resumeDownload(id);
     - [`isDownloadInterrupted()`](#isdownloadinterrupted)
     - [`isDownloadCompleted()`](#isdownloadcompleted)
 - [Mock class](#mock-class)
+- [FAQ](#faq)
 - [Acknowledgments](#acknowledgments)
 
 # Installation
@@ -352,7 +353,9 @@ class DownloadData {
    */
   resolvedFilename: string
   /**
-   * If true, the download was cancelled from the save as dialog
+   * If true, the download was cancelled from the save as dialog. This flag
+   * will also be true if the download was cancelled by the application when
+   * using the save as dialog.
    */
   cancelledFromSaveAsDialog?: boolean
   /**
@@ -455,6 +458,46 @@ If you need to mock out `ElectronDownloadManager` in your tests, you can use the
 
 `import { ElectronDownloadManagerMock } from 'electron-dl-manager'`
 
+# FAQ
+
+## How do I capture if the download is invalid? `onError()` is not being called.
+
+Electron doesn't provide an explicit way to capture errors for downloads in general.
+What it does for invalid URLs, it will trigger the `onDownloadCancelled()` callback.
+
+```typescript
+const id = await manager.download({
+  window: mainWindow,
+  url: 'https://alkjsdflksjdflk.com/file.zip',
+  callbacks: {
+    onDownloadCancelled: async (...) => {
+      // Invalid download; this callback will be called
+    },
+  }
+});
+```
+
+A better way to handle this is to check if the URL exists prior to the download yourself.
+I couldn't find a library that I felt was reliable to include into this package,
+so it's best you find a library that works for you:
+
+- https://www.npmjs.com/search?q=url%20exists&ranking=maintenance
+
+GPT also suggests the following code (untested):
+
+```typescript
+async function urlExists(url: string): Promise<boolean> {
+  try {
+    const response = await fetch(url, { method: 'HEAD' });
+    return response.ok;
+  } catch (error) {
+    return false;
+  }
+}
+
+const exists = await urlExists('https://example.com/file.jpg');
+```
+
 # Acknowledgments
 
 This code uses small portions from [`electron-dl`](https://github.com/sindresorhus/electron-dl) and is noted in the

src/DownloadData.ts

@@ -30,7 +30,9 @@ export class DownloadData {
    */
   resolvedFilename: string;
   /**
-   * If true, the download was cancelled from the save as dialog
+   * If true, the download was cancelled from the save as dialog. This flag
+   * will also be true if the download was cancelled by the application when
+   * using the save as dialog.
    */
   cancelledFromSaveAsDialog?: boolean;
   /**

src/DownloadInitiator.ts

@@ -176,7 +176,7 @@ export class DownloadInitiator {
         }
       } else if (this.downloadData.isDownloadCancelled()) {
         clearInterval(interval);
-        this.log("Download was cancelled by user");
+        this.log("Download was cancelled");
         this.downloadData.cancelledFromSaveAsDialog = true;
         await this.callbackDispatcher.onDownloadCancelled(this.downloadData);
       } else {

test-app/.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true

test-app/.eslintignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+out
+.gitignore

test-app/.eslintrc.js

@@ -0,0 +1,7 @@
+module.exports = {
+  extends: [
+    'eslint:recommended',
+    '@electron-toolkit/eslint-config-ts/recommended',
+    '@electron-toolkit/eslint-config-prettier'
+  ]
+}

test-app/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+out
+.DS_Store
+*.log*

test-app/.prettierignore

@@ -0,0 +1,6 @@
+out
+dist
+pnpm-lock.yaml
+LICENSE.md
+tsconfig.json
+tsconfig.*.json

test-app/.prettierrc.yaml

@@ -0,0 +1,4 @@
+singleQuote: true
+semi: false
+printWidth: 100
+trailingComma: none

test-app/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["dbaeumer.vscode-eslint"]
+}

test-app/.vscode/launch.json

@@ -0,0 +1,39 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Main Process",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceRoot}",
+      "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-vite",
+      "windows": {
+        "runtimeExecutable": "${workspaceRoot}/node_modules/.bin/electron-vite.cmd"
+      },
+      "runtimeArgs": ["--sourcemap"],
+      "env": {
+        "REMOTE_DEBUGGING_PORT": "9222"
+      }
+    },
+    {
+      "name": "Debug Renderer Process",
+      "port": 9222,
+      "request": "attach",
+      "type": "chrome",
+      "webRoot": "${workspaceFolder}/src/renderer",
+      "timeout": 60000,
+      "presentation": {
+        "hidden": true
+      }
+    }
+  ],
+  "compounds": [
+    {
+      "name": "Debug All",
+      "configurations": ["Debug Main Process", "Debug Renderer Process"],
+      "presentation": {
+        "order": 1
+      }
+    }
+  ]
+}

test-app/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

test-app/README.md

@@ -0,0 +1,34 @@
+# test-app
+
+A minimal Electron application with TypeScript
+
+## Recommended IDE Setup
+
+- [VSCode](https://code.visualstudio.com/) + [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) + [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+
+## Project Setup
+
+### Install
+
+```bash
+$ npm install
+```
+
+### Development
+
+```bash
+$ npm run dev
+```
+
+### Build
+
+```bash
+# For windows
+$ npm run build:win
+
+# For macOS
+$ npm run build:mac
+
+# For Linux
+$ npm run build:linux
+```

test-app/build/entitlements.mac.plist

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>com.apple.security.cs.allow-jit</key>
+    <true/>
+    <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+    <true/>
+    <key>com.apple.security.cs.allow-dyld-environment-variables</key>
+    <true/>
+  </dict>
+</plist>

test-app/electron-builder.yml

@@ -0,0 +1,43 @@
+appId: com.electron.app
+productName: test-app
+directories:
+  buildResources: build
+files:
+  - '!**/.vscode/*'
+  - '!src/*'
+  - '!electron.vite.config.{js,ts,mjs,cjs}'
+  - '!{.eslintignore,.eslintrc.js,.prettierignore,.prettierrc.yaml,dev-app-update.yml,CHANGELOG.md,README.md}'
+  - '!{.env,.env.*,.npmrc,pnpm-lock.yaml}'
+  - '!{tsconfig.json,tsconfig.node.json,tsconfig.web.json}'
+asarUnpack:
+  - resources/**
+win:
+  executableName: test-app
+nsis:
+  artifactName: ${name}-${version}-setup.${ext}
+  shortcutName: ${productName}
+  uninstallDisplayName: ${productName}
+  createDesktopShortcut: always
+mac:
+  entitlementsInherit: build/entitlements.mac.plist
+  extendInfo:
+    - NSCameraUsageDescription: Application requests access to the device's camera.
+    - NSMicrophoneUsageDescription: Application requests access to the device's microphone.
+    - NSDocumentsFolderUsageDescription: Application requests access to the user's Documents folder.
+    - NSDownloadsFolderUsageDescription: Application requests access to the user's Downloads folder.
+  notarize: false
+dmg:
+  artifactName: ${name}-${version}.${ext}
+linux:
+  target:
+    - AppImage
+    - snap
+    - deb
+  maintainer: electronjs.org
+  category: Utility
+appImage:
+  artifactName: ${name}-${version}.${ext}
+npmRebuild: false
+publish:
+  provider: generic
+  url: https://example.com/auto-updates

test-app/electron.vite.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig, externalizeDepsPlugin } from 'electron-vite'
+
+export default defineConfig({
+  main: {
+    plugins: [externalizeDepsPlugin()]
+  },
+  preload: {
+    plugins: [externalizeDepsPlugin()]
+  },
+  renderer: {}
+})