refactor: make savePath a property on DownloadItem (#18677)

docs/api/download-item.md

@@ -80,7 +80,9 @@ The `downloadItem` object has the following methods:
 
 The API is only available in session's `will-download` callback function.
 If user doesn't set the save path via the API, Electron will use the original
-routine to determine the save path(Usually prompts a save dialog).
+routine to determine the save path; this usually prompts a save dialog.
+
+**[Deprecated](modernization/property-updates.md): use the `savePath` property instead.**
 
 #### `downloadItem.getSavePath()`
 
@@ -88,6 +90,8 @@ Returns `String` - The save path of the download item. This will be either the p
 set via `downloadItem.setSavePath(path)` or the path selected from the shown
 save dialog.
 
+**[Deprecated](modernization/property-updates.md): use the `savePath` property instead.**
+
 #### `downloadItem.setSaveDialogOptions(options)`
 
 * `options` SaveDialogOptions - Set the save file dialog options. This object has the same
@@ -181,3 +185,13 @@ Returns `String` - ETag header value.
 
 Returns `Double` - Number of seconds since the UNIX epoch when the download was
 started.
+
+### Instance Properties
+
+#### `downloadItem.savePath`
+
+A `String` property that determines the save file path of the download item.
+
+The property is only available in session's `will-download` callback function.
+If user doesn't set the save path via the property, Electron will use the original
+routine to determine the save path; this usually prompts a save dialog.

docs/api/modernization/property-updates.md

@@ -20,9 +20,6 @@ The Electron team is currently undergoing an initiative to convert separate gett
   * `visibleOnAllWorkspaces`
 * `crashReporter` module
   * `uploadToServer`
-* `DownloadItem` class
-  * `savePath`
-  * `paused`
 * `Session` module
   * `preloads`
 * `webContents` module
@@ -47,6 +44,8 @@ The Electron team is currently undergoing an initiative to convert separate gett
   * `applicationMenu`
   * `badgeCount`
   * `name`
+* `DownloadItem` class
+  * `savePath`
 * `BrowserWindow` module
   * `autohideMenuBar`
   * `resizable`

shell/browser/api/atom_api_download_item.cc

@@ -209,6 +209,8 @@ void DownloadItem::BuildPrototype(v8::Isolate* isolate,
       .SetMethod("isDone", &DownloadItem::IsDone)
       .SetMethod("setSavePath", &DownloadItem::SetSavePath)
       .SetMethod("getSavePath", &DownloadItem::GetSavePath)
+      .SetProperty("savePath", &DownloadItem::GetSavePath,
+                   &DownloadItem::SetSavePath)
       .SetMethod("setSaveDialogOptions", &DownloadItem::SetSaveDialogOptions)
       .SetMethod("getSaveDialogOptions", &DownloadItem::GetSaveDialogOptions)
       .SetMethod("getLastModifiedTime", &DownloadItem::GetLastModifiedTime)

spec-main/api-session-spec.js

@@ -553,8 +553,8 @@ describe('session module', () => {
     const assertDownload = (state, item, isCustom = false) => {
       expect(state).to.equal('completed')
       expect(item.getFilename()).to.equal('mock.pdf')
-      expect(path.isAbsolute(item.getSavePath())).to.equal(true)
-      expect(isPathEqual(item.getSavePath(), downloadFilePath)).to.equal(true)
+      expect(path.isAbsolute(item.savePath)).to.equal(true)
+      expect(isPathEqual(item.savePath, downloadFilePath)).to.equal(true)
       if (isCustom) {
         expect(item.getURL()).to.equal(`${protocolName}://item`)
       } else {
@@ -571,7 +571,7 @@ describe('session module', () => {
     it('can download using WebContents.downloadURL', (done) => {
       const port = downloadServer.address().port
       w.webContents.session.once('will-download', function (e, item) {
-        item.setSavePath(downloadFilePath)
+        item.savePath = downloadFilePath
         item.on('done', function (e, state) {
           assertDownload(state, item)
           done()
@@ -589,7 +589,7 @@ describe('session module', () => {
       protocol.registerHttpProtocol(protocolName, handler, (error) => {
         if (error) return done(error)
         w.webContents.session.once('will-download', function (e, item) {
-          item.setSavePath(downloadFilePath)
+          item.savePath = downloadFilePath
           item.on('done', function (e, state) {
             assertDownload(state, item, true)
             done()
@@ -612,7 +612,7 @@ describe('session module', () => {
       }
       const done = new Promise(resolve => {
         w.webContents.session.once('will-download', function (e, item) {
-          item.setSavePath(downloadFilePath)
+          item.savePath = downloadFilePath
           item.on('done', function (e, state) {
             resolve([state, item])
           })
@@ -626,7 +626,7 @@ describe('session module', () => {
     it('can cancel download', (done) => {
       const port = downloadServer.address().port
       w.webContents.session.once('will-download', function (e, item) {
-        item.setSavePath(downloadFilePath)
+        item.savePath = downloadFilePath
         item.on('done', function (e, state) {
           expect(state).to.equal('cancelled')
           expect(item.getFilename()).to.equal('mock.pdf')
@@ -650,7 +650,7 @@ describe('session module', () => {
 
       const port = downloadServer.address().port
       w.webContents.session.once('will-download', function (e, item) {
-        item.setSavePath(downloadFilePath)
+        item.savePath = downloadFilePath
         item.on('done', function (e, state) {
           expect(item.getFilename()).to.equal('download.pdf')
           done()
@@ -694,7 +694,7 @@ describe('session module', () => {
     describe('when a save path is specified and the URL is unavailable', () => {
       it('does not display a save dialog and reports the done state as interrupted', (done) => {
         w.webContents.session.once('will-download', function (e, item) {
-          item.setSavePath(downloadFilePath)
+          item.savePath = downloadFilePath
           if (item.getState() === 'interrupted') {
             item.resume()
           }
@@ -725,7 +725,7 @@ describe('session module', () => {
         expect(item.getMimeType()).to.equal(options.mimeType)
         expect(item.getReceivedBytes()).to.equal(options.offset)
         expect(item.getTotalBytes()).to.equal(options.length)
-        expect(item.getSavePath()).to.equal(downloadFilePath)
+        expect(item.savePath).to.equal(downloadFilePath)
         done()
       })
       w.webContents.session.createInterruptedDownload(options)
@@ -756,7 +756,7 @@ describe('session module', () => {
         expect(item.getState()).to.equal('cancelled')
 
         const options = {
-          path: item.getSavePath(),
+          path: item.savePath,
           urlChain: item.getURLChain(),
           mimeType: item.getMimeType(),
           offset: item.getReceivedBytes(),
@@ -778,7 +778,7 @@ describe('session module', () => {
         const completedItem = await downloadResumed
         expect(completedItem.getState()).to.equal('completed')
         expect(completedItem.getFilename()).to.equal('logo.png')
-        expect(completedItem.getSavePath()).to.equal(downloadFilePath)
+        expect(completedItem.savePath).to.equal(downloadFilePath)
         expect(completedItem.getURL()).to.equal(downloadUrl)
         expect(completedItem.getMimeType()).to.equal('image/png')
         expect(completedItem.getReceivedBytes()).to.equal(14022)