feat: promisify contentTracing.getTraceBufferUsage() (#16600)

* feat: promsify contentTracing.getTraceBufferUsage()

* deprecate getTraceBufferUsage

* address feedback from review

* properly deprecate

atom/browser/api/atom_api_content_tracing.cc

@@ -115,10 +115,25 @@ v8::Local<v8::Promise> StartTracing(
   return promise->GetHandle();
 }
 
-bool GetTraceBufferUsage(
+void OnTraceBufferUsageAvailable(scoped_refptr<atom::util::Promise> promise,
-    const base::RepeatingCallback<void(float, size_t)>& callback) {
+                                 float percent_full,
-  return TracingController::GetInstance()->GetTraceBufferUsage(
+                                 size_t approximate_count) {
-      base::BindOnce(callback));
+  mate::Dictionary dict = mate::Dictionary::CreateEmpty(promise->isolate());
+  dict.Set("percentage", percent_full);
+  dict.Set("value", approximate_count);
+
+  promise->Resolve(dict.GetHandle());
+}
+
+v8::Local<v8::Promise> GetTraceBufferUsage(v8::Isolate* isolate) {
+  scoped_refptr<atom::util::Promise> promise = new atom::util::Promise(isolate);
+  bool success = TracingController::GetInstance()->GetTraceBufferUsage(
+      base::BindOnce(&OnTraceBufferUsageAvailable, promise));
+
+  if (!success)
+    promise->RejectWithErrorMessage("Could not get trace buffer usage.");
+
+  return promise->GetHandle();
 }
 
 void Initialize(v8::Local<v8::Object> exports,

docs/api/breaking-changes.md

@@ -17,6 +17,19 @@ win.setMenu(null)
 win.removeMenu()
 ```
 
+## `contentTracing.getTraceBufferUsage()`
+
+```js
+// Deprecated
+contentTracing.getTraceBufferUsage((percentage, value) => {
+  // do something
+})
+// Replace with
+contentTracing.getTraceBufferUsage().then(infoObject => {
+  // infoObject has percentage and value fields
+})
+```
+
 ## `electron.screen` in renderer process
 
 ```js

docs/api/content-tracing.md

@@ -122,9 +122,19 @@ temporary file.
 ### `contentTracing.getTraceBufferUsage(callback)`
 
 * `callback` Function
+  * Object
     * `value` Number
     * `percentage` Number
 
 Get the maximum usage across processes of trace buffer as a percentage of the
 full state. When the TraceBufferUsage value is determined the `callback` is
 called.
+
+**[Deprecated Soon](promisification.md)**
+
+### `contentTracing.getTraceBufferUsage()`
+
+Returns `Promise<Object>` - Resolves with an object containing the `value` and `percentage` of trace buffer maximum usage
+
+Get the maximum usage across processes of trace buffer as a percentage of the
+full state.

docs/api/promisification.md

@@ -9,7 +9,6 @@ When a majority of affected functions are migrated, this flag will be enabled by
 ### Candidate Functions
 
 - [app.importCertificate(options, callback)](https://github.com/electron/electron/blob/master/docs/api/app.md#importCertificate)
-- [contentTracing.getTraceBufferUsage(callback)](https://github.com/electron/electron/blob/master/docs/api/content-tracing.md#getTraceBufferUsage)
 - [dialog.showOpenDialog([browserWindow, ]options[, callback])](https://github.com/electron/electron/blob/master/docs/api/dialog.md#showOpenDialog)
 - [dialog.showSaveDialog([browserWindow, ]options[, callback])](https://github.com/electron/electron/blob/master/docs/api/dialog.md#showSaveDialog)
 - [dialog.showMessageBox([browserWindow, ]options[, callback])](https://github.com/electron/electron/blob/master/docs/api/dialog.md#showMessageBox)
@@ -40,6 +39,7 @@ When a majority of affected functions are migrated, this flag will be enabled by
 - [contentTracing.getCategories(callback)](https://github.com/electron/electron/blob/master/docs/api/content-tracing.md#getCategories)
 - [contentTracing.startRecording(options, callback)](https://github.com/electron/electron/blob/master/docs/api/content-tracing.md#startRecording)
 - [contentTracing.stopRecording(resultFilePath, callback)](https://github.com/electron/electron/blob/master/docs/api/content-tracing.md#stopRecording)
+- [contentTracing.getTraceBufferUsage(callback)](https://github.com/electron/electron/blob/master/docs/api/content-tracing.md#getTraceBufferUsage)
 - [cookies.flushStore(callback)](https://github.com/electron/electron/blob/master/docs/api/cookies.md#flushStore)
 - [cookies.get(filter, callback)](https://github.com/electron/electron/blob/master/docs/api/cookies.md#get)
 - [cookies.remove(url, name, callback)](https://github.com/electron/electron/blob/master/docs/api/cookies.md#remove)

lib/browser/api/content-tracing.js

@@ -5,5 +5,6 @@ const contentTracing = process.atomBinding('content_tracing')
 contentTracing.getCategories = deprecate.promisify(contentTracing.getCategories)
 contentTracing.startRecording = deprecate.promisify(contentTracing.startRecording)
 contentTracing.stopRecording = deprecate.promisify(contentTracing.stopRecording)
+contentTracing.getTraceBufferUsage = deprecate.promisifyMultiArg(contentTracing.getTraceBufferUsage)
 
 module.exports = contentTracing

lib/common/api/deprecate.js

@@ -104,6 +104,32 @@ const deprecate = {
     }
   },
 
+  promisifyMultiArg: (fn) => {
+    const fnName = fn.name || 'function'
+    const oldName = `${fnName} with callbacks`
+    const newName = `${fnName} with Promises`
+    const warn = warnOnce(oldName, newName)
+
+    return function (...params) {
+      let cb
+      if (params.length > 0 && typeof params[params.length - 1] === 'function') {
+        cb = params.pop()
+      }
+      const promise = fn.apply(this, params)
+      if (!cb) return promise
+      if (process.enablePromiseAPIs) warn()
+      return promise
+        .then(res => {
+          process.nextTick(() => {
+            // eslint-disable-next-line standard/no-callback-literal
+            cb.length > 2 ? cb(null, ...res) : cb(...res)
+          })
+        }, err => {
+          process.nextTick(() => cb(err))
+        })
+    }
+  },
+
   renameProperty: (o, oldName, newName) => {
     const warn = warnOnce(oldName, newName)