refactor: prefer using app.whenReady() (#21972)

* docs: add references to app.whenReady() in isReady

* refactor: prefer app.whenReady()

In the docs, specs, and lib, replace instances of `app.once('ready')`
(seen occasionally) and `app.on('ready')` (extremely common) with
`app.whenReady()`.

It's better to encourage users to use whenReady():
1. it handles the edge case of registering for 'ready' after it's fired
2. it avoids the minor wart of leaving an active listener alive for
an event that wll never fire again

spec/fixtures/api/command-line/main.js

@@ -1,6 +1,6 @@
 const { app } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const payload = {
     hasSwitch: app.commandLine.hasSwitch('foobar'),
     getSwitchValue: app.commandLine.getSwitchValue('foobar')

spec/fixtures/api/cookie-app/main.js

@@ -1,6 +1,6 @@
 const { app, session } = require('electron')
 
-app.on('ready', async function () {
+app.whenReady().then(async function () {
   const url = 'http://foo.bar'
   const persistentSession = session.fromPartition('persist:ence-test')
   const name = 'test'

spec/fixtures/api/default-menu/main.js

@@ -18,7 +18,7 @@ try {
     Menu.setApplicationMenu(null)
   }
 
-  app.on('ready', () => {
+  app.whenReady().then(() => {
     setImmediate(() => {
       try {
         output(Menu.getApplicationMenu() === expectedMenu)

spec/fixtures/api/exit-closes-all-windows-app/main.js

@@ -8,7 +8,7 @@ function createWindow (id) {
   windows.push(window)
 }
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   for (let i = 1; i <= 5; i++) {
     createWindow(i)
   }

spec/fixtures/api/gpu-info.js

@@ -2,7 +2,7 @@ const { app } = require('electron')
 
 app.commandLine.appendSwitch('--disable-software-rasterizer')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const infoType = process.argv.pop()
   app.getGPUInfo(infoType).then(
     (gpuInfo) => {

spec/fixtures/api/leak-exit-webcontents.js

@@ -1,5 +1,5 @@
 const { app, webContents } = require('electron')
-app.on('ready', function () {
+app.whenReady().then(function () {
   webContents.create({})
 
   app.quit()

spec/fixtures/api/locale-check/main.js

@@ -1,6 +1,6 @@
 const { app } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   process.stdout.write(app.getLocale())
   process.stdout.end()
 

spec/fixtures/api/mixed-sandbox-app/main.js

@@ -12,7 +12,7 @@ if (process.argv.includes('--app-enable-sandbox')) {
 
 let currentWindowSandboxed = false
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   function testWindow (isSandboxed, callback) {
     currentWindowSandboxed = isSandboxed
     const currentWindow = new BrowserWindow({

spec/fixtures/api/quit-app/main.js

@@ -1,6 +1,6 @@
 const { app } = require('electron')
 
-app.on('ready', function () {
+app.whenReady().then(function () {
   // This setImmediate call gets the spec passing on Linux
   setImmediate(function () {
     app.exit(123)

spec/fixtures/api/relaunch/main.js

@@ -7,7 +7,7 @@ process.on('uncaughtException', () => {
   app.exit(1)
 })
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   const lastArg = process.argv[process.argv.length - 1]
   const client = net.connect(socketPath)
   client.once('connect', () => {

spec/fixtures/api/singleton/main.js

@@ -1,6 +1,6 @@
 const { app } = require('electron')
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   console.log('started') // ping parent
 })
 

spec/fixtures/api/window-all-closed/main.js

@@ -14,7 +14,7 @@ app.on('quit', () => {
   process.stdout.end()
 })
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const win = new BrowserWindow()
   win.close()
 })

spec/fixtures/no-proprietary-codecs.js

@@ -12,7 +12,7 @@ const FIVE_MINUTES = 5 * 60 * 1000
 
 let window
 
-app.once('ready', () => {
+app.whenReady().then(() => {
   window = new BrowserWindow({
     show: false,
     webPreferences: {

spec/fixtures/snapshot-items-available/main.js

@@ -2,7 +2,7 @@
 
 const { app } = require('electron')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   let returnCode = 0
   try {
     const testValue = f() // eslint-disable-line no-undef

spec/static/main.js

@@ -94,7 +94,7 @@ app.on('renderer-process-crashed', (event, contents, killed) => {
   console.log(`webContents ${contents.id} crashed: ${contents.getURL()} (killed=${killed})`)
 })
 
-app.on('ready', async function () {
+app.whenReady().then(async function () {
   await session.defaultSession.clearCache()
   await session.defaultSession.clearStorageData()
   // Test if using protocol module would crash.

spec/ts-smoke/electron/main.ts

@@ -54,7 +54,7 @@ if (!gotLock) {
 
 // This method will be called when Electron has done everything
 // initialization and ready for creating browser windows.
-app.on('ready', () => {
+app.whenReady().then(() => {
   // Create the browser window.
   mainWindow = new BrowserWindow({ width: 800, height: 600 })
 
@@ -147,7 +147,7 @@ app.on('ready', () => {
 
 app.commandLine.appendSwitch('enable-web-bluetooth')
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   mainWindow.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
     event.preventDefault()
 
@@ -322,7 +322,7 @@ app.setAboutPanelOptions({
 
 let onlineStatusWindow: Electron.BrowserWindow
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   onlineStatusWindow = new BrowserWindow({ width: 0, height: 0, show: false, vibrancy: 'sidebar' })
   onlineStatusWindow.loadURL(`file://${__dirname}/online-status.html`)
 })
@@ -335,7 +335,7 @@ ipcMain.on('online-status-changed', (event: any, status: any) => {
 // Synopsis
 // https://github.com/atom/electron/blob/master/docs/api/synopsis.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   window = new BrowserWindow({
     width: 800,
     height: 600,
@@ -737,7 +737,7 @@ const template = <Electron.MenuItemConstructorOptions[]> [
 
 menu = Menu.buildFromTemplate(template)
 
-Menu.setApplicationMenu(menu) // Must be called within app.on('ready', function(){ ... });
+Menu.setApplicationMenu(menu) // Must be called within app.whenReady().then(function(){ ... });
 
 Menu.buildFromTemplate([
   { label: '4', id: '4' },
@@ -807,7 +807,7 @@ Menu.buildFromTemplate([
 // net
 // https://github.com/electron/electron/blob/master/docs/api/net.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const request = net.request('https://github.com')
   request.setHeader('Some-Custom-Header-Name', 'Some-Custom-Header-Value')
   const header = request.getHeader('Some-Custom-Header-Name')
@@ -852,7 +852,7 @@ app.on('ready', () => {
 // power-monitor
 // https://github.com/atom/electron/blob/master/docs/api/power-monitor.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   powerMonitor.on('suspend', () => {
     console.log('The system is going to sleep')
   })
@@ -878,7 +878,7 @@ powerSaveBlocker.stop(id)
 // protocol
 // https://github.com/atom/electron/blob/master/docs/api/protocol.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   protocol.registerSchemesAsPrivileged([{ scheme: 'https', privileges: { standard: true, allowServiceWorkers: true } }])
 
   protocol.registerFileProtocol('atom', (request, callback) => {
@@ -910,7 +910,7 @@ app.on('ready', () => {
 // https://github.com/atom/electron/blob/master/docs/api/tray.md
 
 let appIcon: Electron.Tray = null
-app.on('ready', () => {
+app.whenReady().then(() => {
   appIcon = new Tray('/path/to/my/icon')
   const contextMenu = Menu.buildFromTemplate([
     { label: 'Item1', type: 'radio' },
@@ -1016,12 +1016,12 @@ process.setFdLimit(8192)
 // screen
 // https://github.com/atom/electron/blob/master/docs/api/screen.md
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const size = screen.getPrimaryDisplay().workAreaSize
   mainWindow = new BrowserWindow({ width: size.width, height: size.height })
 })
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const displays = screen.getAllDisplays()
   let externalDisplay: any = null
   for (const i in displays) {
@@ -1190,7 +1190,7 @@ session.defaultSession.webRequest.onBeforeSendHeaders(filter, function (details:
   callback({ cancel: false, requestHeaders: details.requestHeaders })
 })
 
-app.on('ready', function () {
+app.whenReady().then(function () {
   const protocol = session.defaultSession.protocol
   protocol.registerFileProtocol('atom', function (request, callback) {
     const url = request.url.substr(7)

spec/ts-smoke/electron/renderer.ts

@@ -191,12 +191,12 @@ const app = remote.app
 
 let mainWindow: Electron.BrowserWindow = null
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const size = screen.getPrimaryDisplay().workAreaSize
   mainWindow = new BrowserWindow({ width: size.width, height: size.height })
 })
 
-app.on('ready', () => {
+app.whenReady().then(() => {
   const displays = screen.getAllDisplays()
   let externalDisplay: any = null
   for (const i in displays) {