refactor: improve function deprecation module (#19012) (#19199)

* add removeFunction to deprecation module

* clarify deprecate api

* throw error

* change error msg

lib/common/api/deprecate.ts

@@ -33,9 +33,21 @@ const deprecate: ElectronInternal.DeprecationUtil = {
     }
   },
 
+  // remove a function with no replacement
+  removeFunction: (fn, removedName) => {
+    if (!fn) { throw Error(`'${removedName} function' is invalid or does not exist.`) }
+
+    // wrap the deprecated function to warn user
+    const warn = warnOnce(`${fn.name} function`)
+    return function (this: any) {
+      warn()
+      fn.apply(this, arguments)
+    }
+  },
+
   // change the name of a function
-  function: (fn, newName) => {
-    const warn = warnOnce(fn.name, newName)
+  renameFunction: (fn, newName) => {
+    const warn = warnOnce(`${fn.name} function`, `${newName} function`)
     return function (this: any) {
       warn()
       fn.apply(this, arguments)

spec/api-deprecations-spec.js

@@ -87,7 +87,7 @@ describe('deprecations', () => {
     deprecations.setHandler(m => { msg = m })
 
     function oldFn () { return 'hello' }
-    const deprecatedFn = deprecate.function(oldFn)
+    const deprecatedFn = deprecate.removeFunction(oldFn, 'oldFn')
     deprecatedFn()
 
     expect(msg).to.be.a('string')
@@ -100,7 +100,7 @@ describe('deprecations', () => {
 
     function oldFn () { return 'hello' }
     function newFn () { return 'goodbye' }
-    const deprecatedFn = deprecate.function(oldFn, newFn)
+    const deprecatedFn = deprecate.renameFunction(oldFn, newFn)
     deprecatedFn()
 
     expect(msg).to.be.a('string')

typings/internal-electron.d.ts

@@ -75,7 +75,8 @@ declare namespace ElectronInternal {
     getHandler(): DeprecationHandler | null;
     warn(oldName: string, newName: string): void;
     log(message: string): void;
-    function(fn: Function, newName: string): Function;
+    removeFunction(fn: Function, removedName: string): Function;
+    renameFunction(fn: Function, newName: string): Function;
     event(emitter: NodeJS.EventEmitter, oldName: string, newName: string): void;
     fnToProperty(module: any, prop: string, getter: string, setter: string): void;
     removeProperty<T, K extends (keyof T & string)>(object: T, propertyName: K): T;