[electron-packager] v12 introduces a promise-based API to deprecate using callbacks (#27200)

Please fill in this template.

- [x] Use a meaningful title for the pull request. Include the name of the package modified.
- [x] Test the change in your own code. (Compile and run.)
- [x] Add or edit tests to reflect the change. (Run with `npm test`.)
- [x] Follow the advice from the [readme](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.md#make-a-pull-request).
- [x] Avoid [common mistakes](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/README.md#common-mistakes).
- [x] Run `npm run lint package-name` (or `tsc` if no `tslint.json` is present).

Select one of these and delete the others:

If changing an existing definition:
- [x] Provide a URL to documentation or source code which provides context for the suggested changes: 
  - Docs: https://github.com/electron-userland/electron-packager/blob/a43c90ca9d4c0d5f380354a2544585f7d0a46240/docs/api.md
  - Commit: https://github.com/electron-userland/electron-packager/commit/a43c90ca9d4c0d5f380354a2544585f7d0a46240#diff-0f426376b964e609c5c4618eb8bed3b2
- [x] Increase the version number in the header if appropriate.
- ~~[ ] If you are making substantial changes, consider adding a `tslint.json` containing `{ "extends": "dtslint/dt.json" }`.~~

types/electron-packager/electron-packager-tests.ts

@@ -2,7 +2,7 @@ import packager = require("electron-packager");
 
 function callback(err: Error, appPaths: string[]) {
 	const msg = err.message;
-	const	index = appPaths.indexOf("test");
+	const index = appPaths.indexOf("test");
 }
 
 function completeFunction(buildPath: string, electronVersion: string, platform: string, arch: string, callbackFn: () => void) {
@@ -13,6 +13,8 @@ function ignoreFunction(path: string) {
 	return true;
 }
 
+// this is the obsolete API and will be removed in a future version
+
 packager({
 	dir: ".",
 	name: "myapplication",
@@ -30,6 +32,29 @@ packager({
 	}
 }, callback);
 
+function onCompleted(appPaths: string | string[]) {
+}
+
+function onError(error: Error) {
+}
+
+packager({
+	dir: ".",
+	name: "myapplication",
+	platform: "win32",
+	arch: "all",
+	electronVersion: "0.34.0",
+	win32metadata: {
+		CompanyName: "Acme CO",
+		FileDescription: "My application",
+		OriginalFilename: "myapp.exe",
+		ProductName: "Application",
+		InternalName: "roadrunner",
+		"requested-execution-level": "highestAvailable",
+		"application-manifest": "manifest.xml"
+	}
+}).then(onCompleted).catch(onError);
+
 packager({
 	dir: ".",
 	name: "myapplication",
@@ -44,7 +69,7 @@ packager({
 		"requested-execution-level": "requireAdministrator",
 		"application-manifest": "manifest.xml"
 	}
-}, callback);
+}).then(onCompleted).catch(onError);
 
 packager({
 	dir: ".",
@@ -52,14 +77,14 @@ packager({
 	platform: "all",
 	arch: "all",
 	electronVersion: "0.34.0"
-}, callback);
+}).then(onCompleted).catch(onError);
 
 packager({
 	dir: ".",
 	name: "myapplication",
 	electronVersion: "0.34.0",
 	all: true
-}, callback);
+}).then(onCompleted).catch(onError);
 
 packager({
 	dir: ".",
@@ -67,7 +92,7 @@ packager({
 	electronVersion: "0.34.0",
 	arch: "arm64",
 	executableName: "myapp"
-}, callback);
+}).then(onCompleted).catch(onError);
 
 packager({
 	dir: ".",
@@ -110,7 +135,7 @@ packager({
 		"requested-execution-level": "asInvoker",
 		"application-manifest": "manifest.xml"
 	}
-}, callback);
+}).then(onCompleted).catch(onError);
 
 packager({
 	dir: ".",
@@ -142,7 +167,7 @@ packager({
 	extendInfo: "plist.txt",
 	helperBundleId: "23223f",
 	osxSign: true
-}, callback);
+}).then(onCompleted).catch(onError);
 
 packager({
 	dir: ".",
@@ -161,7 +186,7 @@ packager({
 	ignore: ignoreFunction,
 	packageManager: "cnpm",
 	platform: "linux"
-}, callback);
+}).then(onCompleted).catch(onError);
 
 packager({
 	dir: ".",
@@ -192,4 +217,4 @@ packager({
 			"myapp2"
 		]
 	}]
-}, callback);
+}).then(onCompleted).catch(onError);

types/electron-packager/index.d.ts

@@ -1,14 +1,28 @@
-// Type definitions for electron-packager 10.1
+// Type definitions for electron-packager 12.0
 // Project: https://github.com/electron-userland/electron-packager
 // Definitions by: Maxime LUCE <https://github.com/SomaticIT>
 //                 Juan Jimenez-Anca <https://github.com/cortopy>
 //                 John Kleinschmidt <https://github.com/jkleinsc>
+//                 Brendan Forster <https://github.com/shiftkey>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
 
 /// <reference types="node" />
 
 export = electronPackager;
 
+/**
+ * This will:
+ * - Find or download the correct release of Electron
+ * - Use that version of electron to create a app in <out>/<appname>-<platform>-<arch>
+ *
+ * You should be able to launch the app on the platform you built for. If not, check your settings and try again.
+ *
+ * @param opts - Options to configure packaging.
+ *
+ * @returns A promise containing the path(s) to the newly created application(s)
+ */
+declare function electronPackager(opts: electronPackager.Options): Promise<string|string[]>;
+
 /**
  * This will:
  * - Find or download the correct release of Electron
@@ -18,6 +32,8 @@ export = electronPackager;
  *
  * @param opts - Options to configure packaging.
  * @param callback - Callback which is called when packaging is done or an error occured.
+ *
+ * @deprecated since version 12.0
  */
 declare function electronPackager(opts: electronPackager.Options, callback: electronPackager.finalCallback): void;